ts-procedures 5.15.0 → 6.0.0

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

@@ -103,6 +103,166 @@ const { TransferFunds } = Create(
 
 ---
 
+## Error Taxonomy (declarative error-to-response mapping)
+
+`defineErrorTaxonomy` replaces `instanceof` ladders inside `onError`. Register error classes once with their status code and serializer, pass to any HTTP builder. Works across `hono-api`, `hono-rpc`, `express-rpc`, and `hono-stream` pre-stream (mid-stream still uses `onMidStreamError`).
+
+```typescript
+import { defineErrorTaxonomy } from 'ts-procedures/http-errors'
+import { HonoAPIAppBuilder } from 'ts-procedures/hono-api'
+
+class UseCaseError extends Error {
+  constructor(readonly externalMsg: string, readonly internalMsg: string) {
+    super(externalMsg); this.name = 'UseCaseError'
+    Object.setPrototypeOf(this, UseCaseError.prototype)
+  }
+}
+
+const appErrors = defineErrorTaxonomy({
+  AuthError: { class: AuthError, statusCode: 401 },  // default toResponse → { name, message }
+  UseCaseError: {
+    class: UseCaseError,
+    statusCode: 422,
+    toResponse: (err) => ({ message: err.externalMsg }),  // `name: 'UseCaseError'` auto-injected
+    onCatch: (err, { procedure }) => logger.error({ procedure: procedure.name, internal: err.internalMsg }),
+  },
+  // 3rd-party / non-subclassable errors — use `match:`
+  MongoDuplicateKey: {
+    match: (err): err is Error & { code: number } =>
+      err instanceof Error && (err as any).code === 11000,
+    statusCode: 409,
+    toResponse: () => ({ message: 'Resource already exists' }),
+  },
+})
+
+new HonoAPIAppBuilder({
+  errors: appErrors,
+  unknownError: {
+    toResponse: () => ({ name: 'InternalServerError', message: 'Unexpected error' }),
+    onCatch: (err, { procedure }) => logger.error({ procedure: procedure.name, err }),
+  },
+}).register(API, (c) => ({ requestId: c.req.header('x-request-id') })).build()
+```
+
+Handlers throw directly — no try/catch, no ladders:
+
+```typescript
+API.Create('GetUser', { /* ... */ }, async (ctx, { pathParams }) => {
+  const user = await usersRepo.findById(pathParams.id)
+  if (!user) throw new UseCaseError('User not found', `repo returned null for ${pathParams.id}`)
+  return user
+})
+```
+
+Key rules:
+
+- `defineErrorTaxonomy` topologically sorts `class:` entries so a subclass always resolves before its base — declaration order inside the helper no longer matters for inheritance chains. `match:` entries keep declared order.
+- The core wraps any non-`ProcedureError` thrown from a handler into a `ProcedureError` with `.cause` set. The resolver unwraps this automatically so your taxonomy sees the real class.
+- Two peer modes: declarative (`errors` + `unknownError`) or imperative (`onError`). Both are first-class. When neither is configured, the builder falls through to a hard default (`{ error: message }`, 500).
+- `onCatch`'s `raw` is the framework request object (Hono `Context` / `{ req, res }` for Express) typed as `unknown` — cast at the use site.
+
+### Per-route error declaration (typed)
+
+Narrow `APIConfig` / `RPCConfig` to your taxonomy's keys for compile-time typo protection, and declare which errors each procedure may emit. These populate the DocEnvelope per-route so generated clients can type `catch` blocks precisely.
+
+```typescript
+import { APIConfig } from 'ts-procedures/http'
+import { appErrors } from './errors/taxonomy'
+
+type MyAPIConfig = APIConfig<keyof typeof appErrors & string>
+
+const API = Procedures<Ctx, MyAPIConfig>()
+
+API.Create('GetUser', {
+  path: '/users/:id',
+  method: 'get',
+  errors: ['UseCaseError', 'AuthError'],  // typed against taxonomy keys; typos are TS errors
+  schema: { /* ... */ },
+}, async (ctx, params) => { /* ... */ })
+```
+
+Seed the DocEnvelope with both taxonomy errors and framework defaults in one call:
+
+```typescript
+import { DocRegistry } from 'ts-procedures/http-docs'
+
+const envelope = DocRegistry.fromTaxonomy(appErrors, { basePath: '/api' })
+  .from(apiApp)
+  .from(rpcApp)
+  .toJSON()
+// envelope.errors: all registered + framework defaults (deduped)
+// envelope.routes[i].errors: per-route subset declared on config.errors
+```
+
+### Typed catch blocks on the client (via codegen)
+
+The codegen emits runtime error classes (not just types) and a registry object. `createApiClient` wires the registry automatically so non-2xx responses arrive as typed class instances.
+
+Generated client (simplified):
+
+```typescript
+// Generated _errors.ts
+export namespace ApiErrors {
+  export class ApiProcedureError<TBody> extends Error { /* ... */ }
+  export class UseCaseError extends ApiProcedureError<UseCaseErrorBody> {
+    static fromResponse(body, meta): UseCaseError { /* ... */ }
+  }
+  export const ApiErrorRegistry = { UseCaseError, AuthError, /* ... */ }
+}
+
+// Generated index.ts
+export function createApiClient(config) {
+  return createClient({ ...config, errorRegistry: ApiErrors.ApiErrorRegistry, scopes: createApiBindings })
+}
+```
+
+Consumer code:
+
+```typescript
+import { createApiClient, ApiErrors, createFetchAdapter } from './generated'
+
+const api = createApiClient({
+  adapter: createFetchAdapter({ /* ... */ }),
+  basePath: 'https://api.example.com',
+})
+
+try {
+  const user = await api.users.getUser({ pathParams: { id: 'u_123' } })
+} catch (err) {
+  if (err instanceof ApiErrors.UseCaseError) {
+    // err.message is typed; err.body is typed to UseCaseErrorBody;
+    // err.status, err.procedureName, err.scope are available.
+  } else if (err instanceof ApiErrors.ApiProcedureError) {
+    // Catch-all for any generated service error.
+  } else {
+    // Transport error (network, non-JSON body) — still a ClientRequestError.
+  }
+}
+```
+
+Per-route error narrowing: when a route declares `errors: [...]`, the generated scope file emits an `Errors` type union the consumer can use to annotate their catch:
+
+```typescript
+// Generated scope file includes:
+export namespace Users {
+  export namespace GetUser {
+    export type Params = { /* ... */ }
+    export type Response = { /* ... */ }
+    export type Errors = ApiErrors.UseCaseError | ApiErrors.AuthError
+  }
+}
+
+// Consumer:
+catch (err: unknown) {
+  // Cast is manual today (TS has no typed throws); the union documents
+  // which errors this specific route can throw.
+  const e = err as Users.GetUser.Errors | ClientRequestError
+  if (e instanceof ApiErrors.UseCaseError) { /* ... */ }
+}
+```
+
+---
+
 ## Stream Procedures
 
 ```typescript
@@ -275,15 +435,13 @@ const { UpdateUser } = Create(
   async (ctx, params) => updateUser(params)
 )
 
-// 2. Build Express app
+// 2. Build Express app — the taxonomy handles framework errors (ProcedureValidationError
+// maps to 400 by default) and anything the app throws; unknownError is the last resort.
 const app = new ExpressRPCAppBuilder({
   pathPrefix: '/api',
-  onError: (procedure, req, res, error) => {
-    if (error instanceof ProcedureValidationError) {
-      res.status(400).json({ error: error.message, details: error.errors })
-    } else {
-      res.status(500).json({ error: error.message })
-    }
+  errors: appErrors,   // from defineErrorTaxonomy({ ... })
+  unknownError: {
+    toResponse: (err) => ({ error: (err as Error).message }),
   },
 })
   .register(
@@ -437,11 +595,9 @@ API.Create('DeleteUser', {
 
 const app = new HonoAPIAppBuilder({
   pathPrefix: '/api',
-  onError: (procedure, c, error) => {
-    if (error instanceof ProcedureValidationError) {
-      return c.json({ error: error.message, details: error.errors }, 400)
-    }
-    return c.json({ error: error.message }, 500)
+  errors: appErrors,   // taxonomy maps error classes to statuses/bodies; ProcedureValidationError → 400 by default
+  unknownError: {
+    toResponse: (err) => ({ error: (err as Error).message }),
   },
 })
   .register(API, (c) => ({
@@ -754,7 +910,7 @@ onRequestStart → factoryContext() → handler() → onSuccess → onRequestEnd
 ### Streaming (HonoStreamAppBuilder)
 ```
 onRequestStart → factoryContext() → params validation
-                                  → onPreStreamError (if invalid) → onRequestEnd
+                                  → onError (if invalid) → onRequestEnd
                                   → onStreamStart → handler yields → onStreamEnd → onRequestEnd
                                                   → onMidStreamError (if throw) → onStreamEnd → onRequestEnd
 ```
@@ -841,10 +997,11 @@ const result = await stream.result // Typed as WatchNotificationsReturn
 
 ---
 
-## Per-Procedure Hook Override
+## Per-Procedure Hooks
+
+Per-call hooks run *after* global hooks (they don't replace them). They live in the same options bag as `timeout`, `signal`, `headers`, etc.
 
 ```typescript
-// Override hooks for a specific call
 await client.users.GetUser({ pathParams: { id: '123' } }, {
   onAfterResponse(ctx) {
     const rateLimit = ctx.response.headers['x-rate-limit-remaining']
@@ -855,6 +1012,102 @@ await client.users.GetUser({ pathParams: { id: '123' } }, {
 
 ---
 
+## Per-Call Request Options (timeout, signal, headers, basePath)
+
+Every generated callable takes an optional second argument for per-call config. The options bag covers both request-level config and hooks.
+
+```typescript
+// Timeout — aborts the request after 5 seconds
+const user = await client.users.GetUser({ pathParams: { id: '123' } }, { timeout: 5000 })
+
+// Cancellation — supply your own AbortSignal
+const controller = new AbortController()
+const user = await client.users.GetUser(
+  { pathParams: { id: '123' } },
+  { signal: controller.signal },
+)
+
+// Extra per-call headers
+await client.users.GetUser(
+  { pathParams: { id: '123' } },
+  { headers: { 'X-Request-Id': crypto.randomUUID() } },
+)
+
+// Override base path for a single call (multi-region, dev/prod switching)
+await client.users.GetUser(
+  { pathParams: { id: '123' } },
+  { basePath: 'https://api-eu.example.com' },
+)
+```
+
+---
+
+## Client-Level Defaults
+
+Set defaults via `config.defaults` — applied to every call, overridden by per-call options. Headers merge (per-call keys win); `signal` combines via `AbortSignal.any` (whichever aborts first wins); per-call `timeout: 0` disables an inherited default timeout.
+
+```typescript
+const client = createClient({
+  adapter: createFetchAdapter(),
+  basePath: 'http://localhost:3000',
+  scopes: createApiBindings,
+  defaults: {
+    timeout: 30_000,
+    headers: { 'X-Client-Version': '1.0.0' },
+  },
+})
+```
+
+---
+
+## Typed Per-Request Meta (RequestMeta Augmentation)
+
+`AdapterRequest.meta` is typed via the `RequestMeta` interface — declared empty so developers augment it via TypeScript declaration merging. Augmented fields are then typed end-to-end: per-call options, hook contexts, and 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, meta is typed everywhere:
+await client.users.GetUser(
+  { pathParams: { id: '123' } },
+  { meta: { traceId: 'req-abc', priority: 'high' } },  // typed
+)
+
+// Typed in hooks
+hooks: {
+  onBeforeRequest(ctx) {
+    const trace = ctx.request.meta?.traceId   // string | undefined
+    return ctx
+  },
+}
+
+// Typed in adapters
+const adapter: ClientAdapter = {
+  async request(req) {
+    const priority = req.meta?.priority       // 'high' | 'low' | undefined
+    return { status: 200, headers: {}, body: {} }
+  },
+  async stream(req) { /* ... */ },
+}
+```
+
+If `RequestMeta` declares required fields, supply them in `defaults.meta` or per-call `options.meta` — the merged shape must contain them at runtime.
+
+---
+
 ## Custom Client Adapter (Axios)
 
 ```typescript
@@ -862,7 +1115,9 @@ import type { ClientAdapter } from 'ts-procedures/client'
 import axios from 'axios'
 
 const axiosAdapter: ClientAdapter = {
-  async request({ url, method, headers, body, signal }) {
+  async request({ url, method, headers, body, signal, meta }) {
+    // meta is typed via RequestMeta augmentation — use it for tracing,
+    // priority routing, custom auth, etc.
     const res = await axios({ url, method, headers, data: body, signal })
     return {
       status: res.status,

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

@@ -14,7 +14,7 @@ Parse `$ARGUMENTS` as a file or directory path. If a directory, review all `.ts`
 ## Instructions
 
 1. Read the target file(s).
-2. Identify ts-procedures imports (`ts-procedures`, `ts-procedures/express-rpc`, `ts-procedures/hono-rpc`, `ts-procedures/hono-stream`, `ts-procedures/hono-api`, `ts-procedures/http`, `ts-procedures/http-docs`) to determine file types.
+2. Identify ts-procedures imports (`ts-procedures`, `ts-procedures/express-rpc`, `ts-procedures/hono-rpc`, `ts-procedures/hono-stream`, `ts-procedures/hono-api`, `ts-procedures/http`, `ts-procedures/http-docs`, `ts-procedures/http-errors`, `ts-procedures/client`, `ts-procedures/codegen`) to determine file types.
 3. Check each file against the categorized checklist in [checklist.md](checklist.md).
 4. For detailed code examples of each violation pattern, reference [anti-patterns.md](../ts-procedures/anti-patterns.md) — it shows 20 common mistakes with before/after code fixes and severity ratings.
 5. Output findings grouped by severity.

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

@@ -62,26 +62,29 @@
 ### CRITICAL
 - [ ] Standard `Create` procedures registered with `ExpressRPCAppBuilder` or `HonoRPCAppBuilder`, NOT `HonoStreamAppBuilder`
 - [ ] Stream `CreateStream` procedures registered with `HonoStreamAppBuilder`, NOT the RPC builders
-- [ ] `onError` callback handles `ProcedureValidationError` and `ProcedureError` differently
+- [ ] Custom error classes are registered via `defineErrorTaxonomy` + builder's `errors` config — NOT hand-written `onError` instanceof ladders (anti-pattern #20)
+- [ ] If a handler throws a non-`ProcedureError`, its class is either in the taxonomy or intentionally caught by `unknownError`
 
 ### WARNING
 - [ ] `pathPrefix` set consistently across builders
 - [ ] `scope` and `version` set on all procedures when using `RPCConfig`
 - [ ] Uses `extendProcedureDoc` for documentation generation instead of manual doc building
 - [ ] `onRequestEnd` used for cleanup/logging, not business logic
+- [ ] `RPCConfig<keyof typeof appErrors & string>` used when the app wants compile-time typo protection on per-route `errors: [...]`
 
 ### SUGGESTION
 - [ ] Route documentation accessed via `builder.docs` for OpenAPI generation
-- [ ] Uses `DocRegistry` to compose docs from multiple builders instead of manual envelope assembly
+- [ ] Uses `DocRegistry.fromTaxonomy(appErrors)` (or plain `DocRegistry` with explicit `errors`) to compose docs from multiple builders
 - [ ] Lifecycle hooks used for observability (logging, metrics)
+- [ ] Per-route `errors: [...]` declared so generated clients can narrow `catch` types
 
 ---
 
 ## Streaming Checks (HonoStreamAppBuilder)
 
 ### CRITICAL
-- [ ] `onPreStreamError` handles validation errors before streaming starts (returns HTTP response)
-- [ ] `onMidStreamError` handles runtime errors during streaming (yields error event)
+- [ ] Pre-stream errors handled via either peer mode — `errors` + `unknownError` taxonomy OR `onError` callback (the hono-stream `onPreStreamError` was renamed to `onError` in v6)
+- [ ] `onMidStreamError` handles runtime errors during streaming (yields error event) — mid-stream is NOT covered by the taxonomy since HTTP status is already committed
 - [ ] Stream handler does not assume `signal.reason` is always `'stream-completed'` — check for external abort
 
 ### WARNING
@@ -98,20 +101,21 @@
 ## API Builder Checks (HonoAPIAppBuilder)
 
 ### CRITICAL
-- [ ] `build()` is `await`ed — returns `Promise<Hono>`, not `Hono`
+- [ ] `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
-- [ ] `onError` callback handles `ProcedureValidationError` and `ProcedureError` differently
+- [ ] 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)
 - [ ] `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: [...]`
 
 ### SUGGESTION
 - [ ] Route documentation accessed via `builder.docs` for OpenAPI generation
-- [ ] Uses `DocRegistry` to compose docs across builders instead of manual assembly
+- [ ] Uses `DocRegistry.fromTaxonomy(appErrors)` to compose docs across builders instead of manual assembly
 - [ ] Custom `queryParser` provided if complex query string formats needed
 - [ ] Lifecycle hooks used for observability (logging, metrics)
 
@@ -120,18 +124,22 @@
 ## Error Handling Checks
 
 ### CRITICAL
-- [ ] Handler errors use `ctx.error(message, meta?)` — not `throw new Error()`
+- [ ] Handler errors use `ctx.error(message, meta?)` OR throw a class registered in the app's `defineErrorTaxonomy` — never `throw new Error()` directly
 - [ ] Does not catch and swallow errors without re-throwing (hides failures from caller)
-- [ ] HTTP builder has `onError` callback — default behavior may expose internal details
+- [ ] HTTP builder has either an `errors` taxonomy or an `onError` callback configured — both are first-class peer modes; leaving both off uses the hard default `{ error: message }` 500, which may expose internal details
+- [ ] `defineErrorTaxonomy` entries use `class:` for `instanceof` dispatch or `match:` for 3rd-party errors (e.g. MongoServerError) — never both on the same entry
 
 ### WARNING
-- [ ] `ProcedureValidationError` handled separately (400 status) from `ProcedureError` (4xx/5xx)
+- [ ] Framework errors (`ProcedureValidationError` → 400, `ProcedureError` → 500) are covered by the default taxonomy automatically; don't re-declare them unless overriding
+- [ ] `toResponse` output either includes a `name` field or lets the resolver auto-inject `{ name: key }` — required for typed client dispatch
 - [ ] Error `meta` object contains useful context (error codes, IDs) — not sensitive data
+- [ ] Stack traces and `internalMsg`-style fields are kept server-side via `onCatch`, never included in `toResponse` output
 - [ ] Stack traces not exposed in production responses
 
 ### SUGGESTION
-- [ ] Consistent error response shape across all procedures
-- [ ] Error codes documented for API consumers
+- [ ] Consistent error response shape across all procedures (guaranteed by the taxonomy's `name` field)
+- [ ] Error codes documented for API consumers (feed `description` and `schema` on each taxonomy entry)
+- [ ] Per-route `errors: [...]` declared on each procedure config so the generated client gets narrowed `Errors` union types
 
 ---
 

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

@@ -38,7 +38,8 @@ If either argument is missing, ask the user for `<type>` and `<Name>`.
 
 ## Rules
 
-- Use `ctx.error()` for business logic errors, never throw raw `Error`.
+- Use `ctx.error()` for ad-hoc business errors; for structured errors with status codes and typed client dispatch, throw custom error classes and register them via `defineErrorTaxonomy` in the builder's `errors` config (see the HTTP builder templates).
+- Never throw raw `Error` — either use `ctx.error()` or a typed class registered in the taxonomy.
 - `schema.params` is validated at runtime; `schema.returnType` is documentation only.
 - Pass `ctx.signal` to all downstream async calls.
 - Stream handlers always have `ctx.signal` (guaranteed `AbortSignal`).

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

@@ -3,16 +3,31 @@
 ## Implementation — `{{Name}}.client.ts`
 
 ```typescript
-import { createClient, createFetchAdapter } from 'ts-procedures/client'
-import { createApiBindings, Api } from './generated/api'
-// With --service-name {{Name}}: import { create{{Name}}Bindings, {{Name}} } from './generated/api'
-
-// Create the typed client
-export const {{name}}Client = createClient({
+import { createFetchAdapter } from 'ts-procedures/client'
+import { createApiClient, ApiErrors } from './generated/api'
+// With --service-name {{Name}}: import { create{{Name}}Client, {{Name}}Errors } from './generated/api'
+
+// --- Optional: type per-request meta end-to-end via declaration merging ---
+// Self-contained clients (the default) augment './generated/_types':
+declare module './generated/_types' {
+  interface RequestMeta {
+    // TODO: add your fields — typed in options.meta, ctx.request.meta, adapter req.meta
+    // traceId?: string
+    // priority?: 'high' | 'low'
+  }
+}
+
+// Create the typed client — createApiClient wires the error registry
+// automatically so non-2xx responses arrive as typed class instances you can
+// catch with `instanceof ApiErrors.<ErrorName>`.
+export const {{name}}Client = createApiClient({
   adapter: createFetchAdapter(),
   basePath: 'http://localhost:3000', // TODO: configure base URL
-  scopes: createApiBindings,
-  // With --service-name {{Name}}: scopes: create{{Name}}Bindings,
+  defaults: {
+    // TODO: set client-wide defaults (overridden by per-call options)
+    // timeout: 30_000,
+    // headers: { 'X-Client-Version': '1.0.0' },
+  },
   hooks: {
     onBeforeRequest(ctx) {
       // TODO: add auth headers, request IDs, etc.
@@ -29,6 +44,15 @@ export const {{name}}Client = createClient({
   },
 })
 
+// --- Typed error handling ---
+// try {
+//   const user = await {{name}}Client.users.GetUser({ pathParams: { id: '123' } })
+// } catch (err) {
+//   if (err instanceof ApiErrors.UseCaseError) { /* err.body typed; err.status, procedureName, scope */ }
+//   else if (err instanceof ApiErrors.ApiProcedureError) { /* catch-all for service errors */ }
+//   else { /* transport error — ClientRequestError */ }
+// }
+
 // --- RPC call example ---
 // const user = await {{name}}Client.users.GetUser({ userId: '123' })
 
@@ -42,12 +66,24 @@ export const {{name}}Client = createClient({
 // }
 // const result = await stream.result // Typed from server returnType schema
 
-// --- Per-procedure hook override ---
-// const user = await {{name}}Client.users.GetUser({ id: '123' }, {
-//   onAfterResponse(ctx) {
-//     console.log('Rate limit:', ctx.response.headers['x-rate-limit-remaining'])
+// --- Per-call options (timeout, signal, headers, basePath, meta, hooks) ---
+// const user = await {{name}}Client.users.GetUser(
+//   { id: '123' },
+//   {
+//     timeout: 5000,
+//     headers: { 'X-Request-Id': crypto.randomUUID() },
+//     // meta is typed via RequestMeta augmentation above:
+//     // meta: { traceId: 'req-abc' },
+//     onAfterResponse(ctx) {
+//       console.log('Rate limit:', ctx.response.headers['x-rate-limit-remaining'])
+//     },
 //   },
-// })
+// )
+
+// --- Cancellation with AbortController ---
+// const controller = new AbortController()
+// const promise = {{name}}Client.users.GetUser({ id: '123' }, { signal: controller.signal })
+// setTimeout(() => controller.abort(), 3000)
 ```
 
 ## Test — `{{Name}}.client.test.ts`
@@ -77,11 +113,10 @@ describe('{{Name}} Client', () => {
     // expect(result.id).toBe('test-id')
   })
 
-  test('handles validation errors from the server', async () => {
-    // TODO: call with invalid params and verify error handling
-    // await expect(
-    //   {{name}}Client.users.GetUser({} as any)
-    // ).rejects.toThrow()
+  test('dispatches typed errors from the server via the registry', async () => {
+    // TODO: call with invalid params and verify typed error dispatch
+    // const call = {{name}}Client.users.GetUser({} as any)
+    // await expect(call).rejects.toBeInstanceOf(ApiErrors.ProcedureValidationError)
   })
 
   test('streams data with typed yields', async () => {

package/agent_config/claude-code/skills/ts-procedures-scaffold/templates/express-rpc.md

@@ -3,7 +3,8 @@
 ## Implementation — `{{Name}}.rpc.ts`
 
 ```typescript
-import { Procedures, ProcedureError, ProcedureValidationError } from 'ts-procedures'
+import { Procedures } from 'ts-procedures'
+import { defineErrorTaxonomy } from 'ts-procedures/express-rpc'
 import { ExpressRPCAppBuilder } from 'ts-procedures/express-rpc'
 import type { RPCConfig } from 'ts-procedures/http'
 import { Type } from 'typebox'
@@ -60,26 +61,28 @@ export const { ListItems } = RPC.Create(
   }
 )
 
+// ─── Error Taxonomy ───────────────────────────────────────
+// Declare the error classes this service throws. Framework errors
+// (ProcedureValidationError → 400, ctx.error() → 500) are caught by the
+// default taxonomy automatically. Add your own classes here — handlers just
+// `throw` them and the builder serializes via this map. See
+// docs/http-integrations.md#error-handling for the full contract.
+
+const {{name}}Errors = defineErrorTaxonomy({
+  // Example — replace with your app's error classes:
+  // NotFoundError: { class: NotFoundError, statusCode: 404 },
+  // AuthError:     { class: AuthError,     statusCode: 401 },
+})
+
 // ─── Express App Builder ──────────────────────────────────
 
 export const {{name}}App = new ExpressRPCAppBuilder({
   pathPrefix: '/api',
-  onError: (procedure, req, res, error) => {
-    if (error instanceof ProcedureValidationError) {
-      res.status(400).json({
-        error: error.message,
-        details: error.errors,
-        procedure: error.procedureName,
-      })
-    } else if (error instanceof ProcedureError) {
-      res.status(422).json({
-        error: error.message,
-        meta: error.meta,
-        procedure: error.procedureName,
-      })
-    } else {
-      res.status(500).json({ error: 'Internal server error' })
-    }
+  errors: {{name}}Errors,
+  unknownError: {
+    statusCode: 500,
+    toResponse: () => ({ name: 'InternalServerError', message: 'Unexpected error' }),
+    onCatch: (err, { procedure }) => console.error(`[${procedure.name}]`, err),
   },
 })
   .register(RPC, async (req) => ({

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

@@ -3,7 +3,8 @@
 ## Implementation — `{{Name}}.api.ts`
 
 ```typescript
-import { Procedures, ProcedureError, ProcedureValidationError } from 'ts-procedures'
+import { Procedures } from 'ts-procedures'
+import { defineErrorTaxonomy } from 'ts-procedures/hono-api'
 import { HonoAPIAppBuilder } from 'ts-procedures/hono-api'
 import type { APIConfig, APIInput } from 'ts-procedures/http'
 import { Type } from 'typebox'
@@ -81,25 +82,28 @@ export const { DeleteItem } = API.Create(
   }
 )
 
+// ─── Error Taxonomy ───────────────────────────────────────
+// Declare the error classes this service throws. Framework errors
+// (ProcedureValidationError → 400, ctx.error() → 500) are caught by the
+// default taxonomy automatically. Add your own classes here — handlers just
+// `throw` them and the builder serializes via this map. See
+// docs/http-integrations.md#error-handling for the full contract.
+
+const {{name}}Errors = defineErrorTaxonomy({
+  // Example — replace with your app's error classes:
+  // NotFoundError: { class: NotFoundError, statusCode: 404 },
+  // AuthError:     { class: AuthError,     statusCode: 401 },
+})
+
 // ─── Hono App Builder ─────────────────────────────────────
 
 export const {{name}}App = new HonoAPIAppBuilder({
   pathPrefix: '/api',
-  onError: (procedure, c, error) => {
-    if (error instanceof ProcedureValidationError) {
-      return c.json({
-        error: error.message,
-        details: error.errors,
-        procedure: error.procedureName,
-      }, 400)
-    } else if (error instanceof ProcedureError) {
-      return c.json({
-        error: error.message,
-        meta: error.meta,
-        procedure: error.procedureName,
-      }, 422)
-    }
-    return c.json({ error: 'Internal server error' }, 500)
+  errors: {{name}}Errors,
+  unknownError: {
+    statusCode: 500,
+    toResponse: () => ({ name: 'InternalServerError', message: 'Unexpected error' }),
+    onCatch: (err, { procedure }) => console.error(`[${procedure.name}]`, err),
   },
 })
   .register(API, (c) => ({