ts-procedures 8.6.0 → 9.0.0

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

@@ -1,285 +0,0 @@
-# DX Feedback Round — Design
-
-**Date:** 2026-06-05
-**Status:** Approved (pending spec review)
-**Source:** Downstream-developer feedback from building the demo server (`src/server`), 5 findings.
-
-This round addresses five findings. Each section states the problem, the decision
-taken (with the alternatives considered), and the concrete shape of the change.
-
-Two items are cross-logged but **explicitly out of scope** this round (no scope creep):
-- The `ts-channels` codegen has the identical #3 (per-route inlining) defect — coordinating the two is follow-up.
-- #5 is cross-logged with `ts-channels #9` / `mvc-kit #2` — aligning all three scaffolders is follow-up.
-
----
-
-## #1 — `ts-procedures-codegen --help` (MEDIUM)
-
-### Problem
-`--help` falls through to the unknown-flag branch and exits non-zero with a
-misfiring did-you-mean suggestion (`Did you mean --url?`). There is no usage text
-anywhere in the CLI, so the rich flag surface (`--watch`, `--dry-run`,
-`--enum-style`, Kotlin/Swift targets, …) is undiscoverable without reading the
-built JS.
-
-### Decision: structured flags as the single source of truth
-Replace the bare-string `KNOWN_FLAGS` array (`src/codegen/bin/cli.ts`) with a
-structured table — one entry per flag:
-
-```ts
-interface FlagSpec {
-  name: string            // '--service-name'
-  arg?: string            // '<name>'  (omitted for booleans)
-  description: string     // one line
-  group: 'Source' | 'Output' | 'Codegen' | 'Targets' | 'Misc'
-  default?: string        // shown in help when meaningful, e.g. 'Api'
-}
-```
-
-Derive **both** the validation set (the current `KNOWN_FLAGS` membership check)
-and the `--help` output from this table — adding a flag now documents it and the
-two can never drift. This directly resolves the CLAUDE.md warning that
-`KNOWN_FLAGS` must be hand-synced with `parseArgs`.
-
-Behaviour:
-- `--help` / `-h` / **bare invocation with no args** → print grouped usage
-  (header, usage line, flags grouped by `group` with aligned descriptions and
-  defaults) and **exit 0**.
-- Exclude `--help`/`-h` from the did-you-mean candidate set so the suggestion is
-  never actively misleading.
-
-### Alternatives considered
-- *Hand-written usage block, `KNOWN_FLAGS` stays bare strings.* Rejected:
-  descriptions live apart from the flag list and drift — exactly the duplication
-  the codebase warns against.
-
----
-
-## #2 — Offline doc-envelope emission (LOW)
-
-### Problem
-`--file <path>` codegen works, but nothing *produces* that file. The envelope
-only exists in-process via `builder.toDocEnvelope(cfg)`, so the regen loop forces
-either a running server (`codegen --url`) or a hand-written `JSON.stringify`
-script.
-
-### Decision: exported helper only
-Ship a public, stable helper:
-
-```ts
-export async function writeDocEnvelope(
-  source: DocEnvelope | { toDocEnvelope(): DocEnvelope } | DocRegistry,
-  path: string,
-): Promise<void>
-```
-
-- Accepts a built `HonoAppBuilder`/`DocRegistry` (anything with
-  `toDocEnvelope()`) **or** a plain `DocEnvelope`.
-- Serializes pretty JSON to `path` (creating parent dirs).
-- Exported from a stable entry point and documented with a 3-line script:
-  `build builder → writeDocEnvelope(builder, 'docs.json') → codegen --file docs.json`.
-
-No module-loading magic in the CLI — the user owns the tiny emit script, which is
-the most portable option and avoids a TS-loader dependency.
-
-### Alternatives considered
-- *CLI `--builder <module>` that imports the user's builder in-process.* Rejected
-  for now: importing user TS/ESM requires a loader (tsx/jiti) the package doesn't
-  carry; pushes complexity and failure modes into the CLI.
-
----
-
-## #3 — Shared types keyed on `$id` (MEDIUM)
-
-### Problem
-Codegen inlines a fresh structural literal at every route site. The same `Message`
-entity is emitted ~4× under different names in one scope file
-(`GetThread.Response.Message`, `ListMessages.Response.RootType`,
-`SendMessage.Response.Body`, nested in `CreateThread`), none connected to the
-authored `@shared/schemas` `Message`. The copies type-check only because the
-shapes coincide today; a field change one codegen path misses drifts **silently**.
-
-### Decision: hoist in codegen, leave the envelope untouched
-
-**Architectural call.** The `$id` already rides along on route subschemas in the
-envelope (verified: `Type.Object({…}, { $id, title })` survives `toDocEnvelope()`).
-Rather than change the envelope into a `$defs`/`$ref` table — which would break
-every already-serialized envelope and force the Kotlin/Swift pipelines to become
-`$ref`-aware — the **TS codegen** does a pre-pass over the inlined schemas. Result:
-zero envelope-shape change, zero impact on Kotlin/Swift, already-serialized
-envelopes keep working.
-
-#### Identity rule (correctness-critical)
-- Hoist **only** schemas carrying `$id`. `$id` is the dedup key (globally unique).
-- The generated type **name** comes from `title` (fallback: derive from `$id`).
-- Schemas with a `title` but no `$id` are **not** hoisted — they stay inlined
-  exactly as today. Identity is *declared*, never inferred from structure.
-- If two subschemas share an `$id` but have **divergent bodies** → **hard error**
-  at collect time (never silently pick one).
-- Schemas without `$id` produce byte-identical output to today, so existing
-  consumers who never set `$id` see no change.
-
-#### Components
-1. **`src/codegen/collect-models.ts`** (new) — walks every route's JSON schema
-   recursively (all four route kinds: rpc/api/stream/http-stream slots), collects
-   each subschema carrying `$id` into a model registry
-   `{ $id, name, schema }`. Detects `$id` body-divergence collisions and throws.
-   Also detects generated-name collisions between distinct `$id`s and disambiguates
-   (`Message`, `Message2`, …) deterministically by first-seen order.
-
-2. **`_models.ts`** (new emitted file) — the single hub:
-   - For each model whose `$id` is in the `sharedTypesImport` map → emit a
-     re-export: `export { Message } from '@shared/schemas'` (renamed to the
-     model name if `name` differs).
-   - Otherwise → emit a generated named type for the model schema (via ajsc).
-   - Scopes **always** import from `_models.ts`, regardless of generated-vs-vendored.
-     Flipping a type between the two is a one-line change here with zero scope churn.
-
-3. **`emit-scope` change** — when a route's schema contains a hoisted `$id`
-   subschema, the emitted route type **references** the model's name (import in
-   flat mode, qualified `${Service}Models.Message` in namespace mode) instead of
-   inlining the literal. Non-hoisted subschemas emit unchanged.
-
-4. **`sharedTypesImport` config** (config-file only — a map doesn't fit a CLI flag):
-   ```jsonc
-   // ts-procedures-codegen.config.json
-   "sharedTypesImport": {
-     "https://schemas.example/message": { "module": "@shared/schemas", "name": "Message" }
-   }
-   ```
-
-5. **Flag:** `--share-models` defaults **on** (consistent with the other
-   good-by-default flags); `--no-share-models` opts out and restores pure
-   per-route inlining. Added to the structured flag table from #1.
-
-#### Scope
-- **TS target only.** Kotlin/Swift continue to inline (they simply ignore `$id`
-  metadata; the envelope is unchanged so their pipelines are untouched).
-
-#### Key technical risk — verify first
-The plan opens with a short **verification spike** before committing the emission
-mechanism:
-- **ajsc `$ref` behaviour (v7.2.0):** confirm how ajsc emits a `$ref` to a hoisted
-  model — whether it produces a *reference* to a named type or inlines it. Per
-  CLAUDE.md ajsc "resolves `$defs`/`$ref`", which may mean *inline*. Two paths:
-  - *Preferred:* feed ajsc a route schema with the hoisted subschema replaced by
-    `{ $ref: '#/$defs/Message' }` + a `$defs` table, and capture ajsc's named-type
-    reference.
-  - *Fallback:* emit model types standalone, then post-emit string-substitute the
-    inlined literal with the model name — the same word-boundary patching approach
-    `renameExtractedTypes` (`src/codegen/emit-types.ts`) already uses.
-- **Nested `$id` survival:** confirm `extractJsonSchema` preserves `$id` on
-  **nested** subschemas (root `$id` is verified; nested is not). If stripped, fix
-  extraction to preserve it — this is a prerequisite for hoisting nested entities
-  like `Thread.messages: Message[]`.
-
-### Alternatives considered
-- *Change the envelope to `$defs`/`$ref`.* Rejected: breaks serialized envelopes
-  and forces all targets to become `$ref`-aware.
-- *Hoist into existing `_types.ts`.* Rejected: mixes domain entities with
-  transport/runtime types and only works in self-contained mode.
-- *Per-scope first-declarer-owns.* Rejected: implicit cross-scope ordering/coupling.
-- *Auto-merge structurally-identical types.* Explicitly rejected per the feedback:
-  coincidental shape-equality must not couple two scopes.
-- *Dedup by `$id` OR `title`.* Rejected: two unrelated schemas titled `Response`
-  would wrongly merge — weak identity.
-
----
-
-## #4 — Dynamic auth seam: function-valued headers (MEDIUM)
-
-### Problem
-`config.headers` is a static `Record<string,string>` (`src/client/types.ts:202`),
-captured once at construction. The only dynamic seam is `onBeforeRequest`, which
-is discoverable only by reading `_client.ts`. A live bearer token set in `headers`
-silently goes stale after the next login (the easy-and-wrong path compiles).
-
-### Decision: function-valued headers + signposting docs
-Make `headers` accept a function on both the client `defaults` and per-call options:
-
-```ts
-type HeadersInit =
-  | Record<string, string>
-  | (() => Record<string, string> | Promise<Record<string, string>>)
-```
-
-- `ProcedureCallDefaults.headers` and `ProcedureCallOptions.headers` adopt
-  `HeadersInit` (`src/client/types.ts`).
-- Resolution happens on the **async request path**: `call.ts` / `stream.ts` await
-  header resolution before building the `AdapterRequest`. The static-record path
-  stays synchronous and fast (no behavioural change when headers is a plain object).
-- Merge semantics preserved: resolve defaults-headers and per-call-headers to
-  records, then merge with per-call winning — `onBeforeRequest` still has final say.
-- The resolved `AdapterRequest.headers` remains a plain `Record<string,string>` —
-  adapters are unaffected.
-- Regenerates into self-contained `_types.ts` / `_client.ts`; direct consumers get
-  it from `ts-procedures/client`.
-
-**Docs:** add a short auth section (in the generated-client docs /
-`client-and-codegen.md`) presenting function-valued `headers` and `onBeforeRequest`
-as the canonical auth seams, with an explicit "a token in static `headers` goes
-stale — use a function or the hook" warning.
-
-### Alternatives considered
-- *First-class `auth`/`bearer` option wiring the hook internally.* Not chosen this
-  round — function-valued headers is the general-purpose primitive that also covers
-  auth; a dedicated `auth` sugar can layer on later if wanted.
-- *Docs only.* Rejected: the easy-and-wrong static-headers path still compiles.
-
----
-
-## #5 — Scaffolder file-naming knobs (LOW)
-
-### Problem
-The scaffolder (the AI skill `agent_config/claude-code/skills/ts-procedures/SKILL.md`
-scaffold mode + `templates/*.md`, **not** a CLI) hardcodes `{{Name}}.procedure.ts` —
-PascalCase, one file per procedure — so every scaffold is renamed and folded into a
-per-scope file by hand.
-
-### Decision: `fileNameStyle` + `groupBy` with auto-default
-Add two scaffold-mode args, surfaced in `SKILL.md` and consumed by the templates:
-- `fileNameStyle`: `'PascalCase'` (current) | `'kebab.concern'` (e.g.
-  `get-user.procedure.ts`).
-- `groupBy`: `'flat'` (current, CWD) | `'scope'` (e.g. `<scope>/get-user.procedure.ts`,
-  scope taken from the procedure config).
-
-When **unspecified**, the skill infers the default by inspecting the target
-directory's existing convention (per-scope kebab files vs flat Pascal) — so a
-scaffold matches the consumer's layout with no manual rename pass.
-
-Changes:
-- `SKILL.md` scaffold-mode section: document the two args + the auto-default
-  inference instruction; update the "Files Generated" table to show the computed
-  filename.
-- `templates/*.md`: replace the hardcoded `{{Name}}.<concern>.ts` output with a
-  computed `{{fileName}}` placeholder and an optional `{{scope}}/` directory
-  prefix, plus the placeholder-derivation notes (`{{kebab}}` already exists).
-
-### Alternatives considered
-- *Add knobs, explicit-only (no auto-detect).* Rejected: misses the zero-config
-  match to the repo layout, which is the actual friction.
-- *Defer.* Rejected by scope decision (all three findings actioned this round).
-
----
-
-## Testing strategy
-- **#1:** unit test `--help`/`-h`/bare → exit 0 + usage contains every flag from the
-  table; `--help` not in did-you-mean candidates; unknown flag still errors.
-- **#2:** unit test `writeDocEnvelope` with (a) a plain envelope, (b) a builder-like
-  object — round-trips to disk and re-loads via `resolveEnvelope --file`.
-- **#3:** spike verification first; then fixture-based tests on the canonical
-  `__fixtures__/users-envelope.json` extended with `$id`'d schemas — assert one
-  `_models.ts` declaration per `$id`, route types reference it, `$id` collision
-  throws, `sharedTypesImport` produces re-exports, and `--no-share-models` restores
-  byte-identical legacy output. Add a no-`$id` regression asserting unchanged output.
-- **#4:** unit test function-valued `headers` (sync + async) resolves per request,
-  merges with per-call, and `onBeforeRequest` still overrides; static-record path
-  unchanged.
-- **#5:** verify by scaffolding under each `fileNameStyle`/`groupBy` combination and
-  the auto-default inference (skill-level / template review).
-
-## Out of scope (follow-up)
-- `ts-channels` codegen shared-types fix (identical to #3).
-- Cross-scaffolder alignment with `ts-channels #9` / `mvc-kit #2` (#5).
-- A first-class `auth`/`bearer` client option (sugar over #4).
-- Kotlin/Swift shared-model emission.

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

@@ -1,376 +0,0 @@
-# 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.