@camstack/server 1.0.0 → 1.0.1

package/src/api/trpc/__tests__/scope-access.spec.ts

@@ -1,102 +0,0 @@
-/**
- * Matrix tests for `checkScopeAccess`. Drives the scope-gate in
- * `protectedProcedure`.
- *
- * The map (`METHOD_ACCESS_MAP`) is codegen-emitted; the test imports
- * it indirectly via the helper so any drift between cap definitions
- * and runtime would surface here as a test failure (e.g. a renamed
- * method would no longer resolve to a known entry).
- */
-import { describe, it, expect } from 'vitest'
-import { checkScopeAccess } from '../scope-access.js'
-import type { TokenScope } from '@camstack/types'
-
-function scope(
-  type: 'addon' | 'capability',
-  target: string,
-  access: TokenScope['access'],
-): TokenScope {
-  return { type, target, access }
-}
-
-describe('checkScopeAccess', () => {
-  // ── Sanity: known paths resolve, unknown paths fail closed ──────
-
-  it('returns FORBIDDEN with codegen-drift reason for unknown paths', () => {
-    const result = checkScopeAccess([scope('capability', 'backup', ['view'])], 'no-such.method')
-    expect(result.ok).toBe(false)
-    if (!result.ok) {
-      expect(result.reason).toContain('codegen drift')
-    }
-  })
-
-  // ── Capability-typed scopes ─────────────────────────────────────
-
-  it('accepts when capability scope matches target + access', () => {
-    const result = checkScopeAccess([scope('capability', 'backup', ['view'])], 'backup.list')
-    expect(result.ok).toBe(true)
-    if (result.ok) expect(result.access).toBe('view')
-  })
-
-  it('rejects when capability scope matches target but lacks the required access', () => {
-    // backup.trigger requires `create`; the scope only grants `view`.
-    const result = checkScopeAccess([scope('capability', 'backup', ['view'])], 'backup.trigger')
-    expect(result.ok).toBe(false)
-    if (!result.ok) {
-      // Matcher's reason format: "No scope grants <access> on '<cap>' (<scope>-scope cap)"
-      expect(result.reason).toMatch(/No scope grants create on 'backup'/)
-    }
-  })
-
-  it('rejects when capability scope targets a different cap entirely', () => {
-    const result = checkScopeAccess(
-      [scope('capability', 'devices', ['view', 'create', 'delete'])],
-      'backup.list',
-    )
-    expect(result.ok).toBe(false)
-  })
-
-  it('accepts destructive method when scope includes delete', () => {
-    const result = checkScopeAccess(
-      [scope('capability', 'backup', ['view', 'delete'])],
-      'backup.delete',
-    )
-    expect(result.ok).toBe(true)
-    if (result.ok) expect(result.access).toBe('delete')
-  })
-
-  // ── Scope unions ────────────────────────────────────────────────
-
-  it('union of access flavours satisfies any single requirement', () => {
-    const scopes: TokenScope[] = [
-      scope('capability', 'backup', ['view']),
-      scope('capability', 'backup', ['create']),
-    ]
-    // view request → first scope matches
-    expect(checkScopeAccess(scopes, 'backup.list').ok).toBe(true)
-    // create request → second scope matches
-    expect(checkScopeAccess(scopes, 'backup.trigger').ok).toBe(true)
-  })
-
-  // ── Empty scope set ─────────────────────────────────────────────
-
-  it('rejects when no scopes are granted at all', () => {
-    const result = checkScopeAccess([], 'backup.list')
-    expect(result.ok).toBe(false)
-    if (!result.ok) {
-      expect(result.reason).toContain('Have: (none)')
-    }
-  })
-
-  // ── Reason string contains debug-friendly diff ──────────────────
-
-  it('reason string surfaces what the caller actually has', () => {
-    const result = checkScopeAccess([scope('capability', 'devices', ['view'])], 'backup.trigger')
-    expect(result.ok).toBe(false)
-    if (!result.ok) {
-      // Format: "No scope grants create on 'backup' (system-scope cap). Have: capability:devices[view]"
-      expect(result.reason).toMatch(/No scope grants create on 'backup'/)
-      expect(result.reason).toContain('capability:devices[view]')
-    }
-  })
-})

package/src/api/trpc/__tests__/webrtc-session-ua-enrich.spec.ts

@@ -1,136 +0,0 @@
-/**
- * Unit tests for the User-Agent enrichment the hub applies to the
- * `webrtc-session` mount. The hub reads the UA from the tRPC request
- * context and merges it into the subscriber attribution so the
- * stream-broker SUBSCRIBERS panel can identify a browser viewer. Any
- * client-supplied `userAgent` is OVERWRITTEN — the server trusts only the
- * request context, never the client.
- */
-import { describe, it, expect, vi } from 'vitest'
-import type { IncomingMessage } from 'node:http'
-import type { InferProvider, BrokerConsumerAttribution } from '@camstack/types'
-import { webrtcSessionCapability } from '@camstack/types'
-import { enrichInputWithUserAgent, wrapWebrtcSessionProviderWithRelay } from '../trpc.router.js'
-import type { TrpcContext } from '../trpc.context.js'
-
-type WebrtcSessionProvider = InferProvider<typeof webrtcSessionCapability>
-
-function reqWithUa(userAgent?: string): IncomingMessage {
-  const headers: Record<string, string | string[]> = {}
-  if (userAgent !== undefined) headers['user-agent'] = userAgent
-  return { headers, socket: {} } as unknown as IncomingMessage
-}
-
-describe('enrichInputWithUserAgent', () => {
-  it('passes input through unchanged when userAgent is null', () => {
-    const input = { deviceId: 1, consumerAttribution: { kind: 'webrtc-browser' } as const }
-    expect(enrichInputWithUserAgent(input, null)).toBe(input)
-  })
-
-  it('merges userAgent into an existing attribution (new object)', () => {
-    const attribution: BrokerConsumerAttribution = { kind: 'webrtc-browser', label: 'alice' }
-    const input = { deviceId: 1, consumerAttribution: attribution }
-    const out = enrichInputWithUserAgent(input, 'Chrome/120')
-    expect(out.consumerAttribution).toEqual({
-      kind: 'webrtc-browser',
-      label: 'alice',
-      userAgent: 'Chrome/120',
-    })
-    // Immutability: the original attribution is untouched.
-    expect(attribution.userAgent).toBeUndefined()
-  })
-
-  it('defaults to webrtc-browser when no attribution was supplied', () => {
-    const out = enrichInputWithUserAgent({ deviceId: 1 }, 'Firefox/121')
-    expect(out.consumerAttribution).toEqual({ kind: 'webrtc-browser', userAgent: 'Firefox/121' })
-  })
-
-  it('OVERWRITES a client-supplied userAgent (never trust the client)', () => {
-    const input = {
-      deviceId: 1,
-      consumerAttribution: { kind: 'webrtc-browser', userAgent: 'spoofed' } as const,
-    }
-    const out = enrichInputWithUserAgent(input, 'Safari/17')
-    expect(out.consumerAttribution?.userAgent).toBe('Safari/17')
-  })
-})
-
-describe('wrapWebrtcSessionProviderWithRelay — UA enrichment', () => {
-  function mockProvider(): WebrtcSessionProvider {
-    const createSession = vi.fn().mockResolvedValue({ sessionId: 's', sdpOffer: 'o' })
-    const handleOffer = vi.fn().mockResolvedValue({ sessionId: 's', sdpAnswer: 'a' })
-    const passthrough = vi.fn().mockResolvedValue(undefined)
-    return {
-      createSession,
-      handleOffer,
-      listStreams: vi.fn().mockResolvedValue([]),
-      handleAnswer: passthrough,
-      addIceCandidate: passthrough,
-      getIceCandidates: vi.fn().mockResolvedValue({ candidates: [], done: true }),
-      closeSession: passthrough,
-      hasAdaptiveBitrate: vi.fn().mockResolvedValue(false),
-      getSessionState: vi.fn().mockResolvedValue({ pendingRenegotiation: null }),
-    }
-  }
-
-  function ctxWith(userAgent?: string): TrpcContext {
-    return { user: null, req: reqWithUa(userAgent) }
-  }
-
-  it('injects the request UA into createSession attribution', async () => {
-    const provider = mockProvider()
-    const wrapped = wrapWebrtcSessionProviderWithRelay(provider, ctxWith('Edg/120'))
-
-    await wrapped.createSession({ deviceId: 1, target: { kind: 'adaptive' } })
-
-    expect(provider.createSession).toHaveBeenCalledTimes(1)
-    const arg = vi.mocked(provider.createSession).mock.calls[0]![0]
-    expect(arg.consumerAttribution).toEqual({ kind: 'webrtc-browser', userAgent: 'Edg/120' })
-  })
-
-  it('injects the request UA into handleOffer attribution', async () => {
-    const provider = mockProvider()
-    const wrapped = wrapWebrtcSessionProviderWithRelay(provider, ctxWith('CriOS/120'))
-
-    await wrapped.handleOffer({ deviceId: 1, sdpOffer: 'x' })
-
-    const arg = vi.mocked(provider.handleOffer).mock.calls[0]![0]
-    expect(arg.consumerAttribution).toEqual({ kind: 'webrtc-browser', userAgent: 'CriOS/120' })
-  })
-
-  it('overwrites a client-supplied UA on createSession', async () => {
-    const provider = mockProvider()
-    const wrapped = wrapWebrtcSessionProviderWithRelay(provider, ctxWith('TrustedUA/1'))
-
-    await wrapped.createSession({
-      deviceId: 1,
-      target: { kind: 'adaptive' },
-      consumerAttribution: { kind: 'webrtc-browser', userAgent: 'spoofed', label: 'bob' },
-    })
-
-    const arg = vi.mocked(provider.createSession).mock.calls[0]![0]
-    expect(arg.consumerAttribution).toEqual({
-      kind: 'webrtc-browser',
-      label: 'bob',
-      userAgent: 'TrustedUA/1',
-    })
-  })
-
-  it('does not alter the call when no UA header is present', async () => {
-    const provider = mockProvider()
-    const wrapped = wrapWebrtcSessionProviderWithRelay(provider, ctxWith(undefined))
-
-    await wrapped.createSession({ deviceId: 1, target: { kind: 'adaptive' } })
-
-    const arg = vi.mocked(provider.createSession).mock.calls[0]![0]
-    expect(arg.consumerAttribution).toBeUndefined()
-  })
-
-  it('delegates other methods straight through', async () => {
-    const provider = mockProvider()
-    const wrapped = wrapWebrtcSessionProviderWithRelay(provider, ctxWith('Chrome/120'))
-
-    await wrapped.closeSession({ deviceId: 1, sessionId: 's' })
-    expect(provider.closeSession).toHaveBeenCalledWith({ deviceId: 1, sessionId: 's' })
-  })
-})

package/src/api/trpc/cap-mount-helpers.ts

@@ -1,245 +0,0 @@
-/**
- * Small helpers for wiring capability routers to the `CapabilityRegistry`
- * in `trpc.router.ts`. These functions don't generate code — they just
- * remove boilerplate from the mount lambdas we pass to `createCapRouter_X`.
- *
- * When to use what:
- *   - `requireSingleton(registry, name)` — singleton caps with no custom
- *     composition. Returns the active provider or null (the codegen'd
- *     router itself throws PRECONDITION_FAILED when null).
- *   - `concatCollection(providers, method)` — collection caps whose
- *     methods return arrays and where the desired behaviour is "union of
- *     every provider's contribution" (e.g. `turn-provider.getTurnServers`).
- *   - `firstSupported(providers, probe, action)` — collection caps where
- *     exactly one provider should handle each request, selected by a
- *     probe method (e.g. `snapshot-provider.supportsDevice`).
- *
- * Collections that route by an input key (e.g. `webrtc` picking the
- * provider responsible for a given `streamId`) are NOT covered here —
- * they have app-specific routing logic that belongs in the mount.
- */
-import { TRPCError } from '@trpc/server'
-import type { CapabilityRegistry } from '@camstack/kernel'
-import type { CapabilityProviderMap } from '@camstack/types'
-
-/**
- * Fetch the currently active singleton provider for a capability.
- * Returns null if no provider is registered; the downstream codegen'd
- * router surfaces this as `PRECONDITION_FAILED` to the caller.
- */
-export function requireSingleton<K extends keyof CapabilityProviderMap>(
-  registry: CapabilityRegistry | null,
-  capName: K,
-): CapabilityProviderMap[K] | null {
-  return registry?.getSingleton(capName) ?? null
-}
-
-/**
- * Build a per-device dispatcher that satisfies the singleton-provider
- * shape but resolves the actual implementation lazily via
- * `registry.getNativeProvider(capName, deviceId)` on every method call.
- *
- * Use for device-scoped caps that have NO system-level wrapper (PTZ,
- * reboot, doorbell, brightness, motion-trigger, switch, …) — drivers
- * register per-device native providers via
- * `DeviceContext.registerNativeCap`, and this helper bridges the cap-
- * router's "fetch a singleton then call methods on it" flow into a
- * "resolve native by deviceId per call" flow.
- *
- * Method input MUST carry `deviceId: number`. Methods without that
- * field (auto-injected `getStatus({deviceId})` for caps with a status
- * block, every business method that follows the cap-definition
- * convention) work transparently.
- *
- * Throws PRECONDITION_FAILED with a device-specific message when no
- * native provider exists for the requested deviceId — much friendlier
- * than the singleton fallthrough's "no provider" generic error.
- */
-export function requireDeviceScoped<K extends keyof CapabilityProviderMap>(
-  registry: CapabilityRegistry | null,
-  capName: K,
-): CapabilityProviderMap[K] | null {
-  if (!registry) return null
-  // The Proxy is the singleton stand-in. Each property access returns
-  // a function that, on call, looks up the per-device native and
-  // forwards the call. No caching — the lookup is cheap (Map.get) and
-  // re-doing it per call lets devices come/go without stale refs.
-  const dispatcher = new Proxy(
-    {},
-    {
-      get(_target, prop: string | symbol) {
-        if (typeof prop !== 'string') return undefined
-        return async (input: { deviceId?: number } & Record<string, unknown>) => {
-          const deviceId = input?.deviceId
-          if (typeof deviceId !== 'number') {
-            throw new TRPCError({
-              code: 'BAD_REQUEST',
-              message: `${String(capName)}.${prop}: input must carry numeric "deviceId"`,
-            })
-          }
-          const native = registry.getNativeProvider<Record<string, (i: unknown) => unknown>>(
-            capName,
-            deviceId,
-          )
-          if (!native) {
-            throw new TRPCError({
-              code: 'PRECONDITION_FAILED',
-              message: `Capability "${String(capName)}" not registered for device ${deviceId}`,
-            })
-          }
-          const fn = native[prop]
-          if (typeof fn !== 'function') {
-            throw new TRPCError({
-              code: 'NOT_IMPLEMENTED',
-              message: `Capability "${String(capName)}" provider for device ${deviceId} does not implement "${prop}"`,
-            })
-          }
-          const result = await fn.call(native, input)
-          // Device-property-wiring overlay (read-time): only `getStatus`, and only
-          // when the device has links for this cap (resolveLinkedStatus returns
-          // null otherwise → base result untouched). One in-process singleton hop.
-          if (prop === 'getStatus') {
-            const deviceManager = registry.getSingleton<{
-              resolveLinkedStatus?: (i: {
-                deviceId: number
-                cap: string
-                baseStatus: unknown
-              }) => Promise<Record<string, unknown> | null>
-            }>('device-manager')
-            const overlaid = await deviceManager?.resolveLinkedStatus?.({
-              deviceId,
-              cap: String(capName),
-              baseStatus: result,
-            })
-            if (overlaid != null) return overlaid
-          }
-          return result
-        }
-      },
-    },
-  )
-  return dispatcher as unknown as CapabilityProviderMap[K]
-}
-
-// ── Method-on-provider callable types ────────────────────────────────
-
-/** A key on T whose value is a function with array / promise-array return. */
-type ArrayReturningMethodKey<T> = {
-  [K in keyof T]: T[K] extends (
-    ...args: infer _A
-  ) => readonly unknown[] | Promise<readonly unknown[]>
-    ? K
-    : never
-}[keyof T]
-
-/** A key on T whose value is a function returning boolean / promise-boolean. */
-type BoolReturningMethodKey<T> = {
-  [K in keyof T]: T[K] extends (...args: infer _A) => boolean | Promise<boolean> ? K : never
-}[keyof T]
-
-/**
- * Build a method that fan-outs a call to every provider in a collection
- * and concatenates their array results. Useful for contribution-style
- * caps where each provider adds to a shared pool.
- */
-export function concatCollection<T extends object, K extends ArrayReturningMethodKey<T>>(
-  providers: readonly T[],
-  method: K,
-): T[K] extends (...args: infer A) => readonly (infer R)[] | Promise<readonly (infer R)[]>
-  ? (...args: A) => Promise<readonly R[]>
-  : never {
-  const wrapper = async (...args: unknown[]): Promise<readonly unknown[]> => {
-    const results = await Promise.all(
-      providers.map(async (p): Promise<readonly unknown[]> => {
-        const member = Reflect.get(p, method)
-        if (typeof member !== 'function') return []
-        // `Reflect.apply` returns `any`; funnel through unknown.
-        const out: unknown = await Reflect.apply(member, p, args)
-        if (!Array.isArray(out)) return []
-        const arr: readonly unknown[] = out
-        return arr
-      }),
-    )
-    return results.flat()
-  }
-  // Type-level bridge: the runtime wrapper signature (unknown → Promise<unknown[]>)
-  // matches the declared generic conditional return; TypeScript's
-  // conditional types can't be narrowed inside a function body, so this
-  // boundary assertion is required.
-  return wrapper as T[K] extends (
-    ...args: infer A
-  ) => readonly (infer R)[] | Promise<readonly (infer R)[]>
-    ? (...args: A) => Promise<readonly R[]>
-    : never
-}
-
-/**
- * Iterate a collection asking each provider "do you handle this?" via a
- * probe method, then call an action on the first one that answers yes.
- * Each provider is tried in registration order; errors are swallowed and
- * the next provider is attempted. Returns null if no provider matches or
- * if every matching provider's action throws/returns null.
- */
-export function firstSupported<
-  T extends object,
-  Probe extends BoolReturningMethodKey<T>,
-  Action extends keyof T,
->(
-  providers: readonly T[],
-  probe: Probe,
-  action: Action,
-): T[Action] extends (...args: infer A) => infer R
-  ? (...args: A) => Promise<Awaited<R> | null>
-  : never {
-  const wrapper = async (...args: unknown[]): Promise<unknown> => {
-    const [first] = args
-    for (const p of providers) {
-      try {
-        const probeMember = Reflect.get(p, probe)
-        if (typeof probeMember !== 'function') continue
-        const supported: unknown = await Reflect.apply(probeMember, p, [first])
-        if (supported !== true) continue
-        const actionMember = Reflect.get(p, action)
-        if (typeof actionMember !== 'function') continue
-        const result: unknown = await Reflect.apply(actionMember, p, args)
-        if (result !== null && result !== undefined) return result
-      } catch {
-        // try next provider
-      }
-    }
-    return null
-  }
-  // Type-level bridge — see concatCollection for the same pattern.
-  return wrapper as T[Action] extends (...args: infer A) => infer R
-    ? (...args: A) => Promise<Awaited<R> | null>
-    : never
-}
-
-/**
- * Convenience for collection caps that want a "logical OR of probes"
- * (e.g. `supportsDevice` across every snapshot-provider).
- */
-export function anySupports<T extends object, K extends BoolReturningMethodKey<T>>(
-  providers: readonly T[],
-  probe: K,
-): T[K] extends (...args: infer A) => boolean | Promise<boolean>
-  ? (...args: A) => Promise<boolean>
-  : never {
-  const wrapper = async (...args: unknown[]): Promise<boolean> => {
-    for (const p of providers) {
-      const member = Reflect.get(p, probe)
-      if (typeof member !== 'function') continue
-      try {
-        const result: unknown = await Reflect.apply(member, p, args)
-        if (result === true) return true
-      } catch {
-        /* next */
-      }
-    }
-    return false
-  }
-  // Type-level bridge — see concatCollection for the same pattern.
-  return wrapper as T[K] extends (...args: infer A) => boolean | Promise<boolean>
-    ? (...args: A) => Promise<boolean>
-    : never
-}

package/src/api/trpc/cap-route-error-formatter.ts

@@ -1,171 +0,0 @@
-/**
- * tRPC error formatter that serializes CapRouteError diagnostic fields
- * across the server→client boundary.
- *
- * tRPC only carries `error.message` by default. This formatter augments
- * the default shape's `data` block with typed CapRouteError fields so the
- * admin-UI can read `capRouteReason` instead of substring-matching message text.
- *
- * Fields added (all optional — absent when the error is not a CapRouteError):
- *   - `capRouteReason` — 'no-provider' | 'node-offline' | 'cap-unknown' | 'transport-failed'
- *   - `capRouteRejected` — array of `{ kind: string; why: string }` route-rejection descriptors
- *   - `capRouteNodeId` — the target node id, when known
- *
- * The formatter is EXPORTED for unit testing (no side-effects, pure function).
- */
-import { CapRouteError } from '@camstack/kernel'
-import type { RejectedRoute } from '@camstack/kernel'
-import type { TRPCError } from '@trpc/server'
-import type { DefaultErrorShape } from '@trpc/server/unstable-core-do-not-import'
-
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-/** The augmented data block we attach when a CapRouteError is present. */
-export interface CapRouteErrorData {
-  readonly capRouteReason: string
-  readonly capRouteRejected: readonly RejectedRoute[]
-  readonly capRouteNodeId?: string
-}
-
-export interface AugmentedErrorShape extends DefaultErrorShape {
-  readonly data: DefaultErrorShape['data'] & Partial<CapRouteErrorData>
-}
-
-// ---------------------------------------------------------------------------
-// Type guards
-// ---------------------------------------------------------------------------
-
-/** Known CapRouteError reason values — used as a runtime safety rail. */
-const KNOWN_REASONS = new Set<string>([
-  'no-provider',
-  'node-offline',
-  'cap-unknown',
-  'transport-failed',
-])
-
-/** Narrows a plain string to the `CapRouteError['reason']` union. */
-function isCapRouteReason(r: string): r is CapRouteError['reason'] {
-  return KNOWN_REASONS.has(r)
-}
-
-/** Narrows an `unknown` value to `RejectedRoute` by checking structural shape. */
-function isRejectedRoute(r: unknown): r is RejectedRoute {
-  if (typeof r !== 'object' || r === null) return false
-  const kind: unknown = Reflect.get(r, 'kind')
-  const why: unknown = Reflect.get(r, 'why')
-  return typeof kind === 'string' && typeof why === 'string'
-}
-
-// ---------------------------------------------------------------------------
-// CapRouteError extraction helpers
-// ---------------------------------------------------------------------------
-
-/**
- * Walks the `.cause` chain of an error to find a CapRouteError.
- * Returns the first one found, or null.
- *
- * Detection is dual-mode:
- *   1. `instanceof CapRouteError` — works when the same module is loaded.
- *   2. Duck-type: `name === 'CapRouteError'` + `typeof reason === 'string'`
- *      — robust against module-boundary issues (self-contained addons).
- */
-function extractCapRouteError(err: unknown): CapRouteError | null {
-  let current: unknown = err
-  for (let depth = 0; depth < 8; depth++) {
-    if (current === null || current === undefined) return null
-
-    if (current instanceof CapRouteError) {
-      return current
-    }
-
-    // Duck-type fallback: err.name + err.reason field present
-    if (typeof current === 'object' && Reflect.get(current, 'name') === 'CapRouteError') {
-      const rawReason: unknown = Reflect.get(current, 'reason')
-      if (typeof rawReason === 'string') {
-        // Runtime safety: reject unrecognised reason strings so the formatter
-        // only promotes values it knows are valid CapRouteError reasons.
-        if (!isCapRouteReason(rawReason)) {
-          // Unrecognised reason — treat as a non-CapRouteError and keep walking
-          const cause: unknown = Reflect.get(current, 'cause')
-          if (cause === current) return null
-          current = cause
-          continue
-        }
-        const reason: CapRouteError['reason'] = rawReason
-
-        const rawRejected: unknown = Reflect.get(current, 'rejected')
-        const rejected: readonly RejectedRoute[] = Array.isArray(rawRejected)
-          ? rawRejected.filter(isRejectedRoute)
-          : []
-
-        const nodeId: unknown = Reflect.get(current, 'nodeId')
-        const message: unknown = Reflect.get(current, 'message')
-        const rawCapName: unknown = Reflect.get(current, 'capName')
-        const capName: string = typeof rawCapName === 'string' ? rawCapName : '(unknown)'
-
-        // Build a minimal object with the same shape — enough for the formatter.
-        const synthetic = Object.assign(
-          new CapRouteError(capName, undefined, {
-            reason,
-            rejected,
-            ...(typeof nodeId === 'string' ? { nodeId } : {}),
-          }),
-          {
-            // Override message from the original if available
-            message: typeof message === 'string' ? message : '(duck-typed CapRouteError)',
-          },
-        )
-        return synthetic
-      }
-    }
-
-    // Walk the cause chain
-    if (typeof current !== 'object') return null
-    const cause: unknown = Reflect.get(current, 'cause')
-    if (cause === current) return null // Guard against circular refs
-    current = cause
-  }
-  return null
-}
-
-// ---------------------------------------------------------------------------
-// Formatter — exported for unit tests
-// ---------------------------------------------------------------------------
-
-export interface FormatTrpcErrorOpts {
-  readonly error: TRPCError
-  readonly shape: DefaultErrorShape
-}
-
-/**
- * Augments the default tRPC error shape with CapRouteError diagnostic fields
- * when the thrown error (or any error in its `.cause` chain) is a CapRouteError.
- * Returns the shape unchanged for all other errors.
- */
-export function formatTrpcError(opts: FormatTrpcErrorOpts): AugmentedErrorShape {
-  const { error, shape } = opts
-
-  // extractCapRouteError already walks the full .cause chain, so a single call
-  // starting from `error` covers both `error instanceof CapRouteError` and
-  // `error.cause` (and deeper nesting). No second call needed.
-  const capRouteError = extractCapRouteError(error)
-  if (capRouteError === null) {
-    return { ...shape, data: { ...shape.data } }
-  }
-
-  const extraData: CapRouteErrorData = {
-    capRouteReason: capRouteError.reason,
-    capRouteRejected: capRouteError.rejected,
-    ...(capRouteError.nodeId !== undefined ? { capRouteNodeId: capRouteError.nodeId } : {}),
-  }
-
-  return {
-    ...shape,
-    data: {
-      ...shape.data,
-      ...extraData,
-    },
-  }
-}