ts-procedures 8.5.0 → 9.0.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()))
@@ -267,7 +267,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 +489,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
@@ -650,4 +650,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.
 
 ---
 
@@ -88,6 +88,66 @@ The `else { throw err }` rethrow at the end is intentional: any error that slips
 
 ---
 
+## 3a. Discoverability: where the types live and how to reach them
+
+Two capabilities are easy to miss because they need no extra imports or wrappers — they fall out of the generated code directly. This section is purely about *finding and using* them.
+
+### Narrowing declared errors on the throwing path
+
+You do **not** need `.safe()` to narrow typed errors — the throwing path is fully typed. Declared route errors are **real runtime classes**, so they narrow with the same `try/catch` + `instanceof` pattern shown in §3 (`err instanceof ApiErrors.Conflict`), right alongside the framework transport classes — there's no separate API to learn.
+
+What makes them *discoverable*: when a server route declares `errors`, codegen also emits that route's error union as a **named type you can hover and import**, so you can see which classes a call may throw without leaving your editor:
+
+- **Namespace mode** (default): `Scope.Route.Errors` — e.g. `Api.Users.CreateUser.Errors`.
+- **Flat mode** (`--no-namespace-types`): `RouteErrors` — e.g. `CreateUserErrors`.
+
+The classes themselves are the `${ServiceName}Errors` namespace (default `ApiErrors`) — the same one §3 catches against — and each class name matches the taxonomy key declared on the server. The callable's JSDoc names the union inline too: hovering a declared-error route shows `@throws Declared typed errors: {@link Api.Users.CreateUser.Errors} — narrow on the throwing path (§3), or call .safe() for a Result`.
+
+Routes that declare *no* errors omit the `Errors` type (and the `kind: 'typed'` arm on `.safe()`) entirely, so their absence is discoverable too. `.safe()` (§4) stays available whenever you'd rather branch on a returned `Result` than catch.
+
+### Per-call options (signal, timeout, headers, basePath)
+
+Every generated callable takes an **optional second argument**: a `ProcedureCallOptions` bag. It is the per-call seam for cancellation, deadlines, headers, and base-path overrides — no client reconfiguration required.
+
+```ts
+export interface ProcedureCallDefaults {
+  signal?: AbortSignal     // cancel this call (combines with any client-default signal)
+  timeout?: number         // ms; per-call 0 disables an inherited default timeout
+  headers?: ClientHeadersInit  // record or (async) () => record; merges over defaults
+  basePath?: string        // override the base path for this call only
+  meta?: RequestMeta       // typed per-request metadata (declaration-merged)
+}
+// ProcedureCallOptions = ProcedureCallDefaults + per-call hooks
+```
+
+The most common case is threading an `AbortSignal` so the request cancels when the caller is torn down (component unmount, route change, a newer request superseding an in-flight one):
+
+```ts
+const controller = new AbortController()
+
+// Cancel on unmount / navigation:
+const cleanup = () => controller.abort()
+
+const user = await api.users.CreateUser(
+  { email, displayName },
+  { signal: controller.signal },
+)
+```
+
+When the signal fires, the in-flight call rejects with `ClientAbortError` (or resolves to `kind: 'aborted'` under `.safe()`), which you typically treat as silent. A per-call `timeout` fires `ClientTimeoutError` the same way:
+
+```ts
+// A deliberately slow endpoint gets a longer deadline, just for this call:
+const report = await api.reports.GenerateReport(
+  { range },
+  { timeout: 60_000, signal: controller.signal },
+)
+```
+
+Per-call options layer over client-wide `defaults` (set via `createApiClient({ defaults })`): headers and `meta` merge (per-call keys win), signals combine via `AbortSignal.any` (whichever aborts first wins), and per-call `timeout` overrides the default — with `timeout: 0` opting out of an inherited default entirely. Options are applied before hooks, so an `onBeforeRequest` hook still has the final say. For the full precedence table and the rotating-token `headers` function form, see [`docs/client-and-codegen.md`](./client-and-codegen.md).
+
+---
+
 ## 4. `.safe()` Form: Exhaustive Narrowing
 
 The same operation rewritten with `.safe()`. The call never rejects. `r.ok` is the top-level gate; `r.kind` narrows the failure:
@@ -248,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.
 
@@ -352,6 +412,33 @@ 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)
+
+---
+
+## 11. Design note: typed errors and your state layer
+
+ts-procedures throws real, `instanceof`-catchable error classes. On the throwing path you `catch (err)` and narrow with `instanceof` (§3); with `.safe()` you get the same instances inside a `Result` (§4). Either way, the actual thrown value reaches your handler intact — that is the headline of this client's error model, and nothing below qualifies it.
+
+### Where the boundary sits
+
+A state-management layer that sits between the call and your UI (for example, an async-task tracker in an MVC/store library) sometimes records a failure as a flattened, closed code union — mapping every rejection down to a `string` code or a single `error` enum before your view layer sees it. When that happens, the typed instance is intact when ts-procedures throws it, and lossy by the time your component reads task state. The narrowing in §3/§4 still works at the call site; what changes is what survives storage in the layer above.
+
+That flattening is a property of the state layer, not of the transport. ts-procedures has already done its job: it produced an instance you can narrow. The fix — preserving the original thrown value (or its `cause`) on the task state so the UI can still narrow with `instanceof` — belongs to the state layer, which owns that storage decision.
+
+### Why the client does not add a transform hook
+
+It would be possible to add a client-level "error map" or transform hook that pre-shapes thrown errors into whatever a given state layer expects. We have deliberately chosen not to, for two reasons:
+
+1. **It would erase the win.** The value of typed errors is that the *original instance* reaches you. A transform that reshapes errors at the transport boundary to satisfy a downstream consumer is the same flattening, just moved one layer earlier — every other consumer of the same client would inherit a lossy shape to accommodate one state layer.
+2. **The seam already exists, and it is an observer by design.** The `onError` hook (`ClientHooks.onError`) is typed to return `void` — it is a cross-cutting observer for telemetry, not a mutator. The error it observes is the same instance the client then throws; the hook cannot rewrite it, and that is intentional. Both call paths re-throw the original: the typed registry match is thrown as-is (tagged only with an internal `__tsProceduresTyped` marker so `.safe()` can label its `kind`), and the classified adapter error is thrown as the normalized framework instance. The transport's contract is "you get the instance"; honoring that means not reshaping it on the way out.
+
+### What to do instead
+
+- **Catch at the call site.** Narrow with `instanceof` on the throwing path (§3), or read `Result.error` from `.safe()` (§4), before the value enters a state layer that might flatten it.
+- **Carry the original through your state layer.** If your tracker stores a flattened code, also store the original thrown value (or `error.cause`) alongside it, and narrow against that in the UI. Every framework class carries `cause` for exactly this kind of pass-through (§2).
+- **If your state layer can't carry it, that's where the change goes.** Surfacing the original error on task state is a state-layer concern. ts-procedures will keep throwing the instance; preserving it across the storage boundary is the layer that owns that boundary's responsibility.
+
+This keeps each layer's contract clean: the client guarantees a typed, narrowable instance at the throw site, and the state layer decides how much of it to retain.

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'