ts-procedures 5.16.0 → 6.0.1

package/src/implementations/http/hono-stream/index.test.ts

@@ -503,7 +503,7 @@ describe('HonoStreamAppBuilder', () => {
         return c.json({ customError: error.message }, 400)
       })
 
-      const builder = new HonoStreamAppBuilder({ onPreStreamError: errorHandler })
+      const builder = new HonoStreamAppBuilder({ onError: errorHandler })
       const RPC = Procedures<{}, RPCConfig>()
 
       RPC.CreateStream(
@@ -575,8 +575,10 @@ describe('HonoStreamAppBuilder', () => {
       expect(JSON.parse(lines[1]!).error).toContain('Stream error')
     })
 
-    test('validation errors return 400 by default when no error handler', async () => {
-      const builder = new HonoStreamAppBuilder()
+    test('validation errors return 400 when the default taxonomy is engaged (via `errors: {}`)', async () => {
+      // Opting into the taxonomy (even an empty one) engages the framework
+      // default entries — ProcedureValidationError → 400.
+      const builder = new HonoStreamAppBuilder({ errors: {} })
       const RPC = Procedures<{}, RPCConfig>()
 
       RPC.CreateStream(
@@ -598,22 +600,53 @@ describe('HonoStreamAppBuilder', () => {
 
       const res = await app.request('/validated/validated-stream/1?count=not-a-number')
 
-      // Default: returns 400 JSON error
       expect(res.status).toBe(400)
       const body = await res.json()
+      expect(body.name).toBe('ProcedureValidationError')
+    })
+
+    test('validation errors return 500 by default with no builder config (hard-default path)', async () => {
+      // With no taxonomy and no onError configured, every error falls through
+      // to the flat 500 hard default — consistent with the other three
+      // builders. Previously hono-stream special-cased ProcedureValidationError
+      // to 400; that predated the taxonomy and was removed in v6.
+      const builder = new HonoStreamAppBuilder()
+      const RPC = Procedures<{}, RPCConfig>()
+
+      RPC.CreateStream(
+        'ValidatedStream',
+        {
+          scope: 'validated',
+          version: 1,
+          schema: {
+            params: v.object({ count: v.number() }),
+          },
+        },
+        async function* (ctx, params) {
+          yield { count: params.count }
+        }
+      )
+
+      builder.register(RPC, () => ({}))
+      const app = builder.build()
+
+      const res = await app.request('/validated/validated-stream/1?count=not-a-number')
+
+      expect(res.status).toBe(500)
+      const body = await res.json()
       expect(body.error).toContain('Validation error')
     })
 
-    // Tests for onPreStreamError and onMidStreamError callbacks
+    // Tests for onError and onMidStreamError callbacks
 
-    test('onPreStreamError handles validation errors with custom Response', async () => {
-      const onPreStreamError = vi.fn((procedure, c, error) => {
+    test('onError handles validation errors with custom Response', async () => {
+      const onError = vi.fn((procedure, c, error) => {
         return c.json(
           { customError: true, procedureName: procedure.name, details: error.message },
           422
         )
       })
-      const builder = new HonoStreamAppBuilder({ onPreStreamError })
+      const builder = new HonoStreamAppBuilder({ onError })
       const RPC = Procedures<{}, RPCConfig>()
 
       RPC.CreateStream(
@@ -641,14 +674,14 @@ describe('HonoStreamAppBuilder', () => {
       expect(body.procedureName).toBe('ValidatedStream')
       expect(body.details).toContain('Validation error')
 
-      expect(onPreStreamError).toHaveBeenCalledTimes(1)
+      expect(onError).toHaveBeenCalledTimes(1)
     })
 
-    test('onPreStreamError handles context resolution errors', async () => {
-      const onPreStreamError = vi.fn((procedure, c, error) => {
+    test('onError handles context resolution errors', async () => {
+      const onError = vi.fn((procedure, c, error) => {
         return c.json({ contextError: error.message }, 401)
       })
-      const builder = new HonoStreamAppBuilder({ onPreStreamError })
+      const builder = new HonoStreamAppBuilder({ onError })
       const RPC = Procedures<{ userId: string }, RPCConfig>()
 
       RPC.CreateStream('SecureStream', { scope: 'secure', version: 1 }, async function* (ctx) {
@@ -666,7 +699,7 @@ describe('HonoStreamAppBuilder', () => {
       const body = await res.json()
       expect(body.contextError).toBe('Authentication required')
 
-      expect(onPreStreamError).toHaveBeenCalledTimes(1)
+      expect(onError).toHaveBeenCalledTimes(1)
     })
 
     test('onMidStreamError returns custom value written to SSE stream', async () => {
@@ -1257,7 +1290,10 @@ describe('HonoStreamAppBuilder', () => {
 
     test('invalid params are caught by HonoStreamAppBuilder before handler runs', async () => {
       let handlerCalled = false
-      const builder = new HonoStreamAppBuilder({ defaultStreamMode: 'text' })
+      // Opt into the taxonomy (empty) so the default ProcedureValidationError
+      // entry returns 400 — the recommended way to get a structured validation
+      // response now that the hard default is a flat 500.
+      const builder = new HonoStreamAppBuilder({ defaultStreamMode: 'text', errors: {} })
       const RPC = Procedures<{}, RPCConfig>()
 
       RPC.CreateStream(
@@ -1283,7 +1319,7 @@ describe('HonoStreamAppBuilder', () => {
       expect(res.status).toBe(400)
 
       const body = await res.json()
-      expect(body.error).toContain('Validation error')
+      expect(body.name).toBe('ProcedureValidationError')
 
       // Handler should never be called since validation fails before streaming
       expect(handlerCalled).toBe(false)
@@ -1646,14 +1682,14 @@ describe('HonoStreamAppBuilder', () => {
   })
 
   // --------------------------------------------------------------------------
-  // ProcedureValidationError narrowing in onPreStreamError
+  // ProcedureValidationError narrowing in onError
   // --------------------------------------------------------------------------
   describe('ProcedureValidationError narrowing', () => {
-    test('instanceof check works in onPreStreamError', async () => {
+    test('instanceof check works in onError', async () => {
       let wasValidationError = false
 
       const builder = new HonoStreamAppBuilder({
-        onPreStreamError: (procedure, c, error) => {
+        onError: (procedure, c, error) => {
           if (error instanceof ProcedureValidationError) {
             wasValidationError = true
             return c.json({ validation: true, errors: error.errors }, 422)

package/src/implementations/http/hono-stream/index.ts

@@ -6,8 +6,28 @@ import { TStreamProcedureRegistration } from '../../../index.js'
 import { ExtractConfig, ExtractContext, ProceduresFactory, RPCConfig } from '../../types.js'
 import { HonoStreamFactoryItem, StreamHttpRouteDoc, StreamMode } from './types.js'
 import { ProcedureValidationError } from '../../../errors.js'
+import {
+  ErrorTaxonomy,
+  ErrorTaxonomyEntry,
+  UnknownErrorConfig,
+  defineErrorTaxonomy,
+  resolveErrorResponse,
+} from '../error-taxonomy.js'
 
 export type { StreamHttpRouteDoc, StreamMode }
+export { defineErrorTaxonomy }
+export type { ErrorTaxonomy, ErrorTaxonomyEntry, UnknownErrorConfig }
+
+/**
+ * Context passed to the `onRequestError` observer. `raw` is the Hono
+ * `Context` for the in-flight request — cast at the use site if you need
+ * framework-specific fields.
+ */
+export type OnRequestErrorContext = {
+  err: unknown
+  procedure: TStreamProcedureRegistration
+  raw: Context
+}
 
 export type SSEOptions = {
   event?: string
@@ -54,14 +74,38 @@ export type HonoStreamAppBuilderConfig<TErrorData = unknown> = {
   onStreamStart?: (procedure: TStreamProcedureRegistration, c: Context, streamMode: StreamMode) => void
   onStreamEnd?: (procedure: TStreamProcedureRegistration, c: Context, streamMode: StreamMode) => void
   /**
-   * Called for errors BEFORE streaming starts (validation, auth, context resolution).
-   * Return value IS used as the HTTP response.
+   * Declarative error-to-response mapping (one of the two peer error modes).
+   * Thrown error classes map to status codes + bodies declaratively. Mid-stream
+   * errors still go through `onMidStreamError` — the HTTP status is already
+   * committed once streaming starts. See hono-api for the full taxonomy
+   * contract.
+   */
+  errors?: ErrorTaxonomy
+  /**
+   * Fallback serializer when a taxonomy is configured but no entry matches.
    */
-  onPreStreamError?: (
+  unknownError?: UnknownErrorConfig
+  /**
+   * Imperative pre-stream error callback — the other peer error mode.
+   * Receives every pre-stream error directly and returns the HTTP response.
+   * Use this instead of `errors` when you want full control over the response
+   * shape, or alongside it for the tail of errors the taxonomy doesn't cover.
+   *
+   * Mid-stream errors always go through `onMidStreamError`.
+   */
+  onError?: (
     procedure: TStreamProcedureRegistration,
     c: Context,
     error: ProcedureValidationError | Error
   ) => Response | Promise<Response>
+  /**
+   * Cross-cutting observer — fires for every caught pre-stream error, BEFORE
+   * dispatch to the taxonomy or `onError`. Awaited. Cannot mutate the
+   * response. Intended for logging, tracing, and metrics (Sentry, Datadog,
+   * OpenTelemetry). Any error thrown inside the observer is swallowed and
+   * logged so the primary dispatch flow is never disrupted.
+   */
+  onRequestError?: (ctx: OnRequestErrorContext) => void | Promise<void>
   /**
    * Called for errors DURING streaming (generator throws).
    * Return value is written to the stream as a yield.
@@ -195,20 +239,17 @@ export class HonoStreamAppBuilder<TErrorData = unknown> {
             ? Object.fromEntries(new URL(c.req.url).searchParams)
             : await c.req.json().catch(() => ({}))
 
-        // Validate params BEFORE starting the stream
+        // Validate params BEFORE starting the stream. Throw so both the
+        // validation path and the outer-catch (context resolution) path flow
+        // through one dispatch site.
         if (procedure.config.validation?.params) {
           const { errors } = procedure.config.validation.params(params)
           if (errors) {
-            const error = new ProcedureValidationError(
+            throw new ProcedureValidationError(
               procedure.name,
               `Validation error for ${procedure.name}`,
               errors
             )
-            // Use onPreStreamError if provided
-            if (this.config?.onPreStreamError) {
-              return this.config.onPreStreamError(procedure, c, error)
-            }
-            return c.json({ error: error.message }, 400)
           }
         }
 
@@ -222,9 +263,34 @@ export class HonoStreamAppBuilder<TErrorData = unknown> {
           return this.handleTextStream(procedure, context, params, c)
         }
       } catch (error) {
-        // Use onPreStreamError for context resolution errors
-        if (this.config?.onPreStreamError) {
-          return this.config.onPreStreamError(procedure, c, error as Error)
+        // Observer fires first — cross-cutting, cannot alter dispatch or the
+        // response. Swallow any throw from the observer so the primary flow
+        // never breaks because of instrumentation.
+        if (this.config?.onRequestError) {
+          try {
+            await this.config.onRequestError({ err: error, procedure, raw: c })
+          } catch (observerErr) {
+            console.error('[ts-procedures hono-stream] onRequestError threw — swallowed:', observerErr)
+          }
+        }
+
+        // Dispatch: taxonomy → onError → hard default. The two modes are
+        // peers; developers configure whichever fits their app.
+        if (this.config?.errors || this.config?.unknownError) {
+          const resolved = resolveErrorResponse({
+            err: error,
+            userTaxonomy: this.config.errors,
+            unknownError: this.config.unknownError,
+            procedure,
+            raw: c,
+          })
+          if (resolved) {
+            await resolved.runOnCatch()
+            return c.json(resolved.body, resolved.statusCode as never)
+          }
+        }
+        if (this.config?.onError) {
+          return this.config.onError(procedure, c, error as Error)
         }
         return c.json({ error: (error as Error).message }, 500)
       }
@@ -442,6 +508,10 @@ export class HonoStreamAppBuilder<TErrorData = unknown> {
       jsonSchema,
     }
 
+    if (config.errors && config.errors.length > 0) {
+      base.errors = [...config.errors]
+    }
+
     let extendedDoc: object = {}
 
     if (extendProcedureDoc) {

package/src/implementations/http/on-request-error.test.ts

@@ -0,0 +1,201 @@
+/* eslint-disable @typescript-eslint/no-empty-object-type */
+/**
+ * Cross-builder tests for the `onRequestError` observer hook.
+ *
+ * Invariants verified once per builder:
+ *   1. Fires exactly once for every caught error.
+ *   2. Runs BEFORE dispatch (taxonomy / onError / hard default).
+ *   3. Is awaited — async observer work completes before the response is sent.
+ *   4. Doesn't replace dispatch — response shape when observer is configured
+ *      matches the response shape when it's not.
+ *   5. Thrown errors inside the observer are swallowed — the primary dispatch
+ *      path still produces a response.
+ */
+import { describe, expect, test, vi } from 'vitest'
+import request from 'supertest'
+import { Type } from 'typebox'
+import { Procedures } from '../../index.js'
+import { APIConfig, RPCConfig } from '../types.js'
+import { HonoAPIAppBuilder } from './hono-api/index.js'
+import { HonoRPCAppBuilder } from './hono-rpc/index.js'
+import { ExpressRPCAppBuilder } from './express-rpc/index.js'
+import { HonoStreamAppBuilder } from './hono-stream/index.js'
+
+describe('onRequestError — HonoAPIAppBuilder', () => {
+  function boomApp(config: ConstructorParameters<typeof HonoAPIAppBuilder>[0]) {
+    const API = Procedures<{}, APIConfig>()
+    API.Create(
+      'Boom',
+      { path: '/boom', method: 'get', schema: { returnType: Type.Object({}) } },
+      async () => {
+        throw new TypeError('boom')
+      }
+    )
+    return new HonoAPIAppBuilder(config).register(API, () => ({})).build()
+  }
+
+  test('fires exactly once and before dispatch', async () => {
+    const order: string[] = []
+    const onRequestError = vi.fn(() => {
+      order.push('observer')
+    })
+    const onError = vi.fn((_p: any, c: any) => {
+      order.push('onError')
+      return c.json({ handled: true }, 418)
+    })
+
+    const app = boomApp({ onRequestError, onError })
+    await app.request('/boom')
+    expect(onRequestError).toHaveBeenCalledTimes(1)
+    expect(order).toEqual(['observer', 'onError'])
+  })
+
+  test('is awaited — async work completes before response is sent', async () => {
+    const log: string[] = []
+    const onRequestError = async () => {
+      await new Promise((r) => setTimeout(r, 5))
+      log.push('observer-done')
+    }
+    const app = boomApp({
+      onRequestError,
+      onError: (_p, c) => {
+        log.push('onError-called')
+        return c.json({ ok: true }, 500)
+      },
+    })
+    await app.request('/boom')
+    expect(log).toEqual(['observer-done', 'onError-called'])
+  })
+
+  test('observer-thrown errors are swallowed — dispatch still produces a response', async () => {
+    const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+    const app = boomApp({
+      onRequestError: () => {
+        throw new Error('observer exploded')
+      },
+    })
+    const res = await app.request('/boom')
+    expect(res.status).toBe(500)
+    consoleSpy.mockRestore()
+  })
+
+  test('omitting observer preserves existing behavior', async () => {
+    const app = boomApp({ onError: (_p, c) => c.json({ ok: true }, 418) })
+    const res = await app.request('/boom')
+    expect(res.status).toBe(418)
+  })
+})
+
+describe('onRequestError — HonoRPCAppBuilder', () => {
+  function boomApp(config: ConstructorParameters<typeof HonoRPCAppBuilder>[0]) {
+    const RPC = Procedures<{}, RPCConfig>()
+    RPC.Create(
+      'Boom',
+      { scope: 'test', version: 1, schema: { params: Type.Object({}) } },
+      async () => {
+        throw new TypeError('boom')
+      }
+    )
+    return new HonoRPCAppBuilder(config).register(RPC, () => ({})).build()
+  }
+
+  test('fires once; runs before onError', async () => {
+    const order: string[] = []
+    const onRequestError = vi.fn(() => {
+      order.push('observer')
+    })
+    const onError = vi.fn((_p: any, c: any) => {
+      order.push('onError')
+      return c.json({}, 500)
+    })
+
+    const app = boomApp({ onRequestError, onError })
+    await app.request('/test/boom/1', { method: 'POST', body: '{}' })
+    expect(onRequestError).toHaveBeenCalledTimes(1)
+    expect(order).toEqual(['observer', 'onError'])
+  })
+
+  test('observer throws are swallowed', async () => {
+    const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+    const app = boomApp({
+      onRequestError: () => {
+        throw new Error('boom in observer')
+      },
+    })
+    const res = await app.request('/test/boom/1', { method: 'POST', body: '{}' })
+    expect(res.status).toBe(500)
+    consoleSpy.mockRestore()
+  })
+})
+
+describe('onRequestError — ExpressRPCAppBuilder', () => {
+  function boomApp(config: ConstructorParameters<typeof ExpressRPCAppBuilder>[0]) {
+    const RPC = Procedures<{}, RPCConfig>()
+    RPC.Create(
+      'Boom',
+      { scope: 'test', version: 1, schema: { params: Type.Object({}) } },
+      async () => {
+        throw new TypeError('boom')
+      }
+    )
+    return new ExpressRPCAppBuilder(config).register(RPC, () => ({})).build()
+  }
+
+  test('fires once; raw is { req, res }', async () => {
+    let rawSeen: any
+    const app = boomApp({
+      onRequestError: (ctx) => {
+        rawSeen = ctx.raw
+      },
+    })
+    await request(app).post('/test/boom/1').send({})
+    expect(rawSeen.req).toBeDefined()
+    expect(rawSeen.res).toBeDefined()
+  })
+
+  test('observer throws are swallowed', async () => {
+    const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+    const app = boomApp({
+      onRequestError: () => {
+        throw new Error('observer bug')
+      },
+    })
+    const res = await request(app).post('/test/boom/1').send({})
+    expect(res.status).toBe(500)
+    consoleSpy.mockRestore()
+  })
+})
+
+describe('onRequestError — HonoStreamAppBuilder (pre-stream)', () => {
+  function boomApp(config: ConstructorParameters<typeof HonoStreamAppBuilder>[0]) {
+    const RPC = Procedures<{}, RPCConfig>()
+    RPC.CreateStream('Stream', { scope: 'test', version: 1 }, async function* () {
+      yield { ok: true }
+    })
+    return new HonoStreamAppBuilder(config)
+      .register(RPC, () => {
+        throw new TypeError('context failed')
+      })
+      .build()
+  }
+
+  test('fires once for pre-stream errors', async () => {
+    const onRequestError = vi.fn()
+    const app = boomApp({ onRequestError })
+    await app.request('/test/stream/1')
+    expect(onRequestError).toHaveBeenCalledTimes(1)
+    expect(onRequestError.mock.calls[0]![0].err).toBeInstanceOf(TypeError)
+  })
+
+  test('observer throws are swallowed', async () => {
+    const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+    const app = boomApp({
+      onRequestError: () => {
+        throw new Error('observer fail')
+      },
+    })
+    const res = await app.request('/test/stream/1')
+    expect(res.status).toBe(500)
+    consoleSpy.mockRestore()
+  })
+})

package/src/implementations/http/route-errors.test.ts

@@ -0,0 +1,176 @@
+/* eslint-disable @typescript-eslint/no-empty-object-type */
+import { describe, expect, test } from 'vitest'
+import { Type } from 'typebox'
+import { Procedures } from '../../index.js'
+import { APIConfig, RPCConfig } from '../types.js'
+import { HonoAPIAppBuilder } from './hono-api/index.js'
+import { HonoRPCAppBuilder } from './hono-rpc/index.js'
+import { ExpressRPCAppBuilder } from './express-rpc/index.js'
+import { HonoStreamAppBuilder } from './hono-stream/index.js'
+import { DocRegistry } from './doc-registry.js'
+import { defineErrorTaxonomy } from './error-taxonomy.js'
+
+class UseCaseError extends Error {
+  constructor(readonly externalMsg: string) {
+    super(externalMsg)
+    this.name = 'UseCaseError'
+    Object.setPrototypeOf(this, UseCaseError.prototype)
+  }
+}
+
+class AuthError extends Error {}
+
+const appErrors = defineErrorTaxonomy({
+  UseCaseError: { class: UseCaseError, statusCode: 422 },
+  AuthError: { class: AuthError, statusCode: 401 },
+})
+
+describe('per-route errors declaration', () => {
+  test('hono-api copies config.errors onto the route doc', () => {
+    const API = Procedures<{}, APIConfig<keyof typeof appErrors & string>>()
+    API.Create(
+      'GetUser',
+      {
+        path: '/users/:id',
+        method: 'get',
+        errors: ['UseCaseError', 'AuthError'],
+        schema: {
+          input: { pathParams: Type.Object({ id: Type.String() }) },
+          returnType: Type.Object({}),
+        },
+      },
+      async () => ({})
+    )
+    const builder = new HonoAPIAppBuilder().register(API, () => ({}))
+    builder.build()
+    expect(builder.docs[0]!.errors).toEqual(['UseCaseError', 'AuthError'])
+  })
+
+  test('hono-api route doc omits errors when not declared', () => {
+    const API = Procedures<{}, APIConfig>()
+    API.Create(
+      'Health',
+      { path: '/health', method: 'get', schema: { returnType: Type.Object({}) } },
+      async () => ({})
+    )
+    const builder = new HonoAPIAppBuilder().register(API, () => ({}))
+    builder.build()
+    expect(builder.docs[0]!.errors).toBeUndefined()
+  })
+
+  test('hono-rpc copies config.errors onto the route doc', () => {
+    const RPC = Procedures<{}, RPCConfig<keyof typeof appErrors & string>>()
+    RPC.Create(
+      'DoThing',
+      {
+        scope: 'things',
+        version: 1,
+        errors: ['UseCaseError'],
+        schema: { params: Type.Object({}) },
+      },
+      async () => ({})
+    )
+    const builder = new HonoRPCAppBuilder().register(RPC, () => ({}))
+    builder.build()
+    expect(builder.docs[0]!.errors).toEqual(['UseCaseError'])
+  })
+
+  test('express-rpc copies config.errors onto the route doc', () => {
+    const RPC = Procedures<{}, RPCConfig<keyof typeof appErrors & string>>()
+    RPC.Create(
+      'DoThing',
+      {
+        scope: 'things',
+        version: 1,
+        errors: ['AuthError'],
+        schema: { params: Type.Object({}) },
+      },
+      async () => ({})
+    )
+    const builder = new ExpressRPCAppBuilder().register(RPC, () => ({}))
+    builder.build()
+    expect(builder.docs[0]!.errors).toEqual(['AuthError'])
+  })
+
+  test('hono-stream copies config.errors onto the route doc', () => {
+    const Stream = Procedures<{}, RPCConfig<keyof typeof appErrors & string>>()
+    Stream.CreateStream(
+      'Watch',
+      { scope: 'watch', version: 1, errors: ['AuthError'] },
+      async function* () {
+        yield { ok: true }
+      }
+    )
+    const builder = new HonoStreamAppBuilder().register(Stream, () => ({}))
+    builder.build()
+    expect(builder.docs[0]!.errors).toEqual(['AuthError'])
+  })
+
+  test('compile-time: errors typed as keyof taxonomy narrows valid keys', () => {
+    // TS-only: this test compiles only if the generic narrows correctly.
+    type Narrow = APIConfig<keyof typeof appErrors & string>['errors']
+    const _valid: Narrow = ['UseCaseError', 'AuthError']
+    // @ts-expect-error - 'NotRegistered' is not in the taxonomy
+    const _invalid: Narrow = ['NotRegistered']
+    expect(_valid).toBeDefined()
+    expect(_invalid).toBeDefined()
+  })
+})
+
+describe('DocRegistry with taxonomy input', () => {
+  test('seeds envelope errors from the taxonomy + framework defaults', () => {
+    const registry = new DocRegistry({ errors: appErrors, basePath: '/api' })
+    const envelope = registry.toJSON()
+    const names = envelope.errors.map((e) => e.name)
+    expect(names).toContain('UseCaseError')
+    expect(names).toContain('AuthError')
+    expect(names).toContain('ProcedureValidationError')
+    expect(names).toContain('ProcedureRegistrationError')
+    expect(envelope.basePath).toBe('/api')
+  })
+
+  test('includeDefaults: false omits framework entries', () => {
+    const registry = new DocRegistry({ errors: appErrors, includeDefaults: false })
+    const names = registry.toJSON().errors.map((e) => e.name)
+    expect(names).toEqual(['UseCaseError', 'AuthError'])
+  })
+
+  test('user entry with same key as default takes precedence (deduped)', () => {
+    const overridden = defineErrorTaxonomy({
+      ProcedureError: {
+        class: Error,
+        statusCode: 418,
+        description: 'custom override',
+      },
+    })
+    const envelope = new DocRegistry({ errors: overridden }).toJSON()
+    const proc = envelope.errors.find((e) => e.name === 'ProcedureError')
+    expect(proc?.statusCode).toBe(418)
+    expect(proc?.description).toBe('custom override')
+    const count = envelope.errors.filter((e) => e.name === 'ProcedureError').length
+    expect(count).toBe(1)
+  })
+
+  test('registered route errors survive DocRegistry composition', () => {
+    const API = Procedures<{}, APIConfig<keyof typeof appErrors & string>>()
+    API.Create(
+      'GetUser',
+      {
+        path: '/users/:id',
+        method: 'get',
+        errors: ['UseCaseError'],
+        schema: {
+          input: { pathParams: Type.Object({ id: Type.String() }) },
+          returnType: Type.Object({}),
+        },
+      },
+      async () => ({})
+    )
+    const app = new HonoAPIAppBuilder().register(API, () => ({}))
+    app.build()
+
+    const envelope = new DocRegistry({ errors: appErrors }).from(app).toJSON()
+    const route = envelope.routes.find((r) => r.kind === 'api' && r.name === 'GetUser')
+    expect(route?.errors).toEqual(['UseCaseError'])
+  })
+})