ts-procedures 10.2.0 → 10.2.1

package/agent_config/copilot/copilot-instructions.md

@@ -1,521 +0,0 @@
-# ts-procedures Framework Reference
-
-You are assisting a developer using **ts-procedures**, a TypeScript RPC framework that creates type-safe, schema-validated procedure calls with a single function definition.
-
-## Core Flow
-
-```
-Procedures<TContext, TExtendedConfig>(options?)
-    ↓
-Create(name, config, handler)           → Standard async procedure   (kind: 'rpc')
-CreateStream(name, config, handler)     → Streaming async generator  (kind: 'rpc-stream')
-CreateHttp(name, config, handler)       → REST-style HTTP route      (kind: 'http')
-CreateHttpStream(name, config, handler) → REST-style streaming route (kind: 'http-stream')
-    ↓
-Returns: { [name]: handler, procedure: handler, info: metadata }
-```
-
-Every registration and every creator's `info` carries the `kind` discriminant — branch on it (there is no `isStream` flag).
-
-## Imports
-
-```typescript
-// Core
-import { Procedures } from 'ts-procedures'
-import type { Infer, SchemaAdapter, TLocalContext, TStreamContext, TProcedureRegistration, TStreamProcedureRegistration } from 'ts-procedures'
-
-// Errors
-import { ProcedureError, ProcedureValidationError, ProcedureYieldValidationError, ProcedureRegistrationError } from 'ts-procedures'
-
-// HTTP types
-import type { RPCConfig, APIConfig, APIInput, RPCHttpRouteDoc, StreamHttpRouteDoc, StreamMode } from 'ts-procedures/http'
-
-// Hono (RPC, streaming, REST — one unified builder)
-import { HonoAppBuilder, sse, defineErrorTaxonomy } from 'ts-procedures/hono'
-
-// Doc Registry — compose route docs from multiple builders
-import { DocRegistry } from 'ts-procedures/http-docs'
-import type { DocEnvelope, HeaderDoc, ErrorDoc } from 'ts-procedures/http-docs'
-
-// Server toolkit — transport-agnostic building blocks for writing custom adapters (Fastify, Express, ...)
-// Also re-exports DocRegistry, writeDocEnvelope, defineErrorTaxonomy, sse, and the doc builders
-import { dispatchPreStreamError, dispatchMidStreamError, extractReqChannels, buildRpcRouteDoc, SseEventSequencer } from 'ts-procedures/server'
-import type { RequestSource } from 'ts-procedures/server'
-```
-
-## Architecture Rules
-
-1. **schema.params is validated at runtime; schema.returnType is documentation only.** Never expect returnType to be validated. Use TypeScript for return type safety.
-
-2. **Use ctx.error() for business logic errors.** Never throw raw `Error` instances. `ctx.error(message, meta?)` creates `ProcedureError` with procedure name, metadata, and enhanced stack trace.
-
-3. **Pass ctx.signal to all downstream async calls.** HTTP implementations inject AbortSignal automatically. Pass it to fetch, database queries, and other async operations for cancellation support.
-
-4. **Stream handlers always have ctx.signal (guaranteed AbortSignal).** Standard handlers get it when HTTP implementations provide it. Check `signal.reason === 'stream-completed'` to distinguish normal completion from client disconnect.
-
-5. **Use TypeBox for schemas** (`import { Type } from 'typebox'`). Plain JSON Schema objects are not recognized. TypeBox is the built-in schema library; other libraries plug in via the `SchemaAdapter` interface (`Procedures({ schema: { adapters: [myAdapter] } })` — `{ name, detect, toJsonSchema }`). Custom adapters get runtime validation + docs only; compile-time `Infer<T>` inference is TypeBox-only. Default AJV config: `allErrors: true`, `coerceTypes: true`, `removeAdditional: true` — customize per factory via `Procedures({ validation: { ajv } })` (options merged over defaults, or a configured Ajv instance). The bundled TypeBox does **not** export `Type.Composite` — compose schemas with a flat property spread (`Type.Object({ ...Base.properties, name: Type.String() })`), which also keeps the generated JSON Schema a single `object` instead of an `allOf`.
-
-6. **Prefer middleware + layered context for access levels.** Use `HonoAppBuilder` `middleware`, `.use()`, or per-`register({ middleware, context })` for tenant/auth. Separate factories are still valid for truly disjoint `TContext` shapes.
-
-7. **onCreate callback enables framework integration.** Use for route registration, OpenAPI generation, logging.
-
-8. **getProcedures() for introspection.** Returns all registered procedures with metadata.
-
-9. **`Procedures({ validation: false })` skips per-call AJV validation** for every procedure on the factory (all four creators, both `schema.params` and `schema.req`). JSON Schema and validators are still computed at registration time (bad schemas still fail fast), so codegen and `info.schema` are unaffected; only the per-call validator runs are bypassed. **Never enable this on a factory whose handlers are reachable from public/untrusted callers** — coerceTypes and removeAdditional also stop running. Reserve for trusted internal factories whose callers are already type-checked at build time. Independent of the per-call `ctx.isPrevalidated` escape hatch used by HTTP builders.
-
-10. **`Procedures({ http: { pathPrefix, scope } })` sets factory-level defaults for `CreateHttp` / `CreateHttpStream`.** `pathPrefix` is prepended to every route's `path` at registration time — it becomes part of the route's identity (shows up in `config.path` and route docs), unlike the builder-level `pathPrefix`, which is a deployment mount point. `scope` is the default codegen scope for routes that don't set one; per-route values win.
-
-## Procedure Pattern
-
-```typescript
-import { Procedures } from 'ts-procedures'
-import { Type } from 'typebox'
-
-type AppContext = { userId: string; signal?: AbortSignal }
-
-const { Create, CreateStream } = Procedures<AppContext>()
-
-// Standard procedure
-const { GetUser } = Create(
-  'GetUser',
-  {
-    description: 'Fetch user by ID',
-    schema: {
-      params: Type.Object({ id: Type.String() }),
-      returnType: Type.Object({ id: Type.String(), name: Type.String() }),
-    },
-  },
-  async (ctx, params) => {
-    // params.id guaranteed string (AJV validated)
-    const user = await fetchUser(params.id, { signal: ctx.signal })
-    if (!user) throw ctx.error('Not found', { code: 'NOT_FOUND' })
-    return user
-  }
-)
-```
-
-## Stream Procedure Pattern
-
-```typescript
-const { StreamEvents } = CreateStream(
-  'StreamEvents',
-  {
-    schema: {
-      params: Type.Object({ channel: Type.String() }),
-      yieldType: Type.Object({ type: Type.String(), data: Type.Any() }),
-    },
-  },
-  async function* (ctx, params) {
-    // ctx.signal always present in streams
-    while (!ctx.signal.aborted) {
-      const event = await pollEvents(params.channel, { signal: ctx.signal })
-      yield event
-    }
-  }
-)
-```
-
-## Hono RPC Pattern
-
-```typescript
-import { HonoAppBuilder } from 'ts-procedures/hono'
-
-const app = new HonoAppBuilder({ pathPrefix: '/api' })
-  .register(RPC, (c) => ({ userId: c.req.header('x-user-id') }))
-  .build()
-```
-
-## Hono Streaming Pattern
-
-```typescript
-import { HonoAppBuilder, sse } from 'ts-procedures/hono'
-
-const StreamRPC = Procedures<AppContext, RPCConfig>()
-
-StreamRPC.CreateStream('Feed', {
-  scope: 'events', version: 1,
-  schema: { params: Type.Object({ channel: Type.String() }) },
-}, async function* (ctx, params) {
-  while (!ctx.signal.aborted) {
-    const event = await poll({ signal: ctx.signal })
-    yield sse(event, { event: 'update' })
-  }
-})
-
-const app = new HonoAppBuilder({ stream: { defaultStreamMode: 'sse' } })
-  .register(StreamRPC, (c) => ({ userId: c.req.header('x-user-id') }))
-  .build()
-// GET|POST /events/feed/1
-```
-
-SSE wire behavior is identical for `rpc-stream` and `http-stream` routes (one shared `SseEventSequencer`): `sse(data, { event, id, retry })` metadata is honored on yields and error events of both kinds, and a `null` yield serializes as empty SSE data on both.
-
-## Hono API Pattern (REST-style) — `CreateHttp`
-
-HTTP routes use `CreateHttp` (not `Create + APIConfig`). Request channels live under `schema.req` (`pathParams`, `query`, `body`, `headers`); response docs under `schema.res`. The factory needs no `APIConfig` type parameter.
-
-```typescript
-import { HonoAppBuilder } from 'ts-procedures/hono'
-
-const API = Procedures<AppContext>()
-
-API.CreateHttp('GetUser', {
-  path: '/users/:id', method: 'get',
-  schema: {
-    req: { pathParams: Type.Object({ id: Type.String() }) },
-    res: { body: Type.Object({ id: Type.String(), name: Type.String() }) },
-  },
-}, async (ctx, { pathParams }) => fetchUser(pathParams.id))
-
-API.CreateHttp('CreateUser', {
-  path: '/users', method: 'post',
-  schema: {
-    req: { body: Type.Object({ name: Type.String() }) },
-  },
-}, async (ctx, { body }) => createUser(body))
-
-const app = new HonoAppBuilder({ pathPrefix: '/api' })
-  .register(API, (c) => ({ userId: c.req.header('x-user-id') }))
-  .build()
-// GET /api/users/:id → 200, POST /api/users → 201
-```
-
-Streaming HTTP routes use `CreateHttpStream` with `schema.yield` (and optional `schema.res.headers`) — both schemas flow into route docs and generated client types.
-
-**v8 → v9 migration:**
-
-1. `Procedures({ config: { noRuntimeValidation: true } })` → `Procedures({ validation: false })`
-2. Suretype schemas → TypeBox (or a custom `SchemaAdapter`); `isSuretypeSchema` removed
-3. `registration.isStream` → branch on the `kind` discriminant (`'rpc' | 'rpc-stream' | 'http' | 'http-stream'`)
-4. Duplicate-name registration now throws `ProcedureRegistrationError` instead of a bare `Error` (same message)
-5. `schemaParser` removed — use `computeSchema(name, schema, { adapters, compile })`; `extractJsonSchema(schema, adapters)` takes the adapter list explicitly
-6. Codegen CLI/options/output unchanged — regenerated clients are byte-identical to v8.6.0
-
-## Astro adapter
-
-Catch-all endpoint pattern. Build Hono apps once with `HonoAppBuilder`, mount via `createAstroHandler` in `src/pages/api/[...rest].ts` with `pathPrefix: '/api'`. Read Astro context inside factory closures with `getAstroContext(c)`. Multi-app dispatch is first-non-404-wins.
-
-## Error Handling
-
-| Error Class | Trigger | HTTP Status |
-|-------------|---------|-------------|
-| `ProcedureValidationError` | Schema params validation failure | 400 (auto — default taxonomy) |
-| `ProcedureError` | `ctx.error()` or unhandled handler exception | 500 (auto — default taxonomy) |
-| `ProcedureYieldValidationError` | Yield validation failure (validateYields: true) | N/A (mid-stream) |
-| `ProcedureRegistrationError` | Invalid schema or duplicate name at registration | N/A (startup) |
-
-Every framework error instance carries a `kind` field (`'procedure' | 'validation' | 'yield-validation' | 'registration'`) as an alternative to `instanceof`.
-
-### Error Taxonomy (required for custom errors)
-
-`defineErrorTaxonomy` maps error classes to HTTP responses declaratively. Works with `HonoAppBuilder` for `rpc`, `http`, and pre-stream paths (`rpc-stream` / `http-stream`).
-
-Do NOT write `onError` `instanceof` ladders — that's anti-pattern #20. Use the taxonomy instead:
-
-```typescript
-import { defineErrorTaxonomy } from 'ts-procedures/http-errors'
-
-class UseCaseError extends Error {
-  constructor(readonly externalMsg: string, readonly internalMsg: string) {
-    super(externalMsg); this.name = 'UseCaseError'
-    Object.setPrototypeOf(this, UseCaseError.prototype)
-  }
-}
-
-const appErrors = defineErrorTaxonomy({
-  // class: entries are topologically sorted (subclasses checked first) automatically.
-  // Predicate (match:) entries keep declared order — put narrower predicates first.
-  UseCaseError: {
-    class: UseCaseError,
-    statusCode: 422,
-    toResponse: (err) => ({ name: 'UseCaseError', message: err.externalMsg }),
-    onCatch: (err) => logger.error(err.internalMsg), // internal logs only
-  },
-  MongoDuplicateKey: {
-    match: (err): err is Error => err instanceof Error && (err as any).code === 11000,
-    statusCode: 409,
-    toResponse: () => ({ name: 'Conflict', message: 'Resource already exists' }),
-  },
-})
-
-new HonoAppBuilder({
-  errors: appErrors,
-  unknownError: { statusCode: 500, toResponse: () => ({ name: 'InternalServerError' }) },
-})
-```
-
-Handlers throw the error classes directly — the builder auto-serializes. `onError` is the first-class imperative peer when you want to handle errors in one callback instead (both modes coexist). In v6 `HonoAppBuilder.onPreStreamError` was renamed to `onError`. Cross-cutting `onRequestError` observer fires for every caught error.
-
-Custom (non-Hono) adapters consume the same taxonomy via `ts-procedures/server`'s `dispatchPreStreamError` / `dispatchMidStreamError`, which return plain data (`{ type: 'body', statusCode, body } | { type: 'response', response }` / `{ data, sseEvent?, runOnCatch? }`) — your adapter translates that into its framework's response.
-
-### Per-route errors (typed)
-
-Declare a route's errors via the `errors` field on the `CreateHttp` config. For compile-time typo protection, attach a `satisfies` clause to the array — do NOT pass an explicit generic. `CreateHttp` is generic over `<TName, TReq, TRes, TErrorKey>`, so a single type argument binds `TName` and breaks `schema.req` / `schema.res` inference:
-
-```typescript
-import { DocRegistry } from 'ts-procedures/http-docs'
-
-const API = Procedures<Ctx>()
-
-API.CreateHttp('GetUser', {
-  path: '/users/:id', method: 'get',
-  errors: ['UseCaseError'] satisfies (keyof typeof appErrors & string)[],
-  schema: { req: { pathParams: Type.Object({ id: Type.String() }) } },
-}, async (ctx, { pathParams }) => fetchUser(pathParams.id))
-
-// Seed envelope errors from the taxonomy + framework defaults in one call
-const envelope = new DocRegistry({ errors: appErrors, basePath: '/api' }).from(apiApp).toJSON()
-```
-
-### Client-side typed catch blocks (via codegen)
-
-The generated `_errors.ts` emits real runtime classes extending a shared `${Service}ProcedureError` base. The generated `createApiClient` wires an error registry so non-2xx responses arrive as typed class instances:
-
-```typescript
-import { createApiClient, ApiErrors, createFetchAdapter } from './generated'
-
-const api = createApiClient({ adapter: createFetchAdapter({ /* ... */ }), basePath: '...' })
-
-try {
-  await api.users.getUser({ pathParams: { id: 'x' } })
-} catch (err) {
-  if (err instanceof ApiErrors.UseCaseError) {
-    // err.body typed; err.status, err.procedureName, err.scope available
-  } else if (err instanceof ApiErrors.ApiProcedureError) {
-    // Catch-all for any service error
-  }
-}
-```
-
-Typed classes are generated automatically for taxonomy entries declared with just `{ class, statusCode }` (their default `{ name, message }` body is self-describing). Add an explicit `schema` only when you give an entry a custom `toResponse` (shape can't be inferred) or document a raw `ErrorDoc` (via `documentError(...)` / a `config.errors` array) — without a schema those dispatch as the untyped `ClientHttpError`.
-
-Per-route error unions: routes with `errors: [...]` get an `Errors` type in their namespace (e.g. `Users.GetUser.Errors = ApiErrors.UseCaseError | ApiErrors.AuthError`).
-
-- Generated client error handling: catch the framework classes (`ClientHttpError`, `ClientNetworkError`, `ClientTimeoutError`, `ClientAbortError`), not raw `DOMException`/`TypeError` — the framework normalizes platform errors at the `executeCall` boundary, so raw platform errors no longer reach `catch` blocks after 7.0.0 (original is on `error.cause`). Use the `.safe()` sibling on RPC/API callables for an exhaustive `Result<T, E>` switch (`ok`, `typed`, `http`, `network`, `timeout`, `aborted`, `parse`, `usage`, `unknown`). Streams keep the throwing form — no `.safe()`.
-
-## Lifecycle Hook Order
-
-### Standard RPC
-```
-onRequestStart → factoryContext() → handler() → onSuccess → onRequestEnd
-                                  → onError  → onRequestEnd
-```
-
-### Streaming
-```
-onRequestStart → factoryContext() → validation → onStreamStart → handler yields → onStreamEnd → onRequestEnd
-                                               → onError (or taxonomy) → onRequestEnd
-                                                                  → onMidStreamError → onStreamEnd → onRequestEnd
-```
-
-## Decision Framework
-
-**Which procedure type?**
-- Single response (RPC) → `Create`
-- Multiple values over time (RPC) → `CreateStream`
-- REST-style route (`path` + `method`) → `CreateHttp`
-- REST-style streaming route → `CreateHttpStream`
-
-**Which schema library?**
-- **TypeBox** (`import { Type } from 'typebox'`) — built in, with `Infer<T>` type inference
-- Other libraries → implement `SchemaAdapter` and pass `Procedures({ schema: { adapters: [...] } })` (runtime validation + docs only)
-
-**Which HTTP implementation?**
-- Hono (RPC, streams, REST, REST streams) → `HonoAppBuilder`
-- Other frameworks (Fastify, Express, ...) → write a thin adapter on `ts-procedures/server` (doc builders, taxonomy dispatch returning data, `extractReqChannels`/`RequestSource`, `SseEventSequencer`); use the Hono adapter as the blueprint
-
-**Stream mode?**
-- Browser EventSource → `'sse'` (default)
-- Simple HTTP client → `'text'` (newline-delimited JSON)
-
-## Anti-Patterns — NEVER Do These
-
-1. **Never throw raw Error** — use `ctx.error(message, meta?)`
-2. **Never expect returnType runtime validation** — it's docs only
-3. **Never put validation logic in handler** — use `schema.params`
-4. **Never ignore ctx.signal** — pass to all async calls
-5. **Never skip signal.aborted check in stream loops** — causes resource leaks
-6. **Never branch on `isStream`** — removed in v9; use the `kind` discriminant (on registrations and every creator's `info`)
-7. **Never use plain JSON Schema objects** — use TypeBox builders (or register a `SchemaAdapter` for another library)
-8. **Never swallow errors without re-throwing** — hides failures
-9. **Never assume extra params fields survive** — `removeAdditional: true` strips them
-10. **Never manually parse types AJV coerces** — `coerceTypes: true` handles it
-11. **Never put `schema.req` on `Create`/`CreateStream` or `schema.params` on `CreateHttp`/`CreateHttpStream`** — RPC creators take `schema.params`; HTTP creators take `schema.req` channels
-12. **Never catch raw DOMException/TypeError from generated callables** — catch `ClientTimeoutError`, `ClientAbortError`, `ClientNetworkError` instead; or use `.safe()` for Result-based narrowing
-13. **Never use `Create` for HTTP routes (v8+)** — use `CreateHttp` (unary) or `CreateHttpStream` (streaming); request channels go under `schema.req`; `Procedures<Ctx, APIConfig>()` → `Procedures<Ctx>()`
-
-## Testing
-
-```typescript
-import { describe, test, expect } from 'vitest'
-import { ProcedureError, ProcedureValidationError } from 'ts-procedures'
-
-describe('GetUser', () => {
-  test('valid params', async () => {
-    const result = await GetUser(mockCtx, { id: 'user-1' })
-    expect(result.id).toBe('user-1')
-  })
-
-  test('invalid params', async () => {
-    await expect(GetUser(mockCtx, {})).rejects.toThrow(ProcedureValidationError)
-  })
-
-  test('business error', async () => {
-    await expect(GetUser(mockCtx, { id: 'missing' })).rejects.toThrow(ProcedureError)
-  })
-})
-```
-
-## HTTP Route Path Format
-
-`{pathPrefix}/{scope}/{kebab-case-name}/{version}`
-
-- `scope` can be string or string[] (joined as path segments)
-- Procedure name auto-converted to kebab-case
-- Stream routes support both GET (query params) and POST (JSON body)
-
-## Client Code Generation
-
-Generate type-safe client SDKs from a running DocRegistry endpoint.
-
-### Imports
-
-```typescript
-// Client Runtime
-import { createClient, createFetchAdapter } from 'ts-procedures/client'
-import type { ClientAdapter, ClientHooks, TypedStream, ClientInstance } from 'ts-procedures/client'
-
-// Code Generation (build-time only)
-import { generateClient } from 'ts-procedures/codegen'
-```
-
-### CLI
-
-```bash
-npx ts-procedures-codegen --url http://localhost:3000/docs --out ./src/generated/api
-# Defaults (on): --self-contained --namespace-types --jsdoc --clean-out-dir
-#                  (--clean-out-dir prunes orphaned generated files signed by ts-procedures-codegen; never deletes hand-written files)
-# Opt-out flags:  --no-self-contained --no-namespace-types --no-jsdoc --no-clean-out-dir
-# Optional flags: --depluralize --enum-style union
-#                  --array-item-naming Item --uncountable-words criteria,alumni
-#                  --dry-run --watch --client-import-path @my-app/client
-#                  --config ./codegen.config.json --service-name Auth
-#                  --check [--check-mode scan|tsc]  (self-validate output; exit non-zero if it won't compile)
-```
-
-For Kotlin codegen (Android/JVM consumers), see `docs/codegen-kotlin.md` in the ts-procedures repo. The Kotlin target is types-only; consumer apps own HTTP/error handling.
-For Swift codegen (iOS/macOS/Apple-platform consumers), see `docs/codegen-swift.md` in the ts-procedures repo. The Swift target is types-only; consumer apps own HTTP/error handling.
-
-Generates one `.ts` file per scope plus a root `index.ts` that imports each scope as a namespace and exports a `create${ServiceName}Bindings(client)` factory AND a `create${ServiceName}Client(config)` convenience factory that pre-wires the error registry (defaults to `createApiBindings` / `createApiClient`; pass `--service-name <Name>` to rename). When namespace mode is on (the default), `index.ts` also wraps every scope namespace in an outer `export namespace ${ServiceName} { ... }` block so types are reachable as `Api.Users.GetUser.Params`, `Api.Errors.UseCaseError`, etc. The errors file (`_errors.ts`) emits runtime error classes extending a shared `${ServiceName}ProcedureError` base, each with `static fromResponse(body, meta)`, plus `${ServiceName}ErrorRegistry` (runtime dispatch map) and `${ServiceName}ProcedureErrorUnion` (type union). Defaults: `ApiErrors`, `ApiProcedureError`, `ApiErrorRegistry`, `ApiProcedureErrorUnion`.
-By default, types are wrapped in nested TS namespaces (`Scope.Route.Params`), JSDoc comments are emitted, and output is self-contained (no runtime dependency on `ts-procedures`). Use `--no-namespace-types` to revert to flat type names (`RouteParams`); this also disables the outer service namespace in `index.ts` and skips importing `_errors` from there.
-The generated client is **compatible with `tsconfig` `verbatimModuleSyntax: true`** (the strictest mode astro/tsconfigs and many monorepos enable). In namespace mode the scope's `bindScope(client)` function is emitted as a member of `export namespace ${Pascal}` so the namespace is value+type — required for the index's `export import` re-exports to compile under verbatim. Most consumers stay on `create${Name}Bindings(client)` / `create${Name}Client(config)` and never touch `bindScope` directly.
-**Strict CLI**: any unknown `--…` flag throws immediately with a `Did you mean …?` suggestion when the typo is close to a known flag (e.g. `--targt` → `--target`, `--service` → `--service-name`). Typos no longer fall through silently.
-**Generation-time guards** (fail fast, non-zero): two routes in a scope whose names PascalCase to the same identifier (e.g. `get-task` + `getTask`), or a scope name colliding with `--service-name` (e.g. scope `godmode` + `--service-name Godmode`), error at generation with the fix to make. Opt into `--check` (or `generateClient({ validate: true })`) to validate the whole emitted client and fail loud if it won't compile — recommended in CI.
-Note: ajsc formatting options (`--enum-style enum`, `--depluralize`, etc.) only take effect in namespace mode (the default). They are ignored with `--no-namespace-types`.
-Supports config file: `ts-procedures-codegen.config.json` (auto-loaded from CWD) or `--config <path>`.
-
-### createClient Example
-
-```typescript
-import { createClient, createFetchAdapter } from 'ts-procedures/client'
-import { createApiBindings, Api } from './generated/api'
-// With --service-name <Name>: import { create<Name>Bindings, <Name> } from './generated/api'
-
-const client = createClient({
-  adapter: createFetchAdapter(),
-  basePath: 'http://localhost:3000',
-  scopes: createApiBindings,
-  defaults: { timeout: 30_000, headers: { 'X-Client-Version': '1.0.0' } },
-  hooks: {
-    onBeforeRequest(ctx) {
-      ctx.request.headers = { ...ctx.request.headers, Authorization: `Bearer ${getToken()}` }
-      return ctx
-    },
-    onAfterResponse(ctx) {
-      if (ctx.response.status === 401) redirect('/login')
-    },
-  },
-})
-
-// Fully typed — params and response inferred from server schemas; type aliases live under Api.<Scope>.<Route>.
-const user = await client.users.GetUser({ pathParams: { id: '123' } })
-
-// Per-call options — timeout, signal, headers, basePath, and hooks all share one bag
-await client.users.GetUser(
-  { pathParams: { id: '123' } },
-  {
-    timeout: 5000,
-    headers: { 'X-Request-Id': crypto.randomUUID() },
-    onAfterResponse(ctx) {
-      console.log(ctx.response.headers['x-rate-limit-remaining'])
-    },
-  },
-)
-```
-
-### Per-Call Options & Defaults
-
-```typescript
-interface ProcedureCallDefaults {
-  signal?: AbortSignal      // cancellation (combined with per-call via AbortSignal.any)
-  timeout?: number          // ms — per-call timeout:0 disables inherited default
-  headers?: Record<string, string>  // merged, per-call keys win
-  basePath?: string         // per-call > default > config.basePath
-  meta?: RequestMeta        // typed per-request metadata (declaration-mergeable)
-}
-
-interface ProcedureCallOptions extends ProcedureCallDefaults, ClientHooks {}
-```
-
-- Defaults are set via `config.defaults`; per-call options are passed as the 2nd argument to any generated callable.
-- Header precedence (low → high): adapter config < `defaults.headers` < per-call `headers` < route-declared `schema.req.headers` < `onBeforeRequest` mutations.
-
-### Typed RequestMeta (Declaration Merging)
-
-Augment `RequestMeta` to type `meta` end-to-end (options, hooks, adapter):
-
-```typescript
-// For code-generated self-contained clients
-declare module './generated/_types' {
-  interface RequestMeta {
-    traceId: string
-    priority?: 'high' | 'low'
-  }
-}
-
-// Or for direct ts-procedures/client usage
-declare module 'ts-procedures/client' {
-  interface RequestMeta { traceId: string }
-}
-
-await client.users.GetUser(
-  { pathParams: { id: '1' } },
-  { meta: { traceId: 'req-abc', priority: 'high' } },  // fully typed
-)
-```
-
-### Hook Types
-
-```typescript
-interface ClientHooks {
-  onBeforeRequest?: (ctx: BeforeRequestContext) => BeforeRequestContext | Promise<BeforeRequestContext>
-  onAfterResponse?: (ctx: AfterResponseContext) => void | Promise<void>
-  onError?: (ctx: ErrorContext) => void | Promise<void>
-}
-```
-
-### TypedStream Usage
-
-```typescript
-const stream = client.events.WatchNotifications({ filter: 'all' })
-
-for await (const event of stream) {
-  console.log(event) // Typed as WatchNotificationsYield
-}
-
-const result = await stream.result // Typed as WatchNotificationsReturn
-```
-
-- `TypedStream<TYield, TReturn>` extends `AsyncIterable<TYield>`
-- `stream.result` resolves with the final return value sent as `event: 'return'` SSE message
-- Stream procedures that return `void` have `result` resolve to `undefined`