@camstack/system 1.2.2 → 1.2.3

package/dist/index.js

@@ -1,8 +1,8 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_chunk = require("./chunk-Cek0wNdY.js");
-const require_dist = require("./dist-CkdNC8US.js");
+const require_dist = require("./dist-CQZxGJ8u.js");
 const require_model_download_service = require("./model-download-service-hf0ookyy.js");
-const require_manifest_python_deps = require("./manifest-python-deps-DRq5MreI.js");
+const require_manifest_python_deps = require("./manifest-python-deps-Cd7ocUBi.js");
 const require_resource_monitor = require("./resource-monitor-DNNomR-i.js");
 const require_builtins_sqlite_storage_filesystem_storage_addon = require("./builtins/sqlite-storage/filesystem-storage.addon.js");
 const require_builtins_sqlite_storage_sqlite_settings_addon = require("./builtins/sqlite-storage/sqlite-settings.addon.js");
@@ -184,7 +184,7 @@ function proxyToUpstream(opts) {
 }
 //#endregion
 //#region src/python/python-env-manager.ts
-var execFileAsync$3 = (0, node_util.promisify)(node_child_process.execFile);
+var execFileAsync$4 = (0, node_util.promisify)(node_child_process.execFile);
 var PythonEnvManager = class {
 	venvPath;
 	cachedProbe = null;
@@ -194,12 +194,12 @@ var PythonEnvManager = class {
 	async probe() {
 		if (this.cachedProbe) return this.cachedProbe;
 		for (const cmd of ["python3", "python"]) try {
-			const { stdout } = await execFileAsync$3(cmd, ["--version"]);
+			const { stdout } = await execFileAsync$4(cmd, ["--version"]);
 			const version = stdout.trim().replace("Python ", "");
 			const major = parseInt(version.split(".")[0] ?? "0", 10);
 			const minor = parseInt(version.split(".")[1] ?? "0", 10);
 			if (major < 3 || major === 3 && minor < 10) continue;
-			const { stdout: pathOut } = await execFileAsync$3(cmd, ["-c", "import sys; print(sys.executable)"]);
+			const { stdout: pathOut } = await execFileAsync$4(cmd, ["-c", "import sys; print(sys.executable)"]);
 			this.cachedProbe = {
 				available: true,
 				version,
@@ -215,13 +215,13 @@ var PythonEnvManager = class {
 	async ensure(options) {
 		const probe = await this.probe();
 		if (!probe.available || !probe.path) throw new Error("Python 3.10+ is required but not found on this system");
-		if (!node_fs.existsSync(node_path.join(this.venvPath, "bin", "python"))) await execFileAsync$3(probe.path, [
+		if (!node_fs.existsSync(node_path.join(this.venvPath, "bin", "python"))) await execFileAsync$4(probe.path, [
 			"-m",
 			"venv",
 			this.venvPath
 		]);
 		const venvPython = node_path.join(this.venvPath, "bin", "python");
-		if (options.packages.length > 0) await execFileAsync$3(venvPython, [
+		if (options.packages.length > 0) await execFileAsync$4(venvPython, [
 			"-m",
 			"pip",
 			"install",
@@ -1692,7 +1692,7 @@ function matchPath(pattern, path) {
 }
 //#endregion
 //#region src/tls/cert-manager.ts
-var execFileAsync$2 = (0, node_util.promisify)(node_child_process.execFile);
+var execFileAsync$3 = (0, node_util.promisify)(node_child_process.execFile);
 /**
 * Ensure a self-signed TLS certificate exists in the given directory.
 * Generates one if missing. Returns paths to cert and key files.
@@ -1729,7 +1729,7 @@ async function ensureTlsCert(dataDir, options) {
 	for (const dns of sanDns) sanParts.push(`DNS:${dns}`);
 	for (const ip of sanIps) sanParts.push(`IP:${ip}`);
 	const sanString = sanParts.join(",");
-	await execFileAsync$2("openssl", [
+	await execFileAsync$3("openssl", [
 		"req",
 		"-x509",
 		"-newkey",
@@ -2597,7 +2597,7 @@ var AddonEngineManager = class {
 };
 //#endregion
 //#region src/kernel/fs-utils.ts
-var execFileAsync$1 = (0, node_util.promisify)(node_child_process.execFile);
+var execFileAsync$2 = (0, node_util.promisify)(node_child_process.execFile);
 /**
 * Ensure a directory exists (recursive).
 * Single source of truth — replaces scattered mkdirSync calls.
@@ -2781,7 +2781,7 @@ function ensureLibraryBuilt(packageName, packagesDir) {
 async function installPackageFromNpm(packageName, targetDir) {
 	const tmpDir = await node_fs.promises.mkdtemp(node_path.join(node_os.tmpdir(), "camstack-install-"));
 	try {
-		const { stdout } = await execFileAsync$1("npm", [
+		const { stdout } = await execFileAsync$2("npm", [
 			"pack",
 			packageName,
 			"--pack-destination",
@@ -2795,7 +2795,7 @@ async function installPackageFromNpm(packageName, targetDir) {
 		const tgzPath = node_path.join(tmpDir, tgzFilename);
 		const extractDir = node_path.join(tmpDir, "extracted");
 		ensureDir(extractDir);
-		await execFileAsync$1("tar", [
+		await execFileAsync$2("tar", [
 			"-xzf",
 			tgzPath,
 			"-C",
@@ -3031,7 +3031,7 @@ var AddonManifest = class {
 };
 //#endregion
 //#region src/kernel/addon-installer.ts
-var execFileAsync = (0, node_util.promisify)(node_child_process.execFile);
+var execFileAsync$1 = (0, node_util.promisify)(node_child_process.execFile);
 function parseInstallSource(value) {
 	switch (value) {
 		case "npm":
@@ -3318,6 +3318,7 @@ var AddonInstaller = class AddonInstaller {
 		await node_fs.promises.writeFile(node_path.join(targetDir, "package.json"), JSON.stringify(stripBundledDeps(pkgData), null, 2));
 		await copyDirRecursive(distDir, node_path.join(targetDir, "dist"));
 		await copyExtraFileDirs(pkgData, sourceDir, targetDir);
+		require_manifest_python_deps.copyBundledNativeModules(sourceDir, targetDir, this.logger);
 		await node_fs.promises.writeFile(node_path.join(targetDir, ".install-source"), "local");
 		const localPkgVersion = require_dist.asString(pkgData.version, "0.0.0");
 		this.manifest.upsert(packageName, {
@@ -3488,7 +3489,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("tar", [
+			await execFileAsync$1("tar", [
 				"-xzf",
 				tgzPath,
 				"-C",
@@ -80143,7 +80144,7 @@ var require_compression = /* @__PURE__ */ require_chunk.__commonJSMin(((exports,
 	var { defaultsDeep } = require_lodash();
 	var { parseByteString } = require_utils$3();
 	var zlib = require("zlib");
-	var { promisify } = require("util");
+	var { promisify: promisify$1 } = require("util");
 	/**
 	* This is a transmission compression middleware. It supports
 	* the `deflate`, `deflateRaw` & `gzip` compression methods.
@@ -80161,16 +80162,16 @@ var require_compression = /* @__PURE__ */ require_chunk.__commonJSMin(((exports,
 		const threshold = parseByteString(opts.threshold);
 		switch (opts.method) {
 			case "deflate":
-				compress = promisify(zlib.deflate);
-				decompress = promisify(zlib.inflate);
+				compress = promisify$1(zlib.deflate);
+				decompress = promisify$1(zlib.inflate);
 				break;
 			case "deflateRaw":
-				compress = promisify(zlib.deflateRaw);
-				decompress = promisify(zlib.inflateRaw);
+				compress = promisify$1(zlib.deflateRaw);
+				decompress = promisify$1(zlib.inflateRaw);
 				break;
 			case "gzip":
-				compress = promisify(zlib.gzip);
-				decompress = promisify(zlib.gunzip);
+				compress = promisify$1(zlib.gzip);
+				decompress = promisify$1(zlib.gunzip);
 				break;
 			default:
  /* istanbul ignore next */
@@ -93397,6 +93398,145 @@ 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;
@@ -93494,6 +93634,7 @@ exports.StorageOrchestratorAddon = require_builtins_storage_orchestrator_storage
 exports.StorageOrchestratorService = require_builtins_storage_orchestrator_storage_orchestrator_addon.StorageOrchestratorService;
 exports.SystemConfigAddon = require_builtins_system_config_system_config_addon.SystemConfigAddon;
 exports.SystemEventBus = SystemEventBus;
+exports.TRADITIONAL_NATIVE_PACKAGES = TRADITIONAL_NATIVE_PACKAGES;
 exports.ToastService = ToastService;
 exports.UDS_NO_ROUTE_PREFIX = require_manifest_python_deps.UDS_NO_ROUTE_PREFIX;
 exports.UdsLocalTransportClient = require_manifest_python_deps.UdsLocalTransportClient;
@@ -93586,6 +93727,7 @@ Object.defineProperty(exports, "ensureFfmpeg", {
 });
 exports.ensureLibraryBuilt = ensureLibraryBuilt;
 exports.ensureModel = require_model_download_service.ensureModel;
+exports.ensureNativePrebuilds = ensureNativePrebuilds;
 Object.defineProperty(exports, "ensurePython", {
 	enumerable: true,
 	get: function() {

package/dist/index.mjs

@@ -1,6 +1,6 @@
-import { At as EventCategory$1, Dt as resolveCapMount, Et as readinessKey, F as kebabToCamel, I as lifecycleJobSchema, K as procedureAuthKey, M as isCollectionArrayMethod, N as isObjectInput, O as extractNestedAddonId, Ot as scopeKey, P as isVoidInput, Tt as parseJsonUnknown$1, U as objectInputDeclaresAddonId, _t as asString$1, ct as DEVICE_STATUS_METHOD, ft as ReadinessRegistry, gt as asNumber, ht as asJsonObject$1, it as errMsg$1, j as isArrayOutputSchema, o as METHOD_ACCESS_MAP, ot as DATAPLANE_SECRET_HEADER$1, p as addonSettingsCapability, pt as ReadinessTimeoutError, s as RUNTIME_DEFAULTS, st as DEVICE_SETTINGS_CONTRIBUTION_METHODS, t as ALL_CAPABILITY_DEFINITIONS, vt as createEvent, wt as parseJsonObject, xt as expandCapMethods, yt as emitDownForOwnedCaps, z as looseSchema } from "./dist-DTTTjPCL.mjs";
+import { At as EventCategory$1, Dt as resolveCapMount, Et as readinessKey, F as kebabToCamel, I as lifecycleJobSchema, K as procedureAuthKey, M as isCollectionArrayMethod, N as isObjectInput, O as extractNestedAddonId, Ot as scopeKey, P as isVoidInput, Tt as parseJsonUnknown$1, U as objectInputDeclaresAddonId, _t as asString$1, ct as DEVICE_STATUS_METHOD, ft as ReadinessRegistry, gt as asNumber, ht as asJsonObject$1, it as errMsg$1, j as isArrayOutputSchema, o as METHOD_ACCESS_MAP, ot as DATAPLANE_SECRET_HEADER$1, p as addonSettingsCapability, pt as ReadinessTimeoutError, s as RUNTIME_DEFAULTS, st as DEVICE_SETTINGS_CONTRIBUTION_METHODS, t as ALL_CAPABILITY_DEFINITIONS, vt as createEvent, wt as parseJsonObject, xt as expandCapMethods, yt as emitDownForOwnedCaps, z as looseSchema } from "./dist-72yufD8v.mjs";
 import { a as downloadModel, c as getModelFilePath, d as contentTypeFor, f as createAuthenticatedFileServer, h as resolveFilePath, i as downloadFile, l as isModelDownloaded, m as parseTokenizedUrl, n as collectModelFiles, o as ensureModel, p as parseRangeHeader, r as deleteModelFromDisk, s as fetchJson, t as ModelDownloadService, u as createFileDataPlaneHandler } from "./model-download-service-Cp9f4dk6.mjs";
-import { $ as buildNativeCapProxy, A as createHubCapForwardService, B as AGENT_CAP_FWD_ACTION, C as brokerTransportLink, Ct as createAddonDataPlaneFacility, 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 resolveAddonClass, 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 resolveNpmInvocation, 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, x as getCapUsageRegistry, xt as runNpm, y as CapUsageRegistry, yt as installManifestNativeDeps, z as UDS_NO_ROUTE_PREFIX } from "./manifest-python-deps-s_-uULmp.mjs";
+import { $ as buildNativeCapProxy, A as createHubCapForwardService, B as AGENT_CAP_FWD_ACTION, C as brokerTransportLink, Ct as resolveAddonClass, 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 runNpm, 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 resolveNpmInvocation, y as CapUsageRegistry, yt as copyBundledNativeModules, z as UDS_NO_ROUTE_PREFIX } from "./manifest-python-deps-6__QF75g.mjs";
 import { n as getSinglePidStats, t as getPidStats } from "./resource-monitor-Le3l0qS2.mjs";
 import { FilesystemStorageAddon, t as FilesystemStorageProvider } from "./builtins/sqlite-storage/filesystem-storage.addon.mjs";
 import { SqliteSettingsAddon, t as SqliteSettingsBackend } from "./builtins/sqlite-storage/sqlite-settings.addon.mjs";
@@ -29,7 +29,7 @@ import { accessSync, constants, existsSync, mkdirSync, readFileSync } from "node
 import * as path$39 from "node:path";
 import { dirname, isAbsolute, join, posix, resolve, win32 } from "node:path";
 import { X509Certificate, createHash, randomUUID, timingSafeEqual } from "node:crypto";
-import { asJsonObject, parseJsonUnknown } from "@camstack/types/addon";
+import { asJsonObject, errMsg, parseJsonUnknown } from "@camstack/types/addon";
 import { execFile, spawn } from "node:child_process";
 import * as util$10 from "node:util";
 import { promisify } from "node:util";
@@ -176,7 +176,7 @@ function proxyToUpstream(opts) {
 }
 //#endregion
 //#region src/python/python-env-manager.ts
-var execFileAsync$3 = promisify(execFile);
+var execFileAsync$4 = promisify(execFile);
 var PythonEnvManager = class {
 	venvPath;
 	cachedProbe = null;
@@ -186,12 +186,12 @@ var PythonEnvManager = class {
 	async probe() {
 		if (this.cachedProbe) return this.cachedProbe;
 		for (const cmd of ["python3", "python"]) try {
-			const { stdout } = await execFileAsync$3(cmd, ["--version"]);
+			const { stdout } = await execFileAsync$4(cmd, ["--version"]);
 			const version = stdout.trim().replace("Python ", "");
 			const major = parseInt(version.split(".")[0] ?? "0", 10);
 			const minor = parseInt(version.split(".")[1] ?? "0", 10);
 			if (major < 3 || major === 3 && minor < 10) continue;
-			const { stdout: pathOut } = await execFileAsync$3(cmd, ["-c", "import sys; print(sys.executable)"]);
+			const { stdout: pathOut } = await execFileAsync$4(cmd, ["-c", "import sys; print(sys.executable)"]);
 			this.cachedProbe = {
 				available: true,
 				version,
@@ -207,13 +207,13 @@ var PythonEnvManager = class {
 	async ensure(options) {
 		const probe = await this.probe();
 		if (!probe.available || !probe.path) throw new Error("Python 3.10+ is required but not found on this system");
-		if (!fs$17.existsSync(path$39.join(this.venvPath, "bin", "python"))) await execFileAsync$3(probe.path, [
+		if (!fs$17.existsSync(path$39.join(this.venvPath, "bin", "python"))) await execFileAsync$4(probe.path, [
 			"-m",
 			"venv",
 			this.venvPath
 		]);
 		const venvPython = path$39.join(this.venvPath, "bin", "python");
-		if (options.packages.length > 0) await execFileAsync$3(venvPython, [
+		if (options.packages.length > 0) await execFileAsync$4(venvPython, [
 			"-m",
 			"pip",
 			"install",
@@ -1684,7 +1684,7 @@ function matchPath(pattern, path) {
 }
 //#endregion
 //#region src/tls/cert-manager.ts
-var execFileAsync$2 = promisify(execFile);
+var execFileAsync$3 = promisify(execFile);
 /**
 * Ensure a self-signed TLS certificate exists in the given directory.
 * Generates one if missing. Returns paths to cert and key files.
@@ -1721,7 +1721,7 @@ async function ensureTlsCert(dataDir, options) {
 	for (const dns of sanDns) sanParts.push(`DNS:${dns}`);
 	for (const ip of sanIps) sanParts.push(`IP:${ip}`);
 	const sanString = sanParts.join(",");
-	await execFileAsync$2("openssl", [
+	await execFileAsync$3("openssl", [
 		"req",
 		"-x509",
 		"-newkey",
@@ -2589,7 +2589,7 @@ var AddonEngineManager = class {
 };
 //#endregion
 //#region src/kernel/fs-utils.ts
-var execFileAsync$1 = promisify(execFile);
+var execFileAsync$2 = promisify(execFile);
 /**
 * Ensure a directory exists (recursive).
 * Single source of truth — replaces scattered mkdirSync calls.
@@ -2773,7 +2773,7 @@ function ensureLibraryBuilt(packageName, packagesDir) {
 async function installPackageFromNpm(packageName, targetDir) {
 	const tmpDir = await fs$17.promises.mkdtemp(path$39.join(os$18.tmpdir(), "camstack-install-"));
 	try {
-		const { stdout } = await execFileAsync$1("npm", [
+		const { stdout } = await execFileAsync$2("npm", [
 			"pack",
 			packageName,
 			"--pack-destination",
@@ -2787,7 +2787,7 @@ async function installPackageFromNpm(packageName, targetDir) {
 		const tgzPath = path$39.join(tmpDir, tgzFilename);
 		const extractDir = path$39.join(tmpDir, "extracted");
 		ensureDir(extractDir);
-		await execFileAsync$1("tar", [
+		await execFileAsync$2("tar", [
 			"-xzf",
 			tgzPath,
 			"-C",
@@ -3023,7 +3023,7 @@ var AddonManifest = class {
 };
 //#endregion
 //#region src/kernel/addon-installer.ts
-var execFileAsync = promisify(execFile);
+var execFileAsync$1 = promisify(execFile);
 function parseInstallSource(value) {
 	switch (value) {
 		case "npm":
@@ -3310,6 +3310,7 @@ var AddonInstaller = class AddonInstaller {
 		await fs$17.promises.writeFile(path$39.join(targetDir, "package.json"), JSON.stringify(stripBundledDeps(pkgData), null, 2));
 		await copyDirRecursive(distDir, path$39.join(targetDir, "dist"));
 		await copyExtraFileDirs(pkgData, sourceDir, targetDir);
+		copyBundledNativeModules(sourceDir, targetDir, this.logger);
 		await fs$17.promises.writeFile(path$39.join(targetDir, ".install-source"), "local");
 		const localPkgVersion = asString$1(pkgData.version, "0.0.0");
 		this.manifest.upsert(packageName, {
@@ -3480,7 +3481,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("tar", [
+			await execFileAsync$1("tar", [
 				"-xzf",
 				tgzPath,
 				"-C",
@@ -93389,4 +93390,143 @@ var LifecycleJobEngine = class {
 	}
 };
 //#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, 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, 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 };
+//#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 };

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

@@ -0,0 +1,36 @@
+import { IScopedLogger } from '@camstack/types';
+/**
+ * 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).
+ */
+export declare const TRADITIONAL_NATIVE_PACKAGES: readonly string[];
+/** The running Node ABI/arch the fetched prebuild must match. */
+export interface PrebuildTarget {
+    /** Node version, e.g. `process.versions.node` (`24.16.0`). */
+    readonly nodeVersion: string;
+    /** CPU arch, e.g. `process.arch` (`arm64` | `x64`). */
+    readonly arch: string;
+}
+/** Fetch a `<moduleDir>`'s prebuild for `target`. Test seam. */
+export type PrebuildFetchFn = (moduleDir: string, target: PrebuildTarget) => Promise<void>;
+export interface EnsureNativePrebuildsOptions {
+    readonly logger: IScopedLogger;
+    /** Defaults to the running process (`process.versions.node` / `process.arch`). */
+    readonly target?: PrebuildTarget;
+    /** Override the native package set (tests). */
+    readonly packages?: readonly string[];
+    /** Override the fetcher (tests). Production uses the bundled `prebuild-install`. */
+    readonly fetchPrebuild?: PrebuildFetchFn;
+}
+/**
+ * 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).
+ */
+export declare function ensureNativePrebuilds(closureDir: string, options: EnsureNativePrebuildsOptions): Promise<readonly string[]>;