ts-procedures 5.15.0 → 6.0.0

package/README.md

@@ -50,6 +50,8 @@ const user2 = await procedure({}, { userId: '456' })
 
 - **[Client Code Generation](docs/client-and-codegen.md)** — Generate type-safe client SDKs from your server's `DocRegistry`. CLI and programmatic API, adapters, hooks, streaming support, and self-contained mode.
 
+- **[Typed Error Handling](docs/http-integrations.md#error-handling)** — Declarative `defineErrorTaxonomy` maps thrown error classes to HTTP responses across every builder; generated clients throw typed class instances you can catch with `instanceof`.
+
 - **[AI Agent Setup](docs/ai-agent-setup.md)** — Built-in configuration for Claude Code, Cursor, and GitHub Copilot. Auto-updates on `npm install`.
 
 Full documentation is available on [GitHub](https://github.com/thermsio/ts-procedures).

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

@@ -37,7 +37,10 @@ When asked to plan an API or procedure set:
 - AJV is configured with `allErrors: true`, `coerceTypes: true`, `removeAdditional: true`.
 - `schema.params` and `schema.input` are mutually exclusive — defining both throws `ProcedureRegistrationError`.
 - Path param names in route template (`:id`) must match `schema.input.pathParams` property names.
-- Use `DocRegistry` to compose route docs from multiple builders — never manually wire `/docs` endpoints.
+- Use `DocRegistry` to compose route docs from multiple builders — never manually wire `/docs` endpoints. Use `DocRegistry.fromTaxonomy(appErrors)` to seed envelope errors from your taxonomy + framework defaults in one call.
+- Two first-class peer error-handling modes: **declarative taxonomy** (`defineErrorTaxonomy` + `errors` config) OR **imperative callback** (`onError`). Neither is deprecated. Pick the taxonomy for structured apps with typed client dispatch; pick `onError` for simple apps or full response control. Mixing both is allowed — the taxonomy handles what it covers, `onError` handles the tail. The anti-pattern is `instanceof` ladders inside `onError` (see anti-pattern #20 in the skill reference) — that's exactly what the taxonomy expresses declaratively.
+- Per-route `errors: ['UseCaseError', ...]` narrows typed errors on the generated client. Declare via `APIConfig<keyof typeof appErrors & string>` / `RPCConfig<keyof typeof appErrors & string>` for compile-time typo protection.
+- Generated `_errors.ts` emits real runtime classes extending `${Service}ProcedureError` — consumers catch with `instanceof ${Service}Errors.${Name}` and access `err.body`, `err.status`, `err.procedureName`, `err.scope`. Use the generated `create${Service}Client(config)` factory to wire the error registry automatically.
 
 ## Context Design Patterns
 
@@ -120,11 +123,15 @@ type AuthContext = { userId: string; requestId: string; db: Database }
 - POST /api/users (HonoAPIAppBuilder, 201)
 - DELETE /api/users/:id (HonoAPIAppBuilder, 204)
 
-### Error Handling
-- Input validation: automatic (schema.params)
-- Auth failures: ctx.error('Unauthorized', { code: 401 })
-- Not found: ctx.error('User not found', { code: 404 })
-- Stream errors: onMidStreamError -> yield error event, close stream
+### Error Handling (pick a mode, optionally combine)
+- **Declarative mode (recommended for structured apps)**: `defineErrorTaxonomy({ AuthError: {class, 401}, NotFoundError: {class, 404}, ... })` wired via `errors` config. Drives typed client dispatch + DocEnvelope.
+- **Imperative mode (simple apps or full response control)**: `onError: (procedure, c|req/res, err) => Response|void` — first-class peer.
+- `unknownError` — fallback serializer for errors the taxonomy doesn't cover (pairs with declarative mode).
+- `onRequestError` — cross-cutting observer for logging/tracing/metrics. Fires for every error, before dispatch.
+- Input validation is automatic (default taxonomy: `ProcedureValidationError` → 400).
+- Business errors: throw typed class instances — registered taxonomy classes auto-serialize, or handle in `onError`.
+- Per-route: declare `errors: ['AuthError', ...]` on each route config so the generated client narrows `catch` types.
+- Stream pre-errors: both peer modes apply. Mid-stream errors: `onMidStreamError` → yield error event, close stream.
 ```
 
 ## Next Steps

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

@@ -76,9 +76,29 @@ AJV config: `allErrors: true`, `coerceTypes: true`, `removeAdditional: true`
 | `ProcedureValidationError` | Schema params validation failure | `procedureName`, `errors[]` (AJV errors) |
 | `ProcedureYieldValidationError` | Stream yield validation failure | `procedureName`, `errors[]` (AJV errors) |
 | `ProcedureRegistrationError` | Invalid schema at registration time | `procedureName`, `message` |
+| `${Service}ProcedureError` (generated, client) | Base class for all generated client error classes | `status`, `procedureName`, `scope`, `body` |
 
 All errors include `definedAt` (file:line:column) and enhanced stack traces pointing to the procedure definition location.
 
+## Error Taxonomy (HTTP builders)
+
+Declare error classes once with `defineErrorTaxonomy` (from `ts-procedures/http-errors`) and pass to any HTTP builder via the `errors` option. Handlers `throw` their classes; the builder serializes to the configured status + body. This is the declarative peer of the imperative `onError` callback — both modes are first-class.
+
+```typescript
+import { defineErrorTaxonomy } from 'ts-procedures/http-errors'
+
+const appErrors = defineErrorTaxonomy({
+  AuthError:    { class: AuthError,    statusCode: 401 },
+  UseCaseError: { class: UseCaseError, statusCode: 422, toResponse: (e) => ({ message: e.externalMsg }) },
+})
+
+new HonoAPIAppBuilder({ errors: appErrors, unknownError: { toResponse: () => ({ error: '...' }) } })
+```
+
+Per-route narrowing: `APIConfig<keyof typeof appErrors & string>` / `RPCConfig<keyof typeof appErrors & string>` with a `errors: [...]` array on the config. Generated `_errors.ts` emits runtime classes — clients catch with `instanceof ${Service}Errors.${Name}` when using `create${Service}Client`.
+
+Full contract: `docs/http-integrations.md § Error Handling` (canonical) and `api-reference.md § Error Taxonomy API`.
+
 ## HTTP Implementations
 
 | Builder | Import | Transport |
@@ -112,10 +132,11 @@ const app = new ExpressRPCAppBuilder({ pathPrefix: '/api' })
 | `onRequestStart` | Before context resolution |
 | `onRequestEnd` | After response sent |
 | `onSuccess` | After successful handler execution |
-| `onError` | On handler error (return custom response) |
+| `onError` | Imperative error callback — first-class peer of the declarative `errors` taxonomy |
 | `onStreamStart` | Before first yield (HonoStreamAppBuilder) |
 | `onStreamEnd` | After stream closes (HonoStreamAppBuilder) |
-| `onPreStreamError` | Validation/context error before streaming starts |
+| `onError` (HonoStream) | Imperative pre-stream error callback — peer of `errors` taxonomy |
+| `onRequestError` | Cross-cutting observer — fires for every caught error before dispatch |
 | `onMidStreamError` | Error during streaming (return data to yield as final event) |
 
 ## Decision Framework
@@ -150,8 +171,9 @@ The npm package ships user-facing documentation with narrative explanations and
 |------|--------|
 | `docs/core.md` | Procedures factory, Create, CreateStream, schema.input, error handling |
 | `docs/streaming.md` | Streaming procedures, AbortSignal, SSE patterns |
-| `docs/http-integrations.md` | Express RPC, Hono RPC/Stream/API builders, DocRegistry |
-| `docs/client-and-codegen.md` | Client code generation, createClient, CLI options |
+| `docs/http-integrations.md` | Express RPC, Hono RPC/Stream/API builders, **error taxonomy (canonical)**, DocRegistry + `fromTaxonomy` |
+| `docs/client-and-codegen.md` | Client code generation, `createApiClient`/`createClient`, typed error dispatch, per-route `Errors` unions, per-call options, client-level defaults, typed RequestMeta augmentation, CLI options |
+| `CHANGELOG.md` | Release notes — see `[6.0.0]` for the current peer error-handling model (taxonomy + `onError` + `onRequestError`), per-route errors, and client runtime error classes. |
 
 ## Workflow
 

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

@@ -404,19 +404,21 @@ new HonoStreamAppBuilder({
 })
 ```
 
-**Fix:** Use `onPreStreamError` for validation errors and `onMidStreamError` for runtime errors.
+**Fix:** Use either peer mode for pre-stream errors — the declarative taxonomy (`errors` + `unknownError`) or the imperative `onError` callback (renamed from `onPreStreamError` in v6). Mid-stream errors thrown after the first yield always go through `onMidStreamError` since HTTP status is already committed.
 
 ```typescript
 // GOOD
+import { defineErrorTaxonomy } from 'ts-procedures/http-errors'
+
 new HonoStreamAppBuilder({
-  onPreStreamError: (proc, c, error) => {
-    // Validation/context error — return normal HTTP response
-    return c.json({ error: error.message }, 400)
-  },
-  onMidStreamError: (proc, c, error) => {
-    // Runtime error during streaming — yield error event, then close
-    return { data: { error: error.message }, closeStream: true }
-  },
+  // Taxonomy handles all pre-stream errors (validation, auth, context)
+  errors: defineErrorTaxonomy({
+    AuthError: { class: AuthError, statusCode: 401 },
+  }),
+  unknownError: { toResponse: (err) => ({ error: (err as Error).message }) },
+  // Mid-stream still goes through onMidStreamError — the HTTP status is
+  // already committed, so errors become yields, not responses.
+  onMidStreamError: (proc, c, error) => ({ data: { error: error.message }, closeStream: true }),
 })
 ```
 
@@ -496,21 +498,37 @@ builder.register(factory, async (req) => {
 })
 ```
 
-**Fix:** Use the builder's `onError` callback to handle context resolution failures gracefully.
+**Fix:** Throw a typed error class from the context factory and register it in the builder's `errors` taxonomy — the builder auto-serializes.
 
 ```typescript
 // GOOD
-new ExpressRPCAppBuilder({
-  onError: (procedure, req, res, error) => {
-    if (error.message.includes('Unauthorized')) {
-      res.status(401).json({ error: 'Unauthorized' })
-    } else {
-      res.status(500).json({ error: 'Internal server error' })
-    }
+import { defineErrorTaxonomy } from 'ts-procedures/http-errors'
+
+class AuthError extends Error {
+  constructor(message: string) { super(message); this.name = 'AuthError' }
+}
+
+const appErrors = defineErrorTaxonomy({
+  AuthError: {
+    class: AuthError,
+    statusCode: 401,
+    toResponse: () => ({ message: 'Unauthorized' }),
   },
 })
+
+const app = new ExpressRPCAppBuilder({
+  errors: appErrors,
+  unknownError: { toResponse: () => ({ error: 'Internal server error' }) },
+})
+  .register(factory, async (req) => {
+    const user = await authenticate(req.headers.authorization)
+    if (!user) throw new AuthError('invalid token')
+    return { userId: user.id }
+  })
 ```
 
+The imperative `onError: (procedure, req, res, error) => void` callback is a first-class peer — use it for apps that prefer a single response handler or when you want to handle the tail of errors the taxonomy doesn't cover.
+
 ---
 
 ## 18. Using Both schema.params and schema.input
@@ -592,6 +610,55 @@ Create('GetUser', {
 
 ---
 
+## 20. Hand-writing `onError` instanceof ladders
+
+**Problem:** Writing manual `instanceof` ladders inside `onError` to map each error class to a status + body. Every builder gets its own copy; generated clients see opaque `ClientRequestError` objects instead of typed instances; response shapes drift between routes.
+
+```typescript
+// BAD — duplicated across builders, invisible to generated clients
+new HonoAPIAppBuilder({
+  onError: (procedure, c, error) => {
+    if (error instanceof ValidationError) return c.json({ error: error.message }, 400)
+    if (error instanceof AuthError)       return c.json({ error: 'Unauthorized' }, 401)
+    if (error instanceof UseCaseError)    return c.json({ message: error.externalMsg }, 422)
+    return c.json({ error: 'Internal server error' }, 500)
+  },
+})
+```
+
+**Fix:** Declare the taxonomy once with `defineErrorTaxonomy`, pass it via the builder's `errors` config, and handlers `throw` their own classes. The taxonomy also feeds the DocEnvelope so generated clients throw typed class instances.
+
+```typescript
+// GOOD
+import { defineErrorTaxonomy } from 'ts-procedures/http-errors'
+
+const appErrors = defineErrorTaxonomy({
+  ValidationError: { class: ValidationError, statusCode: 400 },
+  AuthError:       { class: AuthError,       statusCode: 401 },
+  UseCaseError:    {
+    class: UseCaseError,
+    statusCode: 422,
+    toResponse: (err) => ({ message: err.externalMsg }),   // `name` auto-injected
+  },
+})
+
+new HonoAPIAppBuilder({
+  errors: appErrors,
+  unknownError: {
+    toResponse: () => ({ error: 'Internal server error' }),
+    onCatch: (err, { procedure }) => logger.error({ procedure: procedure.name, err }),
+  },
+})
+```
+
+The same `errors` / `unknownError` shape plugs into every builder (`HonoAPIAppBuilder`, `HonoRPCAppBuilder`, `ExpressRPCAppBuilder`, `HonoStreamAppBuilder` pre-stream only). `ctx.error()` still works and is caught by the default taxonomy at 500.
+
+**The anti-pattern is the ladder, not `onError`.** `onError` is a first-class peer of the taxonomy — it's perfectly fine for simple apps or when you want full response control. The problem is writing `instanceof` ladders *inside* it to route by error class, because that's exactly what the taxonomy is designed to express declaratively.
+
+**Why:** The taxonomy is declarative (easy to audit), shared across builders, and drives client codegen — the generated `_errors.ts` emits real runtime classes so consumers can `catch (err) { if (err instanceof ApiErrors.UseCaseError) ... }` with full typing.
+
+---
+
 ## Summary Table
 
 | # | Anti-Pattern | Risk | Severity |
@@ -615,3 +682,4 @@ Create('GetUser', {
 | 17 | Unhandled async context factory | Request crashes | WARNING |
 | 18 | Both schema.params and schema.input | ProcedureRegistrationError at startup | CRITICAL |
 | 19 | Mismatched path param names | Build-time error or confusing validation failures | CRITICAL |
+| 20 | Hand-writing onError instanceof ladders | Drifting response shapes, untyped client errors | WARNING |

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

@@ -256,6 +256,125 @@ class ProcedureRegistrationError extends ProcedureError {
 
 ---
 
+## Error Taxonomy API
+
+Exported from `ts-procedures/http-errors` (and re-exported from every HTTP builder subpath: `ts-procedures/hono-api`, `ts-procedures/hono-rpc`, `ts-procedures/express-rpc`, `ts-procedures/hono-stream`).
+
+### defineErrorTaxonomy(entries)
+
+```typescript
+function defineErrorTaxonomy<T extends ErrorTaxonomy>(entries: T): T
+```
+
+Identity helper that:
+1. Validates each entry has exactly one discriminator (`class` xor `match`) — throws otherwise.
+2. Topologically sorts `class:` entries so subclasses always precede base classes regardless of declared order. Predicate (`match:`) entries keep declared order.
+
+### ErrorTaxonomyEntry
+
+```typescript
+type ErrorTaxonomyEntry<TError = any, TBody = unknown> = {
+  class?: new (...args: any[]) => TError          // instanceof discriminator — XOR with `match`
+  match?: (err: unknown) => err is TError         // predicate discriminator — for 3rd-party errors
+  statusCode: number
+  description?: string                             // consumed by DocRegistry
+  schema?: Record<string, unknown>                 // response-body JSON Schema; consumed by DocRegistry
+  toResponse?: (err: TError, meta: { key: string }) => TBody
+  onCatch?: (
+    err: TError,
+    ctx: { procedure: TAnyProcedureRegistration; key: string; raw: unknown }
+  ) => void | Promise<void>
+}
+
+type ErrorTaxonomy = Record<string, ErrorTaxonomyEntry>
+```
+
+When `toResponse` is omitted, the body defaults to `{ name: key, message: err.message }`. When `toResponse` returns an object without a `name` field, the resolver auto-injects `{ name: key }` — wire-protocol consistency is guaranteed.
+
+### defaultErrorTaxonomy
+
+Pre-built taxonomy covering `ProcedureValidationError` (400), `ProcedureYieldValidationError` (500), and direct `ProcedureError` (500, unwrapped throws only — wrapped ones fall through so user taxonomy / `unknownError` sees the real error). Applied as a fallback after the user taxonomy unless `includeDefaults: false`.
+
+### taxonomyToErrorDocs(taxonomy)
+
+```typescript
+function taxonomyToErrorDocs(taxonomy: ErrorTaxonomy): ErrorDoc[]
+```
+
+Converts a taxonomy to the `ErrorDoc[]` format consumed by `DocRegistry.errors` — single source of truth so the documented shape cannot drift from runtime behavior.
+
+### resolveErrorResponse(params)
+
+```typescript
+function resolveErrorResponse(params: {
+  err: unknown
+  userTaxonomy?: ErrorTaxonomy
+  includeDefaults?: boolean              // default true
+  unknownError?: UnknownErrorConfig
+  procedure: TAnyProcedureRegistration
+  raw: unknown
+}): { statusCode: number; body: unknown; runOnCatch: () => Promise<void> } | null
+```
+
+Match order: user taxonomy → default taxonomy (when `includeDefaults`) → `unknownError`. Returns `null` when nothing matches — callers fall through to their builder's imperative `onError` callback and then the hard default. Unwraps `ProcedureError.cause` so user taxonomy matches against the real thrown error, not the wrapper. Side effects (`onCatch`) are deferred into `runOnCatch` so the caller decides when to execute them.
+
+### UnknownErrorConfig
+
+```typescript
+type UnknownErrorConfig = {
+  statusCode?: number                    // default 500
+  toResponse: (err: unknown) => unknown
+  onCatch?: (
+    err: unknown,
+    ctx: { procedure: TAnyProcedureRegistration; raw: unknown }
+  ) => void | Promise<void>
+}
+```
+
+---
+
+## Client Error Registry API
+
+Exported from `ts-procedures/client`. Generated clients hook their `${Service}ErrorRegistry` into `createClient` so non-2xx responses arrive as typed class instances.
+
+### ErrorRegistry / ErrorFactory / ErrorResponseMeta
+
+```typescript
+interface ErrorResponseMeta { status: number; procedureName: string; scope: string }
+interface ErrorFactory { fromResponse(body: unknown, meta: ErrorResponseMeta): Error }
+type ErrorRegistry = Record<string, ErrorFactory>
+```
+
+### dispatchTypedError(registry, body, meta)
+
+```typescript
+function dispatchTypedError(
+  registry: ErrorRegistry | undefined,
+  body: unknown,
+  meta: ErrorResponseMeta
+): Error | null
+```
+
+Returns a typed error instance when:
+- `registry` is defined, AND
+- `body` is an object with a string `name`, AND
+- `registry[body.name].fromResponse(body, meta)` returns an `Error` subclass.
+
+Otherwise returns `null`; callers fall back to `ClientRequestError`.
+
+### CreateClientConfig.errorRegistry
+
+```typescript
+interface CreateClientConfig<TScopes> {
+  // ...existing fields
+  errorRegistry?: ErrorRegistry
+}
+```
+
+Threaded into both `executeCall` and `executeStream`. The generated `create${Service}Client(config)` factory wires this automatically.
+
+---
+
 ## Schema Utilities
 
 ### extractJsonSchema(libSchema)
@@ -308,7 +427,11 @@ class ExpressRPCAppBuilder {
     onRequestStart?: (req: express.Request) => void
     onRequestEnd?: (req: express.Request, res: express.Response) => void
     onSuccess?: (procedure: TProcedureRegistration, req: express.Request, res: express.Response) => void
+    // Error handling — two peer modes plus a cross-cutting observer.
+    errors?: ErrorTaxonomy
+    unknownError?: UnknownErrorConfig
     onError?: (procedure: TProcedureRegistration, req: express.Request, res: express.Response, error: Error) => void
+    onRequestError?: (ctx: OnRequestErrorContext) => void | Promise<void>
   })
 
   register<TFactory>(
@@ -326,6 +449,8 @@ class ExpressRPCAppBuilder {
 }
 ```
 
+`OnRequestErrorContext` for Express: `{ err: unknown; procedure: TProcedureRegistration; raw: { req, res } }`.
+
 ### Route Path
 
 `POST {pathPrefix}/{scope}/{kebab-name}/{version}`
@@ -357,7 +482,11 @@ class HonoRPCAppBuilder {
     onRequestStart?: (c: Context) => void
     onRequestEnd?: (c: Context) => void
     onSuccess?: (procedure: TProcedureRegistration, c: Context) => void
+    // Error handling — two peer modes plus a cross-cutting observer.
+    errors?: ErrorTaxonomy
+    unknownError?: UnknownErrorConfig
     onError?: (procedure: TProcedureRegistration, c: Context, error: Error) => Response | Promise<Response>
+    onRequestError?: (ctx: OnRequestErrorContext) => void | Promise<void>
   })
 
   register<TFactory>(
@@ -372,6 +501,8 @@ class HonoRPCAppBuilder {
 }
 ```
 
+`OnRequestErrorContext` for Hono RPC: `{ err: unknown; procedure: TProcedureRegistration; raw: Context }`.
+
 ### Signal Injection
 
 Uses `c.req.raw.signal` — the native Request signal from the Hono context.
@@ -392,7 +523,10 @@ class HonoStreamAppBuilder<TErrorData = unknown> {
     onRequestEnd?: (c: Context) => void
     onStreamStart?: (procedure: TStreamProcedureRegistration, c: Context, streamMode: StreamMode) => void
     onStreamEnd?: (procedure: TStreamProcedureRegistration, c: Context, streamMode: StreamMode) => void
-    onPreStreamError?: (procedure: TStreamProcedureRegistration, c: Context, error: Error) => Response | Promise<Response>
+    errors?: ErrorTaxonomy
+    unknownError?: UnknownErrorConfig
+    onError?: (procedure: TStreamProcedureRegistration, c: Context, error: Error) => Response | Promise<Response>  // renamed from onPreStreamError in v6
+    onRequestError?: (ctx: { err: unknown; procedure: TStreamProcedureRegistration; raw: Context }) => void | Promise<void>
     onMidStreamError?: (procedure: TStreamProcedureRegistration, c: Context, error: Error) => MidStreamErrorResult<TErrorData> | undefined
   })
 
@@ -451,8 +585,8 @@ type MidStreamErrorResult<TErrorData = unknown> = {
 
 ### Error Handling
 
-- **Pre-stream errors** (validation, context): Returns JSON error response (no streaming started). Custom handling via `onPreStreamError`.
-- **Mid-stream errors** (generator throws): Yields error as final event, closes stream. Custom handling via `onMidStreamError`.
+- **Pre-stream errors** (validation, context): Returns a JSON error response (no streaming started). Handle via either peer mode — `errors` taxonomy or `onError` callback. Observe via `onRequestError`.
+- **Mid-stream errors** (generator throws): Yields error as final event, closes stream. Handle via `onMidStreamError` (the only mid-stream path — the HTTP status is already committed).
 
 ---
 
@@ -469,7 +603,11 @@ class HonoAPIAppBuilder {
     onRequestStart?: (c: Context) => void
     onRequestEnd?: (c: Context) => void
     onSuccess?: (procedure: TProcedureRegistration, c: Context) => void
+    // Error handling — two peer modes plus a cross-cutting observer.
+    errors?: ErrorTaxonomy
+    unknownError?: UnknownErrorConfig
     onError?: (procedure: TProcedureRegistration, c: Context, error: Error) => Response | Promise<Response>
+    onRequestError?: (ctx: OnRequestErrorContext) => void | Promise<void>
   })
 
   register<TFactory>(
@@ -484,6 +622,8 @@ class HonoAPIAppBuilder {
 }
 ```
 
+`OnRequestErrorContext` for Hono API: `{ err: unknown; procedure: TProcedureRegistration; raw: Context }`.
+
 ### Route Path
 
 Developer-defined via `APIConfig.path` — no auto-generation. Supports Hono path params (`:id`).
@@ -553,9 +693,12 @@ Uses `c.req.raw.signal` — native Request signal from Hono context.
 ### RPCConfig
 
 ```typescript
-interface RPCConfig {
+// Generic over valid taxonomy keys. Default TErrorKey = string (permissive).
+// Narrow via `RPCConfig<keyof typeof appErrors & string>` for compile-time typo protection.
+interface RPCConfig<TErrorKey extends string = string> {
   scope: string | string[]
   version: number
+  errors?: TErrorKey[]   // Taxonomy keys this procedure may emit (informational; populates DocEnvelope).
 }
 ```
 
@@ -570,6 +713,7 @@ interface RPCHttpRouteDoc extends RPCConfig {
     body?: Record<string, unknown>
     response?: Record<string, unknown>
   }
+  errors?: string[]      // Per-route subset, populated from config.errors.
 }
 ```
 
@@ -586,16 +730,20 @@ interface StreamHttpRouteDoc extends RPCConfig {
     yieldType?: Record<string, unknown>
     returnType?: Record<string, unknown>
   }
+  errors?: string[]
 }
 ```
 
 ### APIConfig
 
 ```typescript
-interface APIConfig {
+// Generic over valid taxonomy keys — same pattern as RPCConfig.
+interface APIConfig<TErrorKey extends string = string> {
   path: string
   method: 'get' | 'post' | 'put' | 'delete' | 'patch' | 'head'
   successStatus?: number
+  scope?: string
+  errors?: TErrorKey[]
 }
 ```
 
@@ -612,6 +760,7 @@ interface APIHttpRouteDoc extends APIConfig {
     headers?: Record<string, unknown>
     response?: Record<string, unknown>
   }
+  errors?: string[]
 }
 ```
 
@@ -660,7 +809,16 @@ class DocRegistry {
     transform?: (envelope: DocEnvelope) => T
   }): T
 
+  // Framework error defaults derived from defaultErrorTaxonomy — single source
+  // of truth so runtime and documented shapes cannot drift.
   static defaultErrors(): ErrorDoc[]
+
+  // Convenience: seed envelope errors from a taxonomy + framework defaults
+  // in one call (deduped — user entries win when keys overlap).
+  static fromTaxonomy(
+    taxonomy: ErrorTaxonomy,
+    config?: Omit<DocRegistryConfig, 'errors'> & { includeDefaults?: boolean }
+  ): DocRegistry
 }
 ```
 
@@ -732,6 +890,7 @@ function createClient<TScopes>(config: {
   basePath: string
   scopes: (client: ClientInstance) => TScopes
   hooks?: ClientHooks
+  defaults?: ProcedureCallDefaults
 }): TScopes
 ```
 
@@ -740,7 +899,8 @@ function createClient<TScopes>(config: {
 - `config.adapter` — Transport adapter implementing `ClientAdapter`. Use `createFetchAdapter()` for fetch-based transport.
 - `config.basePath` — Base URL prepended to all request paths (e.g., `'http://localhost:3000'`).
 - `config.scopes` — Factory function that receives a raw `ClientInstance` and returns the typed scope object. The generated `create${ServiceName}Bindings` export (defaults to `createApiBindings`; pass `--service-name <Name>` to rename).
-- `config.hooks` — Optional global hooks applied to every call. Can be overridden per call.
+- `config.hooks` — Optional global hooks applied to every call. Per-call hooks (passed via the options bag) run *after* global hooks — they stack, not replace.
+- `config.defaults` — Optional default request options (timeout, signal, headers, basePath) applied to every call. Overridden by per-call options.
 
 ### Return Value
 
@@ -750,11 +910,51 @@ Returns the result of `config.scopes(clientInstance)` — a typed object where e
 
 ```typescript
 interface ClientHooks {
-  onBeforeRequest?: (ctx: { request: ClientRequest }) => { request: ClientRequest } | void
-  onAfterResponse?: (ctx: { request: ClientRequest; response: ClientResponse }) => void
+  onBeforeRequest?: (ctx: BeforeRequestContext) => BeforeRequestContext | Promise<BeforeRequestContext>
+  onAfterResponse?: (ctx: AfterResponseContext) => void | Promise<void>
+  onError?: (ctx: ErrorContext) => void | Promise<void>
 }
 ```
 
+### ProcedureCallDefaults / ProcedureCallOptions
+
+`ProcedureCallDefaults` is the shape used at `config.defaults` and is a strict subset of `ProcedureCallOptions` (per-call options). `ProcedureCallOptions` additionally includes the `ClientHooks` fields so a single options bag covers both request config and hooks.
+
+```typescript
+interface ProcedureCallDefaults {
+  signal?: AbortSignal         // cancel signal (combined with per-call via AbortSignal.any)
+  timeout?: number              // ms — per-call timeout:0 disables an inherited default
+  headers?: Record<string, string>  // merged (per-call keys win)
+  basePath?: string             // per-call > default > config.basePath
+  meta?: RequestMeta            // typed per-request metadata (see RequestMeta below)
+}
+
+interface ProcedureCallOptions extends ProcedureCallDefaults, ClientHooks {}
+```
+
+### RequestMeta (typed per-request metadata)
+
+`RequestMeta` is an empty interface designed for TypeScript declaration merging. Augment it in your project to type the `meta` field end-to-end (per-call options, hook contexts, and the adapter).
+
+```typescript
+// Self-contained (code-generated) client
+declare module './generated/_types' {
+  interface RequestMeta {
+    traceId: string
+    priority?: 'high' | 'low'
+  }
+}
+
+// Or when using ts-procedures/client directly
+declare module 'ts-procedures/client' {
+  interface RequestMeta {
+    traceId: string
+  }
+}
+```
+
+After augmentation, `request.meta` is typed in adapters, hooks, defaults, and per-call options. If `RequestMeta` declares required fields, supply them via `defaults.meta` or per-call `options.meta` — the merged shape must satisfy them at runtime.
+
 ### Example
 
 ```typescript
@@ -765,6 +965,7 @@ const client = createClient({
   adapter: createFetchAdapter(),
   basePath: 'http://localhost:3000',
   scopes: createApiBindings,
+  defaults: { timeout: 30_000, headers: { 'X-Client-Version': '1.0.0' } },
   hooks: {
     onBeforeRequest(ctx) {
       ctx.request.headers = { ...ctx.request.headers, Authorization: `Bearer ${getToken()}` }
@@ -773,7 +974,17 @@ const client = createClient({
   },
 })
 
-const user = await client.users.GetUser({ pathParams: { id: '123' } })
+// Per-call timeout + signal + hooks — all in one options bag
+const controller = new AbortController()
+const user = await client.users.GetUser(
+  { pathParams: { id: '123' } },
+  {
+    timeout: 5000,
+    signal: controller.signal,
+    headers: { 'X-Request-Id': crypto.randomUUID() },
+    onAfterResponse(ctx) { log(ctx) },
+  },
+)
 
 // Reach types via the namespace: Api.Users.GetUser.Params, Api.Errors.ProcedureError
 ```