@camstack/system 1.2.84 → 1.2.86

package/dist/index.js

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_chunk = require("./chunk-Cek0wNdY.js");
-const require_dist = require("./dist-CQy9KjsL.js");
+const require_dist = require("./dist-BV5Bug9t.js");
 const require_builtins_alerts_alerts_addon = require("./builtins/alerts/alerts.addon.js");
 require("./builtins/alerts/index.js");
 const require_formatter = require("./formatter-DqAKDlvN.js");
@@ -25,7 +25,7 @@ const require_builtins_system_config_system_config_addon = require("./builtins/s
 require("./builtins/system-config/index.js");
 const require_builtins_winston_logging_index = require("./builtins/winston-logging/index.js");
 const require_file_data_plane = require("./file-data-plane-DUHPHa-Y.js");
-const require_manifest_python_deps = require("./manifest-python-deps-DG_LLcZF.js");
+const require_manifest_python_deps = require("./manifest-python-deps-C0zkl1Ae.js");
 const require_resource_monitor = require("./resource-monitor-CdnzxBLP.js");
 const require_custom_action_registry = require("./custom-action-registry-jY0NOZK8.js");
 let zod = require("zod");
@@ -4227,6 +4227,12 @@ var AddonInstaller = class AddonInstaller {
 	* installs from the admin UI go through `install()` instead, which
 	* defaults to npm in production.
 	*
+	* There is no version argument and there is deliberately no pin: the system is
+	* addons-agnostic and `latest` is the whole contract at first boot (operator,
+	* 2026-08-13). A copy already under the addon root is never replaced either —
+	* bootstrap is seed-only, and overwriting a deployed bundle would be an
+	* un-deploy ([D90](../../../../docs/decisions/adr-0090.md)).
+	*
 	* @param packages — optional custom package list (default: REQUIRED_PACKAGES)
 	*/
 	async ensureRequiredPackages(packages) {
@@ -4651,6 +4657,61 @@ var AddonInstaller = class AddonInstaller {
 			throw new Error(`${packageName} — runtime dependency install failed: ${require_dist.errMsg(err)}`, { cause: err });
 		}
 	}
+	/**
+	* Make `pkgDir`'s NATIVE modules loadable on THIS host, before it is swapped
+	* in: install whatever `camstack.nativeDependencies` declares, then ensure
+	* every traditional native present in the tree actually carries a compiled
+	* `.node` for the running ABI.
+	*
+	* ONE implementation, for the same reason as {@link installRuntimeDependencies}
+	* — every path that materialises an addon tree calls it, so no call site can
+	* forget it. `installFromTgz` (deploy/upload) always ran these two steps; the
+	* OTA staged-swap path ran NEITHER even after the runtime-dep fix (2026-08-12,
+	* task #15, which named this gap explicitly). Same outage class one layer
+	* down: an addon with native modules was broken by its FIRST OTA update, its
+	* dist landing without an ABI-matched binary, and every load dying at the
+	* binding (`Could not locate the bindings file`) — from the outside
+	* indistinguishable from a bad bundle.
+	*
+	* **Two distinct steps, both load-bearing.**
+	* `installManifestNativeDeps` fetches the DECLARED natives (prebuilt host copy
+	* first — offline — then npm + an ABI rebuild), and is idempotent through a
+	* content-hash marker. `ensureAddonNativePrebuilds` is the post-install pass:
+	* npm can leave a traditional native (`better-sqlite3`) SOURCE-ONLY on a
+	* toolchain-less host, so it re-fetches the prebuild for the running ABI and
+	* THROWS naming module + addon if the binary is still absent. No bundled
+	* source is available on this path (unlike `installCopy`) — fetch only.
+	*
+	* **Failure is FATAL**, mirroring the tgz path: callers complete the tree
+	* BEFORE they swap, so an abort simply means the swap never happens and the
+	* previous version keeps serving. Shipping a native-less copy instead would
+	* trade one broken version for a crash-loop.
+	*
+	* A missing/unreadable manifest is logged and skipped — `installRuntimeDependencies`
+	* has already said so loudly, and a tree with no readable package.json
+	* declares no natives.
+	*/
+	async installNativeDependencies(pkgDir, packageName) {
+		const pkgJsonPath = node_path.join(pkgDir, "package.json");
+		const pkgView = readPackageJson(pkgJsonPath);
+		if (pkgView == null) {
+			this.logger.error(`${packageName} — no readable package.json in the prepared tree; native dependencies NOT installed`, { meta: { pkgJsonPath } });
+			return;
+		}
+		try {
+			await require_manifest_python_deps.installManifestNativeDeps(pkgDir, pkgView.raw, this.logger, this.registry, this.npmCacheDir);
+		} catch (nativeErr) {
+			this.logger.error(`${packageName} — native dependency install FAILED; install ABORTED (a swapped-in copy would fail every load at the binding)`, { meta: {
+				pkgDir,
+				error: require_dist.errMsg(nativeErr)
+			} });
+			throw new Error(`${packageName} — native deps install failed: ${require_dist.errMsg(nativeErr)}`, { cause: nativeErr });
+		}
+		await ensureAddonNativePrebuilds(pkgDir, {
+			addonName: packageName,
+			logger: this.logger
+		});
+	}
 	/** Install addon from a tgz file (uploaded or downloaded) */
 	async installFromTgz(tgzPath) {
 		const stagingRoot = node_path.join(this.addonsDir, ".staging");
@@ -4675,15 +4736,7 @@ var AddonInstaller = class AddonInstaller {
 			if (!pkgView.camstackAddons) throw new Error(`Package ${pkgView.name} has no camstack.addons manifest`);
 			const targetDir = node_path.join(this.addonsDir, pkgView.name);
 			await this.installRuntimeDependencies(pkgDir, pkgView.name);
-			try {
-				await require_manifest_python_deps.installManifestNativeDeps(pkgDir, pkgView.raw, this.logger, this.registry, this.npmCacheDir);
-			} catch (nativeErr) {
-				throw new Error(`${pkgView.name} — native deps install failed: ${require_dist.errMsg(nativeErr)}`, { cause: nativeErr });
-			}
-			await ensureAddonNativePrebuilds(pkgDir, {
-				addonName: pkgView.name,
-				logger: this.logger
-			});
+			await this.installNativeDependencies(pkgDir, pkgView.name);
 			await this.evictInstallDir(targetDir);
 			ensureDir(node_path.dirname(targetDir));
 			await node_fs.promises.rename(pkgDir, targetDir);
@@ -4788,9 +4841,12 @@ var AddonInstaller = class AddonInstaller {
 	*
 	* "Skips npm entirely" is true only of the REGISTRY round-trip: the staged
 	* tree is the raw unpacked tarball, so the addon's own
-	* `camstack.runtimeDependencies` still have to be installed into it, exactly
-	* as `installFromTgz` does. Skipping that is what broke every runtime-dep
-	* addon on its first OTA update — see {@link installRuntimeDependencies}.
+	* `camstack.runtimeDependencies` AND `camstack.nativeDependencies` still have
+	* to be installed into it, exactly as `installFromTgz` does. Skipping the
+	* first broke every runtime-dep addon on its first OTA update; skipping the
+	* second broke every addon with a native module the same way, one layer down
+	* (`Could not locate the bindings file` instead of `Cannot find module`) —
+	* see {@link installRuntimeDependencies} and {@link installNativeDependencies}.
 	*
 	* Order matters and is `installFromTgz`'s: the tree is COMPLETED FIRST, and
 	* the live install is only then backed up and replaced. So the addon keeps
@@ -4803,8 +4859,8 @@ var AddonInstaller = class AddonInstaller {
 	* restored and the error is rethrown — identical recovery to `applyUpdate`.
 	*
 	* Throws if the package is not tracked in the manifest, if `addonDir`
-	* is missing (same preconditions as `applyUpdate`), or if the runtime-dep
-	* install fails.
+	* is missing (same preconditions as `applyUpdate`), or if the runtime-dep /
+	* native-dep install fails.
 	*/
 	async applyUpdateFromStaged(packageName, version, stagedPath) {
 		const current = this.manifest.get(packageName);
@@ -4812,6 +4868,7 @@ var AddonInstaller = class AddonInstaller {
 		const addonDir = node_path.join(this.addonsDir, packageName);
 		if (!node_fs.existsSync(addonDir)) throw new Error(`Cannot update ${packageName}: install dir ${addonDir} missing`);
 		await this.installRuntimeDependencies(stagedPath, packageName);
+		await this.installNativeDependencies(stagedPath, packageName);
 		const ts = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
 		const backupRoot = node_path.join(this.addonsDir, ".backups", packageName);
 		ensureDir(backupRoot);

package/dist/index.mjs

@@ -1,5 +1,5 @@
 import { a as __toCommonJS, i as __require, n as __esmMin, o as __toESM$1, r as __exportAll, t as __commonJSMin$1 } from "./chunk-CNf5ZN-e.mjs";
-import { $ as objectInputDeclaresAddonId, At as emitDownForOwnedCaps, B as isArrayOutputSchema, Bt as scopeKey, Ct as ReadinessRegistry, Dt as asNumber, Et as asJsonObject$1, G as kebabToCamel, H as isObjectInput, Ht as EventCategory$1, It as parseJsonObject, K as lifecycleJobSchema, Lt as parseJsonUnknown$1, Mt as expandCapMethods, Ot as asString$1, R as extractNestedAddonId, Rt as readinessKey, V as isCollectionArrayMethod, W as isVoidInput, X as looseSchema, Y as logLevelAtMost, _t as DATAPLANE_SECRET_HEADER$1, d as METHOD_ACCESS_MAP, f as RUNTIME_DEFAULTS, ht as errMsg$1, it as scopesAllowDeviceCap, kt as createEvent, nt as procedureAuthKey, rt as scopesAllowAddon, t as ALL_CAPABILITY_DEFINITIONS, vt as DEVICE_SETTINGS_CONTRIBUTION_METHODS, wt as ReadinessTimeoutError, y as addonSettingsCapability, yt as DEVICE_STATUS_METHOD, zt as resolveCapMount } from "./dist-BAwlOEUy.mjs";
+import { $ as objectInputDeclaresAddonId, At as emitDownForOwnedCaps, B as isArrayOutputSchema, Bt as scopeKey, Ct as ReadinessRegistry, Dt as asNumber, Et as asJsonObject$1, G as kebabToCamel, H as isObjectInput, Ht as EventCategory$1, It as parseJsonObject, K as lifecycleJobSchema, Lt as parseJsonUnknown$1, Mt as expandCapMethods, Ot as asString$1, R as extractNestedAddonId, Rt as readinessKey, V as isCollectionArrayMethod, W as isVoidInput, X as looseSchema, Y as logLevelAtMost, _t as DATAPLANE_SECRET_HEADER$1, d as METHOD_ACCESS_MAP, f as RUNTIME_DEFAULTS, ht as errMsg$1, it as scopesAllowDeviceCap, kt as createEvent, nt as procedureAuthKey, rt as scopesAllowAddon, t as ALL_CAPABILITY_DEFINITIONS, vt as DEVICE_SETTINGS_CONTRIBUTION_METHODS, wt as ReadinessTimeoutError, y as addonSettingsCapability, yt as DEVICE_STATUS_METHOD, zt as resolveCapMount } from "./dist-B90N7AWO.mjs";
 import { AlertCenterAddon } from "./builtins/alerts/alerts.addon.mjs";
 import "./builtins/alerts/index.mjs";
 import { t as formatLogLine } from "./formatter-B7qW8bPJ.mjs";
@@ -24,7 +24,7 @@ import { SystemConfigAddon } from "./builtins/system-config/system-config.addon.
 import "./builtins/system-config/index.mjs";
 import { WinstonDestination, WinstonLoggingAddon } from "./builtins/winston-logging/index.mjs";
 import { a as parseTokenizedUrl, c as collectModelFiles, d as downloadModel, f as ensureModel, h as isModelDownloaded, i as parseRangeHeader, l as deleteModelFromDisk, m as getModelFilePath, n as contentTypeFor, o as resolveFilePath, p as fetchJson, r as createAuthenticatedFileServer, s as ModelDownloadService, t as createFileDataPlaneHandler, u as downloadFile } from "./file-data-plane-CuE_hBli.mjs";
-import { $ as buildNativeCapProxy, A as createHubCapForwardService, B as AGENT_CAP_FWD_ACTION, C as brokerTransportLink, Ct as runNpm, D as localProviderLink, E as ipcParentLink, F as createUdsLogger, G as callWithServiceDiscovery, H as CapRouteResolver, I as createUdsLoggerWithControl, J as UdsLocalTransportServer, K as createLocalTransport, L as LocalChildClient, M as createUdsEventBridge, N as createUdsEventBus, O as HUB_CAP_FWD_ACTION, P as udsChildLogToWorkerEntry, Q as encodeFrame, R as LocalChildRegistry, S as brokerCallForCap, St as resolveNpmInvocation, T as ipcChildLink, U as CapRouteError, V as AGENT_CAP_FWD_SERVICE, W as classifyCapRoute, X as localEndpointPath, Y as SocketChannel, Z as FrameDecoder, _ as createKernelHwAccel, _t as CapabilityHandle, a as getWorkerDeviceRegistry, b as __resetCapUsageRegistryForTests, bt as installManifestNativeDeps, c as setHubConnected, ct as NATIVE_PROVIDER_SERVICE_INFIX, d as getBrokerEventBus, dt as capBareAction, et as buildUdsNativeCapProxy, f as getMoleculerEventStats, ft as capServiceName, g as AddonDepsManager, gt as DeviceRegistry, h as subscribePassthrough, ht as serializeTypedArrays, i as createUdsAddonContext, it as mountNativeCapService, j as createParentUnownedCallHandler, k as HUB_CAP_FWD_SERVICE, l as EVENT_TOPIC_PREFIX, lt as capActionName, m as setNodeEventInterest, mt as deserializeTypedArrays, n as adaptBrokerToCluster, o as getOrInitReadinessRegistry, ot as createAddonService, p as registerEventBusService, pt as parseCapAction, q as UdsLocalTransportClient, r as createAddonContext, s as getOrInitReadinessRegistryForClient, st as validateProviderRegistrations, t as installManifestPythonDeps, tt as createBrokerDeviceManagerApi, u as clusterEventTopic, ut as capActionSuffix, v as resolveHwAccel, vt as CapabilityUnavailableError, w as buildLinkChain, wt as createAddonDataPlaneFacility, x as getCapUsageRegistry, xt as resolveAddonClass, y as CapUsageRegistry, yt as copyBundledNativeModules, z as UDS_NO_ROUTE_PREFIX } from "./manifest-python-deps-C1DMs1J9.mjs";
+import { $ as buildNativeCapProxy, A as createHubCapForwardService, B as AGENT_CAP_FWD_ACTION, C as brokerTransportLink, Ct as runNpm, D as localProviderLink, E as ipcParentLink, F as createUdsLogger, G as callWithServiceDiscovery, H as CapRouteResolver, I as createUdsLoggerWithControl, J as UdsLocalTransportServer, K as createLocalTransport, L as LocalChildClient, M as createUdsEventBridge, N as createUdsEventBus, O as HUB_CAP_FWD_ACTION, P as udsChildLogToWorkerEntry, Q as encodeFrame, R as LocalChildRegistry, S as brokerCallForCap, St as resolveNpmInvocation, T as ipcChildLink, U as CapRouteError, V as AGENT_CAP_FWD_SERVICE, W as classifyCapRoute, X as localEndpointPath, Y as SocketChannel, Z as FrameDecoder, _ as createKernelHwAccel, _t as CapabilityHandle, a as getWorkerDeviceRegistry, b as __resetCapUsageRegistryForTests, bt as installManifestNativeDeps, c as setHubConnected, ct as NATIVE_PROVIDER_SERVICE_INFIX, d as getBrokerEventBus, dt as capBareAction, et as buildUdsNativeCapProxy, f as getMoleculerEventStats, ft as capServiceName, g as AddonDepsManager, gt as DeviceRegistry, h as subscribePassthrough, ht as serializeTypedArrays, i as createUdsAddonContext, it as mountNativeCapService, j as createParentUnownedCallHandler, k as HUB_CAP_FWD_SERVICE, l as EVENT_TOPIC_PREFIX, lt as capActionName, m as setNodeEventInterest, mt as deserializeTypedArrays, n as adaptBrokerToCluster, o as getOrInitReadinessRegistry, ot as createAddonService, p as registerEventBusService, pt as parseCapAction, q as UdsLocalTransportClient, r as createAddonContext, s as getOrInitReadinessRegistryForClient, st as validateProviderRegistrations, t as installManifestPythonDeps, tt as createBrokerDeviceManagerApi, u as clusterEventTopic, ut as capActionSuffix, v as resolveHwAccel, vt as CapabilityUnavailableError, w as buildLinkChain, wt as createAddonDataPlaneFacility, x as getCapUsageRegistry, xt as resolveAddonClass, y as CapUsageRegistry, yt as copyBundledNativeModules, z as UDS_NO_ROUTE_PREFIX } from "./manifest-python-deps-fWzdEasI.mjs";
 import { n as getSinglePidStats, t as getPidStats } from "./resource-monitor-BWmQ5i-o.mjs";
 import { t as CustomActionRegistry } from "./custom-action-registry-F__gp_VX.mjs";
 import { z } from "zod";
@@ -4219,6 +4219,12 @@ var AddonInstaller = class AddonInstaller {
 	* installs from the admin UI go through `install()` instead, which
 	* defaults to npm in production.
 	*
+	* There is no version argument and there is deliberately no pin: the system is
+	* addons-agnostic and `latest` is the whole contract at first boot (operator,
+	* 2026-08-13). A copy already under the addon root is never replaced either —
+	* bootstrap is seed-only, and overwriting a deployed bundle would be an
+	* un-deploy ([D90](../../../../docs/decisions/adr-0090.md)).
+	*
 	* @param packages — optional custom package list (default: REQUIRED_PACKAGES)
 	*/
 	async ensureRequiredPackages(packages) {
@@ -4643,6 +4649,61 @@ var AddonInstaller = class AddonInstaller {
 			throw new Error(`${packageName} — runtime dependency install failed: ${errMsg$1(err)}`, { cause: err });
 		}
 	}
+	/**
+	* Make `pkgDir`'s NATIVE modules loadable on THIS host, before it is swapped
+	* in: install whatever `camstack.nativeDependencies` declares, then ensure
+	* every traditional native present in the tree actually carries a compiled
+	* `.node` for the running ABI.
+	*
+	* ONE implementation, for the same reason as {@link installRuntimeDependencies}
+	* — every path that materialises an addon tree calls it, so no call site can
+	* forget it. `installFromTgz` (deploy/upload) always ran these two steps; the
+	* OTA staged-swap path ran NEITHER even after the runtime-dep fix (2026-08-12,
+	* task #15, which named this gap explicitly). Same outage class one layer
+	* down: an addon with native modules was broken by its FIRST OTA update, its
+	* dist landing without an ABI-matched binary, and every load dying at the
+	* binding (`Could not locate the bindings file`) — from the outside
+	* indistinguishable from a bad bundle.
+	*
+	* **Two distinct steps, both load-bearing.**
+	* `installManifestNativeDeps` fetches the DECLARED natives (prebuilt host copy
+	* first — offline — then npm + an ABI rebuild), and is idempotent through a
+	* content-hash marker. `ensureAddonNativePrebuilds` is the post-install pass:
+	* npm can leave a traditional native (`better-sqlite3`) SOURCE-ONLY on a
+	* toolchain-less host, so it re-fetches the prebuild for the running ABI and
+	* THROWS naming module + addon if the binary is still absent. No bundled
+	* source is available on this path (unlike `installCopy`) — fetch only.
+	*
+	* **Failure is FATAL**, mirroring the tgz path: callers complete the tree
+	* BEFORE they swap, so an abort simply means the swap never happens and the
+	* previous version keeps serving. Shipping a native-less copy instead would
+	* trade one broken version for a crash-loop.
+	*
+	* A missing/unreadable manifest is logged and skipped — `installRuntimeDependencies`
+	* has already said so loudly, and a tree with no readable package.json
+	* declares no natives.
+	*/
+	async installNativeDependencies(pkgDir, packageName) {
+		const pkgJsonPath = path$39.join(pkgDir, "package.json");
+		const pkgView = readPackageJson(pkgJsonPath);
+		if (pkgView == null) {
+			this.logger.error(`${packageName} — no readable package.json in the prepared tree; native dependencies NOT installed`, { meta: { pkgJsonPath } });
+			return;
+		}
+		try {
+			await installManifestNativeDeps(pkgDir, pkgView.raw, this.logger, this.registry, this.npmCacheDir);
+		} catch (nativeErr) {
+			this.logger.error(`${packageName} — native dependency install FAILED; install ABORTED (a swapped-in copy would fail every load at the binding)`, { meta: {
+				pkgDir,
+				error: errMsg$1(nativeErr)
+			} });
+			throw new Error(`${packageName} — native deps install failed: ${errMsg$1(nativeErr)}`, { cause: nativeErr });
+		}
+		await ensureAddonNativePrebuilds(pkgDir, {
+			addonName: packageName,
+			logger: this.logger
+		});
+	}
 	/** Install addon from a tgz file (uploaded or downloaded) */
 	async installFromTgz(tgzPath) {
 		const stagingRoot = path$39.join(this.addonsDir, ".staging");
@@ -4667,15 +4728,7 @@ var AddonInstaller = class AddonInstaller {
 			if (!pkgView.camstackAddons) throw new Error(`Package ${pkgView.name} has no camstack.addons manifest`);
 			const targetDir = path$39.join(this.addonsDir, pkgView.name);
 			await this.installRuntimeDependencies(pkgDir, pkgView.name);
-			try {
-				await installManifestNativeDeps(pkgDir, pkgView.raw, this.logger, this.registry, this.npmCacheDir);
-			} catch (nativeErr) {
-				throw new Error(`${pkgView.name} — native deps install failed: ${errMsg$1(nativeErr)}`, { cause: nativeErr });
-			}
-			await ensureAddonNativePrebuilds(pkgDir, {
-				addonName: pkgView.name,
-				logger: this.logger
-			});
+			await this.installNativeDependencies(pkgDir, pkgView.name);
 			await this.evictInstallDir(targetDir);
 			ensureDir(path$39.dirname(targetDir));
 			await fs$17.promises.rename(pkgDir, targetDir);
@@ -4780,9 +4833,12 @@ var AddonInstaller = class AddonInstaller {
 	*
 	* "Skips npm entirely" is true only of the REGISTRY round-trip: the staged
 	* tree is the raw unpacked tarball, so the addon's own
-	* `camstack.runtimeDependencies` still have to be installed into it, exactly
-	* as `installFromTgz` does. Skipping that is what broke every runtime-dep
-	* addon on its first OTA update — see {@link installRuntimeDependencies}.
+	* `camstack.runtimeDependencies` AND `camstack.nativeDependencies` still have
+	* to be installed into it, exactly as `installFromTgz` does. Skipping the
+	* first broke every runtime-dep addon on its first OTA update; skipping the
+	* second broke every addon with a native module the same way, one layer down
+	* (`Could not locate the bindings file` instead of `Cannot find module`) —
+	* see {@link installRuntimeDependencies} and {@link installNativeDependencies}.
 	*
 	* Order matters and is `installFromTgz`'s: the tree is COMPLETED FIRST, and
 	* the live install is only then backed up and replaced. So the addon keeps
@@ -4795,8 +4851,8 @@ var AddonInstaller = class AddonInstaller {
 	* restored and the error is rethrown — identical recovery to `applyUpdate`.
 	*
 	* Throws if the package is not tracked in the manifest, if `addonDir`
-	* is missing (same preconditions as `applyUpdate`), or if the runtime-dep
-	* install fails.
+	* is missing (same preconditions as `applyUpdate`), or if the runtime-dep /
+	* native-dep install fails.
 	*/
 	async applyUpdateFromStaged(packageName, version, stagedPath) {
 		const current = this.manifest.get(packageName);
@@ -4804,6 +4860,7 @@ var AddonInstaller = class AddonInstaller {
 		const addonDir = path$39.join(this.addonsDir, packageName);
 		if (!fs$17.existsSync(addonDir)) throw new Error(`Cannot update ${packageName}: install dir ${addonDir} missing`);
 		await this.installRuntimeDependencies(stagedPath, packageName);
+		await this.installNativeDependencies(stagedPath, packageName);
 		const ts = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
 		const backupRoot = path$39.join(this.addonsDir, ".backups", packageName);
 		ensureDir(backupRoot);

package/dist/kernel/addon-installer.d.ts

@@ -186,6 +186,12 @@ export declare class AddonInstaller {
      * installs from the admin UI go through `install()` instead, which
      * defaults to npm in production.
      *
+     * There is no version argument and there is deliberately no pin: the system is
+     * addons-agnostic and `latest` is the whole contract at first boot (operator,
+     * 2026-08-13). A copy already under the addon root is never replaced either —
+     * bootstrap is seed-only, and overwriting a deployed bundle would be an
+     * un-deploy ([D90](../../../../docs/decisions/adr-0090.md)).
+     *
      * @param packages — optional custom package list (default: REQUIRED_PACKAGES)
      */
     ensureRequiredPackages(packages?: readonly string[]): Promise<void>;
@@ -341,6 +347,41 @@ export declare class AddonInstaller {
      * package entirely).
      */
     private installRuntimeDependencies;
+    /**
+     * Make `pkgDir`'s NATIVE modules loadable on THIS host, before it is swapped
+     * in: install whatever `camstack.nativeDependencies` declares, then ensure
+     * every traditional native present in the tree actually carries a compiled
+     * `.node` for the running ABI.
+     *
+     * ONE implementation, for the same reason as {@link installRuntimeDependencies}
+     * — every path that materialises an addon tree calls it, so no call site can
+     * forget it. `installFromTgz` (deploy/upload) always ran these two steps; the
+     * OTA staged-swap path ran NEITHER even after the runtime-dep fix (2026-08-12,
+     * task #15, which named this gap explicitly). Same outage class one layer
+     * down: an addon with native modules was broken by its FIRST OTA update, its
+     * dist landing without an ABI-matched binary, and every load dying at the
+     * binding (`Could not locate the bindings file`) — from the outside
+     * indistinguishable from a bad bundle.
+     *
+     * **Two distinct steps, both load-bearing.**
+     * `installManifestNativeDeps` fetches the DECLARED natives (prebuilt host copy
+     * first — offline — then npm + an ABI rebuild), and is idempotent through a
+     * content-hash marker. `ensureAddonNativePrebuilds` is the post-install pass:
+     * npm can leave a traditional native (`better-sqlite3`) SOURCE-ONLY on a
+     * toolchain-less host, so it re-fetches the prebuild for the running ABI and
+     * THROWS naming module + addon if the binary is still absent. No bundled
+     * source is available on this path (unlike `installCopy`) — fetch only.
+     *
+     * **Failure is FATAL**, mirroring the tgz path: callers complete the tree
+     * BEFORE they swap, so an abort simply means the swap never happens and the
+     * previous version keeps serving. Shipping a native-less copy instead would
+     * trade one broken version for a crash-loop.
+     *
+     * A missing/unreadable manifest is logged and skipped — `installRuntimeDependencies`
+     * has already said so loudly, and a tree with no readable package.json
+     * declares no natives.
+     */
+    private installNativeDependencies;
     /** Install addon from a tgz file (uploaded or downloaded) */
     installFromTgz(tgzPath: string): Promise<{
         name: string;
@@ -381,9 +422,12 @@ export declare class AddonInstaller {
      *
      * "Skips npm entirely" is true only of the REGISTRY round-trip: the staged
      * tree is the raw unpacked tarball, so the addon's own
-     * `camstack.runtimeDependencies` still have to be installed into it, exactly
-     * as `installFromTgz` does. Skipping that is what broke every runtime-dep
-     * addon on its first OTA update — see {@link installRuntimeDependencies}.
+     * `camstack.runtimeDependencies` AND `camstack.nativeDependencies` still have
+     * to be installed into it, exactly as `installFromTgz` does. Skipping the
+     * first broke every runtime-dep addon on its first OTA update; skipping the
+     * second broke every addon with a native module the same way, one layer down
+     * (`Could not locate the bindings file` instead of `Cannot find module`) —
+     * see {@link installRuntimeDependencies} and {@link installNativeDependencies}.
      *
      * Order matters and is `installFromTgz`'s: the tree is COMPLETED FIRST, and
      * the live install is only then backed up and replaced. So the addon keeps
@@ -396,8 +440,8 @@ export declare class AddonInstaller {
      * restored and the error is rethrown — identical recovery to `applyUpdate`.
      *
      * Throws if the package is not tracked in the manifest, if `addonDir`
-     * is missing (same preconditions as `applyUpdate`), or if the runtime-dep
-     * install fails.
+     * is missing (same preconditions as `applyUpdate`), or if the runtime-dep /
+     * native-dep install fails.
      */
     applyUpdateFromStaged(packageName: string, version: string, stagedPath: string): Promise<{
         name: string;

package/dist/kernel/moleculer/event-bus-core.d.ts

@@ -2,7 +2,12 @@ import { EventFilter, SystemEvent } from '@camstack/types';
 export interface SubscriberEntry {
     /** Original filter — kept whole so non-category dimensions are honoured per-event. */
     readonly filter: EventFilter | string | undefined;
-    /** Pre-computed category pattern for the cheap pre-filter. */
+    /**
+     * Pre-computed category pattern for the cheap pre-filter — the FIRST of
+     * {@link extractCategoryPatterns} when the filter names several. Diagnostic
+     * only: the authority on which keys an entry occupies is the handler map
+     * itself, written by {@link registerSubscriber}.
+     */
     readonly categoryPattern: string;
     readonly handler: (event: SystemEvent) => void;
 }
@@ -47,7 +52,48 @@ export interface SharedBusState {
  */
 export declare function createSharedBusState(retainRecent?: boolean): SharedBusState;
 export declare function matchesPattern(pattern: string, category: string): boolean;
+/**
+ * The FIRST category pattern of a filter.
+ *
+ * Kept for the diagnostic `SubscriberEntry.categoryPattern` field and for
+ * callers that genuinely want one string. It is NOT the registration path:
+ * a filter naming several categories must occupy several map keys, which is
+ * what {@link extractCategoryPatterns} + {@link registerSubscriber} do. Using
+ * this function to key a subscriber is the bug described on
+ * `extractCategoryPatterns`.
+ */
 export declare function extractCategoryPattern(filter: EventFilter | string): string;
+/**
+ * EVERY category pattern a filter asks for — the registration key set.
+ *
+ * `EventFilter.category` has always accepted an array, and until 2026-08-12
+ * the delivery path kept only `cat[0]`. Inside a forked runner that was not
+ * merely a local filter: `createUdsEventBus` reports its handler-map keys to
+ * the parent as this child's forwarding interest, so the categories that never
+ * became keys were never forwarded across the process boundary at all. A
+ * ten-category subscribe received one category, silently.
+ *
+ * Duplicates are collapsed so a filter that names the same category twice does
+ * not put the entry in one key twice.
+ */
+export declare function extractCategoryPatterns(filter: EventFilter | string): readonly string[];
+/**
+ * Register one handler under every category pattern its filter names, and
+ * return the unsubscribe that removes it from all of them.
+ *
+ * The ONE place a subscriber enters `state.handlers` — both bus
+ * implementations (broker and UDS) call it, so "which keys does this
+ * subscriber occupy" has a single answer. An emptied key is DELETED rather
+ * than left as an empty `Set`: on a child bus the key set is what the parent
+ * is told to forward, and an empty set left behind pins the parent to forward
+ * a category nobody wants.
+ *
+ * @param onKeysChanged - Called after the key set may have changed (both on
+ *   registration and on unsubscribe), for buses that mirror their key set
+ *   somewhere — the UDS child's parent report, the broker's local-interest
+ *   surface. Receives the patterns this call touched.
+ */
+export declare function registerSubscriber(state: SharedBusState, filter: EventFilter | string, handler: (event: SystemEvent) => void, onKeysChanged?: (patterns: readonly string[], added: boolean) => void): () => void;
 /**
  * Match an event against the full `EventFilter`. The Map-keyed subscribe path
  * only handles the category pattern (deciding which handler set to fan out to);

package/dist/kernel/transport/child-cap-protocol.d.ts

@@ -62,6 +62,32 @@ export interface CapCallOutMessage {
      * `platform-probe` hardware). Set via `ctx.api`'s `onNode(nodeId)` modifier.
      */
     readonly nodeId?: string;
+    /**
+     * "Resolve the per-device NATIVE provider for this cap, never a wrapper."
+     * Set by `ctx.getNativeProvider(...)` in a forked runner.
+     *
+     * ## Why a flag and not just the cap name
+     *
+     * A wrapper and its natives share ONE cap name. As long as the wrapper lived
+     * in hub-main that was harmless — the wrapper resolved its native through the
+     * hub's `CapabilityRegistry`, which knows the difference. A wrapper in a
+     * runner has no such registry, and every generic route back out of the
+     * process resolves `capName` the way every OTHER caller does: to the wrapper.
+     * `localProviderLink` answers it from the runner's own provider before the
+     * call ever reaches the socket, and `resolveChildId` would hand it back to
+     * the wrapper's own child if it did. Either way the wrapper calls itself:
+     * the second entry joins the first's single flight and waits on a promise
+     * only it can settle.
+     *
+     * So the intent has to travel. `native: true` makes the parent skip
+     * capName-based resolution entirely and ask the ONE native authority
+     * (`CapabilityRegistry.getNativeProvider`, which covers in-process natives,
+     * hub-local UDS vendor children and remote agents alike) for `(cap, device)`.
+     * With no native for the pair the call FAILS — it never degrades into the
+     * wrapper — with a message a wrapper can read as "absent" and fall through to
+     * its own strategy.
+     */
+    readonly native?: boolean;
 }
 /** Child → parent: a system event produced by the child to be forwarded to the hub event bus. */
 export interface ChildEventMessage {
@@ -110,6 +136,12 @@ export interface CapCallMessage {
      * the child dispatch falls back to its sole provider for the cap.
      */
     readonly addonId?: string;
+    /**
+     * Native-only routing hint — see {@link CapCallOutMessage.native}. Carried
+     * here because `CapCallInput` (the type every parent-side router takes) is
+     * this message minus its discriminant; a child DISPATCH ignores it.
+     */
+    readonly native?: boolean;
 }
 /** Parent → child: a system event delivered by the hub for the child to handle locally. */
 export interface ParentEventMessage {

package/dist/kernel/transport/hub-cap-forward.d.ts

@@ -16,6 +16,14 @@ export interface HubCapForwardParams {
     readonly args: unknown;
     readonly deviceId?: number;
     readonly nodeId?: string;
+    /**
+     * Native-only routing hint (see `CapCallOutMessage.native`). An agent has no
+     * native authority of its own, so a forked wrapper on an agent asking for a
+     * per-device native forwards the question here. It MUST survive the envelope:
+     * without it the hub resolves the cap NAME, i.e. the wrapper the caller is
+     * trying to skip.
+     */
+    readonly native?: boolean;
 }
 /**
  * Handler that routes an agent-originated cap call through the hub's own

package/dist/kernel/transport/parent-unowned-call.d.ts

@@ -183,6 +183,25 @@ export interface ParentUnownedCallDeps {
      * exactly: the miss falls straight to the broker fallback with no retry.
      */
     readonly isCoreServiceCap?: (capName: string) => boolean;
+    /**
+     * Resolve the per-device NATIVE provider for `(capName, deviceId)` — the
+     * `native: true` route (see {@link CapCallInput.native}).
+     *
+     * Wired to this node's `CapabilityRegistry.getNativeProvider`, which is the
+     * SINGLE authority on the question: it already covers in-process natives,
+     * hub-local UDS vendor children (through the hub's `setNativeFallback`
+     * resolver) and remote agents. Nothing here re-derives that — a rule
+     * implemented twice is a rule that drifts, and this one previously drifted
+     * into a wrapper answering on behalf of the native it was supposed to call.
+     *
+     * Returns null when no addon publishes the cap for that device. The handler
+     * then FAILS the call rather than falling back to capName routing: falling
+     * back is how a wrapper ends up calling itself.
+     *
+     * Omitted ⇒ a `native: true` call is forwarded to the hub (agents) or
+     * rejected (no forwarder) — never silently downgraded to wrapper routing.
+     */
+    readonly resolveNative?: (capName: string, deviceId: number) => Record<string, (input: unknown) => Promise<unknown>> | null;
     /** Optional logger for the broker-fallback diagnostic line. */
     readonly logger?: ParentUnownedCallLogger;
 }