ts-procedures 8.6.0 → 9.1.0

package/README.md

@@ -1,146 +1,211 @@
 # ts-procedures
 
-A TypeScript RPC framework that creates type-safe, schema-validated procedure calls with a single function definition. Define your procedures once and get full type inference, runtime validation and procedure documentation/configuration.
+A TypeScript RPC framework that creates type-safe, schema-validated procedure
+calls from a single function definition. Define procedures once on the server
+and get full type inference, runtime validation, HTTP serving, and generated
+clients (TypeScript, Kotlin, Swift) — with typed errors end to end.
 
-## Goals of this Project
-
-1. Full type safety
-2. Auto generated documentation and client api spec
-3. Fast and performant
-4. Excellent DX (and agent documentation)
+```ts
+import { Type } from 'typebox'
+import { Procedures } from 'ts-procedures'
 
+type Ctx = { db: Db }
+const { Create } = Procedures<Ctx>()
 
-## Installation
+export const { GetUser } = Create(
+  'GetUser',
+  {
+    schema: {
+      params: Type.Object({ id: Type.String() }),
+      returnType: Type.Object({ id: Type.String(), name: Type.String() }),
+    },
+  },
+  async (ctx, params) => {
+    const user = await ctx.db.users.find(params.id)
+    if (!user) throw ctx.error('User not found', { id: params.id })
+    return user
+  },
+)
 
-```bash
-npm install ts-procedures
+// Directly callable (great for tests), fully typed:
+await GetUser({ db }, { id: 'u1' })
 ```
 
-The core package is dependency-light and the integrations are **optional** —
-install only what each one needs:
+## The four procedure kinds
 
-| You're using | Also install | Imported from |
+| Creator | Kind | Shape |
 |---|---|---|
-| Core procedures, schema, client, codegen | _(nothing extra)_ | `ts-procedures`, `ts-procedures/client`, `ts-procedures/codegen` |
-| Hono server integration | `npm install hono` | `ts-procedures/hono` |
-| Astro adapter | `npm install astro hono` | `ts-procedures/astro` |
-| Kotlin / Swift codegen targets | `npm install ajsc` | `ts-procedures-codegen --target kotlin\|swift` |
+| `Create` | `rpc` | `(ctx, params) => Promise<T>` — POST, body in/JSON out |
+| `CreateStream` | `rpc-stream` | async generator — SSE (or text) stream |
+| `CreateHttp` | `http` | REST route with per-channel input (`pathParams`, `query`, `body`, `headers`) |
+| `CreateHttpStream` | `http-stream` | REST route streaming SSE, optional initial headers |
 
-`hono`, `astro`, and `ajsc` are declared as `optionalDependencies`, so a plain
-`npm install ts-procedures` never pulls them — and the package is marked
-`sideEffects: false`, so bundlers tree-shake away any subpath you don't import.
-
-## Quick Start
-
-```typescript
-import { Procedures } from 'ts-procedures'
-import { Type } from 'typebox'
+Every creator returns `{ [name]: handler, procedure: handler, info }`: the
+named handler for direct calls, and `info` for introspection (computed JSON
+Schema, validators, your extended config).
 
-// Create a procedures factory
-const { Create } = Procedures()
+```ts
+const { CreateHttp } = Procedures<Ctx>({ http: { pathPrefix: '/v1', scope: 'users' } })
 
-// Define a procedure with schema validation
-const { GetUser, procedure, info } = Create(
-  'GetUser',
+export const { UpdateUser } = CreateHttp(
+  'UpdateUser',
   {
-    description: 'Fetches a user by ID',
+    path: '/users/:id',
+    method: 'put',
+    errors: ['NotFound'], // taxonomy keys → typed client errors
     schema: {
-      params: Type.Object({ userId: Type.String() }),
-      returnType: Type.Object({ id: Type.String(), name: Type.String() }),
+      req: {
+        pathParams: Type.Object({ id: Type.String() }),
+        body: Type.Object({ name: Type.String() }),
+      },
+      res: { body: Type.Object({ id: Type.String(), name: Type.String() }) },
     },
   },
-  async (ctx, params /* typed as { userId: string } */) => {
-    
-    // returnType is inferred as { id: string; name: string }
-    return { id: params.userId, name: 'John Doe' }
-  },
+  async (ctx, req) => ctx.db.users.update(req.pathParams.id, req.body),
 )
-
-// Call the procedure directly
-const user = await GetUser({}, { userId: '123' })
-// Or use the generic reference
-const user2 = await procedure({}, { userId: '456' })
 ```
 
-## v8 Migration — Unified `HonoAppBuilder`
+## Serving over HTTP (Hono)
 
-The three Hono builders (`HonoRPCAppBuilder`, `HonoAPIAppBuilder`, `HonoStreamAppBuilder`) are replaced in v8 by a single `HonoAppBuilder` that accepts any `Procedures<>()` factory and dispatches all four procedure kinds (`rpc`, `rpc-stream`, `http`, `http-stream`) by `procedure.kind` from a single `register()` call.
+```ts
+import { Hono } from 'hono'
+import { HonoAppBuilder, defineErrorTaxonomy } from 'ts-procedures/hono'
 
-```typescript
-// Before (v7)
-const rpc = new HonoRPCAppBuilder({ app, errors }).register(F1, ctx1)
-const api = new HonoAPIAppBuilder({ app, errors, queryParser }).register(F2, ctx2)
-const stream = new HonoStreamAppBuilder({ app, errors, onMidStreamError }).register(F3, ctx3)
+const errors = defineErrorTaxonomy({
+  NotFound: { class: NotFoundError, statusCode: 404 },
+})
 
-// After (v8)
-const builder = new HonoAppBuilder({
-  app,
-  errors,
-  api: { queryParser },
-  stream: { onMidStreamError },
-}).register(F1, ctx1).register(F2, ctx2).register(F3, ctx3)
+const builder = new HonoAppBuilder({ pathPrefix: '/api', errors })
+  .register(factory, (c) => ({ db: makeDb(c) })) // context per request (sync or async)
+
+const app = builder.build() // a Hono app — mount anywhere Hono runs
 ```
 
-Kind-specific config knobs are stratified into `rpc.*`, `api.*`, and `stream.*` blocks. Single-app users can call `builder.toDocEnvelope()` directly (no `DocRegistry` needed). `DocRegistry` remains for multi-app aggregation.
+One builder serves all four kinds. Config is stratified: kind-specific blocks
+(`rpc.onSuccess`, `api.queryParser`, `stream.defaultStreamMode` /
+`onStreamStart` / `onStreamEnd` / `onMidStreamError`) plus cross-cutting
+error handling (`errors` taxonomy, `unknownError`, imperative `onError`,
+`onRequestError` observer) and lifecycle (`onRequestStart/End`).
 
-Subpath imports change from `ts-procedures/hono-rpc`, `ts-procedures/hono-api`, `ts-procedures/hono-stream` to `ts-procedures/hono`.
+An Astro adapter ships too: `createAstroHandler` from `ts-procedures/astro`
+serves built Hono apps from an Astro catch-all route.
 
-## HTTP Routes (v8) — `CreateHttp`
+### Error taxonomy
 
-v8 introduces `CreateHttp` and `CreateHttpStream` as first-class HTTP creators. HTTP fields (`path`, `method`, `scope`, `errors`) live on the creator config directly; no factory type parameter is required.
+Declarative, typo-proof error handling: map error classes (or predicates) to
+status codes and wire bodies once, and the same source of truth drives runtime
+responses, envelope docs, and generated typed client errors.
 
-```typescript
-import { Procedures } from 'ts-procedures'
-import { HonoAppBuilder } from 'ts-procedures/hono'
-import { Type } from 'typebox'
+```ts
+const errors = defineErrorTaxonomy({
+  NotFound:  { class: NotFoundError, statusCode: 404 },
+  UseCase:   { class: UseCaseError, statusCode: 422, toResponse: (e) => ({ message: e.publicMessage }) },
+  PgUnique:  { match: (e): e is DatabaseError => isPgError(e, '23505'), statusCode: 409 },
+})
+```
 
-type AppContext = { userId: string }
-const API = Procedures<AppContext>()
-
-// Input channels: pathParams, query, body, headers (schema.req)
-// Response: schema.res.body (docs) + schema.res.headers (makes handler return { body, headers })
-API.CreateHttp('GetUser', {
-  path: '/users/:id',
-  method: 'get',
-  schema: {
-    req: { pathParams: Type.Object({ id: Type.String() }) },
-    res: { body: Type.Object({ id: Type.String(), name: Type.String() }) },
-  },
-}, async (ctx, { pathParams }) => fetchUser(pathParams.id))
+Subclasses are checked before base classes automatically (topological sort);
+`{ name }` is injected into bodies so client dispatch always works; framework
+defaults (`ProcedureValidationError` → 400, etc.) layer underneath yours.
 
-API.CreateHttp('CreateUser', {
-  path: '/users',
-  method: 'post',
-  schema: {
-    req: { body: Type.Object({ name: Type.String(), email: Type.String() }) },
-  },
-}, async (ctx, { body }) => createUser(body))
+## Generated clients
 
-const app = new HonoAppBuilder({ pathPrefix: '/api' })
-  .register(API, (c) => ({ userId: c.req.header('x-user-id') || 'anonymous' }))
-  .build()
-// GET /api/users/:id → 200, POST /api/users → 201
-```
+Codegen consumes a `DocEnvelope` — from a live URL or a file written with
+`writeDocEnvelope(builder, 'envelope.json')`:
 
-**Migrating from v7?** Replace `Procedures<Ctx, APIConfig>()` → `Procedures<Ctx>()`, `.Create(` → `.CreateHttp(`, and `schema.input` → `schema.req`. Then re-run `npx ts-procedures-codegen`. See `CHANGELOG.md` for the full breaking-changes list.
+```bash
+npx ts-procedures-codegen --url http://localhost:3000/api/docs --out src/generated
+# or offline:
+npx ts-procedures-codegen --file envelope.json --out src/generated
+```
 
-## Features
+```ts
+import { createApiClient } from './generated'
 
-- **[Core Procedures](docs/core.md)** — Type-safe procedure definitions with `Procedures()`, `Create`, `CreateHttp`, and `CreateStream`. Includes schema validation with TypeBox, error handling, generics, testing patterns, and the full API reference.
+const api = createApiClient({ basePath: 'https://api.example.com' })
 
-- **[Streaming](docs/streaming.md)** — Async generator procedures with yield validation, abort signal integration, SSE examples, and stream error handling. `CreateHttpStream` supports response headers via `TypedStream.headers`.
+const user = await api.users.GetUser({ id: 'u1' })          // throws typed errors
+const result = await api.users.GetUser.safe({ id: 'u1' })   // Result<T, E> instead
 
-- **[HTTP Integrations](docs/http-integrations.md)** — `HonoAppBuilder` with lifecycle hooks, route documentation, `DocRegistry` for composing docs, and per-channel input validation via `schema.req`.
+for await (const event of api.users.WatchUsers({})) { ... } // TypedStream
+```
 
-- **[Client Code Generation](docs/client-and-codegen.md)** — Generate type-safe client SDKs from your server's `DocRegistry`. CLI and programmatic API, adapters, hooks, streaming support, and self-contained mode.
+- **Typed errors:** routes declaring `errors: [...]` get real error classes —
+  `catch (e) { if (e instanceof ApiErrors.NotFound) ... }` — plus a named
+  `Errors` union per route.
+- **Self-contained by default:** the generated directory bundles its own
+  runtime (`_client.ts` / `_types.ts`); no runtime dependency on this package.
+- **Shared models:** schemas carrying `$id` are hoisted once into `_models.ts`
+  (or re-exported from your own package via `--shared-models-module`).
+- **Kotlin / Swift:** `--target kotlin --kotlin-package com.example.api` or
+  `--target swift` emit types + route constants/path builders for mobile teams
+  (they own the HTTP layer).
+- Watch mode, config file (`ts-procedures-codegen.config.json`), strict flags
+  with did-you-mean, orphaned-file pruning — see `npx ts-procedures-codegen --help`.
+
+## Validation & schemas
+
+- TypeBox is built in (`import { Type } from 'typebox'`); `schema.params` /
+  `schema.req.*` are validated at runtime with AJV (`allErrors`, `coerceTypes`,
+  `removeAdditional`); `schema.returnType` / `schema.res` document and drive
+  codegen.
+- Customize AJV per factory: `Procedures({ validation: { ajv: {...} } })`.
+- Skip per-call validation for trusted internal factories:
+  `Procedures({ validation: false })` (schemas still computed; bad schemas
+  still fail fast at registration).
+- Plug in another schema library with a 3-line `SchemaAdapter`
+  (`Procedures({ schema: { adapters: [zodAdapter] } })`).
+
+## Streaming
+
+Stream handlers always receive `ctx.signal` — it aborts on client disconnect,
+and with reason `'stream-completed'` on normal completion. Yields become SSE
+events (customize with `sse(data, { event, id, retry })`); the generator's
+return value arrives as the `event: 'return'` payload, surfaced by generated
+clients as `await stream.result`. Opt into per-yield validation with
+`validateYields: true`.
+
+## Build your own server adapter
+
+Everything the Hono adapter uses lives in `ts-procedures/server`, framework-free:
+route-doc builders, taxonomy dispatch (data in, data out), request channel
+extraction (`RequestSource`), SSE metadata, `DocRegistry`. A Fastify or Express
+adapter is a few thin handlers — `src/adapters/hono/` is the reference
+implementation.
+
+## Subpaths
+
+| Import | Contents |
+|---|---|
+| `ts-procedures` | `Procedures`, error classes, schema utilities, `writeDocEnvelope` |
+| `ts-procedures/hono` | `HonoAppBuilder`, `defineErrorTaxonomy`, `sse`, `DocRegistry` |
+| `ts-procedures/astro` | `createAstroHandler`, `getAstroContext` |
+| `ts-procedures/server` | Transport-agnostic adapter toolkit |
+| `ts-procedures/http` | HTTP doc/config types (type-only) |
+| `ts-procedures/http-docs` | `DocRegistry` |
+| `ts-procedures/http-errors` | Error taxonomy helpers |
+| `ts-procedures/client` | Runtime client (`createClient`, adapters, hooks, errors) |
+| `ts-procedures/codegen` | `generateClient` programmatic API |
+
+## AI assistant setup
+
+The package ships rules and skills for Claude Code, Cursor, and GitHub
+Copilot so your AI tooling knows the framework's patterns and footguns:
 
-- **[Typed Error Handling](docs/http-integrations.md#error-handling)** — Declarative `defineErrorTaxonomy` maps thrown error classes to HTTP responses across every builder; generated clients throw typed class instances you can catch with `instanceof`.
+```bash
+npx ts-procedures-setup            # all targets
+npx ts-procedures-setup claude     # Claude Code only
+npx ts-procedures-setup --dry-run  # preview
+```
 
-- **[Client Error Handling](docs/client-error-handling.md)** — Normalized framework error classes (`ClientHttpError`, `ClientNetworkError`, `ClientTimeoutError`, `ClientAbortError`, `ClientParseError`), `.safe()` Result API for exhaustive narrowing without try/catch, and augmentable `ClientErrorMap` for custom error categories.
+Installed files auto-update on subsequent `npm install` via the package's
+postinstall hook.
 
-- **[AI Agent Setup](docs/ai-agent-setup.md)** — Built-in configuration for Claude Code, Cursor, and GitHub Copilot. Auto-updates on `npm install`.
+## Migrating from v8
 
-Full documentation is available on [GitHub](https://github.com/thermsio/ts-procedures).
+Generated client output is byte-identical to v8.6.0 — consumers have nothing
+to do. Server-side breaking changes are small and mechanical; see
+[docs/migration-v8-to-v9.md](docs/migration-v8-to-v9.md).
 
 ## License
 

package/agent_config/claude-code/.claude-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "ts-procedures",
-  "version": "1.1.0",
+  "version": "9.0.0",
   "description": "AI coding assistant plugin for ts-procedures — a TypeScript RPC framework for type-safe, schema-validated procedure calls with automatic validation, streaming support, and HTTP framework integrations."
 }

package/agent_config/claude-code/agents/ts-procedures-architect.md

@@ -32,14 +32,16 @@ When asked to plan an API or procedure set:
 - Handlers receive `(ctx, params)` where ctx includes base context + `error()` function + optional `signal`.
 - Stream handlers always get `ctx.signal` (guaranteed `AbortSignal`). Standard handlers get it when provided by the HTTP implementation.
 - Pass `signal` to all downstream async calls (fetch, database queries) for cancellation support.
-- `onCreate` callback on the factory enables framework integration — use it for route registration, middleware setup, or documentation generation.
+- `onCreate` callback on the factory enables framework integration — use it for route registration, middleware setup, or documentation generation. Every registration carries a `kind` discriminant (`'rpc' | 'rpc-stream' | 'http' | 'http-stream'`). For a full custom server adapter, build on the transport-agnostic `ts-procedures/server` toolkit (route-doc builders, error dispatch, request channel extraction, SSE sequencing).
 - `getProcedures()` returns all registered procedures for introspection (OpenAPI generation, testing, etc.).
-- AJV is configured with `allErrors: true`, `coerceTypes: true`, `removeAdditional: true`.
-- `schema.params` and `schema.input` are mutually exclusive — defining both throws `ProcedureRegistrationError`.
-- Path param names in route template (`:id`) must match `schema.input.pathParams` property names.
+- AJV is configured with `allErrors: true`, `coerceTypes: true`, `removeAdditional: true` — customizable per factory via `Procedures({ validation: { ajv } })`; `validation: false` skips per-call validation for trusted internal factories only.
+- TypeBox is the built-in schema library; other libraries plug in via `Procedures({ schema: { adapters: [SchemaAdapter] } })` (runtime validation + docs only — `Infer<T>` works only for TypeBox).
+- `Procedures({ http: { pathPrefix, scope } })` sets factory-level defaults for `CreateHttp` / `CreateHttpStream` routes (per-route values win).
+- `schema.params` and `schema.req` are mutually exclusive — defining both throws `ProcedureRegistrationError`.
+- Path param names in route template (`:id`) must match `schema.req.pathParams` property names.
 - Use `DocRegistry` to compose route docs from multiple builders — never manually wire `/docs` endpoints. Pass your taxonomy directly: `new DocRegistry({ errors: appErrors })` — framework defaults are auto-merged and deduped. For errors outside your taxonomy (middleware, infrastructure, doc-only), chain `.documentError(...docs)`.
 - Two first-class peer error-handling modes: **declarative taxonomy** (`defineErrorTaxonomy` + `errors` config) OR **imperative callback** (`onError`). Neither is deprecated. Pick the taxonomy for structured apps with typed client dispatch; pick `onError` for simple apps or full response control. Mixing both is allowed — the taxonomy handles what it covers, `onError` handles the tail. The anti-pattern is `instanceof` ladders inside `onError` (see anti-pattern #20 in the skill reference) — that's exactly what the taxonomy expresses declaratively.
-- Per-route `errors: ['UseCaseError', ...]` narrows typed errors on the generated client. Declare via `APIConfig<keyof typeof appErrors & string>` / `RPCConfig<keyof typeof appErrors & string>` for compile-time typo protection.
+- Per-route `errors: ['UseCaseError', ...]` narrows typed errors on the generated client. For compile-time typo protection, narrow `RPCConfig<keyof typeof appErrors & string>` on RPC factories; on `CreateHttp` routes attach `satisfies (keyof typeof appErrors & string)[]` to the `errors` array (an explicit generic would bind `TName` and break `schema.req`/`schema.res` inference).
 - Generated `_errors.ts` emits real runtime classes extending `${Service}ProcedureError` — consumers catch with `instanceof ${Service}Errors.${Name}` and access `err.body`, `err.status`, `err.procedureName`, `err.scope`. Use the generated `create${Service}Client(config)` factory to wire the error registry automatically.
 
 ## Context Design Patterns
@@ -66,11 +68,10 @@ interface AppConfig extends RPCConfig {
   version: number
 }
 
-// REST-style: path + method (required for API builder)
-interface AppConfig extends APIConfig {
-  path: string
-  method: HttpMethod
-}
+// REST-style: no extended config needed — path, method, scope, errors are
+// first-class fields on the CreateHttp / CreateHttpStream config itself.
+const API = Procedures<AppContext>()
+API.CreateHttp('GetUser', { path: '/users/:id', method: 'get', schema: { /* req/res */ } }, handler)
 ```
 
 ## Output Format

package/agent_config/claude-code/skills/ts-procedures/SKILL.md

@@ -39,7 +39,7 @@ This skill has three modes, selected by the **first whitespace-delimited word of
 Load the right reference for your task:
 
 - **Writing new procedures or HTTP routes?** Read [patterns.md](patterns.md) — prescribed code examples for every procedure type and HTTP integration
-- **Reviewing or debugging existing code?** Read [anti-patterns.md](anti-patterns.md) — 20 common mistakes with before/after fixes and severity ratings
+- **Reviewing or debugging existing code?** Read [anti-patterns.md](anti-patterns.md) — 23 common mistakes with before/after fixes and severity ratings
 - **Need exact API signatures or type definitions?** Read [api-reference.md](api-reference.md) — complete API documentation with type signatures for every export
 - **Generating a Kotlin client for Android/JVM consumers?** See the **Kotlin Client Codegen** section below — it covers `--target kotlin` end-to-end.
 - **Generating a Swift client for iOS/macOS/Apple-platform consumers?** See the **Swift Client Codegen** section below — it covers `--target swift` end-to-end.
@@ -47,7 +47,7 @@ Load the right reference for your task:
 ## Core Flow
 
 ```
-Procedures<TContext, TExtendedConfig>(builder?)
+Procedures<TContext, TExtendedConfig>(options?)
     |
 Create(name, config, handler)       --> Standard async procedure
 CreateStream(name, config, handler) --> Streaming async generator
@@ -58,21 +58,29 @@ Returns: { [name]: handler, procedure: handler, info: metadata }
 ## Factory API
 
 ```typescript
-const { Create, CreateStream, getProcedures, getProcedure, removeProcedure, clear } =
+const { Create, CreateStream, CreateHttp, CreateHttpStream, getProcedures, getProcedure, removeProcedure, clear } =
   Procedures<TContext, TExtendedConfig>({
-    onCreate: (procedure) => { /* called on each registration */ }
+    onCreate: (procedure) => { /* called on each registration — narrow on procedure.kind */ },
+    validation: false,                              // optional: skip per-call AJV (replaces v8 noRuntimeValidation)
+    // validation: { ajv: { coerceTypes: false } }, // or per-factory AJV options / instance
+    schema: { adapters: [myZodAdapter] },           // optional: plug in other schema libraries (TypeBox built in)
+    http: { pathPrefix: '/v1', scope: 'billing' },  // optional: CreateHttp/CreateHttpStream defaults (per-route wins)
   })
 ```
 
 | Method | Purpose |
 |--------|---------|
-| `Create(name, config, handler)` | Register standard async procedure |
-| `CreateStream(name, config, handler)` | Register streaming procedure (async generator) |
+| `Create(name, config, handler)` | Register standard async procedure (`kind: 'rpc'`) |
+| `CreateStream(name, config, handler)` | Register streaming procedure (async generator, `kind: 'rpc-stream'`) |
+| `CreateHttp(name, config, handler)` | Register REST-style HTTP procedure (`kind: 'http'`) |
+| `CreateHttpStream(name, config, handler)` | Register streaming HTTP procedure (`kind: 'http-stream'`) |
 | `getProcedures()` | Returns array of all registered procedures |
 | `getProcedure(name)` | Get single procedure by name |
 | `removeProcedure(name)` | Remove procedure by name |
 | `clear()` | Remove all procedures |
 
+Every registration (and every creator's `info`) carries a `kind` discriminant: `'rpc' | 'rpc-stream' | 'http' | 'http-stream'`. Registering the same name twice throws `ProcedureRegistrationError`.
+
 ## Context
 
 Handlers receive `(ctx, params)` where ctx includes:
@@ -94,7 +102,9 @@ Uses **TypeBox** for schema definitions (`import { Type } from 'typebox'`):
 | `schema.yieldType` | Validated only if `validateYields: true` in CreateStream config |
 | `schema.req` | Structured multi-channel HTTP input (`pathParams`, `query`, `body`, `headers`) — available on `CreateHttp` / `CreateHttpStream` only |
 
-AJV config: `allErrors: true`, `coerceTypes: true`, `removeAdditional: true`
+AJV config: `allErrors: true`, `coerceTypes: true`, `removeAdditional: true` — customizable per factory via `Procedures({ validation: { ajv } })` (options merged over the defaults, or a configured `Ajv` instance).
+
+TypeBox is the only built-in schema library. Other libraries plug in via the 3-member `SchemaAdapter` interface (`{ name, detect, toJsonSchema }`) passed as `Procedures({ schema: { adapters: [...] } })` — custom adapters get runtime validation + docs, but compile-time inference (`Infer<T>`) works only for TypeBox.
 
 > **Composing schemas:** the bundled TypeBox does **not** export `Type.Composite`. Extend a schema with a flat property spread — `Type.Object({ ...Base.properties, name: Type.String() })` — which also keeps the generated JSON Schema a single `object` instead of an `allOf`.
 
@@ -108,7 +118,7 @@ AJV config: `allErrors: true`, `coerceTypes: true`, `removeAdditional: true`
 | `ProcedureRegistrationError` | Invalid schema at registration time | `procedureName`, `message` |
 | `${Service}ProcedureError` (generated, client) | Base class for all generated client error classes | `status`, `procedureName`, `scope`, `body` |
 
-All errors include `definedAt` (file:line:column) and enhanced stack traces pointing to the procedure definition location.
+All errors include `definedAt` (file:line:column) and enhanced stack traces pointing to the procedure definition location. Every framework error also carries a `kind` discriminant (`'procedure' | 'validation' | 'yield-validation' | 'registration'`) as an alternative to `instanceof`.
 
 ## Error Taxonomy (HTTP builders)
 
@@ -136,6 +146,8 @@ Full contract: `docs/http-integrations.md § Error Handling` (canonical) and `ap
 | `HonoAppBuilder` | `ts-procedures/hono` | RPC, REST-style HTTP, and streaming (SSE / newline-JSON) — one builder dispatches all four procedure kinds |
 | `DocRegistry` | `ts-procedures/http-docs` | Compose route docs from multiple builders (single-app users can also call `builder.toDocEnvelope()`) |
 
+Building on another framework (Fastify, Express, raw http, ...)? Use the transport-agnostic **`ts-procedures/server`** toolkit — route-doc builders, data-in/data-out error dispatch (`dispatchPreStreamError` / `dispatchMidStreamError`), `RequestSource` channel extraction, `SseEventSequencer`, `DocRegistry`. A custom adapter is ~4 thin handlers; `src/adapters/hono/` is the reference. See `api-reference.md § Server Toolkit`.
+
 ### Route Path Format (RPC)
 
 ```
@@ -154,7 +166,7 @@ const app = new HonoAppBuilder({ pathPrefix: '/api' })
 
 ### Lifecycle Hooks (HTTP builders)
 
-For `HonoAppBuilder` (v8), hooks are stratified: cross-cutting hooks live at the top level, kind-specific hooks live inside `rpc:` / `api:` / `stream:` blocks.
+For `HonoAppBuilder`, hooks are stratified: cross-cutting hooks live at the top level, kind-specific hooks live inside `rpc:` / `api:` / `stream:` blocks.
 
 | Hook | Block | When |
 |------|-------|------|
@@ -203,7 +215,8 @@ The npm package ships user-facing documentation with narrative explanations and
 | `docs/client-error-handling.md` | **Canonical guide** for 7.0+ client error surface: normalized error classes, `.safe()` Result API, `ClientErrorMap` augmentation, custom `ErrorClassifier`, migration from `ClientRequestError`. |
 | `docs/codegen-kotlin.md` | Kotlin target consumer setup (Gradle deps, contextual serializers, sealed interfaces) |
 | `docs/codegen-swift.md` | Swift target consumer setup (SPM/Xcode integration, JSONDecoder config, discriminated unions, error dispatch patterns) |
-| `CHANGELOG.md` | Release notes — see `[7.0.0]` for the safe-result API, new error classes, and `ClientRequestError` → `ClientHttpError` rename. See `[6.0.0]` for the peer error-handling model (taxonomy + `onError` + `onRequestError`). |
+| `docs/migration-v8-to-v9.md` | Every v8 → v9 breaking change with before/after (`validation: false` replaces `noRuntimeValidation`, Suretype removal, `kind` discriminants, `ts-procedures/server`) |
+| `CHANGELOG.md` | Release notes — see `[9.0.0]` for the factory options bag, `SchemaAdapter`, the `ts-procedures/server` toolkit, and SSE wire normalization. See `[7.0.0]` for the safe-result API, new error classes, and `ClientRequestError` → `ClientHttpError` rename. See `[6.0.0]` for the peer error-handling model (taxonomy + `onError` + `onRequestError`). |
 
 ## Workflow
 
@@ -222,9 +235,9 @@ Parse the remainder of `$ARGUMENTS` (everything after `review`) as a file or dir
 ### Instructions
 
 1. Read the target file(s).
-2. Identify ts-procedures imports (`ts-procedures`, `ts-procedures/hono`, `ts-procedures/http`, `ts-procedures/http-docs`, `ts-procedures/http-errors`, `ts-procedures/client`, `ts-procedures/codegen`) to determine file types.
+2. Identify ts-procedures imports (`ts-procedures`, `ts-procedures/hono`, `ts-procedures/astro`, `ts-procedures/server`, `ts-procedures/http`, `ts-procedures/http-docs`, `ts-procedures/http-errors`, `ts-procedures/client`, `ts-procedures/codegen`) to determine file types.
 3. Check each file against the categorized checklist in [checklist.md](checklist.md).
-4. For detailed code examples of each violation pattern, reference [anti-patterns.md](anti-patterns.md) — it shows 20 common mistakes with before/after code fixes and severity ratings.
+4. For detailed code examples of each violation pattern, reference [anti-patterns.md](anti-patterns.md) — it shows 23 common mistakes with before/after code fixes and severity ratings.
 5. Output findings grouped by severity.
 
 ### Output Format

package/agent_config/claude-code/skills/ts-procedures/anti-patterns.md

@@ -397,7 +397,7 @@ Create('GetUser', {
 }, handler)
 ```
 
-**Why:** ts-procedures detects schema type via TypeBox's `~kind` symbol. Plain JSON Schema objects are not recognized and will throw `ProcedureRegistrationError`.
+**Why:** ts-procedures detects schemas via the adapter chain — the built-in `typeboxAdapter` recognizes TypeBox's `~kind` marker. Plain JSON Schema objects are not recognized (no adapter matches) and will throw `ProcedureRegistrationError`. If you must use another schema library, register a custom `SchemaAdapter` via `Procedures({ schema: { adapters: [...] } })` instead of passing raw objects.
 
 ---
 
@@ -705,17 +705,17 @@ Or use the `.safe()` sibling for exhaustive Result-based narrowing (see `pattern
 
 ---
 
-## 22. Using `noRuntimeValidation` on a public-facing factory
+## 22. Using `validation: false` on a public-facing factory
 
-**Problem:** Setting `Procedures({ config: { noRuntimeValidation: true } })` on a factory whose procedures are exposed via HTTP, mounted on a public surface, or invoked with caller-supplied JSON. Schema validation is the only thing standing between untyped wire data and your handlers — turning it off lets malformed payloads reach business logic.
+**Problem:** Setting `Procedures({ validation: false })` (which replaces v8's `config: { noRuntimeValidation: true }`) on a factory whose procedures are exposed via HTTP, mounted on a public surface, or invoked with caller-supplied JSON. Schema validation is the only thing standing between untyped wire data and your handlers — turning it off lets malformed payloads reach business logic.
 
 ```typescript
 // BAD — these procedures are mounted on Hono and called by browsers
-const { Create } = Procedures({ config: { noRuntimeValidation: true } })
+const { CreateHttp } = Procedures({ validation: false })
 
-const { CreateUser } = Create('CreateUser', {
+const { CreateUser } = CreateHttp('CreateUser', {
   path: '/users', method: 'post',
-  schema: { input: { body: Type.Object({ email: Type.String() }) } },
+  schema: { req: { body: Type.Object({ email: Type.String() }) } },
 }, async (ctx, { body }) => {
   // body.email is typed `string`, but at runtime it can be anything —
   // the request validator was disabled at the factory level.
@@ -730,12 +730,10 @@ const { CreateUser } = Create('CreateUser', {
 const { Create: CreatePublic } = Procedures()
 
 // GOOD — internal factory used only from already-validated callers
-const { Create: CreateInternal } = Procedures({
-  config: { noRuntimeValidation: true },
-})
+const { Create: CreateInternal } = Procedures({ validation: false })
 ```
 
-**Why:** `noRuntimeValidation` skips both `schema.params` and `schema.input` AJV runs for every procedure on the factory — there is no per-procedure escape hatch. TypeScript types still flow, but TS types vanish at runtime. AJV is also what enforces `coerceTypes` and `removeAdditional`; once disabled, extra wire fields will leak through and string/number coercion stops happening. The flag is only `true` (no `false`) because the safe default — validation on — should never be expressed by a config value at all; an unset config is the safe path.
+**Why:** `validation: false` skips both `schema.params` and `schema.req` AJV runs for every procedure on the factory — there is no per-procedure escape hatch (JSON Schema and validators are still computed at registration, so bad schemas still fail fast). TypeScript types still flow, but TS types vanish at runtime. AJV is also what enforces `coerceTypes` and `removeAdditional`; once disabled, extra wire fields will leak through and string/number coercion stops happening. The safe default — validation on — is expressed by leaving the option unset; the only opt-out value is the explicit literal `false`.
 
 ---
 
@@ -800,9 +798,9 @@ API.CreateHttp('GetUser', {
 | 15 | Manual doc building instead of extendProcedureDoc | Fragile, incomplete documentation | SUGGESTION |
 | 16 | Manual /docs endpoint instead of DocRegistry | Duplicated boilerplate, missing error schemas | SUGGESTION |
 | 17 | Unhandled async context factory | Request crashes | WARNING |
-| 18 | Both schema.params and schema.input | ProcedureRegistrationError at startup | CRITICAL |
+| 18 | Both schema.params and schema.req | ProcedureRegistrationError at startup | CRITICAL |
 | 19 | Mismatched path param names | Build-time error or confusing validation failures | CRITICAL |
 | 20 | Hand-writing onError instanceof ladders | Drifting response shapes, untyped client errors | WARNING |
 | 21 | Catching raw DOMException/TypeError from generated callables | Framework normalizes these; raw platform errors won't reach catch blocks after 7.0.0 | WARNING |
-| 22 | `noRuntimeValidation` on a public-facing factory | Untrusted wire data reaches handlers without AJV; coerceTypes/removeAdditional also disabled | CRITICAL |
+| 22 | `validation: false` on a public-facing factory | Untrusted wire data reaches handlers without AJV; coerceTypes/removeAdditional also disabled | CRITICAL |
 | 23 | Using `Create` for HTTP routes (v8+) | ProcedureRegistrationError at startup; HTTP fields require `CreateHttp` / `CreateHttpStream` | CRITICAL |