ts-procedures 6.0.0 → 6.0.1

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

@@ -37,7 +37,7 @@ 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.fromTaxonomy(appErrors)` to seed envelope errors from your taxonomy + framework defaults in one call.
+- Use `DocRegistry` to compose route docs from multiple builders — never manually wire `/docs` endpoints. Pass your taxonomy directly: `new DocRegistry({ errors: appErrors })` — framework defaults are auto-merged and deduped. For errors outside your taxonomy (middleware, infrastructure, doc-only), chain `.documentError(...docs)`.
 - 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.

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

@@ -171,7 +171,7 @@ 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, **error taxonomy (canonical)**, DocRegistry + `fromTaxonomy` |
+| `docs/http-integrations.md` | Express RPC, Hono RPC/Stream/API builders, **error taxonomy (canonical)**, DocRegistry (unified constructor, `.documentError()`) |
 | `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. |
 

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

@@ -476,13 +476,13 @@ 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).from(streamBuilder)
 
 app.get('/docs', (c) => c.json(docs.toJSON()))
 ```
 
-**Why:** `DocRegistry` provides a typed `DocEnvelope`, includes `defaultErrors()` with JSON Schemas for all 4 procedure error types, reads docs lazily (order-independent), and supports filtering and transformation via `toJSON()` options.
+**Why:** `DocRegistry` provides a typed `DocEnvelope`, auto-merges framework error defaults (`ProcedureError`, `ProcedureValidationError`, `ProcedureYieldValidationError`, `ProcedureRegistrationError`) with JSON Schemas, reads docs lazily (order-independent), and supports filtering and transformation via `toJSON()` options.
 
 ---
 

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

@@ -295,13 +295,7 @@ When `toResponse` is omitted, the body defaults to `{ name: key, message: err.me
 
 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.
+Taxonomy-to-doc conversion is handled automatically by `DocRegistry` when you pass your taxonomy to the constructor. There is no public helper.
 
 ### resolveErrorResponse(params)
 
@@ -795,30 +789,24 @@ import type { DocEnvelope, DocRegistryConfig, DocRegistryOutputOptions, HeaderDo
 ```
 
 ```typescript
+import { DocRegistry } from 'ts-procedures/http-docs'
+import type { DocEnvelope, DocRegistryConfig, DocRegistryOutputOptions, HeaderDoc, ErrorDoc, DocSource } from 'ts-procedures/http-docs'
+
+interface DocRegistryConfig {
+  basePath?: string
+  headers?: HeaderDoc[]
+  errors?: ErrorTaxonomy | ErrorDoc[]   // polymorphic — pass taxonomy or raw docs
+  includeDefaults?: boolean              // default: true (auto-merges framework defaults)
+}
+
 class DocRegistry {
-  constructor(config?: {
-    basePath?: string
-    headers?: HeaderDoc[]
-    errors?: ErrorDoc[]
-  })
+  constructor(config?: DocRegistryConfig)
 
   from(source: DocSource<AnyHttpRouteDoc>): this
+  documentError(...docs: ErrorDoc[]): this
+  toJSON<T = DocEnvelope>(options?: DocRegistryOutputOptions<T>): T
 
-  toJSON<T = DocEnvelope>(options?: {
-    filter?: (route: AnyHttpRouteDoc) => boolean
-    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
 }
 ```
 
@@ -875,7 +863,7 @@ type AnyHttpRouteDoc = RPCHttpRouteDoc | APIHttpRouteDoc | StreamHttpRouteDoc
 
 - `from()` stores a **reference** to the builder — routes are read lazily at `toJSON()` time, so builders can be registered before or after `.build()`
 - `toJSON()` collects routes via `flatMap(source => source.docs)`, applies optional `filter`, builds envelope, then applies optional `transform`
-- `defaultErrors()` returns 4 `ErrorDoc` entries describing `ProcedureError` (500), `ProcedureValidationError` (400), `ProcedureYieldValidationError` (500), `ProcedureRegistrationError` (500) — each with a JSON Schema for the error response body shape
+- `defaultErrors()` returns 4 `ErrorDoc` entries describing `ProcedureError` (500), `ProcedureValidationError` (400), `ProcedureYieldValidationError` (500), `ProcedureRegistrationError` (500) — each with a JSON Schema for the error response body shape. Most consumers do not need to call this directly; the `DocRegistry` constructor auto-merges these unless `includeDefaults: false` is passed.
 - `JSON.stringify(registry)` works directly (calls `toJSON()` implicitly)
 
 ---

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

@@ -186,7 +186,7 @@ Seed the DocEnvelope with both taxonomy errors and framework defaults in one cal
 ```typescript
 import { DocRegistry } from 'ts-procedures/http-docs'
 
-const envelope = DocRegistry.fromTaxonomy(appErrors, { basePath: '/api' })
+const envelope = new DocRegistry({ errors: appErrors, basePath: '/api' })
   .from(apiApp)
   .from(rpcApp)
   .toJSON()
@@ -194,6 +194,13 @@ const envelope = DocRegistry.fromTaxonomy(appErrors, { basePath: '/api' })
 // 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.
@@ -805,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)
@@ -824,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
 
 ---
@@ -926,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/checklist.md

@@ -74,7 +74,7 @@
 
 ### SUGGESTION
 - [ ] Route documentation accessed via `builder.docs` for OpenAPI generation
-- [ ] Uses `DocRegistry.fromTaxonomy(appErrors)` (or plain `DocRegistry` with explicit `errors`) to compose docs from multiple builders
+- [ ] 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
 
@@ -115,7 +115,7 @@
 
 ### SUGGESTION
 - [ ] Route documentation accessed via `builder.docs` for OpenAPI generation
-- [ ] Uses `DocRegistry.fromTaxonomy(appErrors)` 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)
 

package/agent_config/copilot/copilot-instructions.md

@@ -218,7 +218,8 @@ class UseCaseError extends Error {
 }
 
 const appErrors = defineErrorTaxonomy({
-  // First-match wins — declare subclasses before base classes
+  // class: entries are topologically sorted (subclasses checked first) automatically.
+  // Predicate (match:) entries keep declared order — put narrower predicates first.
   UseCaseError: {
     class: UseCaseError,
     statusCode: 422,
@@ -254,7 +255,7 @@ const API = Procedures<Ctx, MyAPIConfig>()
 API.Create('GetUser', { path: '/users/:id', method: 'get', errors: ['UseCaseError'], /* ... */ }, ...)
 
 // Seed envelope errors from the taxonomy + framework defaults in one call
-const envelope = DocRegistry.fromTaxonomy(appErrors, { basePath: '/api' }).from(apiApp).toJSON()
+const envelope = new DocRegistry({ errors: appErrors, basePath: '/api' }).from(apiApp).toJSON()
 ```
 
 ### Client-side typed catch blocks (via codegen)

package/agent_config/cursor/cursorrules

@@ -218,7 +218,8 @@ class UseCaseError extends Error {
 }
 
 const appErrors = defineErrorTaxonomy({
-  // First-match wins — declare subclasses before base classes
+  // class: entries are topologically sorted (subclasses checked first) automatically.
+  // Predicate (match:) entries keep declared order — put narrower predicates first.
   UseCaseError: {
     class: UseCaseError,
     statusCode: 422,
@@ -254,7 +255,7 @@ const API = Procedures<Ctx, MyAPIConfig>()
 API.Create('GetUser', { path: '/users/:id', method: 'get', errors: ['UseCaseError'], /* ... */ }, ...)
 
 // Seed envelope errors from the taxonomy + framework defaults in one call
-const envelope = DocRegistry.fromTaxonomy(appErrors, { basePath: '/api' }).from(apiApp).toJSON()
+const envelope = new DocRegistry({ errors: appErrors, basePath: '/api' }).from(apiApp).toJSON()
 ```
 
 ### Client-side typed catch blocks (via codegen)

package/build/implementations/http/doc-registry.d.ts

@@ -1,33 +1,28 @@
 import type { AnyHttpRouteDoc, DocEnvelope, DocRegistryConfig, DocRegistryOutputOptions, DocSource, ErrorDoc } from '../types.js';
-import { ErrorTaxonomy } from './error-taxonomy.js';
 export type { AnyHttpRouteDoc, DocEnvelope, DocRegistryConfig, DocRegistryOutputOptions, DocSource, ErrorDoc, HeaderDoc, } from '../types.js';
 export declare class DocRegistry {
     private readonly basePath;
     private readonly headers;
-    private readonly errors;
+    private errors;
     private readonly sources;
     constructor(config?: DocRegistryConfig);
     from(source: DocSource<AnyHttpRouteDoc>): this;
-    toJSON<T = DocEnvelope>(options?: DocRegistryOutputOptions<T>): T;
     /**
-     * Framework error defaults for the DocEnvelope — derived from
-     * {@link defaultErrorTaxonomy} so the documented shape cannot drift from what
-     * the HTTP builders actually emit at runtime. `ProcedureRegistrationError` is
-     * appended because it's thrown at registration time (never at request time)
-     * and therefore lives only in the catalog, not the runtime taxonomy.
+     * Adds one or more {@link ErrorDoc} entries to the envelope. Use for errors
+     * outside your runtime taxonomy — middleware-level errors, infrastructure
+     * errors (502/503/504), or doc-only meta errors.
+     *
+     * Deduped by `name` — last write wins.
      */
-    static defaultErrors(): ErrorDoc[];
+    documentError(...docs: ErrorDoc[]): this;
+    toJSON<T = DocEnvelope>(options?: DocRegistryOutputOptions<T>): T;
     /**
-     * Convenience constructor that seeds `config.errors` from a taxonomy so the
-     * DocEnvelope automatically documents every error class registered with the
-     * HTTP builders. Framework defaults (including `ProcedureRegistrationError`)
-     * are included unless `includeDefaults: false` is passed.
+     * Framework error defaults — derived from {@link defaultErrorTaxonomy} plus
+     * `ProcedureRegistrationError` (which is thrown only at registration time
+     * and therefore lives in the catalog, not the runtime taxonomy).
      *
-     * @example
-     * const registry = DocRegistry.fromTaxonomy(appErrors, { basePath: '/api' })
-     *   .from(apiApp)
+     * Most consumers do not need to call this directly — the `DocRegistry`
+     * constructor auto-includes these unless `includeDefaults: false` is passed.
      */
-    static fromTaxonomy(taxonomy: ErrorTaxonomy, config?: Omit<DocRegistryConfig, 'errors'> & {
-        includeDefaults?: boolean;
-    }): DocRegistry;
+    static defaultErrors(): ErrorDoc[];
 }

package/build/implementations/http/doc-registry.js

@@ -1,23 +1,17 @@
-import { defaultErrorTaxonomy, taxonomyToErrorDocs, } from './error-taxonomy.js';
+import { PROCEDURE_REGISTRATION_ERROR_DOC, defaultErrorTaxonomy, taxonomyToErrorDocs, } from './error-taxonomy.js';
+function isTaxonomy(input) {
+    return !Array.isArray(input);
+}
 /**
- * `ProcedureRegistrationError` is thrown at procedure-definition time (never at
- * request time), so it doesn't appear in the runtime taxonomy. It is documented
- * here so consumers still see it in the error catalog.
+ * Dedupes ErrorDocs by `name`, last occurrence wins. Map insertion order
+ * preserves the latest position of each name.
  */
-const PROCEDURE_REGISTRATION_ERROR_DOC = {
-    name: 'ProcedureRegistrationError',
-    statusCode: 500,
-    description: 'An invalid schema or configuration was detected at procedure registration time.',
-    schema: {
-        type: 'object',
-        properties: {
-            name: { type: 'string', const: 'ProcedureRegistrationError' },
-            procedureName: { type: 'string' },
-            message: { type: 'string' },
-        },
-        required: ['name', 'procedureName', 'message'],
-    },
-};
+function dedupeByName(docs) {
+    const byName = new Map();
+    for (const doc of docs)
+        byName.set(doc.name, doc);
+    return Array.from(byName.values());
+}
 export class DocRegistry {
     basePath;
     headers;
@@ -26,12 +20,34 @@ export class DocRegistry {
     constructor(config) {
         this.basePath = config?.basePath ?? '';
         this.headers = config?.headers ?? [];
-        this.errors = config?.errors ?? [];
+        const includeDefaults = config?.includeDefaults ?? true;
+        const userErrors = config?.errors
+            ? isTaxonomy(config.errors)
+                ? taxonomyToErrorDocs(config.errors)
+                : config.errors
+            : [];
+        // Precedence: defaults come first, user errors override via dedupe
+        // (last-write-wins). Matches runtime resolution order.
+        const merged = includeDefaults
+            ? [...DocRegistry.defaultErrors(), ...userErrors]
+            : userErrors;
+        this.errors = dedupeByName(merged);
     }
     from(source) {
         this.sources.push(source);
         return this;
     }
+    /**
+     * Adds one or more {@link ErrorDoc} entries to the envelope. Use for errors
+     * outside your runtime taxonomy — middleware-level errors, infrastructure
+     * errors (502/503/504), or doc-only meta errors.
+     *
+     * Deduped by `name` — last write wins.
+     */
+    documentError(...docs) {
+        this.errors = dedupeByName([...this.errors, ...docs]);
+        return this;
+    }
     toJSON(options) {
         let routes = this.sources.flatMap((source) => source.docs);
         if (options?.filter) {
@@ -49,11 +65,12 @@ export class DocRegistry {
         return envelope;
     }
     /**
-     * Framework error defaults for the DocEnvelope — derived from
-     * {@link defaultErrorTaxonomy} so the documented shape cannot drift from what
-     * the HTTP builders actually emit at runtime. `ProcedureRegistrationError` is
-     * appended because it's thrown at registration time (never at request time)
-     * and therefore lives only in the catalog, not the runtime taxonomy.
+     * Framework error defaults — derived from {@link defaultErrorTaxonomy} plus
+     * `ProcedureRegistrationError` (which is thrown only at registration time
+     * and therefore lives in the catalog, not the runtime taxonomy).
+     *
+     * Most consumers do not need to call this directly — the `DocRegistry`
+     * constructor auto-includes these unless `includeDefaults: false` is passed.
      */
     static defaultErrors() {
         return [
@@ -61,27 +78,5 @@ export class DocRegistry {
             PROCEDURE_REGISTRATION_ERROR_DOC,
         ];
     }
-    /**
-     * Convenience constructor that seeds `config.errors` from a taxonomy so the
-     * DocEnvelope automatically documents every error class registered with the
-     * HTTP builders. Framework defaults (including `ProcedureRegistrationError`)
-     * are included unless `includeDefaults: false` is passed.
-     *
-     * @example
-     * const registry = DocRegistry.fromTaxonomy(appErrors, { basePath: '/api' })
-     *   .from(apiApp)
-     */
-    static fromTaxonomy(taxonomy, config) {
-        const { includeDefaults = true, ...rest } = config ?? {};
-        const errors = [
-            ...taxonomyToErrorDocs(taxonomy),
-            ...(includeDefaults ? DocRegistry.defaultErrors() : []),
-        ];
-        // Dedupe by name — user entries take precedence over defaults with the
-        // same key, matching runtime resolution order.
-        const seen = new Set();
-        const deduped = errors.filter((e) => seen.has(e.name) ? false : (seen.add(e.name), true));
-        return new DocRegistry({ ...rest, errors: deduped });
-    }
 }
 //# sourceMappingURL=doc-registry.js.map

package/build/implementations/http/doc-registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"doc-registry.js","sourceRoot":"","sources":["../../../src/implementations/http/doc-registry.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"doc-registry.js","sourceRoot":"","sources":["../../../src/implementations/http/doc-registry.ts"],"names":[],"mappings":"AASA,OAAO,EACL,gCAAgC,EAChC,oBAAoB,EACpB,mBAAmB,GAEpB,MAAM,qBAAqB,CAAA;AAY5B,SAAS,UAAU,CAAC,KAAiC;IACnD,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;AAC9B,CAAC;AAED;;;GAGG;AACH,SAAS,YAAY,CAAC,IAAgB;IACpC,MAAM,MAAM,GAAG,IAAI,GAAG,EAAoB,CAAA;IAC1C,KAAK,MAAM,GAAG,IAAI,IAAI;QAAE,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAA;IACjD,OAAO,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAA;AACpC,CAAC;AAED,MAAM,OAAO,WAAW;IACL,QAAQ,CAAQ;IAChB,OAAO,CAAa;IAC7B,MAAM,CAAY;IACT,OAAO,GAAiC,EAAE,CAAA;IAE3D,YAAY,MAA0B;QACpC,IAAI,CAAC,QAAQ,GAAG,MAAM,EAAE,QAAQ,IAAI,EAAE,CAAA;QACtC,IAAI,CAAC,OAAO,GAAG,MAAM,EAAE,OAAO,IAAI,EAAE,CAAA;QAEpC,MAAM,eAAe,GAAG,MAAM,EAAE,eAAe,IAAI,IAAI,CAAA;QACvD,MAAM,UAAU,GAAe,MAAM,EAAE,MAAM;YAC3C,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC;gBACzB,CAAC,CAAC,mBAAmB,CAAC,MAAM,CAAC,MAAM,CAAC;gBACpC,CAAC,CAAC,MAAM,CAAC,MAAM;YACjB,CAAC,CAAC,EAAE,CAAA;QAEN,mEAAmE;QACnE,uDAAuD;QACvD,MAAM,MAAM,GAAG,eAAe;YAC5B,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,aAAa,EAAE,EAAE,GAAG,UAAU,CAAC;YACjD,CAAC,CAAC,UAAU,CAAA;QAEd,IAAI,CAAC,MAAM,GAAG,YAAY,CAAC,MAAM,CAAC,CAAA;IACpC,CAAC;IAED,IAAI,CAAC,MAAkC;QACrC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;QACzB,OAAO,IAAI,CAAA;IACb,CAAC;IAED;;;;;;OAMG;IACH,aAAa,CAAC,GAAG,IAAgB;QAC/B,IAAI,CAAC,MAAM,GAAG,YAAY,CAAC,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC,CAAA;QACrD,OAAO,IAAI,CAAA;IACb,CAAC;IAED,MAAM,CAAkB,OAAqC;QAC3D,IAAI,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;QAE1D,IAAI,OAAO,EAAE,MAAM,EAAE,CAAC;YACpB,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAA;QACxC,CAAC;QAED,MAAM,QAAQ,GAAgB;YAC5B,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,OAAO,EAAE,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC;YAC1B,MAAM,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC;YACxB,MAAM;SACP,CAAA;QAED,IAAI,OAAO,EAAE,SAAS,EAAE,CAAC;YACvB,OAAO,OAAO,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAA;QACpC,CAAC;QAED,OAAO,QAAa,CAAA;IACtB,CAAC;IAED;;;;;;;OAOG;IACH,MAAM,CAAC,aAAa;QAClB,OAAO;YACL,GAAG,mBAAmB,CAAC,oBAAoB,CAAC;YAC5C,gCAAgC;SACjC,CAAA;IACH,CAAC;CACF"}

package/build/implementations/http/doc-registry.test.js

@@ -3,6 +3,7 @@ import { v } from 'suretype';
 import { Procedures } from '../../index.js';
 import { HonoRPCAppBuilder } from './hono-rpc/index.js';
 import { DocRegistry } from './doc-registry.js';
+import { defineErrorTaxonomy } from './error-taxonomy.js';
 // ---------------------------------------------------------------------------
 // Helpers — minimal doc fixtures
 // ---------------------------------------------------------------------------
@@ -45,14 +46,14 @@ describe('DocRegistry', () => {
     // --------------------------------------------------------------------------
     describe('constructor', () => {
         test('uses defaults when no config provided', () => {
-            const registry = new DocRegistry();
+            const registry = new DocRegistry({ includeDefaults: false });
             const out = registry.toJSON();
             expect(out.basePath).toBe('');
             expect(out.headers).toEqual([]);
             expect(out.errors).toEqual([]);
         });
         test('accepts partial config', () => {
-            const registry = new DocRegistry({ basePath: '/v1' });
+            const registry = new DocRegistry({ basePath: '/v1', includeDefaults: false });
             const out = registry.toJSON();
             expect(out.basePath).toBe('/v1');
             expect(out.headers).toEqual([]);
@@ -61,7 +62,7 @@ describe('DocRegistry', () => {
         test('accepts full config', () => {
             const headers = [{ name: 'Authorization', description: 'Bearer token', required: true }];
             const errors = [{ name: 'Unauthorized', statusCode: 401, description: 'Missing token' }];
-            const registry = new DocRegistry({ basePath: '/api', headers, errors });
+            const registry = new DocRegistry({ basePath: '/api', headers, errors, includeDefaults: false });
             const out = registry.toJSON();
             expect(out.basePath).toBe('/api');
             expect(out.headers).toEqual(headers);
@@ -142,7 +143,7 @@ describe('DocRegistry', () => {
         test('headers and errors are copies', () => {
             const headers = [{ name: 'X-Custom' }];
             const errors = [{ name: 'E', statusCode: 500, description: 'd' }];
-            const registry = new DocRegistry({ headers, errors });
+            const registry = new DocRegistry({ headers, errors, includeDefaults: false });
             const out = registry.toJSON();
             expect(out.headers).toEqual(headers);
             expect(out.headers).not.toBe(headers);
@@ -249,6 +250,141 @@ describe('DocRegistry', () => {
         });
     });
     // --------------------------------------------------------------------------
+    // taxonomy input + auto-defaults + dedupe (v6.0.1 simplification)
+    // --------------------------------------------------------------------------
+    describe('errors: ErrorTaxonomy (polymorphic constructor input)', () => {
+        test('accepts an ErrorTaxonomy directly and converts to ErrorDoc[]', () => {
+            const taxonomy = defineErrorTaxonomy({
+                AuthError: {
+                    class: class AuthError extends Error {
+                    },
+                    statusCode: 401,
+                    description: 'unauthenticated',
+                },
+            });
+            const envelope = new DocRegistry({ errors: taxonomy }).toJSON();
+            const auth = envelope.errors.find((e) => e.name === 'AuthError');
+            expect(auth).toBeDefined();
+            expect(auth?.statusCode).toBe(401);
+            expect(auth?.description).toBe('unauthenticated');
+        });
+        test('auto-includes framework defaults when errors is a taxonomy', () => {
+            const taxonomy = defineErrorTaxonomy({
+                AuthError: { class: class AuthError extends Error {
+                    }, statusCode: 401 },
+            });
+            const names = new DocRegistry({ errors: taxonomy }).toJSON().errors.map((e) => e.name);
+            expect(names).toContain('AuthError');
+            expect(names).toContain('ProcedureValidationError');
+            expect(names).toContain('ProcedureYieldValidationError');
+            expect(names).toContain('ProcedureError');
+            expect(names).toContain('ProcedureRegistrationError');
+        });
+        test('auto-includes framework defaults when errors is ErrorDoc[]', () => {
+            const custom = { name: 'CustomThing', statusCode: 418, description: 'teapot' };
+            const names = new DocRegistry({ errors: [custom] }).toJSON().errors.map((e) => e.name);
+            expect(names).toContain('CustomThing');
+            expect(names).toContain('ProcedureValidationError');
+        });
+        test('includeDefaults: false omits framework defaults', () => {
+            const taxonomy = defineErrorTaxonomy({
+                AuthError: { class: class AuthError extends Error {
+                    }, statusCode: 401 },
+            });
+            const names = new DocRegistry({ errors: taxonomy, includeDefaults: false })
+                .toJSON()
+                .errors.map((e) => e.name);
+            expect(names).toEqual(['AuthError']);
+        });
+        test('user taxonomy entry with same name as default overrides default (dedupe, user wins)', () => {
+            const taxonomy = defineErrorTaxonomy({
+                ProcedureError: {
+                    class: Error,
+                    statusCode: 418,
+                    description: 'custom override',
+                },
+            });
+            const envelope = new DocRegistry({ errors: taxonomy }).toJSON();
+            const proc = envelope.errors.filter((e) => e.name === 'ProcedureError');
+            expect(proc).toHaveLength(1);
+            expect(proc[0].statusCode).toBe(418);
+            expect(proc[0].description).toBe('custom override');
+        });
+        test('user ErrorDoc with same name as default overrides default (dedupe, user wins)', () => {
+            const custom = {
+                name: 'ProcedureError',
+                statusCode: 418,
+                description: 'custom override',
+            };
+            const envelope = new DocRegistry({ errors: [custom] }).toJSON();
+            const proc = envelope.errors.filter((e) => e.name === 'ProcedureError');
+            expect(proc).toHaveLength(1);
+            expect(proc[0].statusCode).toBe(418);
+            expect(proc[0].description).toBe('custom override');
+        });
+        test('empty errors config still returns framework defaults', () => {
+            const names = new DocRegistry().toJSON().errors.map((e) => e.name);
+            expect(names).toContain('ProcedureError');
+            expect(names).toContain('ProcedureValidationError');
+            expect(names).toContain('ProcedureYieldValidationError');
+            expect(names).toContain('ProcedureRegistrationError');
+        });
+        test('includeDefaults: false with no errors produces empty error list', () => {
+            const envelope = new DocRegistry({ includeDefaults: false }).toJSON();
+            expect(envelope.errors).toEqual([]);
+        });
+    });
+    // --------------------------------------------------------------------------
+    // .documentError() fluent extension
+    // --------------------------------------------------------------------------
+    describe('.documentError()', () => {
+        test('adds a single ErrorDoc to the envelope', () => {
+            const registry = new DocRegistry({ includeDefaults: false }).documentError({
+                name: 'RateLimitExceeded',
+                statusCode: 429,
+                description: 'too many requests',
+            });
+            const names = registry.toJSON().errors.map((e) => e.name);
+            expect(names).toEqual(['RateLimitExceeded']);
+        });
+        test('accepts multiple docs via variadic args', () => {
+            const registry = new DocRegistry({ includeDefaults: false }).documentError({ name: 'A', statusCode: 400, description: 'a' }, { name: 'B', statusCode: 500, description: 'b' });
+            const names = registry.toJSON().errors.map((e) => e.name);
+            expect(names).toEqual(['A', 'B']);
+        });
+        test('returns this for chaining', () => {
+            const registry = new DocRegistry();
+            const returned = registry.documentError({
+                name: 'Foo',
+                statusCode: 500,
+                description: 'x',
+            });
+            expect(returned).toBe(registry);
+        });
+        test('composes with taxonomy input — extends docs without replacing', () => {
+            const taxonomy = defineErrorTaxonomy({
+                AuthError: { class: class AuthError extends Error {
+                    }, statusCode: 401 },
+            });
+            const envelope = new DocRegistry({ errors: taxonomy })
+                .documentError({ name: 'RateLimitExceeded', statusCode: 429, description: 'x' })
+                .toJSON();
+            const names = envelope.errors.map((e) => e.name);
+            expect(names).toContain('AuthError');
+            expect(names).toContain('RateLimitExceeded');
+            expect(names).toContain('ProcedureValidationError');
+        });
+        test('dedupes against existing errors (last write wins)', () => {
+            const registry = new DocRegistry({ includeDefaults: false })
+                .documentError({ name: 'Foo', statusCode: 400, description: 'first' })
+                .documentError({ name: 'Foo', statusCode: 500, description: 'second' });
+            const foo = registry.toJSON().errors.filter((e) => e.name === 'Foo');
+            expect(foo).toHaveLength(1);
+            expect(foo[0].statusCode).toBe(500);
+            expect(foo[0].description).toBe('second');
+        });
+    });
+    // --------------------------------------------------------------------------
     // kind discriminant
     // --------------------------------------------------------------------------
     describe('kind discriminant', () => {
@@ -279,7 +415,6 @@ describe('DocRegistry', () => {
             const registry = new DocRegistry({
                 basePath: '/api',
                 headers: [{ name: 'Authorization', description: 'Bearer token', required: false }],
-                errors: DocRegistry.defaultErrors(),
             })
                 .from(makeSource([rpcDoc]))
                 .from(makeSource([apiDoc]))
@@ -291,10 +426,7 @@ describe('DocRegistry', () => {
             expect(out.routes).toHaveLength(3);
         });
         test('filter + transform combined', () => {
-            const registry = new DocRegistry({
-                basePath: '/api',
-                errors: DocRegistry.defaultErrors(),
-            })
+            const registry = new DocRegistry({ basePath: '/api' })
                 .from(makeSource([rpcDoc]))
                 .from(makeSource([apiDoc]))
                 .from(makeSource([streamDoc]));
@@ -313,7 +445,6 @@ describe('DocRegistry', () => {
             const registry = new DocRegistry({
                 basePath: '/api',
                 headers: [{ name: 'X-Request-Id', example: 'abc-123' }],
-                errors: DocRegistry.defaultErrors(),
             })
                 .from(makeSource([rpcDoc]))
                 .from(makeSource([apiDoc]));