ts-procedures 8.5.0 → 9.0.0

package/docs/http-integrations.md

@@ -4,13 +4,15 @@
 
 ts-procedures includes a built-in HTTP builder for Hono that handles routing, context resolution, lifecycle hooks, abort signals, and automatic route documentation. The builder reads procedures off the factory at registration time and mounts the matching routes when you call `build()`.
 
-For a full reference (config interfaces, path generation, context resolution, abort signal, lifecycle hooks, route documentation), see the [HTTP implementations overview](../src/implementations/http/README.md).
+The machinery behind the builder — route-doc builders, error taxonomy dispatch, request channel extraction, SSE semantics — lives in the transport-agnostic [`ts-procedures/server` subpath](#build-your-own-adapter--ts-proceduresserver), so adapters for other frameworks are thin glue.
 
 ## Integrations at a Glance
 
 | Integration | Export | Procedure kinds | Guide |
 |-------------|--------|-----------------|-------|
-| HonoAppBuilder | `ts-procedures/hono` | `rpc`, `rpc-stream`, `http`, `http-stream` | [HTTP implementations overview](../src/implementations/http/README.md) |
+| HonoAppBuilder | `ts-procedures/hono` | `rpc`, `rpc-stream`, `http`, `http-stream` | This page |
+| Astro (catch-all over Hono apps) | `ts-procedures/astro` | all four | [Astro adapter walkthrough](./astro-adapter.md) |
+| Build your own | `ts-procedures/server` | all four | [Build your own adapter](#build-your-own-adapter--ts-proceduresserver) |
 
 ## Hono
 
@@ -80,7 +82,32 @@ const app = new HonoAppBuilder({
 
 `HonoAppBuilder`'s config is **stratified** — kind-specific knobs (`onSuccess`, `queryParser`, `defaultStreamMode`, `onStreamStart`, `onStreamEnd`, `onMidStreamError`) live inside the matching `rpc:` / `api:` / `stream:` block. Cross-cutting hooks (`onRequestStart`, `onRequestEnd`, `onRequestError`, `errors`, `unknownError`, `onError`) stay at the top level.
 
-For the full surface — config interfaces, path generation, context resolution, abort signal, lifecycle hooks, route doc shapes — see the [HTTP implementations overview](../src/implementations/http/README.md).
+> **Two path prefixes, two meanings.** The builder's `pathPrefix` (above) is a deployment mount point — it does not appear in route docs' `path`. The factory-level `Procedures({ http: { pathPrefix } })` default, by contrast, is part of each route's **identity**: it is baked into `config.path` at registration time and shows up in route docs and generated clients. Use the factory default for API versioning (`/v1`), the builder prefix for where the app is mounted.
+
+### No-content (204) procedures
+
+Not every HTTP procedure returns a body. A logout, a delete, a "mark as read" — the success signal is the status code, not a payload. You author these by simply **omitting `schema.res`** and returning `undefined`. There's nothing to invent.
+
+```typescript
+procs.CreateHttp('Logout', {
+  path: '/session',
+  method: 'delete',
+  scope: 'auth',
+  successStatus: 204,
+  // no `schema.res` — there is no response body to describe
+}, async (ctx) => {
+  await revokeSession(ctx.sessionId)
+  return undefined            // handler return type is inferred as `void`
+})
+```
+
+What you get, end to end:
+
+- **A `Promise<void>` client method.** With no `schema.res`, `HttpReturn<TRes>` falls through to `void`, so codegen emits `client.bindCallable<…, void>` — `await client.auth.Logout(…)` resolves to `void`.
+- **No generated response model.** Codegen never emits a `LogoutResponse` type, because there's no `res` schema to derive one from.
+- **A clean 204 at runtime.** The Hono builder sends `c.body(null)` whenever `successStatus === 204` (or the handler returns `undefined`) — a genuinely bodyless response, not `c.json(undefined)` with a dangling `application/json` content-type.
+
+**Why:** the empty return shape is already a first-class, fully-typed citizen — don't model a `LogoutResponse: { success: boolean }` just to have something to return. Inventing a body forces a generated model, a non-`void` client signature, and a payload the caller must ignore; omitting `schema.res` is both less code and a more honest contract.
 
 ## Error Handling
 
@@ -175,7 +202,7 @@ procs.CreateHttp('GetUser', {
 
 These per-route declarations flow into the DocEnvelope and drive typed `catch` blocks on generated clients — see [Client & Codegen → Typed Error Handling](./client-and-codegen.md#typed-error-handling).
 
-**Tip:** if a factory exclusively contains HTTP procedures, prefer the factory-level generic form `Procedures<Ctx, APIConfig<keyof typeof appErrors & string>>()` — it bakes the typo-checked error keys into every route on that factory so individual `errors: [...] satisfies ErrorKey[]` annotations are no longer needed. The per-route `satisfies` form above is the right pick when a single factory mixes HTTP procedures with other config shapes.
+**Tip:** for RPC procedures (`Create` / `CreateStream`), whose `scope`/`version`/`errors` config comes from the factory's `TExtendedConfig`, you can bake the typo-checked keys into the whole factory with `Procedures<Ctx, RPCConfig<keyof typeof appErrors & string>>()` — individual `satisfies ErrorKey[]` annotations are then unnecessary. `CreateHttp` / `CreateHttpStream` carry their own fixed config shape, so HTTP routes declare errors per-route with the `satisfies` form above.
 
 ### Cross-cutting observability — `onRequestError`
 
@@ -201,6 +228,47 @@ The observer is awaited before the response is sent, and any error it throws is
 
 Configuring only the taxonomy, only `onError`, both, or neither are all valid. When neither is configured the builder goes straight from step 1 to step 4.
 
+## Build Your Own Adapter — `ts-procedures/server`
+
+`HonoAppBuilder` is deliberately thin: everything framework-agnostic lives in the `ts-procedures/server` subpath, so an adapter for Fastify, Express, or raw `http` is ~4 thin handlers translating between your framework's request/response/streaming primitives and these helpers. Use `src/adapters/hono/` in the package source as the blueprint.
+
+```typescript
+import {
+  // Error dispatch — data-in/data-out, no framework Response types
+  dispatchPreStreamError, // → { type: 'body', statusCode, body } | { type: 'response', response }
+  dispatchMidStreamError, // → { data, sseEvent?, sseId?, sseRetry?, runOnCatch? }
+
+  // Request handling
+  extractReqChannels,     // RequestSource → the declared schema.req channels
+  parseQueryNative,       // default QueryParser
+  resolveFactoryContext,  // runs your per-request context resolver
+
+  // SSE
+  SseEventSequencer,      // shared yield/return/error event sequencing for both stream kinds
+  sse, getSSEMeta,
+
+  // Route docs
+  buildRpcRouteDoc,
+  buildStreamRouteDoc,
+  buildHttpRouteDoc,
+  buildHttpStreamRouteDoc,
+  makeRoutePath,
+
+  // Doc aggregation
+  DocRegistry,
+  writeDocEnvelope,
+} from 'ts-procedures/server'
+```
+
+Key contracts:
+
+- **`dispatchPreStreamError` is transport-agnostic.** It returns plain data — `{ type: 'body', statusCode, body }` for taxonomy / `unknownError` / hard-default resolutions (serialize `body` as JSON with `statusCode`), or `{ type: 'response', response }` when the imperative `onError` callback produced a framework response (send as-is). Your adapter translates; the dispatch order is identical to the table above.
+- **`extractReqChannels`** takes a `RequestSource` (a tiny interface your adapter implements over its request object) and returns only the channels the route declared in `schema.req`.
+- **`SseEventSequencer`** owns yield/return/error event names, id sequencing, and the `event: 'return'` envelope, so every adapter's SSE wire format matches the Hono builder's byte-for-byte.
+- Only the taxonomy callbacks' `raw` parameter is typed `unknown` at the server layer — it is your framework's request context; cast it in your adapter.
+
+No framework imports are allowed inside `ts-procedures/server` (enforced by test), so depending on it never drags Hono into your bundle.
+
 ## DocRegistry — Composing Docs
 
 For a single-builder app, the simplest path is `builder.toDocEnvelope({ basePath, errors })` — it wraps `DocRegistry` for you and produces the same envelope shape:
@@ -241,6 +309,8 @@ const docs = new DocRegistry({ errors: appErrors, basePath: '/api' })
 
 `from()` stores a reference — routes are read lazily at `toJSON()` time, so builders can be registered before or after `.build()`. Supports optional `filter` and `transform` options for customizing output.
 
+`http-stream` route docs include the route's `yield` and `res.headers` schemas. (Through v8, live envelopes silently dropped these for `http-stream` routes, so generated clients lost those types unless the envelope was hand-authored; v9 fixed this.)
+
 The `DocRegistry` output is the input for [Client Code Generation](./client-and-codegen.md).
 
 ## Type Exports
@@ -260,6 +330,13 @@ import type {
 } from 'ts-procedures/http'
 
 // Hono builder + Hono-specific types
-import { HonoAppBuilder } from 'ts-procedures/hono'
-import type { HonoAppBuilderConfig, QueryParser, OnRequestErrorContext, ExtendProcedureDoc } from 'ts-procedures/hono'
+import { HonoAppBuilder, sse, defineErrorTaxonomy, DocRegistry } from 'ts-procedures/hono'
+import type {
+  HonoAppBuilderConfig,
+  QueryParser,
+  OnRequestErrorContext,
+  ExtendProcedureDoc,
+  SSEOptions,
+  MidStreamErrorResult,
+} from 'ts-procedures/hono'
 ```

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

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