ts-procedures 6.0.0 → 6.0.2

package/docs/superpowers/specs/2026-04-24-kotlin-swift-codegen-design.md

@@ -0,0 +1,401 @@
+# Kotlin & Swift Codegen for ts-procedures
+
+**Status:** Design
+**Date:** 2026-04-24
+**Author:** Cory Robinson
+**Implementation order:** Kotlin first, Swift second.
+
+## Context
+
+`ts-procedures` already generates a TypeScript client from a `DocEnvelope` so web developers consume backend procedures with full type safety and zero schema duplication. The same problem exists for native mobile consumers: Android and iOS developers currently hand-write request/response types that mirror the server's schema, then re-edit those types every time the backend changes. This is the precise pain the TS codegen was built to eliminate — extending it to Kotlin and Swift removes the same drift for mobile.
+
+## Goals
+
+1. Generate **Kotlin** and **Swift** type definitions plus URL/method primitives directly from a ts-procedures `DocEnvelope`.
+2. Be **non-invasive**: do not impose an HTTP stack, networking adapter, or runtime dependency on downstream mobile codebases.
+3. Preserve dot-notation ergonomics consistent with the TS namespace mode (`Users.GetUser.Response`) so mobile devs can reference generated types directly in their own code.
+4. Keep the codegen surface and maintenance burden **small** — add Kotlin/Swift without forcing a parallel runtime client to track every TS-side change.
+
+## Non-goals (explicit deferrals)
+
+- **No call functions, HTTP adapter, or reference adapter implementation.** Mobile devs own the HTTP layer entirely.
+- **No streams (SSE).** Stream support is deferred; mobile devs needing streaming wire it themselves.
+- **No hooks pipeline** (`onBeforeRequest` / `onAfterResponse` / `onError` / `onRequestError`).
+- **No per-call options** (`signal`, `timeout`, `headers`, `basePath`, `meta`).
+- **No error registry or typed error dispatch logic.** Error *types* are emitted; runtime dispatch is the consumer's job.
+- **No base-URL handling.** Generated paths are relative; consumers prepend their environment base URL.
+- **No Kotlin Multiplatform-specific output.** Initial Kotlin target is JVM/Android; KMP-friendliness comes from kotlinx.serialization but is not a tested target.
+
+These are deliberate scope cuts, not architectural impossibilities — they may be revisited in a follow-up once the minimum-viable target is in production use.
+
+## Architecture overview
+
+Two packages collaborate:
+
+- **`ajsc`** owns "JSON Schema → target-language types." Today it emits TypeScript; this design extends it with Kotlin and Swift emitters that share its existing schema walker, naming-convention logic (`enumStyle`, `depluralize`, `arrayItemNaming`, `uncountableWords`), and sub-type extraction.
+- **`ts-procedures`** owns "DocEnvelope → per-scope output files." It resolves the envelope, groups routes by scope, calls into ajsc once per schema slot (path params / query / body / response / per-error type), and wraps the returned code in route-level `object` (Kotlin) or case-less `enum` (Swift) blocks alongside HTTP method constants and path builders.
+
+```
+DocEnvelope
+   │
+   ├── ts-procedures: resolveEnvelope → groupRoutesByScope
+   │
+   └── per route, per schema slot:
+         │
+         ├── ajsc.emitKotlin(schema, opts) → { code, rootTypeName, extractedTypeNames, imports }
+         │
+         └── ts-procedures wraps emitted code into:
+               object Users { object GetUser {
+                 const val method = "GET"
+                 const val pathTemplate = "/users/{id}"
+                 fun path(p: PathParams): String = "/users/${p.id}"
+                 // <ajsc-emitted PathParams, Response, Errors.* types here>
+               } }
+```
+
+ts-procedures never does schema → type emission itself. ajsc never knows about routes, scopes, or DocEnvelopes.
+
+## Generated output shape
+
+### Kotlin
+
+One file per scope (mirrors the TS codegen). Path templates emit as constants when there are no path params; as a function when there are.
+
+```kotlin
+// users.kt — generated by ts-procedures-codegen, do not edit
+package com.example.api  // configurable
+
+import kotlinx.serialization.Serializable
+import kotlinx.serialization.SerialName
+
+object Users {
+    object GetUser {
+        const val method = "GET"
+        const val pathTemplate = "/users/{id}"
+        fun path(p: PathParams): String = "/users/${p.id}"
+
+        @Serializable data class PathParams(val id: String)
+
+        @Serializable data class Response(
+            val id: String,
+            val name: String,
+            val address: Address,
+        )
+
+        // sub-type extracted from Response.address
+        @Serializable data class Address(val street: String, val city: String)
+
+        object Errors {
+            // `name` is a regular String field with a constructor default matching the
+            // server's wire-protocol value. kotlinx.serialization does not enforce
+            // literal-type discriminators here — consumers identify error variants by
+            // checking `body.name` themselves (this is a deliberate non-goal of the
+            // generated code, see "Non-goals" → no error registry).
+            @Serializable data class NotFound(
+                val name: String = "NotFound",
+                val message: String,
+            )
+        }
+    }
+
+    object CreateUser {
+        const val method = "POST"
+        const val path = "/users"  // no path params → const, not a function
+
+        @Serializable data class Body(val name: String, val email: String)
+        @Serializable data class Response(val id: String)
+    }
+}
+```
+
+### Swift
+
+Same structure using case-less `enum` as a namespace idiom. One file per scope.
+
+```swift
+// Users.swift — generated by ts-procedures-codegen, do not edit
+import Foundation
+
+public enum Users {
+    public enum GetUser {
+        public static let method = "GET"
+        public static let pathTemplate = "/users/{id}"
+        public static func path(_ p: PathParams) -> String { "/users/\(p.id)" }
+
+        public struct PathParams: Codable {
+            public let id: String
+            public init(id: String) { self.id = id }
+        }
+
+        public struct Response: Codable {
+            public let id: String
+            public let name: String
+            public let address: Address
+        }
+
+        public struct Address: Codable {
+            public let street: String
+            public let city: String
+        }
+
+        public enum Errors {
+            public struct NotFound: Codable, Error {
+                public let name: String
+                public let message: String
+            }
+        }
+    }
+
+    public enum CreateUser {
+        public static let method = "POST"
+        public static let path = "/users"
+
+        public struct Body: Codable {
+            public let name: String
+            public let email: String
+        }
+        public struct Response: Codable { public let id: String }
+    }
+}
+```
+
+### Consumer usage (illustrative, not generated)
+
+```kotlin
+// downstream Android repo
+suspend fun loadUser(id: String): Users.GetUser.Response {
+    val path = Users.GetUser.path(Users.GetUser.PathParams(id))
+    val raw = myHttpClient.request(method = Users.GetUser.method, path = "$baseUrl$path")
+    return Json.decodeFromString(raw.body)
+}
+```
+
+```swift
+// downstream iOS repo
+func loadUser(id: String) async throws -> Users.GetUser.Response {
+    let path = Users.GetUser.path(.init(id: id))
+    let data = try await myHTTP.get(baseURL + path)
+    return try JSONDecoder().decode(Users.GetUser.Response.self, from: data)
+}
+```
+
+## ajsc contract
+
+The single most important artifact for cross-team coordination. ajsc adds two emitter entry points; ts-procedures depends on them.
+
+### API
+
+```ts
+// ajsc/kotlin
+emitKotlin(schema: JSONSchema, opts: KotlinEmitOptions): EmitResult
+
+// ajsc/swift
+emitSwift(schema: JSONSchema, opts: SwiftEmitOptions): EmitResult
+
+interface EmitResult {
+  /** Target-language source (no surrounding namespace; ts-procedures wraps). */
+  code: string
+  /** Name of the top-level type emitted, derived from opts.rootTypeName. */
+  rootTypeName: string
+  /** Names of all extracted sub-types (for caller reference resolution). */
+  extractedTypeNames: string[]
+  /** Required import lines for this output (e.g., kotlinx.serialization.*). */
+  imports: string[]
+}
+
+interface KotlinEmitOptions {
+  /** Caller-supplied root type name (e.g., "Response", "PathParams"). */
+  rootTypeName: string
+  /** Default false. When false, nested objects extract to named siblings. */
+  inlineTypes?: boolean
+  /** Phase 1: 'kotlinx' only. Reserved: 'moshi', 'none'. */
+  serializer?: 'kotlinx'
+  // carried over from existing TS-side ajsc options:
+  enumStyle?: ...
+  depluralize?: boolean
+  arrayItemNaming?: ...
+  uncountableWords?: string[]
+}
+
+interface SwiftEmitOptions {
+  rootTypeName: string
+  inlineTypes?: boolean
+  // Codable is the only target; no serializer flag.
+  enumStyle?: ...
+  depluralize?: boolean
+  arrayItemNaming?: ...
+  uncountableWords?: string[]
+}
+```
+
+### Why the return shape matters
+
+ts-procedures must reference emitted type names (e.g., the path-builder function takes `PathParams`; the wrapping `object GetUser` body lists each emitted name). Returning `rootTypeName` and `extractedTypeNames` explicitly avoids string-parsing ajsc's output and survives changes to ajsc's formatting.
+
+### Type-mapping specification (Kotlin)
+
+| JSON Schema | Kotlin | Notes |
+|---|---|---|
+| `string` | `String` | |
+| `string` + `format: "date-time"` | `String` (phase 1) | `kotlinx.datetime.Instant` reserved as opt-in. Default `String` to avoid forcing the `kotlinx-datetime` dependency on consumers. |
+| `string` + `format: "uuid"` | `String` | No widely-adopted UUID type in kotlinx. |
+| `integer` | `Long` | Safer default for backend IDs. `Int` not chosen because JSON Schema `integer` carries no size info. |
+| `number` | `Double` | |
+| `boolean` | `Boolean` | |
+| `array` | `List<T>` | |
+| `object` | `@Serializable data class` | |
+| `enum` (string) | `enum class` with `@SerialName(...)` per variant | |
+| `oneOf` with discriminator | `@Serializable sealed class` with `@JsonClassDiscriminator(...)` | |
+| `oneOf` without discriminator | Phase 1: emit warning + `@Polymorphic Any`. Reconsider in phase 2. | |
+| `type: ["X", "null"]` / `nullable: true` | `T?` | |
+| Required vs optional property | Required → non-null; optional → nullable with `= null` default | |
+
+### Type-mapping specification (Swift)
+
+| JSON Schema | Swift | Notes |
+|---|---|---|
+| `string` | `String` | |
+| `string` + `format: "date-time"` | `String` (phase 1) | `Date` opt-in via flag once `Codable` strategies are settled. |
+| `string` + `format: "uuid"` | `String` | `UUID` opt-in. |
+| `integer` | `Int64` | Mirrors Kotlin `Long` choice. |
+| `number` | `Double` | |
+| `boolean` | `Bool` | |
+| `array` | `[T]` | |
+| `object` | `struct ... : Codable` | |
+| `enum` (string) | `enum: String, Codable` | |
+| `oneOf` with discriminator | `enum` with associated values + custom `Codable` impl | |
+| `oneOf` without discriminator | Phase 1: warning + emit unsupported marker. | |
+| `type: ["X", "null"]` / `nullable: true` | `T?` | |
+| Required vs optional property | Required → non-optional; optional → `T?` | |
+
+### Naming rules
+
+- Root type: caller passes via `opts.rootTypeName`. ajsc never infers from `schema.title`.
+- Sub-types: derived from the parent property name via existing `depluralize`/`arrayItemNaming` logic. Collision suffixes appended deterministically.
+- Output must be deterministic across runs so the source-hash staleness check continues to work.
+
+## ts-procedures-side scope
+
+### Pipeline extension
+
+Extend `src/codegen/pipeline.ts` to dispatch on a target argument:
+
+```
+DocEnvelope
+  → resolveEnvelope (shared)
+  → groupRoutesByScope (shared)
+  → for each target in {ts, kotlin, swift}:
+       → emitScopeFile<target> per scope
+       → emitErrorsFile (TS only — Kotlin/Swift errors live inline per-route, no registry)
+       → emitIndexFile (TS only — Kotlin/Swift have no factory)
+       → write
+```
+
+### Directory layout
+
+```
+src/codegen/
+  emit-types.ts              # existing TS emitter (keep)
+  emit-scope.ts              # existing TS scope emitter (keep)
+  ...
+  targets/
+    kotlin/
+      emit-scope-kotlin.ts   # wraps ajsc.emitKotlin into `object Scope { object Route { ... } }`
+      emit-scope-kotlin.test.ts
+    swift/
+      emit-scope-swift.ts
+      emit-scope-swift.test.ts
+  pipeline.ts                # target-aware dispatcher
+  bin/cli.ts                 # adds --target flag
+```
+
+The `targets/` directory is structured so a future split into sibling packages (`@ts-procedures/codegen-kotlin`, `@ts-procedures/codegen-swift`) is mechanical: each subdirectory is internally self-contained and depends only on shared core utilities.
+
+### CLI
+
+Single binary, multi-target via `--target`:
+
+```bash
+npx ts-procedures-codegen --target kotlin --url https://api.example.com/_ts-procedures.json --out ./generated-kotlin
+npx ts-procedures-codegen --target swift  --file ./envelope.json                          --out ./generated-swift
+```
+
+Default `--target ts` preserves backward compatibility — every existing invocation continues to work unchanged.
+
+Target-specific flags:
+
+- Kotlin: `--kotlin-package <com.example.api>` — sets the `package` declaration on every emitted file. Required, **unless supplied via the config file's `kotlin.package`**. CLI flag and config value are interchangeable; CLI overrides config when both are present. The codegen rejects invocations where neither path provides a package.
+- Swift: `--swift-module-name <name>` — currently informational (Swift does not have file-level module declarations); may drive output directory naming.
+
+Flags inherited from existing CLI: `--watch`, `--dry-run`, `--clean-out-dir`, `--config`, `--enum-style`, `--depluralize`, `--array-item-naming`, `--uncountable-words`.
+
+`--service-name` (existing TS flag) is **not applicable** to Kotlin/Swift targets — those targets emit no service-level namespace, factory, or aggregate index. The flag is silently ignored when `--target` is `kotlin` or `swift`. (The Kotlin scope namespace is named after the route's scope, not the service.)
+
+Flags **not applicable** to Kotlin/Swift targets (silently ignored or rejected): `--self-contained`, `--namespace-types` (always on for Kotlin/Swift; flat mode unsupported), `--client-import-path`, `--jsdoc`, `--service-name`.
+
+Config file: existing `ts-procedures-codegen.config.json` extended with optional `kotlin` and `swift` sub-objects:
+
+```json
+{
+  "target": "kotlin",
+  "url": "https://api.example.com/_ts-procedures.json",
+  "out": "./generated",
+  "kotlin": { "package": "com.example.api" }
+}
+```
+
+### Source-hash staleness
+
+The existing source-hash-as-comment mechanism extends naturally — Kotlin and Swift both support line comments (`// ...`). ts-procedures injects `// source-hash: <hash>` at the top of each generated file; rerunning with an unchanged envelope produces a no-op diff.
+
+## Testing strategy
+
+### ajsc side
+
+- Acceptance corpus: representative JSON Schemas + golden Kotlin and Swift outputs (`fixtures/<name>.kotlin.txt`, `fixtures/<name>.swift.txt`). Tests assert byte-identical output.
+- Corpus seeded from ts-procedures' existing codegen test envelopes plus pathological cases: deeply nested objects, discriminated unions, self-referencing `$ref`, large enums, every nullable combination, arrays of arrays.
+
+### ts-procedures side
+
+- Unit tests for `emit-scope-kotlin.ts` and `emit-scope-swift.ts`: given a fake `groupedRoutes` + a stubbed ajsc, assert the wrapping output (object/enum nesting, method constants, path templates, path-builder shapes).
+- Integration test: feed a known DocEnvelope through the full pipeline with a real ajsc dependency; assert generated file contents against golden files.
+- E2E test (Kotlin): generate output, place in a small Gradle project, compile with `kotlinc`. Asserts output is syntactically valid and imports resolve.
+- E2E test (Swift): generate output, place in a small SwiftPM package, compile with `swift build`. Same syntactic-validity guarantee.
+
+The compile-check E2E tests are essential because Kotlin/Swift are statically typed and the only way to catch "ajsc emitted a name that ts-procedures referenced incorrectly" is to compile.
+
+**Toolchain availability.** `kotlinc` and `swift build` are not currently part of this repo's CI environment. Plan options: (a) provision both toolchains in CI (Kotlin via the `kotlin/` GitHub Action, Swift via macOS runners or `swift-actions/setup-swift`); (b) gate the compile-check E2E tests behind an opt-in flag and run them locally / in a separate scheduled CI job. Decision deferred to the implementation plan; either path is acceptable, but at minimum a manual local run must be performed before each Kotlin/Swift release.
+
+## Sequencing
+
+| Phase | Owner | Deliverable |
+|---|---|---|
+| **A** | ajsc | `emitKotlin` exposed, type-mapping spec implemented, fixture corpus with golden outputs, semver minor bump. |
+| **B** | ts-procedures | `--target kotlin` end-to-end: scope wrapper, path builders, method constants, CLI flag, config-file integration, kotlinc E2E test. |
+| **C** | ajsc | `emitSwift` exposed, Swift fixture corpus. |
+| **D** | ts-procedures | `--target swift` end-to-end: scope wrapper, swift build E2E test. |
+
+Phases A→B and C→D are sequential within each target. Kotlin (A+B) ships fully before Swift work begins to avoid co-designing two emitters before either has shipped to a real consumer.
+
+### Coordination
+
+- ajsc ships a `0.x` minor with each emitter; ts-procedures pins the minor range.
+- Sample fixtures live in ajsc; ts-procedures duplicates a small subset for its own integration tests so the two repos cannot drift silently.
+
+## Open questions / explicit deferrals
+
+1. **Cross-route shared types** (e.g., a `User` type referenced by multiple routes via `$ref`). Phase 1 emits per-route copies, matching current TS behavior. Cross-route dedup (`Users.Shared.User` or top-level `Shared.User`) is a candidate refinement once consumer pain is known.
+2. **`format: "date-time"` → `Instant` / `Date` upgrade.** Default to `String` in phase 1 to avoid forcing kotlinx-datetime / Date-strategy decisions on consumers; promote to typed when consumer demand is concrete.
+3. **`oneOf` without discriminator.** Phase 1 emits a warning and a fallback; not all backends produce well-discriminated unions.
+4. **Per-call options.** Deferred entirely — no `signal`, `headers`, `timeout`, `meta`. If consumers ask, the additive surface (an optional second parameter to the path builder, or an opaque `RequestOptions` struct) is small enough to add later without breaking existing output.
+5. **Sub-type extraction depth.** `inlineTypes: false` is the default; whether to expose a CLI flag to override is deferred until someone asks.
+
+## Risk assessment
+
+- **Risk: ajsc emitter output and ts-procedures wrapping drift.** Mitigated by the explicit `EmitResult.rootTypeName` + `extractedTypeNames` contract — no string-parsing of ajsc output — and by the kotlinc/swift-build E2E compile checks.
+- **Risk: scope creep into a full mobile client (adapter, errors registry, hooks).** Mitigated by the explicit non-goals list above. Future work goes through a new spec, not a quiet expansion of this one.
+- **Risk: kotlinx.serialization adoption resistance.** A `serializer: 'none'` mode is **reserved for a future phase** (not part of phase 1) — punting type annotations entirely is a one-flag escape if a consumer team's ecosystem cannot accept the kotlinx Gradle plugin. Phase 1 ships kotlinx-only; broadening is additive.
+
+## Summary
+
+Add two new emitters to `ajsc` (Kotlin then Swift) and one new `--target` mode to ts-procedures codegen. Generated output is **types + URL/method primitives only** — no runtime, no adapter, no registry. Mobile consumers receive a typed, structured catalog of the server's contract and integrate it into whatever HTTP stack they already use. The non-invasive surface keeps maintenance burden low and lets Android/iOS teams keep their existing networking architecture intact.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-procedures",
-  "version": "6.0.0",
+  "version": "6.0.2",
   "description": "A TypeScript RPC framework that creates type-safe, schema-validated procedure calls with a single function definition. Define your procedures once and get full type inference, runtime validation, and framework integration hooks.",
   "main": "build/exports.js",
   "types": "build/exports.d.ts",

package/src/implementations/http/README.md

@@ -234,6 +234,8 @@ const docs = builder.docs
 
 All four builders' `build()` methods are synchronous — they return the framework app instance directly. Don't `await` the call.
 
+**Single Hono server across builders:** all three Hono builders (`HonoRPCAppBuilder`, `HonoAPIAppBuilder`, `HonoStreamAppBuilder`) accept an optional `app?: Hono` in their config. Pass the same `new Hono()` instance to mount RPC, API, and Stream routes onto one server — the builders are registration scopes, not separate servers. See **[docs/http-integrations.md § One Hono Server, Multiple Builders](../../../docs/http-integrations.md#one-hono-server-multiple-builders)**.
+
 **Key methods:**
 
 | Method | Returns | Description |
@@ -257,8 +259,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)
@@ -269,7 +270,7 @@ app.get('/docs', (c) => c.json(docs.toJSON()))
 
 - `from()` stores a reference — routes are read lazily at `toJSON()` time
 - `toJSON()` supports optional `filter` and `transform` options
-- `defaultErrors()` returns error schemas for all 4 procedure error types
+- `errors` accepts an `ErrorTaxonomy` or raw `ErrorDoc[]`; framework defaults are auto-merged (opt out via `includeDefaults: false`)
 - All builders satisfy the `DocSource` interface (`{ readonly docs: AnyHttpRouteDoc[] }`)
 
 ### Client Code Generation

package/src/implementations/http/doc-registry.test.ts

@@ -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'
 import type {
   AnyHttpRouteDoc,
   RPCHttpRouteDoc,
@@ -11,6 +12,7 @@ import type {
   StreamHttpRouteDoc,
   DocSource,
   DocEnvelope,
+  ErrorDoc,
 } from '../types.js'
 
 // ---------------------------------------------------------------------------
@@ -61,7 +63,7 @@ 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([])
@@ -69,7 +71,7 @@ describe('DocRegistry', () => {
     })
 
     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([])
@@ -79,7 +81,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)
@@ -175,7 +177,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)
@@ -298,6 +300,153 @@ 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: ErrorDoc = { 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: ErrorDoc = {
+        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
   // --------------------------------------------------------------------------
@@ -333,7 +482,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]))
@@ -347,10 +495,7 @@ describe('DocRegistry', () => {
     })
 
     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]))
@@ -372,7 +517,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]))