ts-procedures 8.5.0 → 9.0.0

package/agent_config/claude-code/skills/ts-procedures/api-reference.md

@@ -1,27 +1,24 @@
 # ts-procedures API Reference
 
-## Procedures\<TContext, TExtendedConfig\>(builder?)
+## Procedures\<TContext, TExtendedConfig\>(options?)
 
 Factory function that creates a scoped procedure registration system.
 
 ```typescript
 function Procedures<TContext = unknown, TExtendedConfig = unknown>(
-  builder?: {
-    config?: {
-      noRuntimeValidation?: true
-    }
-    onCreate?: (procedure: {
-      name: string
-      isStream?: boolean
-      handler: Function
-      config: { description?: string; schema?: object } & TExtendedConfig
-    }) => void
+  options?: {
+    validation?: false | { ajv?: Ajv | AjvOptions }
+    schema?: { adapters?: SchemaAdapter[] }
+    http?: { pathPrefix?: string; scope?: string }
+    onCreate?: (procedure: AnyProcedureRegistration<TContext, TExtendedConfig>) => void
   }
 ): {
   Create: CreateFunction
   CreateStream: CreateStreamFunction
-  getProcedures(): Array<TProcedureRegistration | TStreamProcedureRegistration>
-  getProcedure(name: string): TProcedureRegistration | TStreamProcedureRegistration | undefined
+  CreateHttp: CreateHttpFunction
+  CreateHttpStream: CreateHttpStreamFunction
+  getProcedures(): AnyProcedureRegistration[]
+  getProcedure(name: string): AnyProcedureRegistration | undefined
   removeProcedure(name: string): boolean
   clear(): void
 }
@@ -29,8 +26,10 @@ function Procedures<TContext = unknown, TExtendedConfig = unknown>(
 
 ### Parameters
 
-- `builder.config.noRuntimeValidation` — When `true`, every procedure registered through this factory skips AJV validation at call time. Applies to all four creators: `Create` and `CreateStream` skip `schema.params` validation; `CreateHttp` and `CreateHttpStream` skip per-channel `schema.req.{pathParams,query,body,headers}` validation. JSON Schema is still computed at registration time, so `info.schema` and codegen are unaffected. Shape is `noRuntimeValidation?: true` — only `true` is accepted, making the opt-out explicit. Use only for trusted internal factories whose callers are already type-checked at build time; do **not** enable for procedures that accept input from public clients or untyped JSON bodies.
-- `builder.onCreate` — Called each time a procedure is registered. Use for framework integration, route registration, or logging.
+- `options.validation` — Runtime validation behavior. Omitted: validate every call with the default AJV configuration (`allErrors`, `coerceTypes`, `removeAdditional`). `false`: every procedure registered through this factory skips AJV validation at call time (replaces v8's `config.noRuntimeValidation`). Applies to all four creators: `Create` and `CreateStream` skip `schema.params` validation; `CreateHttp` and `CreateHttpStream` skip per-channel `schema.req.{pathParams,query,body,headers}` validation. JSON Schema and validators are still computed at registration time, so bad schemas still fail fast and `info.schema` / codegen are unaffected. Use only for trusted internal factories whose callers are already type-checked at build time; do **not** enable for procedures that accept input from public clients or untyped JSON bodies. `{ ajv }`: AJV options merged over the defaults, or a configured `Ajv` instance used as-is — AJV is per-factory, not a module-level singleton.
+- `options.schema.adapters` — Plug in other schema libraries via the `SchemaAdapter` interface (`{ name, detect, toJsonSchema }`). TypeBox is built in and always last in the chain. Custom adapters get runtime validation + docs; compile-time inference (`Infer<T>`) is built in only for TypeBox.
+- `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 — it shows up in `config.path` and route docs, unlike a server adapter's mount prefix); `scope` is the default codegen scope for routes that don't set one. Per-route values win.
+- `options.onCreate` — Called each time a procedure is registered with the full registration object (narrow on the `kind` discriminant: `'rpc' | 'rpc-stream' | 'http' | 'http-stream'`). Use for framework integration, route registration, or logging.
 
 ### Return Value
 
@@ -68,13 +67,14 @@ function Create<TName extends string, TParams, TReturnType>(
   } & TExtendedConfig,
   handler: (
     ctx: TContext & TLocalContext,
-    params: TSchemaLib<TParams>
-  ) => Promise<TSchemaLib<TReturnType>>
+    params: Infer<TParams>
+  ) => Promise<Infer<TReturnType>>
 ): {
-  [K in TName]: (ctx: TContext, params: TSchemaLib<TParams>) => Promise<TSchemaLib<TReturnType>>
-  procedure: (ctx: TContext, params: TSchemaLib<TParams>) => Promise<TSchemaLib<TReturnType>>
+  [K in TName]: (ctx: TContext, params: Infer<TParams>) => Promise<Infer<TReturnType>>
+  procedure: (ctx: TContext, params: Infer<TParams>) => Promise<Infer<TReturnType>>
   info: {
     name: TName
+    kind: 'rpc'
     description?: string
     schema: { params?: TJSONSchema; returnType?: TJSONSchema }
     validation?: { params?: (params: any) => { errors?: TSchemaValidationError[] } }
@@ -131,14 +131,14 @@ function CreateStream<TName extends string, TParams, TYieldType, TReturnType = v
   } & TExtendedConfig,
   handler: (
     ctx: TContext & TStreamContext,
-    params: TSchemaLib<TParams>
-  ) => AsyncGenerator<TSchemaLib<TYieldType>, TSchemaLib<TReturnType> | void, unknown>
+    params: Infer<TParams>
+  ) => AsyncGenerator<Infer<TYieldType>, Infer<TReturnType> | void, unknown>
 ): {
-  [K in TName]: (ctx: TContext, params: TSchemaLib<TParams>) => AsyncGenerator<...>
-  procedure: (ctx: TContext, params: TSchemaLib<TParams>) => AsyncGenerator<...>
+  [K in TName]: (ctx: TContext, params: Infer<TParams>) => AsyncGenerator<...>
+  procedure: (ctx: TContext, params: Infer<TParams>) => AsyncGenerator<...>
   info: {
     name: TName
-    isStream: true
+    kind: 'rpc-stream'
     description?: string
     schema: { params?: TJSONSchema; yieldType?: TJSONSchema; returnType?: TJSONSchema }
     validation?: {
@@ -202,7 +202,7 @@ function CreateHttp<
   },
   handler: (
     ctx: TContext & TLocalContext,
-    req: { [K in keyof TReq]: TSchemaLib<TReq[K]> }
+    req: { [K in keyof TReq]: Infer<TReq[K]> }
   ) => Promise<HttpReturn<TRes>>
 ): {
   [K in TName]: typeof handler
@@ -265,6 +265,7 @@ Base error class for all procedure errors.
 
 ```typescript
 class ProcedureError extends Error {
+  readonly kind: ProcedureErrorKind  // 'procedure' | 'validation' | 'yield-validation' | 'registration'
   readonly procedureName: string
   readonly message: string
   readonly meta?: object
@@ -280,6 +281,7 @@ class ProcedureError extends Error {
 - Created via `ctx.error(message, meta?)` in handlers
 - Unhandled handler exceptions are wrapped: original error in `cause`
 - Stack trace enhanced with procedure definition location
+- Every framework error carries a `kind` discriminant (`'procedure' | 'validation' | 'yield-validation' | 'registration'`) as an alternative to `instanceof`; each subclass overrides it
 
 ### ProcedureValidationError extends ProcedureError
 
@@ -308,7 +310,7 @@ class ProcedureYieldValidationError extends ProcedureError {
 
 ### ProcedureRegistrationError extends ProcedureError
 
-Thrown at registration time. Common v8 sources: schema extraction/compilation failure, duplicate procedure name, using the removed v7 `schema.input` field (rejected with a migration message pointing to `CreateHttp` / `CreateHttpStream`), declaring both `schema.params` and `schema.req` on the same procedure (mutually exclusive — RPC vs HTTP), passing `schema.params` to `CreateHttp` / `CreateHttpStream` (use `schema.req.body` or `schema.req.query` instead), and path/schema mismatches on HTTP procedures (path declares params not in `schema.req.pathParams`, or vice versa).
+Thrown at registration time. Common sources: schema extraction/compilation failure, duplicate procedure name (message: `Procedure with name <name> is already registered` — v8 threw a bare `Error` here), using the removed v7 `schema.input` field (rejected with a migration message pointing to `CreateHttp` / `CreateHttpStream`), declaring both `schema.params` and `schema.req` on the same procedure (mutually exclusive — RPC vs HTTP), passing `schema.params` to `CreateHttp` / `CreateHttpStream` (use `schema.req.body` or `schema.req.query` instead), and path/schema mismatches on HTTP procedures (path declares params not in `schema.req.pathParams`, or vice versa).
 
 ```typescript
 class ProcedureRegistrationError extends ProcedureError {
@@ -654,26 +656,56 @@ interface ClassifiedError {
 
 ## Schema Utilities
 
-### extractJsonSchema(libSchema)
+Most users never call these directly — the factory does. They matter when building custom tooling.
+
+### SchemaAdapter
+
+Bridges a schema library to the framework. The framework only ever needs one thing from a schema object: its JSON Schema.
+
+```typescript
+interface SchemaAdapter {
+  name: string                                  // short identifier used in registration error messages
+  detect(schema: unknown): boolean              // does this adapter recognize the schema object?
+  toJsonSchema(schema: unknown): TJSONSchema    // convert a recognized schema to JSON Schema
+}
+```
+
+TypeBox is built in (`typeboxAdapter`); pass custom adapters via `Procedures({ schema: { adapters: [...] } })`. Compile-time inference (`Infer<T>`) works only for TypeBox — custom adapters get runtime validation + docs.
+
+### extractJsonSchema(schema, adapters)
 
-Converts a TypeBox schema to JSON Schema.
+Runs the adapter chain against a schema value.
 
 ```typescript
-function extractJsonSchema(libSchema: unknown): TJSONSchema | undefined
+function extractJsonSchema(schema: unknown, adapters: readonly SchemaAdapter[]): TJSONSchema | undefined
 ```
 
-- TypeBox schemas are valid JSON Schema — returned as-is
-- Returns `undefined` if schema type not recognized
+- Returns the JSON Schema from the first adapter whose `detect` matches
+- TypeBox schemas are valid JSON Schema — returned as-is by `typeboxAdapter`
+- Returns `undefined` if no adapter recognizes the value
 
-### schemaParser(schema, onParseError)
+### computeSchema(name, schema, options)
 
-Compiles schemas into AJV validator functions.
+Computes JSON Schemas and compiled AJV validators for a procedure's schema config (replaces v8's `schemaParser`). Throws `ProcedureRegistrationError` on extraction/compilation failure instead of taking an error callback.
 
 ```typescript
-function schemaParser(
-  schema: { params?: unknown; returnType?: unknown; yieldType?: unknown; input?: Record<string, unknown> },
-  onParseError: (errors: Record<string, string>) => void
-): TSchemaParsed
+function computeSchema(
+  name: string,
+  schema: { params?: unknown; returnType?: unknown; yieldType?: unknown; req?: object; res?: object } | undefined,
+  options: {
+    adapters: readonly SchemaAdapter[]
+    compile: ValidatorCompiler
+    definitionInfo?: DefinitionInfo
+  }
+): ComputedSchema  // { jsonSchema, validations }
+```
+
+### createValidatorCompiler(options?)
+
+Builds a per-factory AJV-backed `ValidatorCompiler` (AJV is no longer a module-level singleton). Defaults (`allErrors`, `coerceTypes`, `removeAdditional`, ajv-formats) live in `DEFAULT_AJV_OPTIONS`.
+
+```typescript
+function createValidatorCompiler(options?: { ajv?: Ajv | AjvOptions }): ValidatorCompiler
 ```
 
 ### isTypeboxSchema(schema)
@@ -684,17 +716,19 @@ Type guard for TypeBox schema detection.
 function isTypeboxSchema(schema: any): schema is TSchema
 ```
 
-### TSchemaLib\<SchemaLibType\>
+### Infer\<SchemaType\>
 
-Maps schema type to inferred TypeScript type:
+Maps schema type to inferred TypeScript type — the primary inference type in v9:
 - TypeBox `TSchema` → `Static<T>`
 - Otherwise → `unknown`
 
+`TSchemaLib<T>` remains exported as a v8-compatible alias.
+
 ---
 
 ## HonoAppBuilder\<TStreamErrorData\>
 
-Unified Hono HTTP implementation for v8. A single builder dispatches all four procedure kinds (`Create` → RPC, `CreateStream` → streaming RPC, `CreateHttp` → REST-style, `CreateHttpStream` → streaming REST) from one `register()` call. Replaces v7's separate `HonoRPCAppBuilder` / `HonoStreamAppBuilder` / `HonoAPIAppBuilder` classes.
+Unified Hono HTTP implementation (public surface unchanged from v8). A single builder dispatches all four procedure kinds (`Create` → RPC, `CreateStream` → streaming RPC, `CreateHttp` → REST-style, `CreateHttpStream` → streaming REST) from one `register()` call. Replaces v7's separate `HonoRPCAppBuilder` / `HonoStreamAppBuilder` / `HonoAPIAppBuilder` classes. The machinery behind it lives in the transport-agnostic `ts-procedures/server` subpath (see below).
 
 Config is **stratified**: cross-cutting fields live at the top level, kind-specific fields live in `rpc:` / `api:` / `stream:` blocks.
 
@@ -799,6 +833,8 @@ function sse<T extends object>(data: T, options?: {
 }): T
 ```
 
+SSE wire behavior is identical for `rpc-stream` and `http-stream` routes (one shared `SseEventSequencer`): `sse()` metadata is honored on both (v8 silently ignored it on `http-stream`), and a `null` yield serializes as empty SSE data on both (v8's `http-stream` wrote the string `null`).
+
 ### HTTP Methods (RPC streams)
 
 For `CreateStream` procedures (RPC-style streams), both GET and POST are registered:
@@ -812,7 +848,7 @@ For `CreateHttpStream`, the method comes from `config.method` (no auto-pairing).
 ```typescript
 type MidStreamErrorResult<TErrorData = unknown> = {
   data: TErrorData       // Data to yield as final event
-  closeStream?: boolean  // Close stream after? (default: true)
+  closeStream?: boolean  // Reserved — the stream currently always closes after dispatch
 }
 ```
 
@@ -884,6 +920,48 @@ Uses `c.req.raw.signal` — native Request signal from Hono context.
 
 For apps that build all routes through one `HonoAppBuilder`, `builder.toDocEnvelope()` returns the full `DocEnvelope` directly — no `DocRegistry` wiring needed. `DocRegistry` is still preferred for multi-app aggregation.
 
+Note (v9 fix): `http-stream` route docs now include the `yield` and `res.headers` schemas — in v8, live envelopes silently dropped them, so generated clients lost those types unless the envelope was hand-authored.
+
+---
+
+## Server Toolkit — `ts-procedures/server` (v9)
+
+Transport-agnostic adapter toolkit: everything a server adapter (Hono, Fastify, Express, ...) needs to serve the four procedure kinds without re-implementing the framework. `src/adapters/hono/` is the reference implementation — a custom adapter is ~4 thin handlers translating between the framework's request/response/streaming primitives and these helpers.
+
+```typescript
+import {
+  // Error dispatch — data-in/data-out (no framework Response objects)
+  dispatchPreStreamError, // → { type: 'body', statusCode, body } | { type: 'response', response }
+  dispatchMidStreamError, // → { data, sseEvent?, sseId?, sseRetry?, runOnCatch? }
+  // Request channel extraction (schema.req → pathParams/query/body/headers)
+  extractReqChannels,     // (source: RequestSource, method, reqSchema, parser) → declared schema.req channels
+  parseQueryNative,
+  // Context resolution
+  resolveFactoryContext,
+  // Route-doc builders (one per procedure kind)
+  buildRpcRouteDoc,
+  buildStreamRouteDoc,
+  buildHttpRouteDoc,
+  buildHttpStreamRouteDoc,
+  // SSE
+  SseEventSequencer,
+  sse,
+  // Docs
+  DocRegistry,
+  writeDocEnvelope,
+} from 'ts-procedures/server'
+```
+
+Key behaviors:
+
+- `dispatchPreStreamError({ err, procedure, raw, cfg })` runs the full pre-stream dispatch order — `onRequestError` observer (awaited, throws swallowed) → taxonomy resolver → imperative `onError` → hard default (`{ error: message }`, 500) — and returns plain data. `{ type: 'body', statusCode, body }` means serialize `body` as JSON with `statusCode`; `{ type: 'response', response }` means the imperative `onError` produced a framework response — send it as-is. (In v8 this helper produced Hono `Response` objects directly.)
+- `RequestSource` is the adapter-neutral request view `extractReqChannels` reads channels from; adapters construct it from their framework's request.
+- `SseEventSequencer` is the single SSE writer shared by `rpc-stream` and `http-stream` routes — event names, id sequencing, `sse()` metadata, and the `event: 'return'` envelope are uniform across both kinds.
+- Taxonomy callbacks' `raw` parameter is typed `unknown` at this layer (it is your framework's request context; cast in your adapter).
+- No framework imports are allowed in this subtree (enforced by test).
+
+The `ts-procedures/http`, `ts-procedures/http-docs`, and `ts-procedures/http-errors` subpaths re-export the same names as v8.
+
 ---
 
 ## HTTP Types
@@ -1422,10 +1500,15 @@ Constraints:
 // Core
 import { Procedures } from 'ts-procedures'
 import type {
+  ProceduresOptions,
+  ProcedureKind,
   TLocalContext,
   TStreamContext,
   TProcedureRegistration,
   TStreamProcedureRegistration,
+  THttpProcedureRegistration,
+  THttpStreamProcedureRegistration,
+  AnyProcedureRegistration,
 } from 'ts-procedures'
 
 // Errors
@@ -1435,12 +1518,11 @@ import {
   ProcedureYieldValidationError,
   ProcedureRegistrationError,
 } from 'ts-procedures'
+import type { ProcedureErrorKind } from 'ts-procedures'
 
 // Schema utilities
-import { extractJsonSchema } from 'ts-procedures'
-import { schemaParser } from 'ts-procedures'
-import { isTypeboxSchema } from 'ts-procedures'
-import type { TSchemaLib, TSchemaLibGenerator, TJSONSchema, TSchemaParsed, TSchemaValidationError } from 'ts-procedures'
+import { extractJsonSchema, computeSchema, createValidatorCompiler, typeboxAdapter, isTypeboxSchema } from 'ts-procedures'
+import type { SchemaAdapter, Infer, TSchemaLib, TJSONSchema, ComputedSchema, TSchemaValidationError } from 'ts-procedures'
 
 // Stack utilities
 import { captureDefinitionInfo, formatDefinitionInfo } from 'ts-procedures'
@@ -1453,6 +1535,20 @@ import type { RPCConfig, RPCHttpRouteDoc, StreamHttpRouteDoc, StreamMode, HttpMe
 // Hono — single unified builder dispatches RPC, HTTP, and streaming kinds
 import { HonoAppBuilder, sse } from 'ts-procedures/hono'
 
+// Server toolkit — transport-agnostic adapter machinery (build your own adapter)
+import {
+  dispatchPreStreamError,
+  dispatchMidStreamError,
+  extractReqChannels,
+  resolveFactoryContext,
+  buildRpcRouteDoc,
+  buildStreamRouteDoc,
+  buildHttpRouteDoc,
+  buildHttpStreamRouteDoc,
+  SseEventSequencer,
+} from 'ts-procedures/server'
+import type { RequestSource } from 'ts-procedures/server'
+
 // Client
 import {
   createClient,

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

@@ -28,12 +28,14 @@
 ### CRITICAL
 - [ ] Uses TypeBox (`Type.Object(...)`, `Type.String()`, etc.) — not plain objects
 - [ ] Required fields use `Type.String()` directly; optional fields wrapped with `Type.Optional(...)`
-- [ ] Does not define both `schema.params` and `schema.input` on the same procedure (mutually exclusive)
+- [ ] Does not define both `schema.params` and `schema.req` on the same procedure (mutually exclusive — RPC vs HTTP)
 
 ### WARNING
 - [ ] Understands AJV `coerceTypes: true` — no manual type parsing for query string values
 - [ ] Understands AJV `removeAdditional: true` — extra fields in params are silently stripped
 - [ ] Does not rely on params fields not in the schema (they get removed)
+- [ ] Factory-level `validation: false` is used only on trusted internal factories — never on factories whose procedures receive caller-supplied JSON (anti-pattern #22)
+- [ ] Non-TypeBox schema libraries go through a registered `SchemaAdapter` (`Procedures({ schema: { adapters } })`), with the caveat that `Infer<T>` only works for TypeBox
 
 ### SUGGESTION
 - [ ] `returnType` schema provided for documentation generation
@@ -101,16 +103,15 @@
 
 ### CRITICAL
 - [ ] `build()` is called synchronously — it returns `Hono`, NOT `Promise<Hono>`. Do not `await` it.
-- [ ] Path param names in route template match `schema.input.pathParams` property names exactly
-- [ ] Does not define both `schema.params` and `schema.input` on the same procedure
+- [ ] Path param names in route template match `schema.req.pathParams` property names exactly
+- [ ] Does not define both `schema.params` and `schema.req` on the same procedure
 - [ ] Custom error classes registered via `defineErrorTaxonomy` + builder `errors` config — not hand-written `onError` ladders
 
 ### WARNING
-- [ ] Uses `schema.input` channels appropriate for the HTTP method (no `body` on GET/HEAD)
+- [ ] Uses `schema.req` channels appropriate for the HTTP method (no `body` on GET/HEAD)
 - [ ] `pathPrefix` set consistently
 - [ ] `successStatus` overridden only when default (POST→201, DELETE→204) is wrong
-- [ ] Uses `APIInput` type constraint (`satisfies APIInput`) to catch channel name typos
-- [ ] `APIConfig<keyof typeof appErrors & string>` used when the app wants compile-time typo protection on per-route `errors: [...]`
+- [ ] `CreateHttp` routes do NOT pass an explicit generic for error-key typo protection (that binds `TName` and breaks `schema.req`/`schema.res` inference) — attach `satisfies (keyof typeof appErrors & string)[]` to the `errors` array instead
 
 ### SUGGESTION
 - [ ] Route documentation accessed via `builder.docs` for OpenAPI generation

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

@@ -33,6 +33,40 @@ const result = await GetUser({ userId: 'u1', requestId: 'r1' }, {})
 
 ---
 
+## Factory Options
+
+All options are optional. `validation: false` replaces v8's `config: { noRuntimeValidation: true }`.
+
+```typescript
+import { Procedures } from 'ts-procedures'
+import type { SchemaAdapter } from 'ts-procedures'
+
+const { Create, CreateHttp } = Procedures<AppContext>({
+  // Skip per-call AJV validation for the whole factory (trusted internal callers only).
+  // Schemas/validators are still computed at registration — bad schemas still fail fast.
+  validation: false,
+
+  // OR customize AJV per factory (options merged over the defaults, or pass an Ajv instance)
+  // validation: { ajv: { coerceTypes: false } },
+
+  // Plug in another schema library (TypeBox is built in).
+  // Runtime validation + docs only — Infer<T> works only for TypeBox.
+  schema: {
+    adapters: [{
+      name: 'zod',
+      detect: (s) => s instanceof z.ZodType,
+      toJsonSchema: (s) => z.toJSONSchema(s as z.ZodType),
+    } satisfies SchemaAdapter],
+  },
+
+  // Factory-level defaults for CreateHttp / CreateHttpStream (per-route values win).
+  // pathPrefix is part of the route's identity — it shows up in config.path and route docs.
+  http: { pathPrefix: '/v1', scope: 'billing' },
+})
+```
+
+---
+
 ## Schema Validation with TypeBox
 
 ```typescript
@@ -585,9 +619,9 @@ const app = new HonoAppBuilder({
 
 ---
 
-## Hono API Integration (REST-style) — v8 `CreateHttp`
+## Hono API Integration (REST-style) — `CreateHttp`
 
-In v8, HTTP routes use `CreateHttp` (and `CreateHttpStream` for streaming). The factory no longer needs an `APIConfig` type parameter; HTTP fields (`path`, `method`, `scope`, `errors`) live on the `CreateHttp` config directly.
+HTTP routes use `CreateHttp` (and `CreateHttpStream` for streaming; both v8+). The factory does not need an `APIConfig` type parameter; HTTP fields (`path`, `method`, `scope`, `errors`) live on the `CreateHttp` config directly.
 
 ```typescript
 import { Procedures } from 'ts-procedures'
@@ -656,7 +690,7 @@ const app = new HonoAppBuilder({
 
 ---
 
-## schema.req — Multi-Channel Structured Input (v8)
+## schema.req — Multi-Channel Structured Input
 
 Use `schema.req` for structured per-channel validation. Channels: `pathParams`, `query`, `body`, `headers`.
 
@@ -689,7 +723,7 @@ API.CreateHttp('UpdateUserField', {
 
 ---
 
-## Response Headers (v8 `CreateHttp`)
+## Response Headers (`CreateHttp`)
 
 The `{ body, headers }` envelope is strictly **opt-in**. By default the handler's return value is serialized verbatim as the response body — the framework does **not** duck-type the result looking for a `body` key. The envelope is only expected when `schema.res.headers` is declared; in that case (and only then) the handler must return `{ body, headers }` instead of the body bare. The client surfaces initial response headers on `TypedStream.headers` for streaming routes.
 
@@ -720,12 +754,15 @@ API.CreateHttp('DownloadReport', {
 ## onCreate Callback for Framework Integration
 
 ```typescript
-const registeredProcedures: TProcedureRegistration[] = []
+import type { AnyProcedureRegistration } from 'ts-procedures'
+
+const registeredProcedures: AnyProcedureRegistration[] = []
 
 const { Create } = Procedures<AppContext>({
   onCreate: (procedure) => {
     registeredProcedures.push(procedure)
-    console.log(`Registered: ${procedure.name}`)
+    // Narrow on the kind discriminant: 'rpc' | 'rpc-stream' | 'http' | 'http-stream'
+    console.log(`Registered: ${procedure.kind} ${procedure.name}`)
   },
 })
 
@@ -736,6 +773,8 @@ const { Create } = Procedures<AppContext>({
 // - Permission registration
 ```
 
+For a full custom server adapter (Fastify, Express, raw http, ...), pair `onCreate`/`getProcedures()` with the transport-agnostic `ts-procedures/server` toolkit — route-doc builders, data-in/data-out error dispatch (`dispatchPreStreamError` / `dispatchMidStreamError`), `RequestSource` channel extraction, and `SseEventSequencer` — so the adapter is thin glue instead of a framework re-implementation. See `api-reference.md § Server Toolkit`.
+
 ---
 
 ## getProcedures() for Introspection

package/agent_config/claude-code/skills/ts-procedures/templates/client.md

@@ -56,7 +56,7 @@ export const {{name}}Client = createApiClient({
 // --- RPC call example ---
 // const user = await {{name}}Client.users.GetUser({ userId: '123' })
 
-// --- API call example (with schema.input channels) ---
+// --- API call example (with schema.req channels) ---
 // const user = await {{name}}Client.users.GetUser({ pathParams: { id: '123' } })
 
 // --- Streaming call example ---

package/agent_config/claude-code/skills/ts-procedures/templates/hono.md

@@ -139,7 +139,7 @@ const {{name}}Errors = defineErrorTaxonomy({
 // One builder, one register() call, all four kinds. Config is stratified by
 // kind: rpc.{onSuccess}, api.{queryParser, onSuccess}, stream.{...}. Cross-cutting
 // concerns (errors, unknownError, onError, onRequestError, onRequestStart/End,
-// pathPrefix) live at the top level. See src/implementations/http/hono/types.ts.
+// pathPrefix) live at the top level. See src/adapters/hono/types.ts.
 
 // Optional observers (uncomment as needed):
 // onRequestStart: (c) => {...}                           // every inbound request (all kinds)