@camstack/server 1.0.0 → 1.0.1

package/src/core/moleculer/moleculer.service.ts

@@ -1,1072 +0,0 @@
-import { ServiceBroker, type Service, type ServiceSchema } from 'moleculer'
-
-/**
- * Narrow-typed view of the Moleculer surface this file actually uses.
- * Moleculer's published `.d.ts` chains through `eventemitter2` whose
- * package.json has no `types` field; typescript-eslint's `no-unsafe-*`
- * rules flag every `broker.X` access. Casting once at the boundary
- * collapses the rule violations into one documented narrowing.
- */
-interface BrokerLike {
-  readonly nodeID: string
-  readonly logger: Record<string, unknown>
-  start(): Promise<void>
-  stop(): Promise<void>
-  createService(svc: Service | unknown): unknown
-  call(action: string, params?: unknown, opts?: unknown): Promise<unknown>
-  waitForServices(services: string[], timeout?: number): Promise<unknown>
-}
-import {
-  createBroker,
-  createHubService,
-  createProcessService,
-  isInfraCapability,
-  registerEventBusService,
-  createReadinessServiceForRegistry,
-  createStreamProbeBrokerService,
-  createHwAccelService,
-  createKernelHwAccel,
-  HubNodeRegistry,
-  serializeTypedArrays,
-  callWithServiceDiscovery,
-  hashClusterSecret,
-  LocalChildRegistry,
-  createLocalTransport,
-  localEndpointPath,
-  CapRouteResolver,
-  CapRouteError,
-  capActionName,
-  udsChildLogToWorkerEntry,
-  createUdsEventBridge,
-  createParentUnownedCallHandler,
-} from '@camstack/kernel'
-import type {
-  HubServiceDeps,
-  CallFn,
-  RegisterNodeParams,
-  RegisteredAddonManifest,
-  ChildCapDescriptor,
-} from '@camstack/kernel'
-import { buildCapCallFn } from './cap-call-fn.js'
-import { createNodeCapAuthority, createInProcessProviderLookup } from './cap-route-authority.js'
-import { EventCategory, expandCapMethods, ReadinessRegistry, emitReadiness } from '@camstack/types'
-import type { CapabilityDefinition } from '@camstack/types'
-import { randomUUID } from 'node:crypto'
-import { EventBusService } from '../events/event-bus.service'
-import { ConfigService } from '../config/config.service'
-import { LoggingService } from '../logging/logging.service'
-import { CapabilityService } from '../capability/capability.service'
-import { StreamProbeService } from '../streaming/stream-probe.service'
-
-/**
- * Narrow-typed view of the Moleculer broker surface used by the
- * `$node.disconnected` listener — extends `BrokerLike` with `localBus`
- * so the handler can be fully typed (same pattern as agent-registry.service.ts).
- */
-interface BrokerWithLocalBus {
-  localBus: {
-    on(event: string, handler: (payload: { node: { id: string } }) => void): void
-  }
-}
-
-/**
- * One `(addon, capability)` pair that a node manifest applies onto the
- * CapabilityRegistry, with its resolved `CapabilityDefinition`. Built by
- * `applyNodeManifest`'s diff so the register loop never re-resolves the
- * cap def. Keyed in the diff map by `` `${registryKey}::${capName}` ``.
- */
-interface AppliedCapEntry {
-  readonly addonId: string
-  readonly capName: string
-  readonly capDef: CapabilityDefinition
-}
-
-export class MoleculerService {
-  readonly broker: ServiceBroker
-  /** Narrow-typed view of `this.broker` — see `BrokerLike` doc above. */
-  private get brokerSafe(): BrokerLike {
-    return this.broker as unknown as BrokerLike
-  }
-  private readonly logger: ReturnType<LoggingService['createLogger']>
-  /**
-   * D3 authority: union of every node's manifest delivered via
-   * `$hub.registerNode`. Populated by `onRegisterNode` in `hubDeps`.
-   */
-  private readonly nodeRegistry = new HubNodeRegistry()
-  private readonly nodeCallFns = new Map<string, CallFn>()
-  /**
-   * D3: callback invoked whenever a bare-ID agent node completes the
-   * `$hub.registerNode` handshake. Registered by `AgentRegistryService`
-   * via `setOnAgentRegistered()`. The handshake is the authoritative
-   * completeness signal — the hub has the full manifest at this point
-   * and reconciliation can run immediately (no grace delay needed).
-   */
-  private onAgentRegisteredCb: ((nodeId: string) => void) | null = null
-  /**
-   * Hub-side authoritative readiness registry. Subscribed to the
-   * shared `EventBusService` so it ingests both hub-local emits and
-   * remote emits forwarded via `$hub.event`. Exposed to:
-   *  - the `$readiness.getSnapshot` Moleculer action (consumed by
-   *    workers / agents on boot)
-   *  - `ctx.kernel.readinessRegistry` on every hub addon context so
-   *    hub consumers share the same snapshot.
-   */
-  readonly readinessRegistry: ReadinessRegistry
-  /**
-   * Resolved cluster secret (`CAMSTACK_CLUSTER_SECRET` env, else
-   * `cluster.secret` config), or `undefined` when none is configured.
-   * Threaded both into the broker factory and the hub's
-   * `expectedClusterSecretHash` so `$hub.registerNode` can gate on it.
-   */
-  private readonly clusterSecret: string | undefined
-  /**
-   * UDS server that listens for addon-runners spawned by this hub node.
-   * `null` when the UDS server failed to start (children run broker-only).
-   */
-  private localChildRegistry: LocalChildRegistry | null = null
-  /**
-   * Tracks cap names already logged as UDS-routed to avoid log spam.
-   * Cleared on no external event — one INFO line per distinct capName
-   * across the lifetime of the process.
-   */
-  private readonly udsRoutedCaps = new Set<string>()
-  /**
-   * CapRouteResolver — the single authority for cap dispatch routing.
-   * Constructed at the end of onModuleInit, once `localChildRegistry` is
-   * available and the broker has started. All cap dispatch flows through this.
-   */
-  private resolver: CapRouteResolver | null = null
-  /**
-   * Disposer returned by `createUdsEventBridge`. Called in `onModuleDestroy`
-   * to unsubscribe the bridge from the parent bus and clear the child-event
-   * handler, preventing subscriber leaks on shutdown.
-   */
-  private udsEventBridgeDispose: (() => void) | null = null
-
-  get childRegistry(): LocalChildRegistry | null {
-    return this.localChildRegistry
-  }
-
-  /** The CapRouteResolver once onModuleInit has completed; null before that. */
-  get capRouteResolver(): CapRouteResolver | null {
-    return this.resolver
-  }
-
-  /** This hub's Moleculer node id (e.g. `hub`). Hub-local forked children
-   *  register under `${nodeId}/${runnerId}`. */
-  get nodeId(): string {
-    return this.brokerSafe.nodeID
-  }
-
-  constructor(
-    private readonly eventBus: EventBusService,
-    private readonly config: ConfigService,
-    private readonly logging: LoggingService,
-    private readonly capabilityService: CapabilityService,
-    private readonly streamProbe: StreamProbeService,
-  ) {
-    this.logger = this.logging.createLogger('moleculer')
-    // Optional port overrides. Live primarily for the e2e harness: when
-    // a developer's dev:full is up on the default 6000/4445 ports, an
-    // isolated test hub can't reuse them. Production keeps the defaults
-    // so cluster discovery + agent-to-hub connections keep working
-    // without per-deploy config.
-    const tcpPortEnv = process.env['CAMSTACK_HUB_TCP_PORT']
-    const udpPortEnv = process.env['CAMSTACK_HUB_UDP_PORT']
-    const tcpPort = tcpPortEnv ? Number(tcpPortEnv) : undefined
-    const udpPort = udpPortEnv ? Number(udpPortEnv) : undefined
-    // Two-step cast: createBroker's dist `.d.ts` chains through
-    // moleculer→eventemitter2 whose types are unresolvable at this
-    // boundary, so the inference falls to `error` and trips
-    // `no-unsafe-assignment`. Going via `unknown` documents the boundary.
-    this.clusterSecret =
-      process.env['CAMSTACK_CLUSTER_SECRET'] ?? this.config.get<string>('cluster.secret')
-    const broker = createBroker({
-      nodeID: 'hub',
-      mode: 'hub',
-      logLevel: this.config.get<string>('moleculer.logLevel') ?? 'warn',
-      secret: this.clusterSecret,
-      ...(tcpPort && !Number.isNaN(tcpPort) ? { tcpPort } : {}),
-      ...(udpPort && !Number.isNaN(udpPort) ? { udpPort } : {}),
-    }) as unknown
-    // `ServiceBroker` itself surfaces as `error`-typed at this boundary
-    // (eventemitter2 chain unresolvable). Documented + single-site cast.
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
-    this.broker = broker as ServiceBroker
-    this.readinessRegistry = new ReadinessRegistry({
-      eventBus: this.eventBus,
-      sourceNodeId: this.brokerSafe.nodeID,
-      logger: this.logging.createLogger('readiness'),
-    })
-  }
-
-  /**
-   * D3: register the callback that fires when an agent node completes the
-   * `$hub.registerNode` handshake. Called by `AgentRegistryService` during
-   * its own `onModuleInit` — after `MoleculerService.onModuleInit` has
-   * returned, so the broker is already live. Option (b) direct-callback
-   * wiring: no event-bus round-trip needed for internal core wiring.
-   */
-  setOnAgentRegistered(cb: (nodeId: string) => void): void {
-    this.onAgentRegisteredCb = cb
-  }
-
-  async onModuleInit(): Promise<void> {
-    const logger = this.logging.createLogger('moleculer')
-
-    const hubDeps: HubServiceDeps = {
-      getAddonConfig: (addonId) => {
-        return this.config.getAddonConfig(addonId)
-      },
-      getSettings: (scope, key) => {
-        return this.config.get(key ? `${scope}.${key}` : scope)
-      },
-      getRecentEvents: (category, limit) => {
-        return this.eventBus.getRecent(category ? { category } : undefined, limit)
-      },
-      onLog: (entry) => {
-        this.logging.writeFromWorker({
-          addonId: entry.addonId,
-          nodeId: entry.nodeId,
-          level: entry.level,
-          message: entry.message,
-          ...(entry.scope !== undefined ? { scope: entry.scope } : {}),
-          ...(entry.tags ? { tags: entry.tags } : {}),
-          ...(entry.meta ? { meta: entry.meta } : {}),
-        })
-      },
-      onSetLogLevel: (level) => {
-        const factory = this.brokerSafe.logger
-        const appenders = factory['appenders'] as Array<{ opts: { level: string } }> | undefined
-        if (appenders) {
-          for (const appender of appenders) {
-            appender.opts.level = level
-          }
-        }
-        const cache = factory['cache'] as Map<string, unknown> | undefined
-        if (cache) {
-          cache.clear()
-        }
-        logger.info('Moleculer log level changed', { meta: { level } })
-        this.brokerSafe.call('$process.setLogLevel', { level }).catch(() => {})
-      },
-      // D3: registration-handshake path. Nodes send $hub.registerNode with
-      // their complete capability manifest; the hub applies it immediately.
-      onRegisterNode: (params) => {
-        this.onRegisterNode(params)
-      },
-      onUnregisterNode: (nodeId) => {
-        this.removeNodeFromRegistry(nodeId)
-      },
-      expectedClusterSecretHash: this.clusterSecret
-        ? hashClusterSecret(this.clusterSecret)
-        : undefined,
-    }
-
-    const hubService: unknown = createHubService(hubDeps)
-    this.brokerSafe.createService(hubService)
-
-    const dataDir = this.config.get<string>('dataDir') ?? 'camstack-data'
-
-    // UDS local transport: the hub hosts a LocalChildRegistry so its
-    // forked addon-runners route cap calls directly over a Unix-domain
-    // socket instead of through Moleculer. The broker stays available as
-    // the no-route fallback (remote agents + caps no local child owns).
-    // If the registry fails to start, children transparently fall back to
-    // broker-only — no parentUdsPath is propagated.
-    let parentUdsPath: string | undefined
-    try {
-      const nodeId = this.brokerSafe.nodeID
-      // F0 (slice-5 outbound): when a forked child issues `ctx.api.<cap>` for a
-      // cap NO local sibling owns, route it from the PARENT and return the
-      // result over UDS — resolver-first, broker-fallback. Closes over `this`
-      // so it reads `this.resolver` at CALL time (the resolver is constructed
-      // later in onModuleInit, after broker.start()). The broker fallback
-      // reaches the hub's core `$`-infra services (`$core-caps`, `$stream-probe`,
-      // settings-store, …) that are Moleculer services, NOT registered
-      // capabilities the resolver can see. Before F0 this fell through
-      // UDS_NO_ROUTE → the child's own brokerTransportLink; F1+F2 removes that
-      // child broker, so the parent must own this path.
-      const onUnownedCall = createParentUnownedCallHandler({
-        getResolver: () => this.resolver,
-        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment -- moleculer types unresolvable; see `broker` getter docstring
-        broker: this.broker,
-        // Single capability authority — lets the broker fallback pin a
-        // device-scoped call to its owning node instead of load-balancing it.
-        nodeRegistry: this.nodeRegistry,
-        // Hub-local UDS child dispatcher — routes a device-scoped native cap
-        // owned by a hub-local child (reolink/hikvision cameras) directly over
-        // UDS before any broker fallback. Getter: `this.localChildRegistry` is
-        // assigned later in this method, after the handler is constructed.
-        getLocalDispatcher: () => this.localChildRegistry,
-        // Device-native signal for the registration-race recovery: a forked
-        // child's device-native cap (e.g. `switch` on an export target) can be
-        // briefly absent from the LocalChildRegistry just after a respawn. The
-        // kernel layer has no cap registry, so feed it the `deviceNative` flag
-        // from the cap definition. When true + binding-not-yet-registered, the
-        // handler retries the hub-local route then throws a precise error rather
-        // than the unroutable broker fallback (`switch.switch.getStatus`).
-        isDeviceNativeCap: (capName) =>
-          this.capabilityService.getRegistry()?.getDefinition(capName)?.deviceNative === true,
-        logger: {
-          warn: (msg, meta) =>
-            logger.warn(
-              msg,
-              meta !== null && meta !== undefined
-                ? { meta: meta as Record<string, unknown> }
-                : undefined,
-            ),
-        },
-      })
-      const registry = new LocalChildRegistry({
-        server: createLocalTransport().createServer(nodeId),
-        onUnownedCall,
-        logger: {
-          info: (msg, meta) =>
-            logger.info(
-              msg,
-              meta !== null && meta !== undefined
-                ? { meta: meta as Record<string, unknown> }
-                : undefined,
-            ),
-        },
-        // Hand the UDS-routing layer a view into the operator's
-        // active-singleton preference. Without this, when two local
-        // children own the same singleton cap (e.g. two `webrtc-session`
-        // providers), routing returns
-        // the first-registered child by insertion order — silently
-        // bypassing `setActiveSingleton`. The closure reads the live
-        // registry on every call so a runtime swap takes effect
-        // immediately without rebuilding the resolver snapshot.
-        getActiveSingletonAddonId: (capName: string): string | null =>
-          this.capabilityService.getRegistry()?.getSingletonAddonId(capName) ?? null,
-      })
-      await registry.start()
-      // E1: apply child manifest + cleanup from the UDS lifecycle (hub-local children).
-      // When a runner connects over UDS, apply its cap descriptors to the
-      // CapabilityRegistry — same effect as the `$hub.registerNode` RPC for
-      // `hub/<runner>` nodes. This runs in PARALLEL with the RPC path until
-      // Phase F removes the child broker; `onRegisterNode`'s diff logic ensures
-      // double-apply is idempotent (same nodeId + same caps → no-op on the second call).
-      registry.onChildRegistered((child) => {
-        const hubNodeId = this.brokerSafe.nodeID
-        const nodeId = `${hubNodeId}/${child.childId}`
-        const params = buildChildUdsManifest(nodeId, child.childId, child.caps)
-        this.onRegisterNode(params)
-        logger.info('UDS child registered — manifest applied', { meta: { nodeId } })
-      })
-      // E1: cleanup on child disconnect — same effect as `$node.disconnected`
-      // for hub-local children. The Moleculer path stays for AGENT nodes.
-      registry.onChildGone((childId) => {
-        const hubNodeId = this.brokerSafe.nodeID
-        const nodeId = `${hubNodeId}/${childId}`
-        logger.info('UDS child gone — removing from registry', { meta: { childId } })
-        this.removeNodeFromRegistry(nodeId)
-      })
-      // B2: ingest UDS child logs into the hub's LoggingService so they appear
-      // in the LogManager / admin-UI log stream alongside broker-forwarded logs.
-      // This runs in PARALLEL with the existing $hub.log / onLog broker path —
-      // both stay active until Phase F removes the broker path.
-      registry.onChildLog((childId, entry) => {
-        this.logging.writeFromWorker(udsChildLogToWorkerEntry(childId, entry))
-      })
-      // D1: answer readiness-snapshot requests from UDS children so they can
-      // hydrate without a `$readiness.getSnapshot` Moleculer call.
-      // `this.readinessRegistry` is the hub-authoritative instance subscribed
-      // to the shared EventBusService — same source `$readiness.getSnapshot` uses.
-      // The handler is a live closure (calls `getSnapshotForTransport()` on each
-      // request) so children always receive the current snapshot, not a stale copy.
-      // Keep `$readiness.getSnapshot` intact — Phase F removes it.
-      registry.onReadinessSnapshotRequest(() => this.readinessRegistry.getSnapshotForTransport())
-      this.localChildRegistry = registry
-      parentUdsPath = localEndpointPath(nodeId)
-      logger.info('UDS child registry listening', { meta: { path: parentUdsPath } })
-    } catch (err) {
-      logger.warn('UDS child registry failed to start; children stay broker-only', {
-        meta: { err: err instanceof Error ? err.message : String(err) },
-      })
-    }
-
-    const processService: unknown = createProcessService(
-      this.brokerSafe.nodeID,
-      dataDir,
-      undefined,
-      undefined,
-      parentUdsPath,
-    )
-    this.brokerSafe.createService(processService)
-
-    // $addonHost — REMOVED (Sprint 6). Three-level settings are now
-    // served by the `addon-settings` singleton capability. Per-addon
-    // Moleculer services expose `settings.*` actions for remote agents.
-
-    // D3: mirror $node.disconnected onto the registry path so nodes that
-    // sent a $hub.registerNode manifest get cleaned up on disconnect.
-    const bridgeBus = this.broker as unknown as BrokerWithLocalBus
-    bridgeBus.localBus.on('$node.disconnected', ({ node }: { node: { id: string } }) => {
-      this.removeNodeFromRegistry(node.id)
-    })
-
-    // Register the $event-bus service BEFORE broker.start(). Moleculer
-    // announces service subscriptions to remote nodes only during discovery
-    // handshake, not dynamically after post-start `createService()`.
-    // Without this, cross-node broadcasts (camstack.evt.<category>) would
-    // arrive unreliably for the first ~10s after each node joins.
-    registerEventBusService(this.broker)
-
-    // Register the hub-authoritative `$readiness.getSnapshot` service
-    // BEFORE broker.start() so workers / agents see it in their initial
-    // INFO packet — post-start `createService` calls propagate via
-    // heartbeat (several seconds) and would force workers to poll.
-    this.brokerSafe.createService(createReadinessServiceForRegistry(this.readinessRegistry))
-
-    // Register the hub-authoritative `$stream-probe` service —
-    // workers route RTSP probe + field-probe through this action when
-    // the tRPC WSS link isn't available (default path for forked
-    // workers). Keeps ffprobe + HTTP-reachability as a single
-    // hub-side implementation; see `createStreamProbeBrokerService`
-    // for the shape.
-    this.brokerSafe.createService(
-      createStreamProbeBrokerService({
-        probe: (url, options) => this.streamProbe.probe(url, options),
-        probeField: (key, value) => this.streamProbe.probeField(key, value),
-      }),
-    )
-
-    // Register `$hwaccel` on hub — every node in the cluster does the
-    // same so `broker.call('$hwaccel.resolve', params, { nodeID })`
-    // returns the backend list for whichever host the caller targets.
-    // Admin UI uses this to show per-agent hwaccel info on the
-    // pipeline / NodeDetail pages.
-    this.brokerSafe.createService(createHwAccelService(createKernelHwAccel()))
-
-    await this.brokerSafe.start()
-    logger.info('Moleculer broker started (TCP transport)')
-
-    // Construct the CapRouteResolver now that both the broker and
-    // localChildRegistry are ready. The resolver reads live registry state
-    // via closure accessors on every call (not a frozen snapshot), so new
-    // children connecting/disconnecting after this point are picked up
-    // correctly. The localChildRegistry reference is captured and may be
-    // null if UDS failed to start.
-    this.resolver = new CapRouteResolver({
-      hubNodeId: this.brokerSafe.nodeID,
-      broker: this.brokerSafe,
-      hubLocalRegistry: this.localChildRegistry,
-      nodeAuthority: createNodeCapAuthority(this.nodeRegistry, {
-        resolveSingleton: (capName, nodeId) =>
-          this.capabilityService.getRegistry()?.resolveSingletonAddonIdForNode(capName, nodeId) ??
-          null,
-      }),
-      inProcessProviders: createInProcessProviderLookup(this.capabilityService),
-    })
-
-    // Wire the hub's EventBusService into the broker so hub-addon
-    // emissions fan out to every remote process via
-    // `camstack.evt.<category>`, and incoming $event-bus events land on
-    // the same local bus that subscribers already use. The
-    // EventBusService's `emit` override handles the "only broadcast
-    // locally-originated events" guard, and id-based dedup absorbs the
-    // duplicate delivery when `createBrokerEventBus` on a remote uses
-    // both broadcast + `$hub.event` for back-compat.
-    this.eventBus.attachBroker(this.broker)
-
-    // C2: wire the UDS ↔ Moleculer event bridge so events emitted by UDS
-    // children fan to siblings and reach the cluster, and cluster / parent-
-    // local events propagate to every UDS child. Inert when no children
-    // are connected (bridge just adds a no-op bus subscriber). The bridge
-    // is wired after attachBroker so the parentBus is backed by the real
-    // shared broker bus and broker.broadcast is live.
-    if (this.localChildRegistry !== null) {
-      const hubNodeId = this.brokerSafe.nodeID
-      this.udsEventBridgeDispose = createUdsEventBridge({
-        registry: this.localChildRegistry,
-        parentBus: this.eventBus,
-        parentNodeId: hubNodeId,
-      })
-    }
-  }
-
-  /**
-   * Register the log-receiver service for agent log forwarding.
-   * Must be called AFTER app.init() so Moleculer re-advertises
-   * the updated service list to the network.
-   */
-  registerLogReceiver(): void {
-    this.brokerSafe.createService({
-      name: 'log-receiver',
-      actions: {
-        ingest: {
-          handler: (ctx: {
-            params: {
-              level: string
-              message: string
-              addonId: string
-              nodeId: string
-              scope?: string
-              tags?: import('@camstack/types').LogTags
-              meta?: Record<string, unknown>
-            }
-          }) => {
-            this.logging.writeFromWorker({
-              addonId: ctx.params.addonId,
-              nodeId: ctx.params.nodeId,
-              level: ctx.params.level,
-              message: ctx.params.message,
-              ...(ctx.params.scope !== undefined ? { scope: ctx.params.scope } : {}),
-              ...(ctx.params.tags ? { tags: ctx.params.tags } : {}),
-              ...(ctx.params.meta ? { meta: ctx.params.meta } : {}),
-            })
-            return true
-          },
-        },
-      },
-    })
-  }
-
-  /**
-   * Register the `$core-caps` Moleculer service that bridges the hub's
-   * core (non-addon) tRPC routers onto the cluster mesh.
-   *
-   * Called from `main.ts` after the appRouter is built — that happens
-   * after `app.init()`, so the broker is already started. Post-start
-   * `createService` is fine: the service propagates to remote nodes via
-   * heartbeat and `brokerTransportLink` polls discovery, so forked
-   * addons and late-joining agents still resolve `ctx.api.<coreCap>`.
-   * `registerLogReceiver` relies on the same post-init registration.
-   */
-  registerCoreCapService(service: ServiceSchema): void {
-    this.brokerSafe.createService(service)
-  }
-
-  /**
-   * Call a capability method on a specific node.
-   *
-   * Delegates all routing decisions to the CapRouteResolver, which classifies
-   * the (capName, nodeId) pair into a typed CapRoute and dispatches to the
-   * appropriate transport (hub-in-process, hub-local-uds, remote-moleculer,
-   * agent-child-forward). A genuinely-absent cap throws CapRouteError (typed,
-   * with reason + rejected routes) instead of the old opaque error string.
-   *
-   * Falls back to the legacy findCallFn path when the resolver is not yet
-   * constructed (before onModuleInit completes) or when the resolver throws a
-   * no-provider / node-offline error for a node that IS in nodeCallFns — this
-   * handles the window between registerNode applying a callFn and the resolver
-   * seeing the new node (the resolver reads live registry state via closure
-   * accessors, but nodeCallFns is populated by applyNodeManifest which may
-   * have run before the resolver was constructed).
-   */
-  async callCapabilityOnNode(
-    nodeId: string,
-    capabilityName: string,
-    methodName: string,
-    params: unknown,
-  ): Promise<unknown> {
-    const resolver = this.resolver
-    if (resolver !== null) {
-      // Extract deviceId from params so device-scoped native caps (ptz, motion-zones, …)
-      // resolve through the resolver's deviceId-aware snapshot instead of falling back to
-      // the legacy callFn store. The deviceId hint is a number extracted from the method args.
-      const rawDeviceId: unknown =
-        params !== null && typeof params === 'object' ? Reflect.get(params, 'deviceId') : undefined
-      const routeDeviceId: number | undefined =
-        typeof rawDeviceId === 'number' ? rawDeviceId : undefined
-      try {
-        const route = resolver.resolveCapRoute(capabilityName, { nodeId, deviceId: routeDeviceId })
-        return await resolver.dispatch(route, methodName, params)
-      } catch (err) {
-        if (
-          err instanceof CapRouteError &&
-          (err.reason === 'no-provider' || err.reason === 'node-offline')
-        ) {
-          // Resolver couldn't find the cap — try the legacy callFn store as a
-          // fallback. This covers caps registered in nodeCallFns (e.g. agent
-          // nodes that registered before the resolver's snapshot was built or
-          // caps that the resolver's nodeAuthority doesn't see yet because the
-          // resolver reads live registry state via closure accessors).
-          // Device-scoped native caps now resolve via the resolver (M1/M5 thread deviceId),
-          // so this fallback only handles genuinely-transitional stale-snapshot windows.
-          const callFn = this.findCallFn(nodeId, capabilityName)
-          if (callFn !== undefined) {
-            return callFn(methodName, params)
-          }
-        }
-        // Rethrow — includes transport-failed and all other errors
-        throw err
-      }
-    }
-
-    // Pre-init fallback (resolver not yet constructed — before onModuleInit).
-    // This path is only reachable in tests that drive onRegisterNode without
-    // calling onModuleInit first.
-    if (nodeId === 'hub' || nodeId === this.brokerSafe.nodeID) {
-      const registry = this.capabilityService.getRegistry()
-      const provider = registry?.getSingleton<Record<string, unknown>>(capabilityName) ?? null
-      if (provider !== null) {
-        const fn = provider[methodName]
-        if (typeof fn !== 'function')
-          throw new Error(`Method "${methodName}" not found on "${capabilityName}"`)
-        return fn.call(provider, params)
-      }
-    }
-
-    const callFn = this.findCallFn(nodeId, capabilityName)
-    if (callFn) {
-      return callFn(methodName, params)
-    }
-
-    throw new CapRouteError(capabilityName, methodName, {
-      reason: 'no-provider',
-      nodeId,
-      rejected: [
-        { kind: 'hub-in-process', why: 'CapRouteResolver not initialised (pre-onModuleInit)' },
-      ],
-    })
-  }
-
-  /**
-   * D3 registration-handshake entrypoint — invoked by the `$hub.registerNode`
-   * Moleculer action (wired through `hubDeps.onRegisterNode`).
-   *
-   * Captures the node's PREVIOUS manifest before `nodeRegistry.registerNode`
-   * overwrites it, then hands both manifests to `applyNodeManifest` so the
-   * CapabilityRegistry update is a diff (atomic replace) rather than an
-   * unconditional re-register — see `applyNodeManifest` for the rationale.
-   */
-  private onRegisterNode(params: RegisterNodeParams): void {
-    const previousManifest = this.nodeRegistry.getNodeManifest(params.nodeId)
-    this.nodeRegistry.registerNode(params)
-    this.applyNodeManifest(params, previousManifest)
-    // Notify AgentRegistryService to reconcile placement for bare-ID
-    // agent nodes (no '/' = not a hub child worker, not the hub itself).
-    // The handshake is the authoritative completeness signal — the full
-    // manifest is available here so reconciliation runs without delay.
-    const { nodeId } = params
-    if (nodeId !== 'hub' && !nodeId.includes('/') && this.onAgentRegisteredCb) {
-      this.onAgentRegisteredCb(nodeId)
-    }
-  }
-
-  /**
-   * D3: apply a node's registered manifest onto the CapabilityRegistry.
-   * Builds a method proxy for each capability — same registryKey rule
-   * (local child → bare addonId, remote agent → addonId@nodeId), same
-   * `broker.call` routing shape, same `expandCapMethods` method surface.
-   *
-   * Called from `onRegisterNode` whenever a node handshakes.
-   *
-   * Diff-based / idempotent: the D3 protocol legitimately re-handshakes (a
-   * node re-sends its COMPLETE manifest — e.g. the post-device-restore
-   * `nativeCaps` re-handshake). `registerProvider` throws on a duplicate
-   * `(cap, addonId)` pair, so a blind re-register would throw on every
-   * re-handshake and trip the registering node's retry loop into a storm.
-   * Instead this diffs the NEW manifest against `previousManifest`:
-   * unchanged caps are left untouched, dropped caps are unregistered, new
-   * caps are registered. This honours the invariant "`registerNode`
-   * replaces the node's entire cap set atomically".
-   *
-   * NOTE: `params.nativeCaps` is stored by `nodeRegistry.registerNode()`
-   * already; this method handles only `params.addons` (system caps).
-   * Native-cap wiring into device-manager is done in a later task.
-   */
-  private applyNodeManifest(
-    params: RegisterNodeParams,
-    previousManifest?: readonly RegisteredAddonManifest[],
-  ): void {
-    const { nodeId, addons } = params
-    const hubNodeId = this.brokerSafe.nodeID
-    const isLocalChild = nodeId.startsWith(hubNodeId + '/')
-    const isHubInProcess = nodeId === hubNodeId
-
-    // Hub in-process addons register themselves during initialize() — skip.
-    if (isHubInProcess) return
-
-    const registry = this.capabilityService.getRegistry()
-    if (!registry) return
-
-    // Same registryKey rule as CapabilityBridge / onProviderConnected:
-    //   local child → bare addonId (one instance per forked child)
-    //   remote agent → addonId@nodeId (unique per agent node)
-    // `nodeId` is identical for the previous and new manifest (same node
-    // re-handshaking), so the rule resolves the same key on both sides.
-    const registryKeyFor = (addonId: string): string =>
-      isLocalChild ? addonId : `${addonId}@${nodeId}`
-
-    // Collect the `(registryKey, capName)` pairs a manifest would APPLY —
-    // applying the SAME `isInfraCapability` skip and `capDef` existence
-    // check the register block below uses, so the set reflects exactly
-    // what is (or would have been) registered. Keyed `${registryKey}::${capName}`.
-    // The resolved `capDef` is carried through so the register loop never
-    // re-looks it up (and never needs a non-null assertion).
-    const appliedKeys = (
-      manifest: readonly RegisteredAddonManifest[],
-    ): Map<string, AppliedCapEntry> => {
-      const keys = new Map<string, AppliedCapEntry>()
-      for (const addon of manifest) {
-        const registryKey = registryKeyFor(addon.addonId)
-        for (const capName of addon.capabilities) {
-          if (isInfraCapability(capName)) continue
-          const capDef = registry.getDefinition(capName)
-          if (!capDef) continue
-          keys.set(`${registryKey}::${capName}`, { addonId: addon.addonId, capName, capDef })
-        }
-      }
-      return keys
-    }
-
-    const desired = appliedKeys(addons)
-    const previous = appliedKeys(previousManifest ?? [])
-
-    // ── UNREGISTER ── caps the previous manifest applied but the new one
-    // does not. Quiet — readiness is driven by `$node.connected/disconnected`,
-    // not by a re-handshake, so no readiness events here.
-    for (const [key, { addonId, capName }] of previous) {
-      if (desired.has(key)) continue
-      registry.unregisterProvider(capName, registryKeyFor(addonId))
-      this.nodeCallFns.delete(`${nodeId}::${capName}`)
-    }
-
-    // ── REGISTER ── caps the new manifest applies that the previous one
-    // did not. Caps present in BOTH sets are left untouched — zero churn,
-    // no duplicate `registerProvider`, no spurious page/widget re-emit.
-    for (const [key, { addonId, capName, capDef }] of desired) {
-      if (previous.has(key)) continue
-
-      const registryKey = registryKeyFor(addonId)
-
-      // The runner id (= UDS childId) for a hub-local forked child is the
-      // trailing segment of its nodeId `${hubNodeId}/${runnerId}`. Only
-      // hub-local children are reachable over UDS; agent-hosted providers
-      // (`<agent>/<runner>`) fall through to Moleculer.
-      const udsChildId = isLocalChild ? nodeId.slice(hubNodeId.length + 1) : null
-
-      // Per-(cap,node) dispatcher. Routing lives in the unit-tested
-      // `buildCapCallFn` (see cap-call-fn.ts):
-      //   - hub-local child → per-child UDS (collection-safe; keyed by runner
-      //     id, never by capName which would collapse a COLLECTION cap onto
-      //     the first child). Fails fast if the child isn't providing — NEVER
-      //     a Moleculer fallback, since a hub-local child is not a Moleculer
-      //     service (a broker call would hang the full discovery timeout).
-      //   - agent-hosted / remote → the unified `CapRouteResolver`, which
-      //     classifies an agent node as `agent-child-forward` (hub→agent→UDS
-      //     child) and a direct remote as `remote-moleculer`. This closes the
-      //     UDS-migration gap where this dispatcher hand-rolled a `broker.call`
-      //     to an agent that exposes no Moleculer service for the cap.
-      //   - resolver not yet built (pre-init) → legacy Moleculer call.
-      const callFn: CallFn = buildCapCallFn({
-        capName,
-        nodeId,
-        udsChildId,
-        getLocalChildRegistry: () => this.localChildRegistry,
-        getResolver: () => this.resolver,
-        legacyBrokerCall: (method, methodParams, targetNode) =>
-          callWithServiceDiscovery(
-            this.brokerSafe,
-            addonId,
-            capActionName(addonId, capName, method, false),
-            serializeTypedArrays(methodParams),
-            { nodeID: targetNode, timeout: 60_000 },
-          ),
-        onUdsRoute: (cap) => {
-          if (!this.udsRoutedCaps.has(cap)) {
-            this.udsRoutedCaps.add(cap)
-            this.logger.info('routing cap over UDS', { meta: { capName: cap } })
-          }
-        },
-      })
-
-      const proxy: Record<string, unknown> = { id: addonId, nodeId }
-      for (const methodName of Object.keys(expandCapMethods(capDef))) {
-        proxy[methodName] = (methodParams: unknown) => callFn(methodName, methodParams)
-      }
-      registry.registerProvider(capName, registryKey, proxy)
-
-      // Local-first singleton preference (UDS regression fix). A
-      // `placement: 'any-node'` singleton (e.g. `pipeline-executor`) can
-      // register on BOTH the hub-local forked child and a remote agent.
-      // `CapabilityRegistry` keeps the FIRST-registered provider active, so a
-      // race could leave the REMOTE agent proxy active — and its callFn routes
-      // over Moleculer to a UDS-only agent runner that no longer hosts the
-      // Moleculer service ("not found on <agent>"). The hub-local provider is
-      // reachable over UDS, so prefer it whenever the current active is absent
-      // or remote (`@`-keyed). Never steals from another local provider, so an
-      // operator's binding choice (a bare-key local provider) is preserved.
-      if (capDef.mode === 'singleton' && isLocalChild) {
-        const activeKey = registry.getSingletonAddonId(capName)
-        if (activeKey === null || activeKey.includes('@')) {
-          registry.setSingletonActiveAddon(capName, registryKey)
-        }
-      }
-
-      // Emit AddonPageReady / AddonWidgetReady so the admin-UI sidebar
-      // refreshes its page/widget registry for cross-process addons.
-      if (capName === 'addon-pages-source') {
-        this.eventBus.emit({
-          id: randomUUID(),
-          timestamp: new Date(),
-          source: { type: 'addon', id: addonId },
-          category: EventCategory.AddonPageReady,
-          data: { addonId, nodeId },
-        })
-      }
-      if (capName === 'addon-widgets-source') {
-        this.eventBus.emit({
-          id: randomUUID(),
-          timestamp: new Date(),
-          source: { type: 'addon', id: addonId },
-          category: EventCategory.AddonWidgetReady,
-          data: { addonId, nodeId },
-        })
-      }
-
-      // Store callFn so `callCapabilityOnNode` and `createCapabilityProxy`
-      // can reach manifest-registered nodes.
-      this.nodeCallFns.set(`${nodeId}::${capName}`, callFn)
-    }
-  }
-
-  /**
-   * D3: remove a node's manifest from the CapabilityRegistry on disconnect.
-   * Unregisters every cap the node's last manifest declared and emits
-   * synthetic readiness-down events for each.
-   */
-  private removeNodeFromRegistry(nodeId: string): void {
-    const manifest = this.nodeRegistry.getNodeManifest(nodeId)
-    if (!manifest) return // node never sent a handshake — nothing to do
-
-    const hubNodeId = this.brokerSafe.nodeID
-    const isLocalChild = nodeId.startsWith(hubNodeId + '/')
-    const disconnectGen = `disconnect-${nodeId}-${randomUUID()}`
-    const agentNodeId = nodeId.includes('/') ? nodeId.split('/')[0]! : nodeId
-
-    const registry = this.capabilityService.getRegistry()
-
-    for (const addon of manifest) {
-      const { addonId, capabilities } = addon
-      const registryKey = isLocalChild ? addonId : `${addonId}@${nodeId}`
-
-      if (registry) {
-        for (const capName of capabilities) {
-          registry.unregisterProvider(capName, registryKey)
-        }
-      }
-
-      for (const capName of capabilities) {
-        this.nodeCallFns.delete(`${nodeId}::${capName}`)
-
-        try {
-          emitReadiness(this.eventBus, {
-            capName,
-            scope: { type: 'node', nodeId: agentNodeId },
-            state: 'down',
-            generation: disconnectGen,
-            sourceNodeId: hubNodeId,
-          })
-        } catch (err) {
-          this.logger.warn('Failed to emit synthetic readiness down', {
-            tags: { addonId, nodeId },
-            meta: { capName, err: err instanceof Error ? err.message : String(err) },
-          })
-        }
-      }
-    }
-
-    this.nodeRegistry.removeNode(nodeId)
-  }
-
-  private findCallFn(nodeId: string, capabilityName: string): CallFn | undefined {
-    // Exact match first — direct hit when the caller knows the full
-    // nodeId (e.g. `hub/detection-pipeline`) or when the cap is hosted
-    // on a bare top-level node (remote agent with in-process addons).
-    const direct = this.nodeCallFns.get(`${nodeId}::${capabilityName}`)
-    if (direct) return direct
-    // Prefix fallback: forkable addons register under
-    // `<parent>/<processName>` (e.g. `dev-agent-0/detection-pipeline`).
-    // UI callers typically pass the bare parent nodeId (`dev-agent-0`)
-    // because that's what they get from AgentOnline events and the
-    // orchestrator assignments. Resolve by finding any registered node
-    // whose id starts with `<nodeId>/` and hosts the cap.
-    const prefix = `${nodeId}/`
-    for (const key of this.nodeCallFns.keys()) {
-      const sep = key.lastIndexOf('::')
-      if (sep < 0) continue
-      const keyNode = key.slice(0, sep)
-      const keyCap = key.slice(sep + 2)
-      if (keyCap !== capabilityName) continue
-      if (keyNode.startsWith(prefix)) return this.nodeCallFns.get(key)
-    }
-    return undefined
-  }
-
-  /**
-   * Returns true when a (nodeId, capabilityName) pair is reachable via the
-   * legacy fallback paths: either a stored callFn in nodeCallFns, or a
-   * hub-local forked child that is reachable over UDS (even without a
-   * manifest callFn — e.g. device-scoped native caps). Used by
-   * createCapabilityProxy to decide whether to build a proxy when the
-   * CapRouteResolver cannot find a route.
-   */
-  private isReachableViaLegacy(nodeId: string, capabilityName: string): boolean {
-    if (this.findCallFn(nodeId, capabilityName) !== undefined) return true
-    return this.localChildRegistry !== null && nodeId.startsWith(`${this.brokerSafe.nodeID}/`)
-  }
-
-  /**
-   * Build a proxy object that forwards every method call on a capability
-   * to the correct transport via CapRouteResolver. Returns null if the
-   * capability is provably not reachable on that node (resolver says no-provider
-   * AND no legacy callFn exists AND it is not a hub-local child).
-   *
-   * Used by the generated cap routers when a request includes a `nodeId` field
-   * for transparent node routing.
-   *
-   * Hub-local forked children (e.g. `hub/provider-reolink`) are reachable over
-   * UDS even when no manifest callFn exists — device-scoped NATIVE caps (ptz,
-   * motion-zones) aren't in `applyNodeManifest`'s callFn store. The proxy is
-   * built unconditionally for hub-local children so `callCapabilityOnNode` can
-   * route the actual method call via the resolver's hub-local-uds branch.
-   */
-  createCapabilityProxy(
-    capabilityName: string,
-    nodeId: string,
-  ): Record<string, (params: unknown) => Promise<unknown>> | null {
-    const resolver = this.resolver
-    if (resolver !== null) {
-      // Use the resolver to determine reachability. If it resolves a route, we
-      // can build a proxy. If it throws no-provider but a legacy callFn exists
-      // or the node is a hub-local child (for native caps), build the proxy anyway
-      // because callCapabilityOnNode's fallback will handle it at dispatch time.
-      try {
-        resolver.resolveCapRoute(capabilityName, { nodeId })
-        // Resolver found a route — proxy is reachable.
-      } catch (err) {
-        if (
-          err instanceof CapRouteError &&
-          (err.reason === 'no-provider' || err.reason === 'node-offline')
-        ) {
-          // Check legacy callFn store and hub-local child fallbacks.
-          if (!this.isReachableViaLegacy(nodeId, capabilityName)) return null
-          // Proxy reachable via fallback paths — fall through to build it.
-        } else {
-          throw err
-        }
-      }
-    } else {
-      // Pre-init: use legacy reachability check.
-      if (!this.isReachableViaLegacy(nodeId, capabilityName)) return null
-    }
-
-    // Build a dynamic proxy: every property access returns a function that
-    // routes the call through callCapabilityOnNode (which delegates to the resolver).
-    return new Proxy<Record<string, (params: unknown) => Promise<unknown>>>(
-      {},
-      {
-        get: (_target, methodName: string) => {
-          return (params: unknown): Promise<unknown> =>
-            this.callCapabilityOnNode(nodeId, capabilityName, methodName, params)
-        },
-      },
-    )
-  }
-
-  /**
-   * D3 handshake-fed native-cap view of the whole cluster.
-   * Returns every `(nodeId, addonId, capName, deviceId)` tuple stored by
-   * `onRegisterNode` — updated atomically each time a node re-handshakes
-   * (e.g. after device restore completes). Used by `device-manager.addon.ts`
-   * as a reliable fallback when push-based `DeviceBindingsChanged` events
-   * were lost in the Moleculer transport handshake window.
-   *
-   * NOT a Moleculer action — only the hub process calls this directly
-   * through the `ctx.kernel.listClusterNativeCaps` injection.
-   */
-  listClusterNativeCaps(): readonly import('@camstack/kernel').NodeNativeCapEntry[] {
-    return this.nodeRegistry.listNativeCapEntries()
-  }
-
-  /**
-   * Per-device slice of {@link listClusterNativeCaps}, served from the
-   * registry's `deviceId → entries` index — O(caps-for-device). Used by the
-   * per-device `getBindings` hot path so `getAllBindings` doesn't flatten the
-   * whole cluster once per device.
-   */
-  listClusterNativeCapsForDevice(
-    deviceId: number,
-  ): readonly import('@camstack/kernel').NodeNativeCapEntry[] {
-    return this.nodeRegistry.listNativeCapEntriesForDevice(deviceId)
-  }
-
-  /**
-   * E2: Send a `set-log-level` UDS message to a hub-local child identified by
-   * `nodeId` (e.g. `hub/provider-reolink`). Extracts the `childId` from the
-   * nodeId and delegates to `LocalChildRegistry.setChildLogLevel`.
-   *
-   * Returns `true` only if the nodeId is a hub-local child (`hub/<childId}`) AND
-   * the child is currently connected to the LocalChildRegistry (the UDS message
-   * was emitted). Returns `false` when the nodeId is not a hub-local child, the
-   * registry is absent, or the child is not yet/no longer connected — in all
-   * three cases the caller (setProcessLogLevel in cap-providers.ts) falls back
-   * to the Moleculer `$node-mgmt.setLogLevel` action.
-   */
-  setChildLogLevelByNodeId(nodeId: string, level: string): boolean {
-    const hubNodeId = this.brokerSafe.nodeID
-    if (!nodeId.startsWith(`${hubNodeId}/`)) return false
-    const childId = nodeId.slice(hubNodeId.length + 1)
-    const registry = this.localChildRegistry
-    if (registry === null) return false
-    return registry.setChildLogLevel(childId, level)
-  }
-
-  async onModuleDestroy(): Promise<void> {
-    this.udsEventBridgeDispose?.()
-    this.udsEventBridgeDispose = null
-    await this.brokerSafe.stop()
-    await this.localChildRegistry?.close()
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Module-level helpers
-// ---------------------------------------------------------------------------
-
-/**
- * E1: Adapt a child's UDS `ChildCapDescriptor[]` (which has no `addonId`) into
- * a `RegisterNodeParams` that `onRegisterNode` / `applyNodeManifest` can consume.
- *
- * Strategy: use `childId` as the synthetic `addonId`. For currently-shipped addons
- * `childId = runnerId = addonId` (one-addon-one-process, no shared group), so the
- * `registryKey = childId` produced here matches what the Moleculer `$hub.registerNode`
- * path uses — making double-apply via both paths fully idempotent.
- *
- * Singleton vs. device-scoped caps: `ChildCapDescriptor.deviceId` is present only
- * for device-scoped native caps. The `addons` array carries system (singleton/collection)
- * cap names; device-scoped native caps are handled separately via `nativeCaps` in the
- * full `RegisterNodeParams`. For the parallel-window phase (E1), we populate only
- * the `addons` portion — the Moleculer path carries `nativeCaps` on the re-handshake.
- *
- * TODO(co-location): This function synthesises ONE manifest entry with `addonId = childId`
- * (the runner id). This is correct under the current one-addon-one-process invariant
- * where `childId = runnerId = addonId`. If `execution.group` co-location is ever
- * activated (multiple addons sharing one runner), a single runner would host multiple
- * addonIds but this function would register all their caps under one synthetic addonId —
- * collapsing distinct provider registryKeys into one and breaking per-addon routing.
- * Multi-addon manifest support (splitting the `ChildCapDescriptor[]` by addonId once the
- * protocol carries addonId) would be needed here before enabling co-location post-Phase-F.
- */
-export function buildChildUdsManifest(
-  nodeId: string,
-  childId: string,
-  caps: readonly ChildCapDescriptor[],
-): RegisterNodeParams {
-  // Collect unique system (non-device-scoped) cap names.
-  const systemCapNames = new Set<string>()
-  for (const cap of caps) {
-    if (cap.deviceId === undefined) {
-      systemCapNames.add(cap.capName)
-    }
-  }
-  const addons: readonly RegisteredAddonManifest[] = [
-    { addonId: childId, capabilities: [...systemCapNames] },
-  ]
-  return { nodeId, addons }
-}