ts-procedures 8.6.0 → 9.1.0

package/CHANGELOG.md

@@ -0,0 +1,540 @@
+# Changelog
+
+All notable changes to **ts-procedures** are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## 9.1.0 — 2026-06-10
+
+### Added
+
+- `CreateHttp` no longer requires a `schema` key — a no-input, no-output route
+  (e.g. `successStatus: 204` with only `errors`) can omit it instead of
+  passing `schema: {}`.
+
+### Fixed
+
+- Codegen: a route that declares `errors` but no req/res (e.g. a 204 logout)
+  now emits a per-route namespace housing its `Errors` union. Previously the
+  typed callable referenced `Scope.Route.Errors` while the namespace was never
+  written, so the generated artifact failed `tsc` with
+  `Namespace '…' has no exported member '…'`. Applies to `api` and `rpc`
+  routes in namespace mode; flat mode was already correct. Parity-safe: the
+  affected output never typechecked, so no working consumer's bytes change.
+- `CHANGELOG.md` is now included in the published npm package (it existed in
+  the repo but was missing from the `files` allowlist).
+
+### Docs
+
+- Migration guide: documented that the byte-parity guarantee carried known v8
+  codegen issues into 9.0.0 unchanged, and when fixes can land.
+- Client/codegen guide: cross-origin `basePath` CORS callout (browser clients
+  need server CORS or a same-origin dev proxy), HTTP-vs-WebSocket auth-seam
+  note, and the `Type.Record` / `$id` shared-model limitation.
+
+## 9.0.0 — 2026-06-10
+
+Ground-up restructuring of the library. **Generated codegen output is
+byte-identical to v8.6.0** across all targets (TypeScript, Kotlin, Swift) and
+all modes — verified by a committed golden corpus captured from the v8 build.
+Full upgrade guide: [docs/migration-v8-to-v9.md](docs/migration-v8-to-v9.md).
+
+### Breaking
+
+- `Procedures({ config: { noRuntimeValidation: true } })` → `Procedures({ validation: false })`.
+- Suretype support removed (deprecated since v8). TypeBox is the built-in
+  schema library; other libraries plug in via the new `SchemaAdapter`.
+- `TStreamProcedureRegistration.isStream` removed — use the `kind` discriminant.
+- Duplicate-name registration throws `ProcedureRegistrationError` instead of a
+  bare `Error` (message unchanged).
+- Low-level schema utilities reshaped: `schemaParser` removed (use
+  `computeSchema(name, schema, { adapters, compile })`); `extractJsonSchema`
+  takes an explicit adapter list; `isSuretypeSchema` removed.
+- `dispatchPreStreamError` / `dispatchMidStreamError` are transport-agnostic:
+  they return plain data (`{ type: 'body', statusCode, body }` /
+  `{ data, sseEvent, runOnCatch }`) instead of Hono responses. Only relevant
+  to custom adapter authors; `HonoAppBuilder` behavior is unchanged.
+
+### Fixed
+
+- `CreateHttpStream` registrations now expose `schema.yield` and
+  `schema.res.headers` under the keys route-doc builders read. In v8, live
+  envelopes silently dropped the yield/response-header schemas for
+  `http-stream` routes, so generated clients lost those types unless the
+  envelope was hand-authored.
+- SSE wire behavior is now identical for `rpc-stream` and `http-stream`
+  routes (both served by one `SseEventSequencer`). Two v8 accidents
+  normalized: `http-stream` yields/error events now honor `sse()` metadata
+  (v8 ignored it on that path), and `null` yields serialize as empty SSE data
+  on both paths (v8's `http-stream` wrote the string `null`).
+
+### Added
+
+- `Procedures({ validation: { ajv } })` — per-factory AJV options or instance
+  (the module-level AJV singleton is gone).
+- `Procedures({ schema: { adapters } })` — pluggable schema libraries via the
+  3-method `SchemaAdapter` interface.
+- `Procedures({ http: { pathPrefix, scope } })` — factory-level defaults for
+  `CreateHttp` / `CreateHttpStream`, removing per-route boilerplate.
+- `ts-procedures/server` subpath — the transport-agnostic server toolkit
+  (route-doc builders, taxonomy dispatch, request channel extraction via
+  `RequestSource`, SSE metadata, `DocRegistry`). Writing a Fastify/Express
+  adapter is now a thin-glue exercise; `src/adapters/hono/` is the reference.
+- `Infer<T>` as the primary inference type (`TSchemaLib` kept as an alias);
+  `ProcedureError.kind` discriminant.
+
+### Internal
+
+- Package restructured into `core/` (factory + creators), `schema/`
+  (adapters + AJV compilation), `server/` (framework-free HTTP machinery),
+  `adapters/{hono,astro}`, `client/` (content-frozen — bundled verbatim into
+  self-contained codegen output), `codegen/`.
+- Codegen output is pinned by a 13-case golden matrix (2 fixture envelopes ×
+  TS default/flat/external-runtime/no-share-models/shared-models-module +
+  Kotlin + Swift) plus a DocEnvelope parity test against a v8-captured
+  envelope and sha256 freeze tests on the bundled client runtime.
+
+## 8.6.0 — 2026-06-08
+
+### Added
+
+- **Per-scope client interfaces.** The generated index now exports a `${ServiceName}Client` type (the bindings factory's return type) plus one `<Scope>Client` per scope (e.g. `UsersClient = ApiClient['users']`). A consumer can type a dependency as the narrow scope it actually uses — `constructor(client: UsersClient = api.users)` — and a fake satisfies just that scope, instead of casting `as unknown as typeof api` at every DI seam. Derived from the existing factory return type, so no new naming scheme. TypeScript target.
+- **Callable JSDoc surfaces the per-call options bag and declared errors.** Every generated callable's JSDoc now documents its optional second argument (`ProcedureCallOptions` — `signal`, `timeout`, `headers`, `basePath`) and, for routes that declare `errors`, a `@throws` breadcrumb naming the route's `Errors` type and how to reach it (narrow with `instanceof` on the throwing path, or call `.safe()` for a `Result`). The capabilities already existed; they're now discoverable at the call site without reading `_types.ts`.
+
+### Changed
+
+- **Generated-output change (input-less routes):** a route with no inputs (no path params, query, body, or params) now generates a `void` params type instead of `unknown`, so `api.auth.Me()` is callable with **no argument** and a stray `api.auth.Me({})` is a **type error** (previously `unknown` silently accepted any object). Type-only and opt-in on regeneration — runtime is unaffected. **Migration:** when you regenerate, drop the empty `({})` argument from no-input calls (`api.auth.Me()`, `api.users.ListUsers()`). Routes *with* input are byte-identical to 8.5.0.
+
+### Notes
+
+- Documentation only (no API change): a no-content (204) procedure recipe (`docs/http-integrations.md` — omit `schema.res`, return `undefined`, get `Promise<void>` and a clean 204), client-side discoverability prose for declared errors + per-call options (`docs/client-error-handling.md`), and a design note on typed errors across a state-management boundary.
+
+## 8.5.0 — 2026-06-06
+
+### Added
+
+- **`sharedModelsModule` — one-value shared-types convention.** A single module path (`--shared-models-module <module>`, the `sharedModelsModule` config key, or `generateClient({ sharedModelsModule })`) re-exports every `$id`-bearing model from that module under its derived name (`$id`/`title`), collapsing a hand-maintained `sharedTypesImport` map to one line. Precedence: explicit `sharedTypesImport[$id]` → `sharedModelsModule` convention → generate locally. The per-`$id` map is unchanged and remains the override for rename / per-package / multi-consumer cases. TypeScript target only.
+- **Shared-models diagnostics.** The CLI now prints a neutral one-line summary on every run with `$id`-bearing models (`Shared models: N total — X re-exported, Y generated locally.`), surfacing a silently-generated structural twin. `--strict-shared-models` (`strictSharedModels` config; default **off**) promotes that to a hard error listing every `$id` that would be generated locally — a CI guard that replaces a hand-written `toEqualTypeOf` contract test.
+- **`logger` codegen option.** `generateClient` / `runPipeline` accept an optional `logger?: (message: string) => void`. The shared-models summary is routed through it: the CLI wires it to `console.log`, while programmatic callers stay silent by default (no stray stdout in build scripts/tests) and opt in by passing `logger`.
+
+### Notes
+
+- Source-tree scanning (a requested `--shared-types-from <dir|glob>`) was deliberately **not** added: codegen's input contract stays the DocEnvelope, so `--url`/offline `--file` generation never depends on a local source tree. Rationale in `docs/handoffs/shared-models-auto-resolve-response.md`.
+- Schemas without `$id`, and projects setting none of the new options, produce byte-identical output to 8.4.0.
+
+## 8.4.0 — 2026-06-06
+
+### Added
+
+- **`writeDocEnvelope(source, path)`** — serialize a `DocEnvelope` to disk for offline codegen. Accepts a built `HonoAppBuilder`/`DocRegistry` (anything exposing `toDocEnvelope()`/`toJSON()`) or a plain envelope, so `ts-procedures-codegen --file <path>` no longer needs a running server. Exported from the package root.
+- **`ts-procedures-codegen --help` / `-h`** (and bare invocation) now print grouped usage and exit 0. The flag catalog is a single structured table that drives both flag validation and the help text — flags can no longer drift from their docs — and `--help` is excluded from the did-you-mean suggester (previously it errored with `Did you mean --url?`).
+- **Function-valued client headers + `auth` convenience.** `headers` (client defaults and per-call) now accepts `ClientHeadersInit = Record<string,string> | (() => Record | Promise<Record>)`, resolved per request — the right home for a rotating bearer token, which goes stale in a static record. A first-class `auth` option, `createClient({ auth: () => session.token })`, wires `Authorization: Bearer <token>` per request and composes with any existing default headers.
+- **Shared client types keyed on `$id`.** When a schema carries a `$id`, codegen hoists it into a single `_models.ts` and has every route reference that one named type via `import type { X } from './_models'`, instead of inlining a fresh structural copy per route — so a value returned by one route is the *same* named type another route (and your `@shared/schemas`) uses. Identity is keyed on the declared `$id` (named from `title`), never on structure; an `$id` reused with a divergent body is a hard error. On by default (`--share-models`; opt out with `--no-share-models`). A `sharedTypesImport` config map (`$id → { module, name }`) makes `_models.ts` re-export the type from your own package instead of generating it. TypeScript target only.
+- **Scaffolder `fileNameStyle` + `groupBy`.** The `ts-procedures` scaffold skill accepts `fileNameStyle` (`PascalCase | kebab.concern`) and `groupBy` (`flat | scope`), inferring the default from the target directory's existing layout.
+
+### Changed
+
+- **Codegen now requires `ajsc` ≥ 7.3.0** and uses its `x-named-type` keyword + `referencedNamedTypes` to emit shared-model references directly (replacing an internal placeholder-token mechanism; generated output is unchanged). A shared-model name that collides with a property-derived sub-type name is detected via ajsc's documented signal (`referencedNamedTypes ∩ extractedTypeNames`) and rejected with an actionable, route-qualified error, pending an ajsc root fix that will let the reference win.
+- **Generated-output change (shared models, on by default):** clients whose schemas set `$id` will see those types relocate into `_models.ts` (referenced from each scope) when regenerated. This is a codegen-output change, not a runtime API break; schemas without `$id` produce byte-identical output to 8.3.0. Pass `--no-share-models` to keep the previous per-route inlining.
+
+## 8.3.0 — 2026-06-05
+
+### Fixed
+
+- **`CreateHttp` response handling now honors the documented schema-gated contract.** The `{ body, headers }` envelope is unwrapped **only** when the route declares `schema.res.headers` (the contract stated since 8.0.0). Previously the Hono builder duck-typed the handler's return value, unwrapping **any** object with a top-level `body` key — so a domain model with its own `body` (or `headers`) field was silently truncated to just that field, with a `200`. Returns are now serialized verbatim unless `schema.res.headers` is declared.
+  - **Behavioral change (potentially breaking):** if you returned `{ body }` to *trigger* unwrapping without declaring `schema.res.headers`, that no longer unwraps. Declare `schema.res.headers` and return `{ body, headers }`, or return the body value bare.
+  - A handler that returns `undefined` (a headers-only `res: { headers }` envelope, or a `void` handler) now emits a clean bodyless response instead of an empty, unparseable `application/json` body.
+
+### Changed
+
+- **Taxonomy errors are typed on the client with zero ceremony.** An entry declared with just `{ class, statusCode }` now gets a synthesized `{ name, message }` body schema in the `DocEnvelope`, so `ts-procedures-codegen` emits a typed client error class and registry entry for it automatically — matching the framework's own (schema-carrying) default errors. Previously such entries reached codegen schema-less and fell back to the untyped `ClientHttpError`. Entries that supply a custom `toResponse` (shape unknown) or are documented as raw `ErrorDoc`s still need an explicit `schema` to become typed — see the typed-client note in `docs/http-integrations.md`.
+
+### Docs
+
+- Corrected the per-route `errors` example (use a `satisfies` clause, not a single explicit `CreateHttp` generic, which binds `TName` and breaks `schema.req`/`schema.res` inference); documented that the bundled TypeBox has no `Type.Composite` (compose via a flat `Type.Object({ ...Base.properties })` spread); noted the client `basePath` must be the origin only (generated paths already include the server `pathPrefix`); and added an ESM-only setup callout.
+
+## 8.2.0 — 2026-06-04
+
+### Changed
+
+- **`cleanOutDir` no longer wipes the output directory — it prunes only orphaned _generated_ files, and is now on by default.** Previously `cleanOutDir`/`--clean-out-dir` ran `rm -rf <outDir>`, which could delete hand-written or co-located files and so had to stay opt-out. It now removes only top-level files carrying the `ts-procedures-codegen` signature that the current run no longer emits (e.g. a deleted scope's stale file); files without the signature and any subdirectories are never touched. Because the operation can only ever delete generator-owned files, it now **defaults to `true`** — regenerating a client automatically prunes orphaned scope files. Opt out with `cleanOutDir: false` / `--no-clean-out-dir`. The signature is version-agnostic, so orphans left by an older release of this package are still pruned (relevant in monorepos pinning multiple versions). Dry-run reports `[dry-run] Would remove orphaned generated file: <path>` instead of mutating.
+- **Every generated file now carries a stable package signature.** The TypeScript and Swift headers already mentioned `ts-procedures-codegen`; the Kotlin header gains a `// ts-procedures-codegen — do not edit` line above its source-hash comment so generated Kotlin files are identifiable by the prune. The TypeScript header also includes the package version (`vX.Y.Z`) for downstream visibility in monorepos.
+
+## 8.1.1 — 2026-06-02
+
+### Changed
+
+- **Package marked side-effect-free (`sideEffects: false`).** Bundlers can now tree-shake any subpath you don't import — a Hono-only app drops the codegen/client code it never references, and vice versa. Verified safe: no module performs import-time side effects.
+- **`typebox` is no longer imported at runtime.** Schema-library detection is duck-typed, so the schema layer imports `typebox`/`suretype` as types only. Slightly leaner runtime; no behavior change.
+
+### Added
+
+- **Optional-integration guidance in the README** — which peer dependency to install for the Hono server, Astro adapter, and Kotlin/Swift codegen targets (`hono`, `astro`, `ajsc` are `optionalDependencies`, never pulled by a plain install).
+
+## 8.1.0 — 2026-06-01
+
+### Fixed
+
+- **Duplicate-identifier in generated clients when a sub-type is shared between a route's request and response (namespace mode).** ajsc (`inlineTypes: false`) joins sibling extracted declarations with a single newline but separates the root with a blank line; the codegen parser split only on blank lines, fusing siblings into one element. The rename/dedup logic then only saw the first sibling, so a route whose body and response each produced two or more sub-types emitted the non-first sub-types twice — `error TS2300: Duplicate identifier` — and cross-references inside renamed sibling types silently resolved to a different schema's sub-type of the same name. `jsonSchemaToExtractedTypes` now splits each ajsc block into individual declarations (brace-depth aware, so multi-line enums and per-property JSDoc stay intact), `renameExtractedTypes` patches renamed references across all sibling declarations (not just the root body), and a `DeclarationCollector` guard fails fast on any unresolved same-name collision instead of emitting code that breaks downstream.
+
+## 8.0.0 — 2026-05-08
+
+### Breaking changes
+
+- **`ExpressRPCAppBuilder` removed.** The Express integration (`ts-procedures/express-rpc`) is gone — `HonoAppBuilder` is the single supported HTTP builder. Apps using Express must migrate to Hono (which works on Node, Bun, Deno, and Cloudflare Workers via `@hono/node-server` or similar). The `express` and `@types/express` packages are no longer optional/dev dependencies of this package.
+- **`schema.input` removed** from `Create` / `CreateStream`. HTTP-specific multi-channel input is now `schema.req` on `CreateHttp` / `CreateHttpStream`.
+- **HTTP routes use `CreateHttp`**, not `Create` + `APIConfig`. HTTP fields (`path`, `method`, `successStatus`, `scope`, `errors`) are first-class on `CreateHttp` config.
+- **`schema.input.X` → `schema.req.X`** — channels (`pathParams`, `query`, `body`, `headers`) are unchanged; only the property name changed.
+- **`APIInput` and `APIConfig` no longer required as factory type parameters.** `CreateHttp` accepts HTTP config directly without a factory type parameter. The types remain exported from `ts-procedures/hono-api` for use as helper types (e.g., `satisfies APIInput` for channel-name typo checks).
+- **`APIHttpRouteDoc.jsonSchema` regrouped** — input channels are now under `jsonSchema.req`, response under `jsonSchema.res`. Consumers reading `base.jsonSchema.body` in `extendProcedureDoc` need to read `base.jsonSchema.req.body`.
+- **`Procedures<Ctx, APIConfig>()` → `Procedures<Ctx>()`** for HTTP-only factories. `Create` on these factories now throws if HTTP fields are present; use `CreateHttp` instead.
+- **Generated client flat-mode aliases renamed** — `<Route>Params` → `<Route>ReqPathParams` (and similar per-channel suffixes). Namespace-mode users get `Users.GetUser.Req.PathParams` automatically with no rename needed.
+- **`kind` discriminant on every registration** — `'rpc' | 'rpc-stream' | 'http' | 'http-stream'`. Builder routing and `skippedProcedures` warnings now use this discriminant; code that inspected `isStream` for routing needs to check `kind`.
+
+### New
+
+- **`CreateHttp(name, config, handler)`** — first-class HTTP creator with `schema.req` channels (`pathParams`, `query`, `body`, `headers`) and `schema.res` (`body`, `headers`). No factory type parameter required.
+- **`CreateHttpStream(name, config, handler)`** — streaming counterpart to `CreateHttp`. Yields SSE events; headers declared on `schema.res.headers` surface on `TypedStream.headers`.
+- **Conditional return shape** — `CreateHttp` handler returns body bare when `schema.res.headers` is not declared; returns `{ body, headers }` when it is. TypeScript narrows automatically.
+- **`TypedStream.headers`** — initial response headers surfaced on streams that declare `schema.res.headers`.
+- **`kind` discriminant** on every registration (`'rpc' | 'rpc-stream' | 'http' | 'http-stream'`) drives builder routing and codegen scope grouping.
+
+### Migration
+
+Quick checklist (see `docs/superpowers/specs/2026-05-08-create-http-design.md` for the full migration table):
+
+1. Replace `Procedures<Ctx, APIConfig>()` with `Procedures<Ctx>()` for HTTP factories. (`APIConfig` and `APIInput` still export for other uses.)
+2. Replace `.Create('Foo', { path, method, schema: { input } }, h)` with `.CreateHttp('Foo', { path, method, schema: { req } }, h)`.
+3. Rename `schema.input.X` → `schema.req.X` (channels are identical; only the wrapper key changed).
+4. Update any `extendProcedureDoc` callbacks that read `base.jsonSchema.body` to read `base.jsonSchema.req?.body`.
+5. Re-run `npx ts-procedures-codegen` — regenerated clients use the new type shapes.
+6. Update flat-mode-alias call sites if applicable (see generated `index.ts` diff for renamed exports).
+
+---
+
+## v7.2.0 - Astro.js adapter
+
+Added optional Astro.js api endpoint adapter
+
+## v7.1.1 — Stream typed errors & builder coverage
+
+Six bug fixes around streaming procedures and HTTP-builder coverage, surfaced by a downstream consumer who'd been patching the package locally. The release brings stream typed-error dispatch in line with the call-path contract, fixes a generator-cleanup leak, and adds explicit warnings when procedures are silently dropped from the doc envelope.
+
+This release contains four behavior changes — see "Behavior changes" below. All fixes target streams or builder filtering; non-streaming RPC/API call paths are unchanged.
+
+### Fixed — Stream typed-error dispatch (`event: 'error'`)
+
+`createTypedStream` now recognizes SSE items with `event: 'error'` as terminal, mirroring the call-path contract: the `data` payload is dispatched through the optional `errorRegistry` (looked up by `body.name`), the resulting typed error rejects `.result` and is thrown from the iterator. When no registry entry matches (or no registry is configured), the iterator throws a `ClientStreamError` that exposes the raw body via `error.cause`. Previously, error events were yielded as data — defeating route-declared typed-error narrowing on streams. `executeStream` now plumbs `errorRegistry` and `descriptor` (name/scope) into `createTypedStream`.
+
+### Fixed — `HonoStreamAppBuilder` consults the taxonomy mid-stream
+
+Mid-stream throws now flow through `resolveErrorResponse` against the configured `errors` taxonomy, mirroring `HonoRPCAppBuilder`'s dispatch chain. The resolved body is written as the SSE `event: 'error'` data (or as a JSON line in text mode), which the client decodes through its registry and surfaces as a typed `Error`. `onMidStreamError` remains as a fallback when no taxonomy entry matches; the hard default (`{ error: message }`) is the last resort. The HTTP status is still committed to 200 once streaming starts — the taxonomy only drives the wire-protocol body shape mid-stream.
+
+### Fixed — Streaming `Procedures` wrapper preserves typed-error class identity
+
+`CreateStream` no longer boxes user-thrown errors inside `ProcedureError` with `cause`. Instead, it rethrows the original error (with the procedure's definition site appended to the stack trace in place) so HTTP builders' taxonomies and `onMidStreamError` callbacks see the actual thrown class. Without this, a user-defined error subclass would never match its taxonomy entry by `class:` instanceof — the resolver would have to unwrap `cause` manually. (`Create` is unchanged for now; only the streaming wrapper is affected.)
+
+### Fixed — `CreateStream` propagates `.return()` to the user generator
+
+When a consumer closes a stream early — calling `iterator.return()` or breaking out of `for await` — the wrapped generator now forwards the `.return()` signal to the user's generator so its `finally` blocks run (DB handles, subscriptions, signal-driven teardown). Previously the wrapper iterated via `userIterator.next()` in a loop and never propagated cleanup; user generators leaked resources on early close.
+
+### Changed — Stream procedures emit `methods: ['post', 'get']`
+
+`HonoStreamAppBuilder.buildStreamHttpRouteDoc` now emits `methods: ['post', 'get']` instead of `['get', 'post']`. Codegen uses `methods[0]` as the default invocation method for the generated callable, so streams now default to POST (which can carry a body). GET is retained as a peer route for query-string callers. Server routes still register both methods — only the doc array order changed.
+
+### Fixed — `HonoRPCAppBuilder` skips streaming procedures with a warning
+
+Streaming procedures registered with `HonoRPCAppBuilder` are now filtered out at `build()` time with `console.warn(...)` rather than getting silently mounted at a POST route that returns the async generator object as JSON. Skipped procedures surface via `builder.skippedProcedures`. Symmetrically, `HonoStreamAppBuilder` already filtered non-stream procedures; it now also tracks them in `skippedProcedures` and warns. Register stream procedures with `HonoStreamAppBuilder` (and regular procedures with `HonoRPCAppBuilder` / `HonoApiAppBuilder`).
+
+### Added — `DocSource.skippedProcedures` + `DocRegistry` coverage warning
+
+`DocSource` gains an optional `skippedProcedures: { name: string; reason: string }[]`. When `DocRegistry.toJSON()` runs, it aggregates `skippedProcedures` across every source and emits a single consolidated warning so consumers who only call `registry.toJSON()` (e.g. dumping the envelope to disk for codegen) see coverage gaps without running the builder under a TTY. Set `TS_PROCEDURES_SUPPRESS_COVERAGE_WARNINGS=1` to silence in CI.
+
+### Fixed — `createTypedStream`: no spurious unhandled-rejection on iterator throw
+
+`createTypedStream` and the `client.stream()` deferred wrapper now attach a no-op rejection sink (`resultPromise.catch(() => undefined)`) so consumers that iterate without `await stream.result` don't trip Node's strict unhandled-rejection trackers (notably `node:test`'s default failure mode). Consumers that DO await `.result` still observe the rejection — `.catch` returns a new promise without suppressing the original.
+
+### Behavior changes
+
+These four are intentional contract changes — most consumers won't notice, but the cases below do flip:
+
+1. **SSE `event: 'error'` is now terminal, not yielded.** Anyone treating `event: 'error'` as data needs to handle it in `catch` instead.
+2. **Taxonomy now wins over `onMidStreamError`.** If both are configured, taxonomy hits no longer fall through to `onMidStreamError`.
+3. **`CreateStream` no longer wraps user errors in `ProcedureError`.** Code matching `instanceof ProcedureError` for user-thrown stream errors will miss them; `.cause` is no longer set. (Framework errors — `ProcedureValidationError`, `ProcedureYieldValidationError`, `ctx.error()` — still throw `ProcedureError` subclasses.)
+4. **Generated stream callables default to POST.** Transparent for `HonoStreamAppBuilder` (mounts both); custom servers that only implemented GET must add POST.
+
+---
+
+## v7.1.0 — Codegen correctness & DX
+
+Three correctness fixes in the TypeScript codegen, two CLI/DX improvements. All changes are non-breaking for consumers using the documented entry points (`create${Name}Bindings`, `create${Name}Client`).
+
+### Fixed — `Cannot find name 'RootType'` for array-root schemas
+
+`jsonSchemaToExtractedTypes` (in `src/codegen/emit-types.ts`) used `block.startsWith('export type Root')` to detect the root type block from ajsc's output. That predicate also matched `RootType` — the items type ajsc emits for `Array<RootType>` root schemas — and silently consumed it as the body, leaving the `Array<RootType>` reference dangling. The matcher is now a strict regex requiring `=` after `Root`, so `RootType` (and any other `Root*` sibling) flows correctly to the declarations branch.
+
+### Fixed — Generated client failed to compile under `verbatimModuleSyntax: true`
+
+The index's `export namespace ${Name} { export import <Scope> = _scope.<Scope> }` re-exports tripped TS1269/TS1288 because each scope namespace was type-only. Namespace-mode scope files now emit the scope's `bindScope(client)` function as a member of `export namespace ${Pascal}` (e.g. `Users.bindScope(client)`), making the namespace value+type. The index's `export import` re-exports compile cleanly under verbatim, and the factory in `index.ts` now calls `_users.${Pascal}.bindScope(client)` in namespace mode. Flat mode is unchanged — `bind${Pascal}Scope` stays at module level.
+
+Most consumers go through `create${Name}Bindings(client)` or `create${Name}Client(config)` and won't notice. Direct callers of `bindUsersScope` in namespace mode should switch to `Users.bindScope` (the standalone export was only ever generated in flat mode anyway).
+
+### Fixed — Duplicate `Params` / `Scope` identifiers when a property name shadows a route shortName
+
+Schemas with a property named `params` (or `scope`, `body`, etc.) caused ajsc to extract `export type Params = {…}`, which then collided with the route's own `Params` shortName. The new `renameExtractedTypes` helper detects collisions per-route and aliases the extracted sub-type to `${name}Inner` (then `Inner2`, `Inner3`, …), patching every word-boundary occurrence in the body string so references still resolve. `formatTypes` accepts an `extraReserved` set so `emitApiRoute` can pre-reserve the structured `Params` it injects after the fact. No public API change.
+
+### Added — Strict CLI flag parsing with did-you-mean suggestions
+
+`parseArgs` previously ignored any unrecognized `--…` token, which let a typo like `--targt` silently produce wrong output (or empty envelopes when paired with another bug). It now throws immediately:
+
+```
+[ts-procedures-codegen] Unknown CLI flag: --targt. Did you mean `--target`?
+```
+
+The suggestion uses prefix-containment as the primary heuristic (so `--service` suggests `--service-name`) and falls back to edit distance ≤ 3 (so `--targt` suggests `--target`). When nothing's close enough, the error points at the README instead of suggesting a misleading match.
+
+### Added — `builder.build()` hint in the empty-routes error
+
+`resolveEnvelope` rejects an envelope with zero routes; the message now calls out the most common cause:
+
+```
+DocEnvelope has an empty "routes" array. Common causes:
+(1) you forgot to call `builder.build()` before passing the builder to `DocRegistry.from(...)` —
+    hono builders only populate `docs` inside `build()`;
+(2) no procedures registered with the builder.
+```
+
+### Internal — `runTsc` test helper
+
+E2E tests that shell out to `tsc --noEmit` now share `src/codegen/test-helpers/run-tsc.ts` instead of duplicating the try/execSync/stderr-capture dance in five places. Failures surface stderr in the assertion message uniformly.
+
+---
+
+## v7.0.0 — Normalized client errors & `.safe()` Result API
+
+This major release reshapes how generated clients surface errors to consumers. Every platform error (`TypeError`, `DOMException`) now arrives as a typed framework class, and every RPC/API callable gets a `.safe()` sibling that returns a discriminated `Result<T, E>` instead of throwing. The throwing form remains canonical; `.safe()` is opt-in for sites that want exhaustive failure handling.
+
+See `docs/client-error-handling.md` for the full consumer guide and migration walkthrough.
+
+### Added — Normalized framework error classes
+
+- `ClientNetworkError` — wraps `TypeError` thrown by the adapter (network failure / DNS / refused / CORS). Carries `procedureName`, `scope`, and `cause`.
+- `ClientTimeoutError` — `AbortError` triggered by the per-call/per-default `timeout`. Carries `timeoutMs`.
+- `ClientAbortError` — `AbortError` triggered by a user-supplied `signal`. Carries `reason`.
+- `ClientParseError` — reserved for adapter authors who want to flag an unparseable response body. Default fetch adapter does not raise it (current behavior preserved).
+- All new classes (and the renamed `ClientHttpError`) accept an optional `cause?: unknown` argument and assign it via the standard `Error.cause` property.
+
+### Added — `.safe()` form on generated callables
+
+- Every emitted RPC and API callable now exposes both forms via two new `ClientInstance` helpers: `bindCallable<P, R>(descriptor)` (routes without typed errors) and `bindCallableTyped<P, R, E>(descriptor)` (routes with typed errors). Codegen emits a single one-line call to the helper per route; the helper owns the `Object.assign(fn, { safe })` wiring internally. Per-route emission is ~7 lines vs ~25 for the inline form.
+- Invoke `client.users.GetUser(params)` for the throwing form, or `client.users.GetUser.safe(params)` for the Result form.
+- Routes with declared `errors` produce `Result<Response, RouteErrors>` (carries the `'typed'` arm); routes without get `ResultNoTyped<Response>` (the `'typed'` arm is omitted so IDE hovers stay clean).
+- Generated callable's `.name` is preserved (set via `Object.defineProperty` inside the helper) so stack traces still show the route name.
+- Streams keep the throwing form — `Result<T, E>` doesn't fit their three-way failure surface (pre-stream, mid-stream, completion). Their pre-stream errors still flow through the classifier.
+
+### Added — Augmentable `ClientErrorMap`
+
+- New `ClientErrorMap` interface lets downstream apps add custom `kind` discriminants via TypeScript declaration merging — same pattern as `RequestMeta`.
+- Default keys: `http`, `network`, `timeout`, `aborted`, `parse`, `usage`, `unknown`. The `'typed'` discriminant is reserved for route-declared errors and is not part of `ClientErrorMap`.
+- Pair augmentation with an adapter-side `classifyError` function (composes with `defaultClassifyError`) to make custom kinds first-class members of `Result`.
+
+### Added — Adapter-level error classifier
+
+- `ClientAdapter` interface gains optional `classifyError?: ErrorClassifier`.
+- `createFetchAdapter({ classifyError })` accepts the same.
+- `defaultClassifyError` is exported for adapter authors who want to compose their own classifier with the default fallthrough.
+
+### Changed — `ClientRequestError` renamed to `ClientHttpError`
+
+- Reflects the class's actual role: HTTP-protocol-level failure (4xx/5xx without a registry match), distinct from network/timeout/abort errors.
+- A deprecated alias (`export const ClientRequestError = ClientHttpError`) is retained for one minor release after 7.0.0. Migrate to the new name; `instanceof ClientRequestError` continues to work via the alias until the deprecation window closes.
+
+### Changed — `executeCall` normalizes platform errors at the adapter boundary
+
+- Before: a thrown `TypeError` / `DOMException` propagated to the consumer's catch block as-is.
+- After: the classifier composition (`adapter.classifyError ?? defaultClassifyError`) wraps the raw error in the appropriate framework class. Hooks (`onError`) receive the normalized error.
+- Same change applies to `executeStream`'s pre-stream connection path. Mid-stream errors are unchanged.
+
+### Breaking changes
+
+1. **`ClientRequestError` → `ClientHttpError`** (deprecated alias retained for one minor cycle).
+2. **Raw `DOMException` / `TypeError` no longer reach consumer catch blocks.** They are wrapped in `ClientNetworkError` / `ClientTimeoutError` / `ClientAbortError`. The original platform error is preserved on `error.cause` for inspection.
+3. **`onError` hook receives the normalized framework error in `ctx.error`** (not the raw platform error). Consumers inspecting the raw shape need to update; most just log `error.message` and don't notice.
+
+### Migration
+
+```ts
+// Before (6.x)
+catch (e) {
+  if (e instanceof ClientRequestError) Alerts.error(`Server ${e.status}`)
+  else if (e instanceof DOMException && e.name === 'AbortError') {
+    if (timedOut) Alerts.error('Timed out')
+    else { /* user cancelled */ }
+  } else if (e instanceof TypeError) Alerts.error('Network error')
+}
+
+// After (7.x) — throwing form
+catch (e) {
+  if (e instanceof ClientHttpError) Alerts.error(`Server ${e.status}`)
+  else if (e instanceof ClientTimeoutError) Alerts.error('Timed out')
+  else if (e instanceof ClientAbortError) { /* user cancelled */ }
+  else if (e instanceof ClientNetworkError) Alerts.error('Network error')
+}
+
+// After (7.x) — safe form (alternative)
+const r = await client.X.GetUser.safe(params)
+if (!r.ok) {
+  switch (r.kind) {
+    case 'http':     Alerts.error(`Server ${r.error.status}`); break
+    case 'timeout':  Alerts.error('Timed out'); break
+    case 'aborted':  break
+    case 'network':  Alerts.error('Network error'); break
+    case 'typed':    /* registry-dispatched typed error */; break
+    default:         throw r.error
+  }
+}
+```
+
+See `docs/client-error-handling.md` for the full guide including custom-kind augmentation and the `.safe()` retry-loop FAQ.
+
+---
+
+## v6.0.1 — DocRegistry constructor simplification
+
+### Changed
+
+- `DocRegistry` constructor now accepts `errors: ErrorTaxonomy | ErrorDoc[]` (polymorphic). Pass your taxonomy directly instead of converting it beforehand.
+- Framework error defaults are now auto-merged into every `DocRegistry` envelope (user entries override defaults via dedupe). Opt out via `includeDefaults: false`.
+- New fluent method `DocRegistry.prototype.documentError(...docs: ErrorDoc[])` for documenting errors not in the taxonomy (middleware-level, infrastructure, doc-only meta errors).
+
+### Removed
+
+- `DocRegistry.fromTaxonomy(taxonomy, config?)` — superseded by `new DocRegistry({ errors: taxonomy, ...config })`. The new form is strictly more capable (auto-defaults + dedupe applies to plain-constructor call sites too).
+- `taxonomyToErrorDocs` — still exists internally but marked `@internal` and no longer recommended as a public entry point. Pass your taxonomy directly to `DocRegistry`.
+
+### Migration
+
+```typescript
+// before (v6.0.0)
+DocRegistry.fromTaxonomy(appErrors, { basePath: '/api' })
+
+// after (v6.0.1)
+new DocRegistry({ errors: appErrors, basePath: '/api' })
+```
+
+If you were constructing `new DocRegistry({ errors: [myDoc] })` in v6.0.0 and relied on framework defaults NOT being auto-included, add `includeDefaults: false` to preserve v6.0.0 behavior.
+
+---
+
+## [6.0.0]
+
+This is a feature-heavy major release built around a comprehensive overhaul of error handling. Every HTTP builder gains a declarative error taxonomy, typed client-side error dispatch, a cross-cutting observability hook, and per-route error documentation. The familiar `onError` callback is now framed as a first-class peer of the taxonomy, not a legacy fallback.
+
+See the **Migration from 5.x** section at the end for the two breaking changes.
+
+### Added — Declarative error taxonomy (HTTP builders)
+
+`defineErrorTaxonomy({ ... })` registers error classes once with `statusCode`, optional `toResponse`, `onCatch`, and `schema`. Pass to any HTTP builder via the new `errors` option; `unknownError` catches anything not declared. Exported from every builder subpath and from the dedicated `ts-procedures/http-errors` subpath.
+
+- `src/implementations/http/error-taxonomy.ts` — `defineErrorTaxonomy`, `defaultErrorTaxonomy`, `resolveErrorResponse`, `taxonomyToErrorDocs`, `UnknownErrorConfig`, `ErrorTaxonomy`, `ErrorTaxonomyEntry`.
+- `HonoAPIAppBuilder`, `HonoRPCAppBuilder`, and `HonoStreamAppBuilder` (pre-stream) now accept `errors` and `unknownError`. Mid-stream errors continue to flow through `onMidStreamError`.
+- `defineErrorTaxonomy` topologically sorts `class:` entries so subclasses precede their base classes regardless of declared order; predicate (`match:`) entries retain declared order.
+- Response bodies auto-inject `{ name: <key> }` when `toResponse` returns an object without a `name`, guaranteeing wire-protocol consistency.
+
+### Added — Per-route error declarations + `DocRegistry.fromTaxonomy`
+
+- `APIConfig<TErrorKey extends string = string>` and `RPCConfig<TErrorKey extends string = string>` gained an optional `errors?: TErrorKey[]` field. Narrow to a taxonomy via `APIConfig<keyof typeof appErrors & string>` for compile-time typo protection.
+- `APIHttpRouteDoc`, `RPCHttpRouteDoc`, and `StreamHttpRouteDoc` carry `errors?: string[]`. Each builder's `buildXxxRouteDoc` method copies `config.errors` onto the route doc.
+- `DocRegistry.fromTaxonomy(taxonomy, config?)` convenience constructor seeds envelope errors from a taxonomy plus framework defaults (deduped — user entries win when keys overlap).
+- `DocRegistry.defaultErrors()` now derives from `defaultErrorTaxonomy` via `taxonomyToErrorDocs` — single source of truth for runtime and documented shapes.
+
+### Added — Client-side runtime error classes + registry dispatch
+
+- `emit-errors.ts` now emits real runtime classes (not just types) extending a shared `${ServiceName}ProcedureError<TBody>` base, each with a static `fromResponse(body, meta)` factory. `${ServiceName}ErrorRegistry` maps `body.name` to class for runtime dispatch. `${ServiceName}ProcedureErrorUnion` remains as a typed union.
+- `emit-scope.ts` emits per-route `Errors` type unions inside each route's namespace when `route.errors` is declared, derived from the generated classes.
+- `emit-index.ts` emits a new `create${ServiceName}Client(config)` convenience factory alongside `create${ServiceName}Bindings(client)`. The convenience form calls `createClient` with the error registry pre-wired so non-2xx responses arrive as typed class instances.
+- `src/client/error-dispatch.ts` exports `dispatchTypedError(registry, body, meta)` — pure dispatch helper consumed by `executeCall` and `executeStream`. Falls back to `ClientRequestError` when no registry is configured or `body.name` doesn't match.
+- `CreateClientConfig.errorRegistry` and new client types `ErrorRegistry`, `ErrorFactory`, `ErrorResponseMeta` (from `ts-procedures/client`).
+- `AdapterStreamResponse.errorBody?` surfaces the parsed JSON body on non-2xx stream responses so pre-stream errors dispatch through the same registry as regular calls. The fetch adapter populates it automatically.
+- Self-contained codegen (`selfContained: true`, the default) bundles `error-dispatch.ts` into `_client.ts`; `emit-index.ts` threads a separate `clientRuntimeImportPath` so the runtime `createClient` value import points at `./_client` while type imports stay at `./_types`.
+
+### Added — `onRequestError` observer hook on all HTTP builders
+
+Fires for every caught error, **before** dispatch (taxonomy / `onError` / hard default). Awaited. Cannot mutate the response — it's an observer for cross-cutting logging, tracing, and metrics (Sentry, Datadog, OpenTelemetry). Errors thrown inside the observer are swallowed and logged to `console.error` so a broken instrumentation hook cannot disrupt the primary flow.
+
+```typescript
+new HonoAPIAppBuilder({
+  errors: appErrors,
+  onRequestError: async ({ err, procedure, raw }) => {
+    sentry.captureException(err, { tags: { procedure: procedure.name } })
+  },
+})
+```
+
+Each builder exports an `OnRequestErrorContext` type with framework-specific typing for `raw` (Hono `Context`).
+
+### Changed — `onError` is a first-class peer, not legacy
+
+Every HTTP builder supports two peer error-handling modes — **declarative** (`errors` taxonomy + `unknownError`) and **imperative** (`onError` callback). Neither is deprecated. The reframe touches JSDoc, all `*.md` docs, and the `scripts/check-docs-consistency.sh` guard; no runtime behavior change from the reframe alone.
+
+Dispatch order inside each catch block: `onRequestError` → `errors` taxonomy → `onError` → hard default.
+
+### Changed — generated client output shape
+
+- `_errors.ts` emits runtime classes + registry instead of type-only declarations. The `${ServiceName}ProcedureErrorUnion` export remains; its members are now class instances rather than interfaces.
+- `DocRegistry.defaultErrors()` returns entries in topologically-sorted order (subclasses first). Code that depended on positional indexing must key by name instead.
+- Generated `index.ts` imports `createClient` as a runtime value (not `import type`) when the envelope contains errors, so the registry can be wired into `create${ServiceName}Client`.
+
+### Migration from 5.x
+
+Two breaking changes. Both have straightforward mitigations.
+
+**1. `HonoStreamAppBuilder.onPreStreamError` renamed to `onError`**
+
+For consistency with the other three HTTP builders. Signature unchanged.
+
+```ts
+// Before (5.x)
+new HonoStreamAppBuilder({
+  onPreStreamError: (proc, c, err) => c.json({ error: err.message }, 400),
+})
+
+// After (6.0)
+new HonoStreamAppBuilder({
+  onError: (proc, c, err) => c.json({ error: err.message }, 400),
+})
+```
+
+**2. `HonoStreamAppBuilder` hard-default status for `ProcedureValidationError` changed from 400 to 500**
+
+Previously, if no `errors` / `onError` was configured and a handler validation failed, hono-stream returned status **400**. All other builders returned **500** in the equivalent no-config case. v6 drops that special case — the hard default is now a flat 500 across all four builders.
+
+Pick one migration path:
+
+```ts
+// Option A — configure the taxonomy (empty object engages framework defaults,
+// which includes ProcedureValidationError → 400).
+new HonoStreamAppBuilder({ errors: {} })
+
+// Option B — handle in onError and pick your own status.
+new HonoStreamAppBuilder({
+  onError: (_p, c, err) =>
+    err instanceof ProcedureValidationError
+      ? c.json({ error: err.message }, 400)
+      : c.json({ error: err.message }, 500),
+})
+
+// Option C — accept the new 500 default.
+```
+
+**Other changes are additive:**
+
+- The error taxonomy, per-route errors, client runtime error classes, and `onRequestError` observer are all optional. Code that doesn't opt in continues to work.
+- `APIConfig` / `RPCConfig` default their `TErrorKey` generic to `string`, so `Procedures<Ctx, APIConfig>()` still works without the generic argument.
+- `createClient` without `errorRegistry` throws `ClientRequestError` as before.
+
+---
+
+## Earlier versions
+
+Release history prior to v6 is available in the Git log — each release is tagged as a commit with the version number (for example, commit `5.16.0`).