ts-procedures 8.3.0 → 8.5.0

package/docs/client-and-codegen.md

@@ -72,6 +72,32 @@ const api = createClient({
 })
 ```
 
+## Offline codegen (no running server)
+
+You don't need a live HTTP server to generate the client. Serialize the DocEnvelope to disk with `writeDocEnvelope`, then point codegen at the file with `--file`.
+
+**Step 1 — Emit the envelope to a file:**
+
+```typescript
+// scripts/emit-docs.ts
+import { writeDocEnvelope } from 'ts-procedures'
+import { buildApp } from '../src/app.js' // builds your HonoAppBuilder / DocRegistry
+
+const builder = buildApp()
+await writeDocEnvelope(builder, 'docs.json')
+```
+
+`writeDocEnvelope` accepts a built `HonoAppBuilder` (via `toDocEnvelope()`), a `DocRegistry` (via `toJSON()`), or a plain `DocEnvelope` object — no running HTTP server required. Parent directories are created as needed and the envelope is written as pretty JSON.
+
+**Step 2 — Run codegen against the file:**
+
+```bash
+tsx scripts/emit-docs.ts
+npx ts-procedures-codegen --file docs.json --out src/generated --service-name Api
+```
+
+This is handy for CI pipelines and monorepos where the client is generated as a build step without standing up the server.
+
 ## Generated File Structure
 
 Running the codegen command produces one file per scope, plus shared types, client runtime, error types, and a barrel export:
@@ -108,6 +134,9 @@ generated/
 | `--uncountable-words <list>` | Comma-separated words to skip singularization (ignored with `--no-namespace-types`) | Off |
 | `--service-name <name>` | Names the service namespace and binding factory (e.g. `Auth` → `export namespace Auth` + `createAuthBindings`). Also prefixes `${Name}Errors` and `${Name}ProcedureErrorUnion` in `_errors.ts`. | `Api` |
 | `--clean-out-dir` / `--no-clean-out-dir` | Prune orphaned generated files from `--out <dir>` before writing — files carrying the `ts-procedures-codegen` signature that this run no longer emits (e.g. a deleted scope). Hand-written files (no signature) are never removed, and subdirectories are left untouched. Skipped under `--dry-run`. Pass `--no-clean-out-dir` to opt out. | **On** |
+| `--share-models` / `--no-share-models` | Collect `$id`-bearing subschemas into a shared `_models.ts` hub; scopes import from there instead of inlining types. | **On** |
+| `--shared-models-module <module>` | Convention form: re-export every `$id` model (with no explicit `sharedTypesImport` entry) from this single module. E.g. `--shared-models-module @app/schemas`. | Off |
+| `--strict-shared-models` | Fail the build if any `$id` model would be generated locally as a structural twin (i.e., not covered by `sharedTypesImport` or `sharedModelsModule`). CI guard. | Off |
 
 > **Note:** ajsc formatting options (`--enum-style`, `--depluralize`, `--array-item-naming`, `--uncountable-words`) only take effect in namespace mode (the default). With `--no-namespace-types`, all types are inlined and these options have no effect.
 >
@@ -199,6 +228,81 @@ const client = createClient({
 })
 ```
 
+### Authentication (rotating tokens)
+
+A bearer token usually changes over the lifetime of a client — it expires and gets refreshed. The catch: a **static** `headers` record is captured **once**, when you create the client (or when you build the per-call options object). Whatever token value was in scope at that moment is frozen into the request forever:
+
+```typescript
+// ⚠️ Goes stale: `session.token` is read once, at client construction.
+const client = createClient({
+  adapter,
+  scopes: createApiBindings,
+  defaults: {
+    headers: { Authorization: `Bearer ${session.token}` },
+  },
+})
+```
+
+There are two seams for re-evaluating the value on every request.
+
+**Function-valued `headers` (recommended).** Instead of a record, pass a function. It's invoked (and awaited, if it returns a promise) on every call, so the current token is always read fresh:
+
+```typescript
+const client = createClient({
+  adapter,
+  scopes: createApiBindings,
+  defaults: {
+    // Re-evaluated per request — never goes stale.
+    headers: () => ({ Authorization: `Bearer ${session.token}` }),
+  },
+})
+
+// The function may be async — useful when the token is loaded on demand:
+const client = createClient({
+  adapter,
+  scopes: createApiBindings,
+  defaults: {
+    headers: async () => ({ Authorization: `Bearer ${await getAccessToken()}` }),
+  },
+})
+```
+
+The function form works everywhere a `headers` record does — client `defaults.headers` and per-call `options.headers` — and the same precedence applies: per-call headers (function or record) win over default headers, and route-declared headers from `schema.input.headers` win over both. A per-call function override:
+
+```typescript
+await client.users.GetUser(
+  { pathParams: { id: '123' } },
+  { headers: () => ({ Authorization: `Bearer ${oneOffToken}` }) },
+)
+```
+
+**The `auth` shorthand (most concise).** For the common case — a single rotating bearer token — pass `auth: () => session.token` directly on the client config. It's sugar over function-valued `headers`: re-evaluated per request, wired to `Authorization: Bearer <token>` internally, and a `null`/`undefined` return omits the header (handy while a session is still loading). It composes with `defaults.headers` (both are applied) and remains overridable by per-call `headers` and `onBeforeRequest`:
+
+```typescript
+const client = createClient({
+  adapter,
+  scopes: createApiBindings,
+  auth: () => session.token, // may be async; null/undefined → no Authorization header
+})
+```
+
+**The `onBeforeRequest` hook (alternative).** If you need full access to the outgoing request — not just the header values — mutate it from the hook. The hook runs last and has the final say (see [Precedence](#precedence)):
+
+```typescript
+const client = createClient({
+  adapter,
+  scopes: createApiBindings,
+  hooks: {
+    onBeforeRequest(ctx) {
+      ctx.request.headers = { ...ctx.request.headers, Authorization: `Bearer ${session.token}` }
+      return ctx
+    },
+  },
+})
+```
+
+> **Warning:** A token placed in a **static** `headers` record (`headers: { Authorization: ... }`) type-checks fine and silently goes stale — the request keeps sending whatever token was current at construction time. For any value that changes between calls, use the function form or `onBeforeRequest`.
+
 ### Typed Per-Request Metadata
 
 Every `AdapterRequest` carries an optional `meta` field typed via the `RequestMeta` interface. `RequestMeta` is declared empty by design — augment it in your own project via TypeScript declaration merging and your fields become typed end-to-end: in per-call options, in hook contexts, and inside your adapter.
@@ -426,6 +530,65 @@ await generateClient({
 })
 ```
 
+## Shared Model Types (`_models.ts`)
+
+When `shareModels` is on (the default), the codegen pre-pass collects every subschema with a `$id` field, deduplicates them, and emits a single `_models.ts` hub. Every scope that references one of those types imports from `./_models` instead of inlining it — so the type is defined once and shared across scopes.
+
+### `sharedTypesImport` — per-`$id` override map
+
+For each `$id` you'd rather import from your own package instead of generating locally, add an entry to `sharedTypesImport` in the config file:
+
+```jsonc
+// ts-procedures-codegen.config.json
+{
+  "sharedTypesImport": {
+    "https://example.com/schemas/Message": { "module": "@app/schemas", "name": "Message" }
+  }
+}
+```
+
+`_models.ts` then re-exports that type from `@app/schemas` instead of generating it — scopes still import from `./_models` (single hub, no scattered imports).
+
+### `sharedModelsModule` — one-value convention
+
+When ALL (or most) of your `$id`-bearing models live in a single shared package, use `sharedModelsModule` instead of listing each one in the per-`$id` map:
+
+```jsonc
+// ts-procedures-codegen.config.json — collapse the per-$id map to one module
+{ "sharedModelsModule": "@app/schemas" }
+```
+
+```bash
+npx ts-procedures-codegen --file envelope.json --out gen --shared-models-module @app/schemas
+```
+
+Every `$id` model that has no explicit `sharedTypesImport` entry is re-exported from this single module under its derived name (the convention: `$id`/`title` === the exported type name). The generated scope file then imports `Api.Users.GetUser.Response.Body` from `./_models`, which re-exports it from `@app/schemas` — one symbol, not a structural twin.
+
+Precedence in `resolveModelImports`: explicit `sharedTypesImport[$id]` → `sharedModelsModule` → generate locally. Use the per-`$id` map only for overrides (rename, a different package per type, multi-consumer setups).
+
+### Shared-models diagnostics
+
+On the CLI, every codegen run that has `$id`-bearing models prints a neutral one-line summary:
+
+```
+[ts-procedures-codegen] Shared models: 5 total — 4 re-exported, 1 generated locally.
+```
+
+This makes a silently-generated structural twin visible — if a model you expected to re-export appears in "generated locally", check that its `$id` is covered by `sharedTypesImport` or `sharedModelsModule`.
+
+When calling `generateClient` programmatically the run is silent by default (no stray stdout in your build scripts or tests); pass `logger: console.log` to opt into the same summary.
+
+**CI guard — `--strict-shared-models`:** pass this flag (or set `strictSharedModels: true` in the config) to turn the silent fallback into a hard error. Codegen will list every `$id` that would be generated as a local structural twin and exit non-zero — a reliable guard against the single-source-of-truth silently degrading:
+
+```bash
+# CI: fail the build if any domain entity is generated as a structural twin
+npx ts-procedures-codegen --file envelope.json --out gen --strict-shared-models
+```
+
+`strictSharedModels` is off by default so existing setups are unaffected. Enable it once you've confirmed all expected `$id` models are covered.
+
+> **Note:** Source-tree scanning (e.g. a `--shared-types-from <dir>` flag) was deliberately not implemented. Codegen is pure-envelope: `--url` and offline `--file` codegen never depend on a local source tree, so it works identically in CI and on a developer's machine.
+
 ## Self-Contained Mode (Default)
 
 By default, the generated output includes two additional files in the output directory:

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

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

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