@camstack/server 1.2.268 → 1.2.270

package/dist/core/addon/addon-registry.service.js

@@ -43,7 +43,6 @@ const node_crypto_1 = require("node:crypto");
 const fs = __importStar(require("node:fs"));
 const os = __importStar(require("node:os"));
 const path = __importStar(require("node:path"));
-const node_url_1 = require("node:url");
 const system_1 = require("@camstack/system");
 const types_1 = require("@camstack/types");
 const client_1 = require("@trpc/client");
@@ -53,8 +52,8 @@ const addon_settings_provider_js_1 = require("./addon-settings-provider.js");
 const device_meta_mirror_js_1 = require("./device-meta-mirror.js");
 const integration_visibility_js_1 = require("./integration-visibility.js");
 const package_dir_utils_1 = require("./package-dir-utils");
+const forked_custom_actions_js_1 = require("./forked-custom-actions.js");
 const prune_misplaced_addons_js_1 = require("./prune-misplaced-addons.js");
-const require_cache_js_1 = require("./require-cache.js");
 const runner_convergence_1 = require("./runner-convergence");
 const runner_spawn_fanout_js_1 = require("./runner-spawn-fanout.js");
 /**
@@ -269,10 +268,14 @@ class AddonRegistryService {
     // through this from the `api.addons.custom` tRPC procedure.
     customActionRegistry = new system_1.CustomActionRegistry();
     /**
-     * Keeps `purgeRequireCacheUnder` + `import()` atomic per addon directory now
-     * that the boot runner plan overlaps (D171). See `runner-spawn-fanout.ts`.
+     * Fingerprint of the custom-action catalogs each UDS child last DESCRIBED
+     * (keyed by child id), and the addon ids registered from that description.
+     * A re-register carrying the same catalogs is a no-op with no line; a child
+     * whose new description drops an addon has that addon's actions withdrawn.
+     * See {@link applyChildCustomActions}.
      */
-    moduleLoadSerializer = (0, runner_spawn_fanout_js_1.createKeyedSerializer)();
+    childCatalogFingerprints = new Map();
+    childCatalogAddons = new Map();
     /**
      * AddonIds whose group-runner disconnect is operator-initiated (update /
      * restart / uninstall). The Moleculer `$node.disconnected` handler skips
@@ -2375,6 +2378,11 @@ class AddonRegistryService {
     wireCapabilityConsumers() {
         if (!this.capabilityRegistry)
             return;
+        // A forked runner's custom-action catalogs arrive in its register frame,
+        // not as a capability event — a non-device runner's post-init register
+        // carries the same caps as its pre-init one, so no `provider-registered`
+        // event marks the moment the catalogs exist. See `applyChildCustomActions`.
+        this.moleculer.onChildCustomActions((child) => this.applyChildCustomActions(child));
         this.eventBusService.subscribe({ category: 'capability:provider-registered' }, (event) => {
             const rawCapability = event.data['capability'];
             const rawAddonId = event.data['addonId'];
@@ -3100,12 +3108,12 @@ class AddonRegistryService {
         catch (err) {
             throw new Error(`Failed to spawn runner "${runnerId}" (${addons.length} addons): ${(0, types_1.errMsg)(err)}`, { cause: err });
         }
-        // Register custom actions for each addon on the runner. Provider
-        // registration for cap methods is handled by
-        // `CapabilityBridge.onProviderConnected` once the runner's
-        // INFO heartbeat lands.
+        // Provider registration for cap methods is handled by
+        // `CapabilityBridge.onProviderConnected` once the runner's INFO heartbeat
+        // lands, and the custom-action catalogs arrive the same way — in the
+        // runner's post-init register frame, applied by `applyChildCustomActions`.
+        // Nothing about the runner is read from its bundle here (D444).
         for (const { addonId } of addons) {
-            await this.registerForkedAddonCustomActions(addonId, runnerId);
             // Mark the entry initialized so the in-process core-builtin boot
             // passes skip it (those passes only touch `@camstack/system`).
             const entry = this.addonEntries.get(addonId);
@@ -3207,146 +3215,78 @@ class AddonRegistryService {
             }
             this.recentGroupRespawns.set(runnerId, Date.now());
         }
-        // 3. Bookkeeping for EVERY roster member. Custom actions live in the
-        //    hub-side registry the process spawn never touches; a hot-update would
-        //    otherwise silently drop them (the boot plan is the only other place
-        //    they register). Mark each member initialized so the in-process
-        //    core-builtin boot passes skip them.
+        // 3. Bookkeeping for EVERY roster member. Mark each member initialized so
+        //    the in-process core-builtin boot passes skip them. The custom-action
+        //    catalogs are NOT touched here: the respawned runner describes them in
+        //    its post-init register frame and `applyChildCustomActions` replaces
+        //    whatever the previous incarnation registered (D444).
         for (const { addonId: memberId } of roster) {
-            await this.registerForkedAddonCustomActions(memberId, runnerId);
             const memberEntry = this.addonEntries.get(memberId);
             if (memberEntry)
                 memberEntry.initialized = true;
         }
     }
     /**
-     * (Re-)register the custom-action catalog for a forked / group-hosted
-     * addon against the shared `CustomActionRegistry`.
+     * Apply the custom-action catalogs a UDS child DESCRIBED in its register
+     * frame (`RegisteredChild.customActions`, schemas stripped) to the hub-wide
+     * `CustomActionRegistry`, dispatching each action back to that child over
+     * the addon-call plane.
      *
-     * The catalog (zod `input`/`output` specs) is read STATICALLY from the
-     * addon module's `customActions` named export — the handler dispatches
-     * 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 the child describes, and the hub never reads the bundle
      *
-     * Why a fresh import: `this.addonLoader`'s `module` namespace is
-     * captured once at boot. After a hot-update (`installFromTgz` →
-     * `restartAddon`) the on-disk bundle is newer than that cached module,
-     * so re-reading the boot-time `module` would register a STALE catalog
-     * (or none at all, if the addon was first installed after boot). We
-     * re-`import()` the entry with a cache-busting query so Node's ESM
-     * loader hands back the current bundle.
+     * Until D444 this was `registerForkedAddonCustomActions`: purge the require
+     * cache, re-import the addon's entry INSIDE hub-main, read its
+     * `customActions` export. Measured 2026-09-10 on the live hub: 9.3 MB of
+     * `addon-pipeline-orchestrator/dist/index.js` evaluated in hub-main by a
+     * sampling heap profile, ten deploys in the process's 23 h life, NONE of
+     * which exported a catalog — and the only line saying so was at `debug`,
+     * which the hub does not write. Every evaluation pins whatever module-scope
+     * state the evicted graph left behind, and the bundle-reload guard existed
+     * only to keep that re-execution survivable (D284). The runner is the
+     * process that owns the addon; it describes its catalog once its init loop
+     * has produced it, in the post-init register frame, and validates the
+     * action's input and output itself (`child-addon-call-dispatch.ts`).
      *
-     * Idempotent: drops any prior registration first. No-op (with a debug
-     * log) when the addon exports no `customActions` — most addons don't.
+     * ## What one description does
+     *
+     *  - identical to the child's last description → nothing, silently (a
+     *    native-cap change or reconnect re-sends the same frame);
+     *  - otherwise every addon in it is (re-)registered — an EMPTY catalog
+     *    withdraws that addon's actions — and an addon the previous description
+     *    named but this one does not is withdrawn too;
+     *  - and ONE `info` line per applied description names what it produced,
+     *    including "nothing": a load that produces nothing and says nothing is
+     *    the branch D391 forbids.
      */
-    async registerForkedAddonCustomActions(addonId, runnerId) {
-        // Always clear first so a restart that REMOVES custom actions (or an
-        // addon whose entry no longer exports them) doesn't leave stale
-        // entries resolvable.
-        this.customActionRegistry.unregisterAddon(addonId);
-        const entry = this.addonEntries.get(addonId);
-        const addonDir = entry?.addonDir;
-        const declarationEntry = entry?.declaration?.entry;
-        if (!addonDir || !declarationEntry)
-            return;
-        // Resolve the built entry the same way `AddonLoader.loadDeclaration`
-        // does: `./src/x.ts` → `dist/x.js`, with index.js fallbacks.
-        const entryFile = declarationEntry
-            .replace(/^\.\//, '')
-            .replace(/^src\//, 'dist/')
-            .replace(/\.ts$/, '.js');
-        let entryPath = path.resolve(addonDir, entryFile);
-        if (!fs.existsSync(entryPath)) {
-            const base = entryPath.replace(/\.(js|cjs|mjs)$/, '');
-            const alternatives = [
-                `${base}.cjs`,
-                `${base}.mjs`,
-                path.resolve(addonDir, 'dist', 'index.js'),
-                path.resolve(addonDir, 'dist', 'index.cjs'),
-                path.resolve(addonDir, 'dist', 'index.mjs'),
-                path.resolve(addonDir, declarationEntry),
-            ];
-            entryPath = alternatives.find((p) => fs.existsSync(p)) ?? entryPath;
-        }
-        if (!fs.existsSync(entryPath))
-            return;
-        let catalog;
-        try {
-            // ── The query string does NOT bust a CommonJS bundle ──────────────
-            //
-            // Every addon here builds to CJS, and Node's ESM loader serves a CJS
-            // module out of the REQUIRE cache, which is keyed by the resolved
-            // filename with the query stripped. So `?t=<now>` below busts nothing
-            // for them: this function re-registered the catalog captured at hub boot
-            // on every restart, forever.
-            //
-            // The consequence was invisible and total: an EXISTING action kept
-            // working, so nothing looked broken, while a NEWLY added one could never
-            // become reachable without restarting the whole hub process — which
-            // quietly falsifies the reason bridge actions exist ("no codegen, no
-            // republish, no train"). Found 2026-08-08, deploying `nc.injectTestEvent`:
-            // the deploy succeeded, the restart logged "custom actions registered",
-            // and the action 404'd.
-            //
-            // Dropping the addon's own modules from the require cache is what
-            // actually re-reads the bundle — see `require-cache.ts` for the scoping
-            // and the real-path match Node's cache keys demand.
-            //
-            // The purge mutates the PROCESS-GLOBAL require cache, so purge-then-import
-            // must stay atomic per BUNDLE now that the boot plan overlaps (D171):
-            // `@camstack/addon-remote-storage` ships four addon ids whose entries all
-            // resolve into one `dist/`, and a sibling's purge landing mid-import would
-            // evict a module graph while it is being evaluated. Different bundles
-            // still load concurrently.
-            //
-            // The scope is the BUNDLE (`<addonDir>/dist`), never `dirname(entryPath)`
-            // — see `bundleGraphRootFor`. The narrow scope evicted the entry chunk and
-            // kept the shared chunks, so the re-import re-ran the entry's module-scope
-            // declarations against singletons that had survived, and took the broker
-            // down on 2026-08-29 (D284). The serializer key MUST match the purge
-            // scope: two addon ids of one package now purge the same graph, so
-            // serializing them per entry-folder would let one evict the other's
-            // modules mid-evaluation — the exact race the key exists to prevent.
-            const graphRoot = (0, require_cache_js_1.bundleGraphRootFor)(addonDir, entryPath);
-            const modUnknown = await this.moduleLoadSerializer.run(graphRoot, async () => {
-                (0, require_cache_js_1.purgeRequireCacheUnder)(graphRoot);
-                // Kept for a genuinely ESM addon entry, where it IS the mechanism.
-                const cacheBustedUrl = `${(0, node_url_1.pathToFileURL)(entryPath).href}?t=${Date.now()}`;
-                // A plain `await import()` here is downleveled by tsc (the backend builds
-                // with `module: CommonJS`) into a `require()`-based shim. `require()` then
-                // treats the `?t=…` cache-bust query as part of the literal filename and
-                // throws MODULE_NOT_FOUND for EVERY forked addon — so no forked addon's
-                // custom-action catalog ever loaded. Use a native dynamic import the
-                // compiler won't rewrite, so Node's ESM loader handles the query string.
-                const nativeImport = new Function('specifier', 'return import(specifier)');
-                return nativeImport(cacheBustedUrl);
-            });
-            catalog =
-                modUnknown && typeof modUnknown === 'object'
-                    ? modUnknown['customActions']
-                    : undefined;
-        }
-        catch (err) {
-            this.logger.warn('Failed to load custom-action catalog for forked addon', {
-                tags: { addonId },
-                meta: { error: (0, types_1.errMsg)(err) },
-            });
+    applyChildCustomActions(child) {
+        const catalogs = child.customActions;
+        if (catalogs === undefined)
             return;
-        }
-        if (!catalog || typeof catalog !== 'object') {
-            this.logger.debug('Forked addon exports no custom actions', {
-                tags: { addonId },
-                meta: { runnerId },
-            });
+        const fingerprint = (0, forked_custom_actions_js_1.childCatalogsFingerprint)(catalogs);
+        if (this.childCatalogFingerprints.get(child.childId) === fingerprint)
             return;
+        this.childCatalogFingerprints.set(child.childId, fingerprint);
+        const described = new Set(Object.keys(catalogs));
+        for (const previous of this.childCatalogAddons.get(child.childId) ?? []) {
+            if (!described.has(previous))
+                this.customActionRegistry.unregisterAddon(previous);
+        }
+        this.childCatalogAddons.set(child.childId, described);
+        for (const [addonId, descriptor] of Object.entries(catalogs)) {
+            if (Object.keys(descriptor).length === 0) {
+                this.customActionRegistry.unregisterAddon(addonId);
+                continue;
+            }
+            this.customActionRegistry.registerAddon(addonId, (0, forked_custom_actions_js_1.toForkedCustomActionsSpec)(descriptor), (action, input, caller) => this.dispatchForkedCustomAction(addonId, action, input, caller));
         }
-        this.customActionRegistry.registerAddon(addonId, catalog, (action, input, caller) => this.dispatchForkedCustomAction(addonId, action, input, caller));
-        this.logger.info('Runner addon custom actions registered', {
-            tags: { addonId },
-            meta: { runnerId },
+        const summary = (0, forked_custom_actions_js_1.summarizeChildCatalogs)(catalogs);
+        this.logger.info('UDS child custom-action catalogs applied', {
+            meta: {
+                childId: child.childId,
+                incarnation: child.incarnation,
+                registered: summary.withActions.length > 0 ? summary.withActions.join(',') : '(none)',
+                withoutActions: summary.withoutActions.length > 0 ? summary.withoutActions.join(',') : '(none)',
+            },
         });
     }
     /**

package/dist/core/addon/forked-custom-actions.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toForkedCustomActionsSpec = toForkedCustomActionsSpec;
+exports.childCatalogsFingerprint = childCatalogsFingerprint;
+exports.summarizeChildCatalogs = summarizeChildCatalogs;
+const zod_1 = require("zod");
+/**
+ * Build the hub-side catalog for a forked addon.
+ *
+ * `input`/`output` are `z.unknown()` ON PURPOSE: the hub's
+ * `dispatchCustomAction` parses input and output around the dispatch, and for
+ * a forked addon both parses must be passthroughs — the runner owns the
+ * schemas and refuses what they refuse. `kind`, `auth`, `scope` and `caller`
+ * are the fields the hub actually gates on, and they arrive intact.
+ */
+function toForkedCustomActionsSpec(descriptor) {
+    const spec = {};
+    for (const [name, action] of Object.entries(descriptor)) {
+        spec[name] = {
+            input: zod_1.z.unknown(),
+            output: zod_1.z.unknown(),
+            kind: action.kind,
+            auth: action.auth,
+            scope: action.scope,
+            ...(action.caller === 'required' ? { caller: 'required' } : {}),
+        };
+    }
+    return spec;
+}
+/**
+ * A stable identity for a child's whole catalog set, so a re-register that
+ * carries the SAME catalogs (native-cap change, reconnect — 246 re-registers in
+ * 30 minutes with zero respawns, measured 2026-08-25) registers nothing and
+ * logs nothing. Key order is normalised at every level: two descriptions of
+ * one catalog must never fingerprint differently because a runner enumerated
+ * its map in another order.
+ */
+function childCatalogsFingerprint(catalogs) {
+    return JSON.stringify(sortKeysDeep(catalogs));
+}
+function sortKeysDeep(value) {
+    if (Array.isArray(value))
+        return value.map(sortKeysDeep);
+    if (value === null || typeof value !== 'object')
+        return value;
+    const out = {};
+    for (const key of Object.keys(value).sort()) {
+        out[key] = sortKeysDeep(Reflect.get(value, key));
+    }
+    return out;
+}
+function summarizeChildCatalogs(catalogs) {
+    const withActions = [];
+    const withoutActions = [];
+    for (const addonId of Object.keys(catalogs).sort()) {
+        const count = Object.keys(catalogs[addonId] ?? {}).length;
+        if (count > 0)
+            withActions.push(`${addonId}:${count}`);
+        else
+            withoutActions.push(addonId);
+    }
+    return { withActions, withoutActions };
+}

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

@@ -49,6 +49,15 @@ class MoleculerService {
      * See {@link ChildManifestGate}.
      */
     childManifestGate = new ChildManifestGate();
+    /**
+     * Receives every child register frame that DESCRIBES its custom-action
+     * catalogs (the post-init one and every re-register after it). Consulted
+     * BEFORE {@link ChildManifestGate}: the gate compares caps, and a post-init
+     * register of a non-device runner carries the same caps as its pre-init one
+     * — skipping it would lose the only frame that carries the catalogs (D444).
+     * The consumer (`AddonRegistryService`) dedupes by catalog fingerprint.
+     */
+    childCustomActionsHandler = null;
     /**
      * Fixed-period agent-readiness snapshot sweep (D8 reconcile) — repairs
      * agent-origin readiness deltas lost while the agent stayed connected.
@@ -126,6 +135,14 @@ class MoleculerService {
     get childRegistry() {
         return this.localChildRegistry;
     }
+    /**
+     * Register the (single) handler for a child's described custom-action
+     * catalogs. See {@link childCustomActionsHandler}. Called once by
+     * `AddonRegistryService` when it wires its consumers.
+     */
+    onChildCustomActions(handler) {
+        this.childCustomActionsHandler = handler;
+    }
     /** The CapRouteResolver once onModuleInit has completed; null before that. */
     get capRouteResolver() {
         return this.resolver;
@@ -437,6 +454,20 @@ class MoleculerService {
             registry.onChildRegistered((child) => {
                 const hubNodeId = this.brokerSafe.nodeID;
                 const childNodeId = `${hubNodeId}/${child.childId}`;
+                // The catalogs first, and unconditionally: the manifest gate below
+                // judges CAPS, and a frame whose caps are unchanged may still be the
+                // one frame that describes the catalogs. An absent field is a pre-init
+                // register and says nothing about actions — it is not forwarded.
+                if (child.customActions !== undefined) {
+                    try {
+                        this.childCustomActionsHandler?.(child);
+                    }
+                    catch (err) {
+                        logger.warn('UDS child custom-action catalogs could not be applied', {
+                            meta: { nodeId: childNodeId, incarnation: child.incarnation, error: (0, types_1.errMsg)(err) },
+                        });
+                    }
+                }
                 const params = buildChildUdsManifest(childNodeId, child.childId, child.caps);
                 // `updateCaps()` re-sends the whole register frame on the same socket,
                 // so this fires far more often than a runner starts: 246 rebuilds in 30

package/dist/core/update-availability-emitter.js

@@ -132,6 +132,11 @@ class UpdateAvailabilityEmitter {
             nodeId: scope,
         }));
         const head = list[0];
+        // `target: 'wrapper'` carries WHICH shell, and it has to survive the
+        // rebuild here or the notification loses the only thing that makes it
+        // actionable — a docker node would be told to press a button that cannot
+        // exist. Absent for every other target.
+        const wrapperKind = head.wrapperKind;
         this.eventBus.emit({
             id: `update.available:${target}:${scope}:${packages
                 .map((pkg) => `${pkg.packageName}@${pkg.latestVersion}`)
@@ -148,6 +153,7 @@ class UpdateAvailabilityEmitter {
                 packages,
                 nodeId: scope,
                 nodeIds: [scope],
+                ...(wrapperKind !== undefined ? { wrapperKind } : {}),
             },
         });
     }

package/dist/core/updates/update-check-scheduler.js

@@ -98,6 +98,9 @@ class UpdateCheckScheduler {
                     continue;
                 }
                 await this.attempt('node server package', node.id, () => this.targets.checkNodeServerUpdate(node.id, node.isHub));
+                // The shell, on EVERY node role — the hub is the one this failure was
+                // found on.
+                await this.attempt('node wrapper', node.id, () => this.targets.checkWrapperUpdate(node.id, node.isHub));
                 if (node.isHub)
                     continue;
                 await this.attempt('agent addon packages', node.id, () => this.targets.checkAgentAddons(node.id));

package/dist/core/updates/wrapper-update-checker.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WrapperUpdateChecker = exports.WRAPPER_PACKAGE_NAME = void 0;
+/**
+ * The availability row's package name. A shell is not an npm package, but the
+ * emitter keys dedup on `(target, node, packageName)` and a stable literal is
+ * what makes "one shell per node" the dedup slot. Never rendered: the
+ * notification body is chosen from the wrapper KIND.
+ */
+exports.WRAPPER_PACKAGE_NAME = 'camstack-wrapper';
+class WrapperUpdateChecker {
+    emitter;
+    logger;
+    readStatus;
+    constructor(options) {
+        this.emitter = options.emitter;
+        this.logger = options.logger;
+        this.readStatus = options.readStatus;
+    }
+    async check(nodeId, isHub) {
+        const status = await this.readStatus(nodeId, isHub);
+        const wrapper = status.wrapper;
+        const contract = status.imageContract;
+        if (wrapper === undefined || contract === undefined) {
+            // Version skew: this node's `@camstack/server` predates the wrapper
+            // field. Unanswerable, so it is an ERROR — reporting it as "no wrapper
+            // update" would be a claim nothing checked.
+            throw new Error(`node ${nodeId} reports no wrapper identity (server-management payload predates it)`);
+        }
+        if (contract.state === 'in-sync') {
+            // The one case where an empty snapshot is a fact rather than a guess.
+            this.emitter.publishSnapshot('wrapper', [], nodeId);
+            return;
+        }
+        const seedVersion = contract.seedVersion;
+        const contractVersion = contract.contractVersion;
+        const behind = contract.state === 'behind-patch' || contract.state === 'behind-series';
+        if (!behind || seedVersion === null || contractVersion === null) {
+            // `unknown` (no seed, or no registry answer yet) and `ahead` (a stale
+            // check) both mean "nothing was proved". Publishing an empty snapshot
+            // would clear a standing announcement on no evidence at all.
+            this.logger.warn('Wrapper check inconclusive — nothing published', {
+                tags: { nodeId },
+                meta: { state: contract.state, wrapperKind: wrapper.kind, seedVersion, contractVersion },
+            });
+            return;
+        }
+        const candidate = {
+            target: 'wrapper',
+            packageName: exports.WRAPPER_PACKAGE_NAME,
+            // The SHELL's versions, not the running code's. `wrapper.currentVersion`
+            // is what the shell says about ITSELF (an Electron app version), which
+            // is not on the same scale as a release; the seed is, and the seed is
+            // what `contractVersion` was compared against.
+            currentVersion: seedVersion,
+            latestVersion: contractVersion,
+            nodeId,
+            wrapperKind: wrapper.kind,
+        };
+        this.emitter.publishSnapshot('wrapper', [candidate], nodeId);
+    }
+}
+exports.WrapperUpdateChecker = WrapperUpdateChecker;