ts-procedures 5.16.0 → 6.0.1

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

@@ -103,6 +103,173 @@ 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 = new DocRegistry({ errors: 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
+```
+
+```typescript
+// For errors outside your taxonomy (middleware, infrastructure, doc-only):
+const docsWithExtras = new DocRegistry({ errors: appErrors, basePath: '/api' })
+  .from(apiBuilder)
+  .documentError({ name: 'RateLimitExceeded', statusCode: 429, description: 'too many requests' })
+```
+
+### 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 +442,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 +602,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) => ({
@@ -649,7 +812,7 @@ import { DocRegistry } from 'ts-procedures/http-docs'
 const docs = new DocRegistry({
   basePath: '/api',
   headers: [{ name: 'Authorization', description: 'Bearer token', required: false }],
-  errors: DocRegistry.defaultErrors(),
+  errors: appErrors,  // your ErrorTaxonomy — framework defaults auto-merged and deduped
 })
   .from(rpcBuilder)
   .from(apiBuilder)
@@ -668,7 +831,7 @@ app.get('/docs', (c) => c.json(docs.toJSON({
 **Key points:**
 - `from()` stores a reference — register builders before or after `.build()`
 - `toJSON()` reads docs lazily, so late-registered procedures are included
-- `DocRegistry.defaultErrors()` provides error schemas for all 4 procedure error types
+- Pass your `ErrorTaxonomy` directly to `errors` — the constructor auto-merges framework defaults and dedupes; opt out with `includeDefaults: false`
 - Accepts any object satisfying `{ readonly docs: AnyHttpRouteDoc[] }` — not limited to built-in builders
 
 ---
@@ -754,7 +917,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
 ```
@@ -770,7 +933,7 @@ import { DocRegistry } from 'ts-procedures/http-docs'
 const docs = new DocRegistry({
   basePath: '/api',
   headers: [{ name: 'Authorization', description: 'Bearer token' }],
-  errors: DocRegistry.defaultErrors(),
+  errors: appErrors,  // your ErrorTaxonomy — framework defaults auto-merged
 })
   .from(rpcBuilder)
   .from(apiBuilder)

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 `new DocRegistry({ errors: appErrors })` 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 `new DocRegistry({ errors: 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,14 +3,13 @@
 ## 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'
+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 augment './generated/_types' instead:
-//   declare module './generated/_types' { interface RequestMeta { traceId: string } }
-declare module 'ts-procedures/client' {
+// 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
@@ -18,12 +17,12 @@ declare module 'ts-procedures/client' {
   }
 }
 
-// Create the typed client
-export const {{name}}Client = createClient({
+// 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,
@@ -45,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' })
 
@@ -105,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) => ({

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

@@ -3,8 +3,8 @@
 ## Implementation — `{{Name}}.rpc.ts`
 
 ```typescript
-import { Procedures, ProcedureError, ProcedureValidationError } from 'ts-procedures'
-import { HonoRPCAppBuilder } from 'ts-procedures/hono-rpc'
+import { Procedures } from 'ts-procedures'
+import { HonoRPCAppBuilder, defineErrorTaxonomy } from 'ts-procedures/hono-rpc'
 import type { RPCConfig } from 'ts-procedures/http'
 import { Type } from 'typebox'
 
@@ -60,25 +60,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 },
+})
+
 // ─── Hono App Builder ─────────────────────────────────────
 
 export const {{name}}App = new HonoRPCAppBuilder({
   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(RPC, (c) => ({

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

@@ -4,7 +4,7 @@
 
 ```typescript
 import { Procedures } from 'ts-procedures'
-import { HonoStreamAppBuilder, sse } from 'ts-procedures/hono-stream'
+import { HonoStreamAppBuilder, sse, defineErrorTaxonomy } from 'ts-procedures/hono-stream'
 import type { RPCConfig } from 'ts-procedures/http'
 import { Type } from 'typebox'
 
@@ -60,13 +60,26 @@ async function pollForEvents(channel: string, opts?: { signal?: AbortSignal }) {
   return { type: 'update', data: { value: Math.random() } }
 }
 
+// ─── Error Taxonomy (pre-stream) ──────────────────────────
+// Pre-stream errors (validation, context resolution) flow through the
+// taxonomy — framework errors are caught by the default taxonomy automatically.
+// Mid-stream errors (thrown after the first yield) still go through
+// onMidStreamError since the HTTP status is already committed.
+
+const {{name}}Errors = defineErrorTaxonomy({
+  // Example — replace with your app's error classes:
+  // AuthError: { class: AuthError, statusCode: 401 },
+})
+
 // ─── Hono Stream App Builder ──────────────────────────────
 
 export const {{name}}StreamApp = new HonoStreamAppBuilder({
   pathPrefix: '/api',
   defaultStreamMode: 'sse',  // or 'text' for newline-delimited JSON
-  onPreStreamError: (procedure, c, error) => {
-    return c.json({ error: error.message }, 400)
+  errors: {{name}}Errors,
+  unknownError: {
+    statusCode: 500,
+    toResponse: () => ({ name: 'InternalServerError', message: 'Unexpected error' }),
   },
   onMidStreamError: (procedure, c, error) => ({
     data: { type: 'error', payload: { message: error.message }, timestamp: Date.now() },