ts-procedures 8.5.0 → 9.0.0

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

@@ -1,324 +0,0 @@
-# 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/docs/superpowers/specs/2026-05-07-astro-adapter-design.md

@@ -1,252 +0,0 @@
-# Astro adapter for ts-procedures
-
-**Date:** 2026-05-07
-**Status:** Design — pending implementation
-**Subpath export:** `ts-procedures/astro`
-
-## Problem
-
-Downstream developers using Astro want to host ts-procedures handlers inside Astro server endpoints (`src/pages/**/*.ts`). Today they must hand-roll the bridge: take an Astro `APIRoute`, convert its `APIContext` into a `Request`, find a way to dispatch through their procedure factories, and translate the result back. Astro's filesystem-as-router model also resists the existing `register(...).build()` pattern, which produces one app for many routes.
-
-The goal is a "drop in the entry point" adapter: a single catch-all Astro file delegates every procedure call to one or more already-built ts-procedures apps, with full access to Astro's per-request data (`locals`, `cookies`, `redirect`) inside procedure handlers.
-
-## Non-goals
-
-- Native Astro builders. Mirroring `HonoAPIAppBuilder` as `AstroAPIAppBuilder` would duplicate path-matching, schema validation, error taxonomy, and DocRegistry plumbing. The catch-all pattern covers the request without that cost.
-- Per-procedure file scaffolding (one Astro file per procedure). Out of scope for v1.
-- DocRegistry / codegen integration. Users keep wiring `DocRegistry` against the same builders they pass to the adapter; the adapter returns no `.docs`.
-- `dispatch: 'merge'` strategy. YAGNI — users who want one Hono app can pre-merge with `app.route(...)` themselves.
-
-## Approach
-
-The adapter is a thin Web-fetch delegator. It accepts already-built Hono apps (from any of `HonoAPIAppBuilder`, `HonoRPCAppBuilder`, `HonoStreamAppBuilder`) and exposes Astro `APIRoute` exports the developer re-exports from a catch-all file.
-
-```
-Browser → /api/users/123
-  ↓
-Astro invokes ALL({ request, locals, cookies, params, redirect, url, ... })
-  ↓
-Adapter:
-  1. Strip pathPrefix from request URL (if configured) → `rewritten`
-       (when no prefix configured, `rewritten` IS `request`)
-  2. astroContextMap.set(rewritten, apiContext)            — WeakMap stash
-  3. For each app in order: response = await app.fetch(rewritten)
-       — first response with status !== 404 is returned (a 500 from
-         app A stops dispatch; it is treated as a real answer, not a
-         miss). Only a literal 404 falls through to the next app.
-  4. All apps 404 → new Response(null, { status: 404 })
-  ↓
-Inside any factory-context closure:
-  getAstroContext(c) → reads c.req.raw → WeakMap lookup → APIContext
-```
-
-The WeakMap is keyed by the `Request` object that Hono ends up seeing — i.e., the post-rewrite Request when `pathPrefix` is configured, and the original Request when it isn't. Hono exposes that same Request on `c.req.raw`, which is what `getAstroContext` reads. Stashing happens AFTER the rewrite so the key matches what Hono observes. Entries clear when the Request is GC'd — no manual cleanup, no leak.
-
-## Public API
-
-Two exports:
-
-```ts
-import type { Hono, Context as HonoContext } from 'hono'
-import type { APIContext, APIRoute } from 'astro'
-
-export type AstroAdapterConfig = {
-  /** One or more built Hono apps. Order matters in 'first-match' dispatch. */
-  apps: Hono | Hono[]
-
-  /**
-   * Path prefix matching the Astro catch-all mount point.
-   * For src/pages/api/[...rest].ts use '/api'. The adapter strips this
-   * before delegating, so Hono routes do NOT need to repeat the prefix.
-   *
-   * Normalization: leading and trailing slashes are optional; '/api',
-   * 'api', and '/api/' are equivalent.
-   */
-  pathPrefix?: string
-}
-
-export type AstroHandlers = {
-  ALL: APIRoute
-  GET: APIRoute
-  POST: APIRoute
-  PUT: APIRoute
-  PATCH: APIRoute
-  DELETE: APIRoute
-  HEAD: APIRoute
-  OPTIONS: APIRoute
-}
-
-export function createAstroHandler(config: AstroAdapterConfig): AstroHandlers
-
-/**
- * Read Astro's APIContext from inside a Hono factory-context closure.
- * Throws if called outside an Astro request scope (e.g., if the Hono app
- * is also being served outside the adapter and the closure ran there).
- */
-export function getAstroContext(c: HonoContext): APIContext
-```
-
-`createAstroHandler` returns every method handler so the developer can destructure whichever they want. Most consumers use `ALL`. Per-method exports support cases where Astro's behavior diverges by method (e.g., `HEAD` auto-derived from `GET`).
-
-## Developer-facing usage
-
-```ts
-// src/server/procedures/users.ts
-import { Procedures } from 'ts-procedures'
-import { Type } from 'typebox'
-
-export const usersAPI = Procedures<{ db: Db; user: User | null }, APIConfig>()
-
-usersAPI.Create('GetUser', {
-  path: '/users/:id',
-  method: 'get',
-  schema: {
-    input: { pathParams: Type.Object({ id: Type.String() }) },
-    returnType: Type.Object({ id: Type.String(), name: Type.String() }),
-  },
-}, async (ctx, { pathParams }) => {
-  return ctx.db.users.findOne(pathParams.id)
-})
-```
-
-```ts
-// src/server/api.ts
-import { HonoAPIAppBuilder } from 'ts-procedures/hono-api'
-import { getAstroContext } from 'ts-procedures/astro'
-import { usersAPI } from './procedures/users'
-import { db } from './db'
-
-export const apiApp = new HonoAPIAppBuilder()
-  .register(usersAPI, (c) => {
-    const astro = getAstroContext(c)
-    return { db, user: astro.locals.user ?? null }
-  })
-  .build()
-```
-
-```ts
-// src/pages/api/[...rest].ts
-import { createAstroHandler } from 'ts-procedures/astro'
-import { apiApp } from '../../server/api'
-
-export const { ALL } = createAstroHandler({
-  apps: apiApp,
-  pathPrefix: '/api',
-})
-```
-
-Multi-app variant:
-
-```ts
-export const { ALL } = createAstroHandler({
-  apps: [apiApp, rpcApp, streamsApp],
-  pathPrefix: '/api',
-})
-```
-
-## Path-prefix rewrite
-
-```ts
-function stripPrefix(request: Request, prefix: string | undefined): Request | null {
-  if (!prefix) return request
-  const url = new URL(request.url)
-  const norm = '/' + prefix.replace(/^\/|\/$/g, '')   // → '/api'
-  if (norm === '/') return request
-  if (!url.pathname.startsWith(norm)) return null      // 404 fast-path
-  const rest = url.pathname.slice(norm.length)
-  url.pathname = rest === '' ? '/' : rest
-  return new Request(url, request)                     // copies method/headers/body/signal/duplex
-}
-```
-
-`new Request(url, request)` per the Web spec init pattern preserves method, headers, body stream, abort signal, and `duplex` mode. Body streams pass through; client disconnect aborts continue to fire on `c.req.raw.signal` inside Hono.
-
-Edge cases:
-- `pathPrefix` undefined → no rewrite
-- `pathPrefix` normalizes to `'/'` → no rewrite (root mount)
-- Request path doesn't start with the normalized prefix → adapter returns 404 without invoking any app
-- Exact prefix match (`/api` with request `/api`) → rewrites to `/`
-
-## Streams & abort signals
-
-Hono stream builders return `Response` with a `ReadableStream` body. Astro SSR forwards that body verbatim — no special handling.
-
-`request.signal` flow on client disconnect:
-```
-Browser closes EventSource
-  → Astro aborts request.signal
-  → rewriteRequest preserves signal via new Request(url, request)
-  → Hono's c.req.raw.signal === request.signal
-  → Stream builder's ctx.signal fires (reason 'client-disconnect')
-```
-
-Same path the existing Hono stream tests cover; one new integration test wires Astro→Hono-stream end-to-end.
-
-## Error handling
-
-The adapter performs no error handling of its own. Errors flow through whatever the underlying Hono builder is configured with — taxonomy, `onError`, `onRequestError`. The adapter returns whatever Response Hono produced.
-
-The only Response the adapter constructs itself: a stock `new Response(null, { status: 404 })` returned when (a) the path-prefix rewrite fails (request path outside the mount), or (b) every registered app returned 404.
-
-If `getAstroContext(c)` is called outside an Astro request (the Hono app is also being served via a non-Astro path and the closure ran there), it throws with a clear message. This propagates into Hono's normal error path and through the configured taxonomy.
-
-## File layout
-
-```
-src/implementations/http/astro/
-├── README.md
-├── index.ts                   # public exports
-├── create-handler.ts          # createAstroHandler, multi-app dispatch
-├── astro-context.ts           # WeakMap + getAstroContext
-├── rewrite-request.ts         # stripPrefix
-└── index.test.ts              # integration tests vs real Hono builders
-```
-
-## Tests
-
-Integration-style, real builders, simulated `Request`:
-
-1. Single Hono API app — GET and POST roundtrip, request/response bodies intact, headers preserved
-2. Path prefix normalization: `/api`, `api`, `/api/`, exact-match → root, missing prefix → 404 short-circuit, no prefix configured, query string preserved through the rewrite (`/api/users?limit=10` → inner app sees `/users?limit=10`)
-3. `getAstroContext(c)` returns the same `APIContext` object passed to `ALL`
-4. Multi-app first-match: app A returns 404 → app B handles → app B's response returned
-5. Multi-app non-404 short-circuit: app A returns 500 → app B is NOT invoked; app A's 500 is returned
-6. All-404 fallback returns adapter's 404 (status 404, empty body), not Hono's
-7. Stream pass-through: `HonoStreamAppBuilder` + generator yielding 3 events; verify all 3 reach the consumer through the adapter
-8. Abort signal flow: simulate client disconnect by aborting the incoming `Request` mid-stream; assert `ctx.signal.aborted === true` inside the handler with `signal.reason !== 'stream-completed'`
-9. `getAstroContext` outside Astro scope throws a clear error
-
-## Package wiring
-
-```json
-// package.json (additions)
-"exports": {
-  "./astro": {
-    "types": "./build/implementations/http/astro/index.d.ts",
-    "import": "./build/implementations/http/astro/index.js"
-  }
-},
-"optionalDependencies": {
-  "ajsc": "...",
-  "hono": "...",
-  "astro": "^5.0.0"
-},
-"devDependencies": {
-  "...": "...",
-  "astro": "^5.0.0"
-}
-```
-
-Matching the existing pattern for `hono`: listed as `optionalDependencies` so it isn't pulled into non-Astro deployments, and as `devDependencies` so types resolve at build time. Astro is imported via `import type` only — zero runtime dependency on the published package.
-
-## Agent config / docs
-
-Mirror the pattern used when other builders shipped:
-- New `docs/astro-adapter.md` end-to-end walkthrough
-- Update `agent_config/claude-code/skills/ts-procedures/api-reference.md` and `patterns.md` to teach downstream Claude/Cursor/Copilot rules the Astro path
-- New `agent_config/claude-code/skills/ts-procedures-scaffold/templates/astro-catchall.ts` template
-- `src/implementations/http/astro/README.md` with usage and the prefix-semantics table
-
-## Open questions
-
-None at design time. Ready for implementation planning.