@camstack/system 1.2.3 → 1.2.5

package/dist/builtins/device-manager/device-linked-devices.d.ts

@@ -4,7 +4,9 @@ import { ProviderContext } from './device-provider-context.js';
 export declare const LINKED_MODE_CONFIG_KEY = "_linkedDevicesMode";
 export declare const LINKED_IDS_CONFIG_KEY = "_linkedDeviceIds";
 /** Reserved key: subset of linked devices that materialize synthetic tracked
- *  events on the camera. Absent ⇒ ALL linked devices produce tracked events. */
+ *  events on the camera. Absent ⇒ NONE — producing tracked events is an
+ *  explicit operator OPT-IN (2026-07-22 flip: the old absent⇒ALL default
+ *  auto-materialized sensor snapshots the operator never asked for). */
 export declare const LINKED_TRACKED_IDS_CONFIG_KEY = "_linkedDeviceTrackedIds";
 export interface LinkedDevicesConfig {
     readonly mode: DeviceLinkMode;
@@ -32,8 +34,9 @@ export declare function resolveLinkedDeviceIds(params: {
 }): readonly number[];
 /**
  * Which linked devices materialize synthetic tracked events on the camera.
- * Absent / non-array config key ⇒ ALL linked devices (back-compat with the
- * pre-existing "every linked device produces events" behaviour). Otherwise the
+ * Absent / non-array config key ⇒ NONE — the operator must explicitly pick
+ * producers (opt-in; flipped from the legacy absent⇒ALL default, which
+ * auto-materialized sensor snapshots for every linked device). Otherwise the
  * configured subset intersected with the currently-resolved linked set (a
  * picked id no longer linked is dropped). Ids may arrive as numbers or numeric
  * strings (the multiselect stores string option values); non-numeric entries

package/dist/builtins/device-manager/device-manager.addon.js

@@ -1210,7 +1210,9 @@ async function testField(pctx, input) {
 var LINKED_MODE_CONFIG_KEY = "_linkedDevicesMode";
 var LINKED_IDS_CONFIG_KEY = "_linkedDeviceIds";
 /** Reserved key: subset of linked devices that materialize synthetic tracked
-*  events on the camera. Absent ⇒ ALL linked devices produce tracked events. */
+*  events on the camera. Absent ⇒ NONE — producing tracked events is an
+*  explicit operator OPT-IN (2026-07-22 flip: the old absent⇒ALL default
+*  auto-materialized sensor snapshots the operator never asked for). */
 var LINKED_TRACKED_IDS_CONFIG_KEY = "_linkedDeviceTrackedIds";
 /** Parse the two reserved keys out of a device-config blob. Tolerant:
 *  ids may arrive as numbers or numeric strings (the multiselect field
@@ -1249,8 +1251,9 @@ function resolveLinkedDeviceIds(params) {
 }
 /**
 * Which linked devices materialize synthetic tracked events on the camera.
-* Absent / non-array config key ⇒ ALL linked devices (back-compat with the
-* pre-existing "every linked device produces events" behaviour). Otherwise the
+* Absent / non-array config key ⇒ NONE — the operator must explicitly pick
+* producers (opt-in; flipped from the legacy absent⇒ALL default, which
+* auto-materialized sensor snapshots for every linked device). Otherwise the
 * configured subset intersected with the currently-resolved linked set (a
 * picked id no longer linked is dropped). Ids may arrive as numbers or numeric
 * strings (the multiselect stores string option values); non-numeric entries
@@ -1258,7 +1261,7 @@ function resolveLinkedDeviceIds(params) {
 */
 function resolveTrackedEventDeviceIds(config, linkedIds) {
 	const raw = config[LINKED_TRACKED_IDS_CONFIG_KEY];
-	if (!Array.isArray(raw)) return linkedIds;
+	if (!Array.isArray(raw)) return [];
 	const picked = /* @__PURE__ */ new Set();
 	for (const v of raw) {
 		const n = typeof v === "number" ? v : typeof v === "string" ? Number(v) : NaN;
@@ -1363,7 +1366,7 @@ async function buildLinkedDevicesContribution(pctx, deviceId) {
 				type: "multiselect",
 				key: LINKED_TRACKED_IDS_CONFIG_KEY,
 				label: "Devices that produce tracked events",
-				description: "Linked devices whose state changes materialize a synthetic tracked event on this camera. Default: all linked devices.",
+				description: "Linked devices whose state changes materialize a synthetic tracked event on this camera. Default: none (opt-in).",
 				options: trackedOptions,
 				value: trackedValue
 			}
@@ -1396,7 +1399,11 @@ async function applyLinkedDevicesPatch(pctx, deviceId, patch) {
 //#region src/builtins/device-manager/device-store-sections.ts
 /** The device-manager's device-store-backed sections. Add an entry to extend. */
 var DEVICE_STORE_SECTIONS = [{
-	keys: [LINKED_MODE_CONFIG_KEY, LINKED_IDS_CONFIG_KEY],
+	keys: [
+		LINKED_MODE_CONFIG_KEY,
+		LINKED_IDS_CONFIG_KEY,
+		LINKED_TRACKED_IDS_CONFIG_KEY
+	],
 	apply: (pctx, deviceId, patch) => applyLinkedDevicesPatch(pctx, deviceId, patch)
 }];
 /**

package/dist/builtins/device-manager/device-manager.addon.mjs

@@ -1205,7 +1205,9 @@ async function testField(pctx, input) {
 var LINKED_MODE_CONFIG_KEY = "_linkedDevicesMode";
 var LINKED_IDS_CONFIG_KEY = "_linkedDeviceIds";
 /** Reserved key: subset of linked devices that materialize synthetic tracked
-*  events on the camera. Absent ⇒ ALL linked devices produce tracked events. */
+*  events on the camera. Absent ⇒ NONE — producing tracked events is an
+*  explicit operator OPT-IN (2026-07-22 flip: the old absent⇒ALL default
+*  auto-materialized sensor snapshots the operator never asked for). */
 var LINKED_TRACKED_IDS_CONFIG_KEY = "_linkedDeviceTrackedIds";
 /** Parse the two reserved keys out of a device-config blob. Tolerant:
 *  ids may arrive as numbers or numeric strings (the multiselect field
@@ -1244,8 +1246,9 @@ function resolveLinkedDeviceIds(params) {
 }
 /**
 * Which linked devices materialize synthetic tracked events on the camera.
-* Absent / non-array config key ⇒ ALL linked devices (back-compat with the
-* pre-existing "every linked device produces events" behaviour). Otherwise the
+* Absent / non-array config key ⇒ NONE — the operator must explicitly pick
+* producers (opt-in; flipped from the legacy absent⇒ALL default, which
+* auto-materialized sensor snapshots for every linked device). Otherwise the
 * configured subset intersected with the currently-resolved linked set (a
 * picked id no longer linked is dropped). Ids may arrive as numbers or numeric
 * strings (the multiselect stores string option values); non-numeric entries
@@ -1253,7 +1256,7 @@ function resolveLinkedDeviceIds(params) {
 */
 function resolveTrackedEventDeviceIds(config, linkedIds) {
 	const raw = config[LINKED_TRACKED_IDS_CONFIG_KEY];
-	if (!Array.isArray(raw)) return linkedIds;
+	if (!Array.isArray(raw)) return [];
 	const picked = /* @__PURE__ */ new Set();
 	for (const v of raw) {
 		const n = typeof v === "number" ? v : typeof v === "string" ? Number(v) : NaN;
@@ -1358,7 +1361,7 @@ async function buildLinkedDevicesContribution(pctx, deviceId) {
 				type: "multiselect",
 				key: LINKED_TRACKED_IDS_CONFIG_KEY,
 				label: "Devices that produce tracked events",
-				description: "Linked devices whose state changes materialize a synthetic tracked event on this camera. Default: all linked devices.",
+				description: "Linked devices whose state changes materialize a synthetic tracked event on this camera. Default: none (opt-in).",
 				options: trackedOptions,
 				value: trackedValue
 			}
@@ -1391,7 +1394,11 @@ async function applyLinkedDevicesPatch(pctx, deviceId, patch) {
 //#region src/builtins/device-manager/device-store-sections.ts
 /** The device-manager's device-store-backed sections. Add an entry to extend. */
 var DEVICE_STORE_SECTIONS = [{
-	keys: [LINKED_MODE_CONFIG_KEY, LINKED_IDS_CONFIG_KEY],
+	keys: [
+		LINKED_MODE_CONFIG_KEY,
+		LINKED_IDS_CONFIG_KEY,
+		LINKED_TRACKED_IDS_CONFIG_KEY
+	],
 	apply: (pctx, deviceId, patch) => applyLinkedDevicesPatch(pctx, deviceId, patch)
 }];
 /**

package/dist/index.d.ts

@@ -85,4 +85,5 @@ export type { DirectCallerOptions } from './addon/addon-api-factory.js';
 export { IntegrationRegistry } from './builtins/sqlite-storage/integration-registry.js';
 export * from './kernel/index.js';
 export { runNpm, resolveNpmInvocation, type RunNpmOptions, type NpmInvocation, } from './kernel/deps/npm-command.js';
-export { ensureNativePrebuilds, TRADITIONAL_NATIVE_PACKAGES, type EnsureNativePrebuildsOptions, type PrebuildTarget, type PrebuildFetchFn, } from './kernel/deps/ensure-native-prebuilds.js';
+export { ensureNativePrebuilds, hasDotNode, NATIVE_SCAN_DEPTH, TRADITIONAL_NATIVE_PACKAGES, type EnsureNativePrebuildsOptions, type PrebuildTarget, type PrebuildFetchFn, } from './kernel/deps/ensure-native-prebuilds.js';
+export { ensureAddonNativePrebuilds, type EnsureAddonNativePrebuildsOptions, type NativeEnsureOutcome, type NativeEnsureResult, } from './kernel/deps/ensure-addon-natives.js';

package/dist/index.js

@@ -3030,8 +3030,270 @@ var AddonManifest = class {
 	}
 };
 //#endregion
-//#region src/kernel/addon-installer.ts
+//#region src/kernel/deps/ensure-native-prebuilds.ts
+/**
+* `ensureNativePrebuilds` — the post-install native-prebuild ENSURE step the
+* shared `RootUpdateService` runs while staging a `@camstack/server` closure,
+* BEFORE its `findMissingNativePrebuilds` validator (in `@camstack/node-root`)
+* decides whether to arm the swap.
+*
+* Why this exists (Mac desktop incident, 2026-07-21): a runtime
+* `applyServerUpdate` on a packaged desktop stages the closure with
+* `npm install @camstack/server@X` under the app's BUNDLED bare Node. The one
+* TRADITIONAL (non-N-API) native, `better-sqlite3`, resolves its `.node` via
+* its `install` script `prebuild-install || node-gyp rebuild`. On a user's Mac
+* with no build toolchain (and where the auto `prebuild-install` does not
+* target the bundled Node's ABI/arch the way the DMG build's EXPLICIT
+* `prebuild-install --runtime node --target <bundled> --arch <arch>` call does)
+* that leaves the module SOURCE-ONLY → the closure has no `better-sqlite3`
+* `.node` → the validator refuses the swap ("staged closure missing native
+* prebuilds: better-sqlite3"). The docker image never hits this: its Node ABI
+* has a published prebuild the auto path fetches cleanly, and it carries a
+* build toolchain fallback.
+*
+* This mirrors the DMG build's explicit re-fetch (`scripts/stage-deps.mjs`)
+* into the runtime staging path: for each traditional native that is present
+* in the closure but missing its compiled `.node`, fetch the prebuild for the
+* RUNNING Node ABI/arch (the same Node that will load the swapped closure).
+*
+* N-API natives (`sharp`, `node-av`) are ABI-stable and ship their binaries as
+* platform SIBLING packages that npm fetches reliably with no compile step, so
+* they are not in scope here — a genuine miss there is a broken install the
+* validator should still reject, not something a prebuild re-fetch can heal.
+*
+* Injected into the update service from the construction site so the zero-dep
+* `@camstack/node-root` layer never depends on npm/@camstack/system, and the
+* fetch is unit-testable with a fake fetcher.
+*/
 var execFileAsync$1 = (0, node_util.promisify)(node_child_process.execFile);
+/** Bounded recursive `.node` scan depth inside a module dir. */
+var NATIVE_SCAN_DEPTH = 4;
+/** Timeout for a single `prebuild-install` fetch. */
+var PREBUILD_FETCH_TIMEOUT_MS = 12e4;
+/**
+* Traditional (compile-or-prebuild) natives an installed closure must carry a
+* `.node` for. Only these are ENSURE-able by a prebuild re-fetch; N-API natives
+* are excluded (see file header).
+*/
+var TRADITIONAL_NATIVE_PACKAGES = ["better-sqlite3"];
+/** Bounded recursive scan for ANY `*.node` file under `dir`. */
+function hasDotNode(dir, maxDepth) {
+	let entries;
+	try {
+		entries = node_fs.readdirSync(dir, { withFileTypes: true });
+	} catch {
+		return false;
+	}
+	for (const entry of entries) if (entry.isFile() && entry.name.endsWith(".node")) return true;
+	if (maxDepth <= 0) return false;
+	for (const entry of entries) if (entry.isDirectory() && hasDotNode(node_path.join(dir, entry.name), maxDepth - 1)) return true;
+	return false;
+}
+/** Locate the bundled `prebuild-install` bin.js inside the staged closure. */
+function resolvePrebuildInstallBin(closureDir, moduleDir) {
+	return [node_path.join(moduleDir, "node_modules", "prebuild-install", "bin.js"), node_path.join(closureDir, "node_modules", "prebuild-install", "bin.js")].find((c) => node_fs.existsSync(c)) ?? null;
+}
+/**
+* Default fetcher: run the closure's own `prebuild-install` under the CURRENT
+* Node (`process.execPath`) — no reliance on `npx`/`npm` on PATH (a packaged
+* app ships a bare Node). Explicitly targets the running ABI/arch, mirroring
+* `scripts/stage-deps.mjs`.
+*/
+function makeDefaultFetch(closureDir, logger) {
+	return async (moduleDir, target) => {
+		const bin = resolvePrebuildInstallBin(closureDir, moduleDir);
+		if (bin === null) throw new Error(`prebuild-install not found in the staged closure for ${moduleDir}`);
+		logger.info("fetching native prebuild via prebuild-install", { meta: {
+			moduleDir,
+			bin,
+			nodeVersion: target.nodeVersion,
+			arch: target.arch
+		} });
+		await execFileAsync$1(process.execPath, [
+			bin,
+			"--runtime",
+			"node",
+			"--target",
+			target.nodeVersion,
+			"--arch",
+			target.arch
+		], {
+			cwd: moduleDir,
+			timeout: PREBUILD_FETCH_TIMEOUT_MS
+		});
+	};
+}
+/**
+* Ensure every traditional native in `<closureDir>/node_modules` carries its
+* compiled `.node`, fetching the prebuild for the running ABI when missing.
+*
+* A NO-OP when nothing is missing (docker / tests) and when a native package is
+* absent from the closure. Never throws for a single package's fetch failure —
+* it logs and continues so the downstream `findMissingNativePrebuilds`
+* validator makes the final swap/abort decision. Returns the packages whose
+* prebuild was successfully fetched (for logging/tests).
+*/
+async function ensureNativePrebuilds(closureDir, options) {
+	const nm = node_path.join(closureDir, "node_modules");
+	const target = options.target ?? {
+		nodeVersion: process.versions.node,
+		arch: process.arch
+	};
+	const packages = options.packages ?? TRADITIONAL_NATIVE_PACKAGES;
+	const fetchPrebuild = options.fetchPrebuild ?? makeDefaultFetch(closureDir, options.logger);
+	const fetched = [];
+	for (const pkg of packages) {
+		const moduleDir = node_path.join(nm, pkg);
+		if (!node_fs.existsSync(moduleDir)) continue;
+		if (hasDotNode(moduleDir, 4)) continue;
+		options.logger.warn("staged closure native prebuild missing — fetching for running ABI", { meta: {
+			pkg,
+			moduleDir,
+			nodeVersion: target.nodeVersion,
+			arch: target.arch
+		} });
+		try {
+			await fetchPrebuild(moduleDir, target);
+		} catch (err) {
+			options.logger.error("native prebuild fetch failed (validator will decide)", { meta: {
+				pkg,
+				error: (0, _camstack_types_addon.errMsg)(err)
+			} });
+			continue;
+		}
+		if (hasDotNode(moduleDir, 4)) {
+			fetched.push(pkg);
+			options.logger.info("native prebuild fetched", { meta: { pkg } });
+		} else options.logger.error("native prebuild still missing after fetch", { meta: { pkg } });
+	}
+	return fetched;
+}
+//#endregion
+//#region src/kernel/deps/ensure-addon-natives.ts
+/**
+* `ensureAddonNativePrebuilds` — the POST-install native-prebuild ENSURE pass an
+* addon install runs on the INSTALLED addon dir AFTER `npm install`.
+*
+* Why this exists (Mac desktop first-boot FATAL, 2026-07-21): `installCopy`
+* copies `dist/`, plants prebuilt natives from the bundled addon copy
+* (`copyBundledNativeModules`), then `npm install`s the addon's runtime deps.
+* On a TOOLCHAIN-LESS host that `npm install` RE-CREATES the traditional native
+* `better-sqlite3` SOURCE-ONLY — clobbering the good `.node` the pre-install
+* copy just planted — and the runner later dies at addon init with a cryptic
+* "Could not locate the bindings file". The copy-BEFORE-install fix was
+* empirically insufficient: npm's own install in the copied dir replaces the
+* satisfied dep without its binary.
+*
+* This pass runs LAST, so it always sees the final on-disk state npm left, and
+* per referenced traditional native still lacking its compiled `.node`:
+*   1. bundled-copy first — if the bundled addon copy carries the matching
+*      `.node` (same machine → same platform/arch/ABI), re-plant it DIRECTLY.
+*      Cheapest + offline-safe; runs BEFORE any network fetch.
+*   2. fetch fallback — otherwise fetch the prebuild for the running ABI via the
+*      shared `ensureNativePrebuilds` pointed at the addon dir.
+*   3. FAIL LOUD — if the native is STILL source-only after both, log a clear
+*      error naming module + addon and THROW so the install fails at install
+*      time rather than at addon init.
+*
+* N-API natives (`sharp`, `node-av`) ship their binaries as ABI-stable platform
+* SIBLING packages npm fetches without a compile step, so they are excluded from
+* the default set — a miss there is a broken install, not something a prebuild
+* re-fetch heals (same rationale as `ensureNativePrebuilds`).
+*/
+/**
+* Re-plant `<srcModuleDir>` → `<dstModuleDir>` when the source carries a `.node`.
+* Returns whether the destination ends up with a compiled binary.
+*/
+function replantFromBundled(srcModuleDir, dstModuleDir, hasNative) {
+	if (!hasNative(srcModuleDir)) return false;
+	try {
+		node_fs.rmSync(dstModuleDir, {
+			recursive: true,
+			force: true
+		});
+		node_fs.mkdirSync(node_path.dirname(dstModuleDir), { recursive: true });
+		node_fs.cpSync(srcModuleDir, dstModuleDir, {
+			recursive: true,
+			dereference: true
+		});
+	} catch {
+		return false;
+	}
+	return hasNative(dstModuleDir);
+}
+/**
+* Ensure every referenced traditional native in `<addonDir>/node_modules`
+* carries its compiled `.node` after the addon's `npm install`. Bundled-copy
+* first (offline), prebuild-fetch fallback, LOUD throw on a residual miss.
+*
+* SKIPS a native absent from the addon's own `node_modules` (it resolves via a
+* hoisted host copy — not this addon's concern). A NO-OP in docker / dev where
+* npm produced a working `.node` (already-present). Returns the per-native
+* outcomes for logging/tests.
+*
+* @throws if any required native is still source-only after copy + fetch.
+*/
+async function ensureAddonNativePrebuilds(addonDir, options) {
+	const packages = options.packages ?? TRADITIONAL_NATIVE_PACKAGES;
+	const hasNative = options.hasNative ?? ((dir) => hasDotNode(dir, 4));
+	const nm = node_path.join(addonDir, "node_modules");
+	const results = [];
+	const missing = [];
+	for (const pkg of packages) {
+		const moduleDir = node_path.join(nm, pkg);
+		if (!node_fs.existsSync(moduleDir)) continue;
+		if (hasNative(moduleDir)) {
+			results.push({
+				pkg,
+				outcome: "already-present"
+			});
+			continue;
+		}
+		if (options.bundledSourceDir) {
+			const src = node_path.join(options.bundledSourceDir, "node_modules", pkg);
+			if (replantFromBundled(src, moduleDir, hasNative)) {
+				options.logger.info("addon native prebuild re-planted from bundled copy (offline)", { meta: {
+					addon: options.addonName,
+					pkg,
+					src,
+					moduleDir
+				} });
+				results.push({
+					pkg,
+					outcome: "copied"
+				});
+				continue;
+			}
+		}
+		if ((await ensureNativePrebuilds(addonDir, {
+			logger: options.logger,
+			packages: [pkg],
+			...options.target ? { target: options.target } : {},
+			...options.fetchPrebuild ? { fetchPrebuild: options.fetchPrebuild } : {}
+		})).includes(pkg)) {
+			results.push({
+				pkg,
+				outcome: "fetched"
+			});
+			continue;
+		}
+		options.logger.error("addon native prebuild MISSING after ensure — module has no compiled .node", { meta: {
+			addon: options.addonName,
+			pkg,
+			moduleDir
+		} });
+		results.push({
+			pkg,
+			outcome: "missing"
+		});
+		missing.push(pkg);
+	}
+	if (missing.length > 0) throw new Error(`${options.addonName} — required native module(s) missing a compiled .node after install (bundled-copy + prebuild-fetch both failed): ${missing.join(", ")}`);
+	return results;
+}
+//#endregion
+//#region src/kernel/addon-installer.ts
+var execFileAsync = (0, node_util.promisify)(node_child_process.execFile);
 function parseInstallSource(value) {
 	switch (value) {
 		case "npm":
@@ -3340,6 +3602,11 @@ var AddonInstaller = class AddonInstaller {
 		} catch (err) {
 			this.logger.warn(`${packageName} — native deps install failed (continuing)`, { meta: { error: require_dist.errMsg(err) } });
 		}
+		await ensureAddonNativePrebuilds(targetDir, {
+			addonName: packageName,
+			logger: this.logger,
+			bundledSourceDir: sourceDir
+		});
 		this.logger.info(`${packageName} — copied from ${sourceDir}`);
 		return {
 			name: pkgData.name,
@@ -3489,7 +3756,7 @@ var AddonInstaller = class AddonInstaller {
 		const stagingDir = node_path.join(stagingRoot, `install-${process.pid}-${(/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-")}`);
 		ensureDir(stagingDir);
 		try {
-			await execFileAsync$1("tar", [
+			await execFileAsync("tar", [
 				"-xzf",
 				tgzPath,
 				"-C",
@@ -3526,6 +3793,10 @@ var AddonInstaller = class AddonInstaller {
 			} 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.evictInstallDir(targetDir);
 			ensureDir(node_path.dirname(targetDir));
 			await node_fs.promises.rename(pkgDir, targetDir);
@@ -80144,7 +80415,7 @@ var require_compression = /* @__PURE__ */ require_chunk.__commonJSMin(((exports,
 	var { defaultsDeep } = require_lodash();
 	var { parseByteString } = require_utils$3();
 	var zlib = require("zlib");
-	var { promisify: promisify$1 } = require("util");
+	var { promisify } = require("util");
 	/**
 	* This is a transmission compression middleware. It supports
 	* the `deflate`, `deflateRaw` & `gzip` compression methods.
@@ -80162,16 +80433,16 @@ var require_compression = /* @__PURE__ */ require_chunk.__commonJSMin(((exports,
 		const threshold = parseByteString(opts.threshold);
 		switch (opts.method) {
 			case "deflate":
-				compress = promisify$1(zlib.deflate);
-				decompress = promisify$1(zlib.inflate);
+				compress = promisify(zlib.deflate);
+				decompress = promisify(zlib.inflate);
 				break;
 			case "deflateRaw":
-				compress = promisify$1(zlib.deflateRaw);
-				decompress = promisify$1(zlib.inflateRaw);
+				compress = promisify(zlib.deflateRaw);
+				decompress = promisify(zlib.inflateRaw);
 				break;
 			case "gzip":
-				compress = promisify$1(zlib.gzip);
-				decompress = promisify$1(zlib.gunzip);
+				compress = promisify(zlib.gzip);
+				decompress = promisify(zlib.gunzip);
 				break;
 			default:
  /* istanbul ignore next */
@@ -93398,145 +93669,6 @@ var LifecycleJobEngine = class {
 	}
 };
 //#endregion
-//#region src/kernel/deps/ensure-native-prebuilds.ts
-/**
-* `ensureNativePrebuilds` — the post-install native-prebuild ENSURE step the
-* shared `RootUpdateService` runs while staging a `@camstack/server` closure,
-* BEFORE its `findMissingNativePrebuilds` validator (in `@camstack/node-root`)
-* decides whether to arm the swap.
-*
-* Why this exists (Mac desktop incident, 2026-07-21): a runtime
-* `applyServerUpdate` on a packaged desktop stages the closure with
-* `npm install @camstack/server@X` under the app's BUNDLED bare Node. The one
-* TRADITIONAL (non-N-API) native, `better-sqlite3`, resolves its `.node` via
-* its `install` script `prebuild-install || node-gyp rebuild`. On a user's Mac
-* with no build toolchain (and where the auto `prebuild-install` does not
-* target the bundled Node's ABI/arch the way the DMG build's EXPLICIT
-* `prebuild-install --runtime node --target <bundled> --arch <arch>` call does)
-* that leaves the module SOURCE-ONLY → the closure has no `better-sqlite3`
-* `.node` → the validator refuses the swap ("staged closure missing native
-* prebuilds: better-sqlite3"). The docker image never hits this: its Node ABI
-* has a published prebuild the auto path fetches cleanly, and it carries a
-* build toolchain fallback.
-*
-* This mirrors the DMG build's explicit re-fetch (`scripts/stage-deps.mjs`)
-* into the runtime staging path: for each traditional native that is present
-* in the closure but missing its compiled `.node`, fetch the prebuild for the
-* RUNNING Node ABI/arch (the same Node that will load the swapped closure).
-*
-* N-API natives (`sharp`, `node-av`) are ABI-stable and ship their binaries as
-* platform SIBLING packages that npm fetches reliably with no compile step, so
-* they are not in scope here — a genuine miss there is a broken install the
-* validator should still reject, not something a prebuild re-fetch can heal.
-*
-* Injected into the update service from the construction site so the zero-dep
-* `@camstack/node-root` layer never depends on npm/@camstack/system, and the
-* fetch is unit-testable with a fake fetcher.
-*/
-var execFileAsync = (0, node_util.promisify)(node_child_process.execFile);
-/** Bounded recursive `.node` scan depth inside a module dir. */
-var NATIVE_SCAN_DEPTH = 4;
-/** Timeout for a single `prebuild-install` fetch. */
-var PREBUILD_FETCH_TIMEOUT_MS = 12e4;
-/**
-* Traditional (compile-or-prebuild) natives an installed closure must carry a
-* `.node` for. Only these are ENSURE-able by a prebuild re-fetch; N-API natives
-* are excluded (see file header).
-*/
-var TRADITIONAL_NATIVE_PACKAGES = ["better-sqlite3"];
-/** Bounded recursive scan for ANY `*.node` file under `dir`. */
-function hasDotNode(dir, maxDepth) {
-	let entries;
-	try {
-		entries = node_fs.readdirSync(dir, { withFileTypes: true });
-	} catch {
-		return false;
-	}
-	for (const entry of entries) if (entry.isFile() && entry.name.endsWith(".node")) return true;
-	if (maxDepth <= 0) return false;
-	for (const entry of entries) if (entry.isDirectory() && hasDotNode(node_path.join(dir, entry.name), maxDepth - 1)) return true;
-	return false;
-}
-/** Locate the bundled `prebuild-install` bin.js inside the staged closure. */
-function resolvePrebuildInstallBin(closureDir, moduleDir) {
-	return [node_path.join(moduleDir, "node_modules", "prebuild-install", "bin.js"), node_path.join(closureDir, "node_modules", "prebuild-install", "bin.js")].find((c) => node_fs.existsSync(c)) ?? null;
-}
-/**
-* Default fetcher: run the closure's own `prebuild-install` under the CURRENT
-* Node (`process.execPath`) — no reliance on `npx`/`npm` on PATH (a packaged
-* app ships a bare Node). Explicitly targets the running ABI/arch, mirroring
-* `scripts/stage-deps.mjs`.
-*/
-function makeDefaultFetch(closureDir, logger) {
-	return async (moduleDir, target) => {
-		const bin = resolvePrebuildInstallBin(closureDir, moduleDir);
-		if (bin === null) throw new Error(`prebuild-install not found in the staged closure for ${moduleDir}`);
-		logger.info("fetching native prebuild via prebuild-install", { meta: {
-			moduleDir,
-			bin,
-			nodeVersion: target.nodeVersion,
-			arch: target.arch
-		} });
-		await execFileAsync(process.execPath, [
-			bin,
-			"--runtime",
-			"node",
-			"--target",
-			target.nodeVersion,
-			"--arch",
-			target.arch
-		], {
-			cwd: moduleDir,
-			timeout: PREBUILD_FETCH_TIMEOUT_MS
-		});
-	};
-}
-/**
-* Ensure every traditional native in `<closureDir>/node_modules` carries its
-* compiled `.node`, fetching the prebuild for the running ABI when missing.
-*
-* A NO-OP when nothing is missing (docker / tests) and when a native package is
-* absent from the closure. Never throws for a single package's fetch failure —
-* it logs and continues so the downstream `findMissingNativePrebuilds`
-* validator makes the final swap/abort decision. Returns the packages whose
-* prebuild was successfully fetched (for logging/tests).
-*/
-async function ensureNativePrebuilds(closureDir, options) {
-	const nm = node_path.join(closureDir, "node_modules");
-	const target = options.target ?? {
-		nodeVersion: process.versions.node,
-		arch: process.arch
-	};
-	const packages = options.packages ?? TRADITIONAL_NATIVE_PACKAGES;
-	const fetchPrebuild = options.fetchPrebuild ?? makeDefaultFetch(closureDir, options.logger);
-	const fetched = [];
-	for (const pkg of packages) {
-		const moduleDir = node_path.join(nm, pkg);
-		if (!node_fs.existsSync(moduleDir)) continue;
-		if (hasDotNode(moduleDir, NATIVE_SCAN_DEPTH)) continue;
-		options.logger.warn("staged closure native prebuild missing — fetching for running ABI", { meta: {
-			pkg,
-			moduleDir,
-			nodeVersion: target.nodeVersion,
-			arch: target.arch
-		} });
-		try {
-			await fetchPrebuild(moduleDir, target);
-		} catch (err) {
-			options.logger.error("native prebuild fetch failed (validator will decide)", { meta: {
-				pkg,
-				error: (0, _camstack_types_addon.errMsg)(err)
-			} });
-			continue;
-		}
-		if (hasDotNode(moduleDir, NATIVE_SCAN_DEPTH)) {
-			fetched.push(pkg);
-			options.logger.info("native prebuild fetched", { meta: { pkg } });
-		} else options.logger.error("native prebuild still missing after fetch", { meta: { pkg } });
-	}
-	return fetched;
-}
-//#endregion
 exports.AGENT_CAP_FWD_ACTION = require_manifest_python_deps.AGENT_CAP_FWD_ACTION;
 exports.AGENT_CAP_FWD_SERVICE = require_manifest_python_deps.AGENT_CAP_FWD_SERVICE;
 exports.AGENT_READINESS_SERVICE_NAME = AGENT_READINESS_SERVICE_NAME;
@@ -93603,6 +93735,7 @@ exports.LogRingBuffer = LogRingBuffer;
 exports.METHOD_ACCESS_MAP = require_dist.METHOD_ACCESS_MAP;
 exports.ModelDownloadService = require_model_download_service.ModelDownloadService;
 exports.NATIVE_PROVIDER_SERVICE_INFIX = require_manifest_python_deps.NATIVE_PROVIDER_SERVICE_INFIX;
+exports.NATIVE_SCAN_DEPTH = NATIVE_SCAN_DEPTH;
 exports.NativeMetricsAddon = require_builtins_native_metrics_native_metrics_addon.default;
 exports.NativeMetricsProvider = require_builtins_native_metrics_native_metrics_addon.NativeMetricsProvider;
 exports.NetworkQualityTracker = NetworkQualityTracker;
@@ -93712,6 +93845,7 @@ exports.downloadFile = require_model_download_service.downloadFile;
 exports.downloadModel = require_model_download_service.downloadModel;
 exports.emitDownForOwnedCaps = require_dist.emitDownForOwnedCaps;
 exports.encodeFrame = require_manifest_python_deps.encodeFrame;
+exports.ensureAddonNativePrebuilds = ensureAddonNativePrebuilds;
 Object.defineProperty(exports, "ensureBinary", {
 	enumerable: true,
 	get: function() {
@@ -93772,6 +93906,7 @@ Object.defineProperty(exports, "getPythonDownloadUrl", {
 exports.getRestartMarkerPath = getRestartMarkerPath;
 exports.getSinglePidStats = require_resource_monitor.getSinglePidStats;
 exports.getWorkerDeviceRegistry = require_manifest_python_deps.getWorkerDeviceRegistry;
+exports.hasDotNode = hasDotNode;
 exports.hashClusterSecret = hashClusterSecret;
 exports.installManifestNativeDeps = require_manifest_python_deps.installManifestNativeDeps;
 exports.installManifestPythonDeps = require_manifest_python_deps.installManifestPythonDeps;

package/dist/index.mjs

@@ -3022,8 +3022,270 @@ var AddonManifest = class {
 	}
 };
 //#endregion
-//#region src/kernel/addon-installer.ts
+//#region src/kernel/deps/ensure-native-prebuilds.ts
+/**
+* `ensureNativePrebuilds` — the post-install native-prebuild ENSURE step the
+* shared `RootUpdateService` runs while staging a `@camstack/server` closure,
+* BEFORE its `findMissingNativePrebuilds` validator (in `@camstack/node-root`)
+* decides whether to arm the swap.
+*
+* Why this exists (Mac desktop incident, 2026-07-21): a runtime
+* `applyServerUpdate` on a packaged desktop stages the closure with
+* `npm install @camstack/server@X` under the app's BUNDLED bare Node. The one
+* TRADITIONAL (non-N-API) native, `better-sqlite3`, resolves its `.node` via
+* its `install` script `prebuild-install || node-gyp rebuild`. On a user's Mac
+* with no build toolchain (and where the auto `prebuild-install` does not
+* target the bundled Node's ABI/arch the way the DMG build's EXPLICIT
+* `prebuild-install --runtime node --target <bundled> --arch <arch>` call does)
+* that leaves the module SOURCE-ONLY → the closure has no `better-sqlite3`
+* `.node` → the validator refuses the swap ("staged closure missing native
+* prebuilds: better-sqlite3"). The docker image never hits this: its Node ABI
+* has a published prebuild the auto path fetches cleanly, and it carries a
+* build toolchain fallback.
+*
+* This mirrors the DMG build's explicit re-fetch (`scripts/stage-deps.mjs`)
+* into the runtime staging path: for each traditional native that is present
+* in the closure but missing its compiled `.node`, fetch the prebuild for the
+* RUNNING Node ABI/arch (the same Node that will load the swapped closure).
+*
+* N-API natives (`sharp`, `node-av`) are ABI-stable and ship their binaries as
+* platform SIBLING packages that npm fetches reliably with no compile step, so
+* they are not in scope here — a genuine miss there is a broken install the
+* validator should still reject, not something a prebuild re-fetch can heal.
+*
+* Injected into the update service from the construction site so the zero-dep
+* `@camstack/node-root` layer never depends on npm/@camstack/system, and the
+* fetch is unit-testable with a fake fetcher.
+*/
 var execFileAsync$1 = promisify(execFile);
+/** Bounded recursive `.node` scan depth inside a module dir. */
+var NATIVE_SCAN_DEPTH = 4;
+/** Timeout for a single `prebuild-install` fetch. */
+var PREBUILD_FETCH_TIMEOUT_MS = 12e4;
+/**
+* Traditional (compile-or-prebuild) natives an installed closure must carry a
+* `.node` for. Only these are ENSURE-able by a prebuild re-fetch; N-API natives
+* are excluded (see file header).
+*/
+var TRADITIONAL_NATIVE_PACKAGES = ["better-sqlite3"];
+/** Bounded recursive scan for ANY `*.node` file under `dir`. */
+function hasDotNode(dir, maxDepth) {
+	let entries;
+	try {
+		entries = fs$17.readdirSync(dir, { withFileTypes: true });
+	} catch {
+		return false;
+	}
+	for (const entry of entries) if (entry.isFile() && entry.name.endsWith(".node")) return true;
+	if (maxDepth <= 0) return false;
+	for (const entry of entries) if (entry.isDirectory() && hasDotNode(path$39.join(dir, entry.name), maxDepth - 1)) return true;
+	return false;
+}
+/** Locate the bundled `prebuild-install` bin.js inside the staged closure. */
+function resolvePrebuildInstallBin(closureDir, moduleDir) {
+	return [path$39.join(moduleDir, "node_modules", "prebuild-install", "bin.js"), path$39.join(closureDir, "node_modules", "prebuild-install", "bin.js")].find((c) => fs$17.existsSync(c)) ?? null;
+}
+/**
+* Default fetcher: run the closure's own `prebuild-install` under the CURRENT
+* Node (`process.execPath`) — no reliance on `npx`/`npm` on PATH (a packaged
+* app ships a bare Node). Explicitly targets the running ABI/arch, mirroring
+* `scripts/stage-deps.mjs`.
+*/
+function makeDefaultFetch(closureDir, logger) {
+	return async (moduleDir, target) => {
+		const bin = resolvePrebuildInstallBin(closureDir, moduleDir);
+		if (bin === null) throw new Error(`prebuild-install not found in the staged closure for ${moduleDir}`);
+		logger.info("fetching native prebuild via prebuild-install", { meta: {
+			moduleDir,
+			bin,
+			nodeVersion: target.nodeVersion,
+			arch: target.arch
+		} });
+		await execFileAsync$1(process.execPath, [
+			bin,
+			"--runtime",
+			"node",
+			"--target",
+			target.nodeVersion,
+			"--arch",
+			target.arch
+		], {
+			cwd: moduleDir,
+			timeout: PREBUILD_FETCH_TIMEOUT_MS
+		});
+	};
+}
+/**
+* Ensure every traditional native in `<closureDir>/node_modules` carries its
+* compiled `.node`, fetching the prebuild for the running ABI when missing.
+*
+* A NO-OP when nothing is missing (docker / tests) and when a native package is
+* absent from the closure. Never throws for a single package's fetch failure —
+* it logs and continues so the downstream `findMissingNativePrebuilds`
+* validator makes the final swap/abort decision. Returns the packages whose
+* prebuild was successfully fetched (for logging/tests).
+*/
+async function ensureNativePrebuilds(closureDir, options) {
+	const nm = path$39.join(closureDir, "node_modules");
+	const target = options.target ?? {
+		nodeVersion: process.versions.node,
+		arch: process.arch
+	};
+	const packages = options.packages ?? TRADITIONAL_NATIVE_PACKAGES;
+	const fetchPrebuild = options.fetchPrebuild ?? makeDefaultFetch(closureDir, options.logger);
+	const fetched = [];
+	for (const pkg of packages) {
+		const moduleDir = path$39.join(nm, pkg);
+		if (!fs$17.existsSync(moduleDir)) continue;
+		if (hasDotNode(moduleDir, 4)) continue;
+		options.logger.warn("staged closure native prebuild missing — fetching for running ABI", { meta: {
+			pkg,
+			moduleDir,
+			nodeVersion: target.nodeVersion,
+			arch: target.arch
+		} });
+		try {
+			await fetchPrebuild(moduleDir, target);
+		} catch (err) {
+			options.logger.error("native prebuild fetch failed (validator will decide)", { meta: {
+				pkg,
+				error: errMsg(err)
+			} });
+			continue;
+		}
+		if (hasDotNode(moduleDir, 4)) {
+			fetched.push(pkg);
+			options.logger.info("native prebuild fetched", { meta: { pkg } });
+		} else options.logger.error("native prebuild still missing after fetch", { meta: { pkg } });
+	}
+	return fetched;
+}
+//#endregion
+//#region src/kernel/deps/ensure-addon-natives.ts
+/**
+* `ensureAddonNativePrebuilds` — the POST-install native-prebuild ENSURE pass an
+* addon install runs on the INSTALLED addon dir AFTER `npm install`.
+*
+* Why this exists (Mac desktop first-boot FATAL, 2026-07-21): `installCopy`
+* copies `dist/`, plants prebuilt natives from the bundled addon copy
+* (`copyBundledNativeModules`), then `npm install`s the addon's runtime deps.
+* On a TOOLCHAIN-LESS host that `npm install` RE-CREATES the traditional native
+* `better-sqlite3` SOURCE-ONLY — clobbering the good `.node` the pre-install
+* copy just planted — and the runner later dies at addon init with a cryptic
+* "Could not locate the bindings file". The copy-BEFORE-install fix was
+* empirically insufficient: npm's own install in the copied dir replaces the
+* satisfied dep without its binary.
+*
+* This pass runs LAST, so it always sees the final on-disk state npm left, and
+* per referenced traditional native still lacking its compiled `.node`:
+*   1. bundled-copy first — if the bundled addon copy carries the matching
+*      `.node` (same machine → same platform/arch/ABI), re-plant it DIRECTLY.
+*      Cheapest + offline-safe; runs BEFORE any network fetch.
+*   2. fetch fallback — otherwise fetch the prebuild for the running ABI via the
+*      shared `ensureNativePrebuilds` pointed at the addon dir.
+*   3. FAIL LOUD — if the native is STILL source-only after both, log a clear
+*      error naming module + addon and THROW so the install fails at install
+*      time rather than at addon init.
+*
+* N-API natives (`sharp`, `node-av`) ship their binaries as ABI-stable platform
+* SIBLING packages npm fetches without a compile step, so they are excluded from
+* the default set — a miss there is a broken install, not something a prebuild
+* re-fetch heals (same rationale as `ensureNativePrebuilds`).
+*/
+/**
+* Re-plant `<srcModuleDir>` → `<dstModuleDir>` when the source carries a `.node`.
+* Returns whether the destination ends up with a compiled binary.
+*/
+function replantFromBundled(srcModuleDir, dstModuleDir, hasNative) {
+	if (!hasNative(srcModuleDir)) return false;
+	try {
+		fs$17.rmSync(dstModuleDir, {
+			recursive: true,
+			force: true
+		});
+		fs$17.mkdirSync(path$39.dirname(dstModuleDir), { recursive: true });
+		fs$17.cpSync(srcModuleDir, dstModuleDir, {
+			recursive: true,
+			dereference: true
+		});
+	} catch {
+		return false;
+	}
+	return hasNative(dstModuleDir);
+}
+/**
+* Ensure every referenced traditional native in `<addonDir>/node_modules`
+* carries its compiled `.node` after the addon's `npm install`. Bundled-copy
+* first (offline), prebuild-fetch fallback, LOUD throw on a residual miss.
+*
+* SKIPS a native absent from the addon's own `node_modules` (it resolves via a
+* hoisted host copy — not this addon's concern). A NO-OP in docker / dev where
+* npm produced a working `.node` (already-present). Returns the per-native
+* outcomes for logging/tests.
+*
+* @throws if any required native is still source-only after copy + fetch.
+*/
+async function ensureAddonNativePrebuilds(addonDir, options) {
+	const packages = options.packages ?? TRADITIONAL_NATIVE_PACKAGES;
+	const hasNative = options.hasNative ?? ((dir) => hasDotNode(dir, 4));
+	const nm = path$39.join(addonDir, "node_modules");
+	const results = [];
+	const missing = [];
+	for (const pkg of packages) {
+		const moduleDir = path$39.join(nm, pkg);
+		if (!fs$17.existsSync(moduleDir)) continue;
+		if (hasNative(moduleDir)) {
+			results.push({
+				pkg,
+				outcome: "already-present"
+			});
+			continue;
+		}
+		if (options.bundledSourceDir) {
+			const src = path$39.join(options.bundledSourceDir, "node_modules", pkg);
+			if (replantFromBundled(src, moduleDir, hasNative)) {
+				options.logger.info("addon native prebuild re-planted from bundled copy (offline)", { meta: {
+					addon: options.addonName,
+					pkg,
+					src,
+					moduleDir
+				} });
+				results.push({
+					pkg,
+					outcome: "copied"
+				});
+				continue;
+			}
+		}
+		if ((await ensureNativePrebuilds(addonDir, {
+			logger: options.logger,
+			packages: [pkg],
+			...options.target ? { target: options.target } : {},
+			...options.fetchPrebuild ? { fetchPrebuild: options.fetchPrebuild } : {}
+		})).includes(pkg)) {
+			results.push({
+				pkg,
+				outcome: "fetched"
+			});
+			continue;
+		}
+		options.logger.error("addon native prebuild MISSING after ensure — module has no compiled .node", { meta: {
+			addon: options.addonName,
+			pkg,
+			moduleDir
+		} });
+		results.push({
+			pkg,
+			outcome: "missing"
+		});
+		missing.push(pkg);
+	}
+	if (missing.length > 0) throw new Error(`${options.addonName} — required native module(s) missing a compiled .node after install (bundled-copy + prebuild-fetch both failed): ${missing.join(", ")}`);
+	return results;
+}
+//#endregion
+//#region src/kernel/addon-installer.ts
+var execFileAsync = promisify(execFile);
 function parseInstallSource(value) {
 	switch (value) {
 		case "npm":
@@ -3332,6 +3594,11 @@ var AddonInstaller = class AddonInstaller {
 		} catch (err) {
 			this.logger.warn(`${packageName} — native deps install failed (continuing)`, { meta: { error: errMsg$1(err) } });
 		}
+		await ensureAddonNativePrebuilds(targetDir, {
+			addonName: packageName,
+			logger: this.logger,
+			bundledSourceDir: sourceDir
+		});
 		this.logger.info(`${packageName} — copied from ${sourceDir}`);
 		return {
 			name: pkgData.name,
@@ -3481,7 +3748,7 @@ var AddonInstaller = class AddonInstaller {
 		const stagingDir = path$39.join(stagingRoot, `install-${process.pid}-${(/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-")}`);
 		ensureDir(stagingDir);
 		try {
-			await execFileAsync$1("tar", [
+			await execFileAsync("tar", [
 				"-xzf",
 				tgzPath,
 				"-C",
@@ -3518,6 +3785,10 @@ var AddonInstaller = class AddonInstaller {
 			} 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.evictInstallDir(targetDir);
 			ensureDir(path$39.dirname(targetDir));
 			await fs$17.promises.rename(pkgDir, targetDir);
@@ -93390,143 +93661,4 @@ var LifecycleJobEngine = class {
 	}
 };
 //#endregion
-//#region src/kernel/deps/ensure-native-prebuilds.ts
-/**
-* `ensureNativePrebuilds` — the post-install native-prebuild ENSURE step the
-* shared `RootUpdateService` runs while staging a `@camstack/server` closure,
-* BEFORE its `findMissingNativePrebuilds` validator (in `@camstack/node-root`)
-* decides whether to arm the swap.
-*
-* Why this exists (Mac desktop incident, 2026-07-21): a runtime
-* `applyServerUpdate` on a packaged desktop stages the closure with
-* `npm install @camstack/server@X` under the app's BUNDLED bare Node. The one
-* TRADITIONAL (non-N-API) native, `better-sqlite3`, resolves its `.node` via
-* its `install` script `prebuild-install || node-gyp rebuild`. On a user's Mac
-* with no build toolchain (and where the auto `prebuild-install` does not
-* target the bundled Node's ABI/arch the way the DMG build's EXPLICIT
-* `prebuild-install --runtime node --target <bundled> --arch <arch>` call does)
-* that leaves the module SOURCE-ONLY → the closure has no `better-sqlite3`
-* `.node` → the validator refuses the swap ("staged closure missing native
-* prebuilds: better-sqlite3"). The docker image never hits this: its Node ABI
-* has a published prebuild the auto path fetches cleanly, and it carries a
-* build toolchain fallback.
-*
-* This mirrors the DMG build's explicit re-fetch (`scripts/stage-deps.mjs`)
-* into the runtime staging path: for each traditional native that is present
-* in the closure but missing its compiled `.node`, fetch the prebuild for the
-* RUNNING Node ABI/arch (the same Node that will load the swapped closure).
-*
-* N-API natives (`sharp`, `node-av`) are ABI-stable and ship their binaries as
-* platform SIBLING packages that npm fetches reliably with no compile step, so
-* they are not in scope here — a genuine miss there is a broken install the
-* validator should still reject, not something a prebuild re-fetch can heal.
-*
-* Injected into the update service from the construction site so the zero-dep
-* `@camstack/node-root` layer never depends on npm/@camstack/system, and the
-* fetch is unit-testable with a fake fetcher.
-*/
-var execFileAsync = promisify(execFile);
-/** Bounded recursive `.node` scan depth inside a module dir. */
-var NATIVE_SCAN_DEPTH = 4;
-/** Timeout for a single `prebuild-install` fetch. */
-var PREBUILD_FETCH_TIMEOUT_MS = 12e4;
-/**
-* Traditional (compile-or-prebuild) natives an installed closure must carry a
-* `.node` for. Only these are ENSURE-able by a prebuild re-fetch; N-API natives
-* are excluded (see file header).
-*/
-var TRADITIONAL_NATIVE_PACKAGES = ["better-sqlite3"];
-/** Bounded recursive scan for ANY `*.node` file under `dir`. */
-function hasDotNode(dir, maxDepth) {
-	let entries;
-	try {
-		entries = fs$17.readdirSync(dir, { withFileTypes: true });
-	} catch {
-		return false;
-	}
-	for (const entry of entries) if (entry.isFile() && entry.name.endsWith(".node")) return true;
-	if (maxDepth <= 0) return false;
-	for (const entry of entries) if (entry.isDirectory() && hasDotNode(path$39.join(dir, entry.name), maxDepth - 1)) return true;
-	return false;
-}
-/** Locate the bundled `prebuild-install` bin.js inside the staged closure. */
-function resolvePrebuildInstallBin(closureDir, moduleDir) {
-	return [path$39.join(moduleDir, "node_modules", "prebuild-install", "bin.js"), path$39.join(closureDir, "node_modules", "prebuild-install", "bin.js")].find((c) => fs$17.existsSync(c)) ?? null;
-}
-/**
-* Default fetcher: run the closure's own `prebuild-install` under the CURRENT
-* Node (`process.execPath`) — no reliance on `npx`/`npm` on PATH (a packaged
-* app ships a bare Node). Explicitly targets the running ABI/arch, mirroring
-* `scripts/stage-deps.mjs`.
-*/
-function makeDefaultFetch(closureDir, logger) {
-	return async (moduleDir, target) => {
-		const bin = resolvePrebuildInstallBin(closureDir, moduleDir);
-		if (bin === null) throw new Error(`prebuild-install not found in the staged closure for ${moduleDir}`);
-		logger.info("fetching native prebuild via prebuild-install", { meta: {
-			moduleDir,
-			bin,
-			nodeVersion: target.nodeVersion,
-			arch: target.arch
-		} });
-		await execFileAsync(process.execPath, [
-			bin,
-			"--runtime",
-			"node",
-			"--target",
-			target.nodeVersion,
-			"--arch",
-			target.arch
-		], {
-			cwd: moduleDir,
-			timeout: PREBUILD_FETCH_TIMEOUT_MS
-		});
-	};
-}
-/**
-* Ensure every traditional native in `<closureDir>/node_modules` carries its
-* compiled `.node`, fetching the prebuild for the running ABI when missing.
-*
-* A NO-OP when nothing is missing (docker / tests) and when a native package is
-* absent from the closure. Never throws for a single package's fetch failure —
-* it logs and continues so the downstream `findMissingNativePrebuilds`
-* validator makes the final swap/abort decision. Returns the packages whose
-* prebuild was successfully fetched (for logging/tests).
-*/
-async function ensureNativePrebuilds(closureDir, options) {
-	const nm = path$39.join(closureDir, "node_modules");
-	const target = options.target ?? {
-		nodeVersion: process.versions.node,
-		arch: process.arch
-	};
-	const packages = options.packages ?? TRADITIONAL_NATIVE_PACKAGES;
-	const fetchPrebuild = options.fetchPrebuild ?? makeDefaultFetch(closureDir, options.logger);
-	const fetched = [];
-	for (const pkg of packages) {
-		const moduleDir = path$39.join(nm, pkg);
-		if (!fs$17.existsSync(moduleDir)) continue;
-		if (hasDotNode(moduleDir, NATIVE_SCAN_DEPTH)) continue;
-		options.logger.warn("staged closure native prebuild missing — fetching for running ABI", { meta: {
-			pkg,
-			moduleDir,
-			nodeVersion: target.nodeVersion,
-			arch: target.arch
-		} });
-		try {
-			await fetchPrebuild(moduleDir, target);
-		} catch (err) {
-			options.logger.error("native prebuild fetch failed (validator will decide)", { meta: {
-				pkg,
-				error: errMsg(err)
-			} });
-			continue;
-		}
-		if (hasDotNode(moduleDir, NATIVE_SCAN_DEPTH)) {
-			fetched.push(pkg);
-			options.logger.info("native prebuild fetched", { meta: { pkg } });
-		} else options.logger.error("native prebuild still missing after fetch", { meta: { pkg } });
-	}
-	return fetched;
-}
-//#endregion
-export { AGENT_CAP_FWD_ACTION, AGENT_CAP_FWD_SERVICE, AGENT_READINESS_SERVICE_NAME, ALL_CAPABILITY_DEFINITIONS, AddonApiFactory, AddonDepsManager, AddonEngineManager, AddonHealthMonitor, AddonInstaller, AddonLoader, AddonManifest, AddonRouteRegistry, AlertCenterAddon, ApiKeyManager, AuthManager, CLUSTER_SECRET_MISMATCH_TYPE, CLUSTER_SECRET_REJECTED_EXIT_CODE, CORE_CAP_SERVICE_NAME, CapRouteError, CapRouteResolver, CapUsageRegistry, CapabilityHandle, CapabilityRegistry, CapabilityUnavailableError, ConfigManager, ConfigStore, ConsoleDestination, ConsoleLoggingAddon, CustomActionRegistry, DEFAULT_DATA_PATH, DEVICE_SETTINGS_CONTRIBUTION_METHODS, DEVICE_STATUS_METHOD, DataPlaneRegistry, DeviceManagerAddon, DeviceRegistry, DeviceStore, EVENT_TOPIC_PREFIX, EngineManagerResolver, EventBus, FeatureManager, FilesystemStorageAddon, FilesystemStorageProvider, FrameDecoder, FsStorageBackend, HEALTH_MONITOR_GRACE_PERIOD_MS, HEALTH_MONITOR_RETRY_INTERVALS_MS, HEALTH_MONITOR_TICK_MS, HUB_CAP_FWD_ACTION, HUB_CAP_FWD_SERVICE, HubForwarderAddon, HubForwarderDestination, HubLogForwarder, HubNodeRegistry, INFRA_CAPABILITIES, IntegrationRegistry, JobJournal, LifecycleJobEngine, LifecycleStateMachine, LocalAuthAddon, LocalChildClient, LocalChildRegistry, LogManager, LogRingBuffer, METHOD_ACCESS_MAP, ModelDownloadService, NATIVE_PROVIDER_SERVICE_INFIX, NativeMetricsAddon, NativeMetricsProvider, NetworkQualityTracker, NotificationService, PYTHON_VERSION, PipelineRunner, PipelineValidator, PythonEnvManager, RESTART_MARKER_FILE, RUNTIME_DEFAULTS, ReadinessRegistry, ReadinessTimeoutError, ReplEngine, RingBuffer, ScopedLogger, ScopedTokenManager, SocketChannel, SqliteSettingsAddon, SqliteSettingsBackend, StagingArea, StorageLocationManager, StorageManager, StorageOrchestratorAddon, StorageOrchestratorService, SystemConfigAddon, SystemEventBus, TRADITIONAL_NATIVE_PACKAGES, ToastService, UDS_NO_ROUTE_PREFIX, UdsLocalTransportClient, UdsLocalTransportServer, UserManager, WinstonDestination, WinstonLoggingAddon, __resetCapUsageRegistryForTests, adaptBrokerToCluster, addonSettingsCapability, bootstrapSchema, brokerCallForCap, brokerTransportLink, buildBinaryPath, buildCapRouters, buildLinkChain, buildNativeCapProxy, buildNodeManifest, buildStorageLocationRegistry, buildUdsNativeCapProxy, builderMountedCapNames, callRegisterNodeWithRetry, callWithServiceDiscovery, capActionName, capActionSuffix, capBareAction, capServiceName, classifyCapRoute, clearPendingRestart, clusterEventTopic, clusterSecretMatches, collectModelFiles, contentTypeFor, copyDirRecursive, copyExtraFileDirs, createAddonContext, createAddonDataPlaneFacility, createAddonService, createAuthenticatedFileServer, createBroker, createBrokerDeviceManagerApi, createCoreCapService, createFileDataPlaneHandler, createHubCapForwardService, createHubService, createKernelHwAccel, createLocalTransport, createParentUnownedCallHandler, createProcessService, createReadinessService, createReadinessServiceForRegistry, createScopedProcessManager, createStreamProbeBrokerService, createUdsAddonContext, createUdsEventBridge, createUdsEventBus, createUdsLogger, createUdsLoggerWithControl, deleteModelFromDisk, deriveAgentListenPort, describeProviderKindDrift, detectWorkspacePackagesDir, downloadBinary, downloadFile, downloadModel, emitDownForOwnedCaps, encodeFrame, ensureBinary, ensureDir, ensureFfmpeg, ensureLibraryBuilt, ensureModel, ensureNativePrebuilds, ensurePython, ensureTlsCert, expandCapMethods, fetchJson, findInPath, formatLogLine, getBrokerEventBus, getCapUsageRegistry, getFfmpegDownloadUrl, getModelFilePath, getMoleculerEventStats, getOrInitReadinessRegistry, getOrInitReadinessRegistryForClient, getPidStats, getPlatformInfo, getPythonDownloadUrl, getRestartMarkerPath, getSinglePidStats, getWorkerDeviceRegistry, hashClusterSecret, installManifestNativeDeps, installManifestPythonDeps, installPackageFromNpm, installPythonPackages, installPythonRequirements, ipcChildLink, ipcParentLink, isAddonDeploySource, isArrayOutputSchema, isClusterSecretMismatchError, isCollectionArrayMethod, isInfraCapability, isModelDownloaded, isSourceNewer, loadTlsCert, localEndpointPath, localProviderLink, mountNativeCapService, parseCapAction, parseRangeHeader, parseTokenizedUrl, proxyToUpstream, readPendingRestart, readinessKey, registerEventBusService, resolveFilePath, resolveHwAccel, resolveNpmInvocation, runNpm, scheduleSelfRestart, scopeKey, scopesAllowDeviceCap, serializeTypedArrays, setHubConnected, setNodeEventInterest, stripCamstackDeps, subscribePassthrough, udsChildLogToWorkerEntry, validateProviderRegistrations, writePendingRestart };
+export { AGENT_CAP_FWD_ACTION, AGENT_CAP_FWD_SERVICE, AGENT_READINESS_SERVICE_NAME, ALL_CAPABILITY_DEFINITIONS, AddonApiFactory, AddonDepsManager, AddonEngineManager, AddonHealthMonitor, AddonInstaller, AddonLoader, AddonManifest, AddonRouteRegistry, AlertCenterAddon, ApiKeyManager, AuthManager, CLUSTER_SECRET_MISMATCH_TYPE, CLUSTER_SECRET_REJECTED_EXIT_CODE, CORE_CAP_SERVICE_NAME, CapRouteError, CapRouteResolver, CapUsageRegistry, CapabilityHandle, CapabilityRegistry, CapabilityUnavailableError, ConfigManager, ConfigStore, ConsoleDestination, ConsoleLoggingAddon, CustomActionRegistry, DEFAULT_DATA_PATH, DEVICE_SETTINGS_CONTRIBUTION_METHODS, DEVICE_STATUS_METHOD, DataPlaneRegistry, DeviceManagerAddon, DeviceRegistry, DeviceStore, EVENT_TOPIC_PREFIX, EngineManagerResolver, EventBus, FeatureManager, FilesystemStorageAddon, FilesystemStorageProvider, FrameDecoder, FsStorageBackend, HEALTH_MONITOR_GRACE_PERIOD_MS, HEALTH_MONITOR_RETRY_INTERVALS_MS, HEALTH_MONITOR_TICK_MS, HUB_CAP_FWD_ACTION, HUB_CAP_FWD_SERVICE, HubForwarderAddon, HubForwarderDestination, HubLogForwarder, HubNodeRegistry, INFRA_CAPABILITIES, IntegrationRegistry, JobJournal, LifecycleJobEngine, LifecycleStateMachine, LocalAuthAddon, LocalChildClient, LocalChildRegistry, LogManager, LogRingBuffer, METHOD_ACCESS_MAP, ModelDownloadService, NATIVE_PROVIDER_SERVICE_INFIX, NATIVE_SCAN_DEPTH, NativeMetricsAddon, NativeMetricsProvider, NetworkQualityTracker, NotificationService, PYTHON_VERSION, PipelineRunner, PipelineValidator, PythonEnvManager, RESTART_MARKER_FILE, RUNTIME_DEFAULTS, ReadinessRegistry, ReadinessTimeoutError, ReplEngine, RingBuffer, ScopedLogger, ScopedTokenManager, SocketChannel, SqliteSettingsAddon, SqliteSettingsBackend, StagingArea, StorageLocationManager, StorageManager, StorageOrchestratorAddon, StorageOrchestratorService, SystemConfigAddon, SystemEventBus, TRADITIONAL_NATIVE_PACKAGES, ToastService, UDS_NO_ROUTE_PREFIX, UdsLocalTransportClient, UdsLocalTransportServer, UserManager, WinstonDestination, WinstonLoggingAddon, __resetCapUsageRegistryForTests, adaptBrokerToCluster, addonSettingsCapability, bootstrapSchema, brokerCallForCap, brokerTransportLink, buildBinaryPath, buildCapRouters, buildLinkChain, buildNativeCapProxy, buildNodeManifest, buildStorageLocationRegistry, buildUdsNativeCapProxy, builderMountedCapNames, callRegisterNodeWithRetry, callWithServiceDiscovery, capActionName, capActionSuffix, capBareAction, capServiceName, classifyCapRoute, clearPendingRestart, clusterEventTopic, clusterSecretMatches, collectModelFiles, contentTypeFor, copyDirRecursive, copyExtraFileDirs, createAddonContext, createAddonDataPlaneFacility, createAddonService, createAuthenticatedFileServer, createBroker, createBrokerDeviceManagerApi, createCoreCapService, createFileDataPlaneHandler, createHubCapForwardService, createHubService, createKernelHwAccel, createLocalTransport, createParentUnownedCallHandler, createProcessService, createReadinessService, createReadinessServiceForRegistry, createScopedProcessManager, createStreamProbeBrokerService, createUdsAddonContext, createUdsEventBridge, createUdsEventBus, createUdsLogger, createUdsLoggerWithControl, deleteModelFromDisk, deriveAgentListenPort, describeProviderKindDrift, detectWorkspacePackagesDir, downloadBinary, downloadFile, downloadModel, emitDownForOwnedCaps, encodeFrame, ensureAddonNativePrebuilds, ensureBinary, ensureDir, ensureFfmpeg, ensureLibraryBuilt, ensureModel, ensureNativePrebuilds, ensurePython, ensureTlsCert, expandCapMethods, fetchJson, findInPath, formatLogLine, getBrokerEventBus, getCapUsageRegistry, getFfmpegDownloadUrl, getModelFilePath, getMoleculerEventStats, getOrInitReadinessRegistry, getOrInitReadinessRegistryForClient, getPidStats, getPlatformInfo, getPythonDownloadUrl, getRestartMarkerPath, getSinglePidStats, getWorkerDeviceRegistry, hasDotNode, hashClusterSecret, installManifestNativeDeps, installManifestPythonDeps, installPackageFromNpm, installPythonPackages, installPythonRequirements, ipcChildLink, ipcParentLink, isAddonDeploySource, isArrayOutputSchema, isClusterSecretMismatchError, isCollectionArrayMethod, isInfraCapability, isModelDownloaded, isSourceNewer, loadTlsCert, localEndpointPath, localProviderLink, mountNativeCapService, parseCapAction, parseRangeHeader, parseTokenizedUrl, proxyToUpstream, readPendingRestart, readinessKey, registerEventBusService, resolveFilePath, resolveHwAccel, resolveNpmInvocation, runNpm, scheduleSelfRestart, scopeKey, scopesAllowDeviceCap, serializeTypedArrays, setHubConnected, setNodeEventInterest, stripCamstackDeps, subscribePassthrough, udsChildLogToWorkerEntry, validateProviderRegistrations, writePendingRestart };

package/dist/kernel/deps/ensure-addon-natives.d.ts

@@ -0,0 +1,41 @@
+import { IScopedLogger } from '@camstack/types';
+import { PrebuildFetchFn, PrebuildTarget } from './ensure-native-prebuilds.js';
+/** Per-native outcome of the ensure pass. */
+export type NativeEnsureOutcome = 'already-present' | 'copied' | 'fetched' | 'missing';
+export interface NativeEnsureResult {
+    readonly pkg: string;
+    readonly outcome: NativeEnsureOutcome;
+}
+export interface EnsureAddonNativePrebuildsOptions {
+    /** Addon package name — for loud error messages naming module + addon. */
+    readonly addonName: string;
+    readonly logger: IScopedLogger;
+    /**
+     * Bundled addon copy dir (the `installCopy` `sourceDir` / a
+     * `CAMSTACK_BUNDLED_ADDONS_DIR/<addon>` copy) whose own
+     * `node_modules/<pkg>` may carry a prebuilt `.node` for THIS machine.
+     * Copied in directly before any network fetch. Absent on the npm/tgz path.
+     */
+    readonly bundledSourceDir?: string;
+    /** Running ABI/arch the fetched prebuild must match. Defaults to the process. */
+    readonly target?: PrebuildTarget;
+    /** Native package set. Defaults to `TRADITIONAL_NATIVE_PACKAGES`. */
+    readonly packages?: readonly string[];
+    /** Override the fetcher (tests). Production uses the bundled `prebuild-install`. */
+    readonly fetchPrebuild?: PrebuildFetchFn;
+    /** Override the `.node` presence scan (tests). */
+    readonly hasNative?: (moduleDir: string) => boolean;
+}
+/**
+ * Ensure every referenced traditional native in `<addonDir>/node_modules`
+ * carries its compiled `.node` after the addon's `npm install`. Bundled-copy
+ * first (offline), prebuild-fetch fallback, LOUD throw on a residual miss.
+ *
+ * SKIPS a native absent from the addon's own `node_modules` (it resolves via a
+ * hoisted host copy — not this addon's concern). A NO-OP in docker / dev where
+ * npm produced a working `.node` (already-present). Returns the per-native
+ * outcomes for logging/tests.
+ *
+ * @throws if any required native is still source-only after copy + fetch.
+ */
+export declare function ensureAddonNativePrebuilds(addonDir: string, options: EnsureAddonNativePrebuildsOptions): Promise<readonly NativeEnsureResult[]>;

package/dist/kernel/deps/ensure-native-prebuilds.d.ts

@@ -1,4 +1,6 @@
 import { IScopedLogger } from '@camstack/types';
+/** Bounded recursive `.node` scan depth inside a module dir. */
+export declare const NATIVE_SCAN_DEPTH = 4;
 /**
  * Traditional (compile-or-prebuild) natives an installed closure must carry a
  * `.node` for. Only these are ENSURE-able by a prebuild re-fetch; N-API natives
@@ -23,6 +25,8 @@ export interface EnsureNativePrebuildsOptions {
     /** Override the fetcher (tests). Production uses the bundled `prebuild-install`. */
     readonly fetchPrebuild?: PrebuildFetchFn;
 }
+/** Bounded recursive scan for ANY `*.node` file under `dir`. */
+export declare function hasDotNode(dir: string, maxDepth: number): boolean;
 /**
  * Ensure every traditional native in `<closureDir>/node_modules` carries its
  * compiled `.node`, fetching the prebuild for the running ABI when missing.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/system",
-  "version": "1.2.3",
+  "version": "1.2.5",
   "description": "Core addon for CamStack — builtins, pipeline, process management, auth, logging, events",
   "keywords": [
     "camstack",