ts-procedures 8.6.0 → 9.0.0

package/docs/decisions/2026-06-02-monorepo-split-evaluation.md

@@ -1,80 +0,0 @@
-# Decision: keep ts-procedures as a single package (monorepo split declined)
-
-- **Status:** Accepted — 2026-06-02
-- **Supersedes:** the draft [`docs/npm-workspaces-migration-plan.md`](../npm-workspaces-migration-plan.md) (retained for the revisit scenario below)
-
-## Context
-
-A plan was drafted to split `ts-procedures` into a 7-package npm-workspaces
-monorepo under the `@ts-procedures/*` scope (core, client, http, codegen, hono,
-astro, setup), published fresh at `v1.0.0`. The stated motivation was **consumer
-install surface**: "a codegen-CLI user shouldn't pull the Hono server runtime; an
-Astro user shouldn't pull `ajsc`."
-
-The overriding project goal is **a codebase that is VERY easy to maintain with
-great DX — no magic, no incidental complexity.** Before committing to the split,
-we verified the motivation line-by-line against the source.
-
-## Decision
-
-**Do not split.** Keep `ts-procedures` as a single package and capture the real,
-residual benefit cheaply. The split's cost (7 packages, Changesets, an import
-codemod, an OIDC release pipeline, an org claim, a hard import cutover, and
-cross-package devDependency test edges) is a large, permanent increase in
-*maintainer* surface that directly conflicts with the project goal — and it
-solves a problem that is mostly already solved.
-
-## Rationale (verified evidence)
-
-| Claim | Evidence |
-|---|---|
-| The install-surface problem is ~80% already solved | `hono`, `astro`, `ajsc` are `optionalDependencies` (`package.json`) → never installed on a normal `npm install ts-procedures`. |
-| `ajsc` is never loaded unless used | Consumed via dynamic `await import('ajsc')` (`src/codegen/emit-types.ts`). |
-| Codegen does not pull the server runtime | Codegen's only edge into core is `import type` (erased at compile); zero value imports of `hono`/`astro`. |
-| The pain is not real (yet) | No doc, commit, or `CLAUDE.md` line records install surface / unwanted deps as a felt problem. |
-| The split would not even shrink the base floor | `core` must keep `suretype`+`typebox` (then) as regular deps, so every consumer pulls them regardless of the split. |
-| The one concrete, cheaply-fixable gap | No `sideEffects: false` field → bundlers couldn't tree-shake unused subpaths. Fixed (see below). |
-
-A split is uniquely justified **only** by benefits the single package cannot
-deliver: independent per-concern **versioning/publishing cadence**, or
-`@ts-procedures` **org branding/discoverability**. Neither was the actual driver,
-so the split was declined.
-
-## Consequences — what we did instead (the cheap wins)
-
-Implemented on the single package, 2026-06-02:
-
-1. **`"sideEffects": false`** in `package.json` — enables bundler tree-shaking of
-   any subpath a consumer doesn't import. Verified safe: no side-effect imports or
-   global mutation in production code.
-2. **`import type` everywhere it belongs** — converted the schema layer
-   (`resolve-schema-lib.ts`, `schema/types.ts`) to type-only imports. Result:
-   `typebox` is no longer a runtime value import anywhere in shipped code (lib
-   detection is duck-typed); only `suretype`'s `extractSingleJsonSchema` remains a
-   runtime value import, in one branch.
-3. **`verbatimModuleSyntax: true`** (`tsconfig.json`) — makes value-vs-type import
-   intent explicit and catches the whole bug class (this is the flag that would
-   have caught the draft plan's own `import { Procedures }` value-vs-type slip).
-4. **`@typescript-eslint/consistent-type-imports`** rule (`error`) — enforces the
-   above going forward; the one-time autofix split mixed imports and surfaced 3
-   genuinely dead imports, which were removed.
-5. **Optional-integrations table** in the README — documents the optional-peer
-   story (install `hono` for `ts-procedures/hono`, `astro` for the adapter, `ajsc`
-   for Kotlin/Swift codegen).
-
-All changes verified: `npm run lint` (0 errors), `npm run build` (clean),
-`npm test` (983 passing, 0 type errors).
-
-## When to revisit
-
-Revive the split — and the retained
-[`npm-workspaces-migration-plan.md`](../npm-workspaces-migration-plan.md) (with
-its corrections: codegen→core is a **normal** dependency because the public API
-leaks `DocEnvelope`; expose the wire contract via a named `core/contract` seam;
-move spanning tests to a private integration-tests package) — **only if** one of
-these becomes a real, stated requirement:
-
-- per-concern packages need to ship on **independent version cadences**, or
-- the `@ts-procedures` **scoped-org identity** is wanted for branding/discovery.
-
-Until then, "install surface" alone does not justify the maintenance cost.

package/docs/handoffs/2026-06-08-dx-round2-declines.md

@@ -1,45 +0,0 @@
-# DX Round 2 — Findings #13 and #11: schema-authoring remedies
-
-Thanks for the careful round-2 report — both #13 and #11 are real friction, and we want to give you the clean fix for each. Both turn out to be schema-authoring choices that live on your side of the contract, so the durable remedy is upstream of codegen. Codegen faithfully reflects the schema it's handed; by the time it runs, each `$id`-bearing model has already been collected as an independent, flattened type (deduped by `$id` and emitted standalone), so codegen has no view of the relationships *between* your models and can't normalize or re-relate them after the fact. Here's the recommended path for each.
-
-## #13 — Optional field spells "empty" two ways across Create vs Update
-
-**The clean fix (do this):** make the Create/Update pair agree on a single "empty" spelling for the optional field, then one form→body mapping serves both branches.
-
-The two bodies currently disagree at the source:
-
-- Create authors the field as `Type.Optional(Type.String())` → `string | undefined`
-- Update authors it as `Type.Optional(Type.Union([Type.String(), Type.Null()]))` → `string | null` (plus `undefined`)
-
-That divergence is in the authored contract, so the generated types reflect it exactly — codegen widening or normalizing one to match the other would mean overriding your schema and silently emitting a type that no longer matches what the server validates and accepts. We don't want generated client types to disagree with the wire contract.
-
-Pick one convention and apply it to both procedures:
-
-- Both `string | undefined` — `Type.Optional(Type.String())` on each; "omit to leave unchanged."
-- Both `string | null` — `Type.Optional(Type.Union([Type.String(), Type.Null()]))` on each; `null` is the explicit "clear it" signal.
-
-Once the pair is symmetric, a single form→body mapper covers both create and update, and the per-call laundering disappears.
-
-## #11 — `UpdateXBody` should be assignable to `Partial<Entity>` without an `as` cast
-
-**The clean fix (do this):** derive the update body from a shared entity schema so the subset relationship is expressed in the *schema*, where it can survive into the generated types.
-
-This one codegen genuinely cannot synthesize. By the time codegen sees `UpdateXBody`, it's a flattened, independent `$id` model — the "this is a subset of `Entity`" relationship was never encoded in the JSON Schema we received, so there's nothing in the input from which to reconstruct the `Partial`/subset linkage. We'd be inventing a relationship the contract didn't state.
-
-Express the relationship at authoring time so it carries through:
-
-```ts
-// shared entity schema — single source of truth
-const Entity = Type.Object({ /* … all fields … */ }, { $id: 'Entity' })
-
-// update body is a structural subset, authored as such
-const UpdateXBody = Type.Partial(Type.Pick(Entity, ['name', 'email', /* … */ ]))
-```
-
-Authored this way, `UpdateXBody` is structurally a partial subset of `Entity`, and the generated update-body type is assignable to `Partial<Entity>` without a cast.
-
-If you'd rather not restructure the schemas right now, the documented `as Partial<Entity>` bridge remains a supported, intentional escape hatch — it's a one-line annotation at the call site and doesn't compromise anything else.
-
----
-
-Happy to pair on either change if it's useful, or to review the schema diff once you've made the Create/Update pair symmetric.

package/docs/handoffs/ajsc-named-type-collision.md

@@ -1,134 +0,0 @@
-# Handoff: x-named-type reference should win over a same-named structural extraction
-
-> **STATUS: OPEN REQUEST — not yet shipped in ajsc.** ts-procedures currently DETECTS this collision and throws a route-qualified error, rejecting an otherwise-valid schema. We'd retire that detect-and-error once ajsc disambiguates per the proposal below.
-
-**To:** ajsc maintainer
-**From:** ts-procedures codegen (consumer of ajsc as the JSON-Schema → TS/Kotlin/Swift emitter)
-**Date:** 2026-06-06
-**ajsc version inspected:** 7.3.0
-**Priority:** medium — removes a DX wart in ts-procedures (a valid schema is rejected); no current miscompilation, because we detect-and-error rather than emit wrong code
-
----
-
-## TL;DR
-
-`x-named-type` (shipped in 7.3.0, thank you) lets ts-procedures reference a shared model `Message` instead of inlining it. But when a route schema *also* has a property whose ajsc-derived extraction name equals that model name, ajsc **silently merges** the two: the external reference resolves to the unrelated structural sub-type. Your README already documents this caveat and the detection signal (`extractedTypeNames` ∩ `referencedNamedTypes`).
-
-The ask: make an `x-named-type` reference **take precedence** over a would-be structural extraction of the same name — rename the *extraction*, keep the *reference* verbatim. The reference is an explicit author intent ("this is the external `Message`"); the extraction name is an ajsc-derived convenience. Intent should win.
-
-Additive and opt-in in effect (only changes output for schemas that currently collide, which today produce silently-wrong code). Nothing changes when no collision exists.
-
----
-
-## Why this happens
-
-ts-procedures hoists every `$id`-bearing subschema into a shared `_models.ts` and rewrites each route schema's occurrence into `{ "x-named-type": "<Name>" }` so routes *reference* the model rather than inline it (the integration contract from the prior `x-named-type` handoff, now live).
-
-Separately, with `inlineTypes: false`, ajsc extracts inline nested objects into sub-types **named after the property** (PascalCased). So a route schema can independently produce an extracted sub-type whose name happens to equal a model's title.
-
-When those two names coincide, ajsc's `$ref`/extraction merge collapses them. Because the merge happens **inside ajsc, before codegen sees any output**, a post-hoc rename downstream can't fix it — renaming the emitted text would rewrite the model reference too, yielding a silently-wrong type. The merge is lossy at the source.
-
-## What ajsc 7.3.0 does today (the blocker)
-
-A route property named `message` (an inline object) PascalCases to an extracted sub-type `Message`. A sibling property `latest` references the external model via `{ "x-named-type": "Message" }`. The reference and the extraction share the name `Message`, and ajsc merges them — `latest` resolves to the structural `{ unread }`, **not** the external `Message`.
-
-```jsonc
-// input route schema (inlineTypes: false)
-{ "type": "object", "properties": {
-    "latest":  { "x-named-type": "Message" },          // external ref → shared _models.ts Message
-    "message": { "type": "object", "title": "Message",  // inline → ajsc extracts a sub-type "Message"
-                 "properties": { "unread": { "type": "boolean" } } } } }
-```
-
-```ts
-// ajsc 7.3.0 output — the extracted structural type wins; the external reference is lost
-export type Message = { unread?: boolean };          // structural extraction (from `message`)
-export type Root = { latest?: Message; message?: Message };
-//                            ^^^^^^^ WRONG — `latest` now points at { unread } instead of the
-//                            real shared Message model. The x-named-type intent was silently merged away.
-// converter.referencedNamedTypes === ['Message']   AND   converter.extractedTypeNames === ['Message', …]
-// → both lists contain 'Message': the documented collision signal.
-```
-
-```ts
-// desired output — the reference wins, the extraction is renamed
-export type MessageRef = { unread?: boolean };       // structural extraction, disambiguated
-export type Root = { latest?: Message; message?: MessageRef };
-//                            ^^^^^^^ correct — external Message preserved (imported from _models)
-//                                                 ^^^^^^^^^^ structural sub-type disambiguated
-// converter.extractedTypeNames === ['MessageRef', …]   // the rename is reported back
-// converter.referencedNamedTypes === ['Message']       // reference untouched
-```
-
-The reference is what the author explicitly asked for; the extraction name is incidental. The reference should be the one preserved verbatim.
-
----
-
-## Requested feature
-
-When a name referenced via `x-named-type` would collide with a name ajsc is about to assign to an *extracted* structural sub-type, **the reference wins**: keep the referenced name verbatim and disambiguate the extraction. Pick whichever of the following best fits ajsc's internals — listed in our order of preference:
-
-### Option (a) — x-named-type references win (recommended)
-
-When a referenced name collides with a would-be extraction, **rename the extraction** (append a suffix — `Ref`, `Inner`, or a numeric tail like ajsc already uses elsewhere) and keep the reference verbatim. Surface the *final* extraction name in `extractedTypeNames` so the caller sees the rename. The referenced name in `referencedNamedTypes` is unchanged.
-
-This is the most "just works" outcome: the schema author gets a correct external reference and a (renamed) structural type, with zero new API surface. It mirrors ajsc's existing sub-type-naming disambiguation, just seeded by the set of referenced names.
-
-### Option (b) — a `reservedExtractionNames` converter option
-
-Add a converter option — `reservedExtractionNames?: Set<string>` (or `reservedNames`) — so the caller can hand ajsc the set of model names up front and guarantee extractions avoid them (renaming on conflict). This puts the caller in control and is explicit, at the cost of one new option. ts-procedures would pass the full set of `_models.ts` names. Functionally equivalent to (a) for our case; (a) is preferable because it needs no caller wiring and protects every consumer by default.
-
-### Option (c) — explicit no-op acknowledgement
-
-If you prefer to keep disambiguation as the caller's responsibility, a short note in the README confirming that — and that the documented `extractedTypeNames` ∩ `referencedNamedTypes` signal is the intended detection mechanism — lets us keep our detect-and-error in good conscience. Least preferred: it leaves a valid schema rejectable downstream.
-
-**Recommendation: (a).** It removes the failure mode for every consumer with no new API and matches the principle that an explicit reference outranks a derived extraction name.
-
----
-
-## Current downstream interim (the DX wart)
-
-ts-procedures DETECTS the collision and throws rather than emit wrong code. The check (`assertNoModelNameCollision` in `src/codegen/emit-scope.ts`) is the **set intersection** of the converter's two reported lists — ajsc's documented signal:
-
-```
-collision = referencedNamedTypes ∩ extractedTypeNames
-```
-
-A non-empty intersection means a referenced model name also appears as an ajsc-extracted declaration — i.e. the silent merge happened. We throw a clear, route-qualified error telling the author to rename the colliding property or change the model's `$id`/`title`. This is correct but unfortunate: the schema is *valid*, and the author is forced to rename something to satisfy a code-generator limitation. We'd retire this the moment ajsc disambiguates.
-
----
-
-## How ts-procedures will consume it (integration contract)
-
-Once ajsc disambiguates (option (a) or (b)):
-
-1. We **drop the detect-and-error** in `emit-scope.ts` — or downgrade it to a defensive `assert` (a non-empty intersection should then be impossible, so a remaining one would indicate an ajsc regression rather than a user error).
-2. The colliding schema **just works**: `latest: Message` resolves to the shared `_models.ts` model; the structural sibling emits under its disambiguated name (e.g. `MessageRef`), referenced correctly from the route type.
-3. We continue to read `referencedNamedTypes` for imports (unchanged) and `extractedTypeNames` for the route's local type set — which, under option (a), now carries the renamed extraction automatically.
-
-The contract we depend on: **a referenced `x-named-type` name is never overwritten by an extraction — the extraction yields**, and the final extraction name is reported in `extractedTypeNames`.
-
----
-
-## Tests worth adding
-
-1. `x-named-type: "Message"` sibling to an inline object property `message` (PascalCases to `Message`) ⇒ reference resolves to external `Message`; extraction renamed (e.g. `MessageRef`); `extractedTypeNames` carries the renamed name; `referencedNamedTypes === ['Message']`; the two lists no longer intersect.
-2. Same model referenced at N sites alongside one colliding extraction ⇒ all references stay verbatim; only the extraction is renamed.
-3. Multiple distinct collisions in one schema ⇒ each extraction independently disambiguated; references all preserved.
-4. No collision (referenced name ≠ any extraction name) ⇒ byte-identical to current 7.3.0 output (regression guard).
-5. Option (b) only: `reservedExtractionNames` containing a name that *would not* otherwise collide ⇒ extraction proactively avoids it; references unaffected.
-
----
-
-## Versioning
-
-Additive in effect — it only changes output for schemas that **currently miscompile** (a silent merge). For every non-colliding schema the output is byte-identical. A **minor** bump (e.g. 7.4.0). ts-procedures will gate the removal of its detect-and-error on the ajsc version that introduces the precedence rule, keeping the guard as a fallback for one release if you'd prefer a soft cutover.
-
----
-
-## Contact / context
-
-- `src/codegen/emit-scope.ts` — `assertNoModelNameCollision` (the detect-and-error we want to retire)
-- `src/codegen/emit-types.ts` — `referencedNamedTypes` already surfaced (`ExtractedTypeOutput.referencedNamedTypes`, `jsonSchemaToTypeBodyWithRefs`); `extractedTypeNames` not yet surfaced, will be wired when (a)/(b) lands
-- `src/codegen/collect-models.ts`, `emit-models.ts` — `$id` model collection / `_models.ts` emission (unaffected)
-- `docs/handoffs/ajsc-named-type-support.md` — the prior (shipped) `x-named-type` handoff this builds on

package/docs/handoffs/ajsc-named-type-support.md

@@ -1,181 +0,0 @@
-# Handoff: named-type / verbatim-type support in ajsc
-
-> **STATUS: Shipped in ajsc 7.3.0 and adopted in ts-procedures (this cutover).** The placeholder-token workaround described below has been deleted; `substituteModelRefs` now emits `{ 'x-named-type': '<Name>' }` and the codegen reads the converter's `referencedNamedTypes`. The rest of this doc is retained for historical context.
-
-**To:** ajsc maintainer
-**From:** ts-procedures codegen (consumer of ajsc as the JSON-Schema → TS/Kotlin/Swift emitter)
-**Date:** 2026-06-05
-**ajsc version inspected:** 7.2.0
-**Priority:** medium — unblocks removing a workaround in ts-procedures, no current breakage
-
----
-
-## TL;DR
-
-ts-procedures needs a way to tell ajsc: *"this subschema is an already-defined named type called `Message` — emit a reference to it (`Message`), don't convert/inline it, and tell me you referenced it so I can add an import."*
-
-ajsc 7.2.0 has no such mechanism: a `$ref` to a `$defs` entry is **inlined and re-extracted under the property name** (with no dedup), and there is no verbatim-type escape hatch. We've worked around this downstream with a placeholder-token hack (described below) that we'd like to delete once ajsc supports this directly.
-
-The ask is small and **additive** (a new opt-in schema keyword + one new field on the emit result). Nothing changes when the keyword is absent.
-
----
-
-## Why we need it
-
-ts-procedures generates a typed API client from a server's schema. The same domain entity (e.g. `Message`) appears in many route schemas. Today ajsc inlines a fresh structural literal at every site, so `Message` is emitted ~4–6 times under different names in one file, disconnected from each other and from the author's `Message` type. We want **one** `Message` type that every route references.
-
-We already know the identity: each such schema carries a stable `$id` (e.g. `urn:msg`) and a `title` (`Message`). So at codegen time we hoist every `$id`-bearing schema into a shared `_models.ts` (emitted via `ajsc.emitTypescript(messageSchema, { rootTypeName: 'Message' })` — which works great), and we want each *route* schema to **reference** `Message` rather than inline it.
-
-## What ajsc 7.2.0 does today (the blocker)
-
-Based on inspecting the installed `dist/`:
-
-1. **`$ref` is inlined, not referenced.** The IR layer (`ir/JSONSchemaConverter`) resolves `$ref` against `$defs`/`definitions` by inlining, and rejects non-local refs (`"Only local references are supported"`). With `inlineTypes: false`, the inlined object is then re-extracted **named after the property** — so a schema with `author`, `lastReply`, and `all` all `$ref`-ing the same `Message` emits three duplicate types `Author`, `LastReply`, `All`, with **no deduplication** and no way to make them one `Message`.
-
-   ```jsonc
-   // input
-   { "type": "object", "properties": {
-       "author":    { "$ref": "#/$defs/Message" },
-       "lastReply": { "$ref": "#/$defs/Message" } },
-     "$defs": { "Message": { "type": "object", "title": "Message",
-                             "properties": { "id": { "type": "string" } } } } }
-   ```
-   ```ts
-   // ajsc 7.2.0 output (inlineTypes:false) — duplicated, property-named, no dedup
-   export type Author    = { id?: string };
-   export type LastReply = { id?: string };
-   export type Root = { author?: Author; lastReply?: LastReply };
-   ```
-
-2. **No verbatim-type escape hatch.** Grepping `dist/` for `tsType | x-ts | verbatim | existingType | customType | rawType` returns nothing. We tried `{ tsType: 'Message' }`, `{ "x-tsType": 'Message' }`, `{ $ref: 'Message' }` (bare), `{ type:'object', tsType:'Message' }` — all are ignored (emit `any` / `{ [key:string]: unknown }`) or throw.
-
-3. **`EmitResult.imports` is empty for TypeScript.** The function-form `emitTypescript(schema, opts)` returns `{ code, rootTypeName, extractedTypeNames, imports }`, but `imports` is documented (README ~line 110) as Kotlin/Swift-only — there's no channel to surface "this TS output references external type `Message`."
-
-### Our current workaround (what we want to delete)
-
-Because ajsc can't reference a named type, ts-procedures smuggles a sentinel through ajsc and scrapes it back out:
-
-1. Before calling ajsc, replace each `$id`-bearing subschema with `{ const: '__MODELREF__Message__' }`. ajsc emits that verbatim as a string-literal type (`author?: "__MODELREF__Message__"`), and — usefully — never extracts it as a sub-type, and survives inside `Array<…>`.
-2. After ajsc, a global regex `/["']__MODELREF__([A-Za-z_$][\w$]*)__["']/g` rewrites the tokens to bare names (`author?: Message`) and collects the referenced names so we can emit `import type { Message } from './_models'`.
-
-It works and is well-tested, but it encodes a *type identity* as schema *data*, runs it through a code generator, and recovers it from generated *text* with a regex. We'd much rather express the intent directly to ajsc.
-
----
-
-## Requested feature
-
-A new **opt-in schema keyword** that marks a subschema as an already-defined named type. When present, ajsc:
-
-1. emits a **reference** to that name (does not convert/inline the subschema, does not extract a sub-type), and
-2. **reports** the referenced name on the emit result so the caller can wire an import.
-
-### Keyword name & shape
-
-ajsc is multi-target (TS/Kotlin/Swift), so prefer a target-agnostic keyword over a TS-specific one. Suggested:
-
-```jsonc
-{ "x-named-type": "Message" }
-```
-
-`x-`-prefixed so it's unambiguously an annotation and ignored by standard JSON-Schema validators. (If you'd rather not use `x-`, `namedType` or `typeRef` are fine — your call on convention.)
-
-- **Value = string:** the identifier emitted verbatim in **every** target (`Message` in TS, Kotlin, and Swift). This matches our usage — we use the same PascalCase name across targets.
-- **Optional future extension:** allow an object for per-language names, e.g. `{ "x-named-type": { "ts": "Message", "kotlin": "Message", "swift": "Message" } }`. Not needed by us now; mentioning so the string form can widen later without a breaking change.
-
-### Semantics
-
-- The keyword **short-circuits conversion** of that subschema node: emit the bare identifier as the type, in all the positions ajsc already handles a leaf type (direct property, `Array<…>` items, union member, map value, etc.).
-- With `inlineTypes: false`, the named type is **not** added to `extractedTypeNames` (it's external — defined elsewhere).
-- The node is **not** recursed into (its `properties`/`items` are irrelevant once it's a named reference). A `type`/`properties` sitting alongside `x-named-type` should be ignored (or, if you prefer strictness, validated to match — but ignore is simpler and matches our need; we strip the body anyway).
-- **Absent keyword ⇒ zero behaviour change.** Fully backward compatible.
-
-### Reporting referenced names
-
-Add referenced external names to the emit result so the caller can build imports. Two acceptable shapes:
-
-- **Preferred:** a new field `referencedNamedTypes: string[]` on `EmitResult` (deduped, sorted or insertion-order — either is fine; we sort downstream).
-- **Or:** populate the existing (currently-empty-for-TS) `imports` field with the bare names.
-
-A new dedicated field is cleaner than overloading `imports` (which means module paths for Kotlin/Swift).
-
-### Worked example
-
-```jsonc
-// input
-{ "type": "object", "properties": {
-    "author": { "x-named-type": "Message" },
-    "replies": { "type": "array", "items": { "x-named-type": "Message" } },
-    "id": { "type": "string" } } }
-```
-
-```ts
-// desired TS output (inlineTypes:false)
-export type Root = { author?: Message; replies?: Array<Message>; id?: string };
-// emitResult.referencedNamedTypes === ['Message']   // Root is NOT polluted with a Message decl
-```
-
-```kotlin
-// desired Kotlin output
-data class Root(val author: Message? = null, val replies: List<Message>? = null, val id: String? = null)
-// referencedNamedTypes === ['Message']
-```
-
-```swift
-// desired Swift output
-struct Root: Codable { let author: Message?; let replies: [Message]?; let id: String? }
-// referencedNamedTypes === ['Message']
-```
-
-In every case ajsc does **not** define `Message` — the caller (ts-procedures) defines it once elsewhere and adds the import/reference.
-
----
-
-## Where this likely lives in ajsc
-
-From the `dist/` surface (you know the real source layout):
-
-- **IR conversion** (`ir/JSONSchemaConverter` or equivalent): detect `x-named-type` on a node early and lower it to a new IR node kind — e.g. `NamedTypeRef(name)` — instead of converting the object. This is the one place that needs to intercept before the existing `$ref`-inline / object-extract logic runs.
-- **Each language emitter** (`typescript/`, `kotlin/`, `swift/`): render `NamedTypeRef(name)` as the bare identifier wherever a leaf type is rendered, and **collect** the name into the result.
-- **`EmitResult` type** (`index.d.ts`): add `referencedNamedTypes?: string[]` (or document `imports` carrying them for TS).
-- **`BaseConverterOpts`:** no new option needed — the keyword lives in the schema, not the options. (You *could* add a `validateNamedTypes` strictness flag later; not required.)
-
----
-
-## Tests worth adding (mirror our spike findings)
-
-1. `x-named-type` on a direct property ⇒ `prop?: Message`, `referencedNamedTypes` includes `Message`, no `Message` extracted.
-2. Inside `array.items` ⇒ `Array<Message>` (TS) / `List<Message>` (Kotlin) / `[Message]` (Swift).
-3. Same name referenced by N properties ⇒ deduped to a single `Message` reference, `referencedNamedTypes === ['Message']` (the dedup we can't get today).
-4. As a whole root schema (`{ "x-named-type": "Message" }` at top level) ⇒ output is just `Message` (our route-response-is-exactly-a-model case).
-5. Both `inlineTypes: true` and `inlineTypes: false` behave identically for the referenced name (it's a leaf either way).
-6. Absent keyword ⇒ byte-identical to current output (regression guard).
-7. Coexists with genuine sibling extraction: a schema with one `x-named-type` property and one ordinary nested object still extracts the ordinary object normally under `inlineTypes:false`.
-
----
-
-## How ts-procedures will consume it (integration contract)
-
-So you can sanity-check the design against the real caller:
-
-1. We already collect every `$id`-bearing subschema into a registry `{ $id, name, schema }` and emit each one standalone via `emitTypescript(schema, { rootTypeName: name })` into `_models.ts`. **No change needed there.**
-2. For each *route* schema, instead of our placeholder-token substitution, we'll walk the schema and replace each `$id`-bearing subschema with `{ "x-named-type": <name> }` before calling ajsc.
-3. We read `emitResult.referencedNamedTypes` to emit `import type { Message, … } from './_models'` per scope file.
-4. We delete `model-refs.ts` (the placeholder/regex module) entirely and the two wrapper functions in `emit-scope.ts`.
-
-The contract we depend on: **(a)** a referenced `x-named-type` is never inlined and never extracted, and **(b)** its name is reported back. Those two guarantees are the whole feature.
-
----
-
-## Versioning
-
-Additive and opt-in ⇒ a **minor** bump (e.g. 7.3.0). No migration for existing consumers. ts-procedures will gate on the ajsc version that introduces `referencedNamedTypes` and keep the placeholder-token path as a fallback for one release if you'd like a soft cutover, or hard-switch if you prefer.
-
----
-
-## Contact / context
-
-The placeholder-token workaround, the design rationale, and the empirical ajsc probes live in the ts-procedures repo:
-- `src/codegen/model-refs.ts` — the current substitution we want to remove
-- `src/codegen/emit-models.ts`, `collect-models.ts` — the model collection/emission (unaffected)
-- `docs/superpowers/specs/2026-06-05-dx-feedback-round-design.md` — design (see finding #3)
-- commit `483185e` — the spike that established ajsc's inlining behaviour and chose the workaround

package/docs/handoffs/shared-models-auto-resolve-response.md

@@ -1,181 +0,0 @@
-# Response: shared-models auto-resolve (re: `--shared-types-from` request)
-
-> **STATUS: SHIPPED (v8.5.0).** Three targeted improvements shipped in place of source-file scanning. See below for what landed and why the requested mechanism was declined.
-
-**To:** downstream developer
-**From:** ts-procedures codegen maintainers
-**Date:** 2026-06-06
-**Reference:** feedback on `sharedTypesImport` DX — pain points 1–3
-
----
-
-## TL;DR
-
-The goal — "define it once, no second table, no silent drift" — was right. We shipped three targeted fixes that deliver those ergonomics from the DocEnvelope side rather than by scanning TypeScript source files, which would introduce a worse class of silent failure. The per-`$id` `sharedTypesImport` map is unchanged and remains available as a precision escape hatch.
-
----
-
-## What shipped
-
-### 1. `sharedModelsModule` — one line replaces the entire map
-
-A single module path tells codegen: *"re-export every `$id` model from this module under its derived name."*
-
-```jsonc
-// ts-procedures-codegen.config.json
-{ "sharedModelsModule": "@app/schemas" }
-```
-
-```bash
-# CLI
-npx ts-procedures-codegen --url http://localhost:3000/doc --out ./generated --shared-models-module @app/schemas
-```
-
-```ts
-// generateClient() API
-await generateClient({ url, outDir, sharedModelsModule: '@app/schemas' })
-```
-
-Convention: the derived name is the model's `$id`/`title` (PascalCase), which is the same identifier your schema file already exports. If the names align — they usually do — the entire `sharedTypesImport` map collapses to this single value.
-
-Precedence: explicit `sharedTypesImport[$id]` entry → `sharedModelsModule` convention → generate locally. The map remains available to override individual entries (rename, different package, multi-consumer split).
-
-### 2. Summary log (CLI)
-
-Every CLI run that finds `$id`-bearing models now prints:
-
-```
-[ts-procedures-codegen] Shared models: 15 total — 15 re-exported, 0 generated locally.
-```
-
-This makes silent generated-twin drift visible without requiring any additional flags or contract tests. (Calling `generateClient` programmatically is silent by default — pass `logger: console.log` to opt in — so the summary never leaks into your own build-script output.)
-
-### 3. `--strict-shared-models` — hard-fail on local twins
-
-Fails the run and lists every `$id` that would be generated as a local structural twin instead of re-exported:
-
-```bash
-npx ts-procedures-codegen ... --strict-shared-models
-```
-
-```jsonc
-{ "strictSharedModels": true }
-```
-
-```ts
-await generateClient({ url, outDir, sharedModelsModule: '@app/schemas', strictSharedModels: true })
-```
-
-This is a **CI flag, not a development default** — run it in your pipeline and codegen becomes the drift gate. It replaces a hand-written `toEqualTypeOf` contract test.
-
----
-
-## How this maps to your three pain points
-
-### Pain 1: Two places to keep in lockstep (`$id` and the map entry)
-
-`sharedModelsModule` derives the import from the model's own `$id`/`title` — you define the convention once and it applies to every model. There is no second table to maintain.
-
-### Pain 2: Silent fallback — a generated structural twin that typechecks but isn't the real type
-
-Two layers now make this visible:
-
-- The CLI summary log surfaces the "generated locally" count on every codegen run.
-- `--strict-shared-models` promotes that to a hard failure, listing the specific `$id`s. Add it to your CI pipeline and the generated-twin state becomes impossible to ship.
-
-This replaces your hand-written `toEqualTypeOf` contract test with a single flag — the codegen itself owns the invariant.
-
-### Pain 3: The map is redundant — `module` is "where the schema lives" and `name` is usually the `$id`
-
-`sharedModelsModule` makes that redundancy disappear. `name` is derived from the model's `$id`/`title`; `module` is supplied once for all models. The 15-entry map becomes one line.
-
----
-
-## Why `--shared-types-from <dir|glob>` was declined
-
-The goal was right. The mechanism is what we changed.
-
-ts-procedures codegen has one explicit input contract: a **DocEnvelope** obtained via `--url`, `--file`, or a passed object. The envelope is a self-contained JSON document — it contains schemas, routes, and error shapes. Codegen never reads the consumer's TypeScript source tree. That decoupling is what makes codegen work against a live remote server, a serialized offline file, or a published package with no local source.
-
-Source-file scanning would break that contract in four concrete ways:
-
-**(a) Silent desync in `--url` / offline `--file` cases.** The live server's envelope and the local source tree can disagree at any point in time — a schema field renamed in the server but not yet deployed, an `$id` changed in source but not rebuilt. Source scanning would produce a "shared" reference that names a type the server actually never returns. The result typechecks and the single-source-of-truth claim is restored, but the types are silently WRONG — a worse outcome than today's duplicate-but-correct structural twin.
-
-**(b) Fails for published-package consumers.** If `@app/schemas` lives in `node_modules`, there is no TypeScript source tree to scan — only compiled `.d.ts` files (if any) or nothing. The scan would silently skip models that are genuinely shared from a published package and generate local twins for them anyway, with no signal.
-
-**(c) Requires a TS parser, glob runner, and export-resolution heuristics in codegen.** This is a substantial dependency and surface area. It introduces failure modes (barrel re-exports, `export * from`, conditional exports, `.d.ts` vs. `.ts`) whose edge cases are hard to exhaustively enumerate and maintain. The DocEnvelope contract specifically exists to avoid this category of tooling dependency.
-
-**(d) Does not solve module-path correctness.** A file path discovered by glob scanning (`src/schemas/message.ts`) is not a valid TypeScript import specifier for a consumer who imports `@app/schemas`. Path-to-module-alias resolution requires TypeScript's full compiler configuration. Without it, any path the scan produces must be corrected by hand — which brings back a second table.
-
-The `sharedModelsModule` convention solves the same "define once, no second table" problem. The module specifier (`@app/schemas`) is typed once; names are derived from the model's own `$id`/`title`. It works in all deployment topologies: live server, offline file, published package.
-
----
-
-## Escape hatch: `sharedTypesImport` unchanged
-
-The per-`$id` map is unchanged and remains available for cases where `sharedModelsModule` is not enough:
-
-- A model whose TypeScript name differs from its `$id` (rename case).
-- Different models imported from different packages (`@app/schemas` and `@app/internal-schemas`).
-- Multi-consumer split where a subset of models come from a shared package and others are generated locally.
-
-```jsonc
-{
-  "sharedModelsModule": "@app/schemas",
-  "sharedTypesImport": {
-    "urn:internal-msg": { "module": "@app/internal-schemas", "name": "InternalMessage" }
-  }
-}
-```
-
-`sharedTypesImport` entries take precedence over `sharedModelsModule`, so you can cover the general case with the convention and override individual outliers explicitly.
-
----
-
-## Migration example
-
-**Before (v8.3 and earlier) — 15-entry hand-maintained map + contract test:**
-
-```jsonc
-// ts-procedures-codegen.config.json
-{
-  "shareModels": true,
-  "sharedTypesImport": {
-    "urn:message":      { "module": "@app/schemas", "name": "Message" },
-    "urn:user":         { "module": "@app/schemas", "name": "User" },
-    "urn:thread":       { "module": "@app/schemas", "name": "Thread" },
-    "urn:attachment":   { "module": "@app/schemas", "name": "Attachment" },
-    "urn:reaction":     { "module": "@app/schemas", "name": "Reaction" },
-    "urn:channel":      { "module": "@app/schemas", "name": "Channel" },
-    "urn:workspace":    { "module": "@app/schemas", "name": "Workspace" },
-    "urn:notification": { "module": "@app/schemas", "name": "Notification" },
-    "urn:role":         { "module": "@app/schemas", "name": "Role" },
-    "urn:permission":   { "module": "@app/schemas", "name": "Permission" },
-    "urn:bot":          { "module": "@app/schemas", "name": "Bot" },
-    "urn:webhook":      { "module": "@app/schemas", "name": "Webhook" },
-    "urn:app":          { "module": "@app/schemas", "name": "App" },
-    "urn:token":        { "module": "@app/schemas", "name": "Token" },
-    "urn:audit-log":    { "module": "@app/schemas", "name": "AuditLog" }
-  }
-}
-```
-
-```ts
-// contract test to catch silent twins
-expect(generatedMessage).toEqualTypeOf<Message>()
-expect(generatedUser).toEqualTypeOf<User>()
-// ... × 15
-```
-
-**After (v8.5.0) — one config line + one CI flag:**
-
-```jsonc
-// ts-procedures-codegen.config.json
-{
-  "shareModels": true,
-  "sharedModelsModule": "@app/schemas",
-  "strictSharedModels": true
-}
-```
-
-No map. No contract tests. `--strict-shared-models` (or `"strictSharedModels": true`) in CI is the drift gate: codegen fails and names the offender if any `$id` model would silently generate as a local twin.