ts-procedures 6.0.0 → 6.0.2

package/build/codegen/targets/kotlin/emit-scope-kotlin.test.js

@@ -0,0 +1,52 @@
+import { describe, expect, it } from 'vitest';
+import { emitKotlinScope } from './emit-scope-kotlin.js';
+import { createStubKotlinEmitter } from './ajsc-adapter.js';
+const ok = (code, rootTypeName) => ({
+    code,
+    rootTypeName,
+    extractedTypeNames: [],
+    imports: ['kotlinx.serialization.Serializable'],
+});
+describe('emitKotlinScope', () => {
+    it('produces a complete kotlin source file for a single-route scope', () => {
+        const route = {
+            kind: 'api',
+            name: 'GetUser',
+            method: 'GET',
+            fullPath: '/users/:id',
+            schema: { input: { pathParams: { type: 'object' } }, returnType: { type: 'object' } },
+            errors: [],
+        };
+        const group = { scopeKey: 'users', camelCase: 'users', routes: [route] };
+        const emitter = createStubKotlinEmitter({
+            PathParams: ok('@Serializable data class PathParams(val id: String)', 'PathParams'),
+            Response: ok('@Serializable data class Response(val id: String)', 'Response'),
+        });
+        const file = emitKotlinScope(group, { kotlinPackage: 'com.example.api', sourceHash: 'abc123' }, emitter, new Map());
+        expect(file.filename).toBe('Users.kt');
+        expect(file.code).toContain('package com.example.api');
+        expect(file.code).toContain('// Source hash: abc123');
+        expect(file.code).toContain('import kotlinx.serialization.Serializable');
+        expect(file.code).toContain('object Users {');
+        expect(file.code).toContain('object GetUser {');
+        expect(file.code).toContain('const val method = "GET"');
+    });
+    it('joins multiple routes inside one scope object', () => {
+        const route1 = { kind: 'api', name: 'GetUser', method: 'GET', fullPath: '/users/:id', schema: {}, errors: [] };
+        const route2 = { kind: 'api', name: 'CreateUser', method: 'POST', fullPath: '/users', schema: {}, errors: [] };
+        const group = { scopeKey: 'users', camelCase: 'users', routes: [route1, route2] };
+        const emitter = createStubKotlinEmitter({});
+        const file = emitKotlinScope(group, { kotlinPackage: 'com.example.api', sourceHash: 'h' }, emitter, new Map());
+        expect(file.code).toContain('object GetUser {');
+        expect(file.code).toContain('object CreateUser {');
+        // exactly one outer scope object
+        expect((file.code.match(/^object Users \{/gm) ?? []).length).toBe(1);
+    });
+    it('uses PascalCase scope name for the filename and outer object', () => {
+        const group = { scopeKey: 'admin-users', camelCase: 'adminUsers', routes: [] };
+        const file = emitKotlinScope(group, { kotlinPackage: 'p', sourceHash: 'h' }, createStubKotlinEmitter({}), new Map());
+        expect(file.filename).toBe('AdminUsers.kt');
+        expect(file.code).toContain('object AdminUsers {');
+    });
+});
+//# sourceMappingURL=emit-scope-kotlin.test.js.map

package/build/codegen/targets/kotlin/emit-scope-kotlin.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"emit-scope-kotlin.test.js","sourceRoot":"","sources":["../../../../src/codegen/targets/kotlin/emit-scope-kotlin.test.ts"],"names":[],"mappings":"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"}

package/build/codegen/targets/kotlin/format-kotlin.d.ts

@@ -0,0 +1,4 @@
+export declare function kotlinPackageDecl(pkg: string): string;
+export declare function kotlinSourceHashHeader(hash: string): string;
+export declare function kotlinImports(imports: string[]): string;
+export declare function indent(text: string, level: number): string;

package/build/codegen/targets/kotlin/format-kotlin.js

@@ -0,0 +1,20 @@
+export function kotlinPackageDecl(pkg) {
+    return `package ${pkg}`;
+}
+export function kotlinSourceHashHeader(hash) {
+    return `// Source hash: ${hash}`;
+}
+export function kotlinImports(imports) {
+    if (imports.length === 0)
+        return '';
+    const unique = Array.from(new Set(imports)).sort();
+    return unique.map((i) => `import ${i}`).join('\n');
+}
+export function indent(text, level) {
+    const prefix = '    '.repeat(level);
+    return text
+        .split('\n')
+        .map((line) => (line.length === 0 ? line : `${prefix}${line}`))
+        .join('\n');
+}
+//# sourceMappingURL=format-kotlin.js.map

package/build/codegen/targets/kotlin/format-kotlin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-kotlin.js","sourceRoot":"","sources":["../../../../src/codegen/targets/kotlin/format-kotlin.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,iBAAiB,CAAC,GAAW;IAC3C,OAAO,WAAW,GAAG,EAAE,CAAA;AACzB,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,IAAY;IACjD,OAAO,mBAAmB,IAAI,EAAE,CAAA;AAClC,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,OAAiB;IAC7C,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAA;IACnC,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,EAAE,CAAA;IAClD,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AACpD,CAAC;AAED,MAAM,UAAU,MAAM,CAAC,IAAY,EAAE,KAAa;IAChD,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;IACnC,OAAO,IAAI;SACR,KAAK,CAAC,IAAI,CAAC;SACX,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,MAAM,GAAG,IAAI,EAAE,CAAC,CAAC;SAC9D,IAAI,CAAC,IAAI,CAAC,CAAA;AACf,CAAC"}

package/build/codegen/targets/kotlin/format-kotlin.test.d.ts

@@ -0,0 +1 @@
+export {};

package/build/codegen/targets/kotlin/format-kotlin.test.js

@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'vitest';
+import { kotlinPackageDecl, kotlinSourceHashHeader, kotlinImports, indent, } from './format-kotlin.js';
+describe('format-kotlin', () => {
+    it('emits a package declaration', () => {
+        expect(kotlinPackageDecl('com.example.api')).toBe('package com.example.api');
+    });
+    it('emits a source-hash header line', () => {
+        expect(kotlinSourceHashHeader('abc123')).toBe('// Source hash: abc123');
+    });
+    it('dedupes and sorts imports', () => {
+        expect(kotlinImports(['kotlinx.serialization.Serializable', 'kotlinx.serialization.SerialName', 'kotlinx.serialization.Serializable'])).toBe('import kotlinx.serialization.SerialName\nimport kotlinx.serialization.Serializable');
+    });
+    it('returns empty string when no imports', () => {
+        expect(kotlinImports([])).toBe('');
+    });
+    it('indents every line by 4 spaces per level', () => {
+        expect(indent('a\nb', 1)).toBe('    a\n    b');
+        expect(indent('a', 2)).toBe('        a');
+    });
+    it('preserves blank lines without trailing whitespace when indenting', () => {
+        expect(indent('a\n\nb', 1)).toBe('    a\n\n    b');
+    });
+});
+//# sourceMappingURL=format-kotlin.test.js.map

package/build/codegen/targets/kotlin/format-kotlin.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-kotlin.test.js","sourceRoot":"","sources":["../../../../src/codegen/targets/kotlin/format-kotlin.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAA;AAC7C,OAAO,EACL,iBAAiB,EACjB,sBAAsB,EACtB,aAAa,EACb,MAAM,GACP,MAAM,oBAAoB,CAAA;AAE3B,QAAQ,CAAC,eAAe,EAAE,GAAG,EAAE;IAC7B,EAAE,CAAC,6BAA6B,EAAE,GAAG,EAAE;QACrC,MAAM,CAAC,iBAAiB,CAAC,iBAAiB,CAAC,CAAC,CAAC,IAAI,CAAC,yBAAyB,CAAC,CAAA;IAC9E,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,iCAAiC,EAAE,GAAG,EAAE;QACzC,MAAM,CAAC,sBAAsB,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,wBAAwB,CAAC,CAAA;IACzE,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,2BAA2B,EAAE,GAAG,EAAE;QACnC,MAAM,CAAC,aAAa,CAAC,CAAC,oCAAoC,EAAE,kCAAkC,EAAE,oCAAoC,CAAC,CAAC,CAAC,CAAC,IAAI,CAC1I,oFAAoF,CACrF,CAAA;IACH,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,sCAAsC,EAAE,GAAG,EAAE;QAC9C,MAAM,CAAC,aAAa,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;IACpC,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,0CAA0C,EAAE,GAAG,EAAE;QAClD,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC,CAAA;QAC9C,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,CAAA;IAC1C,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,kEAAkE,EAAE,GAAG,EAAE;QAC1E,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAA;IACpD,CAAC,CAAC,CAAA;AACJ,CAAC,CAAC,CAAA"}

package/build/codegen/targets/kotlin/integration.test.d.ts

@@ -0,0 +1 @@
+export {};

package/build/codegen/targets/kotlin/integration.test.js

@@ -0,0 +1,34 @@
+import { describe, expect, it } from 'vitest';
+import { readFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { runPipeline } from '../../pipeline.js';
+import { createStubKotlinEmitter } from './ajsc-adapter.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+describe('kotlin codegen — integration', () => {
+    it('produces byte-identical output against the golden fixture', async () => {
+        const envelopePath = join(__dirname, '__fixtures__/users-envelope.json');
+        const goldenPath = join(__dirname, '__fixtures__/users-golden.kt');
+        const envelope = JSON.parse(await readFile(envelopePath, 'utf8'));
+        const goldenTemplate = await readFile(goldenPath, 'utf8');
+        const emitter = createStubKotlinEmitter({
+            PathParams: { code: '@Serializable\ndata class PathParams(val id: String)', rootTypeName: 'PathParams', extractedTypeNames: [], imports: ['kotlinx.serialization.Serializable'] },
+            Response: { code: '@Serializable\ndata class Response(val id: String, val name: String)', rootTypeName: 'Response', extractedTypeNames: [], imports: ['kotlinx.serialization.Serializable'] },
+            Body: { code: '@Serializable\ndata class Body(val name: String, val email: String)', rootTypeName: 'Body', extractedTypeNames: [], imports: ['kotlinx.serialization.Serializable'] },
+            NotFound: { code: '@Serializable\ndata class NotFound(val name: String = "NotFound", val message: String)', rootTypeName: 'NotFound', extractedTypeNames: [], imports: ['kotlinx.serialization.Serializable'] },
+        });
+        const files = await runPipeline({
+            envelope, outDir: 'out', dryRun: true,
+            target: 'kotlin', kotlinPackage: 'com.example.api',
+            kotlinEmitter: emitter,
+        });
+        expect(files).toHaveLength(1);
+        expect(files[0].path).toBe(join('out', 'Users.kt'));
+        // Hash is deterministic given envelope contents; splice into golden template.
+        const sourceHashLine = files[0].code.split('\n').find((l) => l.startsWith('// Source hash:')) ?? '';
+        const goldenWithHash = goldenTemplate.replace('// Source hash: <PLACEHOLDER>', sourceHashLine);
+        expect(files[0].code).toBe(goldenWithHash);
+    });
+});
+//# sourceMappingURL=integration.test.js.map

package/build/codegen/targets/kotlin/integration.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"integration.test.js","sourceRoot":"","sources":["../../../../src/codegen/targets/kotlin/integration.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAA;AAC7C,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AAC3C,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AACzC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AACxC,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAC/C,OAAO,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAA;AAE3D,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;AACjD,MAAM,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,CAAA;AAErC,QAAQ,CAAC,8BAA8B,EAAE,GAAG,EAAE;IAC5C,EAAE,CAAC,2DAA2D,EAAE,KAAK,IAAI,EAAE;QACzE,MAAM,YAAY,GAAG,IAAI,CAAC,SAAS,EAAE,kCAAkC,CAAC,CAAA;QACxE,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,EAAE,8BAA8B,CAAC,CAAA;QAClE,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC,CAAA;QACjE,MAAM,cAAc,GAAG,MAAM,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC,CAAA;QAEzD,MAAM,OAAO,GAAG,uBAAuB,CAAC;YACtC,UAAU,EAAE,EAAE,IAAI,EAAE,sDAAsD,EAAE,YAAY,EAAE,YAAY,EAAE,kBAAkB,EAAE,EAAE,EAAE,OAAO,EAAE,CAAC,oCAAoC,CAAC,EAAE;YACjL,QAAQ,EAAE,EAAE,IAAI,EAAE,sEAAsE,EAAE,YAAY,EAAE,UAAU,EAAE,kBAAkB,EAAE,EAAE,EAAE,OAAO,EAAE,CAAC,oCAAoC,CAAC,EAAE;YAC7L,IAAI,EAAE,EAAE,IAAI,EAAE,qEAAqE,EAAE,YAAY,EAAE,MAAM,EAAE,kBAAkB,EAAE,EAAE,EAAE,OAAO,EAAE,CAAC,oCAAoC,CAAC,EAAE;YACpL,QAAQ,EAAE,EAAE,IAAI,EAAE,wFAAwF,EAAE,YAAY,EAAE,UAAU,EAAE,kBAAkB,EAAE,EAAE,EAAE,OAAO,EAAE,CAAC,oCAAoC,CAAC,EAAE;SAChN,CAAC,CAAA;QAEF,MAAM,KAAK,GAAG,MAAM,WAAW,CAAC;YAC9B,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI;YACrC,MAAM,EAAE,QAAQ,EAAE,aAAa,EAAE,iBAAiB;YAClD,aAAa,EAAE,OAAO;SACvB,CAAC,CAAA;QAEF,MAAM,CAAC,KAAK,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAA;QAC7B,MAAM,CAAC,KAAK,CAAC,CAAC,CAAE,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC,CAAA;QAEpD,8EAA8E;QAC9E,MAAM,cAAc,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,iBAAiB,CAAC,CAAC,IAAI,EAAE,CAAA;QACpG,MAAM,cAAc,GAAG,cAAc,CAAC,OAAO,CAAC,+BAA+B,EAAE,cAAc,CAAC,CAAA;QAC9F,MAAM,CAAC,KAAK,CAAC,CAAC,CAAE,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC,CAAA;IAC7C,CAAC,CAAC,CAAA;AACJ,CAAC,CAAC,CAAA"}

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]));