@camstack/server 0.1.5 → 0.1.7

package/src/__tests__/cap-providers-bulk-update.spec.ts

@@ -0,0 +1,388 @@
+/**
+ * cap-providers-bulk-update.spec.ts
+ *
+ * Verifies the wire-up in buildAddonsProvider for:
+ *   1. Delegation to BulkUpdateCoordinator (startBulkUpdate / cancelBulkUpdate /
+ *      getBulkUpdateState / listActiveBulkUpdates)
+ *   2. isSystem field added to listUpdates output
+ *   3. deferRestart propagated through updateFrameworkPackage
+ *
+ * Spec: docs/superpowers/specs/2026-05-21-addons-bulk-update-progress-design.md
+ * Plan: docs/superpowers/plans/2026-05-21-addons-bulk-update-progress.md  (Task 4)
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import type { IAddonsProvider } from '@camstack/types'
+import { FRAMEWORK_PACKAGE_ALLOWLIST } from '../core/addon/addon-package.service.js'
+
+// ── Module-level mock ─────────────────────────────────────────────────────────
+// Must be hoisted before any import that resolves bulk-update-coordinator.
+// Uses a real class so `new BulkUpdateCoordinator(...)` works; the instance
+// methods are vi.fn stubs shared across all instances created in a test.
+const _startFn = vi.fn()
+const _getFn = vi.fn()
+const _cancelFn = vi.fn()
+const _listFn = vi.fn()
+
+vi.mock('../api/core/bulk-update-coordinator.js', () => {
+  class MockBulkUpdateCoordinator {
+    start = _startFn
+    get = _getFn
+    cancel = _cancelFn
+    list = _listFn
+  }
+  return { BulkUpdateCoordinator: MockBulkUpdateCoordinator }
+})
+
+// ── Imports that depend on the mocked modules ─────────────────────────────────
+import { buildAddonsProvider } from '../api/core/cap-providers.js'
+import { makeCtx } from './cap-routers/harness.js'
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function makeLogger() {
+  const logger = {
+    info: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+    debug: vi.fn(),
+    trace: vi.fn(),
+    fatal: vi.fn(),
+    scope: vi.fn(),
+    child: vi.fn(),
+  }
+  // scope returns a scoped logger with the same shape
+  logger.scope.mockReturnValue(logger)
+  logger.child.mockReturnValue(logger)
+  return logger
+}
+
+type StubStash = {
+  start: ReturnType<typeof vi.fn>
+  get: ReturnType<typeof vi.fn>
+  cancel: ReturnType<typeof vi.fn>
+  list: ReturnType<typeof vi.fn>
+}
+
+function getCoordinatorStubs(): StubStash {
+  // The module-level fn references _startFn etc., shared across all mock instances.
+  return {
+    start: _startFn,
+    get: _getFn,
+    cancel: _cancelFn,
+    list: _listFn,
+  }
+}
+
+interface ProviderEnv {
+  readonly provider: IAddonsProvider
+  readonly psMock: Record<string, ReturnType<typeof vi.fn>>
+}
+
+function createProviderEnv(): ProviderEnv {
+  const psMock: Record<string, ReturnType<typeof vi.fn>> = {
+    getRollbackablePackages: vi.fn().mockReturnValue(new Set()),
+    getAddonHealthSnapshot: vi.fn().mockReturnValue([]),
+    listAllAddons: vi.fn().mockReturnValue([]),
+    listInstalled: vi.fn().mockReturnValue([]),
+    installAndLoad: vi.fn().mockResolvedValue({ success: true }),
+    installFromWorkspaceAndLoad: vi.fn().mockResolvedValue({ success: true }),
+    isWorkspaceAvailable: vi.fn().mockResolvedValue(false),
+    listWorkspacePackages: vi.fn().mockResolvedValue([]),
+    uninstallAndReload: vi.fn().mockResolvedValue({ success: true }),
+    reloadPackages: vi.fn().mockResolvedValue({ success: true }),
+    searchNpm: vi.fn().mockResolvedValue([]),
+    checkUpdates: vi.fn().mockResolvedValue([]),
+    checkUpdatesForInstalled: vi.fn().mockResolvedValue([]),
+    updatePackage: vi.fn().mockResolvedValue({ success: true }),
+    rollbackPackage: vi.fn().mockResolvedValue({ success: true }),
+    restartServer: vi.fn().mockResolvedValue({ success: true }),
+    listFrameworkPackages: vi.fn().mockResolvedValue([]),
+    getPackageVersions: vi.fn().mockResolvedValue([]),
+    getAutoUpdateSettings: vi.fn().mockResolvedValue({ channel: 'stable', intervalSeconds: 3600 }),
+    setAutoUpdateSettings: vi.fn().mockResolvedValue({ success: true }),
+    getAddonAutoUpdate: vi.fn().mockResolvedValue({ channel: 'inherit' }),
+    setAddonAutoUpdate: vi.fn().mockResolvedValue({ success: true }),
+    updateFrameworkPackage: vi.fn().mockResolvedValue({
+      packageName: '@camstack/types',
+      fromVersion: '0.1.38',
+      toVersion: '0.1.40',
+      restartingAt: Date.now() + 500,
+    }),
+    packPackage: vi.fn().mockResolvedValue({ buffer: Buffer.alloc(0), version: '1.0.0' }),
+  }
+
+  const arMock = {
+    listAddons: vi.fn().mockReturnValue([]),
+    listAllAddons: vi.fn().mockReturnValue([]),
+    getAddonHealthSnapshot: vi.fn().mockReturnValue([]),
+    getCapabilityRegistry: vi.fn().mockReturnValue({
+      listCapabilities: vi.fn().mockReturnValue([]),
+    }),
+    getCustomActionRegistry: vi.fn().mockReturnValue({
+      resolve: vi.fn().mockReturnValue(null),
+    }),
+    restartAddon: vi.fn().mockResolvedValue({ success: true }),
+    retryAddonLoad: vi.fn().mockResolvedValue({ success: true }),
+  }
+
+  const lsMock = {
+    createLogger: vi.fn().mockReturnValue(makeLogger()),
+    query: vi.fn().mockResolvedValue([]),
+    subscribe: vi.fn().mockReturnValue(() => {}),
+  }
+
+  const moleculerMock = {
+    broker: {
+      call: vi.fn().mockResolvedValue({}),
+    },
+  }
+
+  const configServiceMock = {}
+
+  const ebMock = {
+    emit: vi.fn(),
+    subscribe: vi.fn().mockReturnValue(() => {}),
+  }
+
+  const ctx = makeCtx('admin')
+
+  const provider = buildAddonsProvider(
+    arMock as never,
+    psMock as never,
+    lsMock as never,
+    moleculerMock as never,
+    configServiceMock as never,
+    ctx,
+    ebMock as never,
+  )
+
+  return { provider, psMock }
+}
+
+// ── Tests ─────────────────────────────────────────────────────────────────────
+
+describe('buildAddonsProvider — BulkUpdateCoordinator delegation', () => {
+  let env: ProviderEnv
+  let stubs: StubStash
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+    env = createProviderEnv()
+    stubs = getCoordinatorStubs()
+  })
+
+  it('startBulkUpdate delegates to coordinator.start with same args and returns its value', async () => {
+    const returnValue = { id: 'bulk-abc-123' }
+    stubs.start.mockReturnValue(returnValue)
+
+    const input = {
+      nodeId: 'hub',
+      items: [
+        { name: '@camstack/addon-stream-broker', version: '1.2.3', isSystem: false },
+        { name: '@camstack/types', version: '0.1.40', isSystem: true },
+      ] as const,
+    }
+
+    const result = await env.provider.startBulkUpdate(input)
+
+    expect(stubs.start).toHaveBeenCalledOnce()
+    expect(stubs.start).toHaveBeenCalledWith(input)
+    expect(result).toEqual(returnValue)
+  })
+
+  it('cancelBulkUpdate delegates to coordinator.cancel with the id and returns its value', async () => {
+    const returnValue = { cancelled: true }
+    stubs.cancel.mockReturnValue(returnValue)
+
+    const result = await env.provider.cancelBulkUpdate({ id: 'bulk-xyz' })
+
+    expect(stubs.cancel).toHaveBeenCalledOnce()
+    expect(stubs.cancel).toHaveBeenCalledWith('bulk-xyz')
+    expect(result).toEqual(returnValue)
+  })
+
+  it('getBulkUpdateState delegates to coordinator.get with the id and returns its value', async () => {
+    const mockState = {
+      id: 'bulk-abc',
+      nodeId: 'hub',
+      startedAtMs: 1000,
+      total: 2,
+      completed: 1,
+      failed: 0,
+      current: null,
+      phase: 'regular' as const,
+      cancelled: false,
+      items: [],
+    }
+    stubs.get.mockReturnValue(mockState)
+
+    const result = await env.provider.getBulkUpdateState({ id: 'bulk-abc' })
+
+    expect(stubs.get).toHaveBeenCalledOnce()
+    expect(stubs.get).toHaveBeenCalledWith('bulk-abc')
+    expect(result).toEqual(mockState)
+  })
+
+  it('getBulkUpdateState returns null when coordinator.get returns null', async () => {
+    stubs.get.mockReturnValue(null)
+
+    const result = await env.provider.getBulkUpdateState({ id: 'unknown-id' })
+
+    expect(result).toBeNull()
+  })
+
+  it('listActiveBulkUpdates delegates to coordinator.list with nodeId and returns its value', async () => {
+    const mockList = [
+      { id: 'bulk-1', nodeId: 'hub', startedAtMs: 1000, total: 1, completed: 0, failed: 0, current: 'pkg-a', phase: 'regular' as const, cancelled: false, items: [] },
+    ]
+    stubs.list.mockReturnValue(mockList)
+
+    const result = await env.provider.listActiveBulkUpdates({ nodeId: 'hub' })
+
+    expect(stubs.list).toHaveBeenCalledOnce()
+    expect(stubs.list).toHaveBeenCalledWith('hub')
+    expect(result).toEqual(mockList)
+  })
+
+  it('listActiveBulkUpdates passes undefined when nodeId is omitted', async () => {
+    stubs.list.mockReturnValue([])
+
+    await env.provider.listActiveBulkUpdates({})
+
+    expect(stubs.list).toHaveBeenCalledWith(undefined)
+  })
+})
+
+describe('buildAddonsProvider — listUpdates isSystem field', () => {
+  let env: ProviderEnv
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+    env = createProviderEnv()
+  })
+
+  it('adds isSystem: true for packages in FRAMEWORK_PACKAGE_ALLOWLIST', async () => {
+    const systemPkg = FRAMEWORK_PACKAGE_ALLOWLIST[0]!
+    env.psMock['checkUpdates']!.mockResolvedValue([
+      {
+        name: systemPkg,
+        currentVersion: '0.1.38',
+        latestVersion: '0.1.40',
+        category: 'core',
+        requiresRestart: true,
+      },
+    ])
+
+    const result = await env.provider.listUpdates({ nodeId: 'hub' })
+
+    expect(result).toHaveLength(1)
+    expect(result[0]!.name).toBe(systemPkg)
+    expect(result[0]!.isSystem).toBe(true)
+  })
+
+  it('adds isSystem: false for non-framework packages', async () => {
+    env.psMock['checkUpdates']!.mockResolvedValue([
+      {
+        name: '@camstack/addon-stream-broker',
+        currentVersion: '1.0.0',
+        latestVersion: '1.0.1',
+        category: 'addon',
+        requiresRestart: false,
+      },
+    ])
+
+    const result = await env.provider.listUpdates({ nodeId: 'hub' })
+
+    expect(result).toHaveLength(1)
+    expect(result[0]!.isSystem).toBe(false)
+  })
+
+  it('handles mixed system and non-system packages correctly', async () => {
+    env.psMock['checkUpdates']!.mockResolvedValue([
+      {
+        name: '@camstack/types',
+        currentVersion: '0.1.38',
+        latestVersion: '0.1.40',
+        category: 'core',
+        requiresRestart: true,
+      },
+      {
+        name: '@camstack/addon-foo',
+        currentVersion: '1.0.0',
+        latestVersion: '1.0.1',
+        category: 'addon',
+        requiresRestart: false,
+      },
+    ])
+
+    const result = await env.provider.listUpdates({ nodeId: 'hub' })
+
+    expect(result).toHaveLength(2)
+    const typesRow = result.find(r => r.name === '@camstack/types')
+    const fooRow = result.find(r => r.name === '@camstack/addon-foo')
+    expect(typesRow?.isSystem).toBe(true)
+    expect(fooRow?.isSystem).toBe(false)
+  })
+
+  it('all FRAMEWORK_PACKAGE_ALLOWLIST members get isSystem: true', async () => {
+    env.psMock['checkUpdates']!.mockResolvedValue(
+      FRAMEWORK_PACKAGE_ALLOWLIST.map(name => ({
+        name,
+        currentVersion: '0.1.0',
+        latestVersion: '0.1.1',
+        category: 'core',
+        requiresRestart: true,
+      })),
+    )
+
+    const result = await env.provider.listUpdates({ nodeId: 'hub' })
+
+    expect(result).toHaveLength(FRAMEWORK_PACKAGE_ALLOWLIST.length)
+    for (const row of result) {
+      expect(row.isSystem).toBe(true)
+    }
+  })
+})
+
+describe('buildAddonsProvider — updateFrameworkPackage deferRestart propagation', () => {
+  let env: ProviderEnv
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+    env = createProviderEnv()
+  })
+
+  it('forwards deferRestart: true to the service', async () => {
+    await env.provider.updateFrameworkPackage({
+      packageName: '@camstack/types',
+      version: '0.1.40',
+      deferRestart: true,
+    })
+
+    expect(env.psMock['updateFrameworkPackage']).toHaveBeenCalledOnce()
+    const callArg = env.psMock['updateFrameworkPackage']!.mock.calls[0]![0] as Record<string, unknown>
+    expect(callArg['deferRestart']).toBe(true)
+  })
+
+  it('forwards deferRestart: false to the service', async () => {
+    await env.provider.updateFrameworkPackage({
+      packageName: '@camstack/types',
+      version: '0.1.40',
+      deferRestart: false,
+    })
+
+    const callArg = env.psMock['updateFrameworkPackage']!.mock.calls[0]![0] as Record<string, unknown>
+    expect(callArg['deferRestart']).toBe(false)
+  })
+
+  it('does not include deferRestart when it is omitted', async () => {
+    await env.provider.updateFrameworkPackage({
+      packageName: '@camstack/types',
+      version: '0.1.40',
+    })
+
+    const callArg = env.psMock['updateFrameworkPackage']!.mock.calls[0]![0] as Record<string, unknown>
+    // Either undefined or not present — both are acceptable
+    expect(callArg['deferRestart']).toBeUndefined()
+  })
+})

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')
+  })
+})