ts-procedures 8.4.0 → 8.6.0

package/docs/superpowers/specs/2026-06-08-dx-feedback-round-2-design.md

@@ -0,0 +1,376 @@
+# DX Feedback Round 2 — Design
+
+**Date:** 2026-06-08
+**Status:** Triage approved. **Workstream A ✅ shipped** (2026-06-08, commits `0d53329`,
+`ec9ea04`, `ced4b86`, `8ad5e9f` on `master`; 1077 tests green). **Round closed 2026-06-08:**
+B → docs (already authorable), C documented as a boundary (no API), D high-value docs shipped
+(#6 recipe, #10/#8 prose; #7/#12/CORS deferred), E ✗ dropped, #13/#11 decline reply sent. Net:
+Workstream A was the only *code* — everything else was already-shipped capability to document or
+out of our lane. See roadmap for the per-item landing.
+**Source:** Downstream-developer feedback from building the demo server (`src/server`)
+and wiring its generated client into the client layer. Findings #6–#15 + three
+cross-cutting notes. (Findings #1–#5 were resolved in 8.4.0 / 8.5.0 — see
+`2026-06-05-dx-feedback-round-design.md`.)
+
+This round is deliberately **not** a single spec. The findings sort by *boundary*,
+not by the severity label the downstream assigned, and the boundary determines how
+each is treated:
+
+1. **"The capability exists; it's just invisible in the generated output."** Pure
+   codegen *surfacing*. Unambiguously ours, low-risk, high-value. → **Workstream A**.
+2. **"The typed error survives our throw but is flattened downstream."** Cross-cutting
+   error-handling design; the actual blocker lives in mvc-kit, not here. → **Workstream
+   C** (a design brainstorm, not a code sprint).
+3. **"Our codegen faithfully reflects a schema the downstream authored
+   inconsistently."** Mislabeled as a codegen gap; fixing it would mean codegen
+   *overriding* the author's contract. → **Declined** (documented, no code).
+
+The guiding principle for this round: ts-procedures owns the *transport, schema, and
+codegen surface*. It does **not** own the consumer's state-management ergonomics
+(mvc-kit) or the consumer's schema-authoring choices. We surface and document what we
+own; we decline to absorb the rest, with written rationale so downstream isn't left
+guessing.
+
+---
+
+## Disposition at a glance
+
+| # | Severity (theirs) | Disposition | Workstream |
+|---|---|---|---|
+| #8  | HIGH   | **Do** — surface the per-call options bag (`signal`/`timeout`) in the generated per-route artifact | A |
+| #9  | MEDIUM | **Do** — emit `void` for input-less routes instead of `unknown` | A |
+| #10 | MEDIUM | **Do (shallow half)** — surface declared `Errors` + `isApiError` guard on the throwing path | A |
+| #15 | LOW    | **Do** — emit a per-scope client interface (`MessagesClient`, …) | A |
+| #6  | LOW    | **Document** — already authorable today (omit `res.body` → `Promise<void>`, no model, 204); fold into D | D |
+| #14 | HIGH   | **Brainstorm** — error-mapping seam; hold the line that flattening is mvc-kit's gap | C |
+| #10 (deep half) | MEDIUM | **Brainstorm** — why `.safe()` is avoided ties into C | C |
+| #7  | LOW    | **Document** — `Type.Record` can't be `$id`-shared | D |
+| #12 | LOW    | **Document** — form Model owns a value type + `toBody()`; partly inherent | D |
+| basePath/CORS | MEDIUM | **Document** (+ optional dev-time warning) | D |
+| correlation-id | MEDIUM | **Dropped** — `onRequestStart` + function-form `factoryContext` + client headers already cover it; no new API earns its surface | — |
+| #13 | MEDIUM | **Decline code** (document convention) — downstream schema inconsistency | — |
+| #11 | LOW    | **Decline code** (document the `as Partial` bridge) — relationship not in JSON Schema | — |
+
+---
+
+## Workstream A — Codegen DX surfacing (ready to plan)
+
+Four findings, one cohesive batch: every one is "the capability already exists (or is
+a one-line detection); make it visible/ergonomic in the generated output." All touch
+`emit-scope.ts` / `emit-types.ts` / `emit-index.ts` and the client `types.ts`. Lowest
+risk, highest signal. **This is the one workstream ready for a TDD plan now.**
+
+### A.1 — #9: input-less routes are typed `unknown`, forcing a noise `({})` arg
+
+**Problem.** Routes with no pathParams/query/body bind their first param as `unknown`
+(`emit-scope.ts:536,679` — `paramsTypeName` defaults to `'unknown'`). Because the type
+is `unknown` (not `void`/optional), consumers must pass a placeholder `({})` —
+`api.auth.Me({})`, `api.users.ListUsers({})` — and worse, `unknown` accepts garbage
+(`api.auth.Me({ nonsense: 1 })` type-checks). Six call sites across five files; the
+single most-repeated papercut.
+
+**Decision.** When a route has **zero present input channels**, emit `void` as the
+param type — `bindCallable<void, T>` / `bindCallableTyped<void, T, E>` — so the callable
+is `(params: void, options?) => Promise<T>`. Detection point is trivial: after
+`presentChannels` is built (`emit-scope.ts:514-520` API, `664-670` http-stream; the RPC
+`refs['Params'] ?? 'unknown'` path at `398-399,408-409`), branch on
+`presentChannels.length === 0`. **No runtime change** — only the emitted `TParams` type
+arg changes.
+
+> **Verified (2026-06-08, `tsc --strict`).** A required parameter of type `void` *can*
+> be omitted at the call site: `Me()` compiles, `Me({})` / `Me({ nonsense: 1 })` are type
+> errors. So the existing `(params, options?)` shape needs no restructuring — `void` for
+> `TParams` is sufficient. The one wart: passing options on a no-input route reads
+> `Me(undefined, { signal })`. That awkwardness is rare (no-input + explicit signal) and
+> is the price of a **uniform** call shape across all routes; the plan should call it out
+> but I recommend keeping the uniform shape rather than special-casing no-input routes to
+> `(options?) =>` (which would need runtime rewiring and break shape uniformity).
+
+**Alternatives considered.** *Optional `params?: SomeEmptyObject`.* Rejected: still
+accepts a stray object. *Drop params entirely → `(options?) => T` for no-input routes.*
+Rejected: nicer `Me({ signal })` ergonomics but breaks call-shape uniformity and needs
+runtime rewiring of the binder. *Leave as-is, document `({})`.* Rejected: highest-frequency
+papercut, and the type fix is a single branch per route kind.
+
+### A.2 — #8: the per-call `AbortSignal`/`timeout` seam is invisible in the generated artifact
+
+**Problem.** Every bound callable is `(params, options?: ProcedureCallOptions) =>
+Promise<T>` and `ProcedureCallOptions` carries `signal`/`timeout`/`headers`/`basePath`/
+`meta` (`client/types.ts:218-230`). But the generated per-route namespace surfaces only
+the first param (`.Req`); the JSDoc emitted at `emit-scope.ts:412-419,640-644,822-833`
+never mentions the second `options` argument. The result is a real downstream
+mis-modeling: resources state as fact "there's no per-call AbortSignal seam" and **every
+resource omits cancellation**, violating their own P7. The seam was reachable all along
+— just not through the surface they treat as the contract.
+
+**Decision.** Surface the options bag in the generated per-route artifact — **JSDoc is
+the primary, highest-value half**:
+1. Add a JSDoc line to every bound callable mentioning `options?.signal` / `options?.timeout`
+   (and that the second arg is `ProcedureCallOptions`), so it shows on hover *at the call
+   site* — which is where the consumer reads the contract.
+2. *(Open — likely drop.)* A per-route `export type Options = ProcedureCallOptions` alias
+   next to `.Req`. On reflection this is probably **over-production**: the alias is
+   byte-identical on every route, so it adds generated noise (`SendMessage.Options` is just
+   `ProcedureCallOptions`) without naming anything route-specific. The plan should default to
+   JSDoc-only and emit the alias only if a concrete discoverability gap remains after the
+   JSDoc lands. Readable generated output > a redundant alias on every route.
+
+**Alternatives considered.** *Docs only (external).* Rejected: the whole finding is that the
+capability is undiscoverable *from the generated namespace* — the place a consumer treats as
+the contract. The JSDoc has to land in the generated code. *Per-route alias as the headline
+fix.* Demoted (see above) — repetition isn't discoverability.
+
+### A.3 — #10 (shallow half): declared typed errors are invisible on the throwing path
+
+**Problem.** A route that declares `errors` already gets `export type Errors = <union>`
+emitted (`emit-scope.ts:363-384`), but the `ETyped` union is wired **only** to `.safe()`
+(`client/types.ts:293-298`); the throwing callable resolves to plain `Promise<TResponse>`.
+Since the data layer uses the throwing form (per its P2/P5), TypeScript gives no signal
+about which typed errors a call can throw — the declared `Conflict` on `CreateUser`/
+`UpdateUser` is never handled. The route-level taxonomy codegen computes is dead weight
+on the common path.
+
+**Decision (shallow half only).** *Grounding correction (2026-06-08):* the per-route
+`Errors` type is **already emitted and reachable** — `Users.GetUser.Errors` (namespace) /
+`GetUserErrors` (flat), confirmed in `emit-scope.test.ts:740,750`. And because the generated
+error classes are **real exported classes**, `if (e instanceof Api.Errors.Conflict)` already
+works on the throwing path. So #10 is **not** a missing-type problem — it's pure
+*discoverability*. That moves the bulk of #10 into the docs pass (Workstream D); the only
+code in Workstream A is a one-line JSDoc breadcrumb:
+1. The per-route callable's JSDoc names its declared errors and points at `Scope.Route.Errors`
+   + "narrow with `instanceof` on the throwing path, or use `.safe()` for a `Result`."
+2. *(Optional, deferred.)* A generic `isProcedureError(e, Cls)` guard in the client runtime
+   (sugar over `instanceof`; classes are tagged `__tsProceduresTyped` at `client/call.ts:170`).
+   Held back unless docs + the breadcrumb prove insufficient — `instanceof` already works, so
+   a guard is ergonomics, not capability. Don't over-produce.
+
+**The deep half is Workstream C.** *Why* the data layer avoids `.safe()` at all (it
+defeats mvc-kit's async tracking) is the cross-cutting error-handling question — not
+solvable by a codegen tweak. Do **not** conflate the two.
+
+**Alternatives considered.** *Attach `ETyped` to the throwing signature too.* Rejected:
+TS can't express "throws X" — the union would have to ride a phantom return position and
+would mislead. A guard + reachable `Errors` type is the honest surface.
+
+### A.4 — #15: no per-scope client interface, forcing `as unknown as typeof api` casts
+
+**Problem.** The aggregate client is the only exported shape, so a Resource that uses one
+scope must type its dependency as the whole `typeof api`
+(`users.resource.ts:26`), and every test fake force-casts a two-method partial
+`as unknown as typeof api` (`thread-messages.resource.test.ts:16`,
+`threads.resource.test.ts:30`). The double-cast is the tell that the injected port is far
+wider than the dependency used — defeating the type safety the generated client exists to
+provide, exactly at the DI seam.
+
+**Decision.** Emit a per-scope client interface alongside the aggregate — the bound
+callables for that scope as a named type — produced where `emit-index.ts` already
+assembles the scope namespaces. A Resource then types its dependency as the narrow port
+(`constructor(client: MessagesClient = api.messages)`) and a fake implements just that
+interface with no cast.
+
+> **Derive from the existing factory return type (verified 2026-06-08).** `emit-index.ts`
+> already emits `create${Service}Bindings(client)` returning `{ users: …, posts: … }` and
+> already uses `ReturnType<typeof ${factoryName}>` (lines 128,145). So the per-scope client
+> type is just an indexed access into that — **zero duplication, reuses the pattern already in
+> the file**:
+> ```ts
+> export type ${Service}Client = ReturnType<typeof create${Service}Bindings>
+> export type UsersClient = ${Service}Client['users']   // one per scope
+> ```
+> This does **not** collide with the `Api.Users` *type* namespace (Params/Response/…) — that
+> namespace is the route data types; `UsersClient` is the callable bundle. The `*Client` suffix
+> cleanly distinguishes the two. No parallel scheme, no hand-written interface — the types fall
+> out of the factory the file already emits. A Resource then writes
+> `constructor(client: UsersClient = api.users)` and a two-method fake satisfies `UsersClient`
+> with no cast.
+
+**Alternatives considered.** *Hand-written per-Resource port type (consumer side).*
+Works, but every consumer reinvents (and mis-scopes) it — codegen already knows the exact
+scope shape, so it should emit it.
+
+---
+
+## Workstream B — No-content response (#6) — → DOCS (folded into D, 2026-06-08)
+
+**Problem.** The downstream invented phantom bodies for naturally-empty responses:
+`Logout` carries a dead-weight `LogoutResponse` model (call site discards it), `LeaveThread`
+returns a `ThreadList` it didn't need. They believed an empty response couldn't be declared.
+
+**Vetted (2026-06-08) — no-content is ALREADY fully authorable today; #6 is a docs gap, not a
+build.** The capability exists end-to-end:
+- **Authoring type:** `schema.res` and `res.body` are both optional (`src/types.ts:100-102`).
+  An author can omit `res` (or `res.body`) entirely.
+- **Handler type:** `HttpReturn<TRes>` falls through to `void` when there's no body
+  (`src/create-http.ts:17-21`), so the handler types as `Promise<void>` and `return undefined`
+  type-checks (`create-http.test.ts:110-119`).
+- **Envelope:** omitting `res.body` emits an absent/empty `res` (`hono/docs/http-doc.ts:14-27`).
+- **Codegen:** empty `res` → `client.bindCallable<void, void>`, **no** response model
+  (`emit-scope.test.ts:1253-1256`).
+- **Runtime:** `undefined` return → clean 204 (`hono/handlers/http.ts:126`;
+  `http.test.ts:70-82`).
+
+So `CreateHttp('Logout', { /* no res */ }, async () => undefined)` already gives a
+`Promise<void>` client, no model, 204 at runtime — exactly what they wanted. They invented a
+body only because the "declare nothing" path **wasn't visible**. Same shape as Workstream E:
+capability exists; the gap is discoverability. **No new API (no `Type.Void()` marker, no
+status-only seam needed).** Fold a short recipe into the **D** docs pass: "for 204 / no-content,
+omit `schema.res.body` and return `undefined` — you get `Promise<void>` and no generated model."
+
+**Out of scope.** Consumer-side response *projection* (the `CreateThread` / `Pick`-one-field
+observation) — the procedure's call, not the call site's; the Resource caches the full
+projection anyway. Flagged in the feedback as "no action needed."
+
+---
+
+## Workstream C — Error-handling, cross-cutting (brainstorm, not a build)
+
+**Covers:** #14 (fire-and-forget command error dead-ends) + the "typed errors flattened
+by mvc-kit async tracking" cross-cutting note + the *deep* half of #10 (why `.safe()` is
+avoided).
+
+**Boundary stance (to defend in the brainstorm).** ts-procedures **already does its job
+correctly**: it throws `instanceof`-catchable typed classes. The error "dead-ends"
+because *mvc-kit's async tracker* collapses the typed instance into a closed 10-value
+`code` union and keeps the original only on a private field. That is mvc-kit's gap — the
+feedback itself says "either side alone closes the gap." We should not bolt on features to
+paper over a downstream flattening problem.
+
+**The one genuinely ts-procedures-side ask:** a client-level error **transform/map** seam.
+We already have a global `onError` hook, but it is an *observer* (`client/hooks.ts`,
+`client/types.ts:118-122`) — it cannot transform or swallow. The open question is whether
+a transform hook (or `errorMap` on `createClient`) earns its surface area, or whether
+mvc-kit surfacing `cause` on its `TaskState` is the cleaner fix that makes our side a
+no-op.
+
+**Why a brainstorm, not a plan.** This is a real API-design decision with overlap against
+existing hooks and the error taxonomy. It needs the requirements explored before any code.
+The brainstorm should produce either (a) a spec for a transform seam with a crisp boundary,
+or (b) a documented decision that the fix is mvc-kit's, with our side limited to documenting
+the existing typed-throw contract.
+
+---
+
+## Workstream D — Documentation pass (small session)
+
+- **#7 — `Type.Record` opaque to `$id` sharing.** Accurate and inherent: a bare record has
+  no `$id`, so its value type is always re-inlined. Not a blocker (it rides inside an
+  `$id`-bearing parent like `Thread`). **Document** the limitation in the shared-models
+  docs; do **not** teach `--share-models` to synthesize names for records (scope creep for
+  a non-blocker).
+- **basePath/CORS footgun.** A cross-origin absolute `basePath` issues a plain
+  cross-origin `fetch`; with no server CORS the first call fails with a generic `Failed to
+  fetch` and nothing on the client surface hints why. **Document** a one-line callout in the
+  codegen `basePath` docs (browser + different origin ⇒ server CORS *or* same-origin dev
+  proxy). *Optional small code add:* the fetch adapter detects a cross-origin `basePath` and
+  emits a clearer dev-time error than the browser's generic one. The HTTP↔WS auth-seam
+  asymmetry half is cross-logged with ts-channels; our half is the basePath/CORS doc.
+- **#12 — form shape not derivable.** The feedback admits this is "partly inherent (draft
+  state ≠ request body)." **Document** that form Models are expected to own a value type +
+  `toBody()` mapper (`LocationFormModel.toBody` as the recommended shape). No codegen change.
+
+---
+
+## Workstream E — Framework-level correlation / request id — ✗ DROPPED (2026-06-08)
+
+**Was:** promoted from the declined body-level `clientId` ask to a transport-level Hono-builder
+feature (a `requestId` config block: read-or-mint an id, echo it on the response header for all
+four kinds, expose `ctx.requestId`).
+
+**Why dropped (brainstorm outcome).** The existing primitives already deliver the *entire*
+feature with no new API — a dedicated block buys only ~6 saved lines and a named knob, which
+doesn't earn permanent public surface on a transport library. Concretely:
+- **Read + mint + echo (server):** `onRequestStart(c)` gets the Hono `Context` and can
+  `c.req.header(name) ?? crypto.randomUUID()`, `c.set(...)`, and `c.header(name, id)` — the
+  header set there persists onto every response, streams included.
+- **Expose on `ctx` (server):** `factoryContext` already accepts a **function form** receiving
+  `c` (`hono/types.ts:42-49`), so `factoryContext: (c) => ({ ...base, requestId: c.get('requestId') })`
+  gives handlers `ctx.requestId` with zero framework change.
+- **Outbound id (client):** function-valued `headers` (shipped 8.5.0) + `onBeforeRequest`
+  already attach/rotate a correlation header per request.
+
+The gap was **discoverability, not capability** — and the user's call (2026-06-08) was that even
+a docs recipe isn't warranted: the two-seam composition is a normal use of documented primitives.
+Same boundary as #13/#11 — the library does not grow surface to wrap what it already enables.
+
+**Decision: no feature, no recipe, no spec.** This consumes the original downstream
+correlation-id ask (transport-level) in full.
+
+---
+
+## Declined (no code change) — with rationale
+
+These are the "don't bend" set. We faithfully reflect the author's schema; we don't
+override it.
+
+- **#13 — Create/Update spell "empty" two ways (`undefined` vs `string | null`).** Root
+  cause is downstream schema inconsistency: `Type.Optional(Type.String())` on create vs
+  `Type.Optional(Type.Union([String, Null]))` on update (`user.schema.ts:40` vs `:53`;
+  `location.schema.ts:28` vs `:39`). Codegen reflects exactly what they wrote. The
+  suggested "codegen emits a per-body normalizer / widens the optional type" would have us
+  **override the author's contract** — the opposite of our job. **Decline the code change.**
+  Remedy is for the author to make the pair consistent (both `string | undefined` *or* both
+  `string | null`). We will document the convention so consumers stop rediscovering it
+  field-by-field.
+
+- **#11 — `UpdateXBody extends Partial<Entity>`.** `collect-models.ts:61-94` does zero
+  structural inference and *cannot*: the Partial/subset relationship isn't expressible in
+  the JSON Schema we receive (it's flattened to an independent `$id` model before codegen
+  sees it). We can't synthesize a relationship the wire format doesn't carry. **Decline the
+  codegen change.** We will document the intended `as Partial<Entity>` bridge so consumers
+  don't each reinvent (and mis-scope) it.
+
+---
+
+## Session roadmap (sequencing)
+
+1. ✅ **DONE — Workstream A** (`docs/superpowers/plans/2026-06-08-codegen-dx-surfacing.md`)
+   — #9, #8, #10-breadcrumb, #15 shipped 2026-06-08. **Process lesson (encode in future
+   plans):** changing `__fixtures__/users-envelope.json` is **cross-target** — it feeds every
+   target's e2e/integration tests, so a new route regenerates the Kotlin *and* Swift goldens
+   (`UPDATE_GOLDENS=1`), not just a 5→6 count bump. Pre-flight for any plan that inlines test
+   code should also grep the referenced test fixtures (the real `emit-index.test.ts` scopes are
+   `users`/`billing`/`adminUsers`, not the assumed `users`/`posts`), not only production-file
+   line anchors.
+2. ✗ **DROPPED — Workstream E** (correlation id). Brainstormed 2026-06-08; existing primitives
+   cover it, no new API or docs warranted. See the Workstream E section above.
+3. → **DOCS — Workstream B** (no-content #6). Vetted 2026-06-08; already authorable today,
+   folded into D as a recipe. See the Workstream B section above.
+4. ✅ **DONE — Workstream C** (error-handling). Documented as a boundary, **no new API**:
+   `docs/client-error-handling.md` §11 "Design note: typed errors and your state layer" — we throw
+   instanceof-catchable classes; a state layer that flattens them is the state layer's concern;
+   `onError` is an observer by design.
+5. ✅ **DONE (high-value) — Workstream D docs.** #6 no-content recipe →
+   `docs/http-integrations.md`; #10/#8 discoverability prose → `docs/client-error-handling.md`
+   §3a. **Deferred (optional follow-up):** #7 (`$id`/Record), #12 (form `toBody`), basePath/CORS
+   + cross-origin adapter warning — lower-value, pull in on request.
+6. ✅ **DONE — Decline reply** → `docs/handoffs/2026-06-08-dx-round2-declines.md` (#13/#11 with
+   the schema-authoring remedies, framed remedy-first).
+
+**Net for the round:** Workstream A (codegen DX) was the only *code*; everything else is either
+already-shipped capability that needs documenting (B, #6) or out of our lane (E dropped; #13/#11
+declined; C likely mvc-kit's). That's the boundary holding — the library surfaces and documents
+what it owns, and doesn't grow to wrap what it already enables.
+
+Each workstream produces working, testable software (or a documented decision) on its own —
+no cross-workstream barriers.
+
+## Testing strategy (per workstream, filled in at plan time)
+
+- **A:** fixture tests asserting (#9) input-less routes emit `void` and reject a stray
+  object; (#8) generated JSDoc + `Options` alias surface the options bag; (#10) `Errors`
+  type reachable at call site + `is${Service}Error` guard narrows; (#15) per-scope
+  interface satisfied by a two-method fake with no cast. Regression: routes *with* input
+  unchanged.
+- **B:** no code — the no-content path already has coverage (`create-http.test.ts:110-119`,
+  `http.test.ts:70-82`, `emit-scope.test.ts:1253-1256`); the docs recipe should compile against
+  those existing behaviors.
+- **C:** determined by the brainstorm outcome.
+- **D:** doc review only.
+
+## Out of scope (this round)
+
+- mvc-kit's half of the error-flattening fix (surface `cause` on `TaskState`) — their repo.
+- ts-channels WS correlation / `?token=` auth-seam asymmetry — cross-logged there.
+- Consumer-side response projection (`Pick`-one-field) — procedure's call, not ours.
+- A first-class body-level `clientId`/idempotency convention — superseded by Workstream E's
+  transport-level approach.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-procedures",
-  "version": "8.4.0",
+  "version": "8.6.0",
   "description": "A TypeScript RPC framework that creates type-safe, schema-validated procedure calls with a single function definition. Define your procedures once and get full type inference, runtime validation, and framework integration hooks.",
   "main": "build/exports.js",
   "types": "build/exports.d.ts",

package/src/codegen/__fixtures__/users-envelope.json

@@ -191,6 +191,15 @@
         }
       },
       "errors": []
+    },
+    {
+      "kind": "api",
+      "name": "Heartbeat",
+      "scope": "users",
+      "method": "GET",
+      "fullPath": "/users/heartbeat",
+      "jsonSchema": { "req": {}, "res": {} },
+      "errors": []
     }
   ],
   "errors": [

package/src/codegen/bin/cli.test.ts

@@ -555,3 +555,30 @@ describe('--share-models', () => {
     expect(parseArgs(['--out', 'g', '--url', 'u'], cfg as CodegenConfig).sharedTypesImport).toEqual(cfg.sharedTypesImport)
   })
 })
+
+describe('--shared-models-module and --strict-shared-models', () => {
+  it('parses --shared-models-module into sharedModelsModule', () => {
+    const parsed = parseArgs(['--out', 'gen', '--file', 'e.json', '--shared-models-module', '@app/schemas'])
+    expect(parsed.sharedModelsModule).toBe('@app/schemas')
+  })
+
+  it('parses --strict-shared-models as a boolean (default false)', () => {
+    expect(parseArgs(['--out', 'gen', '--file', 'e.json']).strictSharedModels).toBe(false)
+    expect(
+      parseArgs(['--out', 'gen', '--file', 'e.json', '--strict-shared-models']).strictSharedModels,
+    ).toBe(true)
+  })
+
+  it('CLI --shared-models-module overrides a config value', () => {
+    const parsed = parseArgs(
+      ['--out', 'gen', '--file', 'e.json', '--shared-models-module', '@cli/pkg'],
+      { sharedModelsModule: '@config/pkg' },
+    )
+    expect(parsed.sharedModelsModule).toBe('@cli/pkg')
+  })
+
+  it('strictSharedModels is seeded from config when the flag is absent', () => {
+    const parsed = parseArgs(['--out', 'gen', '--file', 'e.json'], { strictSharedModels: true })
+    expect(parsed.strictSharedModels).toBe(true)
+  })
+})

package/src/codegen/bin/cli.ts

@@ -30,6 +30,8 @@ export interface CodegenConfig {
   unsupportedUnions?: 'throw' | 'fallback'
   shareModels?: boolean
   sharedTypesImport?: SharedTypesImportMap
+  sharedModelsModule?: string
+  strictSharedModels?: boolean
 }
 
 export interface ParsedArgs {
@@ -51,6 +53,8 @@ export interface ParsedArgs {
   unsupportedUnions?: 'throw' | 'fallback'
   shareModels: boolean
   sharedTypesImport?: SharedTypesImportMap
+  sharedModelsModule?: string
+  strictSharedModels: boolean
 }
 
 // ---------------------------------------------------------------------------
@@ -170,6 +174,8 @@ export function parseArgs(argv: string[], config?: CodegenConfig): ParsedArgs {
   let unsupportedUnions: 'throw' | 'fallback' | undefined = config?.unsupportedUnions
   let shareModels = config?.shareModels ?? true
   const sharedTypesImport = config?.sharedTypesImport
+  let sharedModelsModule: string | undefined = config?.sharedModelsModule
+  let strictSharedModels = config?.strictSharedModels ?? false
   let configPath: string | undefined
 
   for (let i = 0; i < argv.length; i++) {
@@ -260,6 +266,10 @@ export function parseArgs(argv: string[], config?: CodegenConfig): ParsedArgs {
       shareModels = true
     } else if (arg === '--no-share-models') {
       shareModels = false
+    } else if (arg === '--shared-models-module') {
+      sharedModelsModule = argv[++i]
+    } else if (arg === '--strict-shared-models') {
+      strictSharedModels = true
     } else if (arg === '--config') {
       configPath = argv[++i]
     } else if (arg !== undefined && arg.startsWith('--')) {
@@ -336,6 +346,8 @@ export function parseArgs(argv: string[], config?: CodegenConfig): ParsedArgs {
     ...(unsupportedUnions !== undefined ? { unsupportedUnions } : {}),
     shareModels,
     ...(sharedTypesImport !== undefined ? { sharedTypesImport } : {}),
+    ...(sharedModelsModule !== undefined ? { sharedModelsModule } : {}),
+    strictSharedModels,
   }
 }
 
@@ -425,6 +437,9 @@ async function runWithWatch(parsed: ParsedArgs): Promise<void> {
         ...(parsed.swift?.accessLevel !== undefined ? { swiftAccessLevel: parsed.swift.accessLevel } : {}),
         shareModels: parsed.shareModels,
         ...(parsed.sharedTypesImport !== undefined ? { sharedTypesImport: parsed.sharedTypesImport } : {}),
+        ...(parsed.sharedModelsModule !== undefined ? { sharedModelsModule: parsed.sharedModelsModule } : {}),
+        strictSharedModels: parsed.strictSharedModels,
+        logger: (message: string) => { console.log(message) },
         ...kotlinWiring,
         ...swiftWiring,
       })
@@ -555,6 +570,9 @@ async function main(): Promise<void> {
       ...(parsed.swift?.accessLevel !== undefined ? { swiftAccessLevel: parsed.swift.accessLevel } : {}),
       shareModels: parsed.shareModels,
       ...(parsed.sharedTypesImport !== undefined ? { sharedTypesImport: parsed.sharedTypesImport } : {}),
+      ...(parsed.sharedModelsModule !== undefined ? { sharedModelsModule: parsed.sharedModelsModule } : {}),
+      strictSharedModels: parsed.strictSharedModels,
+      logger: (message: string) => { console.log(message) },
       ...kotlinWiring,
       ...swiftWiring,
     })

package/src/codegen/bin/flag-specs.test.ts

@@ -24,4 +24,15 @@ describe('flag-specs', () => {
     expect(KNOWN_FLAGS).not.toContain('--help')
     expect(KNOWN_FLAGS).not.toContain('-h')
   })
+
+  it('catalogs the shared-models convention + strict flags', () => {
+    expect(KNOWN_FLAGS).toContain('--shared-models-module')
+    expect(KNOWN_FLAGS).toContain('--strict-shared-models')
+  })
+
+  it('documents the new flags in --help output', () => {
+    const help = formatHelp()
+    expect(help).toContain('--shared-models-module')
+    expect(help).toContain('--strict-shared-models')
+  })
 })

package/src/codegen/bin/flag-specs.ts

@@ -27,6 +27,8 @@ export const FLAG_SPECS: readonly FlagSpec[] = [
   { name: '--client-import-path', arg: '<path>', description: 'Override the client runtime import path', group: 'Codegen' },
   { name: '--share-models', description: 'Hoist $id-bearing schemas into a shared _models.ts', group: 'Codegen', default: 'on' },
   { name: '--no-share-models', description: 'Inline every type per route (legacy behaviour)', group: 'Codegen' },
+  { name: '--shared-models-module', arg: '<module>', description: 'Re-export every $id model from one module (convention; sharedTypesImport overrides)', group: 'Codegen' },
+  { name: '--strict-shared-models', description: 'Fail if any $id model would be generated as a local twin', group: 'Codegen' },
   { name: '--jsdoc', description: 'Emit JSDoc on generated types', group: 'Codegen', default: 'on' },
   { name: '--no-jsdoc', description: 'Suppress JSDoc', group: 'Codegen' },
   { name: '--enum-style', arg: '<union|enum>', description: 'How to emit enums (namespace mode)', group: 'Codegen' },

package/src/codegen/collect-models.test.ts

@@ -40,7 +40,29 @@ it('does NOT throw for ordinary schemas without the reserved prefix', () => {
 
 it('resolveModelImports tags mapped models and leaves others generated', () => {
   const models = [{ id: 'urn:msg', name: 'Message', schema: {} as any }]
-  const mapped = resolveModelImports(models, { 'urn:msg': { module: '@shared/schemas', name: 'Message' } })
+  const mapped = resolveModelImports(models, {
+    sharedTypesImport: { 'urn:msg': { module: '@shared/schemas', name: 'Message' } },
+  })
   expect(mapped[0]?.import).toEqual({ module: '@shared/schemas', name: 'Message' })
-  expect(resolveModelImports(models, {})[0]?.import).toBeUndefined()
+  expect(resolveModelImports(models)[0]?.import).toBeUndefined()
+})
+
+it('resolveModelImports falls back to sharedModelsModule when no map entry matches', () => {
+  const models = [{ id: 'urn:msg', name: 'Message', schema: {} as any }]
+  const resolved = resolveModelImports(models, { sharedModelsModule: '@app/schemas' })
+  expect(resolved[0]?.import).toEqual({ module: '@app/schemas', name: 'Message' })
+})
+
+it('resolveModelImports: explicit map entry wins over the convention', () => {
+  const models = [{ id: 'urn:msg', name: 'Message', schema: {} as any }]
+  const resolved = resolveModelImports(models, {
+    sharedTypesImport: { 'urn:msg': { module: '@override/pkg', name: 'Msg' } },
+    sharedModelsModule: '@app/schemas',
+  })
+  expect(resolved[0]?.import).toEqual({ module: '@override/pkg', name: 'Msg' })
+})
+
+it('resolveModelImports: empty-string convention is treated as unset (generated locally)', () => {
+  const models = [{ id: 'urn:msg', name: 'Message', schema: {} as any }]
+  expect(resolveModelImports(models, { sharedModelsModule: '' })[0]?.import).toBeUndefined()
 })

package/src/codegen/collect-models.ts

@@ -93,16 +93,33 @@ export function collectModels(routes: AnyHttpRouteDoc[]): CollectedModel[] {
   })
 }
 
+/** Options controlling how collected models are resolved to external imports. */
+export interface ResolveModelImportsOptions {
+  /** Per-`$id` external import. A matching entry wins over `sharedModelsModule`. */
+  sharedTypesImport?: SharedTypesImportMap
+  /** Single module every otherwise-unmapped `$id` model re-exports from (convention). */
+  sharedModelsModule?: string
+}
+
 /**
- * Tags each collected model with its external import when its `$id` is a key in
- * the import map; models without a mapping keep `import` undefined (generated locally).
+ * Tags each collected model with its external import. Precedence:
+ *   1. an explicit `sharedTypesImport[$id]` entry (per-type override / rename),
+ *   2. otherwise, when `sharedModelsModule` is set, the convention
+ *      `{ module: sharedModelsModule, name: model.name }` — every shared model
+ *      re-exports from one module under its derived name (`$id`/`title` === export),
+ *   3. otherwise `import` stays undefined and the model is generated locally.
  */
 export function resolveModelImports(
   models: CollectedModel[],
-  map: SharedTypesImportMap = {}
+  options: ResolveModelImportsOptions = {},
 ): ResolvedModel[] {
+  const { sharedTypesImport = {}, sharedModelsModule } = options
   return models.map((model) => {
-    const mapped = map[model.id]
-    return mapped ? { ...model, import: mapped } : { ...model }
+    const mapped = sharedTypesImport[model.id]
+    if (mapped) return { ...model, import: mapped }
+    if (sharedModelsModule != null && sharedModelsModule !== '') {
+      return { ...model, import: { module: sharedModelsModule, name: model.name } }
+    }
+    return { ...model }
   })
 }

package/src/codegen/emit-index.test.ts

@@ -180,6 +180,40 @@ describe('emitIndexFile', () => {
     })
   })
 
+  describe('per-scope client types (DX #15)', () => {
+    const groups = [usersGroup, billingGroup]
+
+    it('emits the aggregate client type from the factory return type', () => {
+      const out = emitIndexFile(groups, { serviceName: 'Api' })
+      expect(out).toContain('export type ApiClient = ReturnType<typeof createApiBindings>')
+    })
+
+    it('emits one per-scope client type as an indexed access into the aggregate', () => {
+      const out = emitIndexFile(groups, { serviceName: 'Api' })
+      expect(out).toContain("export type UsersClient = ApiClient['users']")
+      expect(out).toContain("export type BillingClient = ApiClient['billing']")
+    })
+
+    it('honors a custom serviceName in the client type names', () => {
+      const out = emitIndexFile(groups, { serviceName: 'Catalog' })
+      expect(out).toContain('export type CatalogClient = ReturnType<typeof createCatalogBindings>')
+      expect(out).toContain("export type UsersClient = CatalogClient['users']")
+    })
+
+    it('documents the aggregate and per-scope client types so the DI-seam intent is visible in the generated file', () => {
+      const out = emitIndexFile(groups, { serviceName: 'Api' })
+      // Aggregate type carries a one-line summary.
+      expect(out).toContain('/** Full typed client surface — every scope of `Api`. */')
+      // Each per-scope type names the scope and points at the DI use case.
+      expect(out).toContain(
+        '/** Narrow port for the `users` scope — inject as a DI seam without casting the aggregate client. */',
+      )
+      expect(out).toContain(
+        '/** Narrow port for the `billing` scope — inject as a DI seam without casting the aggregate client. */',
+      )
+    })
+  })
+
   describe('clientImportPath', () => {
     it('uses custom clientImportPath in both import statements', () => {
       const output = emitIndexFile([usersGroup], { clientImportPath: '@my-app/client' })