@camstack/server 0.2.2 → 1.0.1

package/dist/core/moleculer/moleculer.service.js

@@ -0,0 +1,898 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MoleculerService = void 0;
+exports.buildChildUdsManifest = buildChildUdsManifest;
+const kernel_1 = require("@camstack/kernel");
+const cap_call_fn_js_1 = require("./cap-call-fn.js");
+const cap_route_authority_js_1 = require("./cap-route-authority.js");
+const types_1 = require("@camstack/types");
+const node_crypto_1 = require("node:crypto");
+class MoleculerService {
+    eventBus;
+    config;
+    logging;
+    capabilityService;
+    streamProbe;
+    broker;
+    /** Narrow-typed view of `this.broker` — see `BrokerLike` doc above. */
+    get brokerSafe() {
+        return this.broker;
+    }
+    logger;
+    /**
+     * D3 authority: union of every node's manifest delivered via
+     * `$hub.registerNode`. Populated by `onRegisterNode` in `hubDeps`.
+     */
+    nodeRegistry = new kernel_1.HubNodeRegistry();
+    nodeCallFns = new Map();
+    /**
+     * 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).
+     */
+    onAgentRegisteredCb = 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.
+     */
+    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.
+     */
+    clusterSecret;
+    /**
+     * UDS server that listens for addon-runners spawned by this hub node.
+     * `null` when the UDS server failed to start (children run broker-only).
+     */
+    localChildRegistry = 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.
+     */
+    udsRoutedCaps = new Set();
+    /**
+     * 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.
+     */
+    resolver = 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.
+     */
+    udsEventBridgeDispose = null;
+    get childRegistry() {
+        return this.localChildRegistry;
+    }
+    /** The CapRouteResolver once onModuleInit has completed; null before that. */
+    get capRouteResolver() {
+        return this.resolver;
+    }
+    /** This hub's Moleculer node id (e.g. `hub`). Hub-local forked children
+     *  register under `${nodeId}/${runnerId}`. */
+    get nodeId() {
+        return this.brokerSafe.nodeID;
+    }
+    constructor(eventBus, config, logging, capabilityService, streamProbe) {
+        this.eventBus = eventBus;
+        this.config = config;
+        this.logging = logging;
+        this.capabilityService = capabilityService;
+        this.streamProbe = streamProbe;
+        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('cluster.secret');
+        const broker = (0, kernel_1.createBroker)({
+            nodeID: 'hub',
+            mode: 'hub',
+            logLevel: this.config.get('moleculer.logLevel') ?? 'warn',
+            secret: this.clusterSecret,
+            ...(tcpPort && !Number.isNaN(tcpPort) ? { tcpPort } : {}),
+            ...(udpPort && !Number.isNaN(udpPort) ? { udpPort } : {}),
+        });
+        // `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;
+        this.readinessRegistry = new types_1.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) {
+        this.onAgentRegisteredCb = cb;
+    }
+    async onModuleInit() {
+        const logger = this.logging.createLogger('moleculer');
+        const hubDeps = {
+            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'];
+                if (appenders) {
+                    for (const appender of appenders) {
+                        appender.opts.level = level;
+                    }
+                }
+                const cache = factory['cache'];
+                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
+                ? (0, kernel_1.hashClusterSecret)(this.clusterSecret)
+                : undefined,
+        };
+        const hubService = (0, kernel_1.createHubService)(hubDeps);
+        this.brokerSafe.createService(hubService);
+        const dataDir = this.config.get('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;
+        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 = (0, kernel_1.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 }
+                        : undefined),
+                },
+            });
+            const registry = new kernel_1.LocalChildRegistry({
+                server: (0, kernel_1.createLocalTransport)().createServer(nodeId),
+                onUnownedCall,
+                logger: {
+                    info: (msg, meta) => logger.info(msg, meta !== null && meta !== undefined
+                        ? { meta: meta }
+                        : 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) => 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((0, kernel_1.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 = (0, kernel_1.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 = (0, kernel_1.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;
+        bridgeBus.localBus.on('$node.disconnected', ({ node }) => {
+            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.
+        (0, kernel_1.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((0, kernel_1.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((0, kernel_1.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((0, kernel_1.createHwAccelService)((0, kernel_1.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 kernel_1.CapRouteResolver({
+            hubNodeId: this.brokerSafe.nodeID,
+            broker: this.brokerSafe,
+            hubLocalRegistry: this.localChildRegistry,
+            nodeAuthority: (0, cap_route_authority_js_1.createNodeCapAuthority)(this.nodeRegistry, {
+                resolveSingleton: (capName, nodeId) => this.capabilityService.getRegistry()?.resolveSingletonAddonIdForNode(capName, nodeId) ??
+                    null,
+            }),
+            inProcessProviders: (0, cap_route_authority_js_1.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 = (0, kernel_1.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() {
+        this.brokerSafe.createService({
+            name: 'log-receiver',
+            actions: {
+                ingest: {
+                    handler: (ctx) => {
+                        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) {
+        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, capabilityName, methodName, params) {
+        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 = params !== null && typeof params === 'object' ? Reflect.get(params, 'deviceId') : undefined;
+            const routeDeviceId = 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 kernel_1.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(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 kernel_1.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.
+     */
+    onRegisterNode(params) {
+        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.
+     */
+    applyNodeManifest(params, previousManifest) {
+        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) => 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) => {
+            const keys = new Map();
+            for (const addon of manifest) {
+                const registryKey = registryKeyFor(addon.addonId);
+                for (const capName of addon.capabilities) {
+                    if ((0, kernel_1.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 = (0, cap_call_fn_js_1.buildCapCallFn)({
+                capName,
+                nodeId,
+                udsChildId,
+                getLocalChildRegistry: () => this.localChildRegistry,
+                getResolver: () => this.resolver,
+                legacyBrokerCall: (method, methodParams, targetNode) => (0, kernel_1.callWithServiceDiscovery)(this.brokerSafe, addonId, (0, kernel_1.capActionName)(addonId, capName, method, false), (0, kernel_1.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 = { id: addonId, nodeId };
+            for (const methodName of Object.keys((0, types_1.expandCapMethods)(capDef))) {
+                proxy[methodName] = (methodParams) => 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: (0, node_crypto_1.randomUUID)(),
+                    timestamp: new Date(),
+                    source: { type: 'addon', id: addonId },
+                    category: types_1.EventCategory.AddonPageReady,
+                    data: { addonId, nodeId },
+                });
+            }
+            if (capName === 'addon-widgets-source') {
+                this.eventBus.emit({
+                    id: (0, node_crypto_1.randomUUID)(),
+                    timestamp: new Date(),
+                    source: { type: 'addon', id: addonId },
+                    category: types_1.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.
+     */
+    removeNodeFromRegistry(nodeId) {
+        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}-${(0, node_crypto_1.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 {
+                    (0, types_1.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);
+    }
+    findCallFn(nodeId, capabilityName) {
+        // 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.
+     */
+    isReachableViaLegacy(nodeId, capabilityName) {
+        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, nodeId) {
+        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 kernel_1.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({}, {
+            get: (_target, methodName) => {
+                return (params) => 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() {
+        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) {
+        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, level) {
+        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() {
+        this.udsEventBridgeDispose?.();
+        this.udsEventBridgeDispose = null;
+        await this.brokerSafe.stop();
+        await this.localChildRegistry?.close();
+    }
+}
+exports.MoleculerService = MoleculerService;
+// ---------------------------------------------------------------------------
+// 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.
+ */
+function buildChildUdsManifest(nodeId, childId, caps) {
+    // Collect unique system (non-device-scoped) cap names.
+    const systemCapNames = new Set();
+    for (const cap of caps) {
+        if (cap.deviceId === undefined) {
+            systemCapNames.add(cap.capName);
+        }
+    }
+    const addons = [
+        { addonId: childId, capabilities: [...systemCapNames] },
+    ];
+    return { nodeId, addons };
+}