ts-procedures 8.6.0 → 9.1.0

package/docs/migration-v8-to-v9.md

@@ -0,0 +1,200 @@
+# Migrating from v8 to v9
+
+v9 is a ground-up restructuring of the library with one iron-clad guarantee:
+**generated codegen output is byte-identical to v8.6.0** (TypeScript, Kotlin,
+and Swift targets, every mode). If you consume a generated client, regenerating
+with v9 produces the same files — nothing to migrate on the consumer side.
+
+The flip side of that guarantee: known v8 codegen issues carried over into
+9.0.0 unchanged — output couldn't change, so neither could the bugs. Fixes
+resume in 9.x releases when they can land without breaking parity for output
+that compiles today. First such fix: routes that declare `errors` but no
+req/res schema now emit a namespace housing their `Errors` union instead of a
+dangling type reference (the old output never typechecked, so no working
+consumer's bytes change).
+
+Server-side and tooling APIs have breaking changes, listed exhaustively below.
+
+## TL;DR checklist
+
+| v8 | v9 |
+|---|---|
+| `Procedures({ config: { noRuntimeValidation: true } })` | `Procedures({ validation: false })` |
+| Suretype schemas | Removed — use TypeBox (or a custom `SchemaAdapter`) |
+| `import { HonoAppBuilder } from 'ts-procedures/hono'` | unchanged |
+| `TStreamProcedureRegistration.isStream` | Removed — branch on `kind: 'rpc-stream'` |
+| Duplicate-name registration threw `Error` | Throws `ProcedureRegistrationError` (same message) |
+| `TSchemaLib<T>` | Still exported; `Infer<T>` is the new primary name |
+| `extractJsonSchema(schema)` | `extractJsonSchema(schema, adapters)` — or just use the factory |
+| `schemaParser(...)` | Removed — `computeSchema(name, schema, { adapters, compile })` |
+| `isSuretypeSchema` | Removed |
+| `ts-procedures/http` types (`RPCConfig`, `APIConfig`, doc shapes) | unchanged (moved internally to `server/types`, same subpath) |
+| `dispatchPreStreamError` returned a Hono `Response` | Returns `{ type: 'body', statusCode, body }` \| `{ type: 'response', response }` — adapters translate |
+| — | New: `ts-procedures/server` subpath (transport-agnostic adapter toolkit) |
+
+## Core factory
+
+### `Procedures()` options
+
+The v8 `builder` argument (`{ config, onCreate }`) is replaced by a flat
+options bag:
+
+```ts
+// v8
+const { Create } = Procedures<Ctx>({ config: { noRuntimeValidation: true }, onCreate })
+
+// v9
+const { Create } = Procedures<Ctx>({
+  validation: false,        // replaces noRuntimeValidation: true
+  onCreate,                 // unchanged signature
+})
+```
+
+New options (no v8 equivalent):
+
+```ts
+Procedures<Ctx>({
+  // Customize AJV (options merged over the defaults, or pass an Ajv instance)
+  validation: { ajv: { coerceTypes: false } },
+
+  // Plug in another schema library (TypeBox remains built-in)
+  schema: { adapters: [myZodAdapter] },
+
+  // Factory-level defaults for CreateHttp / CreateHttpStream
+  http: { pathPrefix: '/v1', scope: 'billing' },
+})
+```
+
+`validation: false` keeps v8's `noRuntimeValidation` semantics exactly:
+schemas and validators are still computed at registration (bad schemas fail
+fast); only the per-call validation runs are skipped. The per-call
+`ctx.isPrevalidated` escape hatch is unchanged.
+
+### Suretype removed
+
+Suretype support (deprecated through v8) is gone: no `isSuretypeSchema`, no
+Suretype branch in type inference. Migrate schemas to TypeBox
+(`import { Type } from 'typebox'`). If you must keep another schema library,
+implement the new `SchemaAdapter` interface:
+
+```ts
+import type { SchemaAdapter } from 'ts-procedures'
+
+const zodAdapter: SchemaAdapter = {
+  name: 'zod',
+  detect: (s) => s instanceof z.ZodType,
+  toJsonSchema: (s) => z.toJSONSchema(s as z.ZodType),
+}
+```
+
+Note: compile-time inference (`Infer<T>`) is built in only for TypeBox; custom
+adapters get runtime validation + docs.
+
+### Stream registrations
+
+`isStream: true` is removed from `TStreamProcedureRegistration` and from
+`CreateStream(...).info`. Branch on the `kind` discriminant
+(`'rpc' | 'rpc-stream' | 'http' | 'http-stream'`), which exists since v8 —
+and which every creator's `info` now also carries (v8 only put it on
+`CreateHttpStream`'s info).
+
+### Duplicate names
+
+Registering the same name twice now throws `ProcedureRegistrationError`
+instead of a bare `Error`. The message is unchanged
+(`Procedure with name <name> is already registered`), so message-based
+assertions keep passing; `instanceof Error` also still holds.
+
+### Error classes
+
+Same four classes, same constructor signatures, same `instanceof` hierarchy.
+New: every framework error carries a `kind` field
+(`'procedure' | 'validation' | 'yield-validation' | 'registration'`) as an
+alternative to `instanceof`.
+
+## Schema utilities (low-level)
+
+Most users never call these directly; the factory does.
+
+- `schemaParser` is gone. Its behavior lives in
+  `computeSchema(name, schema, { adapters, compile, definitionInfo? })`, which
+  throws `ProcedureRegistrationError` instead of taking an `onParseError`
+  callback.
+- `extractJsonSchema(schema, adapters)` now takes the adapter list explicitly
+  (e.g. `[typeboxAdapter]`).
+- AJV is no longer a module-level singleton. `createValidatorCompiler()`
+  builds a per-factory compiler; defaults (`allErrors`, `coerceTypes`,
+  `removeAdditional`, ajv-formats) are unchanged.
+
+## HTTP server layer
+
+### Same surface, new home
+
+`HonoAppBuilder` keeps its v8 public surface verbatim: constructor config
+stratification (`rpc.*`, `api.*`, `stream.*`, `errors`, `unknownError`,
+`onError`, `onRequestError`, `onRequestStart/End`, `pathPrefix`, `app`),
+`register()`, lazy `docs`, `build()`, `toDocEnvelope()`, `skippedProcedures`,
+static `makeRoutePath`, and the `sse()` helper re-export. Wire behavior
+(routes, status codes, SSE events, error bodies) is unchanged — verified by an
+envelope-parity test against a captured v8 envelope and by the ported v8 test
+suite.
+
+The machinery behind it moved into the new transport-agnostic
+`ts-procedures/server` subpath: route-doc builders, error taxonomy + dispatch,
+request channel extraction, SSE metadata, path resolution, `DocRegistry`,
+`writeDocEnvelope`. The `ts-procedures/http-docs`, `ts-procedures/http-errors`,
+and `ts-procedures/http` subpaths re-export the same names as v8.
+
+### Writing your own adapter (new capability)
+
+v8's dispatch produced Hono `Response` objects; v9's is data-in/data-out:
+
+```ts
+import {
+  dispatchPreStreamError, // → { type: 'body', statusCode, body } | { type: 'response', response }
+  dispatchMidStreamError, // → { data, sseEvent?, runOnCatch? }
+  extractReqChannels,     // RequestSource → declared schema.req channels
+  resolveFactoryContext,
+  buildRpcRouteDoc,       // + buildHttpRouteDoc / buildStreamRouteDoc / buildHttpStreamRouteDoc
+} from 'ts-procedures/server'
+```
+
+A Fastify/Express adapter is now ~4 thin handlers translating between the
+framework's request/response/streaming primitives and these helpers — use
+`src/adapters/hono/` as the blueprint. Only the taxonomy callbacks' `raw`
+parameter is typed `unknown` at the server layer (it is your framework's
+request context; cast in your adapter).
+
+### SSE wire normalization (behavior fix)
+
+`rpc-stream` and `http-stream` routes now share one SSE sequencer, which
+removed two v8 inconsistencies: `sse(data, { event, id, retry })` metadata is
+now honored on `http-stream` yields and error events (v8 silently ignored it
+there), and a `null` yield serializes as empty SSE data on both route kinds
+(v8's `http-stream` sent the string `null`). Yield/return/error event names,
+id sequencing, and the `event: 'return'` envelope are unchanged.
+
+### Astro adapter
+
+Unchanged (`createAstroHandler`, `getAstroContext` from `ts-procedures/astro`).
+
+## Client runtime and codegen
+
+- `ts-procedures/client`: identical to v8.6.0 — the runtime files are
+  content-frozen because self-contained codegen bundles them verbatim.
+- `ts-procedures/codegen` + `npx ts-procedures-codegen`: same options, flags,
+  config file, watch mode, orphan pruning. Output is byte-identical to v8.6.0
+  except the version stamp in the generated header comment.
+
+## New in v9 (non-breaking)
+
+- `Procedures({ http: { pathPrefix, scope } })` — factory-level defaults that
+  remove per-route boilerplate on `CreateHttp` / `CreateHttpStream`. The
+  prefix becomes part of the route's identity (it shows up in `config.path`
+  and route docs), unlike the builder-level `pathPrefix`, which is a
+  deployment mount point.
+- `Procedures({ validation: { ajv } })` — per-factory AJV configuration.
+- `Procedures({ schema: { adapters } })` — pluggable schema libraries.
+- `ts-procedures/server` — the adapter toolkit described above.
+- `Infer<T>` as the primary inference type (alias `TSchemaLib` retained).
+- `ProcedureError.kind` discriminant.

package/docs/plans/2026-06-09-v9-rewrite.md

@@ -0,0 +1,130 @@
+# ts-procedures v9 Rewrite — Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Build `v9/` — a self-contained next-major `ts-procedures` package with redesigned core/schema/server layers and byte-identical codegen output, verified by goldens captured from the v8 build.
+
+**Architecture:** Golden-anchored rewrite (spec: `v9/docs/specs/2026-06-09-v9-rewrite-design.md`). Output-producing layers (codegen emitters, bundled client runtime, DocEnvelope shape) are ported content-faithfully; core/schema/server are redesigned for DX and pluggability.
+
+**Tech Stack:** TypeScript (ES2024, NodeNext, tsc build), vitest, AJV + ajv-formats, TypeBox, Hono (peer), ajsc ^7.3.0 (optional).
+
+**Port convention:** Tasks marked **PORT** copy the named v8 file(s) under `src/…` into the v9 path, adjusting only import paths and (where stated) renames. Tasks marked **PORT-VERBATIM** must be byte-identical copies. Tasks marked **NEW** are TDD'd from the signatures given. Every task ends with `npx vitest run <file>` green and a commit.
+
+---
+
+## Phase 0 — Scaffold, baseline capture, client freeze
+
+### Task 0.1: Package scaffold
+**Files:** Create `v9/package.json`, `v9/tsconfig.json`, `v9/vitest.config.ts`, `v9/eslint.config.js`, `v9/.gitignore` (`build/`, `node_modules/`).
+- [ ] `package.json`: name `ts-procedures`, version `9.0.0`, `type: module`, same exports-map subpaths as v8 root `package.json:21-53` but pointing at v9 layout (`./hono` → `build/adapters/hono/index.js`, `./astro` → `build/adapters/astro/index.js`, `./http` → types-only `build/server/types.d.ts`, `./http-docs` → `build/server/doc-registry.js`, `./http-errors` → `build/server/errors/taxonomy.js`, `./client` → `build/client/index.js`, `./codegen` → `build/codegen/index.js`, plus new `./server` → `build/server/index.js`); bin `ts-procedures-codegen` → `build/codegen/bin/cli.js`; deps copied from root (ajv, ajv-formats, typebox; peer hono; optional ajsc ^7.3.0).
+- [ ] `tsconfig.json` / `vitest.config.ts` / `eslint.config.js`: mirror root configs (rootDir `src`, outDir `build`).
+- [ ] Verify root test runner does NOT pick up `v9/` (`cat vitest.config.ts` at root; if its include would match `v9/**`, add `v9/**` to root exclude — the only permitted root touch, justified by isolation).
+- [ ] `cd v9 && npm install` succeeds. Commit: `chore(v9): package scaffold`.
+
+### Task 0.2: Client runtime freeze (PORT-VERBATIM)
+**Files:** Copy all of root `src/client/*.ts` (10 runtime files + tests) → `v9/src/client/`.
+- [ ] Copy files byte-identically (runtime files MUST not change — they are bundled into generated `_client.ts`/`_types.ts`).
+- [ ] Create `v9/src/client/freeze.test.ts`: hashes the 10 runtime files (`errors.ts, classify-error.ts, error-dispatch.ts, request-builder.ts, resolve-options.ts, hooks.ts, call.ts, stream.ts, fetch-adapter.ts, index.ts, types.ts`) and compares to recorded v8 sha256 values, with a message explaining the bundling contract.
+- [ ] `npx vitest run src/client` green (ported client tests + freeze test). Commit.
+
+### Task 0.3: Fixture envelopes
+**Files:** Copy root `src/codegen/__fixtures__/users-envelope.json` → `v9/src/codegen/__fixtures__/`; Create `v9/src/codegen/__fixtures__/models-envelope.json`.
+- [ ] `models-envelope.json`: hand-authored DocEnvelope (same shape) with ≥2 scopes, `$id`-bearing shared models used across scopes (to exercise `_models.ts`, `x-named-type` referencing, collision-free naming), route-level `errors`, an `http-stream` route, and ErrorDocs with schemas.
+- [ ] Validate it loads through the **v8** pipeline: `node` one-liner calling root `build/codegen` `generateClient({ envelope, outDir, dryRun: true })` without error. Commit.
+
+### Task 0.4: Golden baseline capture from v8
+**Files:** Create `v9/tools/capture-goldens.mjs`; output `v9/src/codegen/__goldens__/<case>/…`.
+- [ ] Run `npm run build` at root (produces `build/codegen`).
+- [ ] Script imports root `../build/codegen/index.js` and runs the 7-case matrix from the spec §2 (ts-default / ts-flat / ts-external-runtime / ts-no-share-models / ts-shared-models-module / kotlin-default / swift-default) over BOTH fixture envelopes (kotlin/swift only need users-envelope), writing every generated file under `__goldens__/<case>-<envelope>/`.
+- [ ] Commit captured goldens: `test(v9): capture v8.6.0 codegen golden baselines`.
+
+### Task 0.5: Golden test harness
+**Files:** Create `v9/src/codegen/goldens.test.ts`, `v9/src/codegen/test-helpers/golden.ts` (PORT root `src/codegen/test-helpers/golden.ts`, extended).
+- [ ] Harness normalizes two placeholders before byte-compare: envelope-hash comment line and the version inside `CODEGEN_HEADER`.
+- [ ] `goldens.test.ts` iterates the matrix, calls v9 `generateClient` (not yet existing) and compares each file. Mark the whole suite `describe.todo`/skipped until Phase 5 starts, then it becomes the acceptance gate. Commit.
+
+## Phase 1 — Core (NEW, TDD)
+
+### Task 1.1: Errors + definition site
+**Files:** Create `v9/src/core/errors.ts`, `v9/src/core/definition-site.ts` (PORT root `src/stack-utils.ts` logic), tests alongside.
+- [ ] Keep four classes (`ProcedureError`, `ProcedureValidationError`, `ProcedureYieldValidationError`, `ProcedureRegistrationError`) with a shared base carrying `kind`, `procedureName`, `meta`, `definedAt`; definition-stack enrichment preserved. Port/adapt root `src/errors.test.ts` + `src/stack-utils.test.ts`.
+
+### Task 1.2: Schema layer
+**Files:** Create `v9/src/schema/adapter.ts`, `typebox.ts`, `compile.ts`, `compute-schema.ts`, `types.ts`, tests.
+- [ ] `adapter.ts`:
+  ```ts
+  export interface SchemaAdapter {
+    name: string
+    detect(schema: unknown): boolean
+    toJsonSchema(schema: unknown): TJSONSchema
+  }
+  ```
+- [ ] `typebox.ts`: detection via `~kind` / `Symbol.for('TypeBox.Kind')` (port from root `src/schema/resolve-schema-lib.ts`); Suretype removed.
+- [ ] `compile.ts`: `createValidatorCompiler(options?: { ajv?: Ajv | AjvOptions })` returning `compile(jsonSchema): (value) => { errors?: TSchemaValidationError[] }`; default AJV opts `allErrors+coerceTypes+removeAdditional` + ajv-formats (parity with root `src/schema/parser.ts:25-31`).
+- [ ] `compute-schema.ts`: PORT semantics of root `src/schema/compute-schema.ts` + `parser.ts` channel handling (params XOR req, req channels pathParams/query/body/headers, res doc-only, yieldType) on top of the adapter + compiler. Port/adapt the four root schema test files (drop Suretype cases).
+
+### Task 1.3: Procedures factory + four creators
+**Files:** Create `v9/src/core/procedures.ts`, `create.ts`, `create-stream.ts`, `create-http.ts`, `create-http-stream.ts`, `context.ts`, `types.ts`, tests.
+- [ ] Factory options per spec §5: `{ onCreate?, validation?: false | { ajv? }, schema?: { adapter? }, http?: { pathPrefix?, scope? } }`.
+- [ ] Behavior parity targets: dual return `{ [name], procedure, info }`; registration objects with `kind` discriminants identical to root `src/types.ts:30-133` (the hono layer + envelope depend on these); `ctx.error()`/`ctx.signal`/`isPrevalidated`; stream `validateYields`; CreateHttp path-param cross-check; duplicate-name `ProcedureRegistrationError`; `getProcedures()/getProcedure/removeProcedure/clear`.
+- [ ] `http` factory defaults merge UNDER per-route config (route wins); `scope` default applies only when route omits it.
+- [ ] Port/adapt root tests: `create.test.ts`, `create-stream.test.ts`, `create-http.test.ts`, `create-http-stream.test.ts`, `index.test.ts`, `migration.test.ts` (update for renamed options); NEW tests for `validation: false`, custom `SchemaAdapter`, `http` defaults.
+
+## Phase 2 — Server layer (NEW seam, PORTed semantics)
+
+### Task 2.1: Frozen doc types + route-doc builders
+**Files:** Create `v9/src/server/types.ts` (PORT root `src/implementations/types.ts`), `v9/src/server/docs/{rpc,http,stream,http-stream}-doc.ts` (PORT root `src/implementations/http/hono/docs/*`), tests.
+- [ ] Shapes unchanged (spec §2 corollary). SSE yieldType envelope wrapping preserved exactly (root `stream-doc.ts:20-30`).
+
+### Task 2.2: Error taxonomy + dispatch
+**Files:** Create `v9/src/server/errors/taxonomy.ts` (PORT root `src/implementations/http/error-taxonomy.ts`), `v9/src/server/errors/dispatch.ts` (PORT root `error-dispatch.ts`), tests (PORT `error-taxonomy.test.ts`, `on-request-error.test.ts` relevant parts).
+
+### Task 2.3: Request helpers, SSE, paths, DocRegistry
+**Files:** Create `v9/src/server/request/params.ts` + `query.ts` (de-duplicate root `hono/handlers/http.ts:18-66` / `http-stream.ts:11-59` copies into one), `v9/src/server/sse.ts` (`sse()`/`getSSEMeta` + a shared `writeSseSequence` iteration helper extracted from root `stream.ts:117-141` / `http-stream.ts:105-114`), `v9/src/server/paths.ts` (PORT root `hono/path.ts`), `v9/src/server/doc-registry.ts` (PORT root `doc-registry.ts`), `v9/src/server/doc-envelope.ts` (PORT root `src/doc-envelope.ts`), `v9/src/server/index.ts` barrel, tests (PORT `doc-registry.test.ts`, `doc-envelope.test.ts`; NEW for params/query/sse helpers).
+- [ ] No Hono imports anywhere under `server/` (enforced by a lint-style test grepping imports).
+
+## Phase 3 — Adapters
+
+### Task 3.1: Hono builder
+**Files:** Create `v9/src/adapters/hono/index.ts`, `types.ts`, `handlers/{rpc,http,stream,http-stream}.ts` — thin glue over `server/*`; tests PORTed from root `src/implementations/http/hono/**/*.test.ts` + `route-errors.test.ts`.
+- [ ] Public surface parity: constructor config stratification, `register()`, lazy `docs`, `build()`, `toDocEnvelope()`, `makeRoutePath`, `sse` re-export.
+- [ ] **Envelope parity test:** same factory set built via v9 builder produces `toDocEnvelope()` deep-equal to a captured v8 envelope (generate the v8 envelope with a small script against root build, commit as fixture).
+
+### Task 3.2: Astro adapter (PORT)
+**Files:** `v9/src/adapters/astro/*` from root `src/implementations/http/astro/*` + its test.
+
+## Phase 4 — Codegen (PORT with internal split; goldens are the gate)
+
+### Task 4.1: Foundation modules (PORT)
+**Files:** `v9/src/codegen/`: `constants.ts`, `naming.ts`, `schema-walk.ts`, `resolve-envelope.ts`, `group-routes.ts`, `collect-models.ts`, `model-refs.ts`, `emit-types.ts`, `targets/_shared/*` — each with its root test file.
+
+### Task 4.2: emit split (PORT emit-scope.ts → `emit/`)
+**Files:** `v9/src/codegen/emit/scope-file.ts`, `rpc-route.ts`, `api-route.ts`, `stream-route.ts`, `http-stream-route.ts`, `format-types.ts`, `declarations.ts`.
+- [ ] Move code verbatim by responsibility; every emitted string literal unchanged. Port `emit-scope.test.ts` against the new module boundaries.
+
+### Task 4.3: Remaining emitters + targets (PORT)
+**Files:** `emit-models.ts`, `emit-errors.ts`, `emit-index.ts`, `emit-client-types.ts`, `emit-client-runtime.ts` (reads `v9/src/client/*.ts` — frozen in Task 0.2), `targets/ts/run.ts`, `targets/kotlin/*`, `targets/swift/*`, `pipeline.ts`, `index.ts` — each with root tests (incl. kotlin/swift integration goldens + `e2e.test.ts`).
+
+### Task 4.4: Goldens green (acceptance gate)
+- [ ] Unskip Task 0.5 suite; `npx vitest run src/codegen/goldens.test.ts` → every file in every case byte-identical. Fix v9 until green. Commit: `test(v9): golden parity with v8.6.0 codegen output`.
+
+### Task 4.5: CLI (PORT + FLAG_SPECS unification)
+**Files:** `v9/src/codegen/bin/flag-specs.ts` (PORT, extended with per-flag `takesValue`/`configKey`), `v9/src/codegen/bin/cli.ts` (parseArgs driven by FLAG_SPECS; behavior identical — strict unknown-flag error, did-you-mean, `--help`, config file, watch mode), tests PORT `cli.test.ts` + `flag-specs.test.ts`.
+
+## Phase 5 — Finishing
+
+### Task 5.1: Root barrel + build
+**Files:** `v9/src/exports.ts` (mirror root `src/exports.ts` minus Suretype, plus new server exports). `cd v9 && npm run build` clean; `npm run lint` clean.
+
+### Task 5.2: Docs
+**Files:** `v9/README.md` (full library README: quickstart, four kinds, hono builder, error taxonomy, client, codegen), `v9/docs/migration-v8-to-v9.md` (every breaking change with before/after).
+
+### Task 5.3: Full verification
+- [ ] `cd v9 && npx vitest run` — all green; `npm run build`; goldens re-verified; final commit.
+
+---
+
+## Self-review notes
+- Spec coverage: §2→Tasks 0.3-0.5/4.4; §5→1.1-1.3; §6→2.1-2.3/3.1; §7→4.1-4.5; §8 woven through; §9 exclusions respected (no client changes beyond verbatim port, no agent_config).
+- Port tasks intentionally reference v8 source files as the code source of truth instead of inlining thousands of lines.
+- Type consistency: registration/doc/descriptor shapes pinned to root `src/types.ts` / `src/implementations/types.ts` / client `types.ts` by the freeze decisions.

package/docs/specs/2026-06-09-v9-rewrite-design.md

@@ -0,0 +1,221 @@
+# ts-procedures v9 — Ground-Up Rewrite Design
+
+**Date:** 2026-06-09
+**Status:** Approved for implementation (autonomous /goal directive; final review with user at the end)
+**Location:** `v9/` — a self-contained package directory inside the repo, fully separate from the root v8 project.
+
+## 1. Goal
+
+Build the next major version (9.0.0) of `ts-procedures` as a brand-new package in `v9/`, with its own
+`package.json`, free to break any API — **except generated codegen output, which must remain exactly what
+v8.6.0 emits today** (TS, Kotlin, Swift; all mode combinations). Downstream apps depend on that polished output.
+
+Quality bar: most readable, well-structured, best-DX, extendable, configurable, pluggable version of the
+library possible.
+
+## 2. The one hard constraint, made executable
+
+"Codegen output that currently exists" becomes a byte-level golden contract:
+
+1. **Capture baselines from v8 first.** A capture script runs the *current root build's* codegen
+   (`../build/codegen`) against fixture envelopes and writes every generated file to
+   `v9/src/codegen/__goldens__/<case>/`.
+2. **Golden matrix** (each case = full output dir):
+   - `ts-default` — namespace mode, selfContained, shareModels, jsdoc (all defaults)
+   - `ts-flat` — `namespaceTypes: false`
+   - `ts-external-runtime` — `selfContained: false`
+   - `ts-no-share-models` — `shareModels: false`
+   - `ts-shared-models-module` — `sharedModelsModule` convention path
+   - `kotlin-default` — kotlinx serializer
+   - `swift-default` — codable serializer
+3. **Fixture envelopes:** the existing `users-envelope.json` plus a richer `models-envelope.json`
+   (adds `$id`-bearing shared models across scopes, route-level `errors`, http-stream routes) so the
+   shareModels/`_models.ts` paths are pinned too.
+4. **Golden test harness** in v9 compares v9 output byte-for-byte against the captured baselines, splicing
+   two placeholders: the envelope hash comment (already supported by v8's golden helper) and the package
+   version in `CODEGEN_HEADER` (v9 emits `9.x`; everything else must match exactly).
+5. These tests are written **before** any v9 codegen code and stay red until the port is faithful.
+
+Two corollaries that fall out of the constraint:
+
+- **Bundled client runtime is content-frozen.** Self-contained mode concatenates `src/client/*.ts`
+  verbatim (imports stripped) into `_client.ts`/`_types.ts`. Therefore v9's `src/client/` keeps the same
+  ten files with byte-identical content. Client improvements are out of scope for 9.0 and gated on a
+  future bundler change.
+- **DocEnvelope JSON shape is frozen.** It is codegen's input. Server-side APIs may change freely as long
+  as `toDocEnvelope()` emits the same shapes (`kind` discriminants, `jsonSchema` channel layout, SSE
+  envelope wrapping, `fullPath`, `errors: string[]`, ErrorDoc/HeaderDoc).
+
+## 3. What changes vs. what is preserved
+
+| Area | v9 disposition |
+|---|---|
+| Codegen emitted output | **Frozen** (golden-verified) |
+| Codegen internals | Restructured: `emit-scope.ts` (1049 LOC) split into per-kind emitters + shared formatting modules; CLI parsing derived from `FLAG_SPECS` instead of a parallel hand-written switch |
+| Client runtime (`src/client/`) | **Frozen content** (bundling), ported verbatim |
+| DocEnvelope shape | **Frozen** |
+| Core factory / Create* API | Redesigned for DX (see §5) |
+| Schema layer | Pluggable adapters; **Suretype dropped**; AJV configurable |
+| HTTP server layer | Split into transport-agnostic `server/` + thin framework adapters (`hono/`, `astro/`) |
+| Error taxonomy | Kept (it's good); relocated to `server/errors/`; same semantics |
+| Subpath exports | Same names kept (`.`/`./hono`/`./astro`/`./http`/`./http-docs`/`./http-errors`/`./client`/`./codegen`), plus new `./server` |
+| agent_config | Out of scope for the v9 directory (release-time copy; root owns it today) |
+
+## 4. Package layout
+
+```
+v9/
+├── package.json            # name: ts-procedures, version: 9.0.0, type: module
+├── tsconfig.json           # ES2024, NodeNext, strict — mirrors root
+├── vitest.config.ts
+├── eslint.config.js
+├── docs/
+│   └── specs/2026-06-09-v9-rewrite-design.md   (this file)
+├── tools/
+│   └── capture-goldens.mjs # runs root v8 build's codegen → __goldens__
+└── src/
+    ├── exports.ts          # root barrel
+    ├── core/               # framework-agnostic procedure definitions
+    │   ├── procedures.ts   # Procedures() factory + registry
+    │   ├── create.ts / create-stream.ts / create-http.ts / create-http-stream.ts
+    │   ├── context.ts      # ctx.error(), signal contracts
+    │   ├── errors.ts       # ProcedureError family (4 classes, shared base)
+    │   ├── definition-site.ts  # stack-capture (was stack-utils.ts)
+    │   └── types.ts
+    ├── schema/
+    │   ├── adapter.ts      # SchemaAdapter interface (extract + infer hooks)
+    │   ├── typebox.ts      # built-in TypeBox adapter (auto-detected default)
+    │   ├── compile.ts      # AJV compilation, factory-configurable instance
+    │   └── compute-schema.ts
+    ├── server/             # transport-agnostic HTTP machinery (NEW seam)
+    │   ├── types.ts        # DocEnvelope, route docs (frozen shapes)
+    │   ├── docs/           # buildRpc/Api/Stream/HttpStream route docs
+    │   ├── doc-registry.ts
+    │   ├── doc-envelope.ts # writeDocEnvelope
+    │   ├── errors/
+    │   │   ├── taxonomy.ts # defineErrorTaxonomy, defaults, topo sort
+    │   │   └── dispatch.ts # pre-stream / mid-stream dispatch
+    │   ├── request/
+    │   │   ├── params.ts   # extractParams (pathParams/query/body/headers)
+    │   │   └── query.ts    # parseQueryNative + QueryParser type
+    │   ├── sse.ts          # sse() metadata, SSE event sequencing helper
+    │   └── paths.ts        # makeRoutePath, resolveFullPath
+    ├── adapters/
+    │   ├── hono/           # thin HonoAppBuilder over server/*
+    │   └── astro/          # port of the astro handler
+    ├── client/             # FROZEN content (ten files, verbatim from v8)
+    └── codegen/
+        ├── pipeline.ts, resolve-envelope.ts, group-routes.ts, ...
+        ├── emit/           # was emit-scope.ts — split:
+        │   ├── scope-file.ts        # orchestration (namespace/flat assembly)
+        │   ├── rpc-route.ts / api-route.ts / stream-route.ts / http-stream-route.ts
+        │   ├── format-types.ts      # formatTypes/formatSubNamespace/rename
+        │   └── declarations.ts      # DeclarationCollector
+        ├── targets/{_shared,ts,kotlin,swift}/
+        ├── bin/{cli.ts,flag-specs.ts}
+        ├── __fixtures__/   # users-envelope.json + models-envelope.json
+        └── __goldens__/    # captured v8 output (the contract)
+```
+
+Build = plain `tsc` to `build/`, ESM-only — same as v8 (it works and keeps publishing simple).
+Root `vitest.config.ts` excludes `v9/`; v9 has its own config (complete separation).
+
+## 5. Core API design
+
+The four kinds stay (`rpc`, `rpc-stream`, `http`, `http-stream`) and the dual-return shape stays — both
+are proven DX:
+
+```ts
+const { GetUser, procedure, info } = Create('GetUser', { schema: { params, returnType } }, handler)
+```
+
+Changes:
+
+1. **Single options bag for the factory** with named sub-configs replacing scattered flags:
+   ```ts
+   const { Create, CreateStream, CreateHttp, CreateHttpStream, getProcedures } =
+     Procedures<Ctx, Ext>({
+       onCreate?: (registration) => void,
+       validation?: false | { ajv?: AjvLike | AjvOptions },   // replaces noRuntimeValidation: true
+       schema?: { adapter?: SchemaAdapter },                  // pluggable; TypeBox auto-detected default
+       http?: { pathPrefix?: string, scope?: string },        // factory-level defaults for CreateHttp*
+     })
+   ```
+   `validation: false` reads better than `noRuntimeValidation: true`; AJV options/instance become
+   injectable instead of a hardcoded module singleton (default stays `allErrors + coerceTypes +
+   removeAdditional` for behavioral parity).
+2. **Factory-level HTTP defaults** (`http.pathPrefix`, `http.scope`) merge under each `CreateHttp` config —
+   addresses the documented per-route boilerplate pain without changing envelope output shape.
+3. **Error classes:** keep the four (`ProcedureError`, `ProcedureValidationError`,
+   `ProcedureYieldValidationError`, `ProcedureRegistrationError`) because taxonomy dispatch and docs key
+   off `instanceof` and class names; unify internals on one base with a `kind` field, keep definition-site
+   stack enrichment (genuinely good v8 feature).
+4. **Schema layer:** `SchemaAdapter = { detect(schema): boolean; toJsonSchema(schema): TJSONSchema }`.
+   TypeBox adapter ships built-in and is the default; Suretype is removed (deprecated since v8). The AJV
+   compile step lives in `schema/compile.ts` behind a small `Validator` type so a future non-AJV engine is
+   a config swap, not a rewrite.
+5. **Context contract unchanged** (`ctx.error()`, `ctx.signal?` on rpc/http, guaranteed `ctx.signal` on
+   streams, `isPrevalidated` escape hatch kept for builders).
+
+## 6. Server layer design
+
+The v8 hono directory mixes three concerns: framework binding, HTTP semantics, and doc generation. v9
+separates them:
+
+- **`server/`** is pure: no Hono imports. It owns param extraction, query parsing, success-status
+  defaults, SSE event sequencing (auto-incrementing ids, `event: 'return'` envelope, `sse()` metadata via
+  WeakMap), error taxonomy + pre/mid-stream dispatch, route-doc builders, DocRegistry, and path resolution.
+  This kills the v8 duplication (query/param extraction copy-pasted between http.ts and http-stream.ts;
+  near-identical SSE loops in stream.ts and http-stream.ts) once, in one place.
+- **`adapters/hono/`** keeps the v8 `HonoAppBuilder` surface users like — chainable `register()`,
+  stratified config (`rpc.*`, `api.*`, `stream.*`, cross-cutting `errors`/`unknownError`/`onError`/
+  `onRequestError`/`onRequestStart/End`), lazy `docs`, `build()`, `toDocEnvelope()` — but each handler is
+  ~20 lines of Hono-specific glue (read request, call server/* helpers, write response). Writing a
+  Fastify/Express adapter becomes a contained exercise against documented seams rather than a fork.
+- **Envelope parity test:** build the same factories through the v9 hono builder and assert deep-equality
+  of `toDocEnvelope()` against a captured v8 envelope for the same procedure set.
+
+## 7. Codegen design
+
+Port with internal restructuring, never output restructuring:
+
+1. Goldens first (see §2) — red until faithful.
+2. Modules port nearly as-is where already clean (`pipeline.ts`, `group-routes.ts`, `collect-models.ts`,
+   `model-refs.ts`, `emit-models.ts`, `emit-errors.ts`, `emit-index.ts`, `targets/*`).
+3. `emit-scope.ts` is split into `emit/` per-kind modules (§4 layout). Every emitted string literal moves
+   verbatim; only file boundaries and shared helpers change.
+4. `emit-client-runtime.ts` / `emit-client-types.ts` read v9's `src/client/*.ts` — identical content by
+   the freeze in §2 — so `_client.ts`/`_types.ts` match.
+5. CLI: `parseArgs` is generated from `FLAG_SPECS` (single source of truth; v8 had a hand-written switch
+   plus a parallel spec table that could drift). Flags, defaults, help text, error messages, and
+   did-you-mean behavior remain identical and are covered by ported CLI tests.
+6. `generateClient` options, config-file loading, watch mode, orphan pruning (`CODEGEN_SIGNATURE`
+   version-agnostic) all keep v8 semantics.
+
+## 8. Testing strategy
+
+- **Goldens** (§2) are the spine — they encode the only hard requirement.
+- **Envelope parity** test for the hono builder (§6).
+- **Ported unit tests:** v8's co-located tests move with each module (adapted imports/APIs). Target: the
+  full behavioral surface of core/schema/server/client/codegen covered; client tests port verbatim since
+  the runtime is verbatim.
+- **New tests** for new seams: SchemaAdapter plug-in, factory `validation`/`http` defaults, server/*
+  helpers in isolation.
+- TDD discipline for all newly designed code (core/schema/server); port-then-verify for frozen code.
+
+## 9. Out of scope for 9.0.0
+
+- Client runtime improvements (frozen by the bundling contract; revisit with an AST-based bundler in 9.x).
+- New codegen targets, new emit options.
+- agent_config refresh, README/marketing docs rewrite (a migration guide `docs/migration-v8-to-v9.md` IS
+  in scope).
+- Suretype support (removed), Express builder (the v9 seam makes it easy later, not built now).
+
+## 10. Risks
+
+| Risk | Mitigation |
+|---|---|
+| Hidden output drift in untested codegen paths | Two fixture envelopes × 7-case matrix; richer than v8's own coverage; e2e content tests also ported |
+| Client verbatim port silently diverges | A test hashes each of the ten client files against recorded v8 hashes |
+| Envelope drift from redesigned server layer | Deep-equality envelope parity test |
+| ajsc version behavior | Same dependency pin (`^7.3.0`), same dynamic-import pattern |

package/docs/streaming.md

@@ -109,6 +109,18 @@ for await (const item of CancellableStream({}, {})) {
 
 For the built-in Hono streaming integration, see [HTTP Integrations](./http-integrations.md). `HonoAppBuilder` dispatches `CreateStream` and `CreateHttpStream` procedures as SSE or text streams from the same `register()` call as your RPC and REST routes.
 
+Wrap a yield with the `sse()` helper to attach SSE metadata (`event:`, `id:`, `retry:` fields). The value is returned unchanged — metadata rides in a WeakMap, never on the payload:
+
+```typescript
+import { sse } from 'ts-procedures/hono'
+
+async function* (ctx, params) {
+  yield sse({ progress: 0.5 }, { event: 'progress', id: 'p-1' })
+}
+```
+
+SSE wire behavior is identical for `rpc-stream` (`CreateStream`) and `http-stream` (`CreateHttpStream`) routes — both are served by the same event sequencer. `sse()` metadata is honored on both kinds, and a `null` yield serializes as empty SSE data on both. (Through v8, `http-stream` routes ignored `sse()` metadata and wrote the string `null` for null yields; v9 normalized this.)
+
 ## Stream Errors
 
 Streaming procedures support the same error handling as regular procedures (see [Error Handling](./core.md#error-handling)).