ts-procedures 6.2.0 → 7.0.0-beta.0

package/src/client/resolve-options.ts

@@ -17,6 +17,48 @@ export function resolveBasePath(
   return options?.basePath ?? defaults?.basePath ?? fallback
 }
 
+/**
+ * Resolves signal sources individually so callers can distinguish which
+ * underlying signal fired (e.g. timeout vs user abort in the error classifier).
+ *
+ * - `userSignal`: the per-call signal (if any); separate from the default signal
+ * - `timeoutSignal`: created via `AbortSignal.timeout(timeoutMs)` when timeout > 0
+ * - `timeoutMs`: the resolved timeout value (may be 0 if per-call explicitly disables)
+ * - `combined`: `AbortSignal.any([...])` of all active signals, or undefined if none
+ *
+ * Per-call `timeout: 0` disables an inherited default timeout (same as `resolveSignal`).
+ * Both `defaults.signal` and `options.signal` are included in `combined` when present.
+ */
+export interface SignalSources {
+  combined?: AbortSignal
+  timeoutSignal?: AbortSignal
+  /** The per-call signal, if provided. Separate from the default signal. */
+  userSignal?: AbortSignal
+  timeoutMs?: number
+}
+
+export function resolveSignalSources(
+  defaults: ProcedureCallDefaults | undefined,
+  options: ProcedureCallOptions | undefined,
+): SignalSources {
+  const userSignal = options?.signal
+  // Use explicit undefined check so timeout: 0 overrides defaults (not just nullish)
+  const timeoutMs = options?.timeout !== undefined ? options.timeout : defaults?.timeout
+  const timeoutSignal =
+    timeoutMs != null && timeoutMs > 0 ? AbortSignal.timeout(timeoutMs) : undefined
+
+  const signals: AbortSignal[] = []
+  if (defaults?.signal) signals.push(defaults.signal)
+  if (userSignal) signals.push(userSignal)
+  if (timeoutSignal) signals.push(timeoutSignal)
+
+  let combined: AbortSignal | undefined
+  if (signals.length === 1) combined = signals[0]
+  else if (signals.length > 1) combined = AbortSignal.any(signals)
+
+  return { combined, timeoutSignal, userSignal, timeoutMs }
+}
+
 /**
  * Resolves the effective AbortSignal by combining (via `AbortSignal.any`):
  *   - default signal (if any)
@@ -25,24 +67,15 @@ export function resolveBasePath(
  *
  * Returns undefined when none apply. Per-call `timeout: 0` disables an
  * inherited default timeout.
+ *
+ * @deprecated Prefer `resolveSignalSources` when you need access to individual
+ * signal references (e.g. for abort-cause classification).
  */
 export function resolveSignal(
   defaults: ProcedureCallDefaults | undefined,
   options: ProcedureCallOptions | undefined,
 ): AbortSignal | undefined {
-  const signals: AbortSignal[] = []
-
-  if (defaults?.signal) signals.push(defaults.signal)
-  if (options?.signal) signals.push(options.signal)
-
-  const timeout = options?.timeout ?? defaults?.timeout
-  if (timeout != null && timeout > 0) {
-    signals.push(AbortSignal.timeout(timeout))
-  }
-
-  if (signals.length === 0) return undefined
-  if (signals.length === 1) return signals[0]
-  return AbortSignal.any(signals)
+  return resolveSignalSources(defaults, options).combined
 }
 
 /**
@@ -84,6 +117,11 @@ export function resolveMeta(
   return { ...defaultMeta, ...callMeta } as RequestMeta
 }
 
+export interface ApplyRequestOptionsResult {
+  request: AdapterRequest
+  signalSources: SignalSources
+}
+
 /**
  * Applies resolved default + per-call options to an AdapterRequest.
  *
@@ -94,13 +132,17 @@ export function resolveMeta(
  * API routes) are preserved; resolved headers merge underneath them so the
  * route-declared headers win, matching the adapter.config → defaults → call
  * → route-declared → hooks precedence chain documented in the types.
+ *
+ * Returns both the merged request and the raw `signalSources` so callers (e.g.
+ * the error classifier in Task 6) can distinguish timeout from user abort without
+ * losing provenance after `AbortSignal.any` collapses the originals.
  */
 export function applyRequestOptions(
   request: AdapterRequest,
   defaults: ProcedureCallDefaults | undefined,
   options: ProcedureCallOptions | undefined,
-): AdapterRequest {
-  const signal = resolveSignal(defaults, options)
+): ApplyRequestOptionsResult {
+  const signalSources = resolveSignalSources(defaults, options)
   const resolvedHeaders = resolveHeaders(defaults, options)
   const meta = resolveMeta(defaults, options)
 
@@ -109,5 +151,8 @@ export function applyRequestOptions(
       ? { ...resolvedHeaders, ...request.headers }
       : undefined
 
-  return { ...request, headers, signal, meta }
+  return {
+    request: { ...request, headers, signal: signalSources.combined, meta },
+    signalSources,
+  }
 }

package/src/client/result-type.test-d.ts

@@ -0,0 +1,51 @@
+import { describe, it, expectTypeOf } from 'vitest'
+import type {
+  Result,
+  ResultNoTyped,
+  ClientErrorMap,
+} from './types.js'
+import type {
+  ClientHttpError,
+  ClientNetworkError,
+  ClientTimeoutError,
+  ClientAbortError,
+  ClientParseError,
+  ClientPathParamError,
+} from './errors.js'
+
+describe('Result type', () => {
+  it('includes ok=true with value', () => {
+    type R = Result<number, Error>
+    type Ok = Extract<R, { ok: true }>
+    expectTypeOf<Ok['value']>().toEqualTypeOf<number>()
+  })
+
+  it('includes typed kind with ETyped error', () => {
+    class MyTyped extends Error {}
+    type R = Result<number, MyTyped>
+    type Typed = Extract<R, { kind: 'typed' }>
+    expectTypeOf<Typed['error']>().toEqualTypeOf<MyTyped>()
+  })
+
+  it('includes every default framework kind', () => {
+    type R = Result<number, Error>
+    expectTypeOf<Extract<R, { kind: 'http' }>['error']>().toEqualTypeOf<ClientHttpError>()
+    expectTypeOf<Extract<R, { kind: 'network' }>['error']>().toEqualTypeOf<ClientNetworkError>()
+    expectTypeOf<Extract<R, { kind: 'timeout' }>['error']>().toEqualTypeOf<ClientTimeoutError>()
+    expectTypeOf<Extract<R, { kind: 'aborted' }>['error']>().toEqualTypeOf<ClientAbortError>()
+    expectTypeOf<Extract<R, { kind: 'parse' }>['error']>().toEqualTypeOf<ClientParseError>()
+    expectTypeOf<Extract<R, { kind: 'usage' }>['error']>().toEqualTypeOf<ClientPathParamError>()
+    expectTypeOf<Extract<R, { kind: 'unknown' }>['error']>().toEqualTypeOf<unknown>()
+  })
+})
+
+describe('ResultNoTyped', () => {
+  it('omits the typed arm', () => {
+    type R = ResultNoTyped<number>
+    type Typed = Extract<R, { kind: 'typed' }>
+    expectTypeOf<Typed>().toEqualTypeOf<never>()
+  })
+})
+
+// Suppress unused-var warnings on imports we use only for types
+void (null as unknown as ClientErrorMap)

package/src/client/safe-call.test.ts

@@ -0,0 +1,157 @@
+import { describe, it, expect, vi } from 'vitest'
+import { executeSafeCall } from './call.js'
+import {
+  ClientHttpError,
+  ClientNetworkError,
+  ClientTimeoutError,
+  ClientAbortError,
+  ClientPathParamError,
+} from './errors.js'
+import type { ClientAdapter, CallDescriptor } from './types.js'
+
+const baseDescriptor: CallDescriptor = {
+  name: 'GetUser', scope: 'users', path: '/users/:id', method: 'GET',
+  kind: 'rpc', params: { id: '42' },
+}
+
+const ok = (body: unknown): ClientAdapter => ({
+  request: vi.fn(async () => ({ status: 200, headers: {}, body })),
+  stream: vi.fn(async () => { throw new Error('n/a') }),
+})
+
+const failWith = (err: unknown): ClientAdapter => ({
+  request: vi.fn(async () => { throw err }),
+  stream: vi.fn(async () => { throw new Error('n/a') }),
+})
+
+describe('executeSafeCall', () => {
+  it('returns ok=true with value on success', async () => {
+    const r = await executeSafeCall({
+      descriptor: baseDescriptor,
+      basePath: 'https://api.x',
+      adapter: ok({ id: '42' }),
+      hooks: {},
+    })
+    expect(r.ok).toBe(true)
+    if (r.ok) expect(r.value).toEqual({ id: '42' })
+  })
+
+  it("returns kind='http' on non-2xx without registry match", async () => {
+    const r = await executeSafeCall({
+      descriptor: baseDescriptor,
+      basePath: 'https://api.x',
+      adapter: {
+        request: vi.fn(async () => ({ status: 500, headers: {}, body: { msg: 'oops' } })),
+        stream: vi.fn(async () => { throw new Error('n/a') }),
+      },
+      hooks: {},
+    })
+    expect(r.ok).toBe(false)
+    if (!r.ok) {
+      expect(r.kind).toBe('http')
+      expect(r.error).toBeInstanceOf(ClientHttpError)
+    }
+  })
+
+  it("returns kind='network' on TypeError", async () => {
+    const r = await executeSafeCall({
+      descriptor: baseDescriptor,
+      basePath: 'https://api.x',
+      adapter: failWith(new TypeError('Failed to fetch')),
+      hooks: {},
+    })
+    expect(r.ok).toBe(false)
+    if (!r.ok) {
+      expect(r.kind).toBe('network')
+      expect(r.error).toBeInstanceOf(ClientNetworkError)
+    }
+  })
+
+  it("returns kind='timeout' when timeout fires", async () => {
+    // Simulate fetch-style abort wait, mirroring Task 6's fix
+    const r = await executeSafeCall({
+      descriptor: baseDescriptor,
+      basePath: 'https://api.x',
+      adapter: {
+        request: vi.fn(async (req) => {
+          await new Promise<void>((_resolve, reject) => {
+            req.signal?.addEventListener(
+              'abort',
+              () => reject(new DOMException('aborted', 'AbortError')),
+              { once: true },
+            )
+          })
+          throw new Error('unreachable')
+        }),
+        stream: vi.fn(async () => { throw new Error('n/a') }),
+      },
+      hooks: {},
+      options: { timeout: 1 },
+    })
+    expect(r.ok).toBe(false)
+    if (!r.ok) {
+      expect(r.kind).toBe('timeout')
+      expect(r.error).toBeInstanceOf(ClientTimeoutError)
+    }
+  })
+
+  it("returns kind='aborted' when user signal fires", async () => {
+    const ctrl = new AbortController()
+    ctrl.abort('user')
+    const r = await executeSafeCall({
+      descriptor: baseDescriptor,
+      basePath: 'https://api.x',
+      adapter: failWith(new DOMException('aborted', 'AbortError')),
+      hooks: {},
+      options: { signal: ctrl.signal },
+    })
+    if (!r.ok) {
+      expect(r.kind).toBe('aborted')
+      expect(r.error).toBeInstanceOf(ClientAbortError)
+    }
+  })
+
+  it("returns kind='usage' on pre-adapter ClientPathParamError, does NOT invoke onError", async () => {
+    // Spec contract: pre-adapter usage errors bypass the classifier AND the
+    // onError hook entirely. Path 1 of the three failure-source paths.
+    const seen: unknown[] = []
+    const r = await executeSafeCall({
+      // path requires :id but params don't supply it
+      descriptor: { ...baseDescriptor, params: {} },
+      basePath: 'https://api.x',
+      adapter: ok({}),
+      hooks: { onError: ({ error }) => { seen.push(error) } },
+    })
+    if (!r.ok) {
+      expect(r.kind).toBe('usage')
+      expect(r.error).toBeInstanceOf(ClientPathParamError)
+    }
+    // onError must NOT fire — by design (per spec architectural decision #1).
+    expect(seen).toEqual([])
+  })
+
+  it("returns kind='unknown' for unrecognized throws", async () => {
+    const r = await executeSafeCall({
+      descriptor: baseDescriptor,
+      basePath: 'https://api.x',
+      adapter: failWith('weird-string-throw'),
+      hooks: {},
+    })
+    if (!r.ok) {
+      expect(r.kind).toBe('unknown')
+      expect(r.error).toBe('weird-string-throw')
+    }
+  })
+
+  it('invokes onError hook on failure (cross-cutting telemetry)', async () => {
+    const seen: unknown[] = []
+    const r = await executeSafeCall({
+      descriptor: baseDescriptor,
+      basePath: 'https://api.x',
+      adapter: failWith(new TypeError('x')),
+      hooks: { onError: ({ error }) => { seen.push(error) } },
+    })
+    expect(r.ok).toBe(false)
+    expect(seen[0]).toBeInstanceOf(ClientNetworkError)
+  })
+})

package/src/client/stream.test.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect, vi } from 'vitest'
 import { createTypedStream, executeStream } from './stream.js'
-import { ClientRequestError } from './errors.js'
+import { ClientRequestError, ClientNetworkError } from './errors.js'
 import type {
   ClientAdapter,
   AdapterRequest,
@@ -354,3 +354,15 @@ describe('executeStream', () => {
     expect(observedMeta).toEqual({ traceId: 'stream-trace' })
   })
 })
+
+// ── executeStream classifier integration ──────────────────
+
+describe('executeStream classifier integration', () => {
+  it('classifies pre-stream TypeError as ClientNetworkError', async () => {
+    const adapter: ClientAdapter = {
+      request: vi.fn(async () => { throw new Error('n/a') }),
+      stream: vi.fn(async () => { throw new TypeError('Failed to fetch') }),
+    }
+    await expect(run({ adapter })).rejects.toBeInstanceOf(ClientNetworkError)
+  })
+})

package/src/client/stream.ts

@@ -1,11 +1,13 @@
 import { buildAdapterRequest } from './request-builder.js'
 import { runBeforeRequest, runAfterResponse, runOnError } from './hooks.js'
 import { applyRequestOptions, resolveBasePath } from './resolve-options.js'
-import { ClientRequestError } from './errors.js'
+import { ClientHttpError } from './errors.js'
 import { dispatchTypedError } from './error-dispatch.js'
+import { defaultClassifyError } from './classify-error.js'
 import type {
   ClientAdapter,
   ClientHooks,
+  ClassifyErrorContext,
   ErrorRegistry,
   StreamDescriptor,
   TypedStream,
@@ -115,7 +117,7 @@ export interface ExecuteStreamConfig {
  * 4. Call adapter.stream()
  * 5. On adapter error: run onError hooks, re-throw
  * 6. Run onAfterResponse immediately (before iteration), body is null
- * 7. If non-2xx: throw ClientRequestError
+ * 7. If non-2xx: throw ClientHttpError
  * 8. Return createTypedStream(streamResponse.body, descriptor.streamMode)
  */
 export async function executeStream<TYield, TReturn = void>(
@@ -128,7 +130,9 @@ export async function executeStream<TYield, TReturn = void>(
   let request = buildAdapterRequest(descriptor, resolvedBasePath)
 
   // 2. Apply request-level options (headers, signal, timeout, meta)
-  request = applyRequestOptions(request, defaults, options)
+  const applied = applyRequestOptions(request, defaults, options)
+  request = applied.request
+  const signalSources = applied.signalSources
 
   // 3. Run before-request hooks
   const beforeCtx = await runBeforeRequest(
@@ -142,14 +146,27 @@ export async function executeStream<TYield, TReturn = void>(
   let streamResponse
   try {
     streamResponse = await adapter.stream(request)
-  } catch (err) {
-    // 5. On adapter error: run error hooks, re-throw
+  } catch (rawErr) {
+    // 5. On adapter error: classify (adapter > default > fallthrough), then run
+    //    onError hooks with the normalized error, then throw.
+    const classifyCtx: ClassifyErrorContext = {
+      procedureName: descriptor.name,
+      scope: descriptor.scope,
+      timeoutSignal: signalSources.timeoutSignal,
+      userSignal: signalSources.userSignal,
+      timeoutMs: signalSources.timeoutMs,
+    }
+    const classified =
+      adapter.classifyError?.(rawErr, classifyCtx) ??
+      defaultClassifyError(rawErr, classifyCtx)
+    const finalError = classified?.error ?? rawErr
+
     await runOnError(
-      { procedureName: descriptor.name, scope: descriptor.scope, request, error: err },
+      { procedureName: descriptor.name, scope: descriptor.scope, request, error: finalError },
       hooks,
       options,
     )
-    throw err
+    throw finalError
   }
 
   // Build an AdapterResponse shape for the hooks. For success the body is null
@@ -176,7 +193,7 @@ export async function executeStream<TYield, TReturn = void>(
       scope: descriptor.scope,
     })
     if (typed) throw typed
-    throw new ClientRequestError({
+    throw new ClientHttpError({
       status: responseForHooks.status,
       headers: responseForHooks.headers,
       body: responseForHooks.body,

package/src/client/types.ts

@@ -30,11 +30,52 @@
 // eslint-disable-next-line @typescript-eslint/no-empty-object-type
 export interface RequestMeta {}
 
+// ── Error Classifier ─────────────────────────────────────
+
+/**
+ * Classification context — supplies provenance the classifier needs that's
+ * not derivable from the raw error itself.
+ *
+ * `timeoutSignal` and `userSignal` let the classifier distinguish a timeout
+ * abort from a user-initiated abort when an `AbortError` lands.
+ */
+export interface ClassifyErrorContext {
+  procedureName: string
+  scope: string
+  timeoutSignal?: AbortSignal
+  userSignal?: AbortSignal
+  timeoutMs?: number
+}
+
+/**
+ * The output shape of a successful classification. Contract: `error` is
+ * always an `Error` subclass (the framework class). Non-`Error` values fall
+ * through to `null` (handled by `executeCall` as `kind: 'unknown'`).
+ */
+export interface ClassifiedError {
+  kind: string
+  error: Error
+}
+
+/**
+ * Adapter-provided classifier — runs before `defaultClassifyError`. Return
+ * `null` to fall through to the default. Adapter authors should compose with
+ * the default explicitly:
+ *
+ *     classifyError: (e, ctx) => myClassify(e, ctx) ?? defaultClassifyError(e, ctx)
+ */
+export type ErrorClassifier = (
+  raw: unknown,
+  ctx: ClassifyErrorContext,
+) => ClassifiedError | null
+
 // ── Adapter ──────────────────────────────────────────────
 
 export interface ClientAdapter {
   request(config: AdapterRequest): Promise<AdapterResponse>
   stream(config: AdapterRequest): Promise<AdapterStreamResponse>
+  /** Optional adapter-level error classifier — composes with `defaultClassifyError`. */
+  classifyError?: ErrorClassifier
 }
 
 export interface AdapterRequest {
@@ -63,7 +104,7 @@ export interface AdapterStreamResponse {
   /**
    * Populated when `status` is non-2xx — the parsed response body. Surfaced so
    * `executeStream` can dispatch typed errors via the error registry instead
-   * of always falling back to `ClientRequestError` with `body: null`.
+   * of always falling back to `ClientHttpError` with `body: null`.
    */
   errorBody?: unknown
 }
@@ -177,7 +218,7 @@ export interface ErrorFactory {
 /**
  * Maps `body.name` values (taxonomy keys) to error class factories. When the
  * client sees a non-2xx response whose body has a `name` matching a registry
- * entry, it throws the typed error instead of a generic `ClientRequestError`.
+ * entry, it throws the typed error instead of a generic `ClientHttpError`.
  */
 export type ErrorRegistry = Record<string, ErrorFactory>
 
@@ -191,6 +232,10 @@ export interface ClientInstance {
   /** Optional registry for runtime dispatch of typed errors by `body.name`. */
   errorRegistry?: ErrorRegistry
   call<TResponse>(descriptor: CallDescriptor, options?: ProcedureCallOptions): Promise<TResponse>
+  safeCall<TResponse, ETyped = never>(
+    descriptor: CallDescriptor,
+    options?: ProcedureCallOptions,
+  ): Promise<Result<TResponse, ETyped>>
   stream<TYield, TReturn>(descriptor: StreamDescriptor, options?: ProcedureCallOptions): TypedStream<TYield, TReturn>
 }
 
@@ -211,7 +256,71 @@ export interface CreateClientConfig<TScopes> {
    * Optional error-dispatch registry. When a non-2xx response body has a
    * `name` field matching a registry key, the client throws the typed error
    * constructed via that entry's `fromResponse`. When absent or when no key
-   * matches, falls back to `ClientRequestError` (transport error shape).
+   * matches, falls back to `ClientHttpError` (transport error shape).
    */
   errorRegistry?: ErrorRegistry
 }
+
+// ── Result Types ─────────────────────────────────────────
+
+import type {
+  ClientHttpError,
+  ClientNetworkError,
+  ClientTimeoutError,
+  ClientAbortError,
+  ClientParseError,
+  ClientPathParamError,
+} from './errors.js'
+
+/**
+ * Augmentable map of `kind` discriminant → error class for the framework's
+ * non-typed failure categories. Mirrors the `RequestMeta` augmentation
+ * pattern: extend via TypeScript declaration merging.
+ *
+ * @example
+ * ```ts
+ * declare module 'ts-procedures/client' {
+ *   interface ClientErrorMap {
+ *     rateLimited: MyRateLimitError
+ *     paymentRequired: MyPaymentError
+ *   }
+ * }
+ * ```
+ *
+ * **`'typed'` is reserved** — it's the discriminant used by `Result` for
+ * route-declared errors and is not part of `ClientErrorMap`. Attempting to
+ * register it produces a TS error about overlapping discriminants.
+ */
+export interface ClientErrorMap {
+  http: ClientHttpError
+  network: ClientNetworkError
+  timeout: ClientTimeoutError
+  aborted: ClientAbortError
+  parse: ClientParseError
+  usage: ClientPathParamError
+  unknown: unknown
+}
+
+/** Distributed union of every framework failure kind. */
+export type FrameworkFailure = {
+  [K in keyof ClientErrorMap]: { ok: false; kind: K; error: ClientErrorMap[K] }
+}[keyof ClientErrorMap]
+
+/**
+ * Discriminated result type for the `.safe()` form. `kind: 'typed'` carries
+ * route-declared errors (registry-dispatched); other kinds carry framework
+ * failures. Use `ResultNoTyped<T>` for routes without declared errors.
+ */
+export type Result<T, ETyped> =
+  | { ok: true; value: T }
+  | { ok: false; kind: 'typed'; error: ETyped }
+  | FrameworkFailure
+
+/**
+ * `Result` for routes that don't declare typed errors. Omits the `'typed'`
+ * arm entirely so IDE hovers stay clean (TS doesn't collapse `never`-payload
+ * arms in tooltip output).
+ */
+export type ResultNoTyped<T> =
+  | { ok: true; value: T }
+  | FrameworkFailure

package/src/codegen/bundle-size.test.ts

@@ -0,0 +1,74 @@
+import { describe, it, expect, beforeAll } from 'vitest'
+import { generateClient } from './index.js'
+import * as path from 'node:path'
+import * as os from 'node:os'
+import * as fs from 'node:fs/promises'
+import type { DocEnvelope } from '../implementations/types.js'
+
+function makeEnvelope(routeCount: number): DocEnvelope {
+  const routes = Array.from({ length: routeCount }, (_, i) => ({
+    kind: 'rpc' as const,
+    name: `Op${i}`,
+    scope: 'ops',
+    method: 'post' as const,
+    path: `/ops/op${i}`,
+    version: 1,
+    jsonSchema: {
+      body: { type: 'object' as const, properties: { x: { type: 'string' as const } } },
+      response: { type: 'object' as const, properties: { y: { type: 'string' as const } } },
+    },
+    errors: [] as string[],
+  }))
+  return { basePath: '/api', headers: [], errors: [], routes }
+}
+
+describe('bundle size budget', () => {
+  let perRouteDelta: number
+  let totalChars: number
+
+  beforeAll(async () => {
+    const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'tsproc-bundle-'))
+    await generateClient({
+      envelope: makeEnvelope(100),
+      outDir: tmp,
+      selfContained: false,
+    })
+    const scopeFile = await fs.readFile(path.join(tmp, 'ops.ts'), 'utf-8')
+
+    // Strip whitespace, line comments, block comments. This is a stable proxy
+    // for minification — actual minified bytes will be lower, but the *delta*
+    // between commits is what this test guards against.
+    const stripped = scopeFile
+      .replace(/\/\*[\s\S]*?\*\//g, '')   // block comments
+      .replace(/\/\/.*$/gm, '')           // line comments
+      .replace(/\s+/g, ' ')               // collapse whitespace
+    totalChars = stripped.length
+    perRouteDelta = totalChars / 100
+  })
+
+  it('stays within 1500 chars per route post-strip', () => {
+    // Initial budget — refine after first measurement. The .safe sibling adds
+    // roughly 400 chars of unminified emission per route (Object.assign wrapper
+    // + duplicated descriptor literal). Post-strip should land well under 1500.
+    //
+    // RELATIONSHIP TO SPEC TARGET: The spec sets a "200 bytes per route
+    // post-minify" goal. This whitespace-strip proxy is a coarse stand-in
+    // chosen to avoid an esbuild dep — actual minified bytes will be lower
+    // than `perRouteDelta` here. If a future task swaps in real esbuild
+    // minification, tighten the budget to ~250 bytes (200 + 25% headroom)
+    // and link back to spec section "Tests / item 10". For now this guard
+    // catches catastrophic regressions only, not subtle bloat.
+    //
+    // PERROUTEDELTA_BASELINE: 613.2
+    expect(perRouteDelta).toBeLessThan(1500)
+  })
+
+  it('logs the baseline measurement for review', () => {
+    // This isn't a strict assertion — it surfaces the actual numbers to the
+    // test output so reviewers can update PERROUTEDELTA_BASELINE in the
+    // comment above without having to re-run locally.
+    // eslint-disable-next-line no-console
+    console.log(`[bundle-size] 100 routes, scope file = ${totalChars} chars stripped, per-route = ${perRouteDelta.toFixed(1)}`)
+    expect(totalChars).toBeGreaterThan(0)
+  })
+})