ts-procedures 6.2.0 → 7.0.0-beta.0

package/docs/superpowers/plans/2026-04-29-safe-result-api.md

@@ -0,0 +1,2293 @@
+# Safe Result API & Normalized Client Errors — 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 a `.safe()` sibling form to every generated RPC/API callable that returns a discriminated `Result<T, E>` — and back it with a classifier that normalizes platform errors (`TypeError`, `DOMException`) into framework error classes. Make the `kind` set extensible via `ClientErrorMap` interface augmentation, mirroring the existing `RequestMeta` pattern. Throwing form remains canonical; `.safe()` is opt-in.
+
+**Architecture:** Three failure-source paths in `executeCall` (pre-adapter usage error, adapter throw → classifier, adapter non-2xx → registry-or-fallback) each map to exactly one `Result.kind`. Default classifier is composed with optional adapter-provided `classifyError`. Codegen emits `.safe` as a sibling property on each callable (RPC/API only, streams excluded), branching between `Result<T, RouteErrors>` and `ResultNoTyped<T>` based on whether `route.errors` is declared.
+
+**Tech Stack:** TypeScript, Vitest, existing `ts-procedures` codegen pipeline. No new runtime dependencies.
+
+**Spec:** [docs/superpowers/specs/2026-04-29-safe-result-api-design.md](../specs/2026-04-29-safe-result-api-design.md)
+
+**Branch:** Recommend a fresh worktree off `master` named `safe-result-api`. This is a major version (7.0.0) so changes will not merge back into a minor.
+
+---
+
+## File map
+
+**Create:**
+- `src/client/classify-error.ts` — default classifier + `ErrorClassifier` type
+- `src/client/classify-error.test.ts`
+- `src/client/safe-call.test.ts` — covers `executeSafeCall` and `ClientInstance.safeCall`
+- `src/client/augment-error-map.test-d.ts` — type-level test verifying augmentation widens `Result`
+- `src/codegen/bundle-size.test.ts` — regression guard on per-route byte cost
+- `docs/client-error-handling.md` — consumer guide
+
+**Modify:**
+- `src/client/errors.ts` — rename `ClientRequestError` → `ClientHttpError`; add `ClientNetworkError`, `ClientTimeoutError`, `ClientAbortError`, `ClientParseError`; add `cause` constructor contract
+- `src/client/types.ts` — add `ClientErrorMap`, `Result`, `ResultNoTyped`, `FrameworkFailure`; extend `ClientAdapter` with optional `classifyError`; extend `ClientInstance` with `safeCall`
+- `src/client/resolve-options.ts` — return signal sources alongside the merged request so classifier can recover provenance
+- `src/client/call.ts` — wrap adapter call in classifier; add `executeSafeCall`
+- `src/client/stream.ts` — wrap pre-stream adapter call in classifier
+- `src/client/fetch-adapter.ts` — accept `classifyError` in config (composes with default)
+- `src/client/index.ts` — export new classes, classifier, `Result`, `ResultNoTyped`, `ClientErrorMap`, `defaultClassifyError`
+- `src/client/call.test.ts`, `src/client/stream.test.ts`, `src/client/fetch-adapter.test.ts`, `src/client/errors.test.ts`, `src/client/index.test.ts` — update for new shapes
+- `src/codegen/emit-scope.ts` — emit `.safe` sibling for RPC/API; branch between `Result` and `ResultNoTyped`
+- `src/codegen/emit-scope.test.ts` — extend coverage
+- `src/codegen/__fixtures__/users-envelope.json` (review for any envelope augmentation needed for the bundle-size test) — likely unchanged
+- `src/codegen/__fixtures__/users-golden.ts` (or per-target equivalent) — refresh with `.safe` siblings
+- `CLAUDE.md` — add normalized error taxonomy + `.safe` form notes
+- `agent_config/claude-code/skills/ts-procedures/patterns.md`, `anti-patterns.md` — error-handling patterns
+- `agent_config/copilot/copilot-instructions.md`, `agent_config/cursor/cursorrules` — condensed equivalents
+- `package.json` — bump to `7.0.0`
+- `CHANGELOG.md` (or release notes file) — major bump entry
+
+---
+
+## Phase 1 — Error class taxonomy + cause contract
+
+### Task 1: Add `cause` constructor contract to existing error classes
+
+**Files:**
+- Modify: `src/client/errors.ts`
+- Test: `src/client/errors.test.ts`
+
+- [ ] **Step 1: Read the existing test file to understand convention**
+
+```bash
+cat src/client/errors.test.ts
+```
+
+- [ ] **Step 2: Write failing test for cause on existing classes**
+
+Add to `src/client/errors.test.ts`:
+
+```ts
+import { describe, it, expect } from 'vitest'
+import { ClientPathParamError, ClientStreamError } from './errors.js'
+
+describe('ClientPathParamError cause', () => {
+  it('accepts and stores cause', () => {
+    const cause = new TypeError('underlying')
+    const err = new ClientPathParamError('id', '/u/:id', 'GetUser', cause)
+    expect(err.cause).toBe(cause)
+  })
+})
+
+describe('ClientStreamError cause', () => {
+  it('accepts and stores cause', () => {
+    const cause = new Error('underlying')
+    const err = new ClientStreamError('boom', 'StreamUsers', 'users', cause)
+    expect(err.cause).toBe(cause)
+  })
+})
+```
+
+- [ ] **Step 3: Run tests to verify they fail**
+
+```bash
+npx vitest run src/client/errors.test.ts -t 'cause'
+```
+Expected: FAIL — constructor doesn't accept `cause`.
+
+- [ ] **Step 4: Update `ClientPathParamError` and `ClientStreamError` constructors**
+
+Edit `src/client/errors.ts`:
+
+```ts
+export class ClientPathParamError extends Error {
+  readonly name = 'ClientPathParamError'
+
+  constructor(param: string, path: string, procedureName: string, cause?: unknown) {
+    super(`Missing path parameter "${param}" in "${path}" for procedure ${procedureName}`, { cause })
+  }
+}
+
+export class ClientStreamError extends Error {
+  readonly name = 'ClientStreamError'
+  readonly procedureName: string
+  readonly scope: string
+
+  constructor(message: string, procedureName: string, scope: string, cause?: unknown) {
+    super(message, { cause })
+    this.procedureName = procedureName
+    this.scope = scope
+  }
+}
+```
+
+- [ ] **Step 5: Run tests to verify pass**
+
+```bash
+npx vitest run src/client/errors.test.ts
+```
+Expected: PASS.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/client/errors.ts src/client/errors.test.ts
+git commit -m "feat(client/errors): add cause arg to existing error classes"
+```
+
+### Task 2: Rename `ClientRequestError` → `ClientHttpError` with deprecated alias
+
+**Files:**
+- Modify: `src/client/errors.ts`
+- Modify: `src/client/index.ts`
+- Modify: `src/client/call.ts`, `src/client/stream.ts`, `src/client/error-dispatch.ts` (any other in-tree references)
+- Test: `src/client/errors.test.ts`
+
+- [ ] **Step 1: Find every in-tree reference to `ClientRequestError`**
+
+```bash
+grep -rn 'ClientRequestError' src/ --include='*.ts'
+```
+Note the file:line list — every one needs to point at `ClientHttpError` after the rename.
+
+- [ ] **Step 2: Write failing test for the new name + alias**
+
+Add to `src/client/errors.test.ts`:
+
+```ts
+import { ClientHttpError, ClientRequestError } from './errors.js'
+
+describe('ClientHttpError', () => {
+  it('exposes status, headers, body, procedureName, scope', () => {
+    const err = new ClientHttpError({
+      status: 500, headers: { 'x-trace': 'abc' }, body: { error: 'boom' },
+      procedureName: 'GetUser', scope: 'users',
+    })
+    expect(err.status).toBe(500)
+    expect(err.headers['x-trace']).toBe('abc')
+    expect(err.body).toEqual({ error: 'boom' })
+    expect(err.procedureName).toBe('GetUser')
+    expect(err.scope).toBe('users')
+    expect(err.name).toBe('ClientHttpError')
+  })
+
+  it('accepts cause', () => {
+    const cause = new Error('underlying')
+    const err = new ClientHttpError({
+      status: 500, headers: {}, body: null,
+      procedureName: 'X', scope: 'y', cause,
+    })
+    expect(err.cause).toBe(cause)
+  })
+})
+
+describe('ClientRequestError deprecated alias', () => {
+  it('is identical to ClientHttpError', () => {
+    expect(ClientRequestError).toBe(ClientHttpError)
+  })
+
+  it('instanceof check works against thrown ClientHttpError', () => {
+    // Consumers on the previous major used `catch (e) { if (e instanceof
+    // ClientRequestError) ... }`. The alias must keep that pattern working
+    // until the alias is removed in the next minor cycle's deprecation window.
+    const err = new ClientHttpError({
+      status: 500, headers: {}, body: null,
+      procedureName: 'X', scope: 'y',
+    })
+    expect(err instanceof ClientRequestError).toBe(true)
+  })
+})
+```
+
+- [ ] **Step 3: Run tests to verify they fail**
+
+```bash
+npx vitest run src/client/errors.test.ts -t 'ClientHttpError|alias'
+```
+Expected: FAIL — `ClientHttpError` does not exist.
+
+- [ ] **Step 4: Rename in `src/client/errors.ts`, add cause + alias**
+
+Replace the `ClientRequestError` class definition:
+
+```ts
+export class ClientHttpError extends Error {
+  readonly name = 'ClientHttpError'
+  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
+    cause?: unknown
+  }) {
+    super(
+      `${opts.procedureName} (${opts.scope}) failed with status ${opts.status}`,
+      { cause: opts.cause }
+    )
+    this.status = opts.status
+    this.headers = opts.headers
+    this.body = opts.body
+    this.procedureName = opts.procedureName
+    this.scope = opts.scope
+  }
+}
+
+/** @deprecated Renamed to `ClientHttpError`. The alias will be removed in the next major release. */
+export const ClientRequestError = ClientHttpError
+/** @deprecated Renamed to `ClientHttpError`. */
+export type ClientRequestError = ClientHttpError
+```
+
+- [ ] **Step 5: Update every in-tree consumer**
+
+For each file from Step 1, change `ClientRequestError` → `ClientHttpError` (use `Edit` tool's `replace_all` per file). Skip the deprecated-alias test itself.
+
+- [ ] **Step 6: Update `src/client/index.ts` exports**
+
+Ensure both `ClientHttpError` and `ClientRequestError` (alias) are exported.
+
+- [ ] **Step 7: Run full test suite to verify no regressions**
+
+```bash
+npm run test
+```
+Expected: PASS for everything except the next phases (which haven't shipped yet — but the rename should not break anything).
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add src/client/errors.ts src/client/errors.test.ts src/client/index.ts src/client/call.ts src/client/stream.ts src/client/error-dispatch.ts
+git commit -m "feat(client/errors)!: rename ClientRequestError to ClientHttpError
+
+Deprecated alias retained for one minor cycle.
+BREAKING CHANGE: ClientRequestError will be removed next major."
+```
+
+### Task 3: Add new framework error classes
+
+**Files:**
+- Modify: `src/client/errors.ts`
+- Test: `src/client/errors.test.ts`
+- Modify: `src/client/index.ts`
+
+- [ ] **Step 1: Write failing tests for new classes**
+
+Append to `src/client/errors.test.ts`:
+
+```ts
+import {
+  ClientNetworkError,
+  ClientTimeoutError,
+  ClientAbortError,
+  ClientParseError,
+} from './errors.js'
+
+describe('ClientNetworkError', () => {
+  it('carries procedureName, scope, cause', () => {
+    const cause = new TypeError('fetch failed')
+    const err = new ClientNetworkError({
+      procedureName: 'X', scope: 'y', cause,
+    })
+    expect(err.name).toBe('ClientNetworkError')
+    expect(err.procedureName).toBe('X')
+    expect(err.scope).toBe('y')
+    expect(err.cause).toBe(cause)
+  })
+})
+
+describe('ClientTimeoutError', () => {
+  it('carries timeoutMs', () => {
+    const err = new ClientTimeoutError({
+      procedureName: 'X', scope: 'y', timeoutMs: 5000,
+    })
+    expect(err.name).toBe('ClientTimeoutError')
+    expect(err.timeoutMs).toBe(5000)
+  })
+})
+
+describe('ClientAbortError', () => {
+  it('carries reason from abort signal', () => {
+    const err = new ClientAbortError({
+      procedureName: 'X', scope: 'y', reason: 'user-cancelled',
+    })
+    expect(err.name).toBe('ClientAbortError')
+    expect(err.reason).toBe('user-cancelled')
+  })
+})
+
+describe('ClientParseError', () => {
+  it('carries procedureName, scope, cause', () => {
+    const cause = new SyntaxError('Unexpected token')
+    const err = new ClientParseError({
+      procedureName: 'X', scope: 'y', cause,
+    })
+    expect(err.name).toBe('ClientParseError')
+    expect(err.cause).toBe(cause)
+  })
+})
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+```bash
+npx vitest run src/client/errors.test.ts -t 'ClientNetworkError|ClientTimeoutError|ClientAbortError|ClientParseError'
+```
+Expected: FAIL — classes don't exist.
+
+- [ ] **Step 3: Add the new classes**
+
+Append to `src/client/errors.ts`:
+
+```ts
+export class ClientNetworkError extends Error {
+  readonly name = 'ClientNetworkError'
+  readonly procedureName: string
+  readonly scope: string
+
+  constructor(opts: { procedureName: string; scope: string; cause?: unknown; message?: string }) {
+    super(opts.message ?? `${opts.procedureName} (${opts.scope}) failed: network error`, { cause: opts.cause })
+    this.procedureName = opts.procedureName
+    this.scope = opts.scope
+  }
+}
+
+export class ClientTimeoutError extends Error {
+  readonly name = 'ClientTimeoutError'
+  readonly procedureName: string
+  readonly scope: string
+  readonly timeoutMs: number
+
+  constructor(opts: { procedureName: string; scope: string; timeoutMs: number; cause?: unknown }) {
+    super(`${opts.procedureName} (${opts.scope}) timed out after ${opts.timeoutMs}ms`, { cause: opts.cause })
+    this.procedureName = opts.procedureName
+    this.scope = opts.scope
+    this.timeoutMs = opts.timeoutMs
+  }
+}
+
+export class ClientAbortError extends Error {
+  readonly name = 'ClientAbortError'
+  readonly procedureName: string
+  readonly scope: string
+  readonly reason: unknown
+
+  constructor(opts: { procedureName: string; scope: string; reason?: unknown; cause?: unknown }) {
+    super(`${opts.procedureName} (${opts.scope}) aborted`, { cause: opts.cause })
+    this.procedureName = opts.procedureName
+    this.scope = opts.scope
+    this.reason = opts.reason
+  }
+}
+
+export class ClientParseError extends Error {
+  readonly name = 'ClientParseError'
+  readonly procedureName: string
+  readonly scope: string
+
+  constructor(opts: { procedureName: string; scope: string; cause?: unknown; message?: string }) {
+    super(opts.message ?? `${opts.procedureName} (${opts.scope}) response could not be parsed`, { cause: opts.cause })
+    this.procedureName = opts.procedureName
+    this.scope = opts.scope
+  }
+}
+```
+
+- [ ] **Step 4: Export from `src/client/index.ts`**
+
+Add the four new classes to the existing barrel exports.
+
+- [ ] **Step 5: Run tests to verify pass**
+
+```bash
+npx vitest run src/client/errors.test.ts
+```
+Expected: PASS.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/client/errors.ts src/client/errors.test.ts src/client/index.ts
+git commit -m "feat(client/errors): add ClientNetworkError, ClientTimeoutError, ClientAbortError, ClientParseError"
+```
+
+---
+
+## Phase 2 — Default classifier
+
+### Task 4: Create `classify-error.ts` and default classifier
+
+**Files:**
+- Create: `src/client/classify-error.ts`
+- Test: `src/client/classify-error.test.ts`
+
+- [ ] **Step 1: Write failing tests**
+
+Create `src/client/classify-error.test.ts`:
+
+```ts
+import { describe, it, expect } from 'vitest'
+import { defaultClassifyError } from './classify-error.js'
+import {
+  ClientNetworkError,
+  ClientTimeoutError,
+  ClientAbortError,
+} from './errors.js'
+
+const meta = { procedureName: 'GetUser', scope: 'users' }
+
+describe('defaultClassifyError', () => {
+  it('classifies fetch TypeError as network', () => {
+    const result = defaultClassifyError(new TypeError('Failed to fetch'), { ...meta })
+    expect(result?.kind).toBe('network')
+    expect(result?.error).toBeInstanceOf(ClientNetworkError)
+    expect(result?.error.cause).toBeInstanceOf(TypeError)
+  })
+
+  it('classifies AbortError as timeout when timeout signal fired', () => {
+    const timeoutSignal = AbortSignal.timeout(0)
+    // wait a tick for the timeout to fire
+    return new Promise<void>((resolve) => setTimeout(() => {
+      const abortErr = new DOMException('aborted', 'AbortError')
+      const result = defaultClassifyError(abortErr, { ...meta, timeoutSignal, timeoutMs: 5000 })
+      expect(result?.kind).toBe('timeout')
+      expect(result?.error).toBeInstanceOf(ClientTimeoutError)
+      expect((result?.error as ClientTimeoutError).timeoutMs).toBe(5000)
+      resolve()
+    }, 1))
+  })
+
+  it('classifies AbortError as aborted when user signal fired', () => {
+    const userController = new AbortController()
+    userController.abort('user-cancelled')
+    const abortErr = new DOMException('aborted', 'AbortError')
+    const result = defaultClassifyError(abortErr, { ...meta, userSignal: userController.signal })
+    expect(result?.kind).toBe('aborted')
+    expect(result?.error).toBeInstanceOf(ClientAbortError)
+    expect((result?.error as ClientAbortError).reason).toBe('user-cancelled')
+  })
+
+  it('classifies AbortError as timeout when both fired (timeout precedence)', () => {
+    const timeoutSignal = AbortSignal.timeout(0)
+    const userController = new AbortController()
+    return new Promise<void>((resolve) => setTimeout(() => {
+      userController.abort('user')
+      const abortErr = new DOMException('aborted', 'AbortError')
+      const result = defaultClassifyError(abortErr, {
+        ...meta, timeoutSignal, timeoutMs: 1, userSignal: userController.signal,
+      })
+      expect(result?.kind).toBe('timeout')
+      resolve()
+    }, 1))
+  })
+
+  it('returns null for unknown errors', () => {
+    const result = defaultClassifyError(new Error('weird'), { ...meta })
+    expect(result).toBeNull()
+  })
+
+  it('returns null for non-Error throws', () => {
+    expect(defaultClassifyError('string-thrown', { ...meta })).toBeNull()
+    expect(defaultClassifyError(42, { ...meta })).toBeNull()
+  })
+})
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+```bash
+npx vitest run src/client/classify-error.test.ts
+```
+Expected: FAIL — file does not exist.
+
+- [ ] **Step 3: Implement `classify-error.ts`**
+
+Create `src/client/classify-error.ts`:
+
+```ts
+import {
+  ClientNetworkError,
+  ClientTimeoutError,
+  ClientAbortError,
+} from './errors.js'
+
+/**
+ * Classification context — supplies provenance the classifier needs that's
+ * not derivable from the raw error itself.
+ *
+ * `timeoutSignal` and `userSignal` let the classifier distinguish a timeout
+ * abort from a user-initiated abort when an `AbortError` lands.
+ */
+export interface ClassifyErrorContext {
+  procedureName: string
+  scope: string
+  timeoutSignal?: AbortSignal
+  userSignal?: AbortSignal
+  timeoutMs?: number
+}
+
+/**
+ * The output shape of a successful classification. Contract: `error` is
+ * always an `Error` subclass (the framework class). Non-`Error` values fall
+ * through to `null` (handled by `executeCall` as `kind: 'unknown'`).
+ */
+export interface ClassifiedError {
+  kind: string
+  error: Error
+}
+
+/**
+ * Adapter-provided classifier — runs before `defaultClassifyError`. Return
+ * `null` to fall through to the default. Adapter authors should compose with
+ * the default explicitly:
+ *
+ *     classifyError: (e, ctx) => myClassify(e, ctx) ?? defaultClassifyError(e, ctx)
+ */
+export type ErrorClassifier = (
+  raw: unknown,
+  ctx: ClassifyErrorContext,
+) => ClassifiedError | null
+
+/**
+ * Default classifier — recognizes:
+ *   - `TypeError` from fetch → `ClientNetworkError`
+ *   - `DOMException` with `name: 'AbortError'` + timeout-signal-aborted → `ClientTimeoutError`
+ *   - `DOMException` with `name: 'AbortError'` + user-signal-aborted → `ClientAbortError`
+ *
+ * Returns `null` for anything else. Timeout precedence: when both signals
+ * fired, classifies as `timeout`.
+ */
+export const defaultClassifyError: ErrorClassifier = (raw, ctx) => {
+  const meta = { procedureName: ctx.procedureName, scope: ctx.scope }
+
+  if (raw instanceof TypeError) {
+    return {
+      kind: 'network',
+      error: new ClientNetworkError({ ...meta, cause: raw, message: raw.message }),
+    }
+  }
+
+  if (
+    raw instanceof DOMException &&
+    raw.name === 'AbortError'
+  ) {
+    if (ctx.timeoutSignal?.aborted) {
+      return {
+        kind: 'timeout',
+        error: new ClientTimeoutError({
+          ...meta,
+          timeoutMs: ctx.timeoutMs ?? 0,
+          cause: raw,
+        }),
+      }
+    }
+    if (ctx.userSignal?.aborted) {
+      return {
+        kind: 'aborted',
+        error: new ClientAbortError({
+          ...meta,
+          reason: ctx.userSignal.reason,
+          cause: raw,
+        }),
+      }
+    }
+    // AbortError without a tracked source — treat as user abort with no reason.
+    return {
+      kind: 'aborted',
+      error: new ClientAbortError({ ...meta, cause: raw }),
+    }
+  }
+
+  return null
+}
+```
+
+- [ ] **Step 4: Run tests to verify pass**
+
+```bash
+npx vitest run src/client/classify-error.test.ts
+```
+Expected: PASS.
+
+- [ ] **Step 5: Export classifier from `src/client/index.ts`**
+
+Add: `export { defaultClassifyError, type ErrorClassifier, type ClassifyErrorContext, type ClassifiedError } from './classify-error.js'`
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/client/classify-error.ts src/client/classify-error.test.ts src/client/index.ts
+git commit -m "feat(client): add error classifier with default platform-error coverage"
+```
+
+---
+
+## Phase 3 — Wire classifier into runtime
+
+### Task 5: Refactor `resolveSignal` to expose source signals
+
+**Files:**
+- Modify: `src/client/resolve-options.ts`
+- Test: `src/client/resolve-options.test.ts`
+
+The classifier needs the original timeout + user signals (not just the combined `AbortSignal.any` result). This task surfaces them.
+
+- [ ] **Step 1: Write failing test**
+
+Add to `src/client/resolve-options.test.ts`:
+
+```ts
+import { resolveSignalSources } from './resolve-options.js'
+
+describe('resolveSignalSources', () => {
+  it('returns timeout signal alongside combined', () => {
+    const result = resolveSignalSources(undefined, { timeout: 100 })
+    expect(result.timeoutSignal).toBeInstanceOf(AbortSignal)
+    expect(result.timeoutMs).toBe(100)
+    expect(result.combined).toBeInstanceOf(AbortSignal)
+    expect(result.userSignal).toBeUndefined()
+  })
+
+  it('returns user signal alongside combined', () => {
+    const ctrl = new AbortController()
+    const result = resolveSignalSources(undefined, { signal: ctrl.signal })
+    expect(result.userSignal).toBe(ctrl.signal)
+    expect(result.timeoutSignal).toBeUndefined()
+  })
+
+  it('combines both via AbortSignal.any', () => {
+    const ctrl = new AbortController()
+    const result = resolveSignalSources(undefined, { signal: ctrl.signal, timeout: 100 })
+    expect(result.timeoutSignal).toBeInstanceOf(AbortSignal)
+    expect(result.userSignal).toBe(ctrl.signal)
+    expect(result.combined).toBeInstanceOf(AbortSignal)
+  })
+
+  it('returns undefined combined when no signals', () => {
+    const result = resolveSignalSources(undefined, undefined)
+    expect(result.combined).toBeUndefined()
+  })
+})
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+```bash
+npx vitest run src/client/resolve-options.test.ts -t 'resolveSignalSources'
+```
+Expected: FAIL.
+
+- [ ] **Step 3: Implement `resolveSignalSources`**
+
+Add to `src/client/resolve-options.ts`:
+
+```ts
+export interface SignalSources {
+  combined?: AbortSignal
+  timeoutSignal?: AbortSignal
+  userSignal?: AbortSignal
+  timeoutMs?: number
+}
+
+export function resolveSignalSources(
+  defaults: ProcedureCallDefaults | undefined,
+  options: ProcedureCallOptions | undefined,
+): SignalSources {
+  const userSignal = options?.signal ?? defaults?.signal
+  const timeoutMs = options?.timeout ?? defaults?.timeout
+  const timeoutSignal =
+    timeoutMs != null && timeoutMs > 0 ? AbortSignal.timeout(timeoutMs) : undefined
+
+  const signals: AbortSignal[] = []
+  if (userSignal) signals.push(userSignal)
+  if (timeoutSignal) signals.push(timeoutSignal)
+
+  let combined: AbortSignal | undefined
+  if (signals.length === 1) combined = signals[0]
+  else if (signals.length > 1) combined = AbortSignal.any(signals)
+
+  return { combined, timeoutSignal, userSignal, timeoutMs }
+}
+```
+
+- [ ] **Step 4: Refactor `applyRequestOptions` to use `resolveSignalSources` and return both the request and the sources**
+
+Replace `applyRequestOptions`:
+
+```ts
+export interface ApplyRequestOptionsResult {
+  request: AdapterRequest
+  signalSources: SignalSources
+}
+
+export function applyRequestOptions(
+  request: AdapterRequest,
+  defaults: ProcedureCallDefaults | undefined,
+  options: ProcedureCallOptions | undefined,
+): ApplyRequestOptionsResult {
+  const signalSources = resolveSignalSources(defaults, options)
+  const resolvedHeaders = resolveHeaders(defaults, options)
+  const meta = resolveMeta(defaults, options)
+
+  const headers =
+    resolvedHeaders || request.headers
+      ? { ...resolvedHeaders, ...request.headers }
+      : undefined
+
+  return {
+    request: { ...request, headers, signal: signalSources.combined, meta },
+    signalSources,
+  }
+}
+```
+
+Keep `resolveSignal` exported as a thin wrapper for backwards-compat with anyone importing it directly:
+
+```ts
+export function resolveSignal(
+  defaults: ProcedureCallDefaults | undefined,
+  options: ProcedureCallOptions | undefined,
+): AbortSignal | undefined {
+  return resolveSignalSources(defaults, options).combined
+}
+```
+
+- [ ] **Step 5: Update existing `resolve-options.test.ts` tests to handle the new return shape**
+
+Find every `applyRequestOptions(...)` call in tests and unwrap `.request`. Easiest: introduce a helper at top of test file:
+```ts
+const apply = (req, d, o) => applyRequestOptions(req, d, o).request
+```
+Then `replace_all` `applyRequestOptions(` with `apply(` *only* in test files (not in src!).
+
+- [ ] **Step 6: Update `executeCall` and `executeStream` callers to destructure `request` from the return value**
+
+In `src/client/call.ts`, change:
+```ts
+request = applyRequestOptions(request, defaults, options)
+```
+To:
+```ts
+const applied = applyRequestOptions(request, defaults, options)
+request = applied.request
+const signalSources = applied.signalSources  // used in Task 6
+```
+
+Same change in `src/client/stream.ts`.
+
+- [ ] **Step 7: Verify no stale `applyRequestOptions(` callers were missed**
+
+```bash
+grep -rn 'applyRequestOptions(' src/ --include='*.ts'
+```
+Expected output: only the implementation in `src/client/resolve-options.ts` and the in-test helper `apply` definition. If any other test file still references `applyRequestOptions(...)` directly without the `.request` unwrap, fix before continuing.
+
+- [ ] **Step 8: Run full suite to confirm no regressions**
+
+```bash
+npm run test
+```
+Expected: PASS.
+
+- [ ] **Step 9: Commit**
+
+```bash
+git add src/client/resolve-options.ts src/client/resolve-options.test.ts src/client/call.ts src/client/stream.ts
+git commit -m "refactor(client): expose signal sources from applyRequestOptions
+
+Lets the classifier distinguish timeout abort from user abort by
+checking which underlying signal fired first."
+```
+
+### Task 6: Wire classifier into `executeCall`
+
+**Files:**
+- Modify: `src/client/call.ts`
+- Modify: `src/client/types.ts` (extend `ClientAdapter`)
+- Test: `src/client/call.test.ts`
+
+- [ ] **Step 1: Extend `ClientAdapter` interface with optional `classifyError`**
+
+In `src/client/types.ts`:
+
+```ts
+import type { ErrorClassifier } from './classify-error.js'
+
+export interface ClientAdapter {
+  request(config: AdapterRequest): Promise<AdapterResponse>
+  stream(config: AdapterRequest): Promise<AdapterStreamResponse>
+  /** Optional adapter-level error classifier — composes with `defaultClassifyError`. */
+  classifyError?: ErrorClassifier
+}
+```
+
+- [ ] **Step 2: Write failing test for normalized errors**
+
+Add to `src/client/call.test.ts`:
+
+```ts
+import {
+  ClientNetworkError,
+  ClientTimeoutError,
+  ClientAbortError,
+  ClientHttpError,
+} from './errors.js'
+
+describe('executeCall classifier integration', () => {
+  it('throws ClientNetworkError when adapter throws TypeError', async () => {
+    const adapter: ClientAdapter = {
+      request: vi.fn(async () => { throw new TypeError('Failed to fetch') }),
+      stream: vi.fn(async () => { throw new Error('n/a') }),
+    }
+    await expect(run({ adapter })).rejects.toBeInstanceOf(ClientNetworkError)
+  })
+
+  it('throws ClientTimeoutError when adapter rejects with AbortError on timeout signal', async () => {
+    const adapter: ClientAdapter = {
+      request: vi.fn(async () => { throw new DOMException('aborted', 'AbortError') }),
+      stream: vi.fn(async () => { throw new Error('n/a') }),
+    }
+    await expect(
+      run({ adapter, options: { timeout: 1 } })
+    ).rejects.toBeInstanceOf(ClientTimeoutError)
+  })
+
+  it('uses adapter-provided classifier first', async () => {
+    class CustomError extends Error { readonly name = 'CustomError' }
+    const adapter: ClientAdapter = {
+      request: vi.fn(async () => { throw new TypeError('x') }),
+      stream: vi.fn(async () => { throw new Error('n/a') }),
+      classifyError: () => ({ kind: 'custom', error: new CustomError('classified') }),
+    }
+    await expect(run({ adapter })).rejects.toBeInstanceOf(CustomError)
+  })
+
+  it('still throws ClientHttpError for non-2xx responses (registry path unchanged)', async () => {
+    const adapter = makeAdapter({ status: 500, body: { message: 'oops' } })
+    await expect(run({ adapter })).rejects.toBeInstanceOf(ClientHttpError)
+  })
+
+  it('hooks see the normalized error, not the raw TypeError', async () => {
+    const seen: unknown[] = []
+    const adapter: ClientAdapter = {
+      request: vi.fn(async () => { throw new TypeError('x') }),
+      stream: vi.fn(async () => { throw new Error('n/a') }),
+    }
+    const hooks = { onError: ({ error }: { error: unknown }) => { seen.push(error) } }
+    await expect(run({ adapter, hooks })).rejects.toBeInstanceOf(ClientNetworkError)
+    expect(seen[0]).toBeInstanceOf(ClientNetworkError)
+  })
+})
+```
+
+- [ ] **Step 3: Run tests to verify they fail**
+
+```bash
+npx vitest run src/client/call.test.ts -t 'classifier integration'
+```
+Expected: FAIL.
+
+- [ ] **Step 4: Update `executeCall` to classify adapter errors**
+
+Replace the try/catch around `adapter.request()` in `src/client/call.ts`:
+
+```ts
+import { defaultClassifyError } from './classify-error.js'
+// ... existing imports ...
+
+// inside executeCall, after `applied = applyRequestOptions(...)`:
+
+let response
+try {
+  response = await adapter.request(request)
+} catch (rawErr) {
+  // Classify: adapter classifier first, default second, fallthrough = re-throw raw
+  const classifyCtx = {
+    procedureName: descriptor.name,
+    scope: descriptor.scope,
+    timeoutSignal: signalSources.timeoutSignal,
+    userSignal: signalSources.userSignal,
+    timeoutMs: signalSources.timeoutMs,
+  }
+  const classified =
+    adapter.classifyError?.(rawErr, classifyCtx) ??
+    defaultClassifyError(rawErr, classifyCtx)
+  const finalError = classified?.error ?? rawErr
+
+  // Hooks see the normalized error
+  await runOnError(
+    { procedureName: descriptor.name, scope: descriptor.scope, request, error: finalError },
+    hooks,
+    options,
+  )
+  throw finalError
+}
+```
+
+- [ ] **Step 5: Run tests to verify pass**
+
+```bash
+npx vitest run src/client/call.test.ts
+```
+Expected: PASS.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/client/types.ts src/client/call.ts src/client/call.test.ts
+git commit -m "feat(client/call): classify adapter errors into framework classes
+
+executeCall now wraps adapter throws in ClientNetworkError /
+ClientTimeoutError / ClientAbortError via the classifier composition
+(adapter classifier > default > fallthrough). Hooks receive the
+normalized error.
+
+BREAKING CHANGE: Raw DOMException / TypeError no longer reach
+consumer catch blocks — the framework throws normalized classes.
+Migration: catch the framework class instead (instanceof
+ClientTimeoutError, etc.)."
+```
+
+### Task 7: Wire classifier into `executeStream` pre-stream path
+
+**Files:**
+- Modify: `src/client/stream.ts`
+- Test: `src/client/stream.test.ts`
+
+- [ ] **Step 1: Write failing test**
+
+Add to `src/client/stream.test.ts` (mirror the call.test.ts pattern, scoped to pre-stream errors only):
+
+```ts
+import { ClientNetworkError } from './errors.js'
+
+describe('executeStream classifier integration', () => {
+  it('classifies pre-stream TypeError as ClientNetworkError', async () => {
+    const adapter: ClientAdapter = {
+      request: vi.fn(async () => { throw new Error('n/a') }),
+      stream: vi.fn(async () => { throw new TypeError('Failed to fetch') }),
+    }
+    await expect(runStream({ adapter })).rejects.toBeInstanceOf(ClientNetworkError)
+  })
+})
+```
+
+(Use the existing `runStream` helper or add one mirroring `run`.)
+
+- [ ] **Step 2: Run to verify fail**
+
+```bash
+npx vitest run src/client/stream.test.ts -t 'classifier integration'
+```
+
+- [ ] **Step 3: Apply the same classifier composition to the pre-stream try/catch**
+
+In `src/client/stream.ts`, update the try/catch around `adapter.stream()` identically to Task 6 Step 4 (using `signalSources` from the applied options).
+
+- [ ] **Step 4: Run to verify pass**
+
+```bash
+npx vitest run src/client/stream.test.ts
+```
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/client/stream.ts src/client/stream.test.ts
+git commit -m "feat(client/stream): classify pre-stream adapter errors
+
+Mid-stream errors are unchanged — only the pre-stream connection
+path uses the classifier."
+```
+
+### Task 8: Wire classifier into `createFetchAdapter`
+
+**Files:**
+- Modify: `src/client/fetch-adapter.ts`
+- Test: `src/client/fetch-adapter.test.ts`
+
+- [ ] **Step 1: Write failing test**
+
+Add to `src/client/fetch-adapter.test.ts`:
+
+```ts
+import { defaultClassifyError } from './classify-error.js'
+
+describe('createFetchAdapter classifyError', () => {
+  it('passes through to adapter.classifyError', () => {
+    const customClassifier = vi.fn()
+    const adapter = createFetchAdapter({ classifyError: customClassifier })
+    expect(adapter.classifyError).toBe(customClassifier)
+  })
+
+  it('does not set classifyError when not provided', () => {
+    const adapter = createFetchAdapter()
+    expect(adapter.classifyError).toBeUndefined()
+  })
+})
+```
+
+- [ ] **Step 2: Run to verify fail**
+
+```bash
+npx vitest run src/client/fetch-adapter.test.ts -t 'classifyError'
+```
+
+- [ ] **Step 3: Update `createFetchAdapter`**
+
+In `src/client/fetch-adapter.ts`:
+
+```ts
+export interface FetchAdapterConfig {
+  headers?: Record<string, string>
+  classifyError?: ErrorClassifier
+}
+
+export function createFetchAdapter(config?: FetchAdapterConfig): ClientAdapter {
+  // ... existing body ...
+  return {
+    async request(req) { /* existing */ },
+    async stream(req) { /* existing */ },
+    classifyError: config?.classifyError,
+  }
+}
+```
+
+- [ ] **Step 4: Run to verify pass**
+
+```bash
+npx vitest run src/client/fetch-adapter.test.ts
+```
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/client/fetch-adapter.ts src/client/fetch-adapter.test.ts
+git commit -m "feat(client/fetch-adapter): accept optional classifyError config"
+```
+
+---
+
+## Phase 4 — Result type derivation
+
+### Task 8.5: Enable vitest type-checking for `.test-d.ts` files
+
+**Files:**
+- Modify: `vitest.config.ts`
+
+The `.test-d.ts` files in Tasks 9, 10 use `expectTypeOf` from vitest. These only run type-level assertions when vitest's `typecheck` mode is enabled — without it, the files are parsed but type errors are silently ignored. This task wires it up before the first `.test-d.ts` lands.
+
+- [ ] **Step 1: Update `vitest.config.ts`**
+
+```ts
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    exclude: ['**/node_modules/**', '**/build/**', '**/dist/**'],
+    typecheck: {
+      enabled: true,
+      include: ['**/*.test-d.ts'],
+      tsconfig: './tsconfig.json',
+    },
+  },
+})
+```
+
+- [ ] **Step 2: Sanity check — write a deliberately-failing type-test, run it, confirm vitest catches it, then revert**
+
+```bash
+cat > /tmp/sanity.test-d.ts <<'EOF'
+import { expectTypeOf } from 'vitest'
+expectTypeOf<string>().toEqualTypeOf<number>()  // should fail
+EOF
+cp /tmp/sanity.test-d.ts src/client/sanity.test-d.ts
+npx vitest run src/client/sanity.test-d.ts
+# Expected: FAIL with type-mismatch error
+rm src/client/sanity.test-d.ts
+```
+
+If this passes silently, the typecheck wiring isn't active — debug before proceeding.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add vitest.config.ts
+git commit -m "test(vitest): enable typecheck for .test-d.ts files
+
+Required so the type-level tests added in subsequent tasks
+(Result, ResultNoTyped, ClientErrorMap augmentation) actually
+run their assertions."
+```
+
+### Task 9: Add `ClientErrorMap`, `Result`, `ResultNoTyped`, `FrameworkFailure`
+
+**Files:**
+- Modify: `src/client/types.ts`
+- Test: `src/client/result-type.test-d.ts` (type-only test)
+- Modify: `src/client/index.ts`
+
+- [ ] **Step 1: Add the type definitions to `src/client/types.ts`**
+
+Append:
+
+```ts
+import type {
+  ClientHttpError,
+  ClientNetworkError,
+  ClientTimeoutError,
+  ClientAbortError,
+  ClientParseError,
+  ClientPathParamError,
+} from './errors.js'
+
+/**
+ * Augmentable map of `kind` discriminant → error class for the framework's
+ * non-typed failure categories. Mirrors the `RequestMeta` augmentation
+ * pattern: extend via TypeScript declaration merging.
+ *
+ * @example
+ * ```ts
+ * declare module 'ts-procedures/client' {
+ *   interface ClientErrorMap {
+ *     rateLimited: MyRateLimitError
+ *     paymentRequired: MyPaymentError
+ *   }
+ * }
+ * ```
+ *
+ * **`'typed'` is reserved** — it's the discriminant used by `Result` for
+ * route-declared errors and is not part of `ClientErrorMap`. Attempting to
+ * register it produces a TS error about overlapping discriminants.
+ */
+export interface ClientErrorMap {
+  http: ClientHttpError
+  network: ClientNetworkError
+  timeout: ClientTimeoutError
+  aborted: ClientAbortError
+  parse: ClientParseError
+  usage: ClientPathParamError
+  unknown: unknown
+}
+
+/** Distributed union of every framework failure kind. */
+export type FrameworkFailure = {
+  [K in keyof ClientErrorMap]: { ok: false; kind: K; error: ClientErrorMap[K] }
+}[keyof ClientErrorMap]
+
+/**
+ * Discriminated result type for the `.safe()` form. `kind: 'typed'` carries
+ * route-declared errors (registry-dispatched); other kinds carry framework
+ * failures. Use `ResultNoTyped<T>` for routes without declared errors.
+ */
+export type Result<T, ETyped> =
+  | { ok: true; value: T }
+  | { ok: false; kind: 'typed'; error: ETyped }
+  | FrameworkFailure
+
+/**
+ * `Result` for routes that don't declare typed errors. Omits the `'typed'`
+ * arm entirely so IDE hovers stay clean (TS doesn't collapse `never`-payload
+ * arms in tooltip output).
+ */
+export type ResultNoTyped<T> =
+  | { ok: true; value: T }
+  | FrameworkFailure
+```
+
+- [ ] **Step 2: Create `src/client/result-type.test-d.ts`**
+
+Type-level test using `expectTypeOf` from vitest:
+
+```ts
+import { describe, it, expectTypeOf } from 'vitest'
+import type {
+  Result,
+  ResultNoTyped,
+  ClientErrorMap,
+} from './types.js'
+import type {
+  ClientHttpError,
+  ClientNetworkError,
+  ClientTimeoutError,
+  ClientAbortError,
+  ClientParseError,
+  ClientPathParamError,
+} from './errors.js'
+
+describe('Result type', () => {
+  it('includes ok=true with value', () => {
+    type R = Result<number, Error>
+    type Ok = Extract<R, { ok: true }>
+    expectTypeOf<Ok['value']>().toEqualTypeOf<number>()
+  })
+
+  it('includes typed kind with ETyped error', () => {
+    class MyTyped extends Error {}
+    type R = Result<number, MyTyped>
+    type Typed = Extract<R, { kind: 'typed' }>
+    expectTypeOf<Typed['error']>().toEqualTypeOf<MyTyped>()
+  })
+
+  it('includes every default framework kind', () => {
+    type R = Result<number, Error>
+    expectTypeOf<Extract<R, { kind: 'http' }>['error']>().toEqualTypeOf<ClientHttpError>()
+    expectTypeOf<Extract<R, { kind: 'network' }>['error']>().toEqualTypeOf<ClientNetworkError>()
+    expectTypeOf<Extract<R, { kind: 'timeout' }>['error']>().toEqualTypeOf<ClientTimeoutError>()
+    expectTypeOf<Extract<R, { kind: 'aborted' }>['error']>().toEqualTypeOf<ClientAbortError>()
+    expectTypeOf<Extract<R, { kind: 'parse' }>['error']>().toEqualTypeOf<ClientParseError>()
+    expectTypeOf<Extract<R, { kind: 'usage' }>['error']>().toEqualTypeOf<ClientPathParamError>()
+    expectTypeOf<Extract<R, { kind: 'unknown' }>['error']>().toEqualTypeOf<unknown>()
+  })
+})
+
+describe('ResultNoTyped', () => {
+  it('omits the typed arm', () => {
+    type R = ResultNoTyped<number>
+    type Typed = Extract<R, { kind: 'typed' }>
+    expectTypeOf<Typed>().toEqualTypeOf<never>()
+  })
+})
+```
+
+- [ ] **Step 3: Run type-test**
+
+```bash
+npx vitest run src/client/result-type.test-d.ts
+```
+Expected: PASS (vitest runs `.test-d.ts` files; `expectTypeOf` is type-checked at build time).
+
+- [ ] **Step 4: Re-export from `src/client/index.ts`**
+
+Add:
+```ts
+export type {
+  ClientErrorMap,
+  FrameworkFailure,
+  Result,
+  ResultNoTyped,
+} from './types.js'
+```
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/client/types.ts src/client/result-type.test-d.ts src/client/index.ts
+git commit -m "feat(client/types): add Result, ResultNoTyped, ClientErrorMap"
+```
+
+### Task 10: Augmentation type-test
+
+**Files:**
+- Create: `src/client/augment-error-map.test-d.ts`
+
+- [ ] **Step 1: Write the augmentation test**
+
+```ts
+import { describe, it, expectTypeOf } from 'vitest'
+import type { Result } from './types.js'
+
+class RateLimitError extends Error {
+  constructor(public retryAfter: number) { super('rate limited') }
+}
+
+declare module './types.js' {
+  interface ClientErrorMap {
+    rateLimited: RateLimitError
+  }
+}
+
+describe('ClientErrorMap augmentation', () => {
+  it('adds rateLimited kind to Result', () => {
+    type R = Result<number, Error>
+    type RateLimited = Extract<R, { kind: 'rateLimited' }>
+    expectTypeOf<RateLimited['error']>().toEqualTypeOf<RateLimitError>()
+  })
+})
+```
+
+- [ ] **Step 2: Run to verify pass**
+
+```bash
+npx vitest run src/client/augment-error-map.test-d.ts
+```
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add src/client/augment-error-map.test-d.ts
+git commit -m "test(client): verify ClientErrorMap augmentation widens Result"
+```
+
+---
+
+## Phase 5 — `executeSafeCall` and `ClientInstance.safeCall`
+
+**Phase dependencies:** Requires Phase 3 (classifier wired into `executeCall` — Tasks 5, 6) and Phase 4 (Result types — Tasks 8.5, 9, 10) complete. Do not start Task 11 until both phases are committed.
+
+### Task 11: Implement `executeSafeCall`
+
+**Files:**
+- Modify: `src/client/call.ts`
+- Modify: `src/client/types.ts`
+- Create: `src/client/safe-call.test.ts`
+- Modify: `src/client/index.ts` (re-import as needed)
+
+- [ ] **Step 1: Extend `ClientInstance` interface**
+
+In `src/client/types.ts`:
+
+```ts
+export interface ClientInstance {
+  // ... existing ...
+  safeCall<TResponse, ETyped = never>(
+    descriptor: CallDescriptor,
+    options?: ProcedureCallOptions,
+  ): Promise<Result<TResponse, ETyped>>
+}
+```
+
+- [ ] **Step 2: Write failing tests**
+
+Create `src/client/safe-call.test.ts`:
+
+```ts
+import { describe, it, expect, vi } from 'vitest'
+import { executeSafeCall } from './call.js'
+import {
+  ClientHttpError,
+  ClientNetworkError,
+  ClientTimeoutError,
+  ClientAbortError,
+  ClientPathParamError,
+} from './errors.js'
+import type { ClientAdapter, CallDescriptor } from './types.js'
+
+const baseDescriptor: CallDescriptor = {
+  name: 'GetUser', scope: 'users', path: '/users/:id', method: 'GET',
+  kind: 'rpc', params: { id: '42' },
+}
+
+const ok = (body: unknown): ClientAdapter => ({
+  request: vi.fn(async () => ({ status: 200, headers: {}, body })),
+  stream: vi.fn(async () => { throw new Error('n/a') }),
+})
+
+const failWith = (err: unknown): ClientAdapter => ({
+  request: vi.fn(async () => { throw err }),
+  stream: vi.fn(async () => { throw new Error('n/a') }),
+})
+
+describe('executeSafeCall', () => {
+  it('returns ok=true with value on success', async () => {
+    const r = await executeSafeCall({
+      descriptor: baseDescriptor,
+      basePath: 'https://api.x',
+      adapter: ok({ id: '42' }),
+      hooks: {},
+    })
+    expect(r.ok).toBe(true)
+    if (r.ok) expect(r.value).toEqual({ id: '42' })
+  })
+
+  it("returns kind='http' on non-2xx without registry match", async () => {
+    const r = await executeSafeCall({
+      descriptor: baseDescriptor,
+      basePath: 'https://api.x',
+      adapter: {
+        request: vi.fn(async () => ({ status: 500, headers: {}, body: { msg: 'oops' } })),
+        stream: vi.fn(async () => { throw new Error('n/a') }),
+      },
+      hooks: {},
+    })
+    expect(r.ok).toBe(false)
+    if (!r.ok) {
+      expect(r.kind).toBe('http')
+      expect(r.error).toBeInstanceOf(ClientHttpError)
+    }
+  })
+
+  it("returns kind='network' on TypeError", async () => {
+    const r = await executeSafeCall({
+      descriptor: baseDescriptor,
+      basePath: 'https://api.x',
+      adapter: failWith(new TypeError('Failed to fetch')),
+      hooks: {},
+    })
+    expect(r.ok).toBe(false)
+    if (!r.ok) {
+      expect(r.kind).toBe('network')
+      expect(r.error).toBeInstanceOf(ClientNetworkError)
+    }
+  })
+
+  it("returns kind='timeout' when timeout fires", async () => {
+    const r = await executeSafeCall({
+      descriptor: baseDescriptor,
+      basePath: 'https://api.x',
+      adapter: failWith(new DOMException('aborted', 'AbortError')),
+      hooks: {},
+      options: { timeout: 1 },
+    })
+    if (!r.ok) {
+      expect(r.kind).toBe('timeout')
+      expect(r.error).toBeInstanceOf(ClientTimeoutError)
+    }
+  })
+
+  it("returns kind='aborted' when user signal fires", async () => {
+    const ctrl = new AbortController()
+    ctrl.abort('user')
+    const r = await executeSafeCall({
+      descriptor: baseDescriptor,
+      basePath: 'https://api.x',
+      adapter: failWith(new DOMException('aborted', 'AbortError')),
+      hooks: {},
+      options: { signal: ctrl.signal },
+    })
+    if (!r.ok) {
+      expect(r.kind).toBe('aborted')
+      expect(r.error).toBeInstanceOf(ClientAbortError)
+    }
+  })
+
+  it("returns kind='usage' on pre-adapter ClientPathParamError, does NOT invoke onError", async () => {
+    // Spec contract: pre-adapter usage errors bypass the classifier AND the
+    // onError hook entirely. Path 1 of the three failure-source paths.
+    const seen: unknown[] = []
+    const r = await executeSafeCall({
+      // path requires :id but params don't supply it
+      descriptor: { ...baseDescriptor, params: {} },
+      basePath: 'https://api.x',
+      adapter: ok({}),
+      hooks: { onError: ({ error }) => { seen.push(error) } },
+    })
+    if (!r.ok) {
+      expect(r.kind).toBe('usage')
+      expect(r.error).toBeInstanceOf(ClientPathParamError)
+    }
+    // onError must NOT fire — this is by design (per spec architectural decision #1).
+    expect(seen).toEqual([])
+  })
+
+  it("returns kind='unknown' for unrecognized throws", async () => {
+    const r = await executeSafeCall({
+      descriptor: baseDescriptor,
+      basePath: 'https://api.x',
+      adapter: failWith('weird-string-throw'),
+      hooks: {},
+    })
+    if (!r.ok) {
+      expect(r.kind).toBe('unknown')
+      expect(r.error).toBe('weird-string-throw')
+    }
+  })
+
+  it('invokes onError hook on failure (cross-cutting telemetry)', async () => {
+    const seen: unknown[] = []
+    const r = await executeSafeCall({
+      descriptor: baseDescriptor,
+      basePath: 'https://api.x',
+      adapter: failWith(new TypeError('x')),
+      hooks: { onError: ({ error }) => { seen.push(error) } },
+    })
+    expect(r.ok).toBe(false)
+    expect(seen[0]).toBeInstanceOf(ClientNetworkError)
+  })
+})
+```
+
+- [ ] **Step 3: Run to verify fail**
+
+```bash
+npx vitest run src/client/safe-call.test.ts
+```
+Expected: FAIL — `executeSafeCall` does not exist.
+
+- [ ] **Step 4: Implement `executeSafeCall`**
+
+Add to `src/client/call.ts`:
+
+```ts
+import type { Result, ClientErrorMap, FrameworkFailure } from './types.js'
+import {
+  ClientHttpError,
+  ClientNetworkError,
+  ClientTimeoutError,
+  ClientAbortError,
+  ClientParseError,
+  ClientPathParamError,
+} from './errors.js'
+
+/**
+ * Wraps `executeCall` and returns a discriminated `Result` instead of throwing.
+ *
+ * Three failure-source paths map to distinct kinds:
+ *   1. Pre-adapter throw (e.g. `ClientPathParamError`) → `kind: 'usage'`
+ *   2. Adapter throw, classified → `kind: 'network' | 'timeout' | 'aborted' | <custom> | 'unknown'`
+ *   3. Adapter returns non-2xx → `kind: 'typed'` (registry match) or `kind: 'http'`
+ *
+ * `onError` hook fires on every failure path (cross-cutting telemetry).
+ */
+export async function executeSafeCall<TResponse, ETyped = never>(
+  config: ExecuteCallConfig,
+): Promise<Result<TResponse, ETyped>> {
+  try {
+    const value = await executeCall<TResponse>(config)
+    return { ok: true, value }
+  } catch (err) {
+    return classifyThrownError<ETyped>(err)
+  }
+}
+
+function classifyThrownError<ETyped>(err: unknown): Result<never, ETyped> {
+  // Path 1: pre-adapter usage
+  if (err instanceof ClientPathParamError) {
+    return { ok: false, kind: 'usage', error: err }
+  }
+  // Path 3: post-status-check (registry or fallback)
+  if (err instanceof ClientHttpError) {
+    return { ok: false, kind: 'http', error: err }
+  }
+  // Path 2: classifier output (already normalized by executeCall)
+  if (err instanceof ClientNetworkError) {
+    return { ok: false, kind: 'network', error: err }
+  }
+  if (err instanceof ClientTimeoutError) {
+    return { ok: false, kind: 'timeout', error: err }
+  }
+  if (err instanceof ClientAbortError) {
+    return { ok: false, kind: 'aborted', error: err }
+  }
+  if (err instanceof ClientParseError) {
+    return { ok: false, kind: 'parse', error: err }
+  }
+  // Registry-dispatched typed error (any other Error subclass thrown by the registry)
+  if (err instanceof Error && (err as { __tsProceduresTyped?: boolean }).__tsProceduresTyped) {
+    return { ok: false, kind: 'typed', error: err as ETyped }
+  }
+  // Custom adapter-classified error — has a known kind tag.
+  // The cast is intentional: the framework knows only the default ClientErrorMap
+  // keys, but consumer-augmented kinds are valid at the consumer's site (where
+  // the augmented map is in scope). The runtime kind string is whatever the
+  // adapter classifier returned; we trust it to match a registered entry.
+  if (err instanceof Error && typeof (err as { __tsProceduresKind?: string }).__tsProceduresKind === 'string') {
+    const kind = (err as { __tsProceduresKind: string }).__tsProceduresKind
+    return { ok: false, kind: kind as keyof ClientErrorMap, error: err } as FrameworkFailure
+  }
+  // Fallthrough
+  return { ok: false, kind: 'unknown', error: err }
+}
+```
+
+**Note on the `__tsProceduresTyped` / `__tsProceduresKind` tagging:** the simplest way for `executeSafeCall` to distinguish "a generated typed error class" from "a custom-classified error" from "a fallthrough" is for the call-site that *threw* to mark the error before re-throwing. The tags are deliberate internal implementation details — add a brief comment on each tag site explaining that they exist solely to bridge information from the throw-site to `classifyThrownError` without re-doing classification work. Do NOT add tagging to `executeStream` (Task 7) "for symmetry" — streams have no `.safe` form, so `classifyThrownError` is never called on stream-thrown errors and the tags would be inert overhead. Two changes follow:
+
+(a) In `executeCall`, when the registry dispatches a typed error, tag it:
+```ts
+if (typed) {
+  ;(typed as { __tsProceduresTyped?: boolean }).__tsProceduresTyped = true
+  throw typed
+}
+```
+
+(b) In `executeCall`, when the classifier returns a custom kind (not one of the default kinds), tag with the kind:
+```ts
+if (classified) {
+  const defaultKinds = new Set(['network', 'timeout', 'aborted'])
+  if (!defaultKinds.has(classified.kind)) {
+    ;(classified.error as { __tsProceduresKind?: string }).__tsProceduresKind = classified.kind
+  }
+  // Hooks see normalized error, then throw
+  await runOnError(...)
+  throw classified.error
+}
+```
+
+Update `executeCall` accordingly. (This is a behavior detail not present in the spec — we picked the simplest reliable mechanism. Document the field as internal in the source.)
+
+- [ ] **Step 5: Run tests to verify pass**
+
+```bash
+npx vitest run src/client/safe-call.test.ts
+```
+Expected: PASS.
+
+- [ ] **Step 6: Wire `executeSafeCall` into `ClientInstance` via `createClient`**
+
+**Read `src/client/index.ts` first** — the `createClient` factory composes its `call` closure from several local bindings (`basePath`, `adapter`, `hooks`, `globalDefaults`, optional `errorRegistry`). The `safeCall` wiring must reuse exactly the same bindings so behavior is identical except for the throw-vs-return difference.
+
+```bash
+sed -n '1,90p' src/client/index.ts
+```
+
+Add `safeCall` on the returned `ClientInstance` mirroring the existing `call` wiring (use the same field names that `createClient` actually uses — the snippet below uses generic placeholders; substitute them):
+
+```ts
+return {
+  // ... existing fields and call(...) ...
+  safeCall: <TResponse, ETyped = never>(descriptor, options) =>
+    executeSafeCall<TResponse, ETyped>({
+      descriptor,
+      basePath,            // ← whatever local binding holds the resolved basePath
+      adapter,
+      hooks,
+      defaults: globalDefaults,  // ← whatever local binding holds the defaults
+      options,
+      errorRegistry,
+    }),
+}
+```
+
+The TypeScript type on `ClientInstance.safeCall` (added in Step 1) requires `safeCall<TResponse, ETyped = never>(...)`. Match the existing `call` signature shape exactly so generated callables can call either uniformly.
+
+- [ ] **Step 7: Run full client suite**
+
+```bash
+npx vitest run src/client/
+```
+Expected: PASS.
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add src/client/call.ts src/client/types.ts src/client/index.ts src/client/safe-call.test.ts
+git commit -m "feat(client): add executeSafeCall and ClientInstance.safeCall
+
+Returns a discriminated Result<T, E> instead of throwing. Three
+failure-source paths map to distinct kinds (usage / classifier /
+http-or-typed). onError fires on every failure (cross-cutting
+telemetry; consumers suppress per-call for retry loops)."
+```
+
+---
+
+## Phase 6 — Codegen: emit `.safe` sibling
+
+### Task 12: Update `emit-scope.ts` for RPC routes
+
+**Files:**
+- Modify: `src/codegen/emit-scope.ts`
+- Test: `src/codegen/emit-scope.test.ts`
+
+- [ ] **Step 1: Read `emit-scope.test.ts` to understand existing test fixtures**
+
+```bash
+cat src/codegen/emit-scope.test.ts | head -80
+```
+
+- [ ] **Step 2: Write failing test**
+
+Add to `src/codegen/emit-scope.test.ts`:
+
+```ts
+describe('emitScopeFile .safe sibling', () => {
+  it('emits .safe property on RPC callable when route has errors', async () => {
+    const group = makeGroupWithRpcRoute({ name: 'GetUser', errors: ['NotFound'] })
+    const out = await emitScopeFile(group, { errorKeys: new Set(['NotFound']) })
+    expect(out).toContain('GetUser.safe = ')
+    expect(out).toMatch(/Promise<Result<.*GetUser\.Response, .*GetUser\.Errors>>/)
+  })
+
+  it('emits .safe with ResultNoTyped when route has no errors', async () => {
+    const group = makeGroupWithRpcRoute({ name: 'GetUser', errors: [] })
+    const out = await emitScopeFile(group, {})
+    expect(out).toContain('GetUser.safe = ')
+    expect(out).toMatch(/Promise<ResultNoTyped<.*GetUser\.Response>>/)
+    expect(out).not.toContain('Errors')
+  })
+})
+```
+
+(The `makeGroupWithRpcRoute` helper may need to be added; check existing patterns and add minimally.)
+
+- [ ] **Step 3: Run to verify fail**
+
+```bash
+npx vitest run src/codegen/emit-scope.test.ts -t '.safe sibling'
+```
+
+- [ ] **Step 4: Update `emitRpcRoute` in `src/codegen/emit-scope.ts`**
+
+Locate the existing callable emission for RPC (around `src/codegen/emit-scope.ts:249-261`). Replace with:
+
+```ts
+// IMPORTANT: hasErrors must reflect the *filtered* error union (post-errorKeys
+// filter), not raw route.errors.length. Otherwise we may emit
+// Result<Response, Foo.Errors> when no Foo.Errors namespace member was
+// emitted (because all keys lacked schemas) — producing a compile error in
+// the generated client. Use the same buildErrorUnion result that
+// injectRouteErrors uses below.
+const errorUnion = buildErrorUnion(route.errors, ctx)
+const hasErrors = errorUnion !== null
+const errorsRef = ctx.namespaceTypes
+  ? `${ctx.scopePascal}.${pascal}.Errors`
+  : `${pascal}Errors`
+const resultType = hasErrors
+  ? `Result<${responseTypeName}, ${errorsRef}>`
+  : `ResultNoTyped<${responseTypeName}>`
+
+const callable = [
+  `    /** ${route.method.toUpperCase()} ${route.path} */`,
+  `    ${pascal}: Object.assign(`,
+  `      function ${pascal}(params: ${paramsTypeName}, options?: ProcedureCallOptions): Promise<${responseTypeName}> {`,
+  `        return client.call<${responseTypeName}>({`,
+  `          name: '${pascal}',`,
+  `          scope: '${scopeStr}',`,
+  `          path: '${route.path}',`,
+  `          method: '${route.method}',`,
+  `          kind: 'rpc',`,
+  `          params,`,
+  `        }, options)`,
+  `      },`,
+  `      {`,
+  `        safe(params: ${paramsTypeName}, options?: ProcedureCallOptions): Promise<${resultType}> {`,
+  `          return client.safeCall<${responseTypeName}${hasErrors ? `, ${errorsRef}` : ''}>({`,
+  `            name: '${pascal}',`,
+  `            scope: '${scopeStr}',`,
+  `            path: '${route.path}',`,
+  `            method: '${route.method}',`,
+  `            kind: 'rpc',`,
+  `            params,`,
+  `          }, options)`,
+  `        },`,
+  `      },`,
+  `    ),`,
+].join('\n')
+```
+
+Pass the precomputed `errorUnion` into `injectRouteErrors` (instead of recomputing) so we don't call `buildErrorUnion` twice for the same route:
+
+```ts
+// Replace the existing call:
+//   const hasErrors = injectRouteErrors(declarations, pascal, buildErrorUnion(route.errors, ctx), ctx.namespaceTypes)
+// With:
+const hasErrorsInjected = injectRouteErrors(declarations, pascal, errorUnion, ctx.namespaceTypes)
+return { typeDeclarations: declarations, callable, hasStream: false, hasErrors: hasErrorsInjected }
+```
+
+(`hasErrors` and `hasErrorsInjected` are equivalent here — `injectRouteErrors` returns `false` precisely when `errorUnion` is null. Use whichever name reads cleanest in the final code.)
+
+Update the imports block at the top of the generated scope file to include `Result` / `ResultNoTyped`:
+
+```ts
+const clientImports = hasStream
+  ? `import type { ClientInstance, ProcedureCallOptions, TypedStream, Result, ResultNoTyped } from '${clientImportPath}'`
+  : `import type { ClientInstance, ProcedureCallOptions, Result, ResultNoTyped } from '${clientImportPath}'`
+```
+
+(Drop `Result`/`ResultNoTyped` from the import set if no callable in the scope used them — left as an optimization for the writing-plans review pass; safe to always include.)
+
+- [ ] **Step 5: Run tests to verify pass**
+
+```bash
+npx vitest run src/codegen/emit-scope.test.ts
+```
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/codegen/emit-scope.ts src/codegen/emit-scope.test.ts
+git commit -m "feat(codegen): emit .safe sibling on RPC callables"
+```
+
+### Task 13: Update `emit-scope.ts` for API routes
+
+**Files:** same as Task 12.
+
+- [ ] **Step 1: Write failing test for API route .safe emission**
+
+Mirror the Task 12 test for an API route (use `makeGroupWithApiRoute` or analogous helper).
+
+- [ ] **Step 2: Update `emitApiRoute` with the same `Object.assign(fn, { safe })` pattern**
+
+Apply the same changes from Task 12 Step 4 inside `emitApiRoute` (around `src/codegen/emit-scope.ts:326-338`).
+
+- [ ] **Step 3: Run tests to verify pass**
+
+```bash
+npx vitest run src/codegen/emit-scope.test.ts
+```
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add src/codegen/emit-scope.ts src/codegen/emit-scope.test.ts
+git commit -m "feat(codegen): emit .safe sibling on API callables"
+```
+
+### Task 14: Confirm streams remain unchanged (no `.safe` emission)
+
+**Files:**
+- Test: `src/codegen/emit-scope.test.ts`
+
+- [ ] **Step 1: Add a test asserting stream callables do NOT have a `.safe` sibling**
+
+```ts
+it('does not emit .safe on stream callables', async () => {
+  const group = makeGroupWithStreamRoute({ name: 'StreamUsers' })
+  const out = await emitScopeFile(group, {})
+  expect(out).toContain('StreamUsers(')
+  expect(out).not.toContain('StreamUsers.safe')
+  // Stream callables stay as plain functions — no Object.assign wrapper.
+  expect(out).not.toMatch(/StreamUsers:\s*Object\.assign/)
+})
+```
+
+- [ ] **Step 2: Run to verify pass (no implementation change required if Tasks 12-13 only touched RPC/API)**
+
+```bash
+npx vitest run src/codegen/emit-scope.test.ts -t 'stream'
+```
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add src/codegen/emit-scope.test.ts
+git commit -m "test(codegen): confirm stream callables omit .safe sibling"
+```
+
+---
+
+## Phase 7 — Self-contained bundling
+
+### Task 15: Update self-contained bundler with new types and runtime file
+
+**Files:**
+- Modify: `src/codegen/emit-client-runtime.ts`
+- Test: `src/codegen/emit-client-runtime.test.ts` (extend, or add if absent)
+
+The self-contained bundler in `emit-client-runtime.ts` has two **hard-coded** lists that must be extended for the new types and runtime to flow through to consumers' bundled `_types.ts` / `_client.ts`:
+
+1. `TYPES_IMPORT` (around lines 6–25) — the inline import list at the top of the bundled `_client.ts`. Must include every new type from `src/client/types.ts` that the runtime references.
+2. `SOURCE_FILES` (around lines 32–42) — the ordered list of `src/client/*.ts` files concatenated into the bundle. Must include `classify-error.ts`.
+
+- [ ] **Step 1: Read `emit-client-runtime.ts` and confirm the hard-coded lists**
+
+```bash
+sed -n '1,50p' src/codegen/emit-client-runtime.ts
+```
+
+- [ ] **Step 2: Write a failing integration test**
+
+Create or extend `src/codegen/emit-client-runtime.test.ts`:
+
+```ts
+import { describe, it, expect } from 'vitest'
+import { generateClient } from './index.js'
+import * as path from 'node:path'
+import * as os from 'node:os'
+import * as fs from 'node:fs/promises'
+
+describe('self-contained bundling — safe-result symbols', () => {
+  it('includes Result, ResultNoTyped, ClientErrorMap, FrameworkFailure in _client.ts', async () => {
+    const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'tsproc-self-'))
+    await generateClient({
+      envelope: { service: 'Api', routes: [], errors: [] },
+      outDir: tmp,
+      selfContained: true,
+    })
+    const client = await fs.readFile(path.join(tmp, '_client.ts'), 'utf-8')
+    expect(client).toMatch(/Result\b/)
+    expect(client).toMatch(/ResultNoTyped\b/)
+    expect(client).toMatch(/ClientErrorMap\b/)
+    expect(client).toMatch(/FrameworkFailure\b/)
+    expect(client).toMatch(/defaultClassifyError\b/)
+    expect(client).toMatch(/ClientNetworkError\b/)
+    expect(client).toMatch(/ClientTimeoutError\b/)
+    expect(client).toMatch(/ClientAbortError\b/)
+    expect(client).toMatch(/ClientParseError\b/)
+    expect(client).toMatch(/ClientHttpError\b/)
+    expect(client).toMatch(/executeSafeCall\b/)
+  })
+
+  it('bundled _client.ts type-checks under tsc --noEmit', async () => {
+    // Confirms the bundled file is importable and self-consistent — would fail
+    // if TYPES_IMPORT is missing a name the runtime references.
+    const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'tsproc-tsc-'))
+    await generateClient({
+      envelope: { service: 'Api', routes: [], errors: [] },
+      outDir: tmp,
+      selfContained: true,
+    })
+    // Write a minimal tsconfig + invoke tsc; or shell out to tsc with --noEmit
+    // pointed at the temp dir. (Shape this against existing project conventions
+    // for child-process tsc invocations, if any.)
+    const { execSync } = await import('node:child_process')
+    expect(() =>
+      execSync(`npx tsc --noEmit --target es2022 --module nodenext --moduleResolution nodenext ${path.join(tmp, '_client.ts')} ${path.join(tmp, '_types.ts')}`, { stdio: 'pipe' })
+    ).not.toThrow()
+  })
+})
+```
+
+- [ ] **Step 3: Run to verify fail**
+
+```bash
+npx vitest run src/codegen/emit-client-runtime.test.ts
+```
+
+- [ ] **Step 4: Update `TYPES_IMPORT` in `src/codegen/emit-client-runtime.ts`**
+
+Add the new symbols:
+
+```ts
+const TYPES_IMPORT = `import type {
+  ClientAdapter,
+  AdapterRequest,
+  AdapterResponse,
+  AdapterStreamResponse,
+  ClientHooks,
+  BeforeRequestContext,
+  AfterResponseContext,
+  ErrorContext,
+  CallDescriptor,
+  StreamDescriptor,
+  TypedStream,
+  ClientInstance,
+  ProcedureCallDefaults,
+  ProcedureCallOptions,
+  CreateClientConfig,
+  RequestMeta,
+  ErrorRegistry,
+  ErrorFactory,
+  ErrorResponseMeta,
+  ClientErrorMap,
+  FrameworkFailure,
+  Result,
+  ResultNoTyped,
+  ErrorClassifier,
+  ClassifyErrorContext,
+  ClassifiedError,
+} from './_types'`
+```
+
+- [ ] **Step 5: Update `SOURCE_FILES` to include `classify-error.ts`**
+
+```ts
+const SOURCE_FILES = [
+  'errors.ts',
+  'classify-error.ts',     // ← new — must come before call.ts which imports it
+  'error-dispatch.ts',
+  'request-builder.ts',
+  'resolve-options.ts',
+  'hooks.ts',
+  'call.ts',
+  'stream.ts',
+  'fetch-adapter.ts',
+  'index.ts',
+] as const
+```
+
+- [ ] **Step 6: Confirm the `_types.ts` bundling pipeline emits the new types**
+
+`_types.ts` is generated by re-exporting from `src/client/types.ts`. Since Task 9 already added the new types to `types.ts`, they should flow through automatically. Verify by reading the relevant emitter (likely `emit-types-bundle.ts` or similar — find via `grep -n '_types.ts' src/codegen/ -r`). If the bundler uses an explicit re-export list, extend it the same way.
+
+- [ ] **Step 7: Run tests to verify pass**
+
+```bash
+npx vitest run src/codegen/emit-client-runtime.test.ts
+```
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add src/codegen/emit-client-runtime.ts src/codegen/emit-client-runtime.test.ts
+git commit -m "feat(codegen/self-contained): bundle Result types and classifier runtime
+
+Extends TYPES_IMPORT with Result, ResultNoTyped, ClientErrorMap,
+FrameworkFailure, ErrorClassifier; adds classify-error.ts to
+SOURCE_FILES."
+```
+
+### Task 16: Refresh golden fixture for the TS target
+
+**Files:**
+- Modify: the golden output file used by the TS-target codegen integration test
+
+- [ ] **Step 1: Identify the golden fixture file**
+
+```bash
+find src/codegen -name '*golden*' -o -name '*.golden.*' | head
+```
+
+- [ ] **Step 2: Run the integration test in update mode (or hand-edit the expected output)**
+
+If a snapshot-update mode exists:
+```bash
+npx vitest run src/codegen/ -u
+```
+Otherwise hand-edit to include the new `.safe` siblings + `Result`/`ResultNoTyped` imports.
+
+- [ ] **Step 3: Inspect the diff to confirm changes match expected emission**
+
+```bash
+git diff -- src/codegen/__fixtures__/
+```
+
+- [ ] **Step 4: Run integration test**
+
+```bash
+npx vitest run src/codegen/
+```
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/codegen/__fixtures__/<files>
+git commit -m "test(codegen): refresh golden fixture with .safe siblings"
+```
+
+---
+
+## Phase 8 — Bundle-size budget regression test
+
+### Task 17: Add a 100-route fixture and per-route byte-cost assertion
+
+**Files:**
+- Create: `src/codegen/__fixtures__/100-routes-envelope.json` (generated programmatically — see step 1)
+- Create: `src/codegen/bundle-size.test.ts`
+
+- [ ] **Step 1: Generate the 100-route envelope fixture**
+
+Inline the generation in the test setup (no separate fixture file) — easier to maintain:
+
+```ts
+import { describe, it, expect, beforeAll } from 'vitest'
+import { generateClient } from './index.js'
+import * as path from 'node:path'
+import * as os from 'node:os'
+import * as fs from 'node:fs/promises'
+
+function makeEnvelope(routeCount: number) {
+  const routes = Array.from({ length: routeCount }, (_, i) => ({
+    kind: 'rpc',
+    name: `Op${i}`,
+    scope: 'ops',
+    method: 'POST',
+    path: `/ops/op${i}`,
+    jsonSchema: {
+      body: { type: 'object', properties: { x: { type: 'string' } } },
+      response: { type: 'object', properties: { y: { type: 'string' } } },
+    },
+  }))
+  return { service: 'BenchApi', routes, errors: [] }
+}
+```
+
+- [ ] **Step 2: Generate, minify, measure**
+
+```ts
+describe('bundle size budget', () => {
+  let perRouteDelta: number
+
+  beforeAll(async () => {
+    const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'tsproc-bundle-'))
+    await generateClient({ envelope: makeEnvelope(100), outDir: tmp, selfContained: false })
+    const scopeFile = await fs.readFile(path.join(tmp, 'ops.ts'), 'utf-8')
+
+    // Strip whitespace/comments as a stand-in for minification (esbuild would
+    // be more accurate but adds a dep; this is a stable lower-bound proxy).
+    const stripped = scopeFile.replace(/\s+/g, ' ').replace(/\/\*[\s\S]*?\*\//g, '').replace(/\/\/.*$/gm, '')
+    perRouteDelta = stripped.length / 100
+  })
+
+  it('stays within 1500 chars per route post-strip', () => {
+    // Initial budget — refine after first measurement. The .safe sibling adds
+    // roughly 400 chars of unminified emission per route (Object.assign wrapper +
+    // duplicated descriptor literal). Post-strip should land well under 1500.
+    //
+    // RELATIONSHIP TO SPEC TARGET: The spec sets a "200 bytes per route
+    // post-minify" goal. This whitespace-strip proxy is a coarse stand-in
+    // chosen to avoid an esbuild dep — actual minified bytes will be lower
+    // than `perRouteDelta` here. If a future task swaps in real esbuild
+    // minification, tighten the budget to ~250 bytes (200 + 25% headroom)
+    // and link back to spec section "Tests / item 10". For now this guard
+    // catches catastrophic regressions only, not subtle bloat.
+    //
+    // Record the actual measurement when the test first passes:
+    //   PERROUTEDELTA_BASELINE: <fill in after first run>
+    expect(perRouteDelta).toBeLessThan(1500)
+  })
+})
+```
+
+**Note:** The whitespace-strip proxy is a coarse but stable measure. If the team wants a real minified-bytes budget later, swap in `esbuild` (already a transitive dep via vitest) — out of scope for this task. The point of the test is regression detection, not absolute accuracy.
+
+- [ ] **Step 3: Run to establish baseline**
+
+```bash
+npx vitest run src/codegen/bundle-size.test.ts
+```
+If it passes — good baseline. If it fails, log the actual delta and adjust the budget upward to current + 20% headroom, with a comment noting the baseline.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add src/codegen/bundle-size.test.ts
+git commit -m "test(codegen): add per-route bundle-size budget regression guard"
+```
+
+---
+
+## Phase 9 — Documentation
+
+### Task 18: Write `docs/client-error-handling.md`
+
+**Files:**
+- Create: `docs/client-error-handling.md`
+
+- [ ] **Step 1: Write the doc**
+
+Sections required:
+
+1. **The throwing form** — framework error class taxonomy table; narrowing pattern with `instanceof`; example showing `try/catch` with branches for `ApiErrors.X`, `ClientHttpError`, `ClientTimeoutError`, `ClientNetworkError`, `ClientAbortError`.
+2. **The `.safe` form** — when to use, full example with exhaustive switch on `kind`, narrowing inside each branch.
+3. **Custom error categories** — `ClientErrorMap` augmentation example (both direct and self-contained import targets); `classifyError` adapter config example showing composition with `defaultClassifyError`.
+4. **Migration** — `ClientRequestError` → `ClientHttpError`; raw `DOMException` / `TypeError` → framework classes; `onError` payload shape change. Concrete before/after for each.
+5. **FAQ — `.safe` + retries** — explain why `onError` fires on every `.safe` failure, show the per-call no-op or `meta.isRetry` suppression patterns. Note the deliberate choice to not add a config knob in v1.
+
+(Use the spec's "Where each `kind` originates" table verbatim — it's the canonical reference for failure-source paths.)
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add docs/client-error-handling.md
+git commit -m "docs: add client error-handling guide"
+```
+
+### Task 19: Update `CLAUDE.md`
+
+**Files:**
+- Modify: `CLAUDE.md`
+
+- [ ] **Step 1: In the Client section, add a paragraph pointing at the new guide and the `.safe` form**
+
+Append a bullet under "Important Patterns" referencing `docs/client-error-handling.md` and noting that every RPC/API generated callable has a `.safe` sibling returning `Result<T, E>`.
+
+- [ ] **Step 2: Add a paragraph on the framework error class taxonomy**
+
+Mention the six classes and that platform errors (`TypeError`, `DOMException`) are normalized at the `executeCall` boundary.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add CLAUDE.md
+git commit -m "docs(CLAUDE.md): note safe form and normalized error taxonomy"
+```
+
+### Task 20: Update `agent_config/` patterns and anti-patterns
+
+**Files:**
+- Modify: `agent_config/claude-code/skills/ts-procedures/patterns.md`
+- Modify: `agent_config/claude-code/skills/ts-procedures/anti-patterns.md`
+- Modify: `agent_config/copilot/copilot-instructions.md`
+- Modify: `agent_config/cursor/cursorrules`
+
+- [ ] **Step 1: Add an "Error handling in client code" section to `patterns.md`**
+
+Show both the throwing form and the `.safe` form, with the framework class narrowing pattern. Mention `ClientErrorMap` augmentation briefly with a link to `docs/client-error-handling.md`.
+
+- [ ] **Step 2: Add a "Don't catch raw `DOMException`/`TypeError`" entry to `anti-patterns.md`**
+
+Show the wrong pattern (catching `DOMException` to detect timeout) and the right pattern (`instanceof ClientTimeoutError`).
+
+- [ ] **Step 3: Mirror the additions in `copilot-instructions.md` and `cursorrules`**
+
+These files are condensed equivalents — keep them tight (~10-15 lines per addition).
+
+- [ ] **Step 4: Confirm no installer/postinstall changes are needed**
+
+The `agent_config/` files are bundled as static documentation; the installer (`agent_config/bin/setup.mjs`) and postinstall (`agent_config/bin/postinstall.mjs`) do recursive file copies — they pick up new content automatically. No installer change required for this task; confirm with:
+
+```bash
+grep -n 'patterns.md\|anti-patterns.md' agent_config/bin/*.mjs
+```
+Expected: no hard-coded references (or only references that already cover the modified files via globs).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add agent_config/
+git commit -m "docs(agent_config): add safe-form patterns and DOMException anti-pattern"
+```
+
+---
+
+## Phase 10 — Migration + version bump
+
+### Task 21: Update `CHANGELOG.md` (or release notes file)
+
+**Files:**
+- Modify: `CHANGELOG.md` (if it exists) or create one
+
+- [ ] **Step 1: Check if CHANGELOG exists**
+
+```bash
+ls CHANGELOG.md
+```
+
+- [ ] **Step 2: Add a `7.0.0` entry**
+
+Required content:
+- **Breaking changes:**
+  - `ClientRequestError` renamed to `ClientHttpError` (deprecated alias retained for one minor cycle)
+  - Raw `DOMException` / `TypeError` from the adapter no longer reach consumer catch blocks — replaced with `ClientNetworkError`, `ClientTimeoutError`, `ClientAbortError`
+  - `onError` hook receives the normalized framework error in `ctx.error` (not the raw platform error; original is on `error.cause`)
+- **New features:**
+  - `.safe()` sibling form on every generated RPC/API callable, returning `Result<T, E>`
+  - `ClientErrorMap` interface for declaration-merging custom error kinds
+  - `defaultClassifyError` exported for adapter-author composition
+  - `ClientAdapter.classifyError` optional adapter-level classifier
+  - `ClientNetworkError`, `ClientTimeoutError`, `ClientAbortError`, `ClientParseError` framework classes (all carry `cause`)
+- **Migration:** see `docs/client-error-handling.md`
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add CHANGELOG.md
+git commit -m "docs(changelog): add 7.0.0 entry"
+```
+
+### Task 22: Bump `package.json` to `7.0.0`
+
+**Files:**
+- Modify: `package.json`
+
+- [ ] **Step 1: Update version field**
+
+Change `"version": "6.2.0"` to `"version": "7.0.0"`.
+
+- [ ] **Step 2: Run lint + build + test**
+
+```bash
+npm run lint && npm run build && npm run test
+```
+Expected: PASS.
+
+- [ ] **Step 3: Commit**
+
+Match the project's prior version-bump commit style (recent commits use the bare version: `6.2.0`, `6.1.0`):
+
+```bash
+git add package.json
+git commit -m "7.0.0"
+```
+
+---
+
+## Final verification checklist
+
+Before opening the PR / merging:
+
+- [ ] `npm run test` passes (full suite)
+- [ ] `npm run lint` passes
+- [ ] `npm run build` succeeds without TS errors
+- [ ] `npm run check-docs` passes (docs consistency check)
+- [ ] Manually inspect a generated client against a small fixture envelope to confirm `.safe` callables hover correctly in an editor (`tsc --noEmit` in the test fixture's directory)
+- [ ] Bundle-size budget test (Task 17) is green and within reasonable range of expected
+- [ ] Migration doc walks through all three breaking changes with concrete before/after
+- [ ] Spec decision-log items all reflected in code