ts-procedures 7.2.0 → 8.0.0

package/docs/superpowers/plans/2026-05-08-create-http.md

@@ -0,0 +1,3355 @@
+# CreateHttp & CreateHttpStream (v8) — Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Split the core procedure surface into four purpose-shaped creators (`Create` / `CreateStream` / `CreateHttp` / `CreateHttpStream`), eliminating the long-standing `schema.params` vs `schema.input` ambiguity and adding first-class typed response (body + headers) to HTTP routes.
+
+**Architecture:** `Create` and `CreateStream` lose `schema.input` entirely (RPC primitives only). New `CreateHttp` / `CreateHttpStream` carry HTTP fields (`path`/`method`/`successStatus`/`scope`/`errors`) and a structured `req` / `res` schema. A `kind` discriminant on every registration drives builder routing. `HonoAPIAppBuilder` becomes the unified HTTP builder serving both `'http'` and `'http-stream'` registrations. Doc envelope regroups `jsonSchema` under `req`/`res`. Codegen emits `Req.*` / `Response.*` namespaces and conditionally typed return shapes.
+
+**Tech Stack:** TypeScript, Vitest, AJV, TypeBox, Hono. Existing `ts-procedures` codegen pipeline. No new runtime dependencies.
+
+**Spec:** [docs/superpowers/specs/2026-05-08-create-http-design.md](../specs/2026-05-08-create-http-design.md)
+
+**Branch:** Already on `refactor-http-api-v8` (worktree off master). This is a major version (8.0.0) so changes ship as a clean break — no v7 compat shim.
+
+---
+
+## File map
+
+**Create:**
+- `src/types.ts` — shared `TLocalContext`, `TStreamContext`, `TProcedureRegistration`, `TStreamProcedureRegistration`, `ProcedureKind`, `TBuilderConfig`
+- `src/create.ts` — `Create` factory (RPC unary)
+- `src/create-stream.ts` — `CreateStream` factory (RPC streaming)
+- `src/create-http.ts` — `CreateHttp` factory + path-param consistency check (HTTP unary)
+- `src/create-http-stream.ts` — `CreateHttpStream` factory (HTTP streaming)
+- `src/create.test.ts` — extracted from `src/index.test.ts`
+- `src/create-stream.test.ts` — extracted from `src/index.test.ts`
+- `src/create-http.test.ts` — new
+- `src/create-http-stream.test.ts` — new
+- `src/migration.test.ts` — registration errors on v7 shapes (schema.input on Create, etc.)
+
+**Modify:**
+- `src/index.ts` — slimmed to `Procedures` factory glue (~80 lines, was 537)
+- `src/index.test.ts` — keep only Procedures factory tests; per-creator tests moved out
+- `src/schema/compute-schema.ts` — drop `input` shape, add `req`/`res` shape, update mutual-exclusivity guard
+- `src/schema/parser.ts` — wire `req` channels through schemaParser (mirror today's `input` path)
+- `src/implementations/types.ts` — restructure `APIHttpRouteDoc.jsonSchema` to `req`/`res`; add `HttpStreamRouteDoc`; remove `APIInput` / `APIConfig` (or simplify); extend `AnyHttpRouteDoc` union
+- `src/implementations/http/hono-api/index.ts` — read `CreateHttp` registrations directly; add `'http-stream'` branch; apply response headers; drop `APIConfig` extension generic
+- `src/implementations/http/hono-api/types.ts` — simplify `HonoAPIFactoryItem` (no APIConfig generic)
+- `src/implementations/http/hono-api/index.test.ts` — both kinds, response headers
+- `src/implementations/http/hono-rpc/index.ts` — filter by `kind === 'rpc'`
+- `src/implementations/http/hono-stream/index.ts` — filter by `kind === 'rpc-stream'`
+- `src/implementations/http/{hono-rpc,hono-stream}/index.test.ts` — kind-mismatch coverage via `skippedProcedures`
+- `src/implementations/http/astro/*` — kind-aware updates mirroring hono-api
+- `src/implementations/http/doc-registry.ts` — handle new `'http-stream'` kind, regrouped `req`/`res`
+- `src/implementations/http/doc-registry.test.ts` — coverage updates
+- `src/codegen/group-routes.ts` — recognize `'http-stream'` kind
+- `src/codegen/targets/_shared/route-slots.ts` — add response headers slot
+- `src/codegen/targets/ts/run.ts` + supporting `emit-scope.ts` — `Req` / `Response` namespacing, conditional return shape
+- `src/codegen/targets/kotlin/run.ts` — `Response.Headers` data class when declared
+- `src/codegen/targets/swift/run.ts` — `Response.Headers` struct when declared
+- `src/codegen/__fixtures__/users-envelope.json` — regenerate to v8 envelope shape
+- `src/codegen/emit-scope.test.ts` — snapshot updates
+- `src/codegen/targets/{ts,kotlin,swift}/run.test.ts` — snapshot updates
+- `src/client/types.ts` — `AdapterStreamResponse.headers`, `TypedStream.headers` (optional)
+- `src/client/call.ts` — surface response headers when route declares `res.headers`
+- `src/client/stream.ts` — wire initial response headers into `TypedStream`
+- `src/client/fetch-adapter.ts` — populate `AdapterStreamResponse.headers`
+- `src/client/{call,stream,fetch-adapter,index}.test.ts` — coverage updates
+- `package.json` — bump to `8.0.0`
+- `CHANGELOG.md` — major bump entry with migration table
+- `README.md` — update headline examples
+- `CLAUDE.md` — update architecture section
+- `agent_config/claude-code/skills/ts-procedures/{patterns.md,anti-patterns.md,api-reference.md}` — CreateHttp examples
+- `agent_config/claude-code/skills/ts-procedures-scaffold/templates/*` — new templates
+- `agent_config/copilot/copilot-instructions.md`, `agent_config/cursor/cursorrules` — condensed mirror updates
+
+**Delete:**
+- (Nothing deleted outright — `APIInput` and the `schema.input` field are removed from their containing files but no whole-file deletions.)
+
+---
+
+## Phase 1 — Core file split (pure refactor, zero behavior change)
+
+This phase moves code into new files without changing semantics. Run the existing test suite after each task to confirm green. Commit between every task.
+
+### Task 1: Extract shared types into `src/types.ts`
+
+**Files:**
+- Create: `src/types.ts`
+- Modify: `src/index.ts`
+
+- [ ] **Step 1: Create `src/types.ts` with the shared exports**
+
+```ts
+import { ProcedureError } from './errors.js'
+import { TJSONSchema } from './schema/types.js'
+
+export type TNoContextProvided = unknown
+
+export type TLocalContext = {
+  error: (message: string, meta?: object) => ProcedureError
+  signal?: AbortSignal
+}
+
+export type TStreamContext = TLocalContext & {
+  signal: AbortSignal
+}
+
+export type ProcedureKind = 'rpc' | 'rpc-stream' | 'http' | 'http-stream'
+
+export type TProcedureRegistration<TContext = unknown, TExtendedConfig = unknown> = {
+  name: string
+  kind: 'rpc'
+  isStream?: false
+  config: {
+    description?: string
+    schema?: {
+      params?: TJSONSchema
+      returnType?: TJSONSchema
+    }
+    validation?: {
+      params?: (params: any) => { errors?: any[] }
+    }
+  } & TExtendedConfig
+  handler: (ctx: TContext, params?: any) => Promise<any>
+}
+
+export type TStreamProcedureRegistration<TContext = unknown, TExtendedConfig = unknown> = {
+  name: string
+  kind: 'rpc-stream'
+  isStream: true
+  config: {
+    description?: string
+    schema?: {
+      params?: TJSONSchema
+      yieldType?: TJSONSchema
+      returnType?: TJSONSchema
+    }
+    validation?: {
+      params?: (params: any) => { errors?: any[] }
+      yield?: (value: any) => { errors?: any[] }
+    }
+    validateYields?: boolean
+  } & TExtendedConfig
+  handler: (ctx: TContext, params?: any) => AsyncGenerator<any, any, unknown>
+}
+
+export type TBuilderConfig = {
+  /**
+   * Skip per-call AJV runtime validation. JSON Schema is still computed at
+   * registration time. Intended for trusted internal factories whose callers
+   * are already type-checked at build time.
+   */
+  noRuntimeValidation?: true
+}
+```
+
+(`'http'` and `'http-stream'` registration types are added in later phases when those creators land.)
+
+- [ ] **Step 2: Update `src/index.ts` to re-export from types.ts**
+
+Replace the type declarations at the top of `src/index.ts` with a re-export. The factory function and creators stay in place for now:
+
+```ts
+// At the very top of src/index.ts, replace the local TLocalContext/TStreamContext/etc. with:
+export {
+  type TNoContextProvided,
+  type TLocalContext,
+  type TStreamContext,
+  type ProcedureKind,
+  type TProcedureRegistration,
+  type TStreamProcedureRegistration,
+  type TBuilderConfig,
+} from './types.js'
+
+import { TLocalContext, TStreamContext, TBuilderConfig } from './types.js'
+```
+
+Delete the original `export type T...` declarations from `src/index.ts` (lines around 10-69 in the current file). Keep the `Procedures` function and `Create` / `CreateStream` definitions intact.
+
+- [ ] **Step 3: Run the full test suite**
+
+```bash
+npm run test
+```
+
+Expected: all existing tests pass. Type re-exports are transparent.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add src/types.ts src/index.ts
+git commit -m "refactor(core): extract shared types to src/types.ts"
+```
+
+---
+
+### Task 2: Extract `Create` into `src/create.ts`
+
+**Files:**
+- Create: `src/create.ts`
+- Modify: `src/index.ts`
+
+- [ ] **Step 1: Create `src/create.ts`**
+
+Move the `Create` function out of `src/index.ts` into a standalone factory. The function takes the `procedures` Map and `builder` config (so it can register and check `noRuntimeValidation`):
+
+```ts
+import { ProcedureError, ProcedureValidationError } from './errors.js'
+import { computeSchema } from './schema/compute-schema.js'
+import { Prettify, TSchemaLib } from './schema/types.js'
+import { captureDefinitionInfo } from './stack-utils.js'
+import {
+  TBuilderConfig,
+  TLocalContext,
+  TProcedureRegistration,
+  TStreamProcedureRegistration,
+} from './types.js'
+
+export type CreateBuilderArg<TContext, TExtendedConfig> = {
+  config?: TBuilderConfig
+  onCreate?: (procedure: TProcedureRegistration<TContext, TExtendedConfig> | TStreamProcedureRegistration<TContext, TExtendedConfig>) => void
+}
+
+export function makeCreate<TContext, TExtendedConfig>(
+  procedures: Map<string, TProcedureRegistration<TContext, TExtendedConfig> | TStreamProcedureRegistration<TContext, TExtendedConfig>>,
+  builder?: CreateBuilderArg<TContext, TExtendedConfig>,
+) {
+  return function Create<TName extends string, TParams, TReturnType>(
+    name: TName,
+    config: {
+      description?: string
+      schema?: {
+        params?: TParams
+        returnType?: TReturnType
+      }
+    } & TExtendedConfig,
+    handler: (ctx: Prettify<TContext & TLocalContext>, params: TSchemaLib<TParams>) => Promise<TSchemaLib<TReturnType>>,
+  ) {
+    const definitionInfo = captureDefinitionInfo()
+
+    if (procedures.has(name)) {
+      throw new Error(`Procedure with name ${name} is already registered`)
+    }
+
+    const { jsonSchema, validations } = computeSchema(name, config.schema, definitionInfo)
+
+    const errorFactory = (message: string, meta?: object) =>
+      new ProcedureError(name, message, meta, definitionInfo)
+
+    const registeredProcedure: TProcedureRegistration<TContext, TExtendedConfig> = {
+      name,
+      kind: 'rpc',
+      config: {
+        ...config,
+        description: config.description,
+        schema: jsonSchema,
+        validation: {
+          params: validations.params,
+        },
+      },
+      handler: async (ctx: Prettify<TContext>, params: TSchemaLib<TParams>) => {
+        try {
+          const skipValidation =
+            (ctx as { isPrevalidated?: boolean }).isPrevalidated ||
+            builder?.config?.noRuntimeValidation
+
+          if (validations?.params && !skipValidation) {
+            const { errors } = validations.params(params)
+            if (errors) {
+              throw new ProcedureValidationError(
+                name,
+                `Validation error for ${name}`,
+                errors,
+                definitionInfo,
+              )
+            }
+          }
+
+          const localCtx: TLocalContext = { error: errorFactory }
+
+          return await handler({ ...ctx, ...localCtx } as Prettify<TContext & TLocalContext>, params as any)
+        } catch (error: any) {
+          if (error instanceof ProcedureError) throw error
+          const err = new ProcedureError(name, `Error in handler for ${name} - ${error?.message}`, undefined, definitionInfo)
+          err.cause = error
+          if (error.stack && definitionInfo.definedAt) {
+            const { file, line, column } = definitionInfo.definedAt
+            err.stack = error.stack + `\n--- Procedure "${name}" defined at ---\n    at ${file}:${line}:${column}`
+          } else if (error.stack) {
+            err.stack = error.stack
+          }
+          throw err
+        }
+      },
+    }
+
+    procedures.set(name, registeredProcedure)
+    builder?.onCreate?.(registeredProcedure)
+
+    const info = { name, ...registeredProcedure.config }
+
+    return {
+      [name]: registeredProcedure.handler,
+      procedure: registeredProcedure.handler,
+      info,
+    } as {
+      [K in TName]: (ctx: Prettify<TContext>, params: TSchemaLib<TParams>) => Promise<TSchemaLib<TReturnType>>
+    } & {
+      procedure: (ctx: Prettify<TContext>, params: TSchemaLib<TParams>) => Promise<TSchemaLib<TReturnType>>
+      info: {
+        name: TName
+        description?: string
+        schema: { params?: TParams; returnType?: TReturnType }
+        validation?: { params?: (params: any) => { errors?: any[] } }
+      } & TExtendedConfig
+    }
+  }
+}
+```
+
+**Note:** This already drops `input` from the `Create` signature (Phase 2 will enforce the migration error). The conditional `TInput extends Record<string, unknown> ? ... : TSchemaLib<TParams>` is gone — `params` is always `TSchemaLib<TParams>`.
+
+- [ ] **Step 2: Update `src/index.ts` to use `makeCreate`**
+
+In the `Procedures` function body, replace the inline `Create` definition with:
+
+```ts
+import { makeCreate } from './create.js'
+
+// inside Procedures():
+const Create = makeCreate<TContext, TExtendedConfig>(procedures, builder)
+```
+
+Remove the original `function Create<...>` body.
+
+- [ ] **Step 3: Run the test suite**
+
+```bash
+npm run test
+```
+
+Expected: all existing tests that don't use `schema.input` on `Create` pass. Tests using `schema.input` will fail with a TS error or runtime error — that's expected; Phase 2 handles the migration error formally. Note which tests fail.
+
+- [ ] **Step 4: Mark failing tests with `it.todo` or temporarily skip**
+
+For any tests in `src/index.test.ts` that exercise `schema.input` on `Create`, change `it(...)` to `it.todo(...)` with a comment `// migrated to schema.req in Phase 3+`. We'll restore them in Phase 3 against `CreateHttp`.
+
+- [ ] **Step 5: Run tests again, expect green**
+
+```bash
+npm run test
+```
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/create.ts src/index.ts src/index.test.ts
+git commit -m "refactor(core): extract Create into src/create.ts; drop schema.input from Create"
+```
+
+---
+
+### Task 3: Extract `CreateStream` into `src/create-stream.ts`
+
+**Files:**
+- Create: `src/create-stream.ts`
+- Modify: `src/index.ts`
+
+- [ ] **Step 1: Create `src/create-stream.ts`**
+
+Mirror Task 2's pattern. Move the `CreateStream` function into its own file as a `makeCreateStream` factory. Drop the `TInput` generic and `input` from the schema shape — `CreateStream` now only accepts `params`/`yieldType`/`returnType`.
+
+```ts
+import { ProcedureError, ProcedureValidationError, ProcedureYieldValidationError } from './errors.js'
+import { computeSchema } from './schema/compute-schema.js'
+import { Prettify, TSchemaLib } from './schema/types.js'
+import { captureDefinitionInfo } from './stack-utils.js'
+import {
+  TBuilderConfig,
+  TStreamContext,
+  TProcedureRegistration,
+  TStreamProcedureRegistration,
+} from './types.js'
+
+export function makeCreateStream<TContext, TExtendedConfig>(
+  procedures: Map<string, TProcedureRegistration<TContext, TExtendedConfig> | TStreamProcedureRegistration<TContext, TExtendedConfig>>,
+  builder?: { config?: TBuilderConfig; onCreate?: (procedure: any) => void },
+) {
+  return function CreateStream<TName extends string, TParams, TYieldType, TReturnType = void>(
+    name: TName,
+    config: {
+      description?: string
+      schema?: {
+        params?: TParams
+        yieldType?: TYieldType
+        returnType?: TReturnType
+      }
+      validateYields?: boolean
+    } & TExtendedConfig,
+    handler: (
+      ctx: Prettify<TContext & TStreamContext>,
+      params: TSchemaLib<TParams>,
+    ) => AsyncGenerator<TSchemaLib<TYieldType>, TSchemaLib<TReturnType> | void, unknown>,
+  ) {
+    // [body identical to today's CreateStream in src/index.ts:284-503,
+    //  but with schema.input removed and `kind: 'rpc-stream'` set on the
+    //  registration. Copy from existing code, delete the input handling
+    //  blocks at lines ~366-380 and the TInput conditional return shapes.]
+  }
+}
+```
+
+**Reference:** Copy the existing `CreateStream` body from `src/index.ts` lines 284-503. Required edits:
+1. Set `kind: 'rpc-stream'` on the registration (alongside `isStream: true`).
+2. Remove the `TInput` generic and conditional return types.
+3. Remove the `validations.input` loop (around line 366-380 in current).
+4. Remove `input` from the `validation` object spread.
+
+- [ ] **Step 2: Wire `makeCreateStream` into `Procedures`**
+
+In `src/index.ts`:
+
+```ts
+import { makeCreateStream } from './create-stream.js'
+
+// inside Procedures():
+const CreateStream = makeCreateStream<TContext, TExtendedConfig>(procedures, builder)
+```
+
+Remove the inline `function CreateStream<...>` body from `src/index.ts`.
+
+- [ ] **Step 3: Mark schema.input stream tests as `it.todo`**
+
+Same treatment as Task 2 step 4.
+
+- [ ] **Step 4: Run tests**
+
+```bash
+npm run test
+```
+
+Expected: green except for `it.todo` cases.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/create-stream.ts src/index.ts src/index.test.ts
+git commit -m "refactor(core): extract CreateStream into src/create-stream.ts; drop schema.input"
+```
+
+---
+
+### Task 4: Slim `src/index.ts` to glue only
+
+**Files:**
+- Modify: `src/index.ts`
+
+- [ ] **Step 1: Verify `src/index.ts` is now a thin glue file**
+
+The remaining content should be: type re-exports, `Procedures` factory, factory's internal `procedures` Map, `getProcedures` / `getProcedure` / `removeProcedure` / `clear` helpers, and the import wiring for `makeCreate` / `makeCreateStream`. Should be ~100 lines.
+
+```bash
+wc -l src/index.ts
+```
+
+Expected: under 130 lines.
+
+- [ ] **Step 2: Run lint and typecheck**
+
+```bash
+npm run lint
+npm run build
+```
+
+Expected: green.
+
+- [ ] **Step 3: Run tests**
+
+```bash
+npm run test
+```
+
+Expected: green (excluding `it.todo` migrations).
+
+- [ ] **Step 4: Commit (if anything changed)**
+
+```bash
+git add src/index.ts
+git commit -m "refactor(core): finalize index.ts as Procedures factory glue" --allow-empty
+```
+
+---
+
+### Task 5: Add `kind` field to existing registrations and update `getProcedures` consumers
+
+**Files:**
+- Modify: `src/types.ts` (already done in Task 1 — verify)
+- Modify: `src/index.test.ts` (test that `kind` is present on returned registrations)
+
+- [ ] **Step 1: Add a test asserting `kind` appears on Create/CreateStream registrations**
+
+In `src/index.test.ts`:
+
+```ts
+import { Procedures } from './index.js'
+import { Type } from 'typebox'
+
+describe('Procedure registration kind discriminant', () => {
+  it('Create produces kind: rpc', () => {
+    const procs = Procedures()
+    procs.Create('Foo', { schema: { params: Type.Object({}) } }, async () => undefined)
+    const reg = procs.getProcedure('Foo')
+    expect(reg?.kind).toBe('rpc')
+  })
+
+  it('CreateStream produces kind: rpc-stream', () => {
+    const procs = Procedures()
+    procs.CreateStream('Bar', {
+      schema: { params: Type.Object({}), yieldType: Type.Number() },
+    }, async function* () {})
+    const reg = procs.getProcedure('Bar')
+    expect(reg?.kind).toBe('rpc-stream')
+  })
+})
+```
+
+- [ ] **Step 2: Run test, verify it passes**
+
+```bash
+npx vitest run src/index.test.ts -t "kind discriminant"
+```
+
+Expected: PASS (the `kind` was set in Tasks 2 and 3).
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add src/index.test.ts
+git commit -m "test(core): assert kind discriminant on registrations"
+```
+
+---
+
+## Phase 2 — Schema cleanup & migration errors
+
+Lock down the v8 shape: `compute-schema.ts` accepts `req`/`res` instead of `input`, and `Create` / `CreateStream` reject HTTP fields with informative errors.
+
+### Task 6: Update `computeSchema` signature for `req`/`res`
+
+**Files:**
+- Modify: `src/schema/compute-schema.ts`
+- Test: `src/schema/compute-schema.test.ts` (create if missing)
+
+- [ ] **Step 1: Read the current `compute-schema.ts`**
+
+```bash
+cat src/schema/compute-schema.ts
+```
+
+Note the current `input` handling (lines 17-84).
+
+- [ ] **Step 2: Update the schema input/output type signatures**
+
+Replace the `input` field with `req` and add `res`:
+
+```ts
+export function computeSchema<
+  TParamsSchemaType,
+  TReturnTypeSchemaType,
+  TYieldTypeSchemaType = unknown,
+>(
+  name: string,
+  schema?: {
+    params?: TParamsSchemaType
+    returnType?: TReturnTypeSchemaType
+    yieldType?: TYieldTypeSchemaType
+    req?: Record<string, unknown>     // was: input
+    res?: { body?: unknown; headers?: unknown }  // new
+  },
+  definitionInfo?: DefinitionInfo,
+): {
+  jsonSchema: {
+    params?: TJSONSchema
+    returnType?: TJSONSchema
+    yieldType?: TJSONSchema
+    req?: Record<string, TJSONSchema>
+    res?: { body?: TJSONSchema; headers?: TJSONSchema }
+  }
+  validations: {
+    params?: (params?: any) => { errors?: TSchemaValidationError[] }
+    yield?: (value?: any) => { errors?: TSchemaValidationError[] }
+    req?: Record<string, (value?: any) => { errors?: TSchemaValidationError[] }>
+  }
+}
+```
+
+Update the mutual-exclusivity guard:
+
+```ts
+if (schema?.params && schema?.req) {
+  throw new ProcedureRegistrationError(
+    name,
+    `schema.params and schema.req are mutually exclusive for procedure "${name}". Use schema.params for RPC procedures or schema.req for HTTP procedures.`,
+    definitionInfo,
+  )
+}
+```
+
+Adapt the `schemaParser` call to pass `req` where it previously passed `input`. The internal mechanics are identical — `req` is just a renamed `input`. (`res` validation is documentation-only; not parsed.)
+
+- [ ] **Step 3: Update `src/schema/parser.ts` to accept `req` channels**
+
+In `parser.ts`, find the block that processes `input` and rename to `req`. The validator factory pattern is unchanged — each channel gets its own AJV-compiled validator.
+
+- [ ] **Step 4: Run schema tests**
+
+```bash
+npx vitest run src/schema/
+```
+
+Expected: tests pass (no callers yet pass `req`/`res` outside of internal renames).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/schema/compute-schema.ts src/schema/parser.ts
+git commit -m "refactor(schema): rename input→req in compute-schema; add res slot"
+```
+
+---
+
+### Task 7: Add migration error when legacy `schema.input` is passed
+
+**Files:**
+- Modify: `src/schema/compute-schema.ts`
+- Test: `src/migration.test.ts` (create)
+
+- [ ] **Step 1: Write failing migration tests**
+
+Create `src/migration.test.ts`:
+
+```ts
+import { describe, it, expect } from 'vitest'
+import { Procedures } from './index.js'
+import { ProcedureRegistrationError } from './errors.js'
+import { Type } from 'typebox'
+
+describe('v7 → v8 migration errors', () => {
+  it('rejects schema.input on Create with v8 message', () => {
+    const procs = Procedures()
+    expect(() =>
+      procs.Create('Legacy', {
+        schema: {
+          // @ts-expect-error v8 removed schema.input
+          input: { body: Type.Object({}) },
+        },
+      }, async () => undefined)
+    ).toThrow(ProcedureRegistrationError)
+    expect(() =>
+      procs.Create('Legacy2', { schema: { input: { body: Type.Object({}) } } } as any, async () => undefined)
+    ).toThrow(/schema.input was removed in v8/)
+  })
+
+  it('rejects schema.input on CreateStream with v8 message', () => {
+    const procs = Procedures()
+    expect(() =>
+      procs.CreateStream('Legacy', {
+        schema: { input: { body: Type.Object({}) }, yieldType: Type.Number() } as any,
+      }, async function* () {})
+    ).toThrow(/schema.input was removed in v8/)
+  })
+})
+```
+
+- [ ] **Step 2: Run, verify they fail**
+
+```bash
+npx vitest run src/migration.test.ts
+```
+
+Expected: FAIL (no migration error implemented yet).
+
+- [ ] **Step 3: Add migration check in `compute-schema.ts`**
+
+At the top of `computeSchema`, before the existing mutual-exclusivity guard:
+
+```ts
+if (schema && 'input' in schema && (schema as any).input !== undefined) {
+  throw new ProcedureRegistrationError(
+    name,
+    `schema.input was removed in v8. Use CreateHttp / CreateHttpStream for per-channel HTTP validation. Procedure: "${name}".`,
+    definitionInfo,
+  )
+}
+```
+
+- [ ] **Step 4: Run tests, verify they pass**
+
+```bash
+npx vitest run src/migration.test.ts
+```
+
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/schema/compute-schema.ts src/migration.test.ts
+git commit -m "feat(migration): reject schema.input with v8 migration error"
+```
+
+---
+
+### Task 8: Reject HTTP fields on `Create` / `CreateStream`
+
+**Files:**
+- Modify: `src/create.ts`, `src/create-stream.ts`
+- Modify: `src/migration.test.ts`
+
+- [ ] **Step 1: Add failing migration tests**
+
+Append to `src/migration.test.ts`:
+
+```ts
+describe('HTTP fields rejected on RPC creators', () => {
+  const HTTP_FIELDS = ['path', 'method', 'req', 'res', 'successStatus'] as const
+
+  for (const field of HTTP_FIELDS) {
+    it(`Create rejects ${field}`, () => {
+      const procs = Procedures()
+      expect(() =>
+        procs.Create('Foo', { [field]: 'x', schema: { params: Type.Object({}) } } as any, async () => undefined)
+      ).toThrow(/HTTP fields require CreateHttp/)
+    })
+
+    it(`CreateStream rejects ${field}`, () => {
+      const procs = Procedures()
+      expect(() =>
+        procs.CreateStream('Bar', {
+          [field]: 'x',
+          schema: { params: Type.Object({}), yieldType: Type.Number() },
+        } as any, async function* () {})
+      ).toThrow(/HTTP fields require CreateHttp/)
+    })
+  }
+})
+```
+
+- [ ] **Step 2: Run, verify they fail**
+
+```bash
+npx vitest run src/migration.test.ts -t "HTTP fields"
+```
+
+Expected: FAIL.
+
+- [ ] **Step 3: Add HTTP-field guard helper to `src/create.ts`**
+
+At the top of `makeCreate`'s returned `Create` function (after `definitionInfo = captureDefinitionInfo()`):
+
+```ts
+import { ProcedureRegistrationError } from './errors.js'
+
+const HTTP_FIELDS = ['path', 'method', 'req', 'res', 'successStatus'] as const
+const presentHttpFields = HTTP_FIELDS.filter((f) => (config as any)[f] !== undefined)
+if (presentHttpFields.length > 0) {
+  throw new ProcedureRegistrationError(
+    name,
+    `HTTP fields require CreateHttp / CreateHttpStream. Procedure "${name}" has [${presentHttpFields.join(', ')}] which are not valid on Create.`,
+    definitionInfo,
+  )
+}
+```
+
+- [ ] **Step 4: Mirror the guard in `src/create-stream.ts`**
+
+Same block, adjusted message ("not valid on CreateStream").
+
+- [ ] **Step 5: Run tests**
+
+```bash
+npx vitest run src/migration.test.ts
+```
+
+Expected: PASS.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/create.ts src/create-stream.ts src/migration.test.ts
+git commit -m "feat(migration): reject HTTP fields on Create/CreateStream with v8 message"
+```
+
+---
+
+### Task 9: Move per-creator tests out of `src/index.test.ts`
+
+**Files:**
+- Create: `src/create.test.ts`, `src/create-stream.test.ts`
+- Modify: `src/index.test.ts`
+
+- [ ] **Step 1: Move `Create`-specific tests from `src/index.test.ts` to `src/create.test.ts`**
+
+Identify tests in `src/index.test.ts` that exercise `Create` specifically (validation, error wrapping, `info` shape, etc.). Move them to a new file `src/create.test.ts`. Update imports.
+
+- [ ] **Step 2: Move `CreateStream`-specific tests to `src/create-stream.test.ts`**
+
+Same pattern.
+
+- [ ] **Step 3: Keep `Procedures`-factory-level tests in `src/index.test.ts`**
+
+Tests covering: `getProcedures`, `getProcedure`, `removeProcedure`, `clear`, duplicate-name rejection, `onCreate` hook, factory return shape.
+
+- [ ] **Step 4: Run all three test files**
+
+```bash
+npx vitest run src/create.test.ts src/create-stream.test.ts src/index.test.ts
+```
+
+Expected: green.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/create.test.ts src/create-stream.test.ts src/index.test.ts
+git commit -m "test(core): split index.test.ts into per-creator files"
+```
+
+---
+
+## Phase 3 — `CreateHttp` (req only, no res yet)
+
+Add the new HTTP unary creator with structured request channels. Response shape (`res.body`/`res.headers`) lands in Phase 4. This phase keeps the surface minimal — handlers return whatever they want; we'll narrow in Phase 4.
+
+### Task 10: Define `CreateHttp` types in `src/types.ts`
+
+**Files:**
+- Modify: `src/types.ts`
+
+- [ ] **Step 1: Add HTTP method type and `CreateHttp` config / handler types**
+
+Append to `src/types.ts`:
+
+```ts
+export type HttpMethod = 'get' | 'post' | 'put' | 'delete' | 'patch' | 'head'
+
+export type TCreateHttpConfig<TReq, TRes, TErrorKey extends string = string> = {
+  path: string
+  method: HttpMethod
+  successStatus?: number
+  scope?: string
+  errors?: TErrorKey[]
+  description?: string
+  schema: {
+    req?: TReq
+    res?: TRes
+  }
+}
+
+export type THttpProcedureRegistration<TContext = unknown> = {
+  name: string
+  kind: 'http'
+  config: {
+    path: string
+    method: HttpMethod
+    successStatus?: number
+    scope?: string
+    errors?: string[]
+    description?: string
+    schema?: {
+      req?: Record<string, TJSONSchema>
+      res?: { body?: TJSONSchema; headers?: TJSONSchema }
+    }
+    validation?: {
+      req?: Record<string, (value: any) => { errors?: any[] }>
+    }
+  }
+  handler: (ctx: TContext, req?: any) => Promise<any>
+}
+```
+
+- [ ] **Step 2: Run lint to ensure imports resolve**
+
+```bash
+npm run lint
+```
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add src/types.ts
+git commit -m "feat(types): add HttpMethod and CreateHttp registration types"
+```
+
+---
+
+### Task 11: Implement `makeCreateHttp` in `src/create-http.ts`
+
+**Files:**
+- Create: `src/create-http.ts`
+
+- [ ] **Step 1: Write the file with the basic shape (req only, body return)**
+
+```ts
+import { ProcedureError, ProcedureRegistrationError, ProcedureValidationError } from './errors.js'
+import { computeSchema } from './schema/compute-schema.js'
+import { Prettify, TSchemaLib } from './schema/types.js'
+import { captureDefinitionInfo } from './stack-utils.js'
+import {
+  HttpMethod,
+  TBuilderConfig,
+  TLocalContext,
+  THttpProcedureRegistration,
+  TProcedureRegistration,
+  TStreamProcedureRegistration,
+} from './types.js'
+
+const PATH_PARAM_RE = /:([a-zA-Z_][a-zA-Z0-9_]*)/g
+
+function extractPathParamNames(path: string): string[] {
+  const matches = path.match(PATH_PARAM_RE)
+  return matches ? matches.map((m) => m.slice(1)) : []
+}
+
+function checkPathParamConsistency(
+  procedureName: string,
+  path: string,
+  pathParamsSchema: Record<string, unknown> | undefined,
+  definitionInfo: ReturnType<typeof captureDefinitionInfo>,
+) {
+  const pathParamNames = extractPathParamNames(path)
+  const hasPathParams = pathParamNames.length > 0
+  const hasSchema = pathParamsSchema !== undefined
+
+  if (hasPathParams && !hasSchema) {
+    throw new ProcedureRegistrationError(
+      procedureName,
+      `Path "${path}" has path parameters [${pathParamNames.join(', ')}] but schema.req.pathParams is not defined.`,
+      definitionInfo,
+    )
+  }
+  if (!hasPathParams && hasSchema) {
+    throw new ProcedureRegistrationError(
+      procedureName,
+      `schema.req.pathParams is defined but path "${path}" has no path parameters.`,
+      definitionInfo,
+    )
+  }
+  if (hasPathParams && hasSchema) {
+    const schemaProperties = (pathParamsSchema as { properties?: Record<string, unknown> }).properties
+    if (schemaProperties) {
+      const schemaKeys = Object.keys(schemaProperties)
+      const missing = pathParamNames.filter((p) => !schemaKeys.includes(p))
+      const extra = schemaKeys.filter((k) => !pathParamNames.includes(k))
+      if (missing.length > 0 || extra.length > 0) {
+        const parts: string[] = []
+        if (missing.length > 0) parts.push(`path has [${missing.join(', ')}] missing from schema`)
+        if (extra.length > 0) parts.push(`schema has [${extra.join(', ')}] not in path`)
+        throw new ProcedureRegistrationError(
+          procedureName,
+          `Path param mismatch for "${procedureName}": ${parts.join('; ')}.`,
+          definitionInfo,
+        )
+      }
+    }
+  }
+}
+
+export function makeCreateHttp<TContext>(
+  procedures: Map<string, TProcedureRegistration<TContext, any> | TStreamProcedureRegistration<TContext, any> | THttpProcedureRegistration<TContext>>,
+  builder?: { config?: TBuilderConfig; onCreate?: (procedure: any) => void },
+) {
+  return function CreateHttp<TName extends string, TReq extends Record<string, unknown> | undefined, TErrorKey extends string = string>(
+    name: TName,
+    config: {
+      path: string
+      method: HttpMethod
+      successStatus?: number
+      scope?: string
+      errors?: TErrorKey[]
+      description?: string
+      schema: {
+        req?: TReq
+      }
+    },
+    handler: (
+      ctx: Prettify<TContext & TLocalContext>,
+      req: TReq extends Record<string, unknown> ? Prettify<{ [K in keyof TReq]: TSchemaLib<TReq[K]> }> : undefined,
+    ) => Promise<unknown>,
+  ) {
+    const definitionInfo = captureDefinitionInfo()
+
+    if (procedures.has(name)) {
+      throw new Error(`Procedure with name ${name} is already registered`)
+    }
+
+    if ((config.schema as any)?.params) {
+      throw new ProcedureRegistrationError(
+        name,
+        `Use schema.req.body (or schema.req.query) instead of schema.params on CreateHttp. Procedure: "${name}".`,
+        definitionInfo,
+      )
+    }
+
+    const { jsonSchema, validations } = computeSchema(name, {
+      req: config.schema.req as Record<string, unknown> | undefined,
+    }, definitionInfo)
+
+    const pathParamsSchema = (jsonSchema.req as Record<string, unknown> | undefined)?.pathParams
+    checkPathParamConsistency(name, config.path, pathParamsSchema as Record<string, unknown> | undefined, definitionInfo)
+
+    const errorFactory = (message: string, meta?: object) =>
+      new ProcedureError(name, message, meta, definitionInfo)
+
+    const registeredProcedure: THttpProcedureRegistration<TContext> = {
+      name,
+      kind: 'http',
+      config: {
+        path: config.path,
+        method: config.method,
+        successStatus: config.successStatus,
+        scope: config.scope,
+        errors: config.errors as string[] | undefined,
+        description: config.description,
+        schema: jsonSchema as any,
+        validation: { req: validations.req },
+      },
+      handler: async (ctx: TContext, req: any) => {
+        try {
+          const skipValidation =
+            (ctx as { isPrevalidated?: boolean }).isPrevalidated ||
+            builder?.config?.noRuntimeValidation
+
+          if (validations?.req && !skipValidation) {
+            for (const [channel, validator] of Object.entries(validations.req)) {
+              const channelValue = (req as Record<string, unknown>)?.[channel]
+              const { errors } = validator(channelValue)
+              if (errors) {
+                throw new ProcedureValidationError(
+                  name,
+                  `Validation error for ${name} in req.${channel}`,
+                  errors,
+                  definitionInfo,
+                )
+              }
+            }
+          }
+
+          const localCtx: TLocalContext = { error: errorFactory }
+          return await handler({ ...ctx, ...localCtx } as any, req)
+        } catch (error: any) {
+          if (error instanceof ProcedureError) throw error
+          const err = new ProcedureError(name, `Error in handler for ${name} - ${error?.message}`, undefined, definitionInfo)
+          err.cause = error
+          if (error.stack && definitionInfo.definedAt) {
+            const { file, line, column } = definitionInfo.definedAt
+            err.stack = error.stack + `\n--- Procedure "${name}" defined at ---\n    at ${file}:${line}:${column}`
+          } else if (error.stack) {
+            err.stack = error.stack
+          }
+          throw err
+        }
+      },
+    }
+
+    procedures.set(name, registeredProcedure as any)
+    builder?.onCreate?.(registeredProcedure)
+
+    const info = { name, ...registeredProcedure.config }
+
+    return {
+      [name]: registeredProcedure.handler,
+      procedure: registeredProcedure.handler,
+      info,
+    } as {
+      [K in TName]: typeof registeredProcedure.handler
+    } & {
+      procedure: typeof registeredProcedure.handler
+      info: typeof info
+    }
+  }
+}
+```
+
+- [ ] **Step 2: Wire `makeCreateHttp` into `Procedures` factory**
+
+In `src/index.ts`:
+
+```ts
+import { makeCreateHttp } from './create-http.js'
+
+// inside Procedures():
+const CreateHttp = makeCreateHttp<TContext>(procedures as any, builder)
+
+return {
+  // existing fields ...
+  Create,
+  CreateStream,
+  CreateHttp,
+}
+```
+
+Also update the `procedures` Map's type signature to accept `THttpProcedureRegistration`.
+
+- [ ] **Step 3: Run lint and build**
+
+```bash
+npm run lint
+npm run build
+```
+
+Expected: green.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add src/create-http.ts src/index.ts
+git commit -m "feat(core): add CreateHttp with req channels and path-param validation"
+```
+
+---
+
+### Task 12: Test `CreateHttp` registration and req validation
+
+**Files:**
+- Create: `src/create-http.test.ts`
+
+- [ ] **Step 1: Write tests covering registration shape**
+
+```ts
+import { describe, it, expect } from 'vitest'
+import { Procedures } from './index.js'
+import { ProcedureRegistrationError, ProcedureValidationError } from './errors.js'
+import { Type } from 'typebox'
+
+describe('CreateHttp registration', () => {
+  it('registers with kind: http', () => {
+    const procs = Procedures()
+    procs.CreateHttp('GetUser', {
+      path: '/users/:id',
+      method: 'get',
+      schema: { req: { pathParams: Type.Object({ id: Type.String() }) } },
+    }, async (_, { pathParams }) => ({ id: pathParams.id }))
+
+    const reg = procs.getProcedure('GetUser')
+    expect(reg?.kind).toBe('http')
+  })
+
+  it('rejects schema.params with v8 message', () => {
+    const procs = Procedures()
+    expect(() =>
+      procs.CreateHttp('Bad', {
+        path: '/x', method: 'get',
+        schema: { params: Type.Object({}) } as any,
+      }, async () => undefined)
+    ).toThrow(/Use schema.req.body \(or schema.req.query\) instead of schema.params/)
+  })
+
+  it('rejects path with params but no pathParams schema', () => {
+    const procs = Procedures()
+    expect(() =>
+      procs.CreateHttp('Bad', {
+        path: '/users/:id', method: 'get',
+        schema: { req: {} },
+      }, async () => undefined)
+    ).toThrow(/path parameters \[id\] but schema.req.pathParams is not defined/)
+  })
+
+  it('rejects pathParams schema with no path params', () => {
+    const procs = Procedures()
+    expect(() =>
+      procs.CreateHttp('Bad', {
+        path: '/users', method: 'get',
+        schema: { req: { pathParams: Type.Object({ id: Type.String() }) } },
+      }, async () => undefined)
+    ).toThrow(/has no path parameters/)
+  })
+
+  it('rejects pathParams key mismatch', () => {
+    const procs = Procedures()
+    expect(() =>
+      procs.CreateHttp('Bad', {
+        path: '/users/:id', method: 'get',
+        schema: { req: { pathParams: Type.Object({ wrongKey: Type.String() }) } },
+      }, async () => undefined)
+    ).toThrow(/Path param mismatch/)
+  })
+})
+
+describe('CreateHttp req channel validation', () => {
+  it('validates each channel independently with channel-tagged error', async () => {
+    const procs = Procedures()
+    const { GetUser } = procs.CreateHttp('GetUser', {
+      path: '/users/:id', method: 'get',
+      schema: {
+        req: {
+          pathParams: Type.Object({ id: Type.String() }),
+          query: Type.Object({ limit: Type.Number() }),
+        },
+      },
+    }, async (_, { pathParams, query }) => ({ id: pathParams.id, limit: query.limit }))
+
+    await expect(GetUser({} as any, {
+      pathParams: { id: 'abc' },
+      query: { limit: 'not-a-number' as any },
+    })).rejects.toThrow(ProcedureValidationError)
+    await expect(GetUser({} as any, {
+      pathParams: { id: 'abc' },
+      query: { limit: 'not-a-number' as any },
+    })).rejects.toThrow(/req\.query/)
+  })
+})
+```
+
+- [ ] **Step 2: Run tests**
+
+```bash
+npx vitest run src/create-http.test.ts
+```
+
+Expected: PASS for all five registration tests and the validation test.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add src/create-http.test.ts
+git commit -m "test(core): cover CreateHttp registration and req validation"
+```
+
+---
+
+## Phase 4 — `CreateHttp` response shape (`res.body`, `res.headers`, conditional return)
+
+### Task 13: Add `res.body` to `CreateHttp` config and types
+
+**Files:**
+- Modify: `src/types.ts`
+- Modify: `src/create-http.ts`
+- Test: `src/create-http.test.ts`
+
+- [ ] **Step 1: Extend the config type to include `res.body`**
+
+In `src/types.ts`, update `TCreateHttpConfig`:
+
+```ts
+export type TCreateHttpConfig<TReq, TRes, TErrorKey extends string = string> = {
+  path: string
+  method: HttpMethod
+  successStatus?: number
+  scope?: string
+  errors?: TErrorKey[]
+  description?: string
+  schema: {
+    req?: TReq
+    res?: TRes  // { body?, headers? } — narrowed at the creator call site
+  }
+}
+```
+
+- [ ] **Step 2: Update `makeCreateHttp` signature to thread `TRes`**
+
+In `src/create-http.ts`:
+
+```ts
+return function CreateHttp<
+  TName extends string,
+  TReq extends Record<string, unknown> | undefined,
+  TRes extends { body?: unknown; headers?: unknown } | undefined = undefined,
+  TErrorKey extends string = string,
+>(
+  name: TName,
+  config: TCreateHttpConfig<TReq, TRes, TErrorKey>,
+  handler: (
+    ctx: Prettify<TContext & TLocalContext>,
+    req: TReq extends Record<string, unknown> ? Prettify<{ [K in keyof TReq]: TSchemaLib<TReq[K]> }> : undefined,
+  ) => Promise<HttpReturn<TRes>>,
+) { /* ... */ }
+```
+
+Add the `HttpReturn` helper type at the top of the file:
+
+```ts
+type Infer<T> = TSchemaLib<T>
+
+export type HttpReturn<TRes> =
+  TRes extends { body: infer B; headers: infer H } ? { body: Infer<B>; headers: Infer<H> }
+  : TRes extends { headers: infer H }              ? { headers: Infer<H> }
+  : TRes extends { body: infer B }                  ? Infer<B>
+  : void
+```
+
+- [ ] **Step 3: Pass `res` through to `computeSchema`**
+
+In the body of `makeCreateHttp`'s creator function:
+
+```ts
+const { jsonSchema, validations } = computeSchema(name, {
+  req: config.schema.req as Record<string, unknown> | undefined,
+  res: config.schema.res as { body?: unknown; headers?: unknown } | undefined,
+}, definitionInfo)
+```
+
+- [ ] **Step 4: Add a test for body-only return**
+
+In `src/create-http.test.ts`:
+
+```ts
+describe('CreateHttp res.body', () => {
+  it('handler returns body bare when only res.body declared', async () => {
+    const procs = Procedures()
+    const { GetUser } = procs.CreateHttp('GetUser', {
+      path: '/users/:id', method: 'get',
+      schema: {
+        req: { pathParams: Type.Object({ id: Type.String() }) },
+        res: { body: Type.Object({ id: Type.String(), name: Type.String() }) },
+      },
+    }, async (_, { pathParams }) => ({ id: pathParams.id, name: 'Alice' }))
+
+    const result = await GetUser({} as any, { pathParams: { id: '1' } })
+    expect(result).toEqual({ id: '1', name: 'Alice' })
+  })
+})
+```
+
+- [ ] **Step 5: Run tests**
+
+```bash
+npx vitest run src/create-http.test.ts -t "res.body"
+```
+
+Expected: PASS.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/types.ts src/create-http.ts src/create-http.test.ts
+git commit -m "feat(core): add CreateHttp res.body with bare-body return shape"
+```
+
+---
+
+### Task 14: Add `res.headers` and conditional `{ body, headers }` return
+
+**Files:**
+- Modify: `src/create-http.ts`
+- Test: `src/create-http.test.ts`
+
+- [ ] **Step 1: Write failing tests for the four return shapes**
+
+```ts
+describe('CreateHttp conditional return shape', () => {
+  it('res: { body, headers } → returns { body, headers }', async () => {
+    const procs = Procedures()
+    const { GetUser } = procs.CreateHttp('GetUser', {
+      path: '/users/:id', method: 'get',
+      schema: {
+        req: { pathParams: Type.Object({ id: Type.String() }) },
+        res: {
+          body: Type.Object({ id: Type.String() }),
+          headers: Type.Object({ 'x-rate-limit': Type.String() }),
+        },
+      },
+    }, async (_, { pathParams }) => ({
+      body: { id: pathParams.id },
+      headers: { 'x-rate-limit': '99' },
+    }))
+
+    const result = await GetUser({} as any, { pathParams: { id: '1' } })
+    expect(result).toEqual({ body: { id: '1' }, headers: { 'x-rate-limit': '99' } })
+  })
+
+  it('res: { headers } only → returns { headers }', async () => {
+    const procs = Procedures()
+    const { Healthcheck } = procs.CreateHttp('Healthcheck', {
+      path: '/health', method: 'get',
+      schema: {
+        res: { headers: Type.Object({ 'x-version': Type.String() }) },
+      },
+    }, async () => ({ headers: { 'x-version': '8.0.0' } }))
+
+    const result = await Healthcheck({} as any, undefined)
+    expect(result).toEqual({ headers: { 'x-version': '8.0.0' } })
+  })
+
+  it('no res → returns void', async () => {
+    const procs = Procedures()
+    const { Ping } = procs.CreateHttp('Ping', {
+      path: '/ping', method: 'post',
+      schema: { req: { body: Type.Object({}) } },
+    }, async () => undefined)
+
+    const result = await Ping({} as any, { body: {} })
+    expect(result).toBeUndefined()
+  })
+})
+```
+
+- [ ] **Step 2: Run, verify they pass**
+
+The handler return shape is enforced at the **type level** by `HttpReturn<TRes>` (from Task 13). Runtime doesn't validate `res` body/headers (per spec out-of-scope). So if tests are typed correctly, runtime just passes through whatever the handler returns.
+
+```bash
+npx vitest run src/create-http.test.ts -t "conditional return"
+```
+
+Expected: PASS (no implementation change needed beyond Task 13's `HttpReturn` type — runtime is pass-through).
+
+- [ ] **Step 3: Add a type-level test (using `expectTypeOf`)**
+
+```ts
+import { expectTypeOf } from 'vitest'
+
+describe('CreateHttp HttpReturn type inference', () => {
+  it('infers correct return shapes', () => {
+    const procs = Procedures()
+    const { GetUser } = procs.CreateHttp('GetUser', {
+      path: '/users/:id', method: 'get',
+      schema: {
+        req: { pathParams: Type.Object({ id: Type.String() }) },
+        res: {
+          body: Type.Object({ id: Type.String() }),
+          headers: Type.Object({ 'x-rate-limit': Type.String() }),
+        },
+      },
+    }, async () => ({ body: { id: '1' }, headers: { 'x-rate-limit': '99' } }))
+
+    type ReturnT = Awaited<ReturnType<typeof GetUser>>
+    expectTypeOf<ReturnT>().toEqualTypeOf<{ body: { id: string }; headers: { 'x-rate-limit': string } }>()
+  })
+})
+```
+
+- [ ] **Step 4: Run tests**
+
+```bash
+npx vitest run src/create-http.test.ts
+```
+
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/create-http.ts src/create-http.test.ts
+git commit -m "feat(core): conditional return shape on CreateHttp (body, headers, both, void)"
+```
+
+---
+
+## Phase 5 — `CreateHttpStream`
+
+### Task 15: Define `CreateHttpStream` types
+
+**Files:**
+- Modify: `src/types.ts`
+
+- [ ] **Step 1: Add the streaming registration type and config**
+
+```ts
+export type THttpStreamProcedureRegistration<TContext = unknown> = {
+  name: string
+  kind: 'http-stream'
+  config: {
+    path: string
+    method: HttpMethod
+    scope?: string
+    errors?: string[]
+    description?: string
+    schema?: {
+      req?: Record<string, TJSONSchema>
+      res?: { headers?: TJSONSchema }
+      yield?: TJSONSchema
+      returnType?: TJSONSchema
+    }
+    validation?: {
+      req?: Record<string, (value: any) => { errors?: any[] }>
+      yield?: (value: any) => { errors?: any[] }
+    }
+    validateYields?: boolean
+  }
+  handler: (ctx: TContext, req?: any) => AsyncGenerator<any, any, unknown> | Promise<{ headers: Record<string, string>; stream: AsyncGenerator<any, any, unknown> }>
+}
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add src/types.ts
+git commit -m "feat(types): add CreateHttpStream registration type"
+```
+
+---
+
+### Task 16: Implement `makeCreateHttpStream` (no res.headers branch — plain async generator)
+
+**Files:**
+- Create: `src/create-http-stream.ts`
+
+- [ ] **Step 1: Write the file**
+
+Use the existing `CreateStream` body from `src/create-stream.ts` as the template. Required adaptations:
+1. Accept `path`/`method`/`scope`/`errors` config fields.
+2. Use `req` channels (mirror `create-http.ts` validation loop).
+3. Set `kind: 'http-stream'` on registration.
+4. Reject `schema.params` with v8 message (mirror `create-http.ts`).
+5. Run path-param consistency check (call the helper exported from `create-http.ts` — extract it or duplicate).
+
+```ts
+import { ProcedureError, ProcedureRegistrationError, ProcedureValidationError, ProcedureYieldValidationError } from './errors.js'
+import { computeSchema } from './schema/compute-schema.js'
+import { Prettify, TSchemaLib } from './schema/types.js'
+import { captureDefinitionInfo } from './stack-utils.js'
+import {
+  HttpMethod, TBuilderConfig, TStreamContext,
+  THttpStreamProcedureRegistration, TProcedureRegistration, TStreamProcedureRegistration, THttpProcedureRegistration,
+} from './types.js'
+import { checkPathParamConsistency } from './create-http.js'  // export it from create-http.ts
+
+export function makeCreateHttpStream<TContext>(
+  procedures: Map<string, TProcedureRegistration<TContext, any> | TStreamProcedureRegistration<TContext, any> | THttpProcedureRegistration<TContext> | THttpStreamProcedureRegistration<TContext>>,
+  builder?: { config?: TBuilderConfig; onCreate?: (procedure: any) => void },
+) {
+  return function CreateHttpStream<TName extends string, TReq extends Record<string, unknown> | undefined, TYieldType, TReturnType = void, TErrorKey extends string = string>(
+    name: TName,
+    config: {
+      path: string
+      method: HttpMethod
+      scope?: string
+      errors?: TErrorKey[]
+      description?: string
+      schema: {
+        req?: TReq
+        yield?: TYieldType
+        returnType?: TReturnType
+        // res: { headers? } added in Task 18
+      }
+      validateYields?: boolean
+    },
+    handler: (
+      ctx: Prettify<TContext & TStreamContext>,
+      req: TReq extends Record<string, unknown> ? Prettify<{ [K in keyof TReq]: TSchemaLib<TReq[K]> }> : undefined,
+    ) => AsyncGenerator<TSchemaLib<TYieldType>, TSchemaLib<TReturnType> | void, unknown>,
+  ) {
+    const definitionInfo = captureDefinitionInfo()
+
+    if (procedures.has(name)) throw new Error(`Procedure with name ${name} is already registered`)
+    if ((config.schema as any)?.params) {
+      throw new ProcedureRegistrationError(name, `Use schema.req.body (or schema.req.query) instead of schema.params on CreateHttpStream. Procedure: "${name}".`, definitionInfo)
+    }
+
+    const { jsonSchema, validations } = computeSchema(name, {
+      req: config.schema.req as Record<string, unknown> | undefined,
+      yieldType: config.schema.yield,
+      returnType: config.schema.returnType,
+    }, definitionInfo)
+
+    const pathParamsSchema = (jsonSchema.req as Record<string, unknown> | undefined)?.pathParams
+    checkPathParamConsistency(name, config.path, pathParamsSchema as Record<string, unknown> | undefined, definitionInfo)
+
+    const errorFactory = (message: string, meta?: object) => new ProcedureError(name, message, meta, definitionInfo)
+    const validateYields = config.validateYields ?? false
+
+    const wrappedHandler = async function* (ctx: TContext, req: any) {
+      const abortController = new AbortController()
+      const skipValidation = (ctx as { isPrevalidated?: boolean }).isPrevalidated || builder?.config?.noRuntimeValidation
+
+      if (validations?.req && !skipValidation) {
+        for (const [channel, validator] of Object.entries(validations.req)) {
+          const channelValue = (req as Record<string, unknown>)?.[channel]
+          const { errors } = validator(channelValue)
+          if (errors) {
+            throw new ProcedureValidationError(name, `Validation error for ${name} in req.${channel}`, errors, definitionInfo)
+          }
+        }
+      }
+
+      const incomingSignal = (ctx as { signal?: AbortSignal }).signal
+      const signal = incomingSignal ? AbortSignal.any([incomingSignal, abortController.signal]) : abortController.signal
+      const streamCtx: TStreamContext = { error: errorFactory, signal }
+
+      const userGenerator = handler({ ...ctx, ...streamCtx } as any, req)
+      const userIterator = userGenerator[Symbol.asyncIterator]()
+
+      try {
+        let userIterResult = await userIterator.next()
+        while (!userIterResult.done) {
+          const value = userIterResult.value
+          if (validateYields && validations.yield) {
+            const { errors } = validations.yield(value)
+            if (errors) throw new ProcedureYieldValidationError(name, `Yield validation error for ${name}`, errors, definitionInfo)
+          }
+          yield value
+          userIterResult = await userIterator.next()
+        }
+        return userIterResult.value
+      } catch (error: any) {
+        if (definitionInfo.definedAt && error && typeof error.stack === 'string') {
+          const { file, line, column } = definitionInfo.definedAt
+          error.stack = `${error.stack}\n--- Procedure "${name}" defined at ---\n    at ${file}:${line}:${column}`
+        }
+        throw error
+      } finally {
+        try { await userIterator.return?.(undefined) } catch { /* swallow cleanup */ }
+        abortController.abort('stream-completed')
+      }
+    }
+
+    const registeredProcedure: THttpStreamProcedureRegistration<TContext> = {
+      name,
+      kind: 'http-stream',
+      config: {
+        path: config.path,
+        method: config.method,
+        scope: config.scope,
+        errors: config.errors as string[] | undefined,
+        description: config.description,
+        schema: jsonSchema as any,
+        validation: { req: validations.req, yield: validations.yield },
+        validateYields,
+      },
+      handler: wrappedHandler as any,
+    }
+
+    procedures.set(name, registeredProcedure as any)
+    builder?.onCreate?.(registeredProcedure)
+
+    const info = { name, kind: 'http-stream' as const, ...registeredProcedure.config }
+
+    return {
+      [name]: registeredProcedure.handler,
+      procedure: registeredProcedure.handler,
+      info,
+    } as {
+      [K in TName]: typeof registeredProcedure.handler
+    } & {
+      procedure: typeof registeredProcedure.handler
+      info: typeof info
+    }
+  }
+}
+```
+
+- [ ] **Step 2: Export `checkPathParamConsistency` from `create-http.ts`**
+
+Add `export` keyword to the helper.
+
+- [ ] **Step 3: Wire `CreateHttpStream` into `Procedures` factory**
+
+In `src/index.ts`:
+
+```ts
+import { makeCreateHttpStream } from './create-http-stream.js'
+
+// inside Procedures():
+const CreateHttpStream = makeCreateHttpStream<TContext>(procedures as any, builder)
+
+return { /* ... */ Create, CreateStream, CreateHttp, CreateHttpStream }
+```
+
+- [ ] **Step 4: Build**
+
+```bash
+npm run build
+```
+
+Expected: green.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/create-http-stream.ts src/create-http.ts src/index.ts
+git commit -m "feat(core): add CreateHttpStream (plain async generator, no res.headers yet)"
+```
+
+---
+
+### Task 17: Test `CreateHttpStream` plain-generator path
+
+**Files:**
+- Create: `src/create-http-stream.test.ts`
+
+- [ ] **Step 1: Write tests covering the basic shape**
+
+```ts
+import { describe, it, expect, vi } from 'vitest'
+import { Procedures } from './index.js'
+import { Type } from 'typebox'
+import { ProcedureValidationError } from './errors.js'
+
+describe('CreateHttpStream basic generator', () => {
+  it('registers with kind: http-stream', () => {
+    const procs = Procedures()
+    procs.CreateHttpStream('Tail', {
+      path: '/streams/logs', method: 'get',
+      schema: {
+        req: { query: Type.Object({ source: Type.String() }) },
+        yield: Type.Object({ line: Type.String() }),
+      },
+    }, async function* () { yield { line: 'a' } })
+
+    expect(procs.getProcedure('Tail')?.kind).toBe('http-stream')
+  })
+
+  it('yields and returns', async () => {
+    const procs = Procedures()
+    const { Tail } = procs.CreateHttpStream('Tail', {
+      path: '/streams/logs', method: 'get',
+      schema: {
+        req: { query: Type.Object({ source: Type.String() }) },
+        yield: Type.Object({ line: Type.String() }),
+        returnType: Type.Object({ totalLines: Type.Number() }),
+      },
+    }, async function* (_, { query }) {
+      yield { line: `from-${query.source}-1` }
+      yield { line: `from-${query.source}-2` }
+      return { totalLines: 2 }
+    })
+
+    const lines: string[] = []
+    let returnVal: unknown
+    const gen = Tail({} as any, { query: { source: 'app' } })
+    let result = await gen.next()
+    while (!result.done) {
+      lines.push(result.value.line)
+      result = await gen.next()
+    }
+    returnVal = result.value
+    expect(lines).toEqual(['from-app-1', 'from-app-2'])
+    expect(returnVal).toEqual({ totalLines: 2 })
+  })
+
+  it('rejects req.query validation error before opening stream', async () => {
+    const procs = Procedures()
+    const { Tail } = procs.CreateHttpStream('Tail', {
+      path: '/streams/logs', method: 'get',
+      schema: {
+        req: { query: Type.Object({ source: Type.String() }) },
+        yield: Type.Object({ line: Type.String() }),
+      },
+    }, async function* () { yield { line: 'should not run' } })
+
+    const gen = Tail({} as any, { query: {} as any })
+    await expect(gen.next()).rejects.toThrow(ProcedureValidationError)
+    await expect(gen.next()).rejects.toThrow(/req\.query/)
+  })
+})
+```
+
+- [ ] **Step 2: Run tests**
+
+```bash
+npx vitest run src/create-http-stream.test.ts
+```
+
+Expected: PASS.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add src/create-http-stream.test.ts
+git commit -m "test(core): cover CreateHttpStream basic generator path"
+```
+
+---
+
+### Task 18: Add `res.headers` async-preamble shape to `CreateHttpStream`
+
+**Files:**
+- Modify: `src/create-http-stream.ts`
+- Modify: `src/types.ts`
+- Test: `src/create-http-stream.test.ts`
+
+- [ ] **Step 1: Extend the config and handler types**
+
+In `src/create-http-stream.ts`, widen the config and handler signature:
+
+```ts
+return function CreateHttpStream<
+  TName extends string,
+  TReq extends Record<string, unknown> | undefined,
+  TYieldType,
+  TReturnType = void,
+  TResHeaders = undefined,
+  TErrorKey extends string = string,
+>(
+  name: TName,
+  config: {
+    path: string
+    method: HttpMethod
+    scope?: string
+    errors?: TErrorKey[]
+    description?: string
+    schema: {
+      req?: TReq
+      yield?: TYieldType
+      returnType?: TReturnType
+      res?: TResHeaders extends undefined ? undefined : { headers: TResHeaders }
+    }
+    validateYields?: boolean
+  },
+  handler: TResHeaders extends undefined
+    ? (
+        ctx: Prettify<TContext & TStreamContext>,
+        req: TReq extends Record<string, unknown> ? Prettify<{ [K in keyof TReq]: TSchemaLib<TReq[K]> }> : undefined,
+      ) => AsyncGenerator<TSchemaLib<TYieldType>, TSchemaLib<TReturnType> | void, unknown>
+    : (
+        ctx: Prettify<TContext & TStreamContext>,
+        req: TReq extends Record<string, unknown> ? Prettify<{ [K in keyof TReq]: TSchemaLib<TReq[K]> }> : undefined,
+      ) => Promise<{ headers: TSchemaLib<TResHeaders>; stream: AsyncGenerator<TSchemaLib<TYieldType>, TSchemaLib<TReturnType> | void, unknown> }>,
+) { /* ... */ }
+```
+
+- [ ] **Step 2: Update the wrapped handler to detect the async-preamble shape at runtime**
+
+The runtime needs to introspect what the user handler returns. If it's a generator (has `Symbol.asyncIterator`), use today's path. If it's a Promise, await it for `{ headers, stream }` and use the `stream` field.
+
+Replace the `wrappedHandler` body in `makeCreateHttpStream`:
+
+```ts
+const wrappedHandler = async function* (ctx: TContext, req: any) {
+  const abortController = new AbortController()
+  const skipValidation = (ctx as { isPrevalidated?: boolean }).isPrevalidated || builder?.config?.noRuntimeValidation
+
+  if (validations?.req && !skipValidation) {
+    for (const [channel, validator] of Object.entries(validations.req)) {
+      const channelValue = (req as Record<string, unknown>)?.[channel]
+      const { errors } = validator(channelValue)
+      if (errors) throw new ProcedureValidationError(name, `Validation error for ${name} in req.${channel}`, errors, definitionInfo)
+    }
+  }
+
+  const incomingSignal = (ctx as { signal?: AbortSignal }).signal
+  const signal = incomingSignal ? AbortSignal.any([incomingSignal, abortController.signal]) : abortController.signal
+  const streamCtx: TStreamContext = { error: errorFactory, signal }
+
+  const handlerResult: any = (handler as any)({ ...ctx, ...streamCtx }, req)
+
+  // Detect async-preamble shape: handler returned a Promise
+  let userGenerator: AsyncGenerator<any, any, unknown>
+  let initialHeaders: Record<string, string> | undefined
+
+  if (typeof handlerResult?.[Symbol.asyncIterator] === 'function') {
+    // Plain async generator
+    userGenerator = handlerResult
+  } else if (typeof handlerResult?.then === 'function') {
+    // Promise → await for { headers, stream }
+    const resolved = await handlerResult
+    if (!resolved || typeof resolved !== 'object' || !('stream' in resolved)) {
+      throw new ProcedureError(name, `CreateHttpStream handler returned a Promise that did not resolve to { headers, stream }. Got: ${JSON.stringify(resolved)}`, undefined, definitionInfo)
+    }
+    initialHeaders = resolved.headers
+    userGenerator = resolved.stream
+  } else {
+    throw new ProcedureError(name, `CreateHttpStream handler must return an AsyncGenerator or Promise<{ headers, stream }>.`, undefined, definitionInfo)
+  }
+
+  // Surface initial headers via a synthetic first yield with a known sentinel — but
+  // that's not transport-clean. Instead we attach headers to the wrappedHandler's
+  // generator object so the Hono builder can read them. AsyncGenerators don't
+  // support arbitrary properties cleanly through the typed surface, so we expose
+  // them via the registration's `getInitialHeaders` accessor rather than the
+  // generator itself.
+  ;(wrappedHandler as any)._lastInitialHeaders = initialHeaders
+
+  const userIterator = userGenerator[Symbol.asyncIterator]()
+  try {
+    let userIterResult = await userIterator.next()
+    while (!userIterResult.done) {
+      const value = userIterResult.value
+      if (validateYields && validations.yield) {
+        const { errors } = validations.yield(value)
+        if (errors) throw new ProcedureYieldValidationError(name, `Yield validation error for ${name}`, errors, definitionInfo)
+      }
+      yield value
+      userIterResult = await userIterator.next()
+    }
+    return userIterResult.value
+  } catch (error: any) {
+    if (definitionInfo.definedAt && error && typeof error.stack === 'string') {
+      const { file, line, column } = definitionInfo.definedAt
+      error.stack = `${error.stack}\n--- Procedure "${name}" defined at ---\n    at ${file}:${line}:${column}`
+    }
+    throw error
+  } finally {
+    try { await userIterator.return?.(undefined) } catch { /* swallow */ }
+    abortController.abort('stream-completed')
+  }
+}
+```
+
+**Note on the initial-headers handoff:** stashing on `wrappedHandler._lastInitialHeaders` is fragile under concurrent calls. Better: make the wrappedHandler return a custom iterable that exposes `.initialHeaders` when iterated. Or — simpler — yield a sentinel first value `{ __initialHeaders: {...} }` that the Hono builder strips. Choose the sentinel approach for thread safety:
+
+Replace the marked block with:
+
+```ts
+// Yield headers sentinel as the first value if async-preamble was used.
+// The Hono builder strips this sentinel and applies headers before opening SSE.
+if (initialHeaders) {
+  yield { __initialHeaders: initialHeaders } as any
+}
+```
+
+And document the sentinel shape in `src/types.ts`:
+
+```ts
+export const HTTP_STREAM_HEADERS_SENTINEL = '__initialHeaders' as const
+```
+
+- [ ] **Step 3: Write failing tests for the async-preamble shape**
+
+```ts
+describe('CreateHttpStream async-preamble shape (res.headers)', () => {
+  it('handler returning Promise<{ headers, stream }> yields headers sentinel first', async () => {
+    const procs = Procedures()
+    const { Tail } = procs.CreateHttpStream('Tail', {
+      path: '/streams/logs', method: 'get',
+      schema: {
+        req: { query: Type.Object({ source: Type.String() }) },
+        yield: Type.Object({ line: Type.String() }),
+        res: { headers: Type.Object({ 'x-stream-id': Type.String() }) },
+      },
+    }, async (_, { query }) => ({
+      headers: { 'x-stream-id': `id-${query.source}` },
+      stream: (async function* () { yield { line: 'a' } })(),
+    }))
+
+    const gen = Tail({} as any, { query: { source: 'app' } })
+    const first = await gen.next()
+    expect(first.value).toEqual({ __initialHeaders: { 'x-stream-id': 'id-app' } })
+    const second = await gen.next()
+    expect(second.value).toEqual({ line: 'a' })
+  })
+
+  it('throws when handler returns malformed shape', async () => {
+    const procs = Procedures()
+    const { Bad } = procs.CreateHttpStream('Bad', {
+      path: '/streams', method: 'get',
+      schema: {
+        yield: Type.Number(),
+        res: { headers: Type.Object({}) },
+      },
+    }, (async () => 'not-a-shape') as any)
+
+    const gen = Bad({} as any, undefined)
+    await expect(gen.next()).rejects.toThrow(/did not resolve to/)
+  })
+})
+```
+
+- [ ] **Step 4: Run tests**
+
+```bash
+npx vitest run src/create-http-stream.test.ts
+```
+
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/create-http-stream.ts src/types.ts src/create-http-stream.test.ts
+git commit -m "feat(core): add CreateHttpStream async-preamble shape with headers sentinel"
+```
+
+---
+
+## Phase 6 — Hono builder unification
+
+### Task 19: Strip `APIConfig` generic from `HonoAPIFactoryItem`
+
+**Files:**
+- Modify: `src/implementations/http/hono-api/types.ts`
+
+- [ ] **Step 1: Replace `HonoAPIFactoryItem` definition**
+
+```ts
+import { ExtractContext, APIHttpRouteDoc } from '../../types.js'
+import { Procedures } from '../../../index.js'
+import { THttpProcedureRegistration, THttpStreamProcedureRegistration } from '../../../types.js'
+import { Context } from 'hono'
+
+export type HonoAPIFactoryItem<TFactory = ReturnType<typeof Procedures<any>>> = {
+  factory: TFactory
+  factoryContext: ExtractContext<TFactory> | ((c: Context) => ExtractContext<TFactory> | Promise<ExtractContext<TFactory>>)
+  extendProcedureDoc?: (params: {
+    base: APIHttpRouteDoc
+    procedure: THttpProcedureRegistration<any> | THttpStreamProcedureRegistration<any>
+  }) => Record<string, any>
+}
+```
+
+- [ ] **Step 2: Build to surface compile errors**
+
+```bash
+npm run build
+```
+
+Expected: errors in `src/implementations/http/hono-api/index.ts` because the factory is no longer generic over `APIConfig`. Those will be fixed in Task 20.
+
+- [ ] **Step 3: Commit (without build green — Task 20 finishes the chain)**
+
+```bash
+git add src/implementations/http/hono-api/types.ts
+git commit -m "refactor(hono-api): drop APIConfig generic from HonoAPIFactoryItem"
+```
+
+---
+
+### Task 20: Update `HonoAPIAppBuilder` to read `CreateHttp` registrations and apply response headers
+
+**Files:**
+- Modify: `src/implementations/http/hono-api/index.ts`
+
+- [ ] **Step 1: Update `register` signature**
+
+```ts
+register<TFactory extends ProceduresFactory>(
+  factory: TFactory,
+  factoryContext: ExtractContext<TFactory> | ((c: Context) => ExtractContext<TFactory> | Promise<ExtractContext<TFactory>>),
+  extendProcedureDoc?: (params: {
+    base: APIHttpRouteDoc
+    procedure: THttpProcedureRegistration<any> | THttpStreamProcedureRegistration<any>
+  }) => Record<string, any>,
+): this
+```
+
+- [ ] **Step 2: In `build()`, filter procedures by `kind === 'http'` and capture skipped procedures**
+
+```ts
+build(): Hono {
+  const queryParser = this.config?.queryParser ?? parseQueryNative
+  const skipped: { name: string; reason: string }[] = []
+
+  this.factories.forEach(({ factory, factoryContext, extendProcedureDoc }) => {
+    factory.getProcedures().forEach((procedure: any) => {
+      if (procedure.kind === 'http') {
+        // existing http registration flow
+        this.registerHttpRoute(procedure, factoryContext, extendProcedureDoc, queryParser)
+      } else if (procedure.kind === 'http-stream') {
+        // Phase 6 Task 22 wires this up
+        this.registerHttpStreamRoute(procedure, factoryContext, extendProcedureDoc, queryParser)
+      } else {
+        skipped.push({
+          name: procedure.name,
+          reason: `Procedure has kind "${procedure.kind}"; HonoAPIAppBuilder serves only "http" and "http-stream".`,
+        })
+      }
+    })
+  })
+
+  this._skippedProcedures = skipped
+  return this._app
+}
+```
+
+Add the `_skippedProcedures` private field and a `get skippedProcedures()` accessor.
+
+- [ ] **Step 3: Refactor existing route handler logic into `registerHttpRoute`**
+
+Move the existing per-procedure body (path resolution, doc build, route handler, mount) into `private registerHttpRoute(procedure, factoryContext, extendProcedureDoc, queryParser)`. Adapt it to read `procedure.config` directly (no more `APIConfig` generic — fields are first-class).
+
+- [ ] **Step 4: Update `extractInputParams` to read `req` instead of `input`**
+
+The function body is unchanged in logic — just rename the variable from `inputSchema` to `reqSchema` and update the parameter type. Channel extraction (`pathParams`/`query`/`body`/`headers`) is identical to today.
+
+- [ ] **Step 5: Apply response headers when handler returns `{ body, headers }`**
+
+In the route handler:
+
+```ts
+const result = await procedure.handler({ ...context, signal: c.req.raw.signal }, params)
+
+if (this.config?.onSuccess) this.config.onSuccess(procedure, c)
+if (successStatus === 204) {
+  // Apply headers if present
+  if (result && typeof result === 'object' && 'headers' in result && result.headers) {
+    for (const [k, v] of Object.entries(result.headers as Record<string, string>)) {
+      c.header(k, v)
+    }
+  }
+  return c.body(null, 204)
+}
+
+// Detect { body, headers } shape vs bare body
+let body: unknown = result
+let headers: Record<string, string> | undefined
+if (result && typeof result === 'object' && 'body' in result && 'headers' in result) {
+  body = (result as any).body
+  headers = (result as any).headers
+} else if (result && typeof result === 'object' && 'headers' in result && !('body' in result)) {
+  // headers-only case
+  for (const [k, v] of Object.entries((result as any).headers as Record<string, string>)) {
+    c.header(k, v)
+  }
+  return c.body(null, successStatus as any)
+}
+
+if (headers) {
+  for (const [k, v] of Object.entries(headers)) c.header(k, v)
+}
+return c.json(body, successStatus as any)
+```
+
+- [ ] **Step 6: Build to confirm compile errors are resolved**
+
+```bash
+npm run build
+```
+
+Expected: green.
+
+- [ ] **Step 7: Run hono-api tests (will likely fail — fixed in next task)**
+
+```bash
+npx vitest run src/implementations/http/hono-api/
+```
+
+Note any failing tests; they'll need updates (Task 23).
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add src/implementations/http/hono-api/index.ts
+git commit -m "refactor(hono-api): read CreateHttp registrations directly; apply response headers"
+```
+
+---
+
+### Task 21: Add `'http-stream'` branch to `HonoAPIAppBuilder`
+
+**Files:**
+- Modify: `src/implementations/http/hono-api/index.ts`
+
+- [ ] **Step 1: Implement `registerHttpStreamRoute`**
+
+```ts
+import { streamSSE } from 'hono/streaming'
+import { HTTP_STREAM_HEADERS_SENTINEL } from '../../../types.js'
+
+private registerHttpStreamRoute(
+  procedure: THttpStreamProcedureRegistration<any>,
+  factoryContext: any,
+  extendProcedureDoc: any,
+  queryParser: QueryParser,
+) {
+  const fullPath = this.resolveFullPath(procedure.config.path)
+  const route = this.buildHttpStreamRouteDoc(procedure, fullPath, extendProcedureDoc)
+  this._docs.push(route)
+
+  const method = procedure.config.method.toUpperCase()
+  const reqSchema = procedure.config.schema?.req
+
+  this._app.on(method, fullPath, async (c: Context) => {
+    try {
+      const context = typeof factoryContext === 'function' ? await factoryContext(c) : factoryContext
+      const params = reqSchema
+        ? await this.extractInputParams(c, procedure.config.method, reqSchema, queryParser)
+        : undefined
+
+      // Pre-stream phase: open the generator, await first value (which may be sentinel)
+      const gen = procedure.handler({ ...context, signal: c.req.raw.signal, isPrevalidated: false }, params)
+      const first = await gen.next()
+
+      // If first value is the headers sentinel, apply headers and consume next
+      let initialYield: any
+      if (first.value && typeof first.value === 'object' && HTTP_STREAM_HEADERS_SENTINEL in first.value) {
+        for (const [k, v] of Object.entries((first.value as any)[HTTP_STREAM_HEADERS_SENTINEL] as Record<string, string>)) {
+          c.header(k, v)
+        }
+        initialYield = await gen.next()
+      } else {
+        initialYield = first
+      }
+
+      // Open SSE response and stream remaining yields
+      return streamSSE(c, async (stream) => {
+        let it = initialYield
+        while (!it.done) {
+          await stream.writeSSE({ data: JSON.stringify(it.value) })
+          it = await gen.next()
+        }
+        if (it.value !== undefined) {
+          await stream.writeSSE({ event: 'return', data: JSON.stringify(it.value) })
+        }
+      })
+    } catch (error) {
+      // Pre-stream error path — same dispatch as registerHttpRoute
+      return this.handleError(error, procedure, c)
+    }
+  })
+}
+```
+
+Extract the error-dispatch block from `registerHttpRoute` into a shared `private handleError(error, procedure, c)` method so both branches use the same dispatch flow (taxonomy → onError → hard default + onRequestError observer).
+
+- [ ] **Step 2: Add `buildHttpStreamRouteDoc` helper**
+
+```ts
+private buildHttpStreamRouteDoc(
+  procedure: THttpStreamProcedureRegistration<any>,
+  fullPath: string,
+  extendProcedureDoc?: HonoAPIFactoryItem['extendProcedureDoc'],
+): HttpStreamRouteDoc {
+  const config = procedure.config
+  const reqSchema = config.schema?.req
+  const resSchema = config.schema?.res
+  const jsonSchema: HttpStreamRouteDoc['jsonSchema'] = {}
+  if (reqSchema) jsonSchema.req = reqSchema
+  if (resSchema) jsonSchema.res = resSchema
+  if (config.schema?.yield) jsonSchema.yield = config.schema.yield
+  if (config.schema?.returnType) jsonSchema.returnType = config.schema.returnType
+
+  const base: HttpStreamRouteDoc = {
+    kind: 'http-stream',
+    name: procedure.name,
+    scope: config.scope,
+    path: config.path,
+    method: config.method,
+    fullPath,
+    streamMode: 'sse',
+    jsonSchema,
+  }
+  if (config.errors && config.errors.length > 0) base.errors = [...config.errors]
+
+  let extendedDoc: object = {}
+  if (extendProcedureDoc) extendedDoc = extendProcedureDoc({ base: base as any, procedure })
+  return { ...extendedDoc, ...base }
+}
+```
+
+(`HttpStreamRouteDoc` type is added in Phase 7 / Task 24. For now use `any` if needed and revisit.)
+
+- [ ] **Step 3: Build**
+
+```bash
+npm run build
+```
+
+Expected: green (or near-green pending the type added in Phase 7).
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add src/implementations/http/hono-api/index.ts
+git commit -m "feat(hono-api): add http-stream branch with sentinel-based headers handoff"
+```
+
+---
+
+### Task 22: Test `HonoAPIAppBuilder` for both `'http'` and `'http-stream'` kinds + response headers
+
+**Files:**
+- Modify: `src/implementations/http/hono-api/index.test.ts`
+
+- [ ] **Step 1: Update existing tests to use `CreateHttp` instead of `Create` + `APIConfig`**
+
+Find tests that registered procedures via `Procedures<Ctx, APIConfig>().Create('Foo', { path, method, schema: { input } }, ...)`. Migrate them to `Procedures<Ctx>().CreateHttp('Foo', { path, method, schema: { req } }, ...)`.
+
+- [ ] **Step 2: Add new tests for response headers**
+
+```ts
+it('applies res.headers to the response', async () => {
+  const procs = Procedures()
+  procs.CreateHttp('GetUser', {
+    path: '/users/:id', method: 'get',
+    schema: {
+      req: { pathParams: Type.Object({ id: Type.String() }) },
+      res: {
+        body: Type.Object({ id: Type.String() }),
+        headers: Type.Object({ 'x-rate-limit': Type.String() }),
+      },
+    },
+  }, async (_, { pathParams }) => ({
+    body: { id: pathParams.id },
+    headers: { 'x-rate-limit': '99' },
+  }))
+
+  const app = new HonoAPIAppBuilder().register(procs, {}).build()
+  const res = await app.request('/users/abc')
+  expect(res.status).toBe(200)
+  expect(res.headers.get('x-rate-limit')).toBe('99')
+  expect(await res.json()).toEqual({ id: 'abc' })
+})
+
+it('handles headers-only response (204)', async () => {
+  const procs = Procedures()
+  procs.CreateHttp('Touch', {
+    path: '/touch/:id', method: 'delete',
+    schema: {
+      req: { pathParams: Type.Object({ id: Type.String() }) },
+      res: { headers: Type.Object({ 'x-touched-at': Type.String() }) },
+    },
+  }, async () => ({ headers: { 'x-touched-at': '2026-05-08' } }))
+
+  const app = new HonoAPIAppBuilder().register(procs, {}).build()
+  const res = await app.request('/touch/abc', { method: 'DELETE' })
+  expect(res.status).toBe(204)
+  expect(res.headers.get('x-touched-at')).toBe('2026-05-08')
+})
+```
+
+- [ ] **Step 3: Add tests for the http-stream branch**
+
+```ts
+it('serves CreateHttpStream as SSE', async () => {
+  const procs = Procedures()
+  procs.CreateHttpStream('TailLogs', {
+    path: '/streams/logs', method: 'get',
+    schema: {
+      req: { query: Type.Object({ source: Type.String() }) },
+      yield: Type.Object({ line: Type.String() }),
+      returnType: Type.Object({ totalLines: Type.Number() }),
+    },
+  }, async function* (_, { query }) {
+    yield { line: `from-${query.source}-1` }
+    yield { line: `from-${query.source}-2` }
+    return { totalLines: 2 }
+  })
+
+  const app = new HonoAPIAppBuilder().register(procs, {}).build()
+  const res = await app.request('/streams/logs?source=app')
+  const text = await res.text()
+  expect(text).toContain('data: {"line":"from-app-1"}')
+  expect(text).toContain('event: return\ndata: {"totalLines":2}')
+})
+
+it('applies http-stream initial response headers from async preamble', async () => {
+  const procs = Procedures()
+  procs.CreateHttpStream('TailLogs', {
+    path: '/streams/logs', method: 'get',
+    schema: {
+      req: { query: Type.Object({ source: Type.String() }) },
+      yield: Type.Object({ line: Type.String() }),
+      res: { headers: Type.Object({ 'x-stream-id': Type.String() }) },
+    },
+  }, async (_, { query }) => ({
+    headers: { 'x-stream-id': `sid-${query.source}` },
+    stream: (async function* () { yield { line: 'first' } })(),
+  }))
+
+  const app = new HonoAPIAppBuilder().register(procs, {}).build()
+  const res = await app.request('/streams/logs?source=app')
+  expect(res.headers.get('x-stream-id')).toBe('sid-app')
+  expect(await res.text()).toContain('data: {"line":"first"}')
+})
+```
+
+- [ ] **Step 4: Run tests**
+
+```bash
+npx vitest run src/implementations/http/hono-api/
+```
+
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/implementations/http/hono-api/index.test.ts
+git commit -m "test(hono-api): cover CreateHttp response headers and http-stream branch"
+```
+
+---
+
+### Task 23: Add `kind`-based filtering to `HonoRPCAppBuilder`, `HonoStreamAppBuilder`
+
+**Files:**
+- Modify: `src/implementations/http/hono-rpc/index.ts`
+- Modify: `src/implementations/http/hono-stream/index.ts`
+
+- [ ] **Step 1: For each of the two builders, change `getProcedures().forEach` filtering**
+
+In `hono-rpc/index.ts` `build()`:
+
+```ts
+factory.getProcedures().forEach((procedure: any) => {
+  if (procedure.kind !== 'rpc') {
+    skipped.push({
+      name: procedure.name,
+      reason: `Procedure has kind "${procedure.kind}"; HonoRPCAppBuilder serves only "rpc".`,
+    })
+    return
+  }
+  // existing rpc registration flow
+})
+```
+
+- [ ] **Step 2: Same pattern for `hono-stream` (kind === 'rpc-stream')**
+
+- [ ] **Step 3: Add `_skippedProcedures` and accessor on each builder**
+
+Mirror the `HonoAPIAppBuilder._skippedProcedures` pattern from Task 20.
+
+- [ ] **Step 4: Update each builder's tests to assert skipped procedures**
+
+For each test file, add:
+
+```ts
+it('records http-kind procedures in skippedProcedures', () => {
+  const procs = Procedures()
+  procs.CreateHttp('Skipped', {
+    path: '/x', method: 'get',
+    schema: { req: { query: Type.Object({}) } },
+  }, async () => undefined)
+
+  const builder = new HonoRPCAppBuilder().register(procs, {})
+  builder.build()
+  expect(builder.skippedProcedures).toContainEqual({
+    name: 'Skipped',
+    reason: expect.stringContaining('HonoRPCAppBuilder serves only "rpc"'),
+  })
+})
+```
+
+- [ ] **Step 5: Run all builder tests**
+
+```bash
+npx vitest run src/implementations/http/
+```
+
+Expected: PASS.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/implementations/http/hono-rpc/ src/implementations/http/hono-stream/
+git commit -m "refactor(builders): kind-based filtering with skippedProcedures across rpc/stream builders"
+```
+
+---
+
+### Task 24: Update Astro adapter for kind-aware updates
+
+**Files:**
+- Modify: `src/implementations/http/astro/*`
+- Modify: `src/implementations/http/astro/*.test.ts`
+
+- [ ] **Step 1: Inspect the Astro adapter to identify how it consumes procedures**
+
+```bash
+ls src/implementations/http/astro/
+cat src/implementations/http/astro/*.ts | head -200
+```
+
+- [ ] **Step 2: Apply the same pattern as `HonoAPIAppBuilder`**
+
+Filter by `kind === 'http'` (and `'http-stream'` if Astro supports streaming). Stash skipped procedures. Read `path` / `method` / `req` / `res` from `CreateHttp` registrations directly. Apply response headers from handler return.
+
+- [ ] **Step 3: Update Astro tests**
+
+Migrate any tests using `Create` + `schema.input` to `CreateHttp` + `schema.req`.
+
+- [ ] **Step 4: Run Astro tests**
+
+```bash
+npx vitest run src/implementations/http/astro/
+```
+
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/implementations/http/astro/
+git commit -m "refactor(astro): kind-aware procedure filtering and response headers"
+```
+
+---
+
+## Phase 7 — Doc envelope updates
+
+### Task 25: Restructure `APIHttpRouteDoc` and add `HttpStreamRouteDoc`
+
+**Files:**
+- Modify: `src/implementations/types.ts`
+
+- [ ] **Step 1: Replace `APIHttpRouteDoc` with regrouped shape**
+
+```ts
+export interface APIHttpRouteDoc {
+  kind: 'api'
+  name: string
+  scope?: string
+  path: string
+  method: HttpMethod
+  fullPath: string
+  successStatus?: number
+  errors?: string[]
+  jsonSchema: {
+    req?: { pathParams?: Record<string, unknown>; query?: Record<string, unknown>; body?: Record<string, unknown>; headers?: Record<string, unknown> }
+    res?: { body?: Record<string, unknown>; headers?: Record<string, unknown> }
+  }
+}
+```
+
+- [ ] **Step 2: Add `HttpStreamRouteDoc`**
+
+```ts
+export interface HttpStreamRouteDoc {
+  kind: 'http-stream'
+  name: string
+  scope?: string
+  path: string
+  method: HttpMethod
+  fullPath: string
+  streamMode: StreamMode
+  errors?: string[]
+  jsonSchema: {
+    req?: { pathParams?: Record<string, unknown>; query?: Record<string, unknown>; body?: Record<string, unknown>; headers?: Record<string, unknown> }
+    res?: { headers?: Record<string, unknown> }
+    yield?: Record<string, unknown>
+    returnType?: Record<string, unknown>
+  }
+}
+```
+
+- [ ] **Step 3: Extend `AnyHttpRouteDoc` union**
+
+```ts
+export type AnyHttpRouteDoc = RPCHttpRouteDoc | APIHttpRouteDoc | StreamHttpRouteDoc | HttpStreamRouteDoc
+```
+
+- [ ] **Step 4: Remove `APIInput` and `APIConfig` (or simplify)**
+
+`APIConfig` is no longer needed as a `TExtendedConfig` shape since HTTP fields live on `CreateHttp` directly. But it may still be referenced from external types — search for usages first:
+
+```bash
+grep -rn "APIConfig\|APIInput" src/ --include="*.ts"
+```
+
+If any internal code still references `APIConfig`, either inline its fields or leave the type as a deprecation-marked alias. Prefer removal — the migration error in Phase 2 catches v7 callers.
+
+- [ ] **Step 5: Build**
+
+```bash
+npm run build
+```
+
+Expected: surfaces compile errors in `hono-api/index.ts` (the `buildApiHttpRouteDoc` and `buildHttpStreamRouteDoc` need to populate the new shape) and in codegen files (Phase 8 work). Fix the hono-api build errors now:
+
+In `buildApiHttpRouteDoc` (Task 20):
+
+```ts
+const reqSchema = procedure.config.schema?.req
+const resSchema = procedure.config.schema?.res
+const jsonSchema: APIHttpRouteDoc['jsonSchema'] = {}
+if (reqSchema) jsonSchema.req = reqSchema as any
+if (resSchema) jsonSchema.res = resSchema as any
+```
+
+- [ ] **Step 6: Run hono-api tests**
+
+```bash
+npx vitest run src/implementations/http/hono-api/
+```
+
+Expected: PASS.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add src/implementations/types.ts src/implementations/http/hono-api/index.ts
+git commit -m "feat(envelope): regroup APIHttpRouteDoc under req/res; add HttpStreamRouteDoc"
+```
+
+---
+
+### Task 26: Update `DocRegistry` for `'http-stream'` kind
+
+**Files:**
+- Modify: `src/implementations/http/doc-registry.ts`
+- Modify: `src/implementations/http/doc-registry.test.ts`
+
+- [ ] **Step 1: Search for kind-discriminating logic**
+
+```bash
+grep -n "kind\|RPCHttpRouteDoc\|APIHttpRouteDoc\|StreamHttpRouteDoc" src/implementations/http/doc-registry.ts
+```
+
+- [ ] **Step 2: Add `'http-stream'` to any switch/filter logic**
+
+If `doc-registry.ts` has explicit kind-handling, add the new case. If it just iterates `AnyHttpRouteDoc[]`, the type widening in Task 25 is sufficient.
+
+- [ ] **Step 3: Add a test that aggregates docs from multiple builders including http-stream**
+
+```ts
+it('aggregates http-stream routes from HonoAPIAppBuilder', () => {
+  const procs = Procedures()
+  procs.CreateHttpStream('Tail', {
+    path: '/streams/logs', method: 'get',
+    schema: { req: { query: Type.Object({ source: Type.String() }) }, yield: Type.Object({ line: Type.String() }) },
+  }, async function* () {})
+
+  const builder = new HonoAPIAppBuilder().register(procs, {})
+  builder.build()
+
+  const registry = DocRegistry.from(builder)
+  const envelope = registry.toJSON()
+  const route = envelope.routes.find((r) => r.name === 'Tail')
+  expect(route?.kind).toBe('http-stream')
+})
+```
+
+- [ ] **Step 4: Run doc-registry tests**
+
+```bash
+npx vitest run src/implementations/http/doc-registry.test.ts
+```
+
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/implementations/http/doc-registry.ts src/implementations/http/doc-registry.test.ts
+git commit -m "feat(doc-registry): aggregate http-stream routes alongside http"
+```
+
+---
+
+## Phase 8 — Codegen TS target
+
+### Task 27: Update `group-routes.ts` and `route-slots.ts` for new kind and req/res grouping
+
+**Files:**
+- Modify: `src/codegen/group-routes.ts`
+- Modify: `src/codegen/targets/_shared/route-slots.ts`
+
+- [ ] **Step 1: Read current `route-slots.ts`**
+
+```bash
+cat src/codegen/targets/_shared/route-slots.ts
+```
+
+- [ ] **Step 2: Add `responseHeaders` slot to `RouteSlot` definition**
+
+```ts
+export type RouteSlot = {
+  pathParams?: Record<string, unknown>
+  query?: Record<string, unknown>
+  body?: Record<string, unknown>
+  headers?: Record<string, unknown>             // request headers
+  response?: Record<string, unknown>            // response body (for back-compat / unary)
+  responseHeaders?: Record<string, unknown>     // new
+  yield?: Record<string, unknown>
+  returnType?: Record<string, unknown>
+}
+```
+
+- [ ] **Step 3: Update `extractRouteSlots` to read from new envelope shape**
+
+```ts
+export function extractRouteSlots(route: AnyHttpRouteDoc): RouteSlot {
+  const slots: RouteSlot = {}
+  if (route.kind === 'api' || route.kind === 'http-stream') {
+    const req = route.jsonSchema.req
+    if (req?.pathParams) slots.pathParams = req.pathParams
+    if (req?.query) slots.query = req.query
+    if (req?.body) slots.body = req.body
+    if (req?.headers) slots.headers = req.headers
+    const res = route.jsonSchema.res
+    if (res?.body) slots.response = res.body
+    if (res?.headers) slots.responseHeaders = res.headers
+  }
+  if (route.kind === 'http-stream') {
+    if (route.jsonSchema.yield) slots.yield = route.jsonSchema.yield
+    if (route.jsonSchema.returnType) slots.returnType = route.jsonSchema.returnType
+  }
+  // ... existing rpc and stream cases
+  return slots
+}
+```
+
+- [ ] **Step 4: Update `group-routes.ts` to recognize `'http-stream'` kind**
+
+If `group-routes.ts` has any kind-specific switching, add the case. Streams group by scope same as `'http'`.
+
+- [ ] **Step 5: Build**
+
+```bash
+npm run build
+```
+
+Expected: green (or surfaces emit-scope.ts errors fixed in Task 28).
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/codegen/group-routes.ts src/codegen/targets/_shared/route-slots.ts
+git commit -m "feat(codegen): add responseHeaders slot and http-stream kind handling"
+```
+
+---
+
+### Task 28: Update `emit-scope.ts` for `Req` / `Response` namespace naming and conditional return
+
+**Files:**
+- Modify: `src/codegen/emit-scope.ts`
+- Modify: `src/codegen/targets/ts/run.ts` (if emit logic is split there)
+
+- [ ] **Step 1: Read existing emission for `'api'` routes**
+
+```bash
+grep -n "emit\(API\|Api\|Stream\|Rpc\)Route\|Params\|Response" src/codegen/emit-scope.ts | head -40
+```
+
+- [ ] **Step 2: Restructure type namespace emission**
+
+Where today's code emits flat `<Route>Params`, `<Route>Body`, `<Route>Response`, change to nested under `Req` and `Response`:
+
+Namespace mode (the default):
+```
+<Route>.Req.PathParams
+<Route>.Req.Query
+<Route>.Req.Body
+<Route>.Req.Headers
+<Route>.Response.Body
+<Route>.Response.Headers
+<Route>.Errors
+```
+
+Flat mode:
+```
+<Route>ReqPathParams
+<Route>ReqQuery
+<Route>ReqBody
+<Route>ReqHeaders
+<Route>ResponseBody
+<Route>ResponseHeaders
+```
+
+- [ ] **Step 3: Update generated callable signature with conditional return**
+
+When `slots.responseHeaders` is present, emit:
+
+```ts
+declare function getUser(req: GetUser.Req, opts?): Promise<{ body: GetUser.Response.Body; headers: GetUser.Response.Headers }>
+```
+
+When only `slots.response` (body) is present:
+```ts
+declare function getUser(req: GetUser.Req, opts?): Promise<GetUser.Response.Body>
+```
+
+When only `slots.responseHeaders`:
+```ts
+declare function getUser(req: GetUser.Req, opts?): Promise<{ headers: GetUser.Response.Headers }>
+```
+
+When neither:
+```ts
+declare function getUser(req: GetUser.Req, opts?): Promise<void>
+```
+
+- [ ] **Step 4: Add `'http-stream'` callable emission**
+
+Mirror the existing `'stream'` emission but with `Req` namespace and optional `Response.Headers`. Returns `TypedStream<Yield, Return>` where `TypedStream` has optional `headers` field.
+
+- [ ] **Step 5: Update `.safe()` sibling to widen with the conditional return**
+
+If `slots.responseHeaders`, the typed result becomes `Result<{ body, headers }, ETyped>` not `Result<Body, ETyped>`.
+
+- [ ] **Step 6: Regenerate the fixture envelope**
+
+```bash
+# Find the test that constructs the fixture and run it manually to dump current output
+grep -rn "users-envelope.json" src/codegen/
+```
+
+Update `src/codegen/__fixtures__/users-envelope.json` with the new `req`/`res` grouping and `'http-stream'` kind. Easiest path: write a small fixture-generation script that registers procs via `CreateHttp`/`CreateHttpStream`, builds the doc registry, and writes the JSON. Or hand-edit the JSON.
+
+- [ ] **Step 7: Run codegen tests**
+
+```bash
+npx vitest run src/codegen/
+```
+
+Expected: snapshot mismatches at first. Inspect each snapshot diff carefully — confirm the new shape is correct, then update snapshots:
+
+```bash
+npx vitest run src/codegen/ -u
+```
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add src/codegen/emit-scope.ts src/codegen/__fixtures__/users-envelope.json src/codegen/**/*.snap*
+git commit -m "feat(codegen-ts): emit Req/Response namespaces and conditional return shapes"
+```
+
+---
+
+### Task 29: Update self-contained `_client.ts` and `_types.ts` emission
+
+**Files:**
+- Modify: `src/codegen/targets/ts/run.ts` (or wherever `_client.ts` is bundled)
+- Modify: `src/client/*.ts` source files (which get bundled)
+
+- [ ] **Step 1: Find where `_client.ts` is assembled**
+
+```bash
+grep -rn "_client.ts\|selfContained" src/codegen/
+```
+
+- [ ] **Step 2: Ensure new client runtime files (added in Phase 10) are bundled**
+
+Phase 10 will modify `src/client/call.ts`, `src/client/stream.ts`, `src/client/types.ts`, `src/client/fetch-adapter.ts` to surface response headers. The self-contained bundler reads these files — verify the bundling logic picks up changes automatically (typically a `readFileSync` over the client source files).
+
+- [ ] **Step 3: Run codegen tests for self-contained mode**
+
+```bash
+npx vitest run src/codegen/ -t "self-contained"
+```
+
+Expected: tests pass after Phase 10 lands. For now, may pass or have type-only mismatches deferred to Phase 10.
+
+- [ ] **Step 4: Commit any changes**
+
+```bash
+git add -p
+git commit -m "feat(codegen-ts): wire self-contained _client.ts to surface response headers"
+```
+
+---
+
+## Phase 9 — Codegen Kotlin & Swift targets
+
+### Task 30: Kotlin target — emit `Response.Headers` data class
+
+**Files:**
+- Modify: `src/codegen/targets/kotlin/run.ts`
+- Modify: `src/codegen/targets/kotlin/run.test.ts`
+
+- [ ] **Step 1: Read the current Kotlin emit logic**
+
+```bash
+cat src/codegen/targets/kotlin/run.ts | head -80
+```
+
+Identify where `Response` data class is emitted for `'api'` routes.
+
+- [ ] **Step 2: Update Kotlin emission for new envelope shape**
+
+Read `req` channel schemas instead of flat `pathParams` / `query` / etc. Adapt the nested object emission accordingly:
+
+```kotlin
+object Users {
+  object GetUser {
+    const val method = "GET"
+    fun path(p: PathParams): String = "/users/${p.id}"
+    @Serializable data class PathParams(val id: String)
+    @Serializable data class Query(val include: String? = null)
+    object Response {
+      @Serializable data class Body(val id: String, val name: String)
+      @Serializable data class Headers(@SerialName("x-rate-limit") val xRateLimit: String)  // only when res.headers declared
+    }
+  }
+}
+```
+
+- [ ] **Step 3: Add `'http-stream'` kind emission for Kotlin**
+
+Streams in Kotlin emit the same `path`/`method`/types/`Req` constructs. Yield/return types are emitted as `Yield` and `Return` data classes. The runtime/HTTP layer is consumer-owned (per spec posture). No SSE adapter emission.
+
+- [ ] **Step 4: Update Kotlin snapshot tests**
+
+```bash
+npx vitest run src/codegen/targets/kotlin/run.test.ts -u
+```
+
+Inspect each snapshot diff carefully before accepting.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/codegen/targets/kotlin/
+git commit -m "feat(codegen-kotlin): emit Req/Response namespaces and Response.Headers data class"
+```
+
+---
+
+### Task 31: Swift target — emit `Response.Headers` struct
+
+**Files:**
+- Modify: `src/codegen/targets/swift/run.ts`
+- Modify: `src/codegen/targets/swift/run.test.ts`
+
+- [ ] **Step 1: Mirror Task 30's pattern for Swift**
+
+Emit nested caseless-enum namespaces with `Req.PathParams`, `Req.Query`, `Req.Body`, `Req.Headers`, `Response.Body`, `Response.Headers` structs. Conditional `Response.Headers` only when declared.
+
+```swift
+enum Users {
+  enum GetUser {
+    static let method = "GET"
+    static func path(_ p: PathParams) -> String { return "/users/\(p.id)" }
+    struct PathParams: Codable { let id: String }
+    struct Query: Codable { let include: String? }
+    enum Response {
+      struct Body: Codable { let id: String; let name: String }
+      struct Headers: Codable { let xRateLimit: String; enum CodingKeys: String, CodingKey { case xRateLimit = "x-rate-limit" } }
+    }
+  }
+}
+```
+
+- [ ] **Step 2: Add `'http-stream'` kind emission for Swift**
+
+Same posture as Kotlin — types only, no HTTP/SSE runtime.
+
+- [ ] **Step 3: Update Swift snapshot tests**
+
+```bash
+npx vitest run src/codegen/targets/swift/run.test.ts -u
+```
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add src/codegen/targets/swift/
+git commit -m "feat(codegen-swift): emit Req/Response namespaces and Response.Headers struct"
+```
+
+---
+
+## Phase 10 — Client runtime updates
+
+### Task 32: Add `headers` to `AdapterStreamResponse` and `TypedStream`
+
+**Files:**
+- Modify: `src/client/types.ts`
+
+- [ ] **Step 1: Extend `AdapterStreamResponse` with `headers: Headers`**
+
+Find the `AdapterStreamResponse` interface in `src/client/types.ts` and add:
+
+```ts
+export interface AdapterStreamResponse {
+  // existing fields...
+  headers: Headers   // always populated by the adapter
+}
+```
+
+- [ ] **Step 2: Add optional `.headers` to `TypedStream`**
+
+```ts
+export interface TypedStream<TYield, TReturn> {
+  [Symbol.asyncIterator](): AsyncIterator<TYield>
+  result: Promise<TReturn>
+  headers?: Headers   // populated for routes declaring res.headers
+}
+```
+
+- [ ] **Step 3: Build**
+
+```bash
+npm run build
+```
+
+Expected: errors in `fetch-adapter.ts` (now must populate `.headers`) and `stream.ts` (now must wire `.headers` onto `TypedStream`). Fixed in next tasks.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add src/client/types.ts
+git commit -m "feat(client): add headers to AdapterStreamResponse and TypedStream"
+```
+
+---
+
+### Task 33: Update `fetch-adapter.ts` to populate `AdapterStreamResponse.headers`
+
+**Files:**
+- Modify: `src/client/fetch-adapter.ts`
+- Modify: `src/client/fetch-adapter.test.ts`
+
+- [ ] **Step 1: In `fetch-adapter.ts` `stream()` function, set `headers: response.headers` on the returned `AdapterStreamResponse`**
+
+```ts
+return {
+  // existing fields...
+  headers: response.headers,
+}
+```
+
+- [ ] **Step 2: Add a test asserting headers are propagated**
+
+```ts
+it('propagates response headers to AdapterStreamResponse.headers', async () => {
+  const fetchSpy = vi.fn().mockResolvedValue(
+    new Response('data: x\n\n', {
+      status: 200,
+      headers: { 'x-stream-id': 'abc', 'content-type': 'text/event-stream' },
+    })
+  )
+  const adapter = createFetchAdapter({ fetch: fetchSpy })
+  const result = await adapter.stream({ url: 'https://x', method: 'GET', headers: {} })
+  expect(result.headers.get('x-stream-id')).toBe('abc')
+})
+```
+
+- [ ] **Step 3: Run tests**
+
+```bash
+npx vitest run src/client/fetch-adapter.test.ts
+```
+
+Expected: PASS.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add src/client/fetch-adapter.ts src/client/fetch-adapter.test.ts
+git commit -m "feat(client): populate AdapterStreamResponse.headers in fetch adapter"
+```
+
+---
+
+### Task 34: Update `executeCall` to surface response headers in conditional return
+
+**Files:**
+- Modify: `src/client/call.ts`
+- Modify: `src/client/call.test.ts`
+
+- [ ] **Step 1: Inspect current `executeCall` body**
+
+```bash
+cat src/client/call.ts
+```
+
+Identify where the response body is parsed and returned.
+
+- [ ] **Step 2: Read response headers from the descriptor's metadata**
+
+The descriptor (in `src/client/types.ts`) carries the route's declared shape. Add a `responseHeadersDeclared?: boolean` field on the descriptor (set by codegen — see Task 28). When `true`, `executeCall` returns `{ body, headers }` instead of bare body.
+
+```ts
+// Inside executeCall after parsing the response:
+if (descriptor.responseHeadersDeclared) {
+  return { body: parsedBody, headers: response.headers }
+}
+return parsedBody
+```
+
+(`response.headers` here is the platform `Response.headers` — already a `Headers` object.)
+
+- [ ] **Step 3: Update codegen to emit `responseHeadersDeclared: true` when `slots.responseHeaders` is present**
+
+Back in `emit-scope.ts` (Task 28), include the flag on the descriptor literal. Inspect a generated file to confirm:
+
+```ts
+const descriptor: RouteDescriptor = {
+  kind: 'api',
+  // ...
+  responseHeadersDeclared: true,  // only when res.headers in envelope
+}
+```
+
+- [ ] **Step 4: Add tests for both shapes**
+
+```ts
+it('returns bare body when response headers not declared', async () => {
+  // ...
+  expect(result).toEqual({ id: 'abc' })
+})
+
+it('returns { body, headers } when response headers declared', async () => {
+  // ...
+  expect(result).toEqual({ body: { id: 'abc' }, headers: expect.any(Headers) })
+  expect(result.headers.get('x-rate-limit')).toBe('99')
+})
+```
+
+- [ ] **Step 5: Run tests**
+
+```bash
+npx vitest run src/client/call.test.ts
+```
+
+Expected: PASS.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/client/call.ts src/client/call.test.ts src/client/types.ts src/codegen/emit-scope.ts
+git commit -m "feat(client): surface response headers via descriptor.responseHeadersDeclared flag"
+```
+
+---
+
+### Task 35: Update `executeStream` to wire initial headers onto `TypedStream`
+
+**Files:**
+- Modify: `src/client/stream.ts`
+- Modify: `src/client/stream.test.ts`
+
+- [ ] **Step 1: When constructing the `TypedStream`, set `.headers` from `adapterResponse.headers`**
+
+```ts
+// Inside executeStream, when constructing the TypedStream:
+const typedStream: TypedStream<TYield, TReturn> = {
+  [Symbol.asyncIterator]() { /* ... */ },
+  result: resultPromise,
+  headers: descriptor.responseHeadersDeclared ? adapterResponse.headers : undefined,
+}
+```
+
+- [ ] **Step 2: Add a test**
+
+```ts
+it('TypedStream.headers is populated when route declares res.headers', async () => {
+  // mock adapter to return headers
+  // construct stream
+  // expect stream.headers.get('x-stream-id') === '...'
+})
+```
+
+- [ ] **Step 3: Run tests**
+
+```bash
+npx vitest run src/client/stream.test.ts
+```
+
+Expected: PASS.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add src/client/stream.ts src/client/stream.test.ts
+git commit -m "feat(client): wire initial response headers onto TypedStream.headers"
+```
+
+---
+
+## Phase 11 — Migration polish
+
+### Task 36: Update CLAUDE.md architecture section
+
+**Files:**
+- Modify: `CLAUDE.md`
+
+- [ ] **Step 1: Update the "Schema System" and "Important Patterns" sections to reflect v8**
+
+Replace the `schema.input` / `APIInput` references with the four-creator surface and `req`/`res` shape.
+
+- [ ] **Step 2: Add a "Procedure kinds" section near "Architecture"**
+
+Brief paragraph explaining the four creators and their `kind` discriminants.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add CLAUDE.md
+git commit -m "docs(claude): update architecture for v8 four-creator surface"
+```
+
+---
+
+### Task 37: Update `agent_config/` skills, patterns, and templates
+
+**Files:**
+- Modify: `agent_config/claude-code/skills/ts-procedures/{patterns.md,anti-patterns.md,api-reference.md}`
+- Modify: `agent_config/claude-code/skills/ts-procedures-scaffold/templates/*`
+- Modify: `agent_config/copilot/copilot-instructions.md`
+- Modify: `agent_config/cursor/cursorrules`
+
+- [ ] **Step 1: Replace HTTP examples in `patterns.md` to use `CreateHttp`**
+
+Find all examples using `Procedures<Ctx, APIConfig>().Create(...)` with `schema.input`. Replace with `Procedures<Ctx>().CreateHttp(...)` with `schema.req`.
+
+- [ ] **Step 2: Add an `anti-patterns.md` entry**
+
+```markdown
+## Don't use Create for HTTP routes
+
+Wrong:
+\`\`\`ts
+Procedures<Ctx, APIConfig>().Create('GetUser', { path: '/users/:id', ... })
+\`\`\`
+
+Right:
+\`\`\`ts
+Procedures<Ctx>().CreateHttp('GetUser', { path: '/users/:id', schema: { req: ... } })
+\`\`\`
+
+`Create` is the RPC primitive. HTTP routes belong on `CreateHttp` / `CreateHttpStream`.
+```
+
+- [ ] **Step 3: Update scaffold templates**
+
+Replace `procedure-template.ts`, `hono-rpc-template.ts`, etc. as needed. Add new `create-http.ts` and `create-http-stream.ts` templates.
+
+- [ ] **Step 4: Mirror updates to Copilot and Cursor files**
+
+Both files are condensed equivalents — copy the relevant sections.
+
+- [ ] **Step 5: Run agent_config setup dry-run to verify**
+
+```bash
+node agent_config/bin/setup.mjs --dry-run
+```
+
+Expected: shows what would be installed; no errors.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add agent_config/
+git commit -m "docs(agent_config): update skills/templates for v8 CreateHttp surface"
+```
+
+---
+
+### Task 38: Update CHANGELOG and README
+
+**Files:**
+- Modify: `CHANGELOG.md`
+- Modify: `README.md`
+
+- [ ] **Step 1: Add v8.0.0 entry to CHANGELOG**
+
+```markdown
+## 8.0.0 — 2026-05-08
+
+### Breaking changes
+
+- **`schema.input` removed** from `Create` / `CreateStream`. Use `CreateHttp` / `CreateHttpStream` for per-channel HTTP validation.
+- **HTTP routes use `CreateHttp`**, not `Create` + `APIConfig`. HTTP fields (`path`, `method`, `successStatus`, `scope`, `errors`) are first-class on `CreateHttp` config.
+- **`schema.input.X` → `schema.req.X`** (channels: `pathParams`, `query`, `body`, `headers`).
+- **`APIInput` and `APIConfig` removed.**
+- **`APIHttpRouteDoc.jsonSchema` regrouped under `req` / `res`** — extendProcedureDoc callbacks reading `base.jsonSchema.body` need to read `base.jsonSchema.req.body`.
+- **`Procedures<Ctx, APIConfig>()` → `Procedures<Ctx>()`** for HTTP-only factories.
+- **Generated client flat-mode aliases renamed:** `<Route>Params` → `<Route>ReqPathParams` (and similar). Namespace-mode users get `Users.GetUser.Req.PathParams` automatically.
+
+### New
+
+- **`CreateHttp` / `CreateHttpStream`** — first-class HTTP creators with structured `req` channels and typed `res: { body?, headers? }`.
+- **Conditional return shape** — `CreateHttp` handler returns body bare unless `res.headers` declared, in which case `{ body, headers }`.
+- **`TypedStream.headers`** — initial response headers surfaced on streams that declare `res.headers`.
+- **`kind` discriminant** on every registration (`'rpc' | 'rpc-stream' | 'http' | 'http-stream'`) drives builder routing and `skippedProcedures` warnings.
+
+### Migration
+
+See full table at [docs/superpowers/specs/2026-05-08-create-http-design.md](docs/superpowers/specs/2026-05-08-create-http-design.md#migration). Quick checklist:
+
+1. Replace `Procedures<Ctx, APIConfig>()` with `Procedures<Ctx>()` for HTTP factories.
+2. Replace `Create('Foo', { path, method, schema: { input } }, h)` with `CreateHttp('Foo', { path, method, schema: { req } }, h)`.
+3. Replace `schema.input.X` with `schema.req.X`.
+4. Re-run `npx ts-procedures-codegen` to regenerate clients.
+5. Update flat-mode-alias call sites if applicable.
+```
+
+- [ ] **Step 2: Update README.md headline examples**
+
+Replace any `Create` + `schema.input` example with `CreateHttp` + `schema.req`. Add a new section showcasing response headers.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add CHANGELOG.md README.md
+git commit -m "docs: add v8.0.0 changelog entry and README migration"
+```
+
+---
+
+### Task 39: Bump package version to 8.0.0
+
+**Files:**
+- Modify: `package.json`
+
+- [ ] **Step 1: Update version**
+
+```bash
+npm version 8.0.0 --no-git-tag-version
+```
+
+- [ ] **Step 2: Verify**
+
+```bash
+grep '"version"' package.json
+```
+
+Expected: `"version": "8.0.0"`.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add package.json
+git commit -m "chore: bump version to 8.0.0"
+```
+
+---
+
+### Task 40: Final integration check — build, lint, full test suite
+
+**Files:** none
+
+- [ ] **Step 1: Run full build**
+
+```bash
+npm run build
+```
+
+Expected: green, no warnings.
+
+- [ ] **Step 2: Run lint**
+
+```bash
+npm run lint
+```
+
+Expected: green.
+
+- [ ] **Step 3: Run full test suite**
+
+```bash
+npm run test
+```
+
+Expected: all tests green. Any `it.todo` from Phase 1 (legacy `schema.input` tests) should now either be deleted (if obsolete) or migrated to `CreateHttp` / `CreateHttpStream` equivalents.
+
+- [ ] **Step 4: Address any failures by fixing forward (no skip / no `.todo`)**
+
+- [ ] **Step 5: Commit any final fixes**
+
+```bash
+git add -p
+git commit -m "test: final cleanup of v7 schema.input migrations"
+```
+
+- [ ] **Step 6: Verify clean working tree**
+
+```bash
+git status
+```
+
+Expected: `nothing to commit, working tree clean`.
+
+---
+
+## Self-review notes
+
+Spec coverage check (against `docs/superpowers/specs/2026-05-08-create-http-design.md`):
+
+- ✅ Four-creator surface (Tasks 1-18)
+- ✅ `schema.input` removed from Create/CreateStream (Tasks 7-8)
+- ✅ HTTP fields baked into CreateHttp (Tasks 10-11)
+- ✅ Conditional return shape (Task 14)
+- ✅ Async-preamble for CreateHttpStream initial headers (Task 18)
+- ✅ `kind` discriminant + builder filtering (Tasks 5, 23)
+- ✅ Path-param consistency moved to core (Task 11)
+- ✅ HonoAPIAppBuilder unification serving both http and http-stream (Tasks 19-22)
+- ✅ APIHttpRouteDoc regrouped to req/res (Task 25)
+- ✅ HttpStreamRouteDoc added (Task 25)
+- ✅ Codegen TS namespacing (Req/Response) and conditional return (Task 28)
+- ✅ Codegen Kotlin/Swift Response.Headers (Tasks 30-31)
+- ✅ Client runtime: TypedStream.headers, descriptor.responseHeadersDeclared (Tasks 32-35)
+- ✅ Migration messages on legacy shapes (Tasks 7-8)
+- ✅ CHANGELOG, README, agent_config (Tasks 37-38)
+- ✅ Version bump (Task 39)
+- ✅ Astro adapter (Task 24)
+- ✅ skippedProcedures across all builders (Tasks 20, 23)
+
+No placeholders. Type names consistent across tasks (`THttpProcedureRegistration`, `THttpStreamProcedureRegistration`, `HttpReturn<TRes>`, `HTTP_STREAM_HEADERS_SENTINEL`, `responseHeadersDeclared`).