ts-procedures 8.6.0 → 9.1.0

package/docs/client-and-codegen.md

@@ -10,7 +10,7 @@ ts-procedures can generate type-safe client SDKs directly from your server's `Do
 
 ## Quick Start
 
-**Step 1 — Serve your docs endpoint** (see [DocRegistry](./http-integrations.md#docregistry--composing-docs-from-multiple-builders) for setup):
+**Step 1 — Serve your docs endpoint** (see [DocRegistry](./http-integrations.md#docregistry--composing-docs) for setup):
 
 ```typescript
 app.get('/docs', (c) => c.json(docs.toJSON()))
@@ -43,6 +43,10 @@ const api = createApiClient({
 
 > **Note:** `basePath` must be the **origin only** (e.g. `http://localhost:3000`), not `http://localhost:3000/api`. Generated client paths already include the server's `pathPrefix` (e.g. `/api/...`), so putting the prefix in `basePath` too doubles it up to `/api/api/...`.
 
+> **Browser + cross-origin basePath = CORS.** If the client runs in a browser on a different origin than `basePath` (e.g. Vite on `:5173`, API on `:3000`), the browser blocks every request unless the server sends CORS headers — and the failure is the generic `Failed to fetch`, not a CORS-specific error. For dev setups, the usual fix is a same-origin dev proxy (e.g. Vite's `server.proxy['/api'] → http://localhost:3000`) with an **empty** `basePath` — the generated route paths already carry the `/api/...` prefix, so the proxy match comes for free. Reserve an absolute `basePath` for genuinely separate origins, which then need server-side CORS.
+
+> **Auth seams differ by transport.** The HTTP client's per-request hook (the `Authorization` header set in `onBeforeRequest` above) re-reads the token on every call, so rotation is automatic. A WebSocket transport can't set custom handshake headers from a browser, so realtime libraries (e.g. ts-channels) typically take the token as a `?token=` URL query fixed at client construction — rotating it means rebuilding that client. If you wire both transports, expect to inject the same session token through these two different seams.
+
 ```typescript
 try {
   const user = await api.users.GetUser({ pathParams: { id: '123' } })
@@ -267,7 +271,7 @@ const client = createClient({
 })
 ```
 
-The function form works everywhere a `headers` record does — client `defaults.headers` and per-call `options.headers` — and the same precedence applies: per-call headers (function or record) win over default headers, and route-declared headers from `schema.input.headers` win over both. A per-call function override:
+The function form works everywhere a `headers` record does — client `defaults.headers` and per-call `options.headers` — and the same precedence applies: per-call headers (function or record) win over default headers, and route-declared headers from `schema.req.headers` win over both. A per-call function override:
 
 ```typescript
 await client.users.GetUser(
@@ -489,7 +493,7 @@ Headers and signals combine across layers. From lowest to highest precedence (wi
 1. Adapter config (e.g., `createFetchAdapter({ headers })`)
 2. Client `defaults.headers` / `defaults.signal` / `defaults.timeout`
 3. Per-call `options.headers` / `options.signal` / `options.timeout`
-4. Route-declared headers from `schema.input.headers` (part of the typed contract)
+4. Route-declared headers from `schema.req.headers` (part of the typed contract)
 5. `onBeforeRequest` hook mutations — final say
 
 ## Streaming
@@ -534,6 +538,8 @@ await generateClient({
 
 When `shareModels` is on (the default), the codegen pre-pass collects every subschema with a `$id` field, deduplicates them, and emits a single `_models.ts` hub. Every scope that references one of those types imports from `./_models` instead of inlining it — so the type is defined once and shared across scopes.
 
+> **Limitation: record/index schemas can't be shared.** Sharing keys off `$id`, and a bare `Type.Record(...)` (JSON Schema `additionalProperties`) has no `$id` of its own — so a record type is always re-inlined at each use site, never hoisted into `_models.ts`. It still validates and types correctly; it just duplicates if referenced from multiple procedures. If a record type matters enough to share, wrap it in an `$id`-bearing model (e.g. give the object that carries it an `$id`, as `Thread` does for its `readCursors` map) and reference that.
+
 ### `sharedTypesImport` — per-`$id` override map
 
 For each `$id` you'd rather import from your own package instead of generating locally, add an entry to `sharedTypesImport` in the config file:
@@ -650,4 +656,4 @@ import type {
 import { generateClient } from 'ts-procedures/codegen'
 ```
 
-> **Migration note:** `ClientRequestError` was renamed to `ClientHttpError` in 7.0.0. The old name is re-exported as a deprecated alias for one minor cycle. Update imports when possible.
+> **Migration note:** `ClientRequestError` was renamed to `ClientHttpError` in 7.0.0. The old name is still re-exported as a deprecated alias. Update imports when possible.

package/docs/client-error-handling.md

@@ -45,7 +45,7 @@ All framework error classes are exported from `ts-procedures/client` (or from `.
 
 Every class carries `cause` to surface the underlying platform error — typically a `TypeError` or `DOMException` — when one exists.
 
-`ClientRequestError` is a deprecated alias for `ClientHttpError`. It is retained for one minor release after 7.0.0 and will be removed in a subsequent minor. See the [migration guide](#8-migration-6x--7x) below.
+`ClientRequestError` is a deprecated alias for `ClientHttpError` (renamed in 7.0.0) and will be removed in a future release. See the [migration guide](#8-migration-6x--7x) below.
 
 ---
 
@@ -308,7 +308,7 @@ Three breaking changes in 7.0.0 affect error handling.
 
 ### 8a. `ClientRequestError` Renamed to `ClientHttpError`
 
-`ClientRequestError` is a deprecated alias for `ClientHttpError`, retained for one minor release after 7.0.0.
+`ClientRequestError` is a deprecated alias for `ClientHttpError`, retained for backward compatibility since 7.0.0.
 
 **Action**: rename your imports from `ClientRequestError` to `ClientHttpError`. The `instanceof ClientRequestError` guard continues to work until the alias is removed.
 
@@ -412,9 +412,9 @@ A framework-level "skip `onError` for `.safe()`" toggle was deliberately deferre
 
 ## 10. Reference
 
-- Design spec: [`docs/superpowers/specs/2026-04-29-safe-result-api-design.md`](./superpowers/specs/2026-04-29-safe-result-api-design.md)
-- Client types and interfaces: `CLAUDE.md` — "Key Files" → `src/client/`
-- Agent config patterns and anti-patterns: `agent_config/claude-code/skills/ts-procedures/patterns.md` and `anti-patterns.md`
+- Codegen setup, per-call options, hooks, and typed-error wiring: [`docs/client-and-codegen.md`](./client-and-codegen.md)
+- Client types and interfaces: package source under `src/client/` (`types.ts`, `errors.ts`, `error-dispatch.ts`)
+- Agent config patterns and anti-patterns: [`agent_config/claude-code/skills/ts-procedures/patterns.md`](../agent_config/claude-code/skills/ts-procedures/patterns.md) and [`anti-patterns.md`](../agent_config/claude-code/skills/ts-procedures/anti-patterns.md)
 
 ---
 

package/docs/codegen-kotlin.md

@@ -141,7 +141,7 @@ Choosing the dispatch strategy (status-code based, body.name based, sealed-class
 
 ## Untagged unions
 
-ajsc v7.2's Kotlin emitter silently produces an empty `@Serializable data class` for any untagged `oneOf` schema, regardless of whether `--unsupported-unions fallback` is set. There is no "throws on default" mode for Kotlin (that's Swift behavior). The `--unsupported-unions` flag is currently a no-op for the Kotlin target.
+ajsc's Kotlin emitter (as of the bundled 7.x) silently produces an empty `@Serializable data class` for any untagged `oneOf` schema, regardless of whether `--unsupported-unions fallback` is set. There is no "throws on default" mode for Kotlin (that's Swift behavior). The `--unsupported-unions` flag is currently a no-op for the Kotlin target.
 
 For example, the schema `oneOf: [{ type: 'string' }, { type: 'integer' }]` with `rootTypeName: 'Mixed'` produces:
 
@@ -170,7 +170,6 @@ The following ajsc behaviors are intentional and documented; they are **not bugs
 
 ## Reference
 
-- Spec: [`docs/superpowers/specs/2026-04-25-ajsc-v7-kotlin-polish-design.md`](./superpowers/specs/2026-04-25-ajsc-v7-kotlin-polish-design.md)
 - For iOS / macOS / Apple-platform consumers, see [`docs/codegen-swift.md`](./codegen-swift.md) — same types-only design with Swift-specific flags and `Codable` setup notes.
 - ajsc README: `node_modules/ajsc/README.md` (or [npmjs.com/package/ajsc](https://www.npmjs.com/package/ajsc))
-- ts-procedures-codegen CLI flags: see `CLAUDE.md` (search for "Kotlin target") and the spec linked above. (`--help` is not currently implemented; pass invalid/missing args to see error messages with usage hints.)
+- ts-procedures-codegen CLI flags: run `npx ts-procedures-codegen --help` for the full grouped flag catalog. Kotlin-specific flags: `--kotlin-package` (required), `--kotlin-serializer`, `--unsupported-unions`.

package/docs/codegen-swift.md

@@ -308,7 +308,6 @@ The following ajsc behaviors are intentional and documented; they are **not bugs
 
 ## Reference
 
-- Spec: [`docs/superpowers/specs/2026-04-25-swift-codegen-design.md`](./superpowers/specs/2026-04-25-swift-codegen-design.md)
 - For Kotlin / Android consumers, see [`docs/codegen-kotlin.md`](./codegen-kotlin.md) — same types-only design with Kotlin-specific flags and `kotlinx.serialization` setup notes.
 - ajsc README: `node_modules/ajsc/README.md` (or [npmjs.com/package/ajsc](https://www.npmjs.com/package/ajsc))
-- ts-procedures-codegen CLI flags: see `CLAUDE.md` (search for "Swift target") and the spec linked above. (`--help` is not currently implemented; pass invalid/missing args to see error messages with usage hints.)
+- ts-procedures-codegen CLI flags: run `npx ts-procedures-codegen --help` for the full grouped flag catalog. Swift-specific flags: `--swift-serializer`, `--swift-access-level`, `--unsupported-unions`.

package/docs/core.md

@@ -6,21 +6,27 @@ ts-procedures creates type-safe, schema-validated procedure calls with a single
 
 ## Procedures Factory
 
-The `Procedures()` function creates a factory for defining procedures. It accepts two generic type parameters:
+The `Procedures()` function creates a factory for defining procedures. It accepts two generic type parameters and a flat options bag:
 
 ```typescript
-Procedures<TContext, TExtendedConfig>(builder?: {
-    config?: { noRuntimeValidation?: true }
-    onCreate?: (procedure: TProcedureRegistration<TContext, TExtendedConfig>) => void
+Procedures<TContext, TExtendedConfig>(options?: {
+    validation?: false | { ajv?: Ajv | AjvOptions }
+    schema?: { adapters?: SchemaAdapter[] }
+    http?: { pathPrefix?: string; scope?: string }
+    onCreate?: (procedure: AnyProcedureRegistration<TContext, TExtendedConfig>) => void
 })
 ```
 
 | Parameter | Description                                                                |
 |-----------|----------------------------------------------------------------------------|
 | `TContext` | The base context type passed to all handlers as the first parameter        |
-| `TExtendedConfig` | Additional configuration properties for all procedures `config` properties |
-| `builder.config.noRuntimeValidation` | When `true`, every procedure created by this factory skips AJV validation of `schema.params` and `schema.input` at call time. Applies to both `Create` and `CreateStream`. Default: validation runs.   |
-| `builder.onCreate` | Optional callback invoked when each procedure is registered (runtime)      |
+| `TExtendedConfig` | Additional configuration properties for all procedures `config` properties (applies to `Create` and `CreateStream`) |
+| `options.validation` | `false` skips per-call AJV validation for the whole factory (see [Disabling Runtime Validation](#disabling-runtime-validation)); `{ ajv }` customizes AJV — options merged over the defaults, or a configured `Ajv` instance used as-is. Default: validation runs with the default AJV configuration. |
+| `options.schema.adapters` | Plug in additional schema libraries via the `SchemaAdapter` interface. TypeBox is built in. See [Other Schema Libraries](#other-schema-libraries--schemaadapter). |
+| `options.http` | Factory-level defaults for `CreateHttp` / `CreateHttpStream`: `pathPrefix` is prepended to every route's `path` at registration time (part of the route's identity, unlike a server builder's mount prefix), and `scope` is the default codegen scope for routes that don't set one. Per-route config always wins. |
+| `options.onCreate` | Optional callback invoked when each procedure is registered (runtime)      |
+
+**Returns:** `Create`, `CreateStream`, `CreateHttp`, `CreateHttpStream`, plus introspection helpers `getProcedures()`, `getProcedure(name)`, `removeProcedure(name)`, and `clear()`.
 
 ## Create Function
 
@@ -33,27 +39,27 @@ Create(name, config, handler)
 **Returns:**
 - `{ [name]: handler }` - Named export for the handler
 - `procedure` - Generic reference to the handler
-- `info` - Procedure metadata (name, description, schema, `TExtendedConfig` properties, etc.)
+- `info` - Procedure metadata (name, `kind: 'rpc'`, description, schema, `TExtendedConfig` properties, etc.)
 
-## Structured Input with schema.input
+## HTTP Procedures with CreateHttp
 
-For HTTP APIs and other multi-channel transports, `schema.input` provides per-channel type safety. Each key is an independently validated input channel:
+For HTTP APIs and other multi-channel transports, `CreateHttp` provides per-channel type safety via `schema.req`. Each key is an independently validated input channel:
 
 ```typescript
-const { Create } = Procedures<AppContext, APIConfig>()
+const { CreateHttp } = Procedures<AppContext>()
 
-const { UpdateUser } = Create(
+const { UpdateUser } = CreateHttp(
   'UpdateUser',
   {
     path: '/users/:id',
     method: 'put',
     schema: {
-      input: {
+      req: {
         pathParams: Type.Object({ id: Type.String() }),
         query: Type.Object({ notify: Type.Optional(Type.Boolean()) }),
         body: Type.Object({ name: Type.String(), email: Type.String() }),
       },
-      returnType: Type.Object({ ok: Type.Boolean() }),
+      res: { body: Type.Object({ ok: Type.Boolean() }) },
     },
   },
   async (ctx, { pathParams, query, body }) => {
@@ -66,9 +72,13 @@ const { UpdateUser } = Create(
 ```
 
 **Rules:**
-- `schema.input` and `schema.params` are **mutually exclusive** — defining both throws `ProcedureRegistrationError`
-- Each channel is validated independently with per-channel error messages
-- Works with both `Create` and `CreateStream`
+- `schema.req` and `schema.params` are **mutually exclusive** — `schema.params` belongs to RPC procedures (`Create`/`CreateStream`), `schema.req` to HTTP procedures. Using `schema.params` on `CreateHttp` throws `ProcedureRegistrationError`.
+- Valid channels are `pathParams`, `query`, `body`, and `headers`; each is validated independently with per-channel error messages.
+- `schema.res.body` documents the response body (drives codegen); omit `schema.res` entirely for 204-style no-content routes.
+- Factory-level `http.pathPrefix` / `http.scope` defaults apply; per-route config wins.
+- For HTTP streaming routes, use `CreateHttpStream` — same `schema.req` channels plus `schema.yield`.
+
+For routing, status codes, and error handling for HTTP procedures, see [HTTP Integrations](./http-integrations.md).
 
 ## CreateStream Function
 
@@ -98,10 +108,23 @@ When using the built-in HTTP implementation (Hono), `ctx.signal` is automaticall
 **Returns:**
 - `{ [name]: handler }` - Named generator export
 - `procedure` - Generic reference to the generator
-- `info` - Procedure meta with `isStream: true`
+- `info` - Procedure meta with `kind: 'rpc-stream'`
 
 For detailed streaming documentation (yield validation, abort signals, SSE integration), see [Streaming Procedures](./streaming.md).
 
+## Procedure Kinds
+
+Every registration — and every creator's `info` — carries a `kind` discriminant for type narrowing:
+
+| Creator | `kind` |
+|---------|--------|
+| `Create` | `'rpc'` |
+| `CreateStream` | `'rpc-stream'` |
+| `CreateHttp` | `'http'` |
+| `CreateHttpStream` | `'http-stream'` |
+
+Branch on `kind` in `onCreate` callbacks and `getProcedures()` consumers to narrow a registration to its specific shape.
+
 ## Using Generics
 
 ### Base Context
@@ -161,6 +184,8 @@ const { AdminOnly } = Create(
 console.log(AdminOnly.info.permissions) // ['admin']
 ```
 
+`TExtendedConfig` applies to `Create` and `CreateStream`. `CreateHttp` / `CreateHttpStream` have their own fixed config shape (`path`, `method`, `successStatus`, `scope`, `errors`, `schema`).
+
 ### Combined Example
 
 ```typescript
@@ -177,8 +202,10 @@ interface ExtendedConfig {
 const { Create, getProcedures } = Procedures<CustomContext, ExtendedConfig>({
   onCreate: (procedure) => {
     // Register with your framework
-    console.log(`Registered: ${procedure.name}`)
-    console.log(`Requires Auth: ${procedure.config.requiresAuth}`)
+    console.log(`Registered: ${procedure.name} (${procedure.kind})`)
+    if (procedure.kind === 'rpc') {
+      console.log(`Requires Auth: ${procedure.config.requiresAuth}`)
+    }
   },
 })
 
@@ -212,10 +239,31 @@ import { Type } from 'typebox'
 schema: { params: Type.Object({ title: Type.String() }) }
 ```
 
-TypeBox schemas are valid JSON Schema and work directly with AJV for runtime validation.
+TypeBox schemas are valid JSON Schema and work directly with AJV for runtime validation. Handler param and return types are inferred from the schemas via `Infer<T>`.
 
 > **Composing schemas:** the bundled typebox has no `Type.Composite`. Compose with a flat object spread instead — `Type.Object({ ...Base.properties, extra: Type.String() })` — which also keeps the emitted JSON Schema a single `object` rather than an `allOf`.
 
+### Other Schema Libraries — SchemaAdapter
+
+TypeBox is built in. To register procedures with another schema library, implement the 3-member `SchemaAdapter` interface and pass it to the factory:
+
+```typescript
+import type { SchemaAdapter } from 'ts-procedures'
+import * as z from 'zod'
+
+const zodAdapter: SchemaAdapter = {
+  name: 'zod',                                          // used in registration error messages
+  detect: (s) => s instanceof z.ZodType,                // does this adapter recognize the schema?
+  toJsonSchema: (s) => z.toJSONSchema(s as z.ZodType),  // convert to JSON Schema
+}
+
+const { Create } = Procedures({ schema: { adapters: [zodAdapter] } })
+```
+
+The framework only ever needs one thing from a schema object: its JSON Schema. Everything downstream (AJV validation, route docs, codegen) works on JSON Schema.
+
+> **Note:** compile-time type inference (`Infer<T>`) is built in only for TypeBox. Custom adapters get runtime validation and docs, with params inferred as `unknown` unless you annotate handler types yourself.
+
 ### Validation Behavior
 
 AJV is configured with:
@@ -223,21 +271,29 @@ AJV is configured with:
 - `coerceTypes: true` - Automatically coerce types when possible
 - `removeAdditional: true` - Strip properties not in schema
 
+Each factory owns its own AJV compiler. Customize it via the `validation` option — pass AJV options to merge over the defaults, or a fully configured `Ajv` instance to use as-is:
+
+```typescript
+const { Create } = Procedures({
+  validation: { ajv: { coerceTypes: false } },
+})
+```
+
 **Note:** `schema.params` is validated at runtime. `schema.returnType` is for documentation/introspection only.
 
 ### Disabling Runtime Validation
 
-For trusted internal callers — for example, a back-of-house factory whose inputs are already type-checked at build time and whose handlers are never invoked from public HTTP — pass `config.noRuntimeValidation: true` when constructing the factory:
+For trusted internal callers — for example, a back-of-house factory whose inputs are already type-checked at build time and whose handlers are never invoked from public HTTP — pass `validation: false` when constructing the factory:
 
 ```typescript
 const { Create, CreateStream } = Procedures({
-  config: { noRuntimeValidation: true },
+  validation: false,
 })
 ```
 
-When set, every procedure registered by this factory skips AJV validation of `schema.params` and `schema.input` on every call. JSON Schema is still computed at registration time (so `info.schema` and codegen are unaffected) — only the per-call validator runs are bypassed.
+When set, every procedure registered by this factory skips AJV validation of `schema.params` and `schema.req` on every call. JSON Schema and validators are still computed at registration time (so bad schemas fail fast, and `info.schema` and codegen are unaffected) — only the per-call validator runs are bypassed.
 
-**Use sparingly.** Do not enable this for procedures that accept input from public clients, untyped JSON bodies, or anything you do not control end-to-end. The flag is shaped as `noRuntimeValidation?: true` (only `true` is accepted) to make the opt-out explicit at the call site.
+**Use sparingly.** Do not enable this for procedures that accept input from public clients, untyped JSON bodies, or anything you do not control end-to-end.
 
 This is independent of the per-call `ctx.isPrevalidated` escape hatch used by HTTP builders that have already validated upstream — both paths short-circuit the same validators.
 
@@ -267,11 +323,13 @@ Create(
 | Error Class | Trigger |
 |-------------|---------|
 | ProcedureError | `ctx.error()` in handlers |
-| ProcedureValidationError | Schema validation failure (params) |
+| ProcedureValidationError | Schema validation failure (params / req channels) |
 | ProcedureYieldValidationError | Yield validation failure (streaming with `validateYields: true`) |
-| ProcedureRegistrationError | Invalid schema at registration |
+| ProcedureRegistrationError | Invalid schema at registration; duplicate procedure name |
 | `${Service}ProcedureError` (client-side) | Base class for every generated error class on the client — see [Client & Codegen → Typed Error Handling](./client-and-codegen.md#typed-error-handling) |
 
+Every framework error also carries a `kind` field (`'procedure' | 'validation' | 'yield-validation' | 'registration'`) as an alternative to `instanceof` narrowing.
+
 ### Error Properties
 
 ```typescript
@@ -282,6 +340,7 @@ try {
     console.log(e.procedureName) // 'MyProcedure'
     console.log(e.message)       // 'Resource not found'
     console.log(e.meta)          // { id: '123' }
+    console.log(e.kind)          // 'procedure'
   }
 }
 ```
@@ -320,7 +379,7 @@ For streaming abort signal behavior (including `signal.reason` and consumer brea
 
 ### onCreate Callback
 
-Register procedures with a custom framework via the `onCreate` callback. Each registration receives `{ name, handler, config }` so you can wire it into whatever router or framework you want:
+Register procedures with a custom framework via the `onCreate` callback. Each registration receives `{ name, kind, handler, config }` so you can wire it into whatever router or framework you want:
 
 ```typescript
 import { Hono } from 'hono'
@@ -347,7 +406,7 @@ const { Create } = Procedures<{ raw: unknown }>({
 // Procedures are automatically registered as /rpc/GetUser, /rpc/CreateUser, etc.
 ```
 
-For the built-in HTTP integration (RPC, RPC streams, REST, REST streams via `HonoAppBuilder`), see [HTTP Integrations](./http-integrations.md).
+For the built-in HTTP integration (RPC, RPC streams, REST, REST streams via `HonoAppBuilder`), see [HTTP Integrations](./http-integrations.md). To build a full adapter for another framework (route docs, taxonomy dispatch, SSE), use the transport-agnostic [`ts-procedures/server` toolkit](./http-integrations.md#build-your-own-adapter--ts-proceduresserver) instead of hand-rolling everything in `onCreate`.
 
 ### Introspection with getProcedures()
 
@@ -359,12 +418,12 @@ const { Create, getProcedures } = Procedures()
 Create('GetUser', { schema: { params: Type.Object({ id: Type.String() }) } }, async () => {})
 Create('ListUsers', { schema: { params: Type.Object({}) } }, async () => {})
 
-// Get all registered procedures
+// Get all registered procedures (in registration order)
 const procedures = getProcedures()
 
 // Generate OpenAPI spec
-for (const config of procedures) {
-  console.log(`${config.name}:`, config.schema)
+for (const p of procedures) {
+  console.log(`${p.name} (${p.kind}):`, p.config.schema)
 }
 ```
 
@@ -374,7 +433,7 @@ Procedures return handlers that can be called directly in tests:
 
 ```typescript
 import { describe, test, expect } from 'vitest'
-import { Procedures } from 'ts-procedures'
+import { Procedures, ProcedureValidationError } from 'ts-procedures'
 import { Type } from 'typebox'
 
 interface MyCustomContext {
@@ -393,13 +452,13 @@ const { GetUser, info } = Create(
     },
   },
   async (ctx, params) => {
-    if (!params.userName || !ctx.userId) {
+    if (!ctx.userName || !ctx.userId) {
       throw ctx.error('User is not authenticated')
     }
     
     return { 
-      id: params.userId, 
-      name: params?.hideName ? '*******' : params.userName 
+      id: ctx.userId, 
+      name: params?.hideName ? '*******' : ctx.userName 
     }
   },
 )
@@ -432,24 +491,27 @@ describe('GetUser', () => {
 
 ## API Reference
 
-### Procedures(builder?)
+### Procedures(options?)
 
 Creates a procedure factory.
 
 **Parameters:**
-- `builder.config.noRuntimeValidation` - When `true`, every procedure registered through this factory skips AJV validation of `schema.params` and `schema.input` at call time. Default: validation runs. See [Disabling Runtime Validation](#disabling-runtime-validation).
-- `builder.onCreate` - Callback invoked when each procedure is registered
+- `options.validation` - `false` to skip per-call validation for the whole factory (see [Disabling Runtime Validation](#disabling-runtime-validation)), or `{ ajv }` to customize AJV (options merged over defaults, or an `Ajv` instance). Default: validation runs.
+- `options.schema.adapters` - Additional schema-library adapters (see [Other Schema Libraries](#other-schema-libraries--schemaadapter))
+- `options.http` - Factory-level `pathPrefix` / `scope` defaults for `CreateHttp` / `CreateHttpStream`
+- `options.onCreate` - Callback invoked when each procedure is registered
 
 **Returns:**
-- `Create` - Function to define procedures
-- `getProcedures()` - Returns `Array` of all registered procedures
+- `Create` / `CreateStream` / `CreateHttp` / `CreateHttpStream` - Functions to define procedures
+- `getProcedures()` - Returns `Array` of all registered procedures (`{ name, kind, config, handler }`)
+- `getProcedure(name)` / `removeProcedure(name)` / `clear()` - Registry helpers
 
 ### Create(name, config, handler)
 
 Defines a procedure.
 
 **Parameters:**
-- `name` - Unique procedure name (becomes named export)
+- `name` - Unique procedure name (becomes named export; registering the same name twice throws `ProcedureRegistrationError`)
 - `config.description` - Optional description
 - `config.schema.params` - TypeBox schema for params (validated at runtime)
 - `config.schema.returnType` - TypeBox schema for return type (documentation only)
@@ -459,7 +521,7 @@ Defines a procedure.
 **Returns:**
 - `{ [name]: handler }` - Named handler export
 - `procedure` - Generic handler reference
-- `info` - Procedure metadata (name, description, schema, extended-config properties)
+- `info` - Procedure metadata (name, `kind`, description, schema, extended-config properties)
 
 ### Type Exports
 
@@ -474,23 +536,42 @@ import {
   ProcedureRegistrationError,
   ProcedureYieldValidationError,  // For streaming yield validation
 
-  // Types
-  TLocalContext,
-  TStreamContext,               // Streaming context (AbortSignal always present)
+  // Schema utilities (low-level — the factory calls these for you)
+  extractJsonSchema,        // extractJsonSchema(schema, adapters)
+  computeSchema,            // computeSchema(name, schema, { adapters, compile })
+  createValidatorCompiler,  // per-factory AJV compiler (no module singleton)
+  typeboxAdapter,
+  isTypeboxSchema,
+  DEFAULT_AJV_OPTIONS,
+} from 'ts-procedures'
+
+import type {
+  // Factory + registrations
+  ProceduresOptions,
+  ProcedureKind,                    // 'rpc' | 'rpc-stream' | 'http' | 'http-stream'
+  AnyProcedureRegistration,
   TProcedureRegistration,
-  TStreamProcedureRegistration, // Streaming procedure registration
+  TStreamProcedureRegistration,
+  THttpProcedureRegistration,
+  THttpStreamProcedureRegistration,
+  TCreateHttpConfig,
+  TLocalContext,
+  TStreamContext,                   // Streaming context (AbortSignal always present)
   TNoContextProvided,
+  HttpMethod,
+  HttpReturn,
 
-  // Schema utilities
-  extractJsonSchema,
-  schemaParser,
-  isTypeboxSchema,
+  // Errors
+  ProcedureErrorKind,               // 'procedure' | 'validation' | 'yield-validation' | 'registration'
 
   // Schema types
+  SchemaAdapter,
+  ValidationOptions,
+  Validate,
+  ValidatorCompiler,
+  Infer,                            // primary inference type (TypeBox-only)
+  TSchemaLib,                       // alias for Infer (kept for compatibility)
   TJSONSchema,
-  TSchemaLib,
-  TSchemaLibGenerator,          // AsyncGenerator type utility
-  TSchemaParsed,
   TSchemaValidationError,
   Prettify,
 } from 'ts-procedures'

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,7 @@ 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
 
@@ -200,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`
 
@@ -226,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:
@@ -266,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
@@ -285,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'
 ```