@camstack/server 0.1.5 → 0.1.7

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

@@ -16,8 +16,10 @@ interface BrokerLike {
   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 } from '@camstack/kernel'
-import type { HubServiceDeps, CallFn, RegisterNodeParams, RegisteredAddonManifest } from '@camstack/kernel'
+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'
@@ -86,6 +88,44 @@ export class MoleculerService {
    * `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,
@@ -193,7 +233,86 @@ export class MoleculerService {
     this.brokerSafe.createService(hubService)
 
     const dataDir = this.config.get<string>('dataDir') ?? 'camstack-data'
-    const processService: unknown = createProcessService(this.brokerSafe.nodeID, dataDir)
+
+    // 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,
+        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),
+        },
+      })
+      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
@@ -241,6 +360,23 @@ export class MoleculerService {
     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
@@ -250,6 +386,21 @@ export class MoleculerService {
     // 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,
+      })
+    }
   }
 
   /**
@@ -306,8 +457,20 @@ export class MoleculerService {
 
   /**
    * Call a capability method on a specific node.
-   * Hub: calls the local provider directly (same process, no Moleculer overhead).
-   * Remote: routes through the stored Moleculer CallFn for that 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,
@@ -315,34 +478,59 @@ export class MoleculerService {
     methodName: string,
     params: unknown,
   ): Promise<unknown> {
-    // Hub — call local provider directly when registered on hub root.
-    // For caps hosted in a per-addon runner (e.g. 'hub/detection-pipeline'),
-    // the hub root registry has nothing; we then fall through to the
-    // remote findCallFn prefix lookup which routes to the subnode.
+    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(capabilityName) as Record<string, unknown> | null
-      if (provider) {
+      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 as (p: unknown) => unknown).call(provider, params)
+        return fn.call(provider, params)
       }
-      // Fall through to the prefix-fallback findCallFn below.
     }
 
-    // Remote — find stored callFn. The closure already captures the
-    // FULL nodeId at registration time (e.g. `dev-agent-1/detection-pipeline`
-    // for forkable addons). Passing the caller's `nodeId` here as the
-    // 3rd arg would override the closure's capture with the bare parent
-    // prefix (`dev-agent-1`), which Moleculer doesn't know about → the
-    // call fails with "Service not found on '<prefix>' node". Omit it
-    // so the closure routes to the correct worker node.
     const callFn = this.findCallFn(nodeId, capabilityName)
     if (callFn) {
       return callFn(methodName, params)
     }
 
-    throw new Error(`Capability "${capabilityName}" not available on node "${nodeId}"`)
+    throw new CapRouteError(capabilityName, methodName, {
+      reason: 'no-provider',
+      nodeId,
+      rejected: [{ kind: 'hub-in-process', why: 'CapRouteResolver not initialised (pre-onModuleInit)' }],
+    })
   }
 
   /**
@@ -450,18 +638,46 @@ export class MoleculerService {
 
       const registryKey = registryKeyFor(addonId)
 
-      // Build a callFn that routes through Moleculer, matching the shape
-      // produced by CapabilityBridge: service name = addonId, action path
-      // = `<addonId>.<capName>.<method>`, nodeID = the registering node.
-      const callFn: CallFn =
-        (method: string, methodParams: unknown, targetNodeId?: string) =>
+      // 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,
-            `${addonId}.${capName}.${method}`,
+            capActionName(addonId, capName, method, false),
             serializeTypedArrays(methodParams),
-            { nodeID: targetNodeId ?? nodeId, timeout: 60_000 },
-          )
+            { 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))) {
@@ -469,6 +685,23 @@ export class MoleculerService {
       }
       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') {
@@ -570,19 +803,60 @@ export class MoleculerService {
   }
 
 
+  /**
+   * 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 a remote node via Moleculer. Returns null if the capability is not
-   * reachable on that node. Used by the generated cap routers when a
-   * request includes a `nodeId` field for transparent node routing.
+   * 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 {
-    // Check if we can reach this capability on the target node
-    const callFn = this.findCallFn(nodeId, capabilityName)
-    if (!callFn) return 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
-    // calls the remote capability method via the stored callFn.
+    // 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> =>
@@ -606,7 +880,77 @@ export class MoleculerService {
     return this.nodeRegistry.listNativeCapEntries()
   }
 
+  /**
+   * 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 }
 }

package/src/main.ts

@@ -201,6 +201,7 @@ async function bootstrap() {
     const uploadAddonBridge = app.get(AddonBridgeService);
     const uploadMoleculer = app.get(MoleculerService);
     const uploadAddonRegistry = app.get(AddonRegistryService);
+    const uploadAddonPackage = app.get(AddonPackageService);
     const uploadLogger = app.get(LoggingService).createLogger("addon-upload");
     await registerAddonUploadRoute(
       fastify,
@@ -208,6 +209,7 @@ async function bootstrap() {
       uploadAuthService,
       uploadMoleculer,
       uploadAddonRegistry,
+      uploadAddonPackage,
       uploadLogger,
     );
     console.log(
@@ -907,11 +909,16 @@ async function bootstrap() {
       const indexPath = path.join(staticDir, "index.html");
       if (fs.existsSync(staticDir) && fs.existsSync(indexPath)) {
         spaIndexHtml = indexPath;
+        // `serve: false` registers no route — it only decorates
+        // `reply.sendFile`, so the single SPA `/*` handler below owns all
+        // routing and serves each asset LIVE from the current `staticDir`.
+        // The old `wildcard: false` registered one route per file enumerated
+        // AT BOOT, so a redeployed admin-ui's new content-hashed assets had no
+        // route and 404'd until a hub restart. Live `sendFile` removes that.
         await fastify.register(fastifyStatic, {
           root: staticDir,
-          prefix: "/",
-          wildcard: false,
-          decorateReply: false,
+          serve: false,
+          decorateReply: true,
         });
         // Dev diagnostic: serve webrtc-test.html from dataPath if it exists.
         const webrtcTestPath = path.join(dataPath, "webrtc-test.html");
@@ -921,8 +928,9 @@ async function bootstrap() {
           });
         }
 
-        // SPA fallback: catch-all route that serves index.html for non-API paths.
-        // Uses a wildcard route instead of setNotFoundHandler.
+        // SPA fallback + live static serving: this single catch-all owns every
+        // GET. Core API prefixes fall through to their own routers via
+        // `callNotFound`. Uses a wildcard route instead of setNotFoundHandler.
         fastify.get("/*", async (request, reply) => {
           const url = request.url;
           if (
@@ -933,17 +941,42 @@ async function bootstrap() {
           ) {
             return reply.callNotFound();
           }
-          // A request whose last path segment has a file extension is a
-          // static asset, not a SPA navigation route. If it reached here,
-          // `fastify-static` has no route for it — the file is missing.
-          // Return 404 instead of the SPA `index.html`: serving HTML under
-          // an asset URL makes upstream caches (Cloudflare, the browser)
-          // pin `text/html` for a `.js`/`.css` URL, which then fails the
-          // module MIME check long after the file is actually available.
+          // A request whose last path segment has a file extension is a static
+          // asset: serve it LIVE from the current dist so a redeployed
+          // admin-ui's new content-hashed files are picked up without a hub
+          // restart. When the file is missing, 404 — never the SPA
+          // `index.html`: serving HTML under a `.js`/`.css` URL makes upstream
+          // caches (Cloudflare, the browser) pin `text/html`, which then fails
+          // the module MIME check long after the file is actually available.
           const pathOnly = url.split("?")[0] ?? url;
           if (/\.[a-zA-Z0-9]+$/.test(pathOnly)) {
+            const rel = pathOnly.replace(/^\/+/, "");
+            const abs = path.join(staticDir, rel);
+            if (
+              (abs === staticDir || abs.startsWith(staticDir + path.sep)) &&
+              fs.existsSync(abs)
+            ) {
+              // Cache policy that lets PWA updates actually propagate (the
+              // stale-bundle bug): the service worker + registration + manifest
+              // MUST be revalidated every load or a redeploy never reaches the
+              // client (the SW keeps serving the old precache). Content-hashed
+              // build assets (assets/index-<hash>.js) are immutable. Everything
+              // else gets a short cache.
+              const base = rel.split("/").pop() ?? rel;
+              if (/^(sw\.js|registerSW\.js|workbox-.*\.js|manifest\.webmanifest)$/.test(base)) {
+                reply.header("cache-control", "no-cache, must-revalidate");
+              } else if (rel.startsWith("assets/") && /-[A-Za-z0-9_-]{8,}\./.test(base)) {
+                reply.header("cache-control", "public, max-age=31536000, immutable");
+              } else {
+                reply.header("cache-control", "no-cache");
+              }
+              return reply.sendFile(rel);
+            }
             return reply.callNotFound();
           }
+          // index.html (the SPA shell) must never be cached — it references the
+          // content-hashed bundles, so a stale copy pins the old app forever.
+          reply.header("cache-control", "no-cache, must-revalidate");
           return reply.type("text/html").send(fs.createReadStream(spaIndexHtml!));
         });
         const { version } = await adminUI.getVersion();