feat: keep the generated stub path out of the public API surface (#12) (#14)

* feat: keep the generated stub path out of the public API surface

The per-language SDK repo is the distribution mechanism, so the generated
tree has to stay an implementation detail. It was not one: add_github_source,
list_sources, the three mint-side methods, attach and revision_request all
named saas_sdk._gen types, and datasource/work_context re-exported the whole
generated module as `pb` in __all__.

Each facade now re-exports the types it takes and returns — the generated
classes themselves, so isinstance and existing imports keep working — and
tests/test_api_boundary.py fails when a consumer-reachable signature names
the generated package again.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* fix: close three gaps found reviewing the boundary gate

The README's mint example still built scopes through work_context.pb, which
is the exact import the change removes from the API surface — and the one a
consumer is most likely to copy, since it is the documented happy path for
minting. A signature gate cannot see it, so the examples are now checked too.

Two holes in the gate itself: a quoted annotation ("list[pb.Datasource]")
parsed as an opaque string constant and passed silently, and an empty facade
glob would have parametrized every check into nothing and reported green.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

* fix: close the star-import leak and three gaps in the boundary gate

authorization_revision declared no __all__, so `from
saas_sdk.authorization_revision import *` handed a consumer `pb` — the
generated module itself, and with it everything the gate was written to
fence off. The __all__ check could not see this: it only inspected modules
that already declared one, so it passed on the single module that leaked.
No __all__ is now a failure rather than a skip, and a runtime star-import
test asserts what Python actually exports, since that is the thing the
static read was wrong about.

Three further gaps, each demonstrated by restoring the defect it hides:

- _consumer_reachable walked only the top level and one level into a class,
  so a public definition inside a try:/if block was invisible. This module
  already defines its optional transports behind `try: import`, so the blind
  spot sat directly on a pattern the package uses. It now recurses.
- identity was the only proof that a re-export aliases the proto, which
  proves nothing for the three replay-policy enum values: they are small
  ints, so `= 0` satisfies `is` through CPython's integer cache while
  decoupling the constant from the proto and keeping a stale value across a
  renumbering. The binding is now checked structurally.
- a non-literal __all__ raised AttributeError instead of failing with a
  reason.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Antoine Toussaint <312536060+antoinetoussaint-byte@users.noreply.github.com>
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: antoinetoussaint-byte

README.md

@@ -11,7 +11,9 @@ import namespace.
 
 Packages:
 
-- **`saas_sdk._gen`** — the generated protobuf message bindings (`*_pb2`), from
+- **`saas_sdk._gen`** — private; consumers reach these types through the facades
+  that re-export them (see [Consuming](#consuming)). The generated protobuf
+  message bindings (`*_pb2`), from
   the accounts public proto at the ref recorded in `SOURCE.txt`. Only message
   types are generated; the runtime owns the Connect transport, so there are no
   client/server stubs. The bindings embed **only** the accounts protos this SDK
@@ -76,7 +78,7 @@ wc = work_context.new(gateway)
 parent = wc.start_task(
     bearer=user_bearer, org_id=org, task_id=task, session_id=session,
     audience="accounts",
-    scopes=[work_context.pb.WorkContextScope(resource_kind="evidence", actions=["read"])],
+    scopes=[work_context.WorkContextScope(resource_kind="evidence", actions=["read"])],
 )
 ctx = wc.exchange_audience(bearer=user_bearer, parent=parent, audience="evidence", scopes=scopes)
 work_context.attach(headers, ctx)   # per outgoing request
@@ -195,7 +197,23 @@ and shared-proto dependencies (`scripts/strip_options.py`), and regenerates
 
 ## Consuming
 
+Import `saas_sdk`, never `saas_sdk._gen`. Each facade re-exports the message
+types it takes and returns, so the generated tree stays an implementation
+detail:
+
 ```python
-from saas_sdk import datasource                 # the facade
-from saas_sdk._gen import datasource_pb2         # the message types
+from saas_sdk import datasource
+from saas_sdk.datasource import Datasource       # the message type, re-exported
+
+sources: list[Datasource] = datasource.new(gateway).list_sources(org)
 ```
+
+Likewise `work_context` re-exports `IssuedWorkContext`, `WorkContextScope`,
+`WorkContextReplayPolicy` and its enum values, and `authorization_revision`
+re-exports `CheckAuthorizationRevisionRequest`. These are the generated classes
+themselves, not wrappers, so `isinstance` and existing imports keep working.
+
+Naming `saas_sdk._gen` in consumer code pins this SDK's internal layout into
+yours: regenerating against a newer contract, or swapping the committed tree for
+a served dependency, would become a breaking change for you rather than a change
+here. `tests/test_api_boundary.py` fails if a public signature reintroduces it.

src/saas_sdk/authorization_revision.py

@@ -24,6 +24,23 @@
 from ._gen import work_contexts_pb2 as pb
 from .work_context import WorkContext
 
+# Re-exported so a consumer names the request revision_request builds without
+# importing saas_sdk._gen. Same object, so isinstance keeps working.
+CheckAuthorizationRevisionRequest = pb.CheckAuthorizationRevisionRequest
+
+# Without this, a star-import re-exports every public module-level name — which
+# includes ``pb``, the generated bindings themselves.
+__all__ = [
+    "REVISION_PATH",
+    "TIMEOUT",
+    "RevisionDenied",
+    "RevisionUnavailable",
+    "CheckAuthorizationRevisionRequest",
+    "revision_request",
+    "ConnectClient",
+    "GRPCClient",
+]
+
 try:
     import grpc
 except ImportError:
@@ -94,7 +111,7 @@ def _https_origin(value: str) -> str:
     return value.rstrip("/")
 
 
-def revision_request(claims: WorkContext) -> pb.CheckAuthorizationRevisionRequest:
+def revision_request(claims: WorkContext) -> CheckAuthorizationRevisionRequest:
     """Copy owner and every actor scope; the caller owns verification and policy."""
     if (
         not isinstance(claims, WorkContext)

src/saas_sdk/datasource.py

@@ -31,7 +31,11 @@
 
 from saas_sdk._gen import datasource_pb2 as pb
 
-__all__ = ["Client", "Gateway", "new", "pb"]
+# Re-exported so a consumer names the types this facade returns without importing
+# saas_sdk._gen. Same objects, so isinstance and existing imports keep working.
+Datasource = pb.Datasource
+
+__all__ = ["Client", "Datasource", "Gateway", "new"]
 
 _M = TypeVar("_M")
 
@@ -66,7 +70,7 @@ def add_github_source(
         paths: Sequence[str] = (),
         branch: str = "",
         webhook_secret: str = "",
-    ) -> pb.Datasource:
+    ) -> Datasource:
         """Register a GitHub repository as a datasource and return the non-secret
         projection the server stored.
 
@@ -95,7 +99,7 @@ def add_github_source(
         )
         return response.datasource
 
-    def list_sources(self, org_id: str) -> list[pb.Datasource]:
+    def list_sources(self, org_id: str) -> list[Datasource]:
         """Return the org's connected datasources."""
         response = self._gateway.unary(
             _SERVICE + "ListSources", pb.ListSourcesRequest(org_id=org_id), pb.ListSourcesResponse

src/saas_sdk/work_context.py

@@ -51,6 +51,16 @@
 
 from saas_sdk._gen import work_contexts_pb2 as pb
 
+# Re-exported so a consumer names the types the mint side takes and returns
+# without importing saas_sdk._gen. Same objects, so isinstance and existing
+# imports keep working.
+IssuedWorkContext = pb.IssuedWorkContext
+WorkContextScope = pb.WorkContextScope
+WorkContextReplayPolicy = pb.WorkContextReplayPolicy
+WORK_CONTEXT_REPLAY_POLICY_UNSPECIFIED = pb.WORK_CONTEXT_REPLAY_POLICY_UNSPECIFIED
+WORK_CONTEXT_REPLAY_POLICY_IDEMPOTENT = pb.WORK_CONTEXT_REPLAY_POLICY_IDEMPOTENT
+WORK_CONTEXT_REPLAY_POLICY_SINGLE_USE = pb.WORK_CONTEXT_REPLAY_POLICY_SINGLE_USE
+
 __all__ = [
     "WORK_CONTEXT_HEADER",
     "HEADER_NAME",
@@ -64,6 +74,12 @@
     "WorkContextDenied",
     "WorkContextUnavailable",
     "WorkContextMintError",
+    "IssuedWorkContext",
+    "WorkContextScope",
+    "WorkContextReplayPolicy",
+    "WORK_CONTEXT_REPLAY_POLICY_UNSPECIFIED",
+    "WORK_CONTEXT_REPLAY_POLICY_IDEMPOTENT",
+    "WORK_CONTEXT_REPLAY_POLICY_SINGLE_USE",
     "WorkScope",
     "WorkActor",
     "WorkContext",
@@ -77,7 +93,6 @@
     "token_from_headers",
     "attach",
     "new",
-    "pb",
 ]
 
 WORK_CONTEXT_HEADER = "x-codefly-work-context"
@@ -929,13 +944,13 @@ def start_task(
         task_id: str,
         session_id: str,
         audience: str,
-        scopes: Sequence[pb.WorkContextScope],
+        scopes: Sequence[WorkContextScope],
         actor_principal_id: str = "",
         ttl: timedelta | None = None,
-        replay_policy: pb.WorkContextReplayPolicy = pb.WORK_CONTEXT_REPLAY_POLICY_UNSPECIFIED,
+        replay_policy: WorkContextReplayPolicy = WORK_CONTEXT_REPLAY_POLICY_UNSPECIFIED,
         workspace_id: str = "",
         project_id: str = "",
-    ) -> pb.IssuedWorkContext:
+    ) -> IssuedWorkContext:
         """Mint the root capability for a task and return the issued context.
 
         ``actor_principal_id`` empty means a direct human-owned task; otherwise
@@ -962,12 +977,12 @@ def exchange_audience(
         self,
         *,
         bearer: str,
-        parent: pb.IssuedWorkContext,
+        parent: IssuedWorkContext,
         audience: str,
-        scopes: Sequence[pb.WorkContextScope],
+        scopes: Sequence[WorkContextScope],
         ttl: timedelta | None = None,
-        replay_policy: pb.WorkContextReplayPolicy = pb.WORK_CONTEXT_REPLAY_POLICY_UNSPECIFIED,
-    ) -> pb.IssuedWorkContext:
+        replay_policy: WorkContextReplayPolicy = WORK_CONTEXT_REPLAY_POLICY_UNSPECIFIED,
+    ) -> IssuedWorkContext:
         """Reissue ``parent`` for one callee ``audience``, attenuating authority
         to ``scopes`` — the same task, session, and owner, never widened. Call
         once per distinct callee audience at turn start.
@@ -986,12 +1001,12 @@ def renew(
         self,
         *,
         bearer: str,
-        ctx: pb.IssuedWorkContext,
+        ctx: IssuedWorkContext,
         audience: str | None = None,
-        scopes: Sequence[pb.WorkContextScope] = (),
+        scopes: Sequence[WorkContextScope] = (),
         ttl: timedelta | None = None,
-        replay_policy: pb.WorkContextReplayPolicy = pb.WORK_CONTEXT_REPLAY_POLICY_UNSPECIFIED,
-    ) -> pb.IssuedWorkContext:
+        replay_policy: WorkContextReplayPolicy = WORK_CONTEXT_REPLAY_POLICY_UNSPECIFIED,
+    ) -> IssuedWorkContext:
         """Extend ``ctx`` with a fresh TTL for work running past the cap, using
         the current actor's ``bearer`` rather than the owner's.
 
@@ -1050,7 +1065,7 @@ def _validated_token(token: str) -> str:
     return token
 
 
-def attach(request_or_headers: _Headers, ctx: pb.IssuedWorkContext) -> _Headers:
+def attach(request_or_headers: _Headers, ctx: IssuedWorkContext) -> _Headers:
     """Stamp ``ctx``'s token on an outgoing call and return the target.
 
     ``request_or_headers`` is either a mutable header mapping or a request object