ts-procedures 6.2.0 → 7.0.0-beta.0

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

@@ -0,0 +1,324 @@
+# Safe Result API & Normalized Client Errors — Design
+
+Date: 2026-04-29
+Branch: TBD (next major)
+Status: design
+
+## Goal
+
+Eliminate the "what type is `err`?" problem in catch blocks of generated client code by:
+
+1. **Normalizing** every error that can be raised by the client into a known set of framework error classes (network, timeout, abort, http, parse, usage). Today the client throws a mix of its own classes (`ClientRequestError`, `ClientPathParamError`) and raw platform errors (`TypeError`, `DOMException`); the normalized layer means consumers only ever see framework classes from the throwing path.
+2. Adding a **`.safe()` sibling form** on every RPC and API callable that returns a discriminated `Result<T, E>` instead of throwing. Consumers narrow via the `kind` discriminant; per-route typed errors (declared via `route.errors`) come through under `kind: 'typed'`; framework errors come through under their own kinds (`'http'`, `'network'`, `'timeout'`, `'aborted'`, `'usage'`, `'parse'`, `'unknown'`).
+3. Making the `kind` set **extensible** via TypeScript declaration merging on a `ClientErrorMap` interface, paired with an adapter-provided `classifyError` runtime classifier. This mirrors the existing `RequestMeta` augmentation pattern and lets downstream apps surface their own error categories as first-class members of the `Result` union.
+
+The throwing form remains canonical; `.safe()` is opt-in. Both forms are first-class, neither is deprecated.
+
+## Non-goals
+
+- **Streams.** `TypedStream` mixes async iteration, a `.result` promise, and mid-stream SSE errors. Bolting `Result` on top is messy and out of scope. Streams keep the throwing form. (Stream callables benefit from the normalization layer for pre-stream errors — same classifier — but no `.safe` sibling is emitted on streams.)
+- **Per-client generic error map.** Considered and rejected during brainstorming. Module augmentation is the single supported extension mechanism. If apps with multiple clients needing distinct maps materialize, a per-client generic can be added later (additive, non-breaking).
+- **Result-style API wrappers for hooks or adapters.** Hooks still throw or resolve normally. The classifier runs at the `executeCall` boundary only.
+- **Auto-retry, circuit breaking, backoff.** Out of scope. The normalized error categories make these cleaner to implement at consumer layer, but the framework does not ship them.
+- **Renaming `ClientPathParamError` or `ClientStreamError`.** They keep their names; only `ClientRequestError` is renamed (see below).
+
+## Output shape
+
+### What the downstream dev writes
+
+Throwing form (unchanged surface, normalized error classes):
+
+```ts
+try {
+  const response = await client.records.DownloadRecord(params, { timeout: 60_000 })
+  if (response.pdfBase64) downloadBase64AsPdf(...)
+} catch (err) {
+  if (err instanceof ApiErrors.UseCaseError) Alerts.error(err.body.message)
+  else if (err instanceof ClientHttpError)    Alerts.error(`Server ${err.status}`)
+  else if (err instanceof ClientTimeoutError) Alerts.error('Timed out')
+  else if (err instanceof ClientNetworkError) Alerts.error('Network error')
+  else if (err instanceof ClientAbortError)   { /* user cancelled */ }
+  else throw err  // programmer/framework bug
+}
+```
+
+Safe form (new):
+
+```ts
+const r = await client.records.DownloadRecord.safe(params, { timeout: 60_000 })
+
+if (r.ok) {
+  if (r.value.pdfBase64) downloadBase64AsPdf(...)
+  return
+}
+
+switch (r.kind) {
+  case 'typed':
+    if (r.error instanceof ApiErrors.UseCaseError) Alerts.error(r.error.body.message)
+    break
+  case 'http':         Alerts.error(`Server ${r.error.status}`); break
+  case 'network':      Alerts.error('Network error'); break
+  case 'timeout':      Alerts.error('Timed out'); break
+  case 'aborted':      break  // user cancelled
+  case 'rateLimited':  Alerts.error(`Retry in ${r.error.retryAfter}s`); break  // app-defined
+  case 'parse':
+  case 'usage':        throw r.error  // programmer/framework bug — fail loud
+  case 'unknown':      Alerts.error('Unknown error'); console.error(r.error); break
+}
+```
+
+### Generated callable signature (RPC and API)
+
+Today (unchanged):
+```ts
+DownloadRecord(params: Records.DownloadRecord.Params, options?: ProcedureCallOptions): Promise<Records.DownloadRecord.Response>
+```
+
+Added: a `.safe` property on the same function value:
+```ts
+DownloadRecord.safe(
+  params: Records.DownloadRecord.Params,
+  options?: ProcedureCallOptions
+): Promise<Result<Records.DownloadRecord.Response, Records.DownloadRecord.Errors>>
+```
+
+The throwing form and `.safe` share the same params, options, descriptor, hooks, classifier, and adapter — only the failure presentation differs.
+
+### `Result` type derivation
+
+Defined in `src/client/types.ts` (and bundled into `_types.ts` in self-contained mode):
+
+```ts
+export type Result<T, ETyped> =
+  | { ok: true;  value: T }
+  | { ok: false; kind: 'typed';  error: ETyped }
+  | FrameworkFailure
+
+type FrameworkFailure = {
+  [K in keyof ClientErrorMap]: { ok: false; kind: K; error: ClientErrorMap[K] }
+}[keyof ClientErrorMap]
+
+// Default (augmentable) map — devs add keys via declaration merging.
+export interface ClientErrorMap {
+  http:    ClientHttpError
+  network: ClientNetworkError
+  timeout: ClientTimeoutError
+  aborted: ClientAbortError
+  parse:   ClientParseError
+  usage:   ClientPathParamError
+  unknown: unknown
+}
+```
+
+Augmentation example (downstream app code, written once):
+
+```ts
+declare module 'ts-procedures/client' {
+  interface ClientErrorMap {
+    rateLimited:    MyRateLimitError
+    paymentRequired: MyPaymentError
+  }
+}
+```
+
+(For self-contained generated clients, the augmentation target is `./generated/_types` instead — same pattern as `RequestMeta` today.)
+
+After augmentation, `Result`'s union expands automatically; every `.safe()` call narrows the new kinds with no per-call type ceremony and no codegen change.
+
+**`'typed'` is reserved.** Augmentation cannot register a `kind: 'typed'` because the typed-arm is part of `Result<T, ETyped>` itself, not `ClientErrorMap`. Attempting `interface ClientErrorMap { typed: ... }` produces a confusing TS error about overlapping discriminants — which is the desired behavior (don't do it), but the docs page calls this out so adventurous consumers don't have to discover it the hard way.
+
+## Architectural decisions
+
+### 1. Normalize platform errors at the `executeCall` boundary
+
+The classifier wraps the adapter call in `executeCall` (and the equivalent stream pre-error path in `executeStream`). Raw platform errors (`TypeError`, `DOMException`) are caught and translated to framework classes. The classifier composition is:
+
+1. **Adapter-provided `classifyError`** runs first if present. Returns `{ kind, error }` or `null` (fall through).
+2. **Default classifier** runs second. Recognizes `TypeError` from fetch → `ClientNetworkError`; `DOMException` with `name: 'AbortError'` + timeout-signal-aborted → `ClientTimeoutError`; `DOMException` with `name: 'AbortError'` + user-signal-aborted → `ClientAbortError`; anything else → `null`.
+3. **Fallthrough** — anything still unclassified is wrapped as `kind: 'unknown'` with the raw error attached.
+
+The default classifier is exported (`defaultClassifyError`) so adapter authors can compose deliberately:
+
+```ts
+const adapter = createFetchAdapter({
+  classifyError: (e) => myClassify(e) ?? defaultClassifyError(e),
+})
+```
+
+**Where each `kind` originates** — the `executeCall` flow has three distinct exit paths to a non-`ok` Result. The classifier only runs on the second.
+
+| # | Stage | Source of failure | Resulting kind(s) | Notes |
+|---|---|---|---|---|
+| 1 | **Pre-adapter** | `buildAdapterRequest` synchronously throws (e.g. missing path param) | `'usage'` (`ClientPathParamError`) | Bypasses classifier and `onError` hook entirely. `executeSafeCall` catches it at the outer try and maps to `kind: 'usage'`. The throwing form propagates as today. |
+| 2 | **Adapter throws** | `adapter.request()` rejects (network failure, abort, anything custom) | `'network'` / `'timeout'` / `'aborted'` / custom kinds / `'unknown'` | Classifier runs in the try/catch around `adapter.request()`. `onError` hook receives the *normalized* error (post-classification). |
+| 3 | **Adapter returns non-2xx** | `response.status < 200 \|\| >= 300` | `'typed'` (registry match) or `'http'` (no match → `ClientHttpError`) | Classifier does *not* run on this path. The registry-or-fallback dispatch in `call.ts` is the sole source of `'typed'` and `'http'` kinds. |
+
+The `'typed'` arm is **only** reachable via path 3. The framework-failure kinds (`'network'`, `'timeout'`, `'aborted'`, `'unknown'`, custom) are **only** reachable via path 2. The `'usage'` kind is **only** reachable via path 1. There is no overlap; each kind has exactly one source location in the runtime.
+
+### 2. Distinguishing timeout from user-abort
+
+`AbortSignal.any([timeoutSignal, userSignal])` loses provenance — when `aborted` fires, the combined signal alone can't tell us which input triggered it. `executeCall` keeps references to both signals locally and inspects `timeoutSignal?.aborted` first when an `AbortError` lands; if true, classify as timeout, else as user-abort.
+
+This logic lives in `defaultClassifyError`, but it needs the timeout signal as input. Resolution: classifier signature takes `(raw, ctx)` where `ctx` carries `{ timeoutSignal?, userSignal? }`:
+
+```ts
+type ErrorClassifier = (
+  raw: unknown,
+  ctx: { timeoutSignal?: AbortSignal; userSignal?: AbortSignal }
+) => { kind: string; error: Error } | null
+```
+
+The classifier's return contract is `error: Error` — every classified output is a real `Error` subclass (the framework class). Non-`Error` throws (e.g. a hook that threw a string) are *not* classified; they fall through to `kind: 'unknown'` with the raw value preserved as-is. `kind: 'unknown'` is the *only* path that produces a non-`Error` `error` field, and it's the only `ClientErrorMap` entry typed as `unknown` rather than a class.
+
+### 3. New error class taxonomy
+
+| Class | Replaces / new | `kind` | Notes |
+|---|---|---|---|
+| `ClientHttpError` | renames `ClientRequestError` | `'http'` | Same shape (`status`, `headers`, `body`, `procedureName`, `scope`). Old name re-exported as a deprecated alias for one minor cycle? See migration. |
+| `ClientNetworkError` | new | `'network'` | Wraps the original `TypeError`; carries the raw cause. |
+| `ClientTimeoutError` | new | `'timeout'` | Carries `timeoutMs`. |
+| `ClientAbortError` | new | `'aborted'` | Carries the `AbortSignal.reason` if available. |
+| `ClientParseError` | new | `'parse'` | Adapter-reported body parse failure (not currently raised; reserved for adapters that want to flag unparseable bodies). |
+| `ClientPathParamError` | unchanged | `'usage'` | Existing class, kind added. |
+
+All extend `Error`. All have `readonly procedureName` and `readonly scope` for telemetry. **Every framework class accepts an optional `cause` constructor argument and assigns it to the standard `Error.cause` property** — explicit contract so adapter authors and telemetry consumers can rely on `error.cause` to recover the underlying platform error (e.g. the original `TypeError` that produced a `ClientNetworkError`). The default classifier always populates `cause` when wrapping a platform error; consumer-provided classifiers SHOULD do the same and the docs page calls this out.
+
+### 4. `.safe` is a sibling property on the callable, not a separate namespace
+
+Each generated callable becomes the throwing function plus a `.safe` property:
+
+```ts
+// in emit-scope.ts output
+function DownloadRecord(params, options) { return client.call({...}, options) }
+DownloadRecord.safe = function (params, options) { return client.safeCall({...}, options) }
+```
+
+In TypeScript this is expressed via an intersection type at codegen time, or by annotating the binding with a generated interface. (Implementation detail for the writing-plans phase.) Discoverability wins: hover on `DownloadRecord` shows `.safe`.
+
+### 5. Codegen omits the `'typed'` arm when the route declares no errors
+
+A naive emission of `Result<Response, never>` for routes without typed errors leaves `{ ok: false; kind: 'typed'; error: never }` in the union. TypeScript does not collapse `never`-payload arms in hover output — the consumer sees an unreachable five-line arm cluttering every IDE tooltip. To prevent this, codegen branches:
+
+- Route has at least one entry in `route.errors` → `Result<Response, RouteErrors>` (full union, including `'typed'` arm).
+- Route has no errors declared → `ResultNoTyped<Response>` (`{ ok: true; value: T } | FrameworkFailure`, no `'typed'` arm).
+
+Both type aliases live in `src/client/types.ts` (and the bundled `_types.ts` in self-contained mode). The codegen change in `emit-scope.ts` selects which alias to emit per route based on the presence of `route.errors`. Hover output stays clean either way.
+
+### 6. `.safe` is RPC and API only
+
+Streams keep the throwing form. The classifier still normalizes their pre-stream errors (so `executeStream` throws `ClientHttpError` etc. instead of raw `DOMException`), but `TypedStream.result` and async iteration stay as-is.
+
+### 7. `ClientErrorMap` augmentation matches `RequestMeta` precedent
+
+Same module name (`ts-procedures/client` for direct consumers, `./generated/_types` for self-contained), same `interface X { ... }` declaration-merging mechanism, same documentation pattern. Devs who already learned the `RequestMeta` augmentation idiom transfer it directly.
+
+### 8. `unknown` is an explicit kind, not a leak
+
+Anything the classifier can't categorize falls through to `kind: 'unknown'` with `error: unknown`. This is a **deliberate** discriminant — consumers handling all kinds exhaustively get a single fallthrough branch for true edge cases (a hook threw something weird, a custom adapter raised something nobody declared). It is *not* a synonym for "error we forgot to classify" — every category we ship default coverage for is represented as its own kind.
+
+### 9. Hooks see normalized errors
+
+`onError` hook receives the classified framework error in `ctx.error`, not the raw platform exception. This is a behavior change vs. today (today the hook sees whatever the adapter threw — typically raw `TypeError`/`DOMException`). Documented in migration notes.
+
+The hook ordering is unchanged: `onError` runs after the adapter throws, before `executeCall` re-throws / the `.safe` wrapper catches.
+
+### 10. `.safe` invokes `onError` (cross-cutting telemetry)
+
+`onError` runs on every failure regardless of whether the consumer used the throwing form or the `.safe` form. The hook is for cross-cutting concerns (logging, tracing, metrics) which want to observe all failures uniformly; making it conditional on call style would force telemetry consumers to wire two paths.
+
+**Known consequence — retries-via-`.safe`.** A consumer using `.safe` to drive a retry loop will get one `onError` invocation per attempt, including attempts that the application considers expected/recoverable. This is by design for v1 (telemetry should see all attempts; the *application* knows what's "expected", not the framework). The FAQ in `docs/client-error-handling.md` documents this and shows the suppression pattern: the consumer attaches a per-call `onError` that no-ops, or uses the `meta` field to flag "this is a retry, ignore" inside their global `onError`. A dedicated config knob is deliberately not added in v1; if the pattern proves heavy enough that consumers consistently reach for the workaround, a `suppressOnErrorForSafe` adapter-level toggle can be added later (additive, non-breaking).
+
+### 11. Implementation locus
+
+- `src/client/errors.ts` — add `ClientNetworkError`, `ClientTimeoutError`, `ClientAbortError`, `ClientParseError`. Rename `ClientRequestError` → `ClientHttpError`.
+- `src/client/classify-error.ts` — **new file**. Exports `defaultClassifyError`, `ErrorClassifier` type.
+- `src/client/types.ts` — add `ClientErrorMap` interface, `Result<T, E>` type, `FrameworkFailure` derivation. Extend `ClientAdapter` with optional `classifyError`. Extend `ClientInstance` with `safeCall<TResponse, ETyped>(descriptor, options): Promise<Result<TResponse, ETyped>>`.
+- `src/client/call.ts` — wrap adapter call in classifier; `executeCall` throws normalized errors. Add `executeSafeCall` that catches `executeCall` and returns `Result`. The generated `.safe` callable closes over `client.safeCall`, which delegates to `executeSafeCall`. Single source of truth for the safe path: `executeSafeCall`.
+- `src/client/stream.ts` — wrap adapter stream call in classifier (pre-stream errors only). Mid-stream errors unchanged.
+- `src/client/fetch-adapter.ts` — accept `classifyError` in config (composes with default).
+- `src/client/index.ts` — export new classes, classifier, `Result`, `ClientErrorMap`.
+- `src/codegen/emit-scope.ts` — emit `.safe` sibling on every RPC/API callable. Type signature uses `Result<Response, RouteErrors>`.
+- `src/codegen/emit-index.ts` — no changes needed (factory shape unchanged).
+- `src/codegen/targets/_shared/` — no changes (Kotlin/Swift unaffected).
+
+## Pipeline integration
+
+No CLI flag changes. The `.safe` form is always emitted for RPC/API routes; consumers who don't use it pay zero runtime cost (the property is a thin closure over `client.safeCall`).
+
+For self-contained mode (`--self-contained`, the default), `_types.ts` and `_client.ts` bundle the new types and runtime. The augmentation target shifts from `ts-procedures/client` to `./generated/_types` — documented in the codegen docs alongside `RequestMeta`'s analogous note.
+
+`_errors.ts` is unchanged.
+
+## Migration (breaking changes)
+
+**Major version bump (next major).**
+
+| Change | Impact | Mitigation |
+|---|---|---|
+| `ClientRequestError` → `ClientHttpError` | Anyone catching `ClientRequestError` directly | Re-export `ClientRequestError` as a deprecated alias of `ClientHttpError` for one minor cycle. Console-warn on import? (Probably no — pure type re-export is silent. Documentation only.) |
+| Raw `DOMException`/`TypeError` no longer reach consumer catch blocks | Anyone catching `DOMException` directly to detect aborts/timeouts | Migration guide shows `instanceof ClientTimeoutError` / `ClientAbortError` pattern. Old pattern keeps working only if the consumer's own code does the check before our throw — which by definition won't happen since we re-throw normalized. |
+| `onError` hook sees normalized errors | Anyone inspecting `ctx.error` for `DOMException` / `TypeError` shape | Migration guide. The normalized class wraps the raw cause (`error.cause`), so consumers can still drill in if needed. |
+| `ClientAdapter` interface gains optional `classifyError` | None for default fetch adapter consumers; custom adapter authors must consider whether to provide one | Optional field, no required change. |
+
+No changes to: schema authoring, server-side procedure definitions, `Procedures()` factory, hook order, request descriptors, generated index/factory shape, Kotlin/Swift targets.
+
+## Tests
+
+### Runtime (`src/client/`)
+
+1. **`classify-error.test.ts`** — default classifier: `TypeError` → `ClientNetworkError`; `AbortError` + timeout-signal-aborted → `ClientTimeoutError`; `AbortError` + user-signal-aborted → `ClientAbortError`; both signals fired → timeout wins (deterministic precedence); unknown error → `null` (fallthrough).
+2. **`call.test.ts`** (extend) — `executeCall` throws normalized classes for each platform error category. Adapter-provided classifier runs first; default runs second; unclassified raises original error wrapped as a generic `Error` (NOT swallowed). Hooks see normalized error.
+3. **`safe-call.test.ts`** (new) — every kind in `ClientErrorMap` produces the corresponding `Result` shape. `kind: 'typed'` carries the registry-dispatched typed error. `ok: true` for 2xx with body. Adapter classifier custom kinds round-trip.
+4. **`fetch-adapter.test.ts`** (extend) — `classifyError` config composes with default (custom-then-default order).
+5. **`stream.test.ts`** (extend) — pre-stream errors are classified; mid-stream errors are not affected.
+
+### Codegen (`src/codegen/`)
+
+6. **`emit-scope.test.ts`** (extend) — RPC and API callables emit a `.safe` property with the correct `Result<Response, RouteErrors>` signature. Streams do not emit `.safe`. Routes without typed errors emit `Result<Response, never>` (the `kind: 'typed'` branch is unreachable but type-valid).
+7. **Golden file integration** — update `users-golden.ts` (or equivalent ts-target fixture) with the new `.safe` siblings.
+8. **TypeScript compilation test** — verify generated output type-checks under `tsc --noEmit`. Existing test, will catch regressions.
+
+### Augmentation (manual / docs example)
+
+9. **`augment-error-map.test.ts`** (new) — a sample `declare module` block in a `.test-d.ts` file using `tsd` or `expectType` to verify augmented kinds appear in the `Result` union and narrow correctly.
+
+10. **Bundle-size budget test** (new) — generate a 100-route fixture, run the codegen, minify the output (`esbuild --minify`), and assert the per-route byte cost added by the `.safe` sibling is within budget. The doc claims "zero runtime cost" but each callable now wraps two functions in a binding object that prevents tree-shaking; rough estimate ~100 bytes per route post-minify. Initial budget: assert the *delta* between this branch and the prior major's output stays below **200 bytes per route** for the 100-route fixture. If the test fails or the budget is wrong, the budget can be revised but the test itself stays as a regression guard.
+
+## Documentation
+
+1. **`docs/client-error-handling.md`** — new file. Covers:
+   - The throwing form: framework error class taxonomy + narrowing pattern.
+   - The `.safe` form: when to use, full example with exhaustive switch.
+   - Custom error categories: `ClientErrorMap` augmentation + adapter `classifyError`.
+   - Migration from `ClientRequestError` / `DOMException` catches.
+2. **`CLAUDE.md`** — add a paragraph in the Client section pointing at the new file. Update the "Important Patterns" list to mention the normalized error taxonomy and `.safe` form.
+3. **`agent_config/`** — update the AI-assistant skills:
+   - `claude-code/skills/ts-procedures/patterns.md` — add a "Handling errors in client code" section showing both forms.
+   - `claude-code/skills/ts-procedures/anti-patterns.md` — add "Don't catch raw DOMException/TypeError" anti-pattern, point at framework classes.
+   - `copilot/copilot-instructions.md` and `cursor/cursorrules` — same patterns, condensed.
+4. The TS-target consumer guide currently lives in `CLAUDE.md` and the new `docs/client-error-handling.md` — no separate `docs/codegen-ts.md` file exists today, and creating one is out of scope for this change. The `.safe` form is documented in `docs/client-error-handling.md` (item 1) with a back-reference from the `CLAUDE.md` Client section (item 2).
+5. **CHANGELOG / release notes** — major bump entry covering the rename, the new classes, the `.safe` form, the augmentation pattern.
+
+## Open questions
+
+These are the remaining design decisions to resolve before implementation. Each has a recommended default in parentheses; called out explicitly so the writing-plans phase makes them explicit choices rather than implicit ones.
+
+1. **Does the deprecated `ClientRequestError` alias ship?** (Recommended: **yes**, for one minor release after the major bump. Pure type re-export, zero runtime cost.)
+2. **Does `ClientParseError` get raised by the default fetch adapter today?** (Recommended: **no**, the default adapter falls back to text/null on parse failure — current behavior. The class ships so adapter authors who want stricter parsing can use it. Keeps scope tight.)
+3. **What does `executeStream`'s pre-stream error path look like?** (Recommended: same classifier composition as `executeCall`. Mid-stream errors unchanged. No `.safe` on stream callables.)
+4. **Is `ClientErrorMap['unknown']` typed as `unknown` or as `Error`?** (Recommended: **`unknown`**, because by definition nobody knows what raw thing landed there. Forcing `Error` would require wrapping non-`Error` throws and lose information.)
+
+## Decision log
+
+| Decision | Choice | Rationale |
+|---|---|---|
+| Extension mechanism | Module augmentation on `ClientErrorMap` | Matches `RequestMeta` precedent; zero codegen complexity; zero per-call ceremony. Per-client generic rejected as over-engineering for the multi-client case. |
+| `'typed'` discriminant | Reserved; not part of `ClientErrorMap` | Keeps the typed-arm tied to per-route `ETyped` carrier rather than the global map. Augmentation collisions impossible by construction. |
+| `.safe` shape | Sibling property on each callable | Most discoverable; hover shows both forms; only form that carries the per-route `Errors` union typed correctly. Parallel namespace and options-toggle rejected. |
+| Hover cleanliness for routes without errors | Codegen omits `'typed'` arm via `ResultNoTyped<T>` | TS does not collapse `never`-payload arms in hover; explicit alias keeps tooltips clean. |
+| Stream coverage | Out of scope for `.safe` | Stream failure surface is a three-way split (pre-stream, mid-stream, completion); `Result` doesn't fit cleanly. Classifier still normalizes pre-stream errors. |
+| Throwing form | Stays canonical, not deprecated | Most consumers prefer try/catch; `.safe` is opt-in for sites that want exhaustive failure handling. Both forms first-class. |
+| Default classifier composition | Custom-then-default | Adapter authors can intercept early; default is the floor. `defaultClassifyError` exported so authors can opt back in deliberately. |
+| Timeout vs. user-abort distinction | Local refs in `executeCall`, passed to classifier via `ctx` | `AbortSignal.any` loses provenance; refs are the only way to recover it. |
+| `onError` invocation by `.safe` | Yes — fires regardless of call style | Telemetry is cross-cutting; conditional firing forces dual wiring. Retry-via-`.safe` consumers suppress at the call-site (per-call `onError` no-op or `meta.isRetry` flag), not via framework toggle. |
+| Cause chain | Every framework class accepts `cause` constructor arg, sets `Error.cause` | Adapter authors and telemetry consumers rely on `error.cause` to recover the underlying platform error. Explicit contract, default classifier always populates. |

package/package.json

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

package/src/client/augment-error-map.test-d.ts

@@ -0,0 +1,22 @@
+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>()
+  })
+})

package/src/client/call.test.ts

@@ -1,6 +1,12 @@
 import { describe, it, expect, vi } from 'vitest'
 import { executeCall } from './call.js'
-import { ClientRequestError } from './errors.js'
+import {
+  ClientRequestError,
+  ClientNetworkError,
+  ClientTimeoutError,
+  ClientAbortError,
+  ClientHttpError,
+} from './errors.js'
 import type {
   ClientAdapter,
   AdapterRequest,
@@ -333,3 +339,61 @@ describe('executeCall', () => {
     expect(observedMeta).toEqual({ traceId: 'override', attempt: 1 })
   })
 })
+
+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 () => {
+    // Simulate fetch-style behavior: adapter waits on the signal and rejects
+    // with AbortError when it fires. Real fetch() throws AFTER the timeout
+    // signal aborts, so the classifier sees `timeoutSignal.aborted === true`.
+    const adapter: ClientAdapter = {
+      request: vi.fn(async (req) => {
+        await new Promise<void>((_resolve, reject) => {
+          req.signal?.addEventListener(
+            'abort',
+            () => reject(new DOMException('aborted', 'AbortError')),
+            { once: true },
+          )
+        })
+        throw new Error('unreachable')
+      }),
+      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)
+  })
+})

package/src/client/call.ts

@@ -1,15 +1,27 @@
 import { buildAdapterRequest } from './request-builder.js'
 import { runBeforeRequest, runAfterResponse, runOnError } from './hooks.js'
 import { applyRequestOptions, resolveBasePath } from './resolve-options.js'
-import { ClientRequestError } from './errors.js'
+import {
+  ClientHttpError,
+  ClientNetworkError,
+  ClientTimeoutError,
+  ClientAbortError,
+  ClientParseError,
+  ClientPathParamError,
+} from './errors.js'
 import { dispatchTypedError } from './error-dispatch.js'
+import { defaultClassifyError } from './classify-error.js'
 import type {
   ClientAdapter,
   ClientHooks,
   CallDescriptor,
+  ClassifyErrorContext,
   ErrorRegistry,
   ProcedureCallDefaults,
   ProcedureCallOptions,
+  Result,
+  ClientErrorMap,
+  FrameworkFailure,
 } from './types.js'
 
 export interface ExecuteCallConfig {
@@ -32,7 +44,7 @@ export interface ExecuteCallConfig {
  * 4. Call adapter.request()
  * 5. On adapter error: run onError hooks, re-throw
  * 6. Run onAfterResponse hooks (may mutate response.status to swallow errors)
- * 7. If response status is non-2xx: throw ClientRequestError
+ * 7. If response status is non-2xx: throw ClientHttpError
  * 8. Return response.body as TResponse
  */
 export async function executeCall<TResponse>(config: ExecuteCallConfig): Promise<TResponse> {
@@ -43,7 +55,9 @@ export async function executeCall<TResponse>(config: ExecuteCallConfig): Promise
   let request = buildAdapterRequest(descriptor, resolvedBasePath)
 
   // 2. Apply request-level options (headers, signal, timeout, meta)
-  request = applyRequestOptions(request, defaults, options)
+  const applied = applyRequestOptions(request, defaults, options)
+  request = applied.request
+  const signalSources = applied.signalSources
 
   // 3. Run before-request hooks — they may further mutate the request
   const beforeCtx = await runBeforeRequest(
@@ -57,14 +71,36 @@ export async function executeCall<TResponse>(config: ExecuteCallConfig): Promise
   let response
   try {
     response = await adapter.request(request)
-  } catch (err) {
-    // 5. On adapter error: run error hooks, re-throw
+  } catch (rawErr) {
+    // 5. On adapter error: classify (adapter > default > fallthrough), then run
+    //    onError hooks with the normalized error, then throw.
+    const classifyCtx: ClassifyErrorContext = {
+      procedureName: descriptor.name,
+      scope: descriptor.scope,
+      timeoutSignal: signalSources.timeoutSignal,
+      userSignal: signalSources.userSignal,
+      timeoutMs: signalSources.timeoutMs,
+    }
+    const classified =
+      adapter.classifyError?.(rawErr, classifyCtx) ??
+      defaultClassifyError(rawErr, classifyCtx)
+    // Tag the classified error so executeSafeCall can identify its kind without
+    // re-classifying. Default kinds are recognized via instanceof in
+    // classifyThrownError; only custom adapter kinds need an explicit tag.
+    if (classified) {
+      const defaultKinds = new Set(['network', 'timeout', 'aborted', 'parse'])
+      if (!defaultKinds.has(classified.kind)) {
+        ;(classified.error as unknown as { __tsProceduresKind?: string }).__tsProceduresKind = classified.kind
+      }
+    }
+    const finalError = classified?.error ?? rawErr
+
     await runOnError(
-      { procedureName: descriptor.name, scope: descriptor.scope, request, error: err },
+      { procedureName: descriptor.name, scope: descriptor.scope, request, error: finalError },
       hooks,
       options,
     )
-    throw err
+    throw finalError
   }
 
   // 6. Run after-response hooks — they may mutate response.status to swallow errors
@@ -81,8 +117,13 @@ export async function executeCall<TResponse>(config: ExecuteCallConfig): Promise
       procedureName: descriptor.name,
       scope: descriptor.scope,
     })
-    if (typed) throw typed
-    throw new ClientRequestError({
+    if (typed) {
+      // Tag so executeSafeCall can distinguish typed registry errors from plain
+      // ClientHttpError without re-inspecting the registry.
+      ;(typed as unknown as { __tsProceduresTyped?: boolean }).__tsProceduresTyped = true
+      throw typed
+    }
+    throw new ClientHttpError({
       status: response.status,
       headers: response.headers,
       body: response.body,
@@ -94,3 +135,64 @@ export async function executeCall<TResponse>(config: ExecuteCallConfig): Promise
   // 8. Return the body
   return response.body as TResponse
 }
+
+/**
+ * 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 path 2 and 3 (cross-cutting telemetry); NOT on
+ * path 1 (usage errors bypass the classifier and onError entirely).
+ */
+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 error — bypasses classifier and onError
+  if (err instanceof ClientPathParamError) {
+    return { ok: false, kind: 'usage', error: err }
+  }
+  // Path 3: post-status-check typed registry match — tagged by executeCall
+  if (err instanceof Error && (err as unknown as { __tsProceduresTyped?: boolean }).__tsProceduresTyped) {
+    return { ok: false, kind: 'typed', error: err as ETyped }
+  }
+  // Path 3: non-2xx fallback (no registry match)
+  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 }
+  }
+  // Custom adapter-classified error — tagged with its kind by executeCall.
+  // 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 unknown as { __tsProceduresKind?: string }).__tsProceduresKind === 'string') {
+    const kind = (err as unknown as { __tsProceduresKind: string }).__tsProceduresKind
+    return { ok: false, kind: kind as keyof ClientErrorMap, error: err } as FrameworkFailure
+  }
+  // Fallthrough — unrecognized throw type (non-Error or unclassified)
+  return { ok: false, kind: 'unknown', error: err }
+}