ts-procedures 7.3.0 → 8.0.0

package/docs/superpowers/specs/2026-05-08-hono-app-builder-convergence-design.md

@@ -0,0 +1,411 @@
+# HonoAppBuilder Convergence — Design
+
+**Date:** 2026-05-08
+**Status:** Draft for review
+**Scope:** Hono only
+
+## Problem
+
+`ts-procedures` currently exposes three Hono builders — `HonoRPCAppBuilder`, `HonoAPIAppBuilder`, `HonoStreamAppBuilder` — totaling ~1,580 lines of near-parallel code (constructor, `register()`, `build()`, error dispatch, factory iteration, doc emission). Each filters procedures by `kind` and warn-skips mismatches.
+
+Since v8, a single `Procedures<TContext>()` factory produces all four procedure kinds (`rpc`, `rpc-stream`, `http`, `http-stream`) from one call. Splitting registration across three builders is no longer a structural necessity — it's friction. A user wiring a typical app today does:
+
+```ts
+const rpc    = new HonoRPCAppBuilder({ app, errors }).register(F1, ctx1)
+const api    = new HonoAPIAppBuilder({ app, errors }).register(F2, ctx2)
+const stream = new HonoStreamAppBuilder({ app, errors, onMidStreamError }).register(F3, ctx3)
+rpc.build(); api.build(); stream.build()
+new DocRegistry().from(rpc).from(api).from(stream).toJSON()
+```
+
+…three constructors, three `errors` config objects, three `build()` calls, an explicit shared `app`, and a DocRegistry assembly step — to do what is conceptually one thing: "mount these procedures on this Hono server."
+
+## Goal
+
+A single `HonoAppBuilder` that accepts any `Procedures<>()` factory and mounts every procedure kind correctly, with the appropriate documentation surfaced for the codegen pipeline. The current four-builder surface is removed.
+
+## Non-Goals
+
+- **Removing or rewriting `DocRegistry`.** It remains the multi-app aggregation primitive.
+- **Changing per-procedure config.** `RPCConfig`, `APIConfig`, the `CreateHttp`/`CreateStream`/`CreateHttpStream` shapes are unchanged. The convergence is at the *builder* layer, not the procedure-definition layer.
+- **Path generation rule changes.** RPC/rpc-stream still use `pathPrefix + kebab(scope)/kebab(name)/version`. HTTP/http-stream still use `pathPrefix + config.path`.
+- **Error taxonomy semantics.** `defineErrorTaxonomy`, `resolveErrorResponse`, mid-stream error wire shape, and the `onRequestError` observer all keep their current behavior.
+
+## Decisions
+
+| Decision | Choice | Rationale |
+|---|---|---|
+| Convergence scope | Full collapse, remove old builders, no deprecation period | v8 has not been published; v8 is already a breaking release from v7. Bundling this convergence with the v8 break avoids a second migration. |
+| Config shape for kind-specific knobs | Stratified — top-level cross-cutting + nested `rpc`/`api`/`stream` blocks | Type-safe, discoverable; users who only register one kind don't see clutter from other kinds. |
+| Documentation | Builder gains `toDocEnvelope()` for single-app; `DocRegistry` stays for multi-app aggregation | Common case is one builder per app — `toDocEnvelope()` removes the registry boilerplate. Multi-app users keep the existing primitive. |
+| Builder name | `HonoAppBuilder` | Drops the kind suffix (RPC/API/Stream) since it now serves all kinds. |
+| Non-streaming hooks (`onSuccess`) placement | Inside stratified blocks (`rpc.onSuccess`, `api.onSuccess`) | Strict typing per kind; users wiring a unified metrics callback assign the same function to both blocks. Non-breaking to add a top-level `onSuccess` later if duplication is a real pain point. |
+| Shared error-dispatch module location | `src/implementations/http/error-dispatch.ts` (one level up from `hono/`) | Lives outside the framework-specific subdir so it can be reused by future framework adapters. |
+| Path-builder static method | `HonoAppBuilder.makeRoutePath({ procedure, prefix })` — handles all four kinds | Tooling consumers get one entry point regardless of kind. |
+
+## Public API
+
+```ts
+import { HonoAppBuilder } from 'ts-procedures/hono'
+
+const { Create, CreateStream, CreateHttp, CreateHttpStream } =
+  Procedures<AppCtx>()
+
+// ... define procedures with any combination of the four creators ...
+
+const builder = new HonoAppBuilder({
+  app,                             // optional pre-existing Hono
+  pathPrefix: '/api/v1',
+  errors: appErrors,               // ErrorTaxonomy, cross-cutting
+  unknownError,
+  onError,                         // imperative peer of `errors`
+  onRequestError,                  // observer
+  onRequestStart,
+  onRequestEnd,
+  rpc: {
+    onSuccess: (proc, c) => {},
+  },
+  api: {
+    queryParser: qs.parse,
+    onSuccess: (proc, c) => {},
+  },
+  stream: {
+    defaultStreamMode: 'sse',      // applies to rpc-stream + http-stream
+    onStreamStart, onStreamEnd,
+    onMidStreamError,
+  },
+})
+
+builder
+  .register(AppFactory, ctxResolver)
+  .register(InternalFactory, internalCtxResolver, {
+    streamMode: 'text',                  // optional per-factory override
+    extendProcedureDoc: ({ base }) => {
+      switch (base.kind) {
+        case 'rpc':         return { internal: true }
+        case 'api':         return { internal: true, group: 'admin' }
+        case 'stream':      return { internal: true }
+        case 'http-stream': return { internal: true }
+      }
+    },
+  })
+
+const honoApp = builder.build()             // returns Hono
+const docs = builder.docs                   // AnyHttpRouteDoc[] (lazy-cached)
+const envelope = builder.toDocEnvelope()    // DocEnvelope (single-app)
+```
+
+### Config Type
+
+```ts
+export type HonoAppBuilderConfig<TStreamErrorData = unknown> = {
+  // Cross-cutting
+  app?: Hono
+  pathPrefix?: string
+
+  errors?: ErrorTaxonomy
+  unknownError?: UnknownErrorConfig
+  onError?: (
+    procedure: AnyProcedureRegistration,
+    c: Context,
+    error: Error,
+  ) => Response | Promise<Response>
+  onRequestError?: (ctx: OnRequestErrorContext) => void | Promise<void>
+
+  onRequestStart?: (c: Context) => void
+  onRequestEnd?: (c: Context) => void
+
+  // Kind-specific
+  rpc?: {
+    onSuccess?: (procedure: TProcedureRegistration, c: Context) => void
+  }
+  api?: {
+    queryParser?: QueryParser
+    onSuccess?: (
+      procedure: THttpProcedureRegistration<any>,
+      c: Context,
+    ) => void
+  }
+  stream?: {
+    defaultStreamMode?: StreamMode
+    onStreamStart?: (
+      procedure: TStreamProcedureRegistration | THttpStreamProcedureRegistration<any>,
+      c: Context,
+      streamMode: StreamMode,
+    ) => void
+    onStreamEnd?: (
+      procedure: TStreamProcedureRegistration | THttpStreamProcedureRegistration<any>,
+      c: Context,
+      streamMode: StreamMode,
+    ) => void
+    onMidStreamError?: (
+      procedure: TStreamProcedureRegistration | THttpStreamProcedureRegistration<any>,
+      c: Context,
+      error: Error,
+    ) => MidStreamErrorResult<TStreamErrorData> | undefined
+  }
+}
+
+export type AnyProcedureRegistration =
+  | TProcedureRegistration
+  | TStreamProcedureRegistration
+  | THttpProcedureRegistration<any>
+  | THttpStreamProcedureRegistration<any>
+
+export type OnRequestErrorContext = {
+  err: unknown
+  procedure: AnyProcedureRegistration
+  raw: Context
+}
+```
+
+### `register()`
+
+```ts
+register<TFactory extends ProceduresFactory>(
+  factory: TFactory,
+  factoryContext:
+    | ExtractContext<TFactory>
+    | ((c: Context) => ExtractContext<TFactory> | Promise<ExtractContext<TFactory>>),
+  options?: {
+    /** Per-factory override for stream.defaultStreamMode. */
+    streamMode?: StreamMode
+    /** Extend route docs. base is a kind-discriminated union. */
+    extendProcedureDoc?: (params: {
+      base: RPCHttpRouteDoc | APIHttpRouteDoc | StreamHttpRouteDoc | HttpStreamRouteDoc
+      procedure: AnyProcedureRegistration
+    }) => Record<string, unknown>
+  },
+): this
+```
+
+### `toDocEnvelope()`
+
+Mirrors `DocRegistry.toJSON()`'s option surface so the produced envelope is identical and the codegen pipeline reads either interchangeably:
+
+```ts
+toDocEnvelope(options?: {
+  basePath?: string
+  errors?: ErrorTaxonomy | ErrorDoc[]
+  includeDefaults?: boolean
+  filter?: (route: AnyHttpRouteDoc) => boolean
+  transform?: (route: AnyHttpRouteDoc) => AnyHttpRouteDoc
+}): DocEnvelope
+```
+
+`builder.docs` exposes the underlying array (lazy-computed on first read or on `build()`, whichever happens first; cached thereafter).
+
+### Static Path Builder
+
+```ts
+HonoAppBuilder.makeRoutePath({
+  procedure: AnyProcedureRegistration,
+  prefix?: string,
+}): string
+```
+
+- For `rpc` / `rpc-stream`: `{prefix}/{kebab(scope)}/{kebab(name)}/{version}`
+- For `http` / `http-stream`: `{prefix}{config.path}` (prefix normalized to leading `/`)
+
+## Internal Architecture
+
+```
+src/implementations/http/
+├── error-dispatch.ts                   # SHARED — pre-stream + mid-stream dispatchers
+├── error-taxonomy.ts                   # unchanged
+├── doc-registry.ts                     # unchanged
+├── hono/
+│   ├── index.ts                        # HonoAppBuilder (~200 lines)
+│   ├── path.ts                         # makeRoutePath, resolveFullPath
+│   ├── types.ts                        # HonoAppBuilderConfig, factory item
+│   ├── handlers/
+│   │   ├── rpc.ts                      # installRpcRoute(...)
+│   │   ├── http.ts                     # installHttpRoute(...)
+│   │   ├── stream.ts                   # installRpcStreamRoute(...)
+│   │   └── http-stream.ts              # installHttpStreamRoute(...)
+│   └── docs/
+│       ├── rpc-doc.ts                  # buildRpcRouteDoc
+│       ├── http-doc.ts                 # buildHttpRouteDoc
+│       ├── stream-doc.ts               # buildStreamRouteDoc
+│       └── http-stream-doc.ts          # buildHttpStreamRouteDoc
+```
+
+### `build()` Dispatch Loop
+
+```ts
+build(): Hono {
+  for (const item of this._factories) {
+    for (const procedure of item.factory.getProcedures().values()) {
+      switch (procedure.kind) {
+        case 'rpc':
+          installRpcRoute(this._app, procedure, item, this.config, this._docs)
+          break
+        case 'rpc-stream':
+          installRpcStreamRoute(this._app, procedure, item, this.config, this._docs)
+          break
+        case 'http':
+          installHttpRoute(this._app, procedure, item, this.config, this._docs)
+          break
+        case 'http-stream':
+          installHttpStreamRoute(this._app, procedure, item, this.config, this._docs)
+          break
+        default: {
+          const reason = `Unknown procedure kind "${(procedure as any).kind}"`
+          this._skipped.push({ name: procedure.name, reason })
+          console.warn(`[ts-procedures hono] ${reason}`)
+        }
+      }
+    }
+  }
+  return this._app
+}
+```
+
+### Shared Error Dispatch
+
+`src/implementations/http/error-dispatch.ts` exports two functions that consolidate the three current near-identical implementations:
+
+```ts
+// Used by rpc, http, and the pre-stream guards in stream / http-stream.
+// Returns a Response.
+export async function dispatchPreStreamError(args: {
+  err: unknown
+  procedure: AnyProcedureRegistration
+  raw: Context
+  cfg: {
+    errors?: ErrorTaxonomy
+    unknownError?: UnknownErrorConfig
+    onError?: HonoAppBuilderConfig['onError']
+    onRequestError?: HonoAppBuilderConfig['onRequestError']
+  }
+}): Promise<Response>
+
+// Used inside stream generator catch blocks. Returns the data to write
+// (plus optional SSE metadata + onCatch hook), not a full Response — the
+// HTTP status is already committed once streaming starts.
+export async function dispatchMidStreamError<TData = unknown>(args: {
+  err: unknown
+  procedure: TStreamProcedureRegistration | THttpStreamProcedureRegistration<any>
+  raw: Context
+  cfg: {
+    errors?: ErrorTaxonomy
+    unknownError?: UnknownErrorConfig
+    onMidStreamError?: HonoAppBuilderConfig<TData>['stream']['onMidStreamError']
+    onRequestError?: HonoAppBuilderConfig['onRequestError']
+  }
+}): Promise<{
+  data: unknown
+  sseEvent?: string
+  sseId?: string
+  sseRetry?: number
+  runOnCatch?: () => Promise<void>
+}>
+```
+
+Both call the `onRequestError` observer first (swallowing observer throws) and then dispatch through taxonomy → onError/onMidStreamError → hard default — same order as today.
+
+### Per-Kind Handler Modules
+
+Each handler module is a small file (~80–180 lines) exporting one `install*Route` function. Their job:
+
+1. Build the route doc (`docs/<kind>-doc.ts`) and push to `_docs`.
+2. Resolve the route path (`path.ts`).
+3. Register the Hono handler that:
+   - Resolves the factory context (sync object | sync fn | async fn).
+   - Extracts and assembles params from the request (per kind: body for rpc; structured req for http/http-stream; query-or-body for rpc-stream).
+   - Invokes `procedure.handler({ ...ctx, signal: c.req.raw.signal }, params)`.
+   - For streams: forwards `isPrevalidated: true` after the pre-stream validation so core doesn't re-validate.
+   - Catches and routes through `dispatchPreStreamError`.
+   - For streams: forwards mid-stream throws through `dispatchMidStreamError` and writes the result via `streamSSE`/`streamText`.
+   - Calls the right kind-specific lifecycle hook (`rpc.onSuccess`, `api.onSuccess`, `stream.onStreamStart`/`onStreamEnd`).
+
+Module-level coupling: each handler imports only the slice of config it needs (e.g., `handlers/stream.ts` imports `stream.*` and the cross-cutting error config). The full `HonoAppBuilderConfig` type lives in `hono/types.ts`.
+
+### Lazy Doc Computation
+
+Today `_docs` is populated during `build()` — calling `builder.docs` before `build()` returns an empty array. New behavior: `docs` is a getter that runs the per-kind doc-builders (`docs/<kind>-doc.ts`) without touching route registration; the result is cached. `build()` reuses the cached array. This makes `toDocEnvelope()` usable in tests without spinning up handlers.
+
+## Migration Impact
+
+Since v8 is unpublished, there's no in-the-wild deprecation cycle — we update docs, templates, and tests and ship.
+
+### Deletions
+
+- `src/implementations/http/hono-rpc/` (entire directory)
+- `src/implementations/http/hono-api/` (entire directory)
+- `src/implementations/http/hono-stream/` (entire directory)
+- The corresponding `package.json#exports` entries: `./hono-rpc`, `./hono-api`, `./hono-stream`
+
+### Additions
+
+- `src/implementations/http/hono/` (per the layout above)
+- `package.json#exports` entry: `./hono`
+- `src/implementations/http/error-dispatch.ts` — shared dispatchers (replacing inline copies in three builders)
+
+### Re-exports From `ts-procedures/hono`
+
+`HonoAppBuilder`, `HonoAppBuilderConfig`, `OnRequestErrorContext`, `AnyProcedureRegistration`, `RPCConfig`, `RPCHttpRouteDoc`, `APIConfig`, `APIHttpRouteDoc`, `APIInput`, `StreamHttpRouteDoc`, `HttpStreamRouteDoc`, `StreamMode`, `HttpMethod`, `QueryParser`, `MidStreamErrorResult`, `sse`, `defineErrorTaxonomy`, `ErrorTaxonomy`, `ErrorTaxonomyEntry`, `UnknownErrorConfig`.
+
+`./http-errors` and `./http-docs` (DocRegistry) keep their current subpaths.
+
+### User-Facing Migration Table
+
+| Before (in-flight v8) | After |
+|---|---|
+| `import { HonoRPCAppBuilder } from 'ts-procedures/hono-rpc'` | `import { HonoAppBuilder } from 'ts-procedures/hono'` |
+| `import { HonoAPIAppBuilder } from 'ts-procedures/hono-api'` | same |
+| `import { HonoStreamAppBuilder } from 'ts-procedures/hono-stream'` | same |
+| `new HonoRPCAppBuilder({ errors, onSuccess })` | `new HonoAppBuilder({ errors, rpc: { onSuccess } })` |
+| `new HonoAPIAppBuilder({ errors, queryParser })` | `new HonoAppBuilder({ errors, api: { queryParser } })` |
+| `new HonoStreamAppBuilder({ errors, onMidStreamError, defaultStreamMode })` | `new HonoAppBuilder({ errors, stream: { onMidStreamError, defaultStreamMode } })` |
+| Three builders sharing `app: Hono` | One builder, no shared-`app` plumbing |
+| `new DocRegistry().from(rpc).from(api).from(stream).toJSON()` | `builder.toDocEnvelope()` for single-app; DocRegistry only for multi-app aggregation |
+
+### Edge Cases & Behavior Preservation
+
+1. **Mixed-kind factories work natively.** A single `Procedures<>()` factory with `Create`/`CreateStream`/`CreateHttp`/`CreateHttpStream` calls dispatches correctly under one builder.
+2. **`pathPrefix` is global to the builder.** Users who genuinely need different prefixes per kind (rare) instantiate two `HonoAppBuilder`s sharing the same `app`.
+3. **`extendProcedureDoc`** receives a discriminated union — switch on `base.kind`.
+4. **Per-factory `streamMode` override** stays via `register(factory, ctx, { streamMode })`. Applies to both rpc-stream and http-stream procedures within that factory.
+5. **`AbortSignal` injection, SSE `event: 'return'`, `isPrevalidated`, `noRuntimeValidation`** — all preserved.
+6. **`skippedProcedures`** stays on the public surface but is expected to always be empty post-convergence (defensive logging for future kinds).
+7. **`HonoAppBuilder` satisfies `DocSource`** — multi-app users continue to assemble via `DocRegistry`.
+
+### Tests
+
+Consolidated under `src/implementations/http/hono/`:
+
+- `index.test.ts` — public surface (constructor, register, build, docs, toDocEnvelope, makeRoutePath)
+- `handlers/rpc.test.ts`, `handlers/http.test.ts`, `handlers/stream.test.ts`, `handlers/http-stream.test.ts` — per-kind handler behavior, taking the place of the three separate `index.test.ts` files
+- `../error-dispatch.test.ts` — shared error dispatch (folds in `error-taxonomy.test.ts` content from each old builder)
+
+Top-level shared tests at `src/implementations/http/` stay: `error-taxonomy.test.ts`, `doc-registry.test.ts`, `on-request-error.test.ts`, `route-errors.test.ts`.
+
+Codegen e2e fixtures consume `DocEnvelope` JSON — unaffected.
+
+### Templates & Docs
+
+- `agent_config/claude-code/skills/ts-procedures-scaffold/templates/` — delete `hono-rpc.ts`, `hono-stream.ts`; rewrite `hono-api.ts` (or rename to `hono.ts`) demonstrating one builder serving all kinds.
+- `agent_config/claude-code/skills/ts-procedures/{SKILL.md, patterns.md, anti-patterns.md}` — replace per-builder examples with single-builder examples.
+- `agent_config/copilot/copilot-instructions.md` and `agent_config/cursor/cursorrules` — same updates (these mirror the Claude skill content).
+- `src/implementations/http/README.md` — rewrite around `HonoAppBuilder`. Drop the "RPC vs Streaming vs API builder" sectioning. Replace with one section + a "Which procedure kind to use" table.
+- `docs/http-integrations.md` — rewrite around the unified builder. Delete the "One Hono Server, Multiple Builders" section (no longer relevant).
+- README v8 changelog — update the convergence entry.
+
+## Test Plan
+
+1. **Public-surface contract** — constructor stores config; `register()` is chainable; `build()` returns `Hono`; `docs` is lazy and stable across multiple reads; `toDocEnvelope()` produces a DocEnvelope identical to a `DocRegistry({ basePath, errors }).from(builder).toJSON()` output for the same builder.
+2. **Per-kind dispatch** — register a single factory containing one procedure of each of the four kinds; verify each is mounted at the correct path with the correct method(s) and produces the correct doc shape.
+3. **Mixed factories** — register two factories with different `factoryContext` resolvers; verify each procedure receives the correct context and that the resolver runs once per request.
+4. **Stratified config** — `rpc.onSuccess` fires only for rpc; `api.onSuccess` fires only for http; `stream.onStreamStart`/`onStreamEnd`/`onMidStreamError` fire only for streaming kinds. Cross-cutting hooks (`onRequestStart`/`onRequestEnd`/`onRequestError`) fire for every kind.
+5. **Error dispatch parity** — port the existing taxonomy tests from each old builder. Pre-stream errors flow through `dispatchPreStreamError`; mid-stream errors flow through `dispatchMidStreamError` with status already committed. `onRequestError` observer fires before dispatch in both paths and its throws are swallowed.
+6. **Path generation** — `makeRoutePath` returns the expected URL for each kind; with and without `prefix`; with array vs. string `scope`.
+7. **Per-factory `streamMode` override** — registering with `{ streamMode: 'text' }` overrides `stream.defaultStreamMode` for that factory's stream procedures only.
+8. **`extendProcedureDoc`** — receives a kind-discriminated `base`; returned fields are merged onto the route doc; `kind` cannot be overwritten.
+9. **DocSource compatibility** — `new DocRegistry().from(builder).toJSON()` produces a valid envelope matching `builder.toDocEnvelope()` (modulo `basePath` if not specified).
+10. **Codegen end-to-end** — feed `builder.toDocEnvelope()` into `generateClient()` for the TS / Kotlin / Swift targets and verify the generated output compiles. Use the existing fixture envelope structure.
+
+## Out of Scope (Follow-ups)
+
+- **Top-level `onSuccess` shortcut** — if the duplicated `rpc.onSuccess` + `api.onSuccess` pattern shows up in real apps, add a top-level `onSuccess` that fans out to both. Non-breaking when added.
+- **Different `pathPrefix` per kind** — if users actually need this, add `rpc.pathPrefix` / `api.pathPrefix` / `stream.pathPrefix` overrides. Today the workaround (two builders sharing one `app`) is acceptable.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-procedures",
-  "version": "7.3.0",
+  "version": "8.0.0",
   "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",
@@ -30,21 +30,9 @@
     "./http": {
       "types": "./build/implementations/types.d.ts"
     },
-    "./express-rpc": {
-      "types": "./build/implementations/http/express-rpc/index.d.ts",
-      "import": "./build/implementations/http/express-rpc/index.js"
-    },
-    "./hono-rpc": {
-      "types": "./build/implementations/http/hono-rpc/index.d.ts",
-      "import": "./build/implementations/http/hono-rpc/index.js"
-    },
-    "./hono-stream": {
-      "types": "./build/implementations/http/hono-stream/index.d.ts",
-      "import": "./build/implementations/http/hono-stream/index.js"
-    },
-    "./hono-api": {
-      "types": "./build/implementations/http/hono-api/index.d.ts",
-      "import": "./build/implementations/http/hono-api/index.js"
+    "./hono": {
+      "types": "./build/implementations/http/hono/index.d.ts",
+      "import": "./build/implementations/http/hono/index.js"
     },
     "./http-docs": {
       "types": "./build/implementations/http/doc-registry.d.ts",
@@ -81,7 +69,6 @@
     "api",
     "framework",
     "hono",
-    "express",
     "http",
     "rest",
     "schema",
@@ -102,7 +89,6 @@
   "optionalDependencies": {
     "ajsc": "^7.2.0",
     "astro": "6.x.x || 7.x.x",
-    "express": "^5.2.1",
     "hono": "^4.7.4"
   },
   "dependencies": {
@@ -114,14 +100,10 @@
   },
   "devDependencies": {
     "@eslint/js": "^9.17.0",
-    "@types/express": "^5.0.6",
-    "@types/supertest": "^7.2.0",
     "astro": "^6.3.1",
     "eslint": "^9.17.0",
-    "express": "^5.2.1",
     "hono": "^4.7.4",
     "prettier": "^3.8.1",
-    "supertest": "^7.2.2",
     "suretype": "^3.3.1",
     "typebox": "^1.0.77",
     "typescript-eslint": "^8.53.0",

package/src/client/call.test.ts

@@ -338,6 +338,32 @@ describe('executeCall', () => {
     })
     expect(observedMeta).toEqual({ traceId: 'override', attempt: 1 })
   })
+
+  // ── responseHeadersDeclared ──
+
+  it('returns bare body when responseHeadersDeclared is not set', async () => {
+    const adapter = makeAdapter({ body: { id: 'abc' } })
+    const result = await run<{ id: string }>({ adapter, descriptor: makeDescriptor() })
+    expect(result).toEqual({ id: 'abc' })
+  })
+
+  it('returns { body, headers } when responseHeadersDeclared is true', async () => {
+    const adapter: ClientAdapter = {
+      request: vi.fn(async (): Promise<AdapterResponse> => ({
+        status: 200,
+        headers: { 'x-rate-limit': '99' },
+        body: { id: 'abc' },
+      })),
+      stream: vi.fn(async () => { throw new Error('not expected') }),
+    }
+    const descriptor = makeDescriptor({ responseHeadersDeclared: true })
+    const result = await run<{ body: { id: string }; headers: Record<string, string> }>({
+      adapter,
+      descriptor,
+    })
+    expect(result).toEqual({ body: { id: 'abc' }, headers: { 'x-rate-limit': '99' } })
+    expect(result.headers['x-rate-limit']).toBe('99')
+  })
 })
 
 describe('executeCall classifier integration', () => {

package/src/client/call.ts

@@ -132,7 +132,10 @@ export async function executeCall<TResponse>(config: ExecuteCallConfig): Promise
     })
   }
 
-  // 8. Return the body
+  // 8. Return the body (or { body, headers } when the route declares res.headers)
+  if (descriptor.responseHeadersDeclared) {
+    return { body: response.body, headers: response.headers } as TResponse
+  }
   return response.body as TResponse
 }
 

package/src/client/fetch-adapter.test.ts

@@ -302,7 +302,20 @@ describe('createFetchAdapter — stream()', () => {
       method: 'GET',
     })
 
-    expect(response.headers['content-type']).toContain('text/event-stream')
+    expect(response.headers.get('content-type')).toContain('text/event-stream')
+  })
+
+  it('propagates response headers to AdapterStreamResponse.headers', async () => {
+    const mockFetch = vi.mocked(globalThis.fetch)
+    mockFetch.mockResolvedValueOnce(
+      new Response('data: x\n\n', {
+        status: 200,
+        headers: { 'x-stream-id': 'abc', 'content-type': 'text/event-stream' },
+      })
+    )
+    const adapter = createFetchAdapter()
+    const result = await adapter.stream({ url: 'https://x', method: 'GET', headers: {} })
+    expect(result.headers.get('x-stream-id')).toBe('abc')
   })
 
   it('passes signal to fetch for streams', async () => {

package/src/client/fetch-adapter.ts

@@ -174,7 +174,9 @@ export function createFetchAdapter(config?: FetchAdapterConfig): ClientAdapter {
         signal: req.signal,
       })
 
-      const headers = extractHeaders(response)
+      // Expose the platform Headers object directly — callers that declared
+      // res.headers receive it on TypedStream.headers without any conversion.
+      const { headers } = response
       const emptyBody: AsyncIterable<unknown> = {
         [Symbol.asyncIterator]: async function* () {},
       }

package/src/client/index.test.ts

@@ -32,7 +32,7 @@ function makeAdapter(
     })),
     stream: vi.fn(async (_req: AdapterRequest): Promise<AdapterStreamResponse> => ({
       status: 200,
-      headers: {},
+      headers: new Headers(),
       body: makeAsyncIterable(streamItems),
     })),
   }
@@ -117,7 +117,7 @@ describe('createClient', () => {
       })),
       stream: vi.fn(async (): Promise<AdapterStreamResponse> => ({
         status: 200,
-        headers: {},
+        headers: new Headers(),
         body: makeAsyncIterable([]),
       })),
     }
@@ -145,7 +145,7 @@ describe('createClient', () => {
       }),
       stream: vi.fn(async (): Promise<AdapterStreamResponse> => ({
         status: 200,
-        headers: {},
+        headers: new Headers(),
         body: makeAsyncIterable([]),
       })),
     }
@@ -254,7 +254,7 @@ describe('createClient', () => {
       request: vi.fn(async (): Promise<never> => { throw new Error('not expected') }),
       stream: vi.fn(async (req: AdapterRequest): Promise<AdapterStreamResponse> => {
         capturedHeaders.push(req.headers ?? {})
-        return { status: 200, headers: {}, body: makeAsyncIterable([]) }
+        return { status: 200, headers: new Headers(), body: makeAsyncIterable([]) }
       }),
     }
 
@@ -299,7 +299,7 @@ describe('createClient', () => {
       }),
       stream: vi.fn(async (): Promise<AdapterStreamResponse> => ({
         status: 200,
-        headers: {},
+        headers: new Headers(),
         body: makeAsyncIterable([]),
       })),
     }
@@ -328,7 +328,7 @@ describe('createClient', () => {
       }),
       stream: vi.fn(async (): Promise<AdapterStreamResponse> => ({
         status: 200,
-        headers: {},
+        headers: new Headers(),
         body: makeAsyncIterable([]),
       })),
     }
@@ -364,7 +364,7 @@ describe('createClient', () => {
         }),
         stream: vi.fn(async (): Promise<AdapterStreamResponse> => ({
           status: 200,
-          headers: {},
+          headers: new Headers(),
           body: makeAsyncIterable([]),
         })),
       }

package/src/client/request-builder.ts

@@ -23,7 +23,7 @@ export function interpolatePath(
  * Builds an `AdapterRequest` from a `CallDescriptor` and a base URL.
  *
  * - `kind === 'rpc'` or `kind === 'stream'`: params are flat — sent as the JSON body.
- * - `kind === 'api'`: params are structured channels — `pathParams`, `query`, `body`, `headers`.
+ * - `kind === 'api'` or `kind === 'http-stream'`: params are structured channels — `pathParams`, `query`, `body`, `headers`.
  */
 export function buildAdapterRequest(descriptor: CallDescriptor, basePath: string): AdapterRequest {
   const { name, path, method, kind, params } = descriptor
@@ -36,7 +36,7 @@ export function buildAdapterRequest(descriptor: CallDescriptor, basePath: string
     }
   }
 
-  // kind === 'api' — params are structured channels
+  // kind === 'api' | 'http-stream' — params are structured channels
   const structured = (params ?? {}) as {
     pathParams?: Record<string, unknown>
     query?: Record<string, unknown>