ts-procedures 5.9.1 → 5.10.2

package/docs/superpowers/plans/2026-03-30-client-codegen.md

@@ -1,2833 +0,0 @@
-# Client Code Generation 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:** Add two new package exports to ts-procedures — `ts-procedures/client` (runtime) and `ts-procedures/codegen` (code generation) — that together produce type-safe, per-scope TypeScript client files from the DocRegistry's JSON output.
-
-**Architecture:** Three layers: (1) additive changes to existing route doc types (`kind` discriminant, optional `scope` on API routes), (2) a zero-dependency runtime client with adapter interface, hook pipeline, and streaming support, (3) a code generation engine using `ajsc` that reads a `DocEnvelope` and emits per-scope `.ts` files with types and callables. CLI wraps the programmatic API.
-
-**Tech Stack:** TypeScript, ajsc (JSON Schema → TS types), vitest (testing), Node.js fs/fetch (codegen I/O)
-
-**Spec:** `docs/superpowers/specs/2026-03-30-client-codegen-design.md`
-
----
-
-## Phase 1: Existing Codebase Changes
-
-These tasks add the `kind` discriminant and optional `scope` to existing types and builders. All changes are additive — no breaking changes.
-
----
-
-### Task 1: Add `kind` and `scope` to Route Doc Types
-
-**Files:**
-- Modify: `src/implementations/types.ts:14-52,78-88`
-- Modify: `src/implementations/http/hono-stream/types.ts:7-17`
-- Test: `src/implementations/http/doc-registry.test.ts`
-
-- [ ] **Step 1: Write failing test — `kind` field required on doc type assignments**
-
-In `src/implementations/http/doc-registry.test.ts`, update the existing fixture declarations (lines ~20-45) to require `kind`. The test will fail because the type doesn't have `kind` yet:
-
-```ts
-describe('kind discriminant', () => {
-  it('rpcDoc fixture requires kind field', () => {
-    // This access will fail TypeScript compilation until kind is on the type
-    const doc = rpcDoc
-    expect(doc.kind).toBe('rpc')
-  })
-
-  it('apiDoc fixture requires kind field', () => {
-    const doc = apiDoc
-    expect(doc.kind).toBe('api')
-  })
-
-  it('streamDoc fixture requires kind field', () => {
-    const doc = streamDoc
-    expect(doc.kind).toBe('stream')
-  })
-
-  it('narrows AnyHttpRouteDoc union via kind', () => {
-    const routes: AnyHttpRouteDoc[] = [rpcDoc, apiDoc, streamDoc]
-    for (const route of routes) {
-      // This property access fails compilation until kind exists on the union
-      expect(route.kind).toBeDefined()
-    }
-  })
-})
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run: `npx vitest run src/implementations/http/doc-registry.test.ts`
-Expected: TypeScript error — Property `kind` does not exist on type `RPCHttpRouteDoc`, runtime test fails with `undefined`
-
-- [ ] **Step 3: Add `kind` to RPCHttpRouteDoc, APIHttpRouteDoc, StreamHttpRouteDoc in types.ts**
-
-In `src/implementations/types.ts`, add `kind` to each interface:
-
-```ts
-// Line 14 — RPCHttpRouteDoc
-export interface RPCHttpRouteDoc extends RPCConfig {
-  kind: 'rpc'
-  name: string
-  path: string
-  method: 'post'
-  jsonSchema: {
-    body?: Record<string, unknown>
-    response?: Record<string, unknown>
-  }
-}
-
-// Line 32 — APIConfig: add optional scope
-export interface APIConfig {
-  path: string
-  method: HttpMethod
-  scope?: string
-  successStatus?: number
-}
-
-// Line 41 — APIHttpRouteDoc
-export interface APIHttpRouteDoc extends APIConfig {
-  kind: 'api'
-  name: string
-  fullPath: string
-  jsonSchema: {
-    pathParams?: Record<string, unknown>
-    query?: Record<string, unknown>
-    body?: Record<string, unknown>
-    headers?: Record<string, unknown>
-    response?: Record<string, unknown>
-  }
-}
-
-// Line 78 — StreamHttpRouteDoc
-export interface StreamHttpRouteDoc extends RPCConfig {
-  kind: 'stream'
-  name: string
-  path: string
-  methods: ('get' | 'post')[]
-  streamMode: StreamMode
-  jsonSchema: {
-    params?: Record<string, unknown>
-    yieldType?: Record<string, unknown>
-    returnType?: Record<string, unknown>
-  }
-}
-```
-
-Also consolidate the duplicate `StreamHttpRouteDoc`: remove the definition from `src/implementations/http/hono-stream/types.ts` and replace it with a re-export from the canonical source:
-
-```ts
-// src/implementations/http/hono-stream/types.ts — replace local definition with:
-export type { StreamHttpRouteDoc } from '../../types.js'
-```
-
-This eliminates the duplication the spec flagged. The hono-stream module still exports the type for its consumers.
-
-- [ ] **Step 4: Update test fixtures to include `kind`**
-
-In `src/implementations/http/doc-registry.test.ts`, update the existing fixtures (lines 20-45) to include the `kind` field:
-
-```ts
-const rpcDoc: RPCHttpRouteDoc = {
-  kind: 'rpc',
-  // ... existing fields
-}
-const apiDoc: APIHttpRouteDoc = {
-  kind: 'api',
-  // ... existing fields
-}
-const streamDoc: StreamHttpRouteDoc = {
-  kind: 'stream',
-  // ... existing fields
-}
-```
-
-- [ ] **Step 5: Run tests to verify they pass**
-
-Run: `npx vitest run src/implementations/http/doc-registry.test.ts`
-Expected: All tests pass including new `kind` tests
-
-- [ ] **Step 6: Commit**
-
-```bash
-git add src/implementations/types.ts src/implementations/http/hono-stream/types.ts src/implementations/http/doc-registry.test.ts
-git commit -m "feat: add kind discriminant and optional scope to route doc types"
-```
-
----
-
-### Task 2: Update Builders to Set `kind`
-
-**Files:**
-- Modify: `src/implementations/http/hono-rpc/index.ts:218-225`
-- Modify: `src/implementations/http/hono-api/index.ts:438-448`
-- Modify: `src/implementations/http/hono-stream/index.ts:414-422`
-- Modify: `src/implementations/http/express-rpc/index.ts:246-253`
-- Test: `src/implementations/http/hono-rpc/index.test.ts`
-- Test: `src/implementations/http/hono-api/index.test.ts`
-- Test: `src/implementations/http/hono-stream/index.test.ts`
-- Test: `src/implementations/http/express-rpc/index.test.ts`
-
-- [ ] **Step 1: Write failing test — HonoRPC builder sets `kind: 'rpc'`**
-
-In `src/implementations/http/hono-rpc/index.test.ts`, add a test that checks the `kind` field in the builder's docs output:
-
-```ts
-it('sets kind: rpc on route docs', () => {
-  // Use the existing builder setup from the test file
-  const docs = builder.docs
-  expect(docs[0].kind).toBe('rpc')
-})
-```
-
-Add similar tests in each builder's test file.
-
-- [ ] **Step 2: Run tests to verify they fail**
-
-Run: `npx vitest run src/implementations/http/hono-rpc/index.test.ts`
-Expected: FAIL — `kind` is undefined
-
-- [ ] **Step 3: Add `kind` to each builder's doc construction**
-
-In `src/implementations/http/hono-rpc/index.ts`, in `buildRpcHttpRouteDoc()` (around line 218), add `kind: 'rpc'` to the base object:
-
-```ts
-const base: RPCHttpRouteDoc = {
-  kind: 'rpc',
-  name: procedure.name,
-  // ... rest unchanged
-}
-```
-
-In `src/implementations/http/hono-api/index.ts`, in `buildApiHttpRouteDoc()` (around line 438), add `kind: 'api'` and pass through `scope`:
-
-```ts
-const base: APIHttpRouteDoc = {
-  kind: 'api',
-  name: procedure.name,
-  // ... rest unchanged
-}
-```
-
-Note: For the API builder, also pass `scope` from the procedure config if present. The `scope` field on `APIConfig` is optional so existing usage without scope still works.
-
-In `src/implementations/http/hono-stream/index.ts`, in `buildStreamHttpRouteDoc()` (around line 414), add `kind: 'stream'`:
-
-```ts
-const base: StreamHttpRouteDoc = {
-  kind: 'stream',
-  name: procedure.name,
-  // ... rest unchanged
-}
-```
-
-In `src/implementations/http/express-rpc/index.ts`, in `buildRpcHttpRouteDoc()` (around line 246), add `kind: 'rpc'`:
-
-```ts
-const base: RPCHttpRouteDoc = {
-  kind: 'rpc',
-  name: procedure.name,
-  // ... rest unchanged
-}
-```
-
-- [ ] **Step 4: Run all builder tests**
-
-Run: `npx vitest run src/implementations/http/`
-Expected: All tests pass
-
-- [ ] **Step 5: Run full test suite to verify no regressions**
-
-Run: `npm run test`
-Expected: All tests pass
-
-- [ ] **Step 6: Commit**
-
-```bash
-git add src/implementations/http/hono-rpc/index.ts src/implementations/http/hono-api/index.ts src/implementations/http/hono-stream/index.ts src/implementations/http/express-rpc/index.ts src/implementations/http/hono-rpc/index.test.ts src/implementations/http/hono-api/index.test.ts src/implementations/http/hono-stream/index.test.ts src/implementations/http/express-rpc/index.test.ts
-git commit -m "feat: set kind field in all HTTP builders"
-```
-
----
-
-## Phase 2: Runtime Client (`ts-procedures/client`)
-
-The client runtime is a zero-dependency module that the generated code imports. Built bottom-up: types → errors → utilities → call/stream → factory.
-
----
-
-### Task 3: Client Types
-
-**Files:**
-- Create: `src/client/types.ts`
-
-- [ ] **Step 1: Create types file with all client interfaces**
-
-Create `src/client/types.ts` with all the types from the spec:
-
-```ts
-// ── Adapter ──────────────────────────────────────────────
-
-export interface ClientAdapter {
-  request(config: AdapterRequest): Promise<AdapterResponse>
-  stream(config: AdapterRequest): Promise<AdapterStreamResponse>
-}
-
-export interface AdapterRequest {
-  url: string
-  method: string
-  headers?: Record<string, string>
-  body?: unknown
-  signal?: AbortSignal
-}
-
-export interface AdapterResponse {
-  status: number
-  headers: Record<string, string>
-  body: unknown
-}
-
-export interface AdapterStreamResponse {
-  status: number
-  headers: Record<string, string>
-  body: AsyncIterable<unknown>
-}
-
-// ── Hooks ────────────────────────────────────────────────
-
-export interface ClientHooks {
-  onBeforeRequest?(context: BeforeRequestContext): BeforeRequestContext | Promise<BeforeRequestContext>
-  onAfterResponse?(context: AfterResponseContext): void | Promise<void>
-  onError?(context: ErrorContext): void | Promise<void>
-}
-
-export interface BeforeRequestContext {
-  procedureName: string
-  scope: string
-  request: AdapterRequest
-}
-
-export interface AfterResponseContext {
-  procedureName: string
-  scope: string
-  request: AdapterRequest
-  response: AdapterResponse
-}
-
-export interface ErrorContext {
-  procedureName: string
-  scope: string
-  request: AdapterRequest
-  error: unknown
-}
-
-// ── Descriptors ──────────────────────────────────────────
-
-export interface CallDescriptor {
-  name: string
-  scope: string
-  path: string
-  method: string
-  kind: 'rpc' | 'api' | 'stream'
-  params: unknown
-}
-
-export interface StreamDescriptor extends CallDescriptor {
-  kind: 'stream'
-  streamMode: 'sse' | 'text'
-}
-
-// ── TypedStream ──────────────────────────────────────────
-
-export interface TypedStream<TYield, TReturn = void> extends AsyncIterable<TYield> {
-  result: Promise<TReturn>
-}
-
-// ── Client Instance ──────────────────────────────────────
-
-export type ProcedureCallOptions = ClientHooks
-
-export interface ClientInstance {
-  basePath: string
-  adapter: ClientAdapter
-  hooks: ClientHooks
-  call<TResponse>(descriptor: CallDescriptor, options?: ProcedureCallOptions): Promise<TResponse>
-  stream<TYield, TReturn>(descriptor: StreamDescriptor, options?: ProcedureCallOptions): TypedStream<TYield, TReturn>
-}
-
-// ── createClient Config ──────────────────────────────────
-
-export interface CreateClientConfig<TScopes> {
-  adapter: ClientAdapter
-  basePath: string
-  scopes: (client: ClientInstance) => TScopes
-  hooks?: ClientHooks
-}
-```
-
-- [ ] **Step 2: Verify the file compiles**
-
-Run: `npx tsc --noEmit src/client/types.ts`
-Expected: No errors
-
-- [ ] **Step 3: Commit**
-
-```bash
-git add src/client/types.ts
-git commit -m "feat: add client runtime type definitions"
-```
-
----
-
-### Task 4: Client Errors
-
-**Files:**
-- Create: `src/client/errors.ts`
-- Test: `src/client/errors.test.ts`
-
-- [ ] **Step 1: Write failing test**
-
-Create `src/client/errors.test.ts`:
-
-```ts
-import { describe, it, expect } from 'vitest'
-import { ClientRequestError, ClientPathParamError } from './errors.js'
-
-describe('ClientRequestError', () => {
-  it('includes status, headers, and body', () => {
-    const err = new ClientRequestError({
-      status: 401,
-      headers: { 'x-request-id': 'abc' },
-      body: { message: 'Unauthorized' },
-      procedureName: 'GetUser',
-      scope: 'users',
-    })
-    expect(err).toBeInstanceOf(Error)
-    expect(err.name).toBe('ClientRequestError')
-    expect(err.status).toBe(401)
-    expect(err.headers['x-request-id']).toBe('abc')
-    expect(err.body).toEqual({ message: 'Unauthorized' })
-    expect(err.procedureName).toBe('GetUser')
-    expect(err.scope).toBe('users')
-    expect(err.message).toBe('GetUser (users) failed with status 401')
-  })
-})
-
-describe('ClientPathParamError', () => {
-  it('reports missing param', () => {
-    const err = new ClientPathParamError('id', '/users/:id', 'GetUser')
-    expect(err).toBeInstanceOf(Error)
-    expect(err.name).toBe('ClientPathParamError')
-    expect(err.message).toContain('id')
-    expect(err.message).toContain('/users/:id')
-  })
-})
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run: `npx vitest run src/client/errors.test.ts`
-Expected: FAIL — module not found
-
-- [ ] **Step 3: Implement errors**
-
-Create `src/client/errors.ts`:
-
-```ts
-export class ClientRequestError extends Error {
-  readonly name = 'ClientRequestError'
-  readonly status: number
-  readonly headers: Record<string, string>
-  readonly body: unknown
-  readonly procedureName: string
-  readonly scope: string
-
-  constructor(opts: {
-    status: number
-    headers: Record<string, string>
-    body: unknown
-    procedureName: string
-    scope: string
-  }) {
-    super(`${opts.procedureName} (${opts.scope}) failed with status ${opts.status}`)
-    this.status = opts.status
-    this.headers = opts.headers
-    this.body = opts.body
-    this.procedureName = opts.procedureName
-    this.scope = opts.scope
-  }
-}
-
-export class ClientPathParamError extends Error {
-  readonly name = 'ClientPathParamError'
-
-  constructor(param: string, path: string, procedureName: string) {
-    super(`Missing path parameter "${param}" in "${path}" for procedure ${procedureName}`)
-  }
-}
-
-export class ClientStreamError extends Error {
-  readonly name = 'ClientStreamError'
-  readonly procedureName: string
-  readonly scope: string
-
-  constructor(message: string, procedureName: string, scope: string) {
-    super(message)
-    this.procedureName = procedureName
-    this.scope = scope
-  }
-}
-```
-
-- [ ] **Step 4: Run test to verify it passes**
-
-Run: `npx vitest run src/client/errors.test.ts`
-Expected: PASS
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add src/client/errors.ts src/client/errors.test.ts
-git commit -m "feat: add client error classes"
-```
-
----
-
-### Task 5: Path Interpolation and Request Building
-
-**Files:**
-- Create: `src/client/request-builder.ts`
-- Test: `src/client/request-builder.test.ts`
-
-- [ ] **Step 1: Write failing tests**
-
-Create `src/client/request-builder.test.ts`:
-
-```ts
-import { describe, it, expect } from 'vitest'
-import { interpolatePath, buildAdapterRequest } from './request-builder.js'
-
-describe('interpolatePath', () => {
-  it('replaces :param with values', () => {
-    expect(interpolatePath('/users/:id', { id: '123' }, 'GetUser')).toBe('/users/123')
-  })
-
-  it('handles multiple params', () => {
-    expect(interpolatePath('/users/:userId/posts/:postId', { userId: 'a', postId: 'b' }, 'GetPost')).toBe('/users/a/posts/b')
-  })
-
-  it('URI-encodes values', () => {
-    expect(interpolatePath('/search/:q', { q: 'hello world' }, 'Search')).toBe('/search/hello%20world')
-  })
-
-  it('throws on missing param with procedure name', () => {
-    expect(() => interpolatePath('/users/:id', {}, 'GetUser')).toThrow('id')
-    expect(() => interpolatePath('/users/:id', {}, 'GetUser')).toThrow('GetUser')
-  })
-
-  it('returns path unchanged when no params needed', () => {
-    expect(interpolatePath('/health', {}, 'Health')).toBe('/health')
-  })
-})
-
-describe('buildAdapterRequest', () => {
-  it('builds RPC request — body params, POST', () => {
-    const req = buildAdapterRequest('http://api.com', {
-      name: 'CreateUser',
-      scope: 'users',
-      path: '/users/CreateUser/1',
-      method: 'post',
-      kind: 'rpc',
-      params: { name: 'Alice' },
-    })
-    expect(req.url).toBe('http://api.com/users/CreateUser/1')
-    expect(req.method).toBe('post')
-    expect(req.body).toEqual({ name: 'Alice' })
-    expect(req.headers?.['content-type']).toBe('application/json')
-  })
-
-  it('builds API request — structured params with pathParams, query, body, headers', () => {
-    const req = buildAdapterRequest('http://api.com', {
-      name: 'UpdateUser',
-      scope: 'users',
-      path: '/users/:id',
-      method: 'put',
-      kind: 'api',
-      params: {
-        pathParams: { id: '123' },
-        query: { notify: 'true' },
-        body: { name: 'Bob' },
-        headers: { 'x-custom': 'val' },
-      },
-    })
-    expect(req.url).toBe('http://api.com/users/123?notify=true')
-    expect(req.method).toBe('put')
-    expect(req.body).toEqual({ name: 'Bob' })
-    expect(req.headers?.['x-custom']).toBe('val')
-    expect(req.headers?.['content-type']).toBe('application/json')
-  })
-
-  it('builds API request — GET with query only, no body', () => {
-    const req = buildAdapterRequest('http://api.com', {
-      name: 'GetUser',
-      scope: 'users',
-      path: '/users/:id',
-      method: 'get',
-      kind: 'api',
-      params: {
-        pathParams: { id: '42' },
-        query: { include: 'posts' },
-      },
-    })
-    expect(req.url).toBe('http://api.com/users/42?include=posts')
-    expect(req.method).toBe('get')
-    expect(req.body).toBeUndefined()
-  })
-
-  it('treats RPC params with body/query keys as flat params, not structured', () => {
-    const req = buildAdapterRequest('http://api.com', {
-      name: 'Simple',
-      scope: 'test',
-      path: '/test/Simple/1',
-      method: 'post',
-      kind: 'rpc',
-      params: { body: 'some content', query: 'search term' },
-    })
-    // kind: 'rpc' → always flat body params regardless of key names
-    expect(req.body).toEqual({ body: 'some content', query: 'search term' })
-  })
-})
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run: `npx vitest run src/client/request-builder.test.ts`
-Expected: FAIL — module not found
-
-- [ ] **Step 3: Implement request builder**
-
-Create `src/client/request-builder.ts`:
-
-```ts
-import { ClientPathParamError } from './errors.js'
-import type { AdapterRequest, CallDescriptor } from './types.js'
-
-export function interpolatePath(path: string, params: Record<string, string>, procedureName: string): string {
-  return path.replace(/:([a-zA-Z_][a-zA-Z0-9_]*)/g, (match, name) => {
-    if (!(name in params)) {
-      throw new ClientPathParamError(name, path, procedureName)
-    }
-    return encodeURIComponent(params[name])
-  })
-}
-
-export function buildAdapterRequest(basePath: string, descriptor: CallDescriptor): AdapterRequest {
-  const { path, method, params, kind, name } = descriptor
-
-  if (kind === 'api') {
-    const structured = params as {
-      pathParams?: Record<string, string>
-      query?: Record<string, string>
-      body?: unknown
-      headers?: Record<string, string>
-    } | undefined
-    const resolvedPath = structured?.pathParams
-      ? interpolatePath(path, structured.pathParams, name)
-      : path
-
-    const queryString = structured?.query
-      ? '?' + new URLSearchParams(structured.query as Record<string, string>).toString()
-      : ''
-
-    const headers: Record<string, string> = {
-      ...(structured?.headers ?? {}),
-    }
-
-    let body: unknown = undefined
-    if (structured?.body !== undefined) {
-      headers['content-type'] = 'application/json'
-      body = structured.body
-    }
-
-    return {
-      url: `${basePath}${resolvedPath}${queryString}`,
-      method,
-      headers: Object.keys(headers).length > 0 ? headers : undefined,
-      body,
-    }
-  }
-
-  // Flat params → body (RPC/Stream style)
-  return {
-    url: `${basePath}${path}`,
-    method,
-    headers: params !== undefined ? { 'content-type': 'application/json' } : undefined,
-    body: params ?? undefined,
-  }
-}
-```
-
-- [ ] **Step 4: Run test to verify it passes**
-
-Run: `npx vitest run src/client/request-builder.test.ts`
-Expected: PASS
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add src/client/request-builder.ts src/client/request-builder.test.ts
-git commit -m "feat: add path interpolation and request builder"
-```
-
----
-
-### Task 6: Hook Pipeline
-
-**Files:**
-- Create: `src/client/hooks.ts`
-- Test: `src/client/hooks.test.ts`
-
-- [ ] **Step 1: Write failing tests**
-
-Create `src/client/hooks.test.ts`:
-
-```ts
-import { describe, it, expect, vi } from 'vitest'
-import { runBeforeRequest, runAfterResponse, runOnError } from './hooks.js'
-import type { BeforeRequestContext, AfterResponseContext, ClientHooks } from './types.js'
-
-describe('runBeforeRequest', () => {
-  it('runs global then per-procedure hooks in order', async () => {
-    const order: string[] = []
-    const global: ClientHooks = {
-      onBeforeRequest(ctx) { order.push('global'); return ctx },
-    }
-    const local: ClientHooks = {
-      onBeforeRequest(ctx) { order.push('local'); return ctx },
-    }
-    const ctx: BeforeRequestContext = {
-      procedureName: 'Test',
-      scope: 'test',
-      request: { url: '/test', method: 'get' },
-    }
-    await runBeforeRequest(ctx, global, local)
-    expect(order).toEqual(['global', 'local'])
-  })
-
-  it('passes mutated context from global to local', async () => {
-    const global: ClientHooks = {
-      onBeforeRequest(ctx) {
-        ctx.request.headers = { Authorization: 'Bearer token' }
-        return ctx
-      },
-    }
-    const local: ClientHooks = {
-      onBeforeRequest(ctx) {
-        expect(ctx.request.headers?.Authorization).toBe('Bearer token')
-        return ctx
-      },
-    }
-    const ctx: BeforeRequestContext = {
-      procedureName: 'Test',
-      scope: 'test',
-      request: { url: '/test', method: 'get' },
-    }
-    const result = await runBeforeRequest(ctx, global, local)
-    expect(result.request.headers?.Authorization).toBe('Bearer token')
-  })
-
-  it('handles async hooks', async () => {
-    const global: ClientHooks = {
-      async onBeforeRequest(ctx) {
-        return ctx
-      },
-    }
-    const ctx: BeforeRequestContext = {
-      procedureName: 'Test',
-      scope: 'test',
-      request: { url: '/test', method: 'get' },
-    }
-    const result = await runBeforeRequest(ctx, global, undefined)
-    expect(result).toBe(ctx)
-  })
-
-  it('skips undefined hooks gracefully', async () => {
-    const ctx: BeforeRequestContext = {
-      procedureName: 'Test',
-      scope: 'test',
-      request: { url: '/test', method: 'get' },
-    }
-    const result = await runBeforeRequest(ctx, {}, undefined)
-    expect(result).toBe(ctx)
-  })
-})
-
-describe('runAfterResponse', () => {
-  it('runs global then per-procedure hooks', async () => {
-    const order: string[] = []
-    const global: ClientHooks = {
-      onAfterResponse() { order.push('global') },
-    }
-    const local: ClientHooks = {
-      onAfterResponse() { order.push('local') },
-    }
-    const ctx: AfterResponseContext = {
-      procedureName: 'Test',
-      scope: 'test',
-      request: { url: '/test', method: 'get' },
-      response: { status: 200, headers: {}, body: {} },
-    }
-    await runAfterResponse(ctx, global, local)
-    expect(order).toEqual(['global', 'local'])
-  })
-})
-
-describe('runOnError', () => {
-  it('calls global then local onError', async () => {
-    const order: string[] = []
-    const global: ClientHooks = {
-      onError() { order.push('global') },
-    }
-    const local: ClientHooks = {
-      onError() { order.push('local') },
-    }
-    await runOnError(
-      { procedureName: 'Test', scope: 'test', request: { url: '/test', method: 'get' }, error: new Error('fail') },
-      global,
-      local,
-    )
-    expect(order).toEqual(['global', 'local'])
-  })
-})
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run: `npx vitest run src/client/hooks.test.ts`
-Expected: FAIL — module not found
-
-- [ ] **Step 3: Implement hook pipeline**
-
-Create `src/client/hooks.ts`:
-
-```ts
-import type { BeforeRequestContext, AfterResponseContext, ErrorContext, ClientHooks } from './types.js'
-
-export async function runBeforeRequest(
-  ctx: BeforeRequestContext,
-  global: ClientHooks,
-  local: ClientHooks | undefined,
-): Promise<BeforeRequestContext> {
-  let result = ctx
-  if (global.onBeforeRequest) {
-    result = await global.onBeforeRequest(result)
-  }
-  if (local?.onBeforeRequest) {
-    result = await local.onBeforeRequest(result)
-  }
-  return result
-}
-
-export async function runAfterResponse(
-  ctx: AfterResponseContext,
-  global: ClientHooks,
-  local: ClientHooks | undefined,
-): Promise<void> {
-  if (global.onAfterResponse) {
-    await global.onAfterResponse(ctx)
-  }
-  if (local?.onAfterResponse) {
-    await local.onAfterResponse(ctx)
-  }
-}
-
-export async function runOnError(
-  ctx: ErrorContext,
-  global: ClientHooks,
-  local: ClientHooks | undefined,
-): Promise<void> {
-  if (global.onError) {
-    await global.onError(ctx)
-  }
-  if (local?.onError) {
-    await local.onError(ctx)
-  }
-}
-```
-
-- [ ] **Step 4: Run test to verify it passes**
-
-Run: `npx vitest run src/client/hooks.test.ts`
-Expected: PASS
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add src/client/hooks.ts src/client/hooks.test.ts
-git commit -m "feat: add client hook pipeline"
-```
-
----
-
-### Task 7: call() Implementation
-
-**Files:**
-- Create: `src/client/call.ts`
-- Test: `src/client/call.test.ts`
-
-- [ ] **Step 1: Write failing tests**
-
-Create `src/client/call.test.ts`:
-
-```ts
-import { describe, it, expect, vi } from 'vitest'
-import { executeCall } from './call.js'
-import type { ClientAdapter, ClientHooks, CallDescriptor } from './types.js'
-
-function makeAdapter(response = { status: 200, headers: {}, body: { id: '1' } }): ClientAdapter {
-  return {
-    request: vi.fn().mockResolvedValue(response),
-    stream: vi.fn(),
-  }
-}
-
-const descriptor: CallDescriptor = {
-  name: 'GetUser',
-  scope: 'users',
-  path: '/users/GetUser/1',
-  method: 'post',
-  kind: 'rpc',
-  params: { id: '1' },
-}
-
-describe('executeCall', () => {
-  it('calls adapter.request and returns body', async () => {
-    const adapter = makeAdapter()
-    const result = await executeCall('http://api.com', adapter, {}, descriptor, undefined)
-    expect(result).toEqual({ id: '1' })
-    expect(adapter.request).toHaveBeenCalledOnce()
-  })
-
-  it('throws ClientRequestError on non-2xx', async () => {
-    const adapter = makeAdapter({ status: 404, headers: {}, body: { error: 'not found' } })
-    await expect(executeCall('http://api.com', adapter, {}, descriptor, undefined))
-      .rejects.toThrow('GetUser (users) failed with status 404')
-  })
-
-  it('runs onBeforeRequest hook before calling adapter', async () => {
-    const adapter = makeAdapter()
-    const hooks: ClientHooks = {
-      onBeforeRequest(ctx) {
-        ctx.request.headers = { ...ctx.request.headers, Authorization: 'Bearer test' }
-        return ctx
-      },
-    }
-    await executeCall('http://api.com', adapter, hooks, descriptor, undefined)
-    const calledWith = (adapter.request as ReturnType<typeof vi.fn>).mock.calls[0][0]
-    expect(calledWith.headers?.Authorization).toBe('Bearer test')
-  })
-
-  it('runs onAfterResponse hook after receiving response', async () => {
-    const adapter = makeAdapter()
-    const captured: unknown[] = []
-    const hooks: ClientHooks = {
-      onAfterResponse(ctx) { captured.push(ctx.response.body) },
-    }
-    await executeCall('http://api.com', adapter, hooks, descriptor, undefined)
-    expect(captured).toEqual([{ id: '1' }])
-  })
-
-  it('does not throw when onAfterResponse hook handles non-2xx', async () => {
-    const adapter = makeAdapter({ status: 500, headers: {}, body: { error: 'internal' } })
-    const hooks: ClientHooks = {
-      onAfterResponse(ctx) {
-        // Hook swallows the error by setting status to 200
-        ctx.response.status = 200
-      },
-    }
-    const result = await executeCall('http://api.com', adapter, hooks, descriptor, undefined)
-    expect(result).toEqual({ error: 'internal' })
-  })
-})
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run: `npx vitest run src/client/call.test.ts`
-Expected: FAIL — module not found
-
-- [ ] **Step 3: Implement executeCall**
-
-Create `src/client/call.ts`:
-
-```ts
-import { ClientRequestError } from './errors.js'
-import { runBeforeRequest, runAfterResponse, runOnError } from './hooks.js'
-import { buildAdapterRequest } from './request-builder.js'
-import type { ClientAdapter, ClientHooks, CallDescriptor, ProcedureCallOptions } from './types.js'
-
-export async function executeCall<TResponse>(
-  basePath: string,
-  adapter: ClientAdapter,
-  globalHooks: ClientHooks,
-  descriptor: CallDescriptor,
-  options: ProcedureCallOptions | undefined,
-): Promise<TResponse> {
-  const initialRequest = buildAdapterRequest(basePath, descriptor)
-
-  const { request } = await runBeforeRequest(
-    { procedureName: descriptor.name, scope: descriptor.scope, request: initialRequest },
-    globalHooks,
-    options,
-  )
-
-  let response
-  try {
-    response = await adapter.request(request)
-  } catch (error) {
-    await runOnError(
-      { procedureName: descriptor.name, scope: descriptor.scope, request, error },
-      globalHooks,
-      options,
-    )
-    throw error
-  }
-
-  await runAfterResponse(
-    { procedureName: descriptor.name, scope: descriptor.scope, request, response },
-    globalHooks,
-    options,
-  )
-
-  if (response.status < 200 || response.status >= 300) {
-    throw new ClientRequestError({
-      status: response.status,
-      headers: response.headers,
-      body: response.body,
-      procedureName: descriptor.name,
-      scope: descriptor.scope,
-    })
-  }
-
-  return response.body as TResponse
-}
-```
-
-- [ ] **Step 4: Run test to verify it passes**
-
-Run: `npx vitest run src/client/call.test.ts`
-Expected: PASS
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add src/client/call.ts src/client/call.test.ts
-git commit -m "feat: add client call execution with hook pipeline"
-```
-
----
-
-### Task 8: stream() Implementation
-
-**Files:**
-- Create: `src/client/stream.ts`
-- Test: `src/client/stream.test.ts`
-
-- [ ] **Step 1: Write failing tests**
-
-Create `src/client/stream.test.ts`:
-
-```ts
-import { describe, it, expect, vi } from 'vitest'
-import { executeStream, createTypedStream } from './stream.js'
-import type { ClientAdapter, ClientHooks, StreamDescriptor } from './types.js'
-
-async function* mockSSEStream() {
-  yield { data: { id: '1', message: 'hello' }, event: 'message', id: '1' }
-  yield { data: { id: '2', message: 'world' }, event: 'message', id: '2' }
-  yield { data: { total: 2 }, event: 'return', id: '3' }
-}
-
-async function* mockTextStream() {
-  yield 'chunk1'
-  yield 'chunk2'
-}
-
-function makeStreamAdapter(body: AsyncIterable<unknown>): ClientAdapter {
-  return {
-    request: vi.fn(),
-    stream: vi.fn().mockResolvedValue({ status: 200, headers: {}, body }),
-  }
-}
-
-const sseDescriptor: StreamDescriptor = {
-  name: 'WatchNotifications',
-  scope: 'notifications',
-  path: '/notifications/WatchNotifications/1',
-  method: 'post',
-  kind: 'stream',
-  params: { accountId: 'abc' },
-  streamMode: 'sse',
-}
-
-describe('createTypedStream (SSE)', () => {
-  it('yields data payloads, captures return', async () => {
-    const stream = createTypedStream(mockSSEStream(), 'sse')
-    const yields: unknown[] = []
-    for await (const item of stream) {
-      yields.push(item)
-    }
-    expect(yields).toEqual([
-      { id: '1', message: 'hello' },
-      { id: '2', message: 'world' },
-    ])
-    expect(await stream.result).toEqual({ total: 2 })
-  })
-})
-
-describe('createTypedStream (text)', () => {
-  it('yields text chunks, result is void', async () => {
-    const stream = createTypedStream(mockTextStream(), 'text')
-    const yields: unknown[] = []
-    for await (const item of stream) {
-      yields.push(item)
-    }
-    expect(yields).toEqual(['chunk1', 'chunk2'])
-    expect(await stream.result).toBeUndefined()
-  })
-})
-
-describe('executeStream', () => {
-  it('calls adapter.stream and returns TypedStream', async () => {
-    const adapter = makeStreamAdapter(mockSSEStream())
-    const stream = await executeStream('http://api.com', adapter, {}, sseDescriptor, undefined)
-    const yields: unknown[] = []
-    for await (const item of stream) {
-      yields.push(item)
-    }
-    expect(yields).toHaveLength(2)
-    expect(adapter.stream).toHaveBeenCalledOnce()
-  })
-
-  it('runs onBeforeRequest and onAfterResponse hooks', async () => {
-    const adapter = makeStreamAdapter(mockSSEStream())
-    const order: string[] = []
-    const hooks: ClientHooks = {
-      onBeforeRequest(ctx) { order.push('before'); return ctx },
-      onAfterResponse() { order.push('after') },
-    }
-    const stream = await executeStream('http://api.com', adapter, hooks, sseDescriptor, undefined)
-    // Consume the stream to avoid hanging
-    for await (const _ of stream) { /* noop */ }
-    expect(order).toEqual(['before', 'after'])
-  })
-
-  it('throws on non-2xx status', async () => {
-    const adapter: ClientAdapter = {
-      request: vi.fn(),
-      stream: vi.fn().mockResolvedValue({
-        status: 401,
-        headers: {},
-        body: (async function* () {})(),
-      }),
-    }
-    await expect(executeStream('http://api.com', adapter, {}, sseDescriptor, undefined))
-      .rejects.toThrow('WatchNotifications (notifications) failed with status 401')
-  })
-})
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run: `npx vitest run src/client/stream.test.ts`
-Expected: FAIL — module not found
-
-- [ ] **Step 3: Implement stream execution**
-
-Create `src/client/stream.ts`:
-
-```ts
-import { ClientRequestError } from './errors.js'
-import { runBeforeRequest, runAfterResponse, runOnError } from './hooks.js'
-import { buildAdapterRequest } from './request-builder.js'
-import type { ClientAdapter, ClientHooks, StreamDescriptor, ProcedureCallOptions, TypedStream } from './types.js'
-
-export function createTypedStream<TYield, TReturn>(
-  source: AsyncIterable<unknown>,
-  streamMode: 'sse' | 'text',
-): TypedStream<TYield, TReturn> {
-  let resolveResult: (value: TReturn) => void
-  let rejectResult: (error: unknown) => void
-  const resultPromise = new Promise<TReturn>((resolve, reject) => {
-    resolveResult = resolve
-    rejectResult = reject
-  })
-
-  async function* iterate(): AsyncGenerator<TYield> {
-    try {
-      for await (const event of source) {
-        if (streamMode === 'sse') {
-          const sseEvent = event as { data: unknown; event?: string; id?: string }
-          if (sseEvent.event === 'return') {
-            resolveResult!(sseEvent.data as TReturn)
-            continue
-          }
-          yield sseEvent.data as TYield
-        } else {
-          yield event as TYield
-        }
-      }
-      // Stream completed without a return event
-      if (streamMode === 'text') {
-        resolveResult!(undefined as TReturn)
-      } else {
-        // SSE without return event — resolve with undefined
-        resolveResult!(undefined as TReturn)
-      }
-    } catch (error) {
-      rejectResult!(error)
-      throw error
-    }
-  }
-
-  const iterable = iterate()
-
-  return {
-    [Symbol.asyncIterator]() { return iterable },
-    result: resultPromise,
-  }
-}
-
-export async function executeStream<TYield, TReturn>(
-  basePath: string,
-  adapter: ClientAdapter,
-  globalHooks: ClientHooks,
-  descriptor: StreamDescriptor,
-  options: ProcedureCallOptions | undefined,
-): Promise<TypedStream<TYield, TReturn>> {
-  const initialRequest = buildAdapterRequest(basePath, descriptor)
-
-  const { request } = await runBeforeRequest(
-    { procedureName: descriptor.name, scope: descriptor.scope, request: initialRequest },
-    globalHooks,
-    options,
-  )
-
-  let streamResponse
-  try {
-    streamResponse = await adapter.stream(request)
-  } catch (error) {
-    await runOnError(
-      { procedureName: descriptor.name, scope: descriptor.scope, request, error },
-      globalHooks,
-      options,
-    )
-    throw error
-  }
-
-  // Fire onAfterResponse immediately with initial HTTP response
-  await runAfterResponse(
-    {
-      procedureName: descriptor.name,
-      scope: descriptor.scope,
-      request,
-      response: { status: streamResponse.status, headers: streamResponse.headers, body: null },
-    },
-    globalHooks,
-    options,
-  )
-
-  if (streamResponse.status < 200 || streamResponse.status >= 300) {
-    throw new ClientRequestError({
-      status: streamResponse.status,
-      headers: streamResponse.headers,
-      body: null,
-      procedureName: descriptor.name,
-      scope: descriptor.scope,
-    })
-  }
-
-  return createTypedStream<TYield, TReturn>(streamResponse.body, descriptor.streamMode)
-}
-```
-
-- [ ] **Step 4: Run test to verify it passes**
-
-Run: `npx vitest run src/client/stream.test.ts`
-Expected: PASS
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add src/client/stream.ts src/client/stream.test.ts
-git commit -m "feat: add client stream execution with SSE parsing"
-```
-
----
-
-### Task 9: createClient Factory and Client Index
-
-**Files:**
-- Create: `src/client/index.ts`
-- Test: `src/client/index.test.ts`
-
-- [ ] **Step 1: Write failing tests**
-
-Create `src/client/index.test.ts`:
-
-```ts
-import { describe, it, expect, vi } from 'vitest'
-import { createClient } from './index.js'
-import type { ClientAdapter, ClientInstance } from './types.js'
-
-function makeAdapter(): ClientAdapter {
-  return {
-    request: vi.fn().mockResolvedValue({ status: 200, headers: {}, body: { ok: true } }),
-    stream: vi.fn(),
-  }
-}
-
-function mockScopes(client: ClientInstance) {
-  return {
-    users: {
-      GetUser(params: { id: string }) {
-        return client.call({ name: 'GetUser', scope: 'users', path: '/users/GetUser/1', method: 'post', kind: 'rpc', params })
-      },
-    },
-  }
-}
-
-describe('createClient', () => {
-  it('creates a client with typed scope callables', async () => {
-    const client = createClient({
-      adapter: makeAdapter(),
-      basePath: 'http://localhost:3000/api',
-      scopes: mockScopes,
-    })
-    expect(client.users).toBeDefined()
-    expect(typeof client.users.GetUser).toBe('function')
-  })
-
-  it('executes procedure calls through the adapter', async () => {
-    const adapter = makeAdapter()
-    const client = createClient({
-      adapter,
-      basePath: 'http://localhost:3000/api',
-      scopes: mockScopes,
-    })
-    const result = await client.users.GetUser({ id: '1' })
-    expect(result).toEqual({ ok: true })
-    expect(adapter.request).toHaveBeenCalledOnce()
-  })
-
-  it('supports streaming via client.stream()', async () => {
-    const adapter: ClientAdapter = {
-      request: vi.fn(),
-      stream: vi.fn().mockResolvedValue({
-        status: 200,
-        headers: {},
-        body: (async function* () {
-          yield { data: { msg: 'hi' }, event: 'message', id: '1' }
-          yield { data: { total: 1 }, event: 'return', id: '2' }
-        })(),
-      }),
-    }
-    function streamScopes(client: ClientInstance) {
-      return {
-        events: {
-          Watch(params: { filter: string }) {
-            return client.stream({ name: 'Watch', scope: 'events', path: '/events/Watch/1', method: 'post', kind: 'stream', streamMode: 'sse', params })
-          },
-        },
-      }
-    }
-    const client = createClient({ adapter, basePath: 'http://localhost:3000/api', scopes: streamScopes })
-    const stream = client.events.Watch({ filter: 'all' })
-    const yields: unknown[] = []
-    for await (const item of stream) { yields.push(item) }
-    expect(yields).toEqual([{ msg: 'hi' }])
-    expect(await stream.result).toEqual({ total: 1 })
-  })
-
-  it('applies global hooks to all calls', async () => {
-    const adapter = makeAdapter()
-    const captured: string[] = []
-    const client = createClient({
-      adapter,
-      basePath: 'http://localhost:3000/api',
-      scopes: mockScopes,
-      hooks: {
-        onBeforeRequest(ctx) {
-          captured.push(ctx.procedureName)
-          return ctx
-        },
-      },
-    })
-    await client.users.GetUser({ id: '1' })
-    expect(captured).toEqual(['GetUser'])
-  })
-})
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run: `npx vitest run src/client/index.test.ts`
-Expected: FAIL — module not found
-
-- [ ] **Step 3: Implement createClient and barrel exports**
-
-Create `src/client/index.ts`:
-
-```ts
-import { executeCall } from './call.js'
-import { executeStream } from './stream.js'
-import type {
-  CreateClientConfig,
-  ClientInstance,
-  CallDescriptor,
-  StreamDescriptor,
-  ProcedureCallOptions,
-  TypedStream,
-} from './types.js'
-
-export function createClient<TScopes>(config: CreateClientConfig<TScopes>): TScopes {
-  const { adapter, basePath, hooks = {}, scopes } = config
-
-  const instance: ClientInstance = {
-    basePath,
-    adapter,
-    hooks,
-    call<TResponse>(descriptor: CallDescriptor, options?: ProcedureCallOptions): Promise<TResponse> {
-      return executeCall<TResponse>(basePath, adapter, hooks, descriptor, options)
-    },
-    stream<TYield, TReturn>(descriptor: StreamDescriptor, options?: ProcedureCallOptions): TypedStream<TYield, TReturn> {
-      // executeStream is async but we need to return TypedStream synchronously-ish
-      // We create a deferred stream that starts executing immediately
-      let streamPromise = executeStream<TYield, TReturn>(basePath, adapter, hooks, descriptor, options)
-
-      let resolveResult: (value: TReturn) => void
-      let rejectResult: (error: unknown) => void
-      const resultPromise = new Promise<TReturn>((resolve, reject) => {
-        resolveResult = resolve
-        rejectResult = reject
-      })
-
-      async function* iterate(): AsyncGenerator<TYield> {
-        const typedStream = await streamPromise
-        typedStream.result.then(resolveResult!, rejectResult!)
-        yield* typedStream
-      }
-
-      const iterable = iterate()
-      return {
-        [Symbol.asyncIterator]() { return iterable },
-        result: resultPromise,
-      }
-    },
-  }
-
-  return scopes(instance)
-}
-
-// Re-export all public types
-export type {
-  ClientAdapter,
-  AdapterRequest,
-  AdapterResponse,
-  AdapterStreamResponse,
-  ClientHooks,
-  BeforeRequestContext,
-  AfterResponseContext,
-  ErrorContext,
-  CallDescriptor,
-  StreamDescriptor,
-  TypedStream,
-  ProcedureCallOptions,
-  ClientInstance,
-  CreateClientConfig,
-} from './types.js'
-
-// Re-export errors
-export { ClientRequestError, ClientPathParamError, ClientStreamError } from './errors.js'
-```
-
-- [ ] **Step 4: Run test to verify it passes**
-
-Run: `npx vitest run src/client/index.test.ts`
-Expected: PASS
-
-- [ ] **Step 5: Run all client tests**
-
-Run: `npx vitest run src/client/`
-Expected: All pass
-
-- [ ] **Step 6: Commit**
-
-```bash
-git add src/client/index.ts src/client/index.test.ts
-git commit -m "feat: add createClient factory and client barrel exports"
-```
-
----
-
-## Phase 3: Code Generation Engine (`ts-procedures/codegen`)
-
-Built bottom-up: envelope resolution → scope grouping → type emission → scope file emission → index emission → pipeline → public API → CLI.
-
----
-
-### Task 10: Resolve Envelope
-
-**Files:**
-- Create: `src/codegen/resolve-envelope.ts`
-- Test: `src/codegen/resolve-envelope.test.ts`
-
-- [ ] **Step 1: Write failing tests**
-
-Create `src/codegen/resolve-envelope.test.ts`:
-
-```ts
-import { describe, it, expect } from 'vitest'
-import { resolveEnvelope } from './resolve-envelope.js'
-import type { DocEnvelope } from '../implementations/types.js'
-import { writeFileSync, mkdirSync, rmSync } from 'node:fs'
-import { join } from 'node:path'
-import { tmpdir } from 'node:os'
-
-const fixture: DocEnvelope = {
-  basePath: '/api',
-  headers: [],
-  errors: [],
-  routes: [
-    { kind: 'rpc', name: 'GetUser', path: '/users/GetUser/1', method: 'post', scope: 'users', version: 1, jsonSchema: {} },
-  ],
-}
-
-describe('resolveEnvelope', () => {
-  it('accepts a DocEnvelope object directly', async () => {
-    const result = await resolveEnvelope({ envelope: fixture })
-    expect(result.basePath).toBe('/api')
-    expect(result.routes).toHaveLength(1)
-  })
-
-  it('reads from a JSON file', async () => {
-    const dir = join(tmpdir(), 'ts-proc-test-' + Date.now())
-    mkdirSync(dir, { recursive: true })
-    const file = join(dir, 'docs.json')
-    writeFileSync(file, JSON.stringify(fixture))
-    try {
-      const result = await resolveEnvelope({ file })
-      expect(result.basePath).toBe('/api')
-      expect(result.routes).toHaveLength(1)
-    } finally {
-      rmSync(dir, { recursive: true })
-    }
-  })
-
-  it('throws on empty routes', async () => {
-    const empty: DocEnvelope = { basePath: '', headers: [], errors: [], routes: [] }
-    await expect(resolveEnvelope({ envelope: empty })).rejects.toThrow('No routes found')
-  })
-
-  it('throws when no input source provided', async () => {
-    await expect(resolveEnvelope({})).rejects.toThrow('Provide one of: url, file, or envelope')
-  })
-})
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run: `npx vitest run src/codegen/resolve-envelope.test.ts`
-Expected: FAIL — module not found
-
-- [ ] **Step 3: Implement resolve-envelope**
-
-Create `src/codegen/resolve-envelope.ts`:
-
-```ts
-import { readFile } from 'node:fs/promises'
-import type { DocEnvelope } from '../implementations/types.js'
-
-export interface ResolveInput {
-  url?: string
-  file?: string
-  envelope?: DocEnvelope
-}
-
-export async function resolveEnvelope(input: ResolveInput): Promise<DocEnvelope> {
-  let envelope: DocEnvelope
-
-  if (input.envelope) {
-    envelope = input.envelope
-  } else if (input.file) {
-    const content = await readFile(input.file, 'utf-8')
-    envelope = JSON.parse(content) as DocEnvelope
-  } else if (input.url) {
-    const response = await fetch(input.url)
-    if (!response.ok) {
-      throw new Error(`Failed to fetch docs from ${input.url}: ${response.status} ${response.statusText}`)
-    }
-    envelope = (await response.json()) as DocEnvelope
-  } else {
-    throw new Error('Provide one of: url, file, or envelope')
-  }
-
-  if (!envelope.routes || envelope.routes.length === 0) {
-    throw new Error('No routes found in DocEnvelope')
-  }
-
-  return envelope
-}
-```
-
-- [ ] **Step 4: Run test to verify it passes**
-
-Run: `npx vitest run src/codegen/resolve-envelope.test.ts`
-Expected: PASS
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add src/codegen/resolve-envelope.ts src/codegen/resolve-envelope.test.ts
-git commit -m "feat: add DocEnvelope resolution (URL, file, object)"
-```
-
----
-
-### Task 11: Group Routes by Scope
-
-**Files:**
-- Create: `src/codegen/group-routes.ts`
-- Test: `src/codegen/group-routes.test.ts`
-
-- [ ] **Step 1: Write failing tests**
-
-Create `src/codegen/group-routes.test.ts`:
-
-```ts
-import { describe, it, expect, vi } from 'vitest'
-import { groupRoutesByScope, normalizeScope, scopeToCamelCase } from './group-routes.js'
-
-describe('normalizeScope', () => {
-  it('returns string scope as-is', () => {
-    expect(normalizeScope('users')).toBe('users')
-  })
-
-  it('joins array scope with -', () => {
-    expect(normalizeScope(['admin', 'users'])).toBe('admin-users')
-  })
-
-  it('returns "default" for undefined', () => {
-    expect(normalizeScope(undefined)).toBe('default')
-  })
-})
-
-describe('scopeToCamelCase', () => {
-  it('converts hyphenated to camelCase', () => {
-    expect(scopeToCamelCase('admin-users')).toBe('adminUsers')
-  })
-
-  it('leaves single word unchanged', () => {
-    expect(scopeToCamelCase('users')).toBe('users')
-  })
-
-  it('handles default', () => {
-    expect(scopeToCamelCase('default')).toBe('default')
-  })
-})
-
-describe('groupRoutesByScope', () => {
-  it('groups routes by normalized scope', () => {
-    const routes = [
-      { kind: 'rpc' as const, name: 'GetUser', path: '/users/GetUser/1', method: 'post' as const, scope: 'users', version: 1, jsonSchema: {} },
-      { kind: 'rpc' as const, name: 'CreateUser', path: '/users/CreateUser/1', method: 'post' as const, scope: 'users', version: 1, jsonSchema: {} },
-      { kind: 'rpc' as const, name: 'GetInvoice', path: '/billing/GetInvoice/1', method: 'post' as const, scope: 'billing', version: 1, jsonSchema: {} },
-    ]
-    const groups = groupRoutesByScope(routes)
-    expect(groups.size).toBe(2)
-    expect(groups.get('users')!.routes).toHaveLength(2)
-    expect(groups.get('billing')!.routes).toHaveLength(1)
-    expect(groups.get('users')!.camelCase).toBe('users')
-  })
-
-  it('groups array scopes by joined key', () => {
-    const routes = [
-      { kind: 'rpc' as const, name: 'AdminGetUser', path: '/admin/users/AdminGetUser/1', method: 'post' as const, scope: ['admin', 'users'], version: 1, jsonSchema: {} },
-    ]
-    const groups = groupRoutesByScope(routes)
-    expect(groups.has('admin-users')).toBe(true)
-    expect(groups.get('admin-users')!.camelCase).toBe('adminUsers')
-  })
-
-  it('groups API routes without scope into default with warning', () => {
-    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {})
-    const routes = [
-      { kind: 'api' as const, name: 'GetHealth', path: '/health', method: 'get' as const, fullPath: '/health', jsonSchema: {} },
-    ]
-    const groups = groupRoutesByScope(routes as any)
-    expect(groups.has('default')).toBe(true)
-    expect(warn).toHaveBeenCalledWith(expect.stringContaining('GetHealth'))
-    warn.mockRestore()
-  })
-})
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run: `npx vitest run src/codegen/group-routes.test.ts`
-Expected: FAIL — module not found
-
-- [ ] **Step 3: Implement group-routes**
-
-Create `src/codegen/group-routes.ts`:
-
-```ts
-import type { AnyHttpRouteDoc } from '../implementations/types.js'
-
-export interface ScopeGroup {
-  scopeKey: string
-  camelCase: string
-  routes: AnyHttpRouteDoc[]
-}
-
-export function normalizeScope(scope: string | string[] | undefined): string {
-  if (scope === undefined) return 'default'
-  if (Array.isArray(scope)) return scope.join('-')
-  return scope
-}
-
-export function scopeToCamelCase(scope: string): string {
-  return scope.replace(/-([a-z])/g, (_, c) => c.toUpperCase())
-}
-
-export function groupRoutesByScope(routes: AnyHttpRouteDoc[]): Map<string, ScopeGroup> {
-  const groups = new Map<string, ScopeGroup>()
-
-  for (const route of routes) {
-    const rawScope = 'scope' in route ? (route as any).scope : undefined
-    const scopeKey = normalizeScope(rawScope)
-
-    if (scopeKey === 'default' && rawScope === undefined) {
-      console.warn(
-        `ts-procedures-codegen: Route "${route.name}" has no scope — grouping into "default". ` +
-        `Add scope to your builder config for explicit grouping.`
-      )
-    }
-
-    let group = groups.get(scopeKey)
-    if (!group) {
-      group = { scopeKey, camelCase: scopeToCamelCase(scopeKey), routes: [] }
-      groups.set(scopeKey, group)
-    }
-    group.routes.push(route)
-  }
-
-  return groups
-}
-```
-
-- [ ] **Step 4: Run test to verify it passes**
-
-Run: `npx vitest run src/codegen/group-routes.test.ts`
-Expected: PASS
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add src/codegen/group-routes.ts src/codegen/group-routes.test.ts
-git commit -m "feat: add scope normalization and route grouping"
-```
-
----
-
-### Task 12: Type Emission (ajsc Integration)
-
-**Files:**
-- Create: `src/codegen/emit-types.ts`
-- Test: `src/codegen/emit-types.test.ts`
-
-- [ ] **Step 1: Write failing tests**
-
-Create `src/codegen/emit-types.test.ts`:
-
-```ts
-import { describe, it, expect } from 'vitest'
-import { jsonSchemaToTypeString } from './emit-types.js'
-
-describe('jsonSchemaToTypeString', () => {
-  it('converts a simple object schema to a TypeScript type', async () => {
-    const schema = {
-      type: 'object',
-      properties: {
-        id: { type: 'string' },
-        name: { type: 'string' },
-      },
-      required: ['id', 'name'],
-    }
-    const result = await jsonSchemaToTypeString('GetUserResponse', schema)
-    expect(result).toContain('id:')
-    expect(result).toContain('string')
-    expect(result).toContain('name:')
-  })
-
-  it('converts a schema with optional fields', async () => {
-    const schema = {
-      type: 'object',
-      properties: {
-        id: { type: 'string' },
-        nickname: { type: 'string' },
-      },
-      required: ['id'],
-    }
-    const result = await jsonSchemaToTypeString('UserParams', schema)
-    expect(result).toContain('id:')
-    // nickname should be optional (not in required)
-    expect(result).toBeDefined()
-  })
-
-  it('returns undefined for undefined schema', async () => {
-    const result = await jsonSchemaToTypeString('Empty', undefined)
-    expect(result).toBeUndefined()
-  })
-
-  it('handles enum schemas', async () => {
-    const schema = {
-      type: 'string',
-      enum: ['admin', 'member', 'viewer'],
-    }
-    const result = await jsonSchemaToTypeString('Role', schema)
-    expect(result).toBeDefined()
-    // Should contain the enum values in some form
-    expect(result).toContain('admin')
-  })
-})
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run: `npx vitest run src/codegen/emit-types.test.ts`
-Expected: FAIL — module not found
-
-- [ ] **Step 3: Implement emit-types with dynamic ajsc import**
-
-Create `src/codegen/emit-types.ts`:
-
-```ts
-export interface AjscOptions {
-  enumStyle?: 'union' | 'enum'
-  depluralize?: boolean
-  inlineTypes?: boolean
-}
-
-let TypescriptConverter: any = null
-
-async function loadAjsc() {
-  if (TypescriptConverter) return
-  try {
-    const ajsc = await import('ajsc')
-    TypescriptConverter = ajsc.TypescriptConverter
-  } catch {
-    throw new Error(
-      'ajsc is required for code generation but is not installed. ' +
-      'Install it with: npm install ajsc'
-    )
-  }
-}
-
-export async function jsonSchemaToTypeString(
-  typeName: string,
-  schema: Record<string, unknown> | undefined,
-  options?: AjscOptions,
-): Promise<string | undefined> {
-  if (!schema) return undefined
-
-  await loadAjsc()
-
-  const converter = new TypescriptConverter(schema, {
-    inlineTypes: options?.inlineTypes ?? true,
-    depluralize: options?.depluralize ?? true,
-    enumStyle: options?.enumStyle ?? 'union',
-  })
-
-  const code = converter.code as string
-
-  // ajsc produces a root type — wrap it with our name
-  // The output from ajsc with inlineTypes is a type literal we can assign
-  return `export type ${typeName} = ${code}`
-}
-```
-
-**Note:** The exact shape of ajsc's output may vary. The implementer should install `ajsc` (`npm install ajsc`) and verify what `TypescriptConverter.code` returns for various schemas. The wrapping logic above may need adjustment based on actual output format — for example, if ajsc already emits `type X = ...` then we should extract just the type body.
-
-- [ ] **Step 4: Install ajsc and run test to verify it passes**
-
-Run: `npm install ajsc && npx vitest run src/codegen/emit-types.test.ts`
-Expected: PASS (or adjust wrapping logic based on actual ajsc output)
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add src/codegen/emit-types.ts src/codegen/emit-types.test.ts
-git commit -m "feat: add ajsc-based JSON Schema to TypeScript type emission"
-```
-
----
-
-### Task 13: Scope File Emission
-
-**Files:**
-- Create: `src/codegen/emit-scope.ts`
-- Test: `src/codegen/emit-scope.test.ts`
-
-- [ ] **Step 1: Write failing tests**
-
-Create `src/codegen/emit-scope.test.ts`:
-
-```ts
-import { describe, it, expect } from 'vitest'
-import { emitScopeFile } from './emit-scope.js'
-import type { ScopeGroup } from './group-routes.js'
-import type { RPCHttpRouteDoc, APIHttpRouteDoc, StreamHttpRouteDoc } from '../implementations/types.js'
-
-describe('emitScopeFile', () => {
-  it('generates scope file for RPC routes', async () => {
-    const group: ScopeGroup = {
-      scopeKey: 'users',
-      camelCase: 'users',
-      routes: [
-        {
-          kind: 'rpc',
-          name: 'GetUser',
-          path: '/users/GetUser/1',
-          method: 'post',
-          scope: 'users',
-          version: 1,
-          jsonSchema: {
-            body: { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] },
-            response: { type: 'object', properties: { name: { type: 'string' } }, required: ['name'] },
-          },
-        } satisfies RPCHttpRouteDoc,
-      ],
-    }
-    const code = await emitScopeFile(group)
-    expect(code).toContain('ts-procedures-codegen')
-    expect(code).toContain("from 'ts-procedures/client'")
-    expect(code).toContain('GetUserParams')
-    expect(code).toContain('GetUserResponse')
-    expect(code).toContain('bindUsersScope')
-    expect(code).toContain("name: 'GetUser'")
-    expect(code).toContain("scope: 'users'")
-    expect(code).toContain("method: 'post'")
-    expect(code).toContain('client.call')
-  })
-
-  it('generates scope file for API routes with structured params', async () => {
-    const group: ScopeGroup = {
-      scopeKey: 'users',
-      camelCase: 'users',
-      routes: [
-        {
-          kind: 'api',
-          name: 'UpdateUser',
-          path: '/users/:id',
-          method: 'put',
-          scope: 'users',
-          fullPath: '/api/users/:id',
-          jsonSchema: {
-            pathParams: { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] },
-            body: { type: 'object', properties: { name: { type: 'string' } }, required: ['name'] },
-            response: { type: 'object', properties: { ok: { type: 'boolean' } }, required: ['ok'] },
-          },
-        } satisfies APIHttpRouteDoc,
-      ],
-    }
-    const code = await emitScopeFile(group)
-    expect(code).toContain('UpdateUserParams')
-    expect(code).toContain('UpdateUserResponse')
-    expect(code).toContain("method: 'put'")
-  })
-
-  it('generates scope file for stream routes', async () => {
-    const group: ScopeGroup = {
-      scopeKey: 'notifications',
-      camelCase: 'notifications',
-      routes: [
-        {
-          kind: 'stream',
-          name: 'Watch',
-          path: '/notifications/Watch/1',
-          methods: ['get', 'post'],
-          streamMode: 'sse',
-          scope: 'notifications',
-          version: 1,
-          jsonSchema: {
-            params: { type: 'object', properties: { accountId: { type: 'string' } } },
-            yieldType: {
-              type: 'object',
-              description: 'SSE message envelope.',
-              required: ['data', 'event', 'id'],
-              properties: {
-                data: { type: 'object', properties: { msg: { type: 'string' } } },
-                event: { type: 'string' },
-                id: { type: 'string' },
-                retry: { type: 'number' },
-              },
-            },
-            returnType: { type: 'object', properties: { total: { type: 'number' } } },
-          },
-        } satisfies StreamHttpRouteDoc,
-      ],
-    }
-    const code = await emitScopeFile(group)
-    expect(code).toContain('WatchParams')
-    expect(code).toContain('WatchYield')
-    expect(code).toContain('WatchReturn')
-    expect(code).toContain('TypedStream')
-    expect(code).toContain('client.stream')
-    expect(code).toContain("streamMode: 'sse'")
-  })
-
-  it('unwraps SSE envelope for yieldType — uses inner data schema', async () => {
-    const group: ScopeGroup = {
-      scopeKey: 'events',
-      camelCase: 'events',
-      routes: [
-        {
-          kind: 'stream',
-          name: 'StreamEvents',
-          path: '/events/StreamEvents/1',
-          methods: ['get', 'post'],
-          streamMode: 'sse',
-          scope: 'events',
-          version: 1,
-          jsonSchema: {
-            yieldType: {
-              type: 'object',
-              required: ['data', 'event', 'id'],
-              properties: {
-                data: { type: 'object', properties: { value: { type: 'number' } } },
-                event: { type: 'string' },
-                id: { type: 'string' },
-              },
-            },
-          },
-        } satisfies StreamHttpRouteDoc,
-      ],
-    }
-    const code = await emitScopeFile(group)
-    // The yield type should be based on the inner data schema, not the full envelope
-    expect(code).toContain('StreamEventsYield')
-    // Should NOT contain the SSE envelope fields in the yield type
-    expect(code).not.toContain("event: string")
-  })
-})
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run: `npx vitest run src/codegen/emit-scope.test.ts`
-Expected: FAIL — module not found
-
-- [ ] **Step 3: Implement emit-scope**
-
-Create `src/codegen/emit-scope.ts`:
-
-```ts
-import type { AnyHttpRouteDoc, RPCHttpRouteDoc, APIHttpRouteDoc, StreamHttpRouteDoc } from '../implementations/types.js'
-import type { ScopeGroup } from './group-routes.js'
-import type { AjscOptions } from './emit-types.js'
-import { jsonSchemaToTypeString } from './emit-types.js'
-import { scopeToCamelCase } from './group-routes.js'
-
-function isSSEEnvelope(schema: Record<string, unknown> | undefined): boolean {
-  if (!schema) return false
-  const props = schema.properties as Record<string, unknown> | undefined
-  return !!props?.data && !!props?.event && !!props?.id
-}
-
-function unwrapSSEYieldType(schema: Record<string, unknown>): Record<string, unknown> {
-  const props = schema.properties as Record<string, any>
-  return props.data ?? schema
-}
-
-async function emitRpcRoute(route: RPCHttpRouteDoc, ajscOpts?: AjscOptions): Promise<{ types: string; callable: string }> {
-  const types: string[] = []
-  const paramsType = await jsonSchemaToTypeString(`${route.name}Params`, route.jsonSchema.body, ajscOpts)
-  const responseType = await jsonSchemaToTypeString(`${route.name}Response`, route.jsonSchema.response, ajscOpts)
-  if (paramsType) types.push(paramsType)
-  if (responseType) types.push(responseType)
-
-  const paramsArg = paramsType ? `params: ${route.name}Params` : ''
-  const returnType = responseType ? `Promise<${route.name}Response>` : 'Promise<unknown>'
-
-  const callable = `    /** POST ${route.path} */
-    ${route.name}(${paramsArg}${paramsArg ? ', ' : ''}options?: ProcedureCallOptions): ${returnType} {
-      return client.call({
-        name: '${route.name}',
-        scope: '${typeof route.scope === 'string' ? route.scope : route.scope.join('-')}',
-        path: '${route.path}',
-        method: '${route.method}',
-        kind: 'rpc',
-        params${paramsArg ? '' : ': undefined'},
-      }, options)
-    }`
-
-  return { types: types.join('\n\n'), callable }
-}
-
-async function emitApiRoute(route: APIHttpRouteDoc, ajscOpts?: AjscOptions): Promise<{ types: string; callable: string }> {
-  const types: string[] = []
-  const channels: string[] = []
-
-  // Build structured params type with PascalCase channel names
-  for (const channel of ['pathParams', 'query', 'body', 'headers'] as const) {
-    const schema = route.jsonSchema[channel]
-    if (schema) {
-      const channelPascal = channel.charAt(0).toUpperCase() + channel.slice(1)
-      const channelType = await jsonSchemaToTypeString(`${route.name}${channelPascal}`, schema, ajscOpts)
-      if (channelType) {
-        types.push(channelType)
-        channels.push(`  ${channel}: ${route.name}${channelPascal}`)
-      }
-    }
-  }
-
-  if (channels.length > 0) {
-    types.push(`export type ${route.name}Params = {\n${channels.join('\n')}\n}`)
-  }
-
-  const responseType = await jsonSchemaToTypeString(`${route.name}Response`, route.jsonSchema.response, ajscOpts)
-  if (responseType) types.push(responseType)
-
-  const paramsArg = channels.length > 0 ? `params: ${route.name}Params` : ''
-  const returnType = responseType ? `Promise<${route.name}Response>` : 'Promise<unknown>'
-  const scope = route.scope ?? 'default'
-
-  const callable = `    /** ${route.method.toUpperCase()} ${route.fullPath || route.path} */
-    ${route.name}(${paramsArg}${paramsArg ? ', ' : ''}options?: ProcedureCallOptions): ${returnType} {
-      return client.call({
-        name: '${route.name}',
-        scope: '${scope}',
-        path: '${route.path}',
-        method: '${route.method}',
-        kind: 'api',
-        params${paramsArg ? '' : ': undefined'},
-      }, options)
-    }`
-
-  return { types: types.join('\n\n'), callable }
-}
-
-async function emitStreamRoute(route: StreamHttpRouteDoc, ajscOpts?: AjscOptions): Promise<{ types: string; callable: string }> {
-  const types: string[] = []
-
-  const paramsType = await jsonSchemaToTypeString(`${route.name}Params`, route.jsonSchema.params, ajscOpts)
-  if (paramsType) types.push(paramsType)
-
-  // Unwrap SSE envelope for yieldType
-  let yieldSchema = route.jsonSchema.yieldType
-  if (route.streamMode === 'sse' && yieldSchema && isSSEEnvelope(yieldSchema)) {
-    yieldSchema = unwrapSSEYieldType(yieldSchema)
-  }
-  const yieldType = await jsonSchemaToTypeString(`${route.name}Yield`, yieldSchema, ajscOpts)
-  if (yieldType) types.push(yieldType)
-
-  const returnType = await jsonSchemaToTypeString(`${route.name}Return`, route.jsonSchema.returnType, ajscOpts)
-  if (returnType) types.push(returnType)
-
-  const paramsArg = paramsType ? `params: ${route.name}Params` : ''
-  const yieldTypeRef = yieldType ? `${route.name}Yield` : 'unknown'
-  const returnTypeRef = returnType ? `${route.name}Return` : 'void'
-  const scope = typeof route.scope === 'string' ? route.scope : route.scope.join('-')
-
-  const callable = `    /** ${route.streamMode.toUpperCase()} ${route.path} */
-    ${route.name}(${paramsArg}${paramsArg ? ', ' : ''}options?: ProcedureCallOptions): TypedStream<${yieldTypeRef}, ${returnTypeRef}> {
-      return client.stream({
-        name: '${route.name}',
-        scope: '${scope}',
-        path: '${route.path}',
-        method: 'post',
-        kind: 'stream',
-        streamMode: '${route.streamMode}',
-        params${paramsArg ? '' : ': undefined'},
-      }, options)
-    }`
-
-  return { types: types.join('\n\n'), callable }
-}
-
-export async function emitScopeFile(group: ScopeGroup, ajscOpts?: AjscOptions): Promise<string> {
-  const allTypes: string[] = []
-  const allCallables: string[] = []
-  let needsTypedStream = false
-
-  for (const route of group.routes) {
-    let result: { types: string; callable: string }
-
-    if (route.kind === 'rpc') {
-      result = await emitRpcRoute(route as RPCHttpRouteDoc, ajscOpts)
-    } else if (route.kind === 'api') {
-      result = await emitApiRoute(route as APIHttpRouteDoc, ajscOpts)
-    } else if (route.kind === 'stream') {
-      result = await emitStreamRoute(route as StreamHttpRouteDoc, ajscOpts)
-      needsTypedStream = true
-    } else {
-      throw new Error(`Unknown route kind on route "${route.name}"`)
-    }
-
-    if (result.types) allTypes.push(result.types)
-    allCallables.push(result.callable)
-  }
-
-  const pascalScope = group.camelCase.charAt(0).toUpperCase() + group.camelCase.slice(1)
-  const typedStreamImport = needsTypedStream ? ', TypedStream' : ''
-
-  return `// Auto-generated by ts-procedures-codegen — do not edit
-import type { ClientInstance, ProcedureCallOptions${typedStreamImport} } from 'ts-procedures/client'
-
-// ── Types ────────────────────────────────────────────────────
-
-${allTypes.join('\n\n')}
-
-// ── Callables ────────────────────────────────────────────────
-
-export function bind${pascalScope}Scope(client: ClientInstance) {
-  return {
-${allCallables.join(',\n\n')},
-  }
-}
-`
-}
-```
-
-- [ ] **Step 4: Run test to verify it passes**
-
-Run: `npx vitest run src/codegen/emit-scope.test.ts`
-Expected: PASS
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add src/codegen/emit-scope.ts src/codegen/emit-scope.test.ts
-git commit -m "feat: add per-scope file emission for RPC, API, and stream routes"
-```
-
----
-
-### Task 14: Index Emission
-
-**Files:**
-- Create: `src/codegen/emit-index.ts`
-- Test: `src/codegen/emit-index.test.ts`
-
-- [ ] **Step 1: Write failing tests**
-
-Create `src/codegen/emit-index.test.ts`:
-
-```ts
-import { describe, it, expect } from 'vitest'
-import { emitIndexFile } from './emit-index.js'
-import type { ScopeGroup } from './group-routes.js'
-
-describe('emitIndexFile', () => {
-  it('generates barrel with scope bindings', () => {
-    const groups: ScopeGroup[] = [
-      { scopeKey: 'users', camelCase: 'users', routes: [] },
-      { scopeKey: 'billing', camelCase: 'billing', routes: [] },
-      { scopeKey: 'admin-users', camelCase: 'adminUsers', routes: [] },
-    ]
-    const code = emitIndexFile(groups)
-    expect(code).toContain("from './users'")
-    expect(code).toContain("from './billing'")
-    expect(code).toContain("from './admin-users'")
-    expect(code).toContain("export * from './users'")
-    expect(code).toContain('bindUsersScope')
-    expect(code).toContain('bindBillingScope')
-    expect(code).toContain('bindAdminUsersScope')
-    expect(code).toContain('createScopeBindings')
-    expect(code).toContain('users: bindUsersScope(client)')
-    expect(code).toContain('adminUsers: bindAdminUsersScope(client)')
-  })
-})
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run: `npx vitest run src/codegen/emit-index.test.ts`
-Expected: FAIL — module not found
-
-- [ ] **Step 3: Implement emit-index**
-
-Create `src/codegen/emit-index.ts`:
-
-```ts
-import type { ScopeGroup } from './group-routes.js'
-
-export function emitIndexFile(groups: ScopeGroup[]): string {
-  const imports: string[] = []
-  const reExports: string[] = []
-  const bindings: string[] = []
-
-  for (const group of groups) {
-    const pascal = group.camelCase.charAt(0).toUpperCase() + group.camelCase.slice(1)
-    const bindFn = `bind${pascal}Scope`
-    imports.push(`import { ${bindFn} } from './${group.scopeKey}'`)
-    reExports.push(`export * from './${group.scopeKey}'`)
-    bindings.push(`    ${group.camelCase}: ${bindFn}(client)`)
-  }
-
-  return `// Auto-generated by ts-procedures-codegen — do not edit
-import type { ClientInstance } from 'ts-procedures/client'
-${imports.join('\n')}
-
-${reExports.join('\n')}
-
-export function createScopeBindings(client: ClientInstance) {
-  return {
-${bindings.join(',\n')},
-  }
-}
-`
-}
-```
-
-- [ ] **Step 4: Run test to verify it passes**
-
-Run: `npx vitest run src/codegen/emit-index.test.ts`
-Expected: PASS
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add src/codegen/emit-index.ts src/codegen/emit-index.test.ts
-git commit -m "feat: add barrel index file emission"
-```
-
----
-
-### Task 15: Pipeline and generateClient API
-
-**Files:**
-- Create: `src/codegen/pipeline.ts`
-- Create: `src/codegen/index.ts`
-- Test: `src/codegen/pipeline.test.ts`
-
-- [ ] **Step 1: Write failing tests**
-
-Create `src/codegen/pipeline.test.ts`:
-
-```ts
-import { describe, it, expect } from 'vitest'
-import { generateClient } from './index.js'
-import { mkdirSync, rmSync, readFileSync, existsSync } from 'node:fs'
-import { join } from 'node:path'
-import { tmpdir } from 'node:os'
-import type { DocEnvelope } from '../implementations/types.js'
-
-const fixture: DocEnvelope = {
-  basePath: '/api',
-  headers: [],
-  errors: [],
-  routes: [
-    {
-      kind: 'rpc',
-      name: 'GetUser',
-      path: '/users/GetUser/1',
-      method: 'post',
-      scope: 'users',
-      version: 1,
-      jsonSchema: {
-        body: { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] },
-        response: { type: 'object', properties: { name: { type: 'string' } }, required: ['name'] },
-      },
-    },
-    {
-      kind: 'rpc',
-      name: 'ListInvoices',
-      path: '/billing/ListInvoices/1',
-      method: 'post',
-      scope: 'billing',
-      version: 1,
-      jsonSchema: {
-        response: { type: 'object', properties: { items: { type: 'array' } } },
-      },
-    },
-  ],
-}
-
-describe('generateClient', () => {
-  let outDir: string
-
-  it('generates per-scope files and an index', async () => {
-    outDir = join(tmpdir(), 'ts-proc-codegen-test-' + Date.now())
-    mkdirSync(outDir, { recursive: true })
-
-    await generateClient({
-      envelope: fixture as any,
-      outDir,
-    })
-
-    expect(existsSync(join(outDir, 'users.ts'))).toBe(true)
-    expect(existsSync(join(outDir, 'billing.ts'))).toBe(true)
-    expect(existsSync(join(outDir, 'index.ts'))).toBe(true)
-
-    const usersContent = readFileSync(join(outDir, 'users.ts'), 'utf-8')
-    expect(usersContent).toContain('GetUserParams')
-    expect(usersContent).toContain('GetUserResponse')
-    expect(usersContent).toContain('bindUsersScope')
-
-    const indexContent = readFileSync(join(outDir, 'index.ts'), 'utf-8')
-    expect(indexContent).toContain('createScopeBindings')
-    expect(indexContent).toContain("from './users'")
-    expect(indexContent).toContain("from './billing'")
-
-    rmSync(outDir, { recursive: true })
-  })
-})
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run: `npx vitest run src/codegen/pipeline.test.ts`
-Expected: FAIL — module not found
-
-- [ ] **Step 3: Implement pipeline and index**
-
-Create `src/codegen/pipeline.ts`:
-
-```ts
-import { mkdir, writeFile } from 'node:fs/promises'
-import { join } from 'node:path'
-import type { DocEnvelope } from '../implementations/types.js'
-import type { AjscOptions } from './emit-types.js'
-import { groupRoutesByScope } from './group-routes.js'
-import { emitScopeFile } from './emit-scope.js'
-import { emitIndexFile } from './emit-index.js'
-
-export interface PipelineOptions {
-  envelope: DocEnvelope
-  outDir: string
-  ajsc?: AjscOptions
-}
-
-export async function runPipeline(options: PipelineOptions): Promise<void> {
-  const { envelope, outDir, ajsc: ajscOpts } = options
-
-  await mkdir(outDir, { recursive: true })
-
-  const groups = groupRoutesByScope(envelope.routes)
-  const groupArray = Array.from(groups.values())
-
-  // Emit each scope file
-  for (const group of groupArray) {
-    const code = await emitScopeFile(group, ajscOpts)
-    await writeFile(join(outDir, `${group.scopeKey}.ts`), code, 'utf-8')
-  }
-
-  // Emit index
-  const indexCode = emitIndexFile(groupArray)
-  await writeFile(join(outDir, 'index.ts'), indexCode, 'utf-8')
-}
-```
-
-Create `src/codegen/index.ts`:
-
-```ts
-import { resolveEnvelope, type ResolveInput } from './resolve-envelope.js'
-import { runPipeline } from './pipeline.js'
-import type { AjscOptions } from './emit-types.js'
-
-export interface GenerateClientOptions extends ResolveInput {
-  outDir: string
-  ajsc?: AjscOptions
-}
-
-export async function generateClient(options: GenerateClientOptions): Promise<void> {
-  const envelope = await resolveEnvelope(options)
-  await runPipeline({ envelope, outDir: options.outDir, ajsc: options.ajsc })
-}
-
-export type { AjscOptions } from './emit-types.js'
-export type { ResolveInput } from './resolve-envelope.js'
-```
-
-- [ ] **Step 4: Run test to verify it passes**
-
-Run: `npx vitest run src/codegen/pipeline.test.ts`
-Expected: PASS
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add src/codegen/pipeline.ts src/codegen/index.ts src/codegen/pipeline.test.ts
-git commit -m "feat: add codegen pipeline and generateClient public API"
-```
-
----
-
-### Task 16: CLI
-
-**Files:**
-- Create: `src/codegen/bin/cli.ts`
-- Test: `src/codegen/bin/cli.test.ts`
-
-- [ ] **Step 1: Write failing tests**
-
-Create `src/codegen/bin/cli.test.ts`:
-
-```ts
-import { describe, it, expect } from 'vitest'
-import { parseArgs } from './cli.js'
-
-describe('parseArgs', () => {
-  it('parses --url and --out', () => {
-    const args = parseArgs(['--url', 'http://localhost:3000/docs', '--out', './generated'])
-    expect(args.url).toBe('http://localhost:3000/docs')
-    expect(args.outDir).toBe('./generated')
-  })
-
-  it('parses --file and --out', () => {
-    const args = parseArgs(['--file', './docs.json', '--out', './generated'])
-    expect(args.file).toBe('./docs.json')
-    expect(args.outDir).toBe('./generated')
-  })
-
-  it('parses --enum-style', () => {
-    const args = parseArgs(['--url', 'http://x.com/docs', '--out', './gen', '--enum-style', 'enum'])
-    expect(args.ajsc?.enumStyle).toBe('enum')
-  })
-
-  it('throws when --out is missing', () => {
-    expect(() => parseArgs(['--url', 'http://x.com/docs'])).toThrow('--out is required')
-  })
-
-  it('throws when no input source provided', () => {
-    expect(() => parseArgs(['--out', './gen'])).toThrow('Provide --url or --file')
-  })
-})
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run: `npx vitest run src/codegen/bin/cli.test.ts`
-Expected: FAIL — module not found
-
-- [ ] **Step 3: Implement CLI**
-
-Create `src/codegen/bin/cli.ts`:
-
-```ts
-#!/usr/bin/env node
-import { generateClient, type GenerateClientOptions } from '../index.js'
-
-export interface ParsedArgs {
-  url?: string
-  file?: string
-  outDir: string
-  watch?: boolean
-  interval?: number
-  ajsc?: {
-    enumStyle?: 'union' | 'enum'
-    depluralize?: boolean
-  }
-}
-
-export function parseArgs(argv: string[]): ParsedArgs {
-  const result: Partial<ParsedArgs> = { ajsc: {} }
-
-  for (let i = 0; i < argv.length; i++) {
-    switch (argv[i]) {
-      case '--url': result.url = argv[++i]; break
-      case '--file': result.file = argv[++i]; break
-      case '--out': result.outDir = argv[++i]; break
-      case '--watch': result.watch = true; break
-      case '--interval': result.interval = parseInt(argv[++i], 10); break
-      case '--enum-style': result.ajsc!.enumStyle = argv[++i] as 'union' | 'enum'; break
-      case '--depluralize': result.ajsc!.depluralize = argv[++i] !== 'false'; break
-    }
-  }
-
-  if (!result.outDir) throw new Error('--out is required')
-  if (!result.url && !result.file) throw new Error('Provide --url or --file')
-
-  return result as ParsedArgs
-}
-
-async function run() {
-  const args = parseArgs(process.argv.slice(2))
-
-  const options: GenerateClientOptions = {
-    url: args.url,
-    file: args.file,
-    outDir: args.outDir,
-    ajsc: args.ajsc,
-  }
-
-  if (args.watch) {
-    const interval = args.interval ?? 3000
-    let lastHash = ''
-    console.log(`Watching ${args.url || args.file} every ${interval}ms...`)
-
-    const poll = async () => {
-      try {
-        const { createHash } = await import('node:crypto')
-        // Re-resolve each time to detect changes
-        const { resolveEnvelope } = await import('../resolve-envelope.js')
-        const envelope = await resolveEnvelope(options)
-        const hash = createHash('md5').update(JSON.stringify(envelope)).digest('hex')
-
-        if (hash !== lastHash) {
-          lastHash = hash
-          await generateClient({ ...options, envelope })
-          console.log(`Generated client files in ${args.outDir}`)
-        }
-      } catch (err) {
-        console.error('Error:', (err as Error).message)
-      }
-    }
-
-    await poll()
-    setInterval(poll, interval)
-  } else {
-    await generateClient(options)
-    console.log(`Generated client files in ${args.outDir}`)
-  }
-}
-
-// Only run if this is the entry point
-const isMain = process.argv[1]?.endsWith('cli.js') || process.argv[1]?.endsWith('cli.ts')
-if (isMain) {
-  run().catch((err) => {
-    console.error('Error:', err.message)
-    process.exit(1)
-  })
-}
-```
-
-- [ ] **Step 4: Run test to verify it passes**
-
-Run: `npx vitest run src/codegen/bin/cli.test.ts`
-Expected: PASS
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add src/codegen/bin/cli.ts src/codegen/bin/cli.test.ts
-git commit -m "feat: add ts-procedures-codegen CLI"
-```
-
----
-
-## Phase 4: Package Integration
-
-### Task 17: Update package.json
-
-**Files:**
-- Modify: `package.json`
-
-- [ ] **Step 1: Add new exports, bin entry, and optionalDependency**
-
-In `package.json`, add the following:
-
-Under `"exports"`, add:
-```json
-"./client": {
-  "types": "./build/client/index.d.ts",
-  "import": "./build/client/index.js"
-},
-"./codegen": {
-  "types": "./build/codegen/index.d.ts",
-  "import": "./build/codegen/index.js"
-}
-```
-
-Under `"bin"`, add:
-```json
-"ts-procedures-codegen": "./build/codegen/bin/cli.js"
-```
-
-Under `"optionalDependencies"`, add:
-```json
-"ajsc": "^5.2.4"
-```
-
-- [ ] **Step 2: Verify build**
-
-Run: `npm run build`
-Expected: Compiles successfully with new client/ and codegen/ files in build/
-
-- [ ] **Step 3: Run lint**
-
-Run: `npm run lint`
-Expected: No errors. Fix any lint issues in new code before proceeding.
-
-- [ ] **Step 4: Run full test suite**
-
-Run: `npm run test`
-Expected: All tests pass (existing + new)
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add package.json
-git commit -m "feat: add client and codegen package exports, CLI bin entry, ajsc optionalDep"
-```
-
----
-
-### Task 18: End-to-End Integration Test
-
-**Files:**
-- Create: `src/codegen/e2e.test.ts`
-
-- [ ] **Step 1: Write E2E test**
-
-Create `src/codegen/e2e.test.ts` that exercises the full pipeline from DocEnvelope → generated files → verify generated code structure:
-
-```ts
-import { describe, it, expect } from 'vitest'
-import { generateClient } from './index.js'
-import { mkdirSync, rmSync, readFileSync, existsSync } from 'node:fs'
-import { join } from 'node:path'
-import { tmpdir } from 'node:os'
-import type { DocEnvelope, RPCHttpRouteDoc, APIHttpRouteDoc, StreamHttpRouteDoc } from '../implementations/types.js'
-
-describe('E2E: generateClient', () => {
-  const outDir = join(tmpdir(), 'ts-proc-e2e-' + Date.now())
-
-  const envelope: DocEnvelope = {
-    basePath: '/api/v1',
-    headers: [{ name: 'Authorization', required: true }],
-    errors: [],
-    routes: [
-      {
-        kind: 'rpc',
-        name: 'GetUser',
-        path: '/users/GetUser/1',
-        method: 'post',
-        scope: 'users',
-        version: 1,
-        jsonSchema: {
-          body: { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] },
-          response: { type: 'object', properties: { id: { type: 'string' }, name: { type: 'string' } }, required: ['id', 'name'] },
-        },
-      } satisfies RPCHttpRouteDoc,
-      {
-        kind: 'api',
-        name: 'UpdateUser',
-        path: '/users/:id',
-        method: 'put',
-        scope: 'users',
-        fullPath: '/api/v1/users/:id',
-        jsonSchema: {
-          pathParams: { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] },
-          body: { type: 'object', properties: { name: { type: 'string' } }, required: ['name'] },
-          response: { type: 'object', properties: { ok: { type: 'boolean' } }, required: ['ok'] },
-        },
-      } satisfies APIHttpRouteDoc,
-      {
-        kind: 'stream',
-        name: 'WatchEvents',
-        path: '/events/WatchEvents/1',
-        methods: ['get', 'post'],
-        streamMode: 'sse',
-        scope: 'events',
-        version: 1,
-        jsonSchema: {
-          params: { type: 'object', properties: { filter: { type: 'string' } } },
-          yieldType: {
-            type: 'object',
-            required: ['data', 'event', 'id'],
-            properties: {
-              data: { type: 'object', properties: { msg: { type: 'string' } } },
-              event: { type: 'string' },
-              id: { type: 'string' },
-            },
-          },
-          returnType: { type: 'object', properties: { count: { type: 'number' } } },
-        },
-      } satisfies StreamHttpRouteDoc,
-    ],
-  }
-
-  it('generates all expected files', async () => {
-    mkdirSync(outDir, { recursive: true })
-    await generateClient({ envelope: envelope as any, outDir })
-
-    // Check files exist
-    expect(existsSync(join(outDir, 'users.ts'))).toBe(true)
-    expect(existsSync(join(outDir, 'events.ts'))).toBe(true)
-    expect(existsSync(join(outDir, 'index.ts'))).toBe(true)
-
-    // Verify users scope has both RPC and API routes
-    const users = readFileSync(join(outDir, 'users.ts'), 'utf-8')
-    expect(users).toContain('GetUserParams')
-    expect(users).toContain('GetUserResponse')
-    expect(users).toContain('UpdateUserParams')
-    expect(users).toContain('UpdateUserResponse')
-    expect(users).toContain('bindUsersScope')
-    expect(users).toContain('client.call')
-
-    // Verify events scope has stream route
-    const events = readFileSync(join(outDir, 'events.ts'), 'utf-8')
-    expect(events).toContain('WatchEventsYield')
-    expect(events).toContain('WatchEventsReturn')
-    expect(events).toContain('TypedStream')
-    expect(events).toContain('client.stream')
-    expect(events).toContain("streamMode: 'sse'")
-
-    // Verify index barrel
-    const index = readFileSync(join(outDir, 'index.ts'), 'utf-8')
-    expect(index).toContain('createScopeBindings')
-    expect(index).toContain('bindUsersScope')
-    expect(index).toContain('bindEventsScope')
-
-    rmSync(outDir, { recursive: true })
-  })
-})
-```
-
-- [ ] **Step 2: Run E2E test**
-
-Run: `npx vitest run src/codegen/e2e.test.ts`
-Expected: PASS
-
-- [ ] **Step 3: Run full test suite one final time**
-
-Run: `npm run test`
-Expected: All tests pass
-
-- [ ] **Step 4: Run build to confirm everything compiles**
-
-Run: `npm run build`
-Expected: Clean compilation
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add src/codegen/e2e.test.ts
-git commit -m "test: add end-to-end integration test for client codegen"
-```
-
----
-
-## Task Dependency Graph
-
-```
-Task 1 (types) → Task 2 (builders)
-                       ↓
-Task 3 (client types) → Task 4 (errors) → Task 5 (request builder) → Task 6 (hooks)
-                                                                           ↓
-                                                             Task 7 (call) → Task 8 (stream) → Task 9 (createClient)
-                                                                                                        ↓
-Task 10 (resolve) → Task 11 (group) → Task 12 (emit types) → Task 13 (emit scope) → Task 14 (emit index) → Task 15 (pipeline)
-                                                                                                                      ↓
-                                                                                               Task 16 (CLI) → Task 17 (package.json) → Task 18 (E2E)
-```
-
-**Independent parallel tracks:**
-- Phase 1 (Tasks 1-2) and Phase 2 (Tasks 3-9) can run in parallel
-- Phase 3 (Tasks 10-16) depends on Phase 1 (for route types with `kind`) but NOT on Phase 2
-- Phase 4 (Tasks 17-18) depends on everything