@camstack/server 0.1.6 → 0.1.8

package/src/__tests__/cap-route-adapter.spec.ts

@@ -0,0 +1,289 @@
+/**
+ * Unit tests for the two adapter factories and the resolver wired with them.
+ *
+ * Exercises:
+ *  - createNodeCapAuthority: delegates to HubNodeRegistry correctly
+ *  - createInProcessProviderLookup: invokes provider methods cast-free
+ *  - Resolver wired with both adapters:
+ *      hub-local UDS child cap resolves via callCapOnChild
+ *      hub-resident singleton resolves in-process (invoke called)
+ *      absent cap throws CapRouteError (NOT the old opaque string)
+ *
+ * We test the adapter factories directly + a resolver wired with them —
+ * standing up a full MoleculerService is too heavy for a unit test, and
+ * testing the adapters + resolver in isolation exercises the meaningful unit.
+ */
+
+import { describe, it, expect, vi } from 'vitest'
+import { CapRouteError, CapRouteResolver } from '@camstack/kernel'
+import type {
+  NodeCapAuthority,
+  InProcessProviderLookup,
+  HubLocalChildDispatcher,
+  CapRouteResolverDeps,
+} from '@camstack/kernel'
+import type { InProcessProviderRef } from '@camstack/kernel'
+import {
+  createNodeCapAuthority,
+  createInProcessProviderLookup,
+} from '../core/moleculer/cap-route-authority.js'
+
+// ---------------------------------------------------------------------------
+// Helpers for stub HubNodeRegistry
+// ---------------------------------------------------------------------------
+
+interface StubNodeEntry {
+  readonly addonId: string
+  readonly capabilities: readonly string[]
+}
+
+function makeNodeRegistry(nodes: ReadonlyMap<string, readonly StubNodeEntry[]>) {
+  return {
+    getNodeManifest(nodeId: string) {
+      return nodes.get(nodeId)
+    },
+    listNodeIds(): readonly string[] {
+      return [...nodes.keys()]
+    },
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers for stub CapabilityService
+// ---------------------------------------------------------------------------
+
+function makeCapabilityService(
+  providers: ReadonlyMap<string, Record<string, unknown>>,
+) {
+  return {
+    getSingleton<T>(capability: string): T | null {
+      return (providers.get(capability) as T) ?? null
+    },
+  }
+}
+
+// ---------------------------------------------------------------------------
+// createNodeCapAuthority
+// ---------------------------------------------------------------------------
+
+describe('createNodeCapAuthority', () => {
+  const nodes = new Map([
+    ['hub/stream-broker', [{ addonId: 'addon-stream-broker', capabilities: ['stream-broker', 'stream-params'] }]],
+    ['dev-agent-0', [{ addonId: 'addon-detection-pipeline', capabilities: ['pipeline-executor'] }]],
+  ])
+  const registry = makeNodeRegistry(nodes)
+  const authority = createNodeCapAuthority(registry)
+
+  it('nodeKnowsCap returns true when the node manifest includes the cap', () => {
+    expect(authority.nodeKnowsCap('hub/stream-broker', 'stream-broker')).toBe(true)
+    expect(authority.nodeKnowsCap('hub/stream-broker', 'stream-params')).toBe(true)
+    expect(authority.nodeKnowsCap('hub/stream-broker', 'ghost-cap')).toBe(false)
+  })
+
+  it('nodeKnowsCap returns false for unknown nodes', () => {
+    expect(authority.nodeKnowsCap('not-a-node', 'stream-broker')).toBe(false)
+  })
+
+  it('getAddonId returns the addonId for a known cap', () => {
+    expect(authority.getAddonId('hub/stream-broker', 'stream-broker')).toBe('addon-stream-broker')
+    expect(authority.getAddonId('dev-agent-0', 'pipeline-executor')).toBe('addon-detection-pipeline')
+  })
+
+  it('getAddonId returns null for missing nodes or caps', () => {
+    expect(authority.getAddonId('not-a-node', 'stream-broker')).toBeNull()
+    expect(authority.getAddonId('hub/stream-broker', 'ghost-cap')).toBeNull()
+  })
+
+  it('nodeIsAgent: hub and hub-children are NOT agents; bare-id non-hub nodes are agents', () => {
+    expect(authority.nodeIsAgent('hub')).toBe(false)
+    expect(authority.nodeIsAgent('hub/stream-broker')).toBe(false)
+    expect(authority.nodeIsAgent('dev-agent-0')).toBe(true)
+    expect(authority.nodeIsAgent('some-remote-agent')).toBe(true)
+  })
+
+  it('nodeOnline: nodes in the registry are online; absent ones are not', () => {
+    expect(authority.nodeOnline('hub/stream-broker')).toBe(true)
+    expect(authority.nodeOnline('dev-agent-0')).toBe(true)
+    expect(authority.nodeOnline('not-registered')).toBe(false)
+  })
+
+  it('listNodeIds returns all registered node ids', () => {
+    const ids = authority.listNodeIds()
+    expect(ids).toContain('hub/stream-broker')
+    expect(ids).toContain('dev-agent-0')
+    expect(ids).toHaveLength(2)
+  })
+
+  it('getAgentChildId always returns null (hub cannot resolve; Task 6 handles it)', () => {
+    expect(authority.getAgentChildId('dev-agent-0', 'pipeline-executor')).toBeNull()
+  })
+})
+
+// ---------------------------------------------------------------------------
+// createNodeCapAuthority — per-node singleton override
+// ---------------------------------------------------------------------------
+
+describe('createNodeCapAuthority — per-node singleton override', () => {
+  it('getAddonId honors the per-node singleton override when available', () => {
+    const nodeRegistry = {
+      getNodeManifest: (id: string) => id === 'dev-agent-0'
+        ? [{ addonId: 'webrtc-native', capabilities: ['webrtc-session'] },
+           { addonId: 'stream-broker', capabilities: ['webrtc-session'] }]
+        : undefined,
+      listNodeIds: () => ['hub', 'dev-agent-0'],
+    }
+    const authority = createNodeCapAuthority(nodeRegistry, {
+      resolveSingleton: (cap, nodeId) =>
+        cap === 'webrtc-session' && nodeId === 'dev-agent-0' ? 'stream-broker' : null,
+    })
+    expect(authority.getAddonId('dev-agent-0', 'webrtc-session')).toBe('stream-broker')
+  })
+
+  it('getAddonId falls back to first manifest match without an override', () => {
+    const nodeRegistry = {
+      getNodeManifest: (id: string) => id === 'dev-agent-0'
+        ? [{ addonId: 'webrtc-native', capabilities: ['webrtc-session'] }]
+        : undefined,
+      listNodeIds: () => ['hub', 'dev-agent-0'],
+    }
+    const authority = createNodeCapAuthority(nodeRegistry, { resolveSingleton: () => null })
+    expect(authority.getAddonId('dev-agent-0', 'webrtc-session')).toBe('webrtc-native')
+  })
+})
+
+// ---------------------------------------------------------------------------
+// createInProcessProviderLookup
+// ---------------------------------------------------------------------------
+
+describe('createInProcessProviderLookup', () => {
+  it('returns null for a cap not hosted in-process', () => {
+    const lookup = createInProcessProviderLookup(makeCapabilityService(new Map()))
+    expect(lookup('device-manager')).toBeNull()
+  })
+
+  it('returns an InProcessProviderRef whose invoke delegates to the provider method', async () => {
+    const getStatusImpl = vi.fn().mockReturnValue({ ok: true })
+    const providers = new Map<string, Record<string, unknown>>([
+      ['device-manager', { getStatus: getStatusImpl }],
+    ])
+    const lookup = createInProcessProviderLookup(makeCapabilityService(providers))
+
+    const ref = lookup('device-manager')
+    expect(ref).not.toBeNull()
+
+    const result = await ref!.invoke('getStatus', { deviceId: 1 })
+    expect(result).toEqual({ ok: true })
+    expect(getStatusImpl).toHaveBeenCalledOnce()
+    expect(getStatusImpl).toHaveBeenCalledWith({ deviceId: 1 })
+  })
+
+  it('invoke throws a typed Error when the method is not a function (never casts)', async () => {
+    const providers = new Map<string, Record<string, unknown>>([
+      ['device-manager', { notAFn: 'some-string' }],
+    ])
+    const lookup = createInProcessProviderLookup(makeCapabilityService(providers))
+    const ref = lookup('device-manager')
+    expect(ref).not.toBeNull()
+
+    await expect(ref!.invoke('notAFn', {})).rejects.toThrow(/method "notAFn" not found/)
+    await expect(ref!.invoke('missingMethod', {})).rejects.toThrow(/method "missingMethod" not found/)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Resolver wired with both adapters
+// ---------------------------------------------------------------------------
+
+describe('Resolver + adapters — end-to-end dispatch', () => {
+  const HUB_NODE_ID = 'hub'
+
+  function makeCallCapOnChildSpy() {
+    return vi.fn(async (_childId: string, _input: unknown) => ({ ok: true, from: 'uds' }))
+  }
+
+  function makeHubLocalRegistry(caps: ReadonlyMap<string, string>): HubLocalChildDispatcher & { callSpy: ReturnType<typeof vi.fn> } {
+    const callSpy = makeCallCapOnChildSpy()
+    return {
+      resolveChildId: (capName: string) => caps.get(capName) ?? null,
+      callCapOnChild: callSpy,
+      callSpy,
+    }
+  }
+
+  it('hub-local UDS child cap resolves via callCapOnChild', async () => {
+    // Registry: stream-broker is served by a hub-local child.
+    const nodes = new Map([
+      ['hub/stream-broker', [{ addonId: 'addon-stream-broker', capabilities: ['stream-broker'] }]],
+    ])
+    const nodeRegistry = makeNodeRegistry(nodes)
+    const authority = createNodeCapAuthority(nodeRegistry)
+
+    const hubLocalCaps = new Map([['stream-broker', 'addon-stream-broker']])
+    const hubLocalRegistry = makeHubLocalRegistry(hubLocalCaps)
+
+    const lookup = createInProcessProviderLookup(makeCapabilityService(new Map()))
+
+    const deps: CapRouteResolverDeps = {
+      hubNodeId: HUB_NODE_ID,
+      broker: { call: vi.fn(), waitForServices: vi.fn() },
+      hubLocalRegistry,
+      nodeAuthority: authority,
+      inProcessProviders: lookup,
+    }
+
+    const resolver = new CapRouteResolver(deps)
+    const route = resolver.resolveCapRoute('stream-broker', { nodeId: HUB_NODE_ID })
+    expect(route.kind).toBe('hub-local-uds')
+
+    const result = await resolver.dispatch(route, 'attachCamera', { deviceId: 5 })
+    expect(result).toEqual({ ok: true, from: 'uds' })
+    expect(hubLocalRegistry.callSpy).toHaveBeenCalledOnce()
+  })
+
+  it('hub-resident singleton resolves in-process via invoke', async () => {
+    const invokeSpy = vi.fn().mockResolvedValue({ devices: [] })
+    const providers = new Map<string, Record<string, unknown>>([
+      ['device-manager', { listAll: invokeSpy }],
+    ])
+    const lookup = createInProcessProviderLookup(makeCapabilityService(providers))
+
+    const deps: CapRouteResolverDeps = {
+      hubNodeId: HUB_NODE_ID,
+      broker: { call: vi.fn(), waitForServices: vi.fn() },
+      hubLocalRegistry: null,
+      nodeAuthority: createNodeCapAuthority(makeNodeRegistry(new Map())),
+      inProcessProviders: lookup,
+    }
+
+    const resolver = new CapRouteResolver(deps)
+    const route = resolver.resolveCapRoute('device-manager', { nodeId: HUB_NODE_ID })
+    expect(route.kind).toBe('hub-in-process')
+
+    const result = await resolver.dispatch(route, 'listAll', {})
+    expect(result).toEqual({ devices: [] })
+    expect(invokeSpy).toHaveBeenCalledOnce()
+  })
+
+  it('genuinely-absent cap throws CapRouteError, NOT the old opaque string', () => {
+    const deps: CapRouteResolverDeps = {
+      hubNodeId: HUB_NODE_ID,
+      broker: { call: vi.fn(), waitForServices: vi.fn() },
+      hubLocalRegistry: null,
+      nodeAuthority: createNodeCapAuthority(makeNodeRegistry(new Map())),
+      inProcessProviders: createInProcessProviderLookup(makeCapabilityService(new Map())),
+    }
+    const resolver = new CapRouteResolver(deps)
+
+    let thrown: unknown
+    try {
+      resolver.resolveCapRoute('ghost-cap', {})
+    } catch (e) {
+      thrown = e
+    }
+
+    expect(thrown).toBeInstanceOf(CapRouteError)
+    expect((thrown as CapRouteError).reason).toBe('no-provider')
+    // Must NOT be the old opaque string
+    expect((thrown as CapRouteError).message).not.toContain('Capability "ghost-cap" not available on node')
+  })
+})

package/src/__tests__/cap-routers/broker-routing.router.spec.ts

@@ -0,0 +1,169 @@
+
+/**
+ * Routing regression spec for the `broker` system-collection cap.
+ *
+ * The bug: `broker` is `scope:'system', mode:'collection'`. Two addons
+ * register a `broker` provider, each owning a DISJOINT id set
+ * (mqtt-broker owns `mqtt_*`, provider-homeassistant owns `ha_*`). The
+ * generated collection mount only fans out the array-output methods
+ * (`list` / `listProviders`); every id-keyed method (`get` / `getSettings`
+ * / `remove` / `testConnection` / …) falls through to `providers[0]`
+ * (the FIRST-registered provider = mqtt-broker). So operating on an HA
+ * broker `ha_1` hit mqtt-broker → "broker 'ha_1' not found".
+ *
+ * The fix: each broker carries its owning `addonId`; the admin UI threads
+ * it back as the `{ addonId }` system-collection selector so the call
+ * routes to the OWNING provider via `getProviderByAddonId`. Providers
+ * also return `null` (not throw) for ids they don't own, so the
+ * no-addonId fallback degrades gracefully.
+ *
+ * This spec exercises `createCapRouter_broker` with the SAME selector
+ * the generated mount builds (registry-backed: addonId → provider, else
+ * first-provider aggregate with array methods fanned out). It registers
+ * two mock providers and asserts:
+ *  - `list()` returns both, each tagged with its `addonId`.
+ *  - `get({id:'ha_1'}, addonId:'ha')` routes to the HA provider.
+ *  - `get({id:'ha_1'})` WITHOUT addonId returns null (graceful) — the
+ *    HA-owned id isn't in providers[0]'s registry, so it doesn't throw.
+ *  - `listProviders()` aggregates both providers' entries.
+ */
+import { describe, it, expect } from 'vitest'
+import { createCapRouter_broker } from '../../api/trpc/generated-cap-routers.js'
+import { type IBrokerProvider, type BrokerInfo, type BrokerProviderInfo } from '@camstack/types'
+import { concatCollection } from '../../api/trpc/cap-mount-helpers.js'
+import { makeCtx, invokeProcedure } from './harness.js'
+
+/**
+ * A self-contained mock `broker` provider that owns a fixed set of
+ * broker ids and self-tags every returned record with its `addonId`.
+ * Returns `null` / no-op for ids it does NOT own (never throws) — the
+ * exact graceful-degradation contract the real providers must honour.
+ */
+function makeProvider(addonId: string, ownedIds: readonly string[], kind: string): IBrokerProvider {
+  const owns = (id: string): boolean => ownedIds.includes(id)
+  const infoFor = (id: string): BrokerInfo => ({
+    id,
+    addonId,
+    name: `${kind}-${id}`,
+    kind,
+    status: 'connected',
+    info: {},
+    lastCheckedAt: null,
+    error: null,
+  })
+  return {
+    list: async () => ownedIds.map(infoFor),
+    get: async ({ id }) => (owns(id) ? infoFor(id) : null),
+    listProviders: async (): Promise<BrokerProviderInfo[]> => [
+      { addonId, kinds: [{ kind, label: kind }] },
+    ],
+    add: async () => ({ id: 'new' }),
+    remove: async () => {
+      // no-op for foreign ids (and owned ids in this mock)
+    },
+    testConnection: async ({ id }) =>
+      owns(id) ? { ok: true, latencyMs: 1 } : { ok: false, error: 'unknown broker' },
+    getSettings: async ({ id }) => (owns(id) ? { secret: id } : null),
+    setSettings: async () => {
+      // no-op
+    },
+    getBrokerConfig: async ({ id }) => (owns(id) ? { url: id } : null),
+    getSettingsSchema: async ({ kind: k }) => (k === kind ? { form: kind } : null),
+    testSettings: async () => ({ ok: true }),
+    publish: async () => null,
+    subscribe: async () => ({ subscriptionId: 's' }),
+    unsubscribe: async () => {
+      // no-op
+    },
+    getState: async () => null,
+    getStatus: async () => ({ brokerCount: ownedIds.length, connectedCount: ownedIds.length }),
+  }
+}
+
+/**
+ * Mirror of the generated collection mount selector for `broker`
+ * (`generated-cap-mounts.ts`): addonId → that provider directly; else a
+ * first-provider aggregate whose array-output methods are
+ * `concatCollection`-fanned. Two providers registered in order:
+ * mqtt (owns `mqtt_1`) first, ha (owns `ha_1`) second.
+ */
+function makeSelector(): (addonId?: string) => IBrokerProvider | null {
+  const mqtt = makeProvider('mqtt', ['mqtt_1'], 'mqtt')
+  const ha = makeProvider('ha', ['ha_1'], 'home-assistant')
+  const byAddonId: Record<string, IBrokerProvider> = { mqtt, ha }
+  const providers: readonly IBrokerProvider[] = [mqtt, ha]
+  return (addonId?: string): IBrokerProvider | null => {
+    if (addonId !== undefined) return byAddonId[addonId] ?? null
+    const first = providers[0]!
+    return {
+      ...first,
+      list: concatCollection(providers, 'list') as IBrokerProvider['list'],
+      listProviders: concatCollection(providers, 'listProviders') as IBrokerProvider['listProviders'],
+    }
+  }
+}
+
+describe('broker cap — addonId ownership routing', () => {
+  it('list() aggregates both providers, each broker tagged with its addonId', async () => {
+    const selector = makeSelector()
+    const router = createCapRouter_broker((_ctx, addonId) => selector(addonId))
+
+    const outcome = await invokeProcedure(router, 'list', makeCtx('admin'), {})
+
+    expect(outcome.ok).toBe(true)
+    if (!outcome.ok) return
+    const rows = outcome.value as BrokerInfo[]
+    const byId = new Map(rows.map(r => [r.id, r]))
+    expect(byId.get('mqtt_1')?.addonId).toBe('mqtt')
+    expect(byId.get('ha_1')?.addonId).toBe('ha')
+  })
+
+  it('get({id:ha_1}, addonId:ha) routes to the HA provider (not mqtt-broker)', async () => {
+    const selector = makeSelector()
+    const router = createCapRouter_broker((_ctx, addonId) => selector(addonId))
+
+    const outcome = await invokeProcedure(router, 'get', makeCtx('admin'), { id: 'ha_1', addonId: 'ha' })
+
+    expect(outcome.ok).toBe(true)
+    if (!outcome.ok) return
+    const row = outcome.value as BrokerInfo | null
+    expect(row).not.toBeNull()
+    expect(row?.id).toBe('ha_1')
+    expect(row?.addonId).toBe('ha')
+  })
+
+  it('get({id:ha_1}) WITHOUT addonId returns null gracefully (first provider does not own it)', async () => {
+    const selector = makeSelector()
+    const router = createCapRouter_broker((_ctx, addonId) => selector(addonId))
+
+    const outcome = await invokeProcedure(router, 'get', makeCtx('admin'), { id: 'ha_1' })
+
+    expect(outcome.ok).toBe(true)
+    if (!outcome.ok) return
+    expect(outcome.value).toBeNull()
+  })
+
+  it('testConnection({id:ha_1}, addonId:ha) routes to HA provider and succeeds', async () => {
+    const selector = makeSelector()
+    const router = createCapRouter_broker((_ctx, addonId) => selector(addonId))
+
+    const outcome = await invokeProcedure(router, 'testConnection', makeCtx('admin'), { id: 'ha_1', addonId: 'ha' })
+
+    expect(outcome.ok).toBe(true)
+    if (!outcome.ok) return
+    expect(outcome.value).toEqual({ ok: true, latencyMs: 1 })
+  })
+
+  it('listProviders() aggregates both providers entries', async () => {
+    const selector = makeSelector()
+    const router = createCapRouter_broker((_ctx, addonId) => selector(addonId))
+
+    const outcome = await invokeProcedure(router, 'listProviders', makeCtx('admin'))
+
+    expect(outcome.ok).toBe(true)
+    if (!outcome.ok) return
+    const entries = outcome.value as BrokerProviderInfo[]
+    const addonIds = entries.map(e => e.addonId).sort()
+    expect(addonIds).toEqual(['ha', 'mqtt'])
+  })
+})

package/src/__tests__/cap-routers/cap-route-error-formatter.spec.ts

@@ -0,0 +1,123 @@
+/**
+ * Unit tests for the cap-route-error-formatter.
+ *
+ * `formatTrpcError` is a pure function — no tRPC plumbing required.
+ * We hand-craft minimal TRPCError-like / DefaultErrorShape-like objects
+ * to verify the augmentation logic.
+ */
+import { describe, it, expect } from 'vitest'
+import { TRPCError } from '@trpc/server'
+import { CapRouteError } from '@camstack/kernel'
+import { formatTrpcError } from '../../api/trpc/cap-route-error-formatter.js'
+
+// ── Helpers ──────────────────────────────────────────────────────────────────
+
+/** Minimal DefaultErrorShape stub. */
+function makeShape(overrides: Partial<{ message: string }> = {}): Parameters<typeof formatTrpcError>[0]['shape'] {
+  return {
+    message: overrides.message ?? 'Something went wrong',
+    code: -32603, // INTERNAL_SERVER_ERROR code number
+    data: {
+      code: 'INTERNAL_SERVER_ERROR',
+      httpStatus: 500,
+    },
+  }
+}
+
+/** Build a TRPCError-like object that formatTrpcError accepts. */
+function makeTrpcError(
+  message: string,
+  cause?: Error,
+): Parameters<typeof formatTrpcError>[0]['error'] {
+  return new TRPCError({
+    code: 'PRECONDITION_FAILED',
+    message,
+    cause,
+  })
+}
+
+// ── Tests ─────────────────────────────────────────────────────────────────────
+
+describe('formatTrpcError', () => {
+  it('returns shape unchanged when error is not a CapRouteError', () => {
+    const shape = makeShape({ message: 'Boom' })
+    const error = makeTrpcError('Some generic error')
+    const result = formatTrpcError({ error, shape })
+    expect(result).toStrictEqual(shape)
+    expect(result.data).not.toHaveProperty('capRouteReason')
+  })
+
+  it('augments shape with capRouteReason when error.cause is a CapRouteError', () => {
+    const capRouteErr = new CapRouteError('my-cap', undefined, {
+      reason: 'no-provider',
+      rejected: [{ kind: 'hub-in-process', why: 'no provider bound' }],
+    })
+    const shape = makeShape()
+    const error = makeTrpcError('Capability "my-cap" provider not available', capRouteErr)
+    const result = formatTrpcError({ error, shape })
+
+    expect(result.data.capRouteReason).toBe('no-provider')
+    expect(result.data.capRouteRejected).toStrictEqual([
+      { kind: 'hub-in-process', why: 'no provider bound' },
+    ])
+    expect(result.data.capRouteNodeId).toBeUndefined()
+    // Original shape fields preserved
+    expect(result.message).toBe(shape.message)
+    expect(result.code).toBe(shape.code)
+  })
+
+  it('augments shape with capRouteReason when error itself is a CapRouteError', () => {
+    const capRouteErr = new CapRouteError('some-cap', undefined, {
+      reason: 'node-offline',
+      nodeId: 'node-abc',
+      rejected: [{ kind: 'remote-moleculer', why: 'node node-abc is offline' }],
+    })
+    const shape = makeShape()
+    // Wrap as TRPCError with the CapRouteError AS the cause
+    const error = makeTrpcError('Transport failed', capRouteErr)
+    const result = formatTrpcError({ error, shape })
+
+    expect(result.data.capRouteReason).toBe('node-offline')
+    expect(result.data.capRouteNodeId).toBe('node-abc')
+    expect(result.data.capRouteRejected).toHaveLength(1)
+  })
+
+  it('surfaces transport-failed reason correctly (not absent provider)', () => {
+    const capRouteErr = new CapRouteError('stream-params', 'getStatus', {
+      reason: 'transport-failed',
+      rejected: [{ kind: 'hub-local-uds', why: 'socket closed' }],
+    })
+    const shape = makeShape()
+    const error = makeTrpcError('Transport failed', capRouteErr)
+    const result = formatTrpcError({ error, shape })
+
+    expect(result.data.capRouteReason).toBe('transport-failed')
+    expect(result.data.capRouteRejected).toStrictEqual([
+      { kind: 'hub-local-uds', why: 'socket closed' },
+    ])
+  })
+
+  it('walks a nested cause chain to find a CapRouteError', () => {
+    const capRouteErr = new CapRouteError('ptz', undefined, {
+      reason: 'cap-unknown',
+      rejected: [],
+    })
+    // Wrap two levels deep
+    const innerError = new Error('dispatch failed', { cause: capRouteErr })
+    const shape = makeShape()
+    const error = makeTrpcError('Outer error', innerError)
+    const result = formatTrpcError({ error, shape })
+
+    expect(result.data.capRouteReason).toBe('cap-unknown')
+  })
+
+  it('returns shape unchanged for a plain Error (non-CapRouteError cause)', () => {
+    const plainErr = new Error('plain cause')
+    const shape = makeShape()
+    const error = makeTrpcError('Wrapper', plainErr)
+    const result = formatTrpcError({ error, shape })
+
+    expect(result.data).not.toHaveProperty('capRouteReason')
+    expect(result).toStrictEqual(shape)
+  })
+})

package/src/__tests__/cap-routers/capabilities-node.spec.ts

@@ -0,0 +1,55 @@
+/**
+ * Spec for the per-node singleton extension in capabilities.router.
+ *
+ * Exercises:
+ *  - setActiveSingleton with nodeId → calls registry with (cap, addonId, nodeId)
+ *    + persists `capabilities.singletonNode.<cap>.<nodeId>`
+ *  - setActiveSingleton without nodeId → persists `capabilities.singleton.<cap>` (global key)
+ *  - clearSingletonNodeOverride → calls registry.clearSingletonNodeOverride(cap, nodeId)
+ *    + persists the per-node key as null
+ */
+import { describe, it, expect, vi } from 'vitest'
+import type { CapabilityRegistry } from '@camstack/kernel'
+import type { ConfigService } from '../../core/config/config.service.js'
+import { createCapabilitiesRouter } from '../../api/core/capabilities.router.js'
+import { makeCtx } from './harness.js'
+
+function harness() {
+  const calls: { setActiveSingleton: unknown[][]; clear: unknown[][] } = { setActiveSingleton: [], clear: [] }
+  const sets: Record<string, unknown> = {}
+  const registry = {
+    setActiveSingleton: vi.fn(async (...a: unknown[]) => { calls.setActiveSingleton.push(a) }),
+    clearSingletonNodeOverride: vi.fn((...a: unknown[]) => { calls.clear.push(a) }),
+    listCapabilities: () => [],
+  } as unknown as CapabilityRegistry
+  const config = { set: (k: string, v: unknown) => { sets[k] = v } } as unknown as ConfigService
+  const router = createCapabilitiesRouter(registry, config)
+  return { router, calls, sets, registry }
+}
+
+describe('capabilities.router — per-node singleton', () => {
+  it('setActiveSingleton with nodeId persists the per-node key', async () => {
+    const { router, calls, sets } = harness()
+    const caller = router.createCaller(makeCtx('admin'))
+    await caller.setActiveSingleton({
+      capability: 'webrtc-session', addonId: 'webrtc-native', nodeId: 'dev-agent-0',
+    })
+    expect(calls.setActiveSingleton[0]).toEqual(['webrtc-session', 'webrtc-native', 'dev-agent-0'])
+    expect(sets['capabilities.singletonNode.webrtc-session.dev-agent-0']).toBe('webrtc-native')
+  })
+
+  it('setActiveSingleton without nodeId persists the global key', async () => {
+    const { router, sets } = harness()
+    const caller = router.createCaller(makeCtx('admin'))
+    await caller.setActiveSingleton({ capability: 'webrtc-session', addonId: 'stream-broker' })
+    expect(sets['capabilities.singleton.webrtc-session']).toBe('stream-broker')
+  })
+
+  it('clearSingletonNodeOverride clears the per-node key', async () => {
+    const { router, calls, sets } = harness()
+    const caller = router.createCaller(makeCtx('admin'))
+    await caller.clearSingletonNodeOverride({ capability: 'webrtc-session', nodeId: 'dev-agent-0' })
+    expect(calls.clear[0]).toEqual(['webrtc-session', 'dev-agent-0'])
+    expect(sets['capabilities.singletonNode.webrtc-session.dev-agent-0']).toBe(null)
+  })
+})