@camstack/server 0.1.6 → 0.1.8

package/src/core/addon/addon-registry.service.ts

@@ -1,6 +1,7 @@
 /* eslint-disable @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-argument, @typescript-eslint/no-unsafe-return, @typescript-eslint/no-unsafe-member-access -- pre-existing lint debt across this 2200-line orchestration class. The flagged sites (StorageService.setLocationManager / setSettingsBackend, LoggingService.addDestination, RouteRegistry, etc.) are typed as `unknown` by their owning services to break circular construction-order dependencies; runtime contracts are validated structurally. Tracked separately; do not amend in unrelated edits. */
 import * as os from "node:os";
 import { ConfigService } from "../config/config.service";
+import { overlayDeclaration } from "./addon-row-manifest";
 import { LoggingService } from "../logging/logging.service";
 import { EventBusService } from "../events/event-bus.service";
 import { StorageService } from "../storage/storage.service";
@@ -60,12 +61,13 @@ import type {
   IStorageProvider as INewStorageProvider,
   ISettingsBackend,
 } from "@camstack/types";
-import { AddonRouteRegistry } from "@camstack/core";
+import { AddonRouteRegistry, DataPlaneRegistry } from "@camstack/core";
 import { randomUUID } from "node:crypto";
 import * as path from "node:path";
 import * as fs from "node:fs";
 import { pathToFileURL } from "node:url";
 import { createAddonSettingsProvider } from "./addon-settings-provider.js";
+import { AddonCallGateway } from "./addon-call-gateway.js";
 import { addonSettingsCapability } from "@camstack/types";
 import { DisposerChain } from "@camstack/types";
 
@@ -111,6 +113,110 @@ function isSettingsStore(
   return true;
 }
 
+/**
+ * The bridge-dispatch contract on an `addon-routes` provider. The operator-
+ * facing `IAddonRouteProvider` interface declares only `id` + `getRoutes`; the
+ * UDS proxy (and `buildAddonRouteProvider`) also expose `invoke`, which the
+ * forked-routes bridge calls per request. Narrowed via `isAddonRoutesInvoker`.
+ */
+interface AddonRoutesInvoker {
+  invoke(
+    input: import("@camstack/types").AddonRouteInvokeRequest,
+  ): Promise<import("@camstack/types").AddonRouteReplyEnvelope>;
+}
+
+/** Structural guard: true when an `addon-routes` provider also exposes `invoke`. */
+function isAddonRoutesInvoker<T extends object>(
+  provider: T,
+): provider is T & AddonRoutesInvoker {
+  return typeof Reflect.get(provider, "invoke") === "function";
+}
+
+const ROUTE_METHODS: readonly import("@camstack/types").IAddonHttpRoute["method"][] = [
+  "GET",
+  "POST",
+  "PUT",
+  "DELETE",
+];
+const ROUTE_ACCESS: readonly import("@camstack/types").RouteAccess[] = [
+  "public",
+  "authenticated",
+  "admin",
+];
+
+function asRouteMethod(value: string): import("@camstack/types").IAddonHttpRoute["method"] {
+  const upper = value.toUpperCase();
+  for (const m of ROUTE_METHODS) if (m === upper) return m;
+  throw new Error(`addon-routes: unsupported HTTP method "${value}"`);
+}
+
+function asRouteAccess(value: unknown): import("@camstack/types").RouteAccess {
+  if (typeof value === "string") {
+    for (const a of ROUTE_ACCESS) if (a === value) return a;
+  }
+  // Default to the most restrictive sensible default the original mount used.
+  return "public";
+}
+
+/**
+ * Parse the wire-boundary `unknown` returned by `callAddonOnChild(...,
+ * {target:'routes'})` into typed route descriptors. The child sends route
+ * descriptors WITHOUT handlers (functions don't cross MsgPack); only
+ * `method`/`path`/`access`/`description` are present.
+ */
+interface ParsedRouteDescriptor {
+  readonly method: import("@camstack/types").IAddonHttpRoute["method"];
+  readonly path: string;
+  readonly access: import("@camstack/types").RouteAccess;
+  readonly description?: string;
+}
+
+function parseSerializableRouteDescriptors(raw: unknown): readonly ParsedRouteDescriptor[] {
+  if (!Array.isArray(raw)) {
+    throw new Error("addon-routes: child returned a non-array route descriptor set");
+  }
+  return raw.map((entry: unknown): ParsedRouteDescriptor => {
+    if (entry === null || typeof entry !== "object") {
+      throw new Error("addon-routes: route descriptor is not an object");
+    }
+    const method = Reflect.get(entry, "method");
+    const path = Reflect.get(entry, "path");
+    if (typeof method !== "string" || typeof path !== "string") {
+      throw new Error("addon-routes: route descriptor missing method/path");
+    }
+    const description = Reflect.get(entry, "description");
+    return {
+      method: asRouteMethod(method),
+      path,
+      access: asRouteAccess(Reflect.get(entry, "access")),
+      ...(typeof description === "string" ? { description } : {}),
+    };
+  });
+}
+
+/**
+ * Parse the wire-boundary `unknown` from `callForked(..., {target:'data-planes'})`
+ * into typed data-plane endpoint descriptors (`prefix/access/baseUrl/secret`).
+ * Pure data — the addon's `ctx.dataPlane` facility produced them.
+ */
+function parseDataPlaneEndpoints(raw: unknown): readonly import("@camstack/types").AddonDataPlaneEndpoint[] {
+  if (!Array.isArray(raw)) {
+    throw new Error("data-planes: child returned a non-array endpoint set");
+  }
+  return raw.map((entry: unknown): import("@camstack/types").AddonDataPlaneEndpoint => {
+    if (entry === null || typeof entry !== "object") {
+      throw new Error("data-planes: endpoint descriptor is not an object");
+    }
+    const prefix = Reflect.get(entry, "prefix");
+    const baseUrl = Reflect.get(entry, "baseUrl");
+    const secret = Reflect.get(entry, "secret");
+    if (typeof prefix !== "string" || typeof baseUrl !== "string" || typeof secret !== "string") {
+      throw new Error("data-planes: endpoint descriptor missing prefix/baseUrl/secret");
+    }
+    return { prefix, access: asRouteAccess(Reflect.get(entry, "access")), baseUrl, secret };
+  });
+}
+
 interface AddonEntry {
   readonly addon: ICamstackAddon;
   initialized: boolean;
@@ -140,6 +246,8 @@ interface AddonEntry {
 export class AddonRegistryService {
   private readonly addonEntries = new Map<string, AddonEntry>();
   private readonly capabilityRegistry: CapabilityRegistry;
+  /** Single router for addon-level calls (routes / custom / settings). */
+  private addonCallGateway!: AddonCallGateway;
   // Task 7.1: hub-wide registry of addon custom actions. Populated on
   // each addon's initialize() (in-process path); Task 7.2 will dispatch
   // through this from the `api.addons.custom` tRPC procedure.
@@ -156,6 +264,7 @@ export class AddonRegistryService {
   private addonLoader!: AddonLoader;
   private healthMonitor!: AddonHealthMonitor;
   private addonRouteRegistry: AddonRouteRegistry | null = null;
+  private dataPlaneRegistry: DataPlaneRegistry | null = null;
 
   // Broker-routed AddonApi proxy — every addon's `ctx.api` resolves
   // to this. Calls go through `broker.call('${addonId}.${capName}.${method}')`
@@ -272,6 +381,24 @@ export class AddonRegistryService {
       },
     );
 
+    this.capabilityRegistry.setNodeConfigReader(
+      (capability: string, nodeId: string): string | undefined => {
+        try {
+          return (
+            this.configService.get<string>(
+              `capabilities.singletonNode.${capability}.${nodeId}`,
+            ) ?? undefined
+          );
+        } catch (err) {
+          this.logger.debug(
+            'settings-store not wired yet during early boot',
+            { meta: { capability, nodeId, error: errMsg(err) } },
+          );
+          return undefined;
+        }
+      },
+    );
+
     // Collection-provider enable/disable persistence. Reads the same
     // `capabilities.collection.<cap>` ConfigService key the `capabilities`
     // router writes (`JSON.stringify({ disabled: string[] })`), so a
@@ -341,29 +468,33 @@ export class AddonRegistryService {
     // former `$addonHost` Moleculer service. The provider resolves
     // addonId → local addon instance (hub) or remote Moleculer call.
     this.capabilityRegistry.declareCapability(addonSettingsCapability);
-    const settingsProvider = createAddonSettingsProvider({
-      getAddon: (addonId) => {
-        const entry = this.addonEntries.get(addonId);
-        return entry?.addon ?? null;
-      },
+    // The SINGLE router for addon-level calls (routes / custom / settings).
+    // It classifies in-process | hub-local-child (UDS) | remote-agent
+    // (Moleculer) in ONE place — `resolveNode` reports only the BASE node
+    // (the hub for every hub-local addon, forked or not); the gateway's
+    // `isChildKnown` distinguishes a forked UDS child from an in-process
+    // builtin. This is the fix for forked-addon settings: they were forced
+    // down a dead `<addonId>.settings.*` Moleculer path because the old
+    // `resolveNode` marked them non-local; now they route over UDS like
+    // their routes + custom-actions already do.
+    this.addonCallGateway = new AddonCallGateway({
+      hubNodeId: this.broker.nodeID,
       resolveNode: (addonId) => {
-        // Group-runner addons live in a child Moleculer node (e.g.
-        // `hub/pipeline`). The hub-side `entry.addon` instance never
-        // runs `initialize()` and has no `_ctx.settings`, so calling
-        // `addon.getGlobalSettings()` on it returns defaults only —
-        // the real store lives in the worker. Route those via the
-        // remote path so the worker's `<addonId>.settings.*` handler
-        // serves the canonical response.
         const entry = this.addonEntries.get(addonId);
-        if (entry?.declaration && entry.addonDir) {
-          const runnerId = resolveRunnerId(entry.declaration, addonId);
-          return `${this.broker.nodeID}/${runnerId}`;
-        }
-        return "hub";
+        // Every addon in `addonEntries` is hub-local — report the hub node;
+        // forked-vs-in-process is decided by `isChildKnown` in the gateway.
+        return entry ? this.broker.nodeID : "hub";
       },
+      getChildRegistry: () => this.moleculer.childRegistry,
       // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment -- moleculer types unresolvable; see `broker` getter docstring
       broker: this.moleculer.broker,
-      hubNodeId: this.broker.nodeID,
+    });
+    const settingsProvider = createAddonSettingsProvider({
+      getAddon: (addonId) => {
+        const entry = this.addonEntries.get(addonId);
+        return entry?.addon ?? null;
+      },
+      gateway: this.addonCallGateway,
     });
     this.capabilityRegistry.registerProvider(
       "addon-settings",
@@ -487,38 +618,97 @@ export class AddonRegistryService {
 
     // Native-cap cross-process bridge: when a hub consumer resolves a native
     // provider for a device whose IDevice lives in a forked worker, we
-    // return a broker proxy that routes calls to
-    // `<addonId>.native-provider.<capName>.<method>` via standard Moleculer RPC.
+    // return a proxy that routes calls to the correct transport.
     //
-    // The resolver keys off `(capName, deviceId)`, NOT device ownership.
-    // An addon can own a device without registering every conceivable cap
-    // natively (e.g. RtspCamera without `snapshotUrl` does not publish a
-    // snapshot provider). Synthesizing a proxy against the device owner
-    // would point at a Moleculer service that was never mounted and make
-    // every call throw "service not found" at runtime.
+    // G2 — single ownership authority: the CapRouteResolver is consulted FIRST
+    // for hub-local native caps. If the resolver's snapshot identifies a
+    // hub-local-uds route for (capName, deviceId), we build the proxy directly —
+    // no `resolveNativeCapOwnerSync` consult needed for this branch. The resolver's
+    // `hubLocalChildProvides(capName, deviceId)` is the canonical hub-local authority
+    // (fed by the same LocalChildRegistry that owns UDS dispatch), so the old
+    // `owner.nodeId.startsWith(hubNodeId + '/')` gate is replaced by the resolver's
+    // own verdict.
     //
-    // `resolveNativeCapOwnerSync` consults both hub-local native
-    // registrations and `remoteNativeCaps` (populated via
-    // DeviceBindingsChanged events emitted by every worker). It returns
-    // null when no provider published the cap for that device — the
-    // fallback surfaces that as null so wrappers cleanly fall through to
-    // whatever secondary strategy they own (e.g. snapshot → ffmpeg frame
-    // grab), instead of throwing against a phantom service.
+    // `resolveNativeCapOwnerSync` is only consulted for the REMOTE branch: when the
+    // resolver throws no-provider for the hub node (no hub-local-uds child owns the cap),
+    // the fallback queries `resolveNativeCapOwnerSync` to find a remote owner. That
+    // method carries data (push-fed `remoteNativeCaps` from `DeviceBindingsChanged`
+    // events) that the resolver's `NodeCapAuthority` doesn't see, so it stays as the
+    // remote-branch source. If `resolveNativeCapOwnerSync` also returns null, the cap
+    // genuinely has no cross-process provider and the fallback returns null — wrappers
+    // cleanly fall through to their own secondary strategy.
     {
       const { buildNativeCapProxy } = await import("@camstack/kernel");
       // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment -- moleculer types unresolvable; see `broker` getter docstring
       const broker = this.moleculer.broker;
       this.capabilityRegistry.setNativeFallback(
         (capName: string, deviceId: number): unknown | null => {
+          const resolver = this.moleculer.capRouteResolver;
+          const hubNodeId = this.moleculer.nodeId;
+
+          // 1. Hub-local path: the resolver's hub-local-child authority is the
+          //    single source of truth for whether a forked hub-local UDS child
+          //    owns (capName, deviceId) — via hubLocalChildProvides +
+          //    getHubLocalChildId (both deviceId-aware, M1).
+          //
+          //    We deliberately use `resolveHubLocalUdsRoute`, NOT
+          //    `resolveCapRoute`: this fallback's contract is to reach the
+          //    NATIVE provider in the forked vendor child. `resolveCapRoute`
+          //    gives Priority 1 to `hub-in-process`, so a cap that ALSO has an
+          //    in-hub provider for the same name (a wrapper — today `snapshot`)
+          //    would classify as `hub-in-process` (the wrapper) and never reach
+          //    the hub-local-uds native. That made the wrapper's
+          //    `getNativeProvider` return null and silently fall through to its
+          //    secondary strategy (e.g. snapshot's ffmpeg frame grab), so the
+          //    vendor native snapshot was never invoked. `resolveHubLocalUdsRoute`
+          //    skips the in-process branch and returns the native child route.
+          if (resolver !== null) {
+            const route = resolver.resolveHubLocalUdsRoute(capName, deviceId)
+            if (route !== null) {
+              const childId = route.childId
+              const target: Record<string, (input: unknown) => Promise<unknown>> = {}
+              return new Proxy(target, {
+                get(_target, property): ((input: unknown) => Promise<unknown>) | undefined {
+                  if (typeof property !== 'string') return undefined
+                  return (input: unknown): Promise<unknown> => {
+                    const mergedInput =
+                      typeof input === 'object' && input !== null
+                        ? { ...input, deviceId }
+                        : { deviceId }
+                    // Re-resolve at call time so a child that respawned under a
+                    // new runner id is still reachable (route is cheap to build).
+                    const r = resolver.resolveHubLocalUdsRoute(capName, deviceId)
+                      ?? { kind: 'hub-local-uds' as const, capName, childId }
+                    return resolver.dispatch(r, property, mergedInput)
+                  }
+                },
+              })
+            }
+            // No hub-local child owns (capName, deviceId). Fall through to the
+            // remote branch — resolveNativeCapOwnerSync is still consulted there
+            // and may find a remote owner for this (capName, deviceId).
+          }
+
+          // 2. Remote path: resolver has no hub-local route for this (capName, deviceId).
+          //    Consult resolveNativeCapOwnerSync — it includes push-fed remoteNativeCaps
+          //    (DeviceBindingsChanged events from forked workers) that the resolver's
+          //    NodeCapAuthority (backed by HubNodeRegistry) doesn't carry.
           const dm = this.capabilityRegistry.getSingleton<{
             resolveNativeCapOwnerSync?: (
               capName: string,
               deviceId: number,
             ) => { addonId: string; nodeId: string } | null;
           }>("device-manager");
-          const owner =
-            dm?.resolveNativeCapOwnerSync?.(capName, deviceId) ?? null;
+          const owner = dm?.resolveNativeCapOwnerSync?.(capName, deviceId) ?? null;
           if (!owner) return null;
+
+          // Guard: skip hub-local owners here — they were already handled (or skipped
+          // because the resolver was null / not initialised yet). Returning null avoids
+          // building a Moleculer proxy that points at a UDS-only child.
+          if (owner.nodeId.startsWith(`${hubNodeId}/`)) return null;
+
+          // Remote native cap → Moleculer with native-provider infix.
+          // buildNativeCapProxy uses the action `${addonId}.native-provider.${cap}.${method}`.
           return buildNativeCapProxy(broker, owner.addonId, capName, deviceId);
         },
       );
@@ -864,6 +1054,41 @@ export class AddonRegistryService {
     this.addonRouteRegistry = registry;
   }
 
+  /** Set the DataPlaneRegistry the hub's `/addon/:id/*` dispatch reverse-proxies
+   *  against (addon HTTP data-planes). */
+  setDataPlaneRegistry(registry: DataPlaneRegistry): void {
+    this.dataPlaneRegistry = registry;
+  }
+
+  /**
+   * Pull a forked addon's HTTP data-plane endpoints over UDS and register them so
+   * the hub can reverse-proxy `/addon/<addonId>/<prefix>/*` to the addon's own
+   * listener. Idempotent (replace-all); an addon with no data-plane registers an
+   * empty set (cleared). Called off the capabilities-changed signal — a data-plane
+   * isn't a cap, but the child is UDS-reachable and has served its endpoints by
+   * the time any of its caps register.
+   */
+  private async mountAddonDataPlanes(addonId: string): Promise<void> {
+    const registry = this.dataPlaneRegistry;
+    if (!registry) return;
+    const entry = this.addonEntries.get(addonId);
+    const childRegistry = this.moleculer.childRegistry;
+    // Forked addons only for now — co-located builtins would publish into the
+    // registry directly via a hub-side sink (deferred; no builtin serves a
+    // data-plane yet).
+    if (!entry || !this.isForkedAddonEntry(entry)) return;
+    if (childRegistry === null || !childRegistry.isChildKnown(addonId)) return;
+
+    const raw = await this.addonCallGateway.callForked(addonId, { target: "data-planes" });
+    const endpoints = parseDataPlaneEndpoints(raw);
+    registry.registerAddon(addonId, endpoints);
+    if (endpoints.length > 0) {
+      this.logger.info("Addon data-planes mounted (reverse-proxy)", {
+        meta: { phase: "v2", addonId, prefixes: endpoints.map((e) => e.prefix) },
+      });
+    }
+  }
+
   /**
    * Called after app.init() when the tRPC router is available.
    * No-op now: addon `ctx.api` resolves to a broker-routed proxy, so
@@ -1118,8 +1343,8 @@ export class AddonRegistryService {
       // vs in-process being the transport, exactly like cap methods.
       await this.registerForkedAddonCustomActions(
         id,
-        // `shouldFork` already asserted `entry.declaration?.execution`.
-        resolveRunnerId(entry.declaration!, id),
+        // `isForkedAddonEntry` narrowed `entry.declaration` to non-null.
+        resolveRunnerId(entry.declaration, id),
       );
 
       entry.initialized = true;
@@ -1153,7 +1378,9 @@ export class AddonRegistryService {
       // ProviderRegistration.kind/defaultActive are deprecated hints — if an
       // addon still sets them and they disagree, warn (the cap def wins).
       const kindDrift = describeProviderKindDrift(capName, reg.capability, {
+        // eslint-disable-next-line @typescript-eslint/no-deprecated -- this IS the drift detector; it reads the deprecated hint on purpose
         kind: reg.kind,
+        // eslint-disable-next-line @typescript-eslint/no-deprecated -- this IS the drift detector; it reads the deprecated hint on purpose
         defaultActive: reg.defaultActive,
       });
       if (kindDrift) {
@@ -1650,18 +1877,28 @@ export class AddonRegistryService {
   }
 
   /**
-   * True when the entry boots in its own forked runner: it declares an
-   * `execution` block, ships an on-disk `addonDir`, and is not
-   * `agent-only`. Everything else (only `@camstack/core` builtins)
-   * boots in-process on the hub. The type predicate narrows `addonDir`
-   * to `string` for callers.
+   * True when the entry boots in its own forked runner. This MUST mirror
+   * the fork authority `buildAddonGroupPlan`, which spawns a runner for
+   * every addon that ships an on-disk `addonDir` + a manifest
+   * `declaration`, is NOT a `@camstack/core` builtin, and is NOT
+   * `agent-only`. The `execution` block is OPTIONAL — an addon with no
+   * `execution` declaration still forks on its own dedicated runner
+   * (`resolveRunnerId` falls back to the addon id). Requiring `execution`
+   * here previously diverged from `buildAddonGroupPlan`: an addon like
+   * `auth-oidc` (no `execution` block) was forked at boot yet classified
+   * in-process by this predicate, so its route-mount took the co-located
+   * path and received the async UDS cap proxy whose `getRoutes()` returns
+   * a Promise (→ `getRoutes(...).map is not a function`). Only
+   * `@camstack/core` builtins boot in-process on the hub. The type
+   * predicate narrows both `addonDir` and `declaration` for callers.
    */
   private isForkedAddonEntry(
     entry: AddonEntry,
-  ): entry is AddonEntry & { addonDir: string } {
+  ): entry is AddonEntry & { addonDir: string; declaration: AddonDeclaration } {
     return !!(
-      entry.declaration?.execution &&
+      entry.declaration &&
       entry.addonDir &&
+      entry.packageName !== "@camstack/core" &&
       resolveAddonPlacement(entry.declaration) !== 'agent-only'
     );
   }
@@ -1735,7 +1972,14 @@ export class AddonRegistryService {
         }
         return {
           manifest: {
-            ...entry.addon.manifest!,
+            // Overlay the fresh on-disk declaration (refreshed by
+            // `loadNewAddons` on every `camstack deploy`) onto the live
+            // instance manifest, so a redeployed addon's new capabilities /
+            // brokerKind surface here without a full backend restart. See
+            // `overlayDeclaration` — this is what keeps Home Assistant
+            // (post broker rework: broker + device-adoption) visible in the
+            // "+ New Integration" picker.
+            ...overlayDeclaration(entry.addon.manifest!, entry.declaration),
             packageName: entry.packageName,
             packageVersion: entry.packageVersion,
             packageDisplayName: entry.packageDisplayName,
@@ -2275,6 +2519,16 @@ export class AddonRegistryService {
           default:
             break;
         }
+
+        // HTTP data-planes aren't capabilities, so no `case` fires for them —
+        // pull them off ANY cap-changed signal for this (forked) addon. Cheap +
+        // idempotent (replace-all), and re-pulls the fresh baseUrl/secret after a
+        // restart (the child re-handshakes → caps re-register → this re-fires).
+        void this.mountAddonDataPlanes(addonId).catch((err: unknown) => {
+          this.logger.error('Failed to mount addon data-planes', {
+            meta: { phase: 'v2', addonId, error: errMsg(err) },
+          })
+        })
       },
     );
   }
@@ -2282,53 +2536,118 @@ export class AddonRegistryService {
   /**
    * Mount the `addon-routes` provider for `addonId` into the
    * `AddonRouteRegistry`. Handles both co-located (in-process) and
-   * forked/group addons:
+   * forked addons:
    *
-   * - For a forked addon the provider is a Moleculer proxy whose
-   *   `getRoutes()` / `invoke()` return Promises and whose route
-   *   descriptors have their `handler` functions stripped by JSON
-   *   serialization. We `await getRoutes()`, synthesize bridge
-   *   handlers that dispatch through `provider.invoke(...)`, and
-   *   translate the captured envelope back onto the Fastify reply.
-   * - For a co-located addon `getRoutes()` resolves to the live route
-   *   list with real handlers, so we register the provider directly.
+   * - For a hub-local FORKED addon the route handlers live in the
+   *   child process and cannot cross the UDS wire (MsgPack can't encode
+   *   a function). We fetch the handler-stripped route descriptors over
+   *   UDS via `LocalChildRegistry.callAddonOnChild(addonId,
+   *   {target:'routes'})` (F3 — replaces the removed per-addon Moleculer
+   *   `getRoutes` action), synthesize bridge handlers that dispatch
+   *   through the `addon-routes` cap's `invoke(...)` method (a normal
+   *   serializable cap call over UDS), and translate the captured
+   *   envelope back onto the Fastify reply.
+   * - For a co-located (hub-resident) addon `getRoutes()` resolves to the
+   *   live route list with real handlers, so we register the provider
+   *   directly.
    */
   private async mountAddonRoutes(addonId: string): Promise<void> {
-    if (!this.capabilityRegistry) return;
+    if (!this.capabilityRegistry || !this.addonRouteRegistry) return;
+    const addonRouteRegistry = this.addonRouteRegistry;
     const routeProvider = this.capabilityRegistry.getProviderByAddon(
       "addon-routes",
       addonId,
     );
-    if (!routeProvider || !this.addonRouteRegistry) return;
-
-    // `getRoutes()` is synchronous on a co-located provider but
-    // returns a Promise on the Moleculer proxy of a forked addon —
-    // `await` normalizes both. If any route is missing its `handler`
-    // we synthesize one that dispatches via `provider.invoke(...)`
-    // and translates the captured envelope back to the Fastify reply.
-    const liveRoutes = await routeProvider.getRoutes()
-    const handlersMissing = liveRoutes.some((r: { handler?: unknown }) => typeof r.handler !== 'function')
-    if (handlersMissing) {
-      const invokeFn = (routeProvider as { invoke?: (input: unknown) => Promise<unknown> }).invoke
-      if (typeof invokeFn !== 'function') {
-        this.logger.warn('Forked addon-routes provider missing `invoke` method — routes will not dispatch. Use `buildAddonRouteProvider()` from @camstack/types.', {
-          meta: { phase: 'v2', routeProviderId: routeProvider.id },
-        })
+    if (!routeProvider) return;
+
+    // ── Forked addon: fetch handler-stripped routes over UDS (F3) ──────
+    // EVERY non-`@camstack/core` addon forks (the fork authority is
+    // `buildAddonGroupPlan`, which does NOT require an `execution` block — an
+    // addon like `auth-oidc` with no `execution` still runs in its own
+    // runner). `isForkedAddonEntry` now mirrors that rule. For a forked addon
+    // the `getProviderByAddon('addon-routes', …)` result is the async UDS cap
+    // proxy whose `getRoutes()` returns a Promise — registering it directly
+    // would crash `AddonRouteRegistry.registerRoutes` (`getRoutes(...).map is
+    // not a function`), and dispatching the proxy's `getRoutes` cap method
+    // over UDS would try to MsgPack-serialize the child's live handler
+    // functions (→ "Unrecognized object: [object AsyncFunction]"). Instead we
+    // fetch handler-STRIPPED descriptors via `callAddonOnChild(target:
+    // 'routes')` and bridge each through the `invoke` cap method. The UDS
+    // childId for a hub-local single-addon runner equals the addonId
+    // (`resolveRunnerId` — no shipped addon declares a group). Gate on
+    // `isChildKnown` (the child completed its UDS handshake) rather than
+    // `childProvides('addon-routes')`: the `addon-call` route fetch works as
+    // long as the child is connected, and the child is added to the UDS
+    // registry BEFORE its manifest fires the cap-changed event that triggers
+    // this mount, so the gate is satisfied on the happy path.
+    const entry = this.addonEntries.get(addonId);
+    const childRegistry = this.moleculer.childRegistry;
+    if (entry && this.isForkedAddonEntry(entry)) {
+      if (childRegistry !== null && childRegistry.isChildKnown(addonId)) {
+        await this.mountForkedAddonRoutes(addonId, routeProvider, addonRouteRegistry);
+        return;
       }
-      // Wrap each route with a bridge handler so the
-      // AddonRouteRegistry can dispatch through the worker.
-      const bridgeRoutes: import('@camstack/types').IAddonHttpRoute[] = (liveRoutes as ReadonlyArray<{ method: string; path: string; access?: string; description?: string }>).map((route) => ({
-        method: route.method as 'GET' | 'POST' | 'PUT' | 'DELETE',
+      // Child not yet connected over UDS: defer rather than register the async
+      // proxy directly (which would crash on `.map`). The `addon-routes`
+      // cap-changed event re-fires once the child finishes its handshake.
+      this.logger.warn('Deferring forked addon route mount — child not yet UDS-reachable', {
+        meta: { phase: 'v2', addonId },
+      });
+      return;
+    }
+
+    // ── Co-located addon (`@camstack/core` builtin): live handlers, register
+    // the provider directly. The route handlers run in-process against the
+    // real Fastify reply, so no wire bridge is needed.
+    addonRouteRegistry.registerRoutes(routeProvider.id, routeProvider);
+    this.logger.info('Addon routes mounted', {
+      meta: { phase: 'v2', routeProviderId: routeProvider.id },
+    });
+  }
+
+  /**
+   * Mount a hub-local FORKED addon's HTTP routes (F3). The route handlers live
+   * in the child process; only handler-stripped descriptors cross the UDS wire.
+   * We:
+   *   1. fetch the descriptors via `callAddonOnChild(addonId, {target:'routes'})`,
+   *   2. synthesize a bridge handler per route that dispatches the captured
+   *      request through the `addon-routes` cap's `invoke(...)` method (a normal
+   *      serializable UDS cap call on `routeProvider`), and
+   *   3. translate the returned reply envelope back onto the Fastify reply.
+   *
+   * `addonRouteRegistry` is narrowed non-null by the caller's guard in
+   * `mountAddonRoutes` — no assertion needed here.
+   */
+  private async mountForkedAddonRoutes(
+    addonId: string,
+    routeProvider: import('@camstack/types').IAddonRouteProvider,
+    addonRouteRegistry: AddonRouteRegistry,
+  ): Promise<void> {
+    // The cap-registry typed surface for `addon-routes` is the operator-facing
+    // `IAddonRouteProvider` (id + getRoutes). The bridge dispatch contract
+    // `invoke(...)` is present on the UDS proxy but not on that interface —
+    // narrow it via a structural type guard (no cast).
+    if (!isAddonRoutesInvoker(routeProvider)) {
+      this.logger.warn(
+        'Forked addon-routes provider missing `invoke` method — routes will not dispatch. Use `buildAddonRouteProvider()` from @camstack/types.',
+        { meta: { phase: 'v2', routeProviderId: routeProvider.id } },
+      );
+      return;
+    }
+    const invoker = routeProvider;
+
+    const rawRoutes = await this.addonCallGateway.callForked(addonId, {
+      target: 'routes',
+    });
+    const descriptors = parseSerializableRouteDescriptors(rawRoutes);
+    const bridgeRoutes: import('@camstack/types').IAddonHttpRoute[] = descriptors.map(
+      (route) => ({
+        method: route.method,
         path: route.path,
-        access: (route.access ?? 'public') as 'public' | 'authenticated' | 'admin',
+        access: route.access,
         ...(route.description !== undefined ? { description: route.description } : {}),
-        handler: async (req: { params: Record<string, string>; query: Record<string, string>; body: unknown; headers: Record<string, string>; user?: { id: string; username: string; isAdmin: boolean }; scopedToken?: unknown }, reply: { code: (n: number) => unknown; header: (k: string, v: string) => unknown; type: (m: string) => unknown; send: (data: unknown) => void; redirect: (url: string) => void }) => {
-          if (typeof invokeFn !== 'function') {
-            reply.code(500)
-            reply.send({ error: 'Forked addon-routes provider missing invoke' })
-            return
-          }
-          const envelope = await invokeFn({
+        handler: async (req, reply) => {
+          const envelope = await invoker.invoke({
             method: route.method,
             path: route.path,
             params: req.params,
@@ -2336,31 +2655,27 @@ export class AddonRegistryService {
             body: req.body,
             headers: req.headers,
             ...(req.user ? { user: req.user } : {}),
-            ...(req.scopedToken ? { scopedToken: req.scopedToken } : {}),
-          }) as { status: number; headers: Record<string, string>; redirectUrl: string | null; body?: unknown; contentType?: string }
-          reply.code(envelope.status)
-          if (envelope.contentType) reply.type(envelope.contentType)
-          for (const [k, v] of Object.entries(envelope.headers)) reply.header(k, v)
+            ...(req.scopedToken !== undefined ? { scopedToken: req.scopedToken } : {}),
+          });
+          reply.code(envelope.status);
+          if (envelope.contentType) reply.type(envelope.contentType);
+          for (const [k, v] of Object.entries(envelope.headers)) reply.header(k, v);
           if (envelope.redirectUrl !== null) {
-            reply.header('Location', envelope.redirectUrl)
-            reply.send('')
+            reply.header('Location', envelope.redirectUrl);
+            reply.send('');
           } else {
-            reply.send(envelope.body)
+            reply.send(envelope.body);
           }
         },
-      }))
-      this.addonRouteRegistry.registerRoutes(
-        routeProvider.id,
-        { id: routeProvider.id, getRoutes: () => bridgeRoutes },
-      )
-      this.logger.info('Addon routes mounted (forked-bridge)', { meta: { phase: 'v2', routeProviderId: routeProvider.id, routes: bridgeRoutes.length } })
-    } else {
-      this.addonRouteRegistry.registerRoutes(
-        routeProvider.id,
-        routeProvider,
-      );
-      this.logger.info('Addon routes mounted', { meta: { phase: 'v2', routeProviderId: routeProvider.id } });
-    }
+      }),
+    );
+    addonRouteRegistry.registerRoutes(routeProvider.id, {
+      id: routeProvider.id,
+      getRoutes: () => bridgeRoutes,
+    });
+    this.logger.info('Addon routes mounted (forked-bridge over UDS)', {
+      meta: { phase: 'v2', routeProviderId: routeProvider.id, routes: bridgeRoutes.length },
+    });
   }
 
   // Cleanup: `addonHasConfigFields` deleted. It was the last reader of
@@ -2634,12 +2949,22 @@ export class AddonRegistryService {
         streamProbe: kernelStreamProbe,
         hwaccel: createKernelHwAccel(),
         capabilityRegistry: this.capabilityRegistry,
+        // Per-addon storage-location declarations across every installed
+        // addon — surfaced from the kernel's AddonLoader so the
+        // storage-orchestrator builtin can aggregate them and seed defaults.
+        listStorageLocationDeclarations: () =>
+          this.addonLoader.listStorageLocationDeclarations(),
         readinessRegistry: this.moleculer.readinessRegistry,
         // D3: handshake-fed native-cap view of the whole cluster. Backed by
         // `HubNodeRegistry.listNativeCapEntries()` populated by every
         // `$hub.registerNode` re-handshake. Used by device-manager as the
         // reliable fallback when push events were lost mid-transport.
         listClusterNativeCaps: () => this.moleculer.listClusterNativeCaps(),
+        // Per-device slice of the above — O(caps-for-device) via the registry's
+        // deviceId index. The per-device `getBindings` resolver prefers this
+        // over filtering the whole-cluster flat view.
+        listClusterNativeCapsForDevice: (deviceId: number) =>
+          this.moleculer.listClusterNativeCapsForDevice(deviceId),
       },
       registerProvider,
       resolveProvider: <T = unknown>(capName: string): T | null => {
@@ -2838,8 +3163,11 @@ export class AddonRegistryService {
    *
    * The catalog (zod `input`/`output` specs) is read STATICALLY from the
    * addon module's `customActions` named export — the handler dispatches
-   * via `broker.call('<addonId>.custom.<action>')`, so the only divergence
-   * vs an in-process addon is the transport, exactly like cap methods.
+   * over UDS via `LocalChildRegistry.callAddonOnChild(addonId,
+   * {target:'custom', action, args})` (F3 — replaces the removed per-addon
+   * Moleculer `custom.<action>` action), so the only divergence vs an
+   * in-process addon is the transport, exactly like cap methods. The hub's
+   * `CustomActionRegistry` validates input/output around this dispatch.
    *
    * Why a fresh import: `this.addonLoader`'s `module` namespace is
    * captured once at boot. After a hot-update (`installFromTgz` →
@@ -2916,11 +3244,29 @@ export class AddonRegistryService {
     this.customActionRegistry.registerAddon(
       addonId,
       catalog as import("@camstack/types").CustomActionsSpec,
-      (action, input) => this.broker.call(`${addonId}.custom.${action}`, input),
+      (action, input) => this.dispatchForkedCustomAction(addonId, action, input),
     );
     this.logger.info("Runner addon custom actions registered", {
       tags: { addonId },
       meta: { runnerId },
     });
   }
+
+  /**
+   * Dispatch a forked addon's custom action through the shared
+   * {@link AddonCallGateway} (UDS to the hub-local child). The gateway owns the
+   * routing + the child-availability error; there is no broker fallback after
+   * the per-addon Moleculer broker was removed.
+   */
+  private async dispatchForkedCustomAction(
+    addonId: string,
+    action: string,
+    input: unknown,
+  ): Promise<unknown> {
+    return this.addonCallGateway.callForked(addonId, {
+      target: "custom",
+      action,
+      args: input,
+    });
+  }
 }