ts-procedures 8.3.0 → 8.5.0

package/docs/superpowers/specs/2026-06-05-dx-feedback-round-design.md

@@ -0,0 +1,285 @@
+# DX Feedback Round — Design
+
+**Date:** 2026-06-05
+**Status:** Approved (pending spec review)
+**Source:** Downstream-developer feedback from building the demo server (`src/server`), 5 findings.
+
+This round addresses five findings. Each section states the problem, the decision
+taken (with the alternatives considered), and the concrete shape of the change.
+
+Two items are cross-logged but **explicitly out of scope** this round (no scope creep):
+- The `ts-channels` codegen has the identical #3 (per-route inlining) defect — coordinating the two is follow-up.
+- #5 is cross-logged with `ts-channels #9` / `mvc-kit #2` — aligning all three scaffolders is follow-up.
+
+---
+
+## #1 — `ts-procedures-codegen --help` (MEDIUM)
+
+### Problem
+`--help` falls through to the unknown-flag branch and exits non-zero with a
+misfiring did-you-mean suggestion (`Did you mean --url?`). There is no usage text
+anywhere in the CLI, so the rich flag surface (`--watch`, `--dry-run`,
+`--enum-style`, Kotlin/Swift targets, …) is undiscoverable without reading the
+built JS.
+
+### Decision: structured flags as the single source of truth
+Replace the bare-string `KNOWN_FLAGS` array (`src/codegen/bin/cli.ts`) with a
+structured table — one entry per flag:
+
+```ts
+interface FlagSpec {
+  name: string            // '--service-name'
+  arg?: string            // '<name>'  (omitted for booleans)
+  description: string     // one line
+  group: 'Source' | 'Output' | 'Codegen' | 'Targets' | 'Misc'
+  default?: string        // shown in help when meaningful, e.g. 'Api'
+}
+```
+
+Derive **both** the validation set (the current `KNOWN_FLAGS` membership check)
+and the `--help` output from this table — adding a flag now documents it and the
+two can never drift. This directly resolves the CLAUDE.md warning that
+`KNOWN_FLAGS` must be hand-synced with `parseArgs`.
+
+Behaviour:
+- `--help` / `-h` / **bare invocation with no args** → print grouped usage
+  (header, usage line, flags grouped by `group` with aligned descriptions and
+  defaults) and **exit 0**.
+- Exclude `--help`/`-h` from the did-you-mean candidate set so the suggestion is
+  never actively misleading.
+
+### Alternatives considered
+- *Hand-written usage block, `KNOWN_FLAGS` stays bare strings.* Rejected:
+  descriptions live apart from the flag list and drift — exactly the duplication
+  the codebase warns against.
+
+---
+
+## #2 — Offline doc-envelope emission (LOW)
+
+### Problem
+`--file <path>` codegen works, but nothing *produces* that file. The envelope
+only exists in-process via `builder.toDocEnvelope(cfg)`, so the regen loop forces
+either a running server (`codegen --url`) or a hand-written `JSON.stringify`
+script.
+
+### Decision: exported helper only
+Ship a public, stable helper:
+
+```ts
+export async function writeDocEnvelope(
+  source: DocEnvelope | { toDocEnvelope(): DocEnvelope } | DocRegistry,
+  path: string,
+): Promise<void>
+```
+
+- Accepts a built `HonoAppBuilder`/`DocRegistry` (anything with
+  `toDocEnvelope()`) **or** a plain `DocEnvelope`.
+- Serializes pretty JSON to `path` (creating parent dirs).
+- Exported from a stable entry point and documented with a 3-line script:
+  `build builder → writeDocEnvelope(builder, 'docs.json') → codegen --file docs.json`.
+
+No module-loading magic in the CLI — the user owns the tiny emit script, which is
+the most portable option and avoids a TS-loader dependency.
+
+### Alternatives considered
+- *CLI `--builder <module>` that imports the user's builder in-process.* Rejected
+  for now: importing user TS/ESM requires a loader (tsx/jiti) the package doesn't
+  carry; pushes complexity and failure modes into the CLI.
+
+---
+
+## #3 — Shared types keyed on `$id` (MEDIUM)
+
+### Problem
+Codegen inlines a fresh structural literal at every route site. The same `Message`
+entity is emitted ~4× under different names in one scope file
+(`GetThread.Response.Message`, `ListMessages.Response.RootType`,
+`SendMessage.Response.Body`, nested in `CreateThread`), none connected to the
+authored `@shared/schemas` `Message`. The copies type-check only because the
+shapes coincide today; a field change one codegen path misses drifts **silently**.
+
+### Decision: hoist in codegen, leave the envelope untouched
+
+**Architectural call.** The `$id` already rides along on route subschemas in the
+envelope (verified: `Type.Object({…}, { $id, title })` survives `toDocEnvelope()`).
+Rather than change the envelope into a `$defs`/`$ref` table — which would break
+every already-serialized envelope and force the Kotlin/Swift pipelines to become
+`$ref`-aware — the **TS codegen** does a pre-pass over the inlined schemas. Result:
+zero envelope-shape change, zero impact on Kotlin/Swift, already-serialized
+envelopes keep working.
+
+#### Identity rule (correctness-critical)
+- Hoist **only** schemas carrying `$id`. `$id` is the dedup key (globally unique).
+- The generated type **name** comes from `title` (fallback: derive from `$id`).
+- Schemas with a `title` but no `$id` are **not** hoisted — they stay inlined
+  exactly as today. Identity is *declared*, never inferred from structure.
+- If two subschemas share an `$id` but have **divergent bodies** → **hard error**
+  at collect time (never silently pick one).
+- Schemas without `$id` produce byte-identical output to today, so existing
+  consumers who never set `$id` see no change.
+
+#### Components
+1. **`src/codegen/collect-models.ts`** (new) — walks every route's JSON schema
+   recursively (all four route kinds: rpc/api/stream/http-stream slots), collects
+   each subschema carrying `$id` into a model registry
+   `{ $id, name, schema }`. Detects `$id` body-divergence collisions and throws.
+   Also detects generated-name collisions between distinct `$id`s and disambiguates
+   (`Message`, `Message2`, …) deterministically by first-seen order.
+
+2. **`_models.ts`** (new emitted file) — the single hub:
+   - For each model whose `$id` is in the `sharedTypesImport` map → emit a
+     re-export: `export { Message } from '@shared/schemas'` (renamed to the
+     model name if `name` differs).
+   - Otherwise → emit a generated named type for the model schema (via ajsc).
+   - Scopes **always** import from `_models.ts`, regardless of generated-vs-vendored.
+     Flipping a type between the two is a one-line change here with zero scope churn.
+
+3. **`emit-scope` change** — when a route's schema contains a hoisted `$id`
+   subschema, the emitted route type **references** the model's name (import in
+   flat mode, qualified `${Service}Models.Message` in namespace mode) instead of
+   inlining the literal. Non-hoisted subschemas emit unchanged.
+
+4. **`sharedTypesImport` config** (config-file only — a map doesn't fit a CLI flag):
+   ```jsonc
+   // ts-procedures-codegen.config.json
+   "sharedTypesImport": {
+     "https://schemas.example/message": { "module": "@shared/schemas", "name": "Message" }
+   }
+   ```
+
+5. **Flag:** `--share-models` defaults **on** (consistent with the other
+   good-by-default flags); `--no-share-models` opts out and restores pure
+   per-route inlining. Added to the structured flag table from #1.
+
+#### Scope
+- **TS target only.** Kotlin/Swift continue to inline (they simply ignore `$id`
+  metadata; the envelope is unchanged so their pipelines are untouched).
+
+#### Key technical risk — verify first
+The plan opens with a short **verification spike** before committing the emission
+mechanism:
+- **ajsc `$ref` behaviour (v7.2.0):** confirm how ajsc emits a `$ref` to a hoisted
+  model — whether it produces a *reference* to a named type or inlines it. Per
+  CLAUDE.md ajsc "resolves `$defs`/`$ref`", which may mean *inline*. Two paths:
+  - *Preferred:* feed ajsc a route schema with the hoisted subschema replaced by
+    `{ $ref: '#/$defs/Message' }` + a `$defs` table, and capture ajsc's named-type
+    reference.
+  - *Fallback:* emit model types standalone, then post-emit string-substitute the
+    inlined literal with the model name — the same word-boundary patching approach
+    `renameExtractedTypes` (`src/codegen/emit-types.ts`) already uses.
+- **Nested `$id` survival:** confirm `extractJsonSchema` preserves `$id` on
+  **nested** subschemas (root `$id` is verified; nested is not). If stripped, fix
+  extraction to preserve it — this is a prerequisite for hoisting nested entities
+  like `Thread.messages: Message[]`.
+
+### Alternatives considered
+- *Change the envelope to `$defs`/`$ref`.* Rejected: breaks serialized envelopes
+  and forces all targets to become `$ref`-aware.
+- *Hoist into existing `_types.ts`.* Rejected: mixes domain entities with
+  transport/runtime types and only works in self-contained mode.
+- *Per-scope first-declarer-owns.* Rejected: implicit cross-scope ordering/coupling.
+- *Auto-merge structurally-identical types.* Explicitly rejected per the feedback:
+  coincidental shape-equality must not couple two scopes.
+- *Dedup by `$id` OR `title`.* Rejected: two unrelated schemas titled `Response`
+  would wrongly merge — weak identity.
+
+---
+
+## #4 — Dynamic auth seam: function-valued headers (MEDIUM)
+
+### Problem
+`config.headers` is a static `Record<string,string>` (`src/client/types.ts:202`),
+captured once at construction. The only dynamic seam is `onBeforeRequest`, which
+is discoverable only by reading `_client.ts`. A live bearer token set in `headers`
+silently goes stale after the next login (the easy-and-wrong path compiles).
+
+### Decision: function-valued headers + signposting docs
+Make `headers` accept a function on both the client `defaults` and per-call options:
+
+```ts
+type HeadersInit =
+  | Record<string, string>
+  | (() => Record<string, string> | Promise<Record<string, string>>)
+```
+
+- `ProcedureCallDefaults.headers` and `ProcedureCallOptions.headers` adopt
+  `HeadersInit` (`src/client/types.ts`).
+- Resolution happens on the **async request path**: `call.ts` / `stream.ts` await
+  header resolution before building the `AdapterRequest`. The static-record path
+  stays synchronous and fast (no behavioural change when headers is a plain object).
+- Merge semantics preserved: resolve defaults-headers and per-call-headers to
+  records, then merge with per-call winning — `onBeforeRequest` still has final say.
+- The resolved `AdapterRequest.headers` remains a plain `Record<string,string>` —
+  adapters are unaffected.
+- Regenerates into self-contained `_types.ts` / `_client.ts`; direct consumers get
+  it from `ts-procedures/client`.
+
+**Docs:** add a short auth section (in the generated-client docs /
+`client-and-codegen.md`) presenting function-valued `headers` and `onBeforeRequest`
+as the canonical auth seams, with an explicit "a token in static `headers` goes
+stale — use a function or the hook" warning.
+
+### Alternatives considered
+- *First-class `auth`/`bearer` option wiring the hook internally.* Not chosen this
+  round — function-valued headers is the general-purpose primitive that also covers
+  auth; a dedicated `auth` sugar can layer on later if wanted.
+- *Docs only.* Rejected: the easy-and-wrong static-headers path still compiles.
+
+---
+
+## #5 — Scaffolder file-naming knobs (LOW)
+
+### Problem
+The scaffolder (the AI skill `agent_config/claude-code/skills/ts-procedures/SKILL.md`
+scaffold mode + `templates/*.md`, **not** a CLI) hardcodes `{{Name}}.procedure.ts` —
+PascalCase, one file per procedure — so every scaffold is renamed and folded into a
+per-scope file by hand.
+
+### Decision: `fileNameStyle` + `groupBy` with auto-default
+Add two scaffold-mode args, surfaced in `SKILL.md` and consumed by the templates:
+- `fileNameStyle`: `'PascalCase'` (current) | `'kebab.concern'` (e.g.
+  `get-user.procedure.ts`).
+- `groupBy`: `'flat'` (current, CWD) | `'scope'` (e.g. `<scope>/get-user.procedure.ts`,
+  scope taken from the procedure config).
+
+When **unspecified**, the skill infers the default by inspecting the target
+directory's existing convention (per-scope kebab files vs flat Pascal) — so a
+scaffold matches the consumer's layout with no manual rename pass.
+
+Changes:
+- `SKILL.md` scaffold-mode section: document the two args + the auto-default
+  inference instruction; update the "Files Generated" table to show the computed
+  filename.
+- `templates/*.md`: replace the hardcoded `{{Name}}.<concern>.ts` output with a
+  computed `{{fileName}}` placeholder and an optional `{{scope}}/` directory
+  prefix, plus the placeholder-derivation notes (`{{kebab}}` already exists).
+
+### Alternatives considered
+- *Add knobs, explicit-only (no auto-detect).* Rejected: misses the zero-config
+  match to the repo layout, which is the actual friction.
+- *Defer.* Rejected by scope decision (all three findings actioned this round).
+
+---
+
+## Testing strategy
+- **#1:** unit test `--help`/`-h`/bare → exit 0 + usage contains every flag from the
+  table; `--help` not in did-you-mean candidates; unknown flag still errors.
+- **#2:** unit test `writeDocEnvelope` with (a) a plain envelope, (b) a builder-like
+  object — round-trips to disk and re-loads via `resolveEnvelope --file`.
+- **#3:** spike verification first; then fixture-based tests on the canonical
+  `__fixtures__/users-envelope.json` extended with `$id`'d schemas — assert one
+  `_models.ts` declaration per `$id`, route types reference it, `$id` collision
+  throws, `sharedTypesImport` produces re-exports, and `--no-share-models` restores
+  byte-identical legacy output. Add a no-`$id` regression asserting unchanged output.
+- **#4:** unit test function-valued `headers` (sync + async) resolves per request,
+  merges with per-call, and `onBeforeRequest` still overrides; static-record path
+  unchanged.
+- **#5:** verify by scaffolding under each `fileNameStyle`/`groupBy` combination and
+  the auto-default inference (skill-level / template review).
+
+## Out of scope (follow-up)
+- `ts-channels` codegen shared-types fix (identical to #3).
+- Cross-scaffolder alignment with `ts-channels #9` / `mvc-kit #2` (#5).
+- A first-class `auth`/`bearer` client option (sugar over #4).
+- Kotlin/Swift shared-model emission.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-procedures",
-  "version": "8.3.0",
+  "version": "8.5.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",
@@ -88,7 +88,7 @@
     "trpc"
   ],
   "optionalDependencies": {
-    "ajsc": "^7.2.0",
+    "ajsc": "^7.3.0",
     "astro": "6.x.x || 7.x.x",
     "hono": "^4.7.4"
   },

package/src/client/call.ts

@@ -55,7 +55,7 @@ export async function executeCall<TResponse>(config: ExecuteCallConfig): Promise
   let request = buildAdapterRequest(descriptor, resolvedBasePath)
 
   // 2. Apply request-level options (headers, signal, timeout, meta)
-  const applied = applyRequestOptions(request, defaults, options)
+  const applied = await applyRequestOptions(request, defaults, options)
   request = applied.request
   const signalSources = applied.signalSources
 

package/src/client/index.test.ts

@@ -387,6 +387,104 @@ describe('createClient', () => {
     }
   })
 
+  // ── auth (bearer token sugar) ─────────────────────────────
+
+  it('auth wires Authorization: Bearer <token>, re-evaluated per call', async () => {
+    const capturedHeaders: Record<string, string>[] = []
+    const adapter: ClientAdapter = {
+      request: vi.fn(async (req: AdapterRequest): Promise<AdapterResponse> => {
+        capturedHeaders.push(req.headers ?? {})
+        return { status: 200, headers: {}, body: {} }
+      }),
+      stream: vi.fn(async (): Promise<AdapterStreamResponse> => ({
+        status: 200,
+        headers: new Headers(),
+        body: makeAsyncIterable([]),
+      })),
+    }
+
+    let token = 'tok-1'
+    const client = createClient({
+      adapter,
+      basePath: 'https://api.example.com',
+      auth: () => token,
+      scopes: (instance: ClientInstance) => ({
+        users: {
+          getUser: () => instance.call<unknown>(makeCallDescriptor()),
+        },
+      }),
+    })
+
+    await client.users.getUser()
+    expect(capturedHeaders[0]?.['Authorization']).toBe('Bearer tok-1')
+
+    token = 'tok-2'
+    await client.users.getUser()
+    expect(capturedHeaders[1]?.['Authorization']).toBe('Bearer tok-2')
+  })
+
+  it('auth omits the Authorization header when the token is null', async () => {
+    const capturedHeaders: Record<string, string>[] = []
+    const adapter: ClientAdapter = {
+      request: vi.fn(async (req: AdapterRequest): Promise<AdapterResponse> => {
+        capturedHeaders.push(req.headers ?? {})
+        return { status: 200, headers: {}, body: {} }
+      }),
+      stream: vi.fn(async (): Promise<AdapterStreamResponse> => ({
+        status: 200,
+        headers: new Headers(),
+        body: makeAsyncIterable([]),
+      })),
+    }
+
+    const client = createClient({
+      adapter,
+      basePath: 'https://api.example.com',
+      auth: () => null,
+      scopes: (instance: ClientInstance) => ({
+        users: {
+          getUser: () => instance.call<unknown>(makeCallDescriptor()),
+        },
+      }),
+    })
+
+    await client.users.getUser()
+    expect(capturedHeaders[0]?.['Authorization']).toBeUndefined()
+  })
+
+  it('auth composes with existing defaults.headers (both present)', async () => {
+    const capturedHeaders: Record<string, string>[] = []
+    const adapter: ClientAdapter = {
+      request: vi.fn(async (req: AdapterRequest): Promise<AdapterResponse> => {
+        capturedHeaders.push(req.headers ?? {})
+        return { status: 200, headers: {}, body: {} }
+      }),
+      stream: vi.fn(async (): Promise<AdapterStreamResponse> => ({
+        status: 200,
+        headers: new Headers(),
+        body: makeAsyncIterable([]),
+      })),
+    }
+
+    const client = createClient({
+      adapter,
+      basePath: 'https://api.example.com',
+      defaults: { headers: { 'x-client': 'web' } },
+      auth: async () => 'tok-async',
+      scopes: (instance: ClientInstance) => ({
+        users: {
+          getUser: () => instance.call<unknown>(makeCallDescriptor()),
+        },
+      }),
+    })
+
+    await client.users.getUser()
+    expect(capturedHeaders[0]).toMatchObject({
+      'x-client': 'web',
+      Authorization: 'Bearer tok-async',
+    })
+  })
+
   it('ClientInstance exposes defaults', () => {
     const adapter = makeAdapter()
     const defaults = { timeout: 5000, headers: { 'x-client': 'test' } }

package/src/client/index.ts

@@ -6,6 +6,8 @@ import type {
   CallDescriptor,
   StreamDescriptor,
   ProcedureCallOptions,
+  ProcedureCallDefaults,
+  ClientHeadersInit,
   TypedStream,
   Result,
   ResultNoTyped,
@@ -13,6 +15,24 @@ import type {
 
 // ── createClient ──────────────────────────────────────────
 
+/**
+ * Folds `config.auth` into the resolved default headers as a single async
+ * function-valued `ClientHeadersInit`. Resolves the user's existing default
+ * headers (record OR function) to a record first, then appends
+ * `Authorization: Bearer <token>` when `auth()` yields a non-null token.
+ * Re-evaluated per request, so a rotating token never goes stale.
+ */
+function composeAuthHeaders(
+  base: ClientHeadersInit | undefined,
+  auth: NonNullable<CreateClientConfig<unknown>['auth']>,
+): ClientHeadersInit {
+  return async () => {
+    const resolvedBase = base == null ? {} : typeof base === 'function' ? await base() : base
+    const token = await auth()
+    return token ? { ...resolvedBase, Authorization: `Bearer ${token}` } : resolvedBase
+  }
+}
+
 /**
  * Creates a typed client from a config object.
  *
@@ -31,11 +51,21 @@ export function createClient<TScopes>(config: CreateClientConfig<TScopes>): TSco
     adapter,
     basePath,
     hooks: globalHooks = {},
-    defaults: globalDefaults = {},
+    defaults: configDefaults = {},
     errorRegistry,
+    auth,
     scopes,
   } = config
 
+  // `auth` is sugar over a function-valued `defaults.headers`: fold it into the
+  // resolved default headers as an async function so it shares the single
+  // per-request header-resolution path (no new resolution branch). The user's
+  // existing `defaults.headers` (record or function) is resolved first, then the
+  // bearer token is appended — a null/undefined token omits the header.
+  const globalDefaults: ProcedureCallDefaults = auth
+    ? { ...configDefaults, headers: composeAuthHeaders(configDefaults.headers, auth) }
+    : configDefaults
+
   const instance: ClientInstance = {
     basePath,
     adapter,
@@ -171,6 +201,7 @@ export type {
   ClientInstance,
   ProcedureCallDefaults,
   ProcedureCallOptions,
+  ClientHeadersInit,
   CreateClientConfig,
   RequestMeta,
   ErrorRegistry,

package/src/client/resolve-options.test.ts

@@ -9,6 +9,13 @@ import {
 } from './resolve-options.js'
 import type { AdapterRequest, ProcedureCallDefaults, ProcedureCallOptions } from './types.js'
 
+// Minimal valid AdapterRequest (headers undefined) shared across describe blocks.
+const baseRequest: AdapterRequest = {
+  url: 'https://api.example.com/foo',
+  method: 'POST',
+  body: { hello: 'world' },
+}
+
 // ── resolveBasePath ───────────────────────────────────────
 
 describe('resolveBasePath', () => {
@@ -38,24 +45,70 @@ describe('resolveBasePath', () => {
 // ── resolveHeaders ────────────────────────────────────────
 
 describe('resolveHeaders', () => {
-  it('returns undefined when neither side sets headers', () => {
-    expect(resolveHeaders(undefined, undefined)).toBeUndefined()
+  it('returns undefined when neither side sets headers', async () => {
+    expect(await resolveHeaders(undefined, undefined)).toBeUndefined()
   })
 
-  it('returns default headers when only defaults set', () => {
-    expect(resolveHeaders({ headers: { 'x-a': '1' } }, undefined)).toEqual({ 'x-a': '1' })
+  it('returns default headers when only defaults set', async () => {
+    expect(await resolveHeaders({ headers: { 'x-a': '1' } }, undefined)).toEqual({ 'x-a': '1' })
   })
 
-  it('per-call keys override default keys', () => {
+  it('per-call keys override default keys', async () => {
     const defaults: ProcedureCallDefaults = { headers: { 'x-a': 'default', 'x-b': 'keep' } }
     const options: ProcedureCallOptions = { headers: { 'x-a': 'override' } }
-    expect(resolveHeaders(defaults, options)).toEqual({
+    expect(await resolveHeaders(defaults, options)).toEqual({
       'x-a': 'override',
       'x-b': 'keep',
     })
   })
 })
 
+// ── resolveHeaders (function-valued) ──────────────────────
+
+describe('function-valued headers', () => {
+  it('resolves a sync function-valued default header', async () => {
+    const { request } = await applyRequestOptions(
+      baseRequest,
+      { headers: () => ({ Authorization: 'Bearer t1' }) },
+      undefined,
+    )
+    expect(request.headers).toMatchObject({ Authorization: 'Bearer t1' })
+  })
+
+  it('resolves an async function-valued header', async () => {
+    const { request } = await applyRequestOptions(
+      baseRequest,
+      { headers: async () => ({ Authorization: 'Bearer async' }) },
+      undefined,
+    )
+    expect(request.headers).toMatchObject({ Authorization: 'Bearer async' })
+  })
+
+  it('per-call headers win over default headers (both functions)', async () => {
+    const { request } = await applyRequestOptions(
+      baseRequest,
+      { headers: () => ({ Authorization: 'Bearer default', 'x-a': '1' }) },
+      { headers: () => ({ Authorization: 'Bearer call' }) },
+    )
+    expect(request.headers).toMatchObject({ Authorization: 'Bearer call', 'x-a': '1' })
+  })
+
+  it('static record path still works', async () => {
+    const { request } = await applyRequestOptions(baseRequest, { headers: { 'x-s': 'v' } }, undefined)
+    expect(request.headers).toMatchObject({ 'x-s': 'v' })
+  })
+
+  it('re-evaluates the function on each call (no staleness)', async () => {
+    let token = 't1'
+    const headers = () => ({ Authorization: `Bearer ${token}` })
+    const first = await applyRequestOptions(baseRequest, { headers }, undefined)
+    expect(first.request.headers).toMatchObject({ Authorization: 'Bearer t1' })
+    token = 't2'
+    const second = await applyRequestOptions(baseRequest, { headers }, undefined)
+    expect(second.request.headers).toMatchObject({ Authorization: 'Bearer t2' })
+  })
+})
+
 // ── resolveMeta ───────────────────────────────────────────
 
 describe('resolveMeta', () => {
@@ -202,21 +255,15 @@ describe('resolveSignalSources', () => {
 // ── applyRequestOptions ───────────────────────────────────
 
 // Helper so existing tests can destructure .request without boilerplate
-const apply = (
+const apply = async (
   req: AdapterRequest,
   d: ProcedureCallDefaults | undefined,
   o: ProcedureCallOptions | undefined,
-) => applyRequestOptions(req, d, o).request
+) => (await applyRequestOptions(req, d, o)).request
 
 describe('applyRequestOptions', () => {
-  const baseRequest: AdapterRequest = {
-    url: 'https://api.example.com/foo',
-    method: 'POST',
-    body: { hello: 'world' },
-  }
-
-  it('returns the request unchanged when nothing is provided', () => {
-    const result = apply(baseRequest, undefined, undefined)
+  it('returns the request unchanged when nothing is provided', async () => {
+    const result = await apply(baseRequest, undefined, undefined)
     expect(result.url).toBe(baseRequest.url)
     expect(result.body).toEqual({ hello: 'world' })
     expect(result.headers).toBeUndefined()
@@ -224,12 +271,12 @@ describe('applyRequestOptions', () => {
     expect(result.meta).toBeUndefined()
   })
 
-  it('merges default + per-call headers, preserving route-declared headers', () => {
+  it('merges default + per-call headers, preserving route-declared headers', async () => {
     const reqWithHeaders: AdapterRequest = {
       ...baseRequest,
       headers: { 'content-type': 'application/json', 'x-route': 'declared' },
     }
-    const result = apply(
+    const result = await apply(
       reqWithHeaders,
       { headers: { 'x-default': 'd', 'x-route': 'from-default' } },
       { headers: { 'x-call': 'c', 'x-route': 'from-call' } },
@@ -243,23 +290,23 @@ describe('applyRequestOptions', () => {
     })
   })
 
-  it('attaches meta to the request when provided', () => {
-    const result = apply(baseRequest, undefined, {
+  it('attaches meta to the request when provided', async () => {
+    const result = await apply(baseRequest, undefined, {
       meta: { traceId: 'abc' } as never,
     })
     expect(result.meta).toEqual({ traceId: 'abc' })
   })
 
-  it('passes per-call signal through', () => {
+  it('passes per-call signal through', async () => {
     const controller = new AbortController()
-    const result = apply(baseRequest, undefined, { signal: controller.signal })
+    const result = await apply(baseRequest, undefined, { signal: controller.signal })
     expect(result.signal).toBe(controller.signal)
   })
 
-  it('attaches a signal when per-call timeout is set', () => {
+  it('attaches a signal when per-call timeout is set', async () => {
     const spy = vi.spyOn(AbortSignal, 'timeout')
     try {
-      const result = apply(baseRequest, undefined, { timeout: 100 })
+      const result = await apply(baseRequest, undefined, { timeout: 100 })
       expect(spy).toHaveBeenCalledWith(100)
       expect(result.signal).toBeDefined()
       expect(result.signal?.aborted).toBe(false)
@@ -268,9 +315,9 @@ describe('applyRequestOptions', () => {
     }
   })
 
-  it('exposes signalSources alongside the request', () => {
+  it('exposes signalSources alongside the request', async () => {
     const ctrl = new AbortController()
-    const { request, signalSources } = applyRequestOptions(baseRequest, undefined, {
+    const { request, signalSources } = await applyRequestOptions(baseRequest, undefined, {
       signal: ctrl.signal,
       timeout: 500,
     })