@camstack/system 1.2.164 → 1.2.165

package/dist/addon-runner.js

@@ -1,5 +1,5 @@
 const require_chunk = require("./chunk-Cek0wNdY.js");
-const require_manifest_system_deps = require("./manifest-system-deps-CJLqfJUs.js");
+const require_manifest_system_deps = require("./manifest-system-deps-uflHvHDB.js");
 const require_custom_action_registry = require("./custom-action-registry-jY0NOZK8.js");
 let node_path = require("node:path");
 node_path = require_chunk.__toESM(node_path);

package/dist/addon-runner.mjs

@@ -1,4 +1,4 @@
-import { Ct as resolveAddonClass, N as createUdsLoggerWithControl, P as LocalChildClient, Rt as RUNNER_RSS_BUDGET_ENV, St as installManifestNativeDeps, Zt as startRunnerHeapWatch, a as createUdsAddonContext, at as getWorkerNativeCapSnapshot, it as getWorkerNativeCapProvider, lt as validateProviderRegistrations, n as installManifestPythonDeps, nn as emitHeapDiagnosticReport, st as setWorkerNativeCapsChangeListener, t as installManifestSystemDeps } from "./manifest-system-deps-Bk_XLYbB.mjs";
+import { Ct as resolveAddonClass, N as createUdsLoggerWithControl, P as LocalChildClient, Rt as RUNNER_RSS_BUDGET_ENV, St as installManifestNativeDeps, Zt as startRunnerHeapWatch, a as createUdsAddonContext, at as getWorkerNativeCapSnapshot, it as getWorkerNativeCapProvider, lt as validateProviderRegistrations, n as installManifestPythonDeps, nn as emitHeapDiagnosticReport, st as setWorkerNativeCapsChangeListener, t as installManifestSystemDeps } from "./manifest-system-deps-D2GebQTp.mjs";
 import { t as CustomActionRegistry } from "./custom-action-registry-F__gp_VX.mjs";
 import { register } from "node:module";
 import * as path$1 from "node:path";

package/dist/builtins/sqlite-storage/index.d.ts

@@ -4,7 +4,7 @@ export { DeviceStore } from './device-store.js';
 export { FilesystemStorageAddon, FilesystemStorageAddon as default, } from './filesystem-storage.addon.js';
 export { FilesystemStorageProvider } from './filesystem-storage-provider.js';
 export type { SqliteOpLabel, SqliteOpSample, SqliteOpStat } from './query-profiler.js';
-export { SQLITE_PROFILE_REPORT_FLOOR_MS, SQLITE_PROFILE_REPORT_INTERVAL_MS, SQLITE_PROFILE_TOP_N, SQLITE_SLOW_CALL_MS, SqliteOpProfiler, } from './query-profiler.js';
+export { SQLITE_ENGINE_STORM_WALL_SHARE, SQLITE_PROFILE_REPORT_FLOOR_MS, SQLITE_PROFILE_REPORT_INTERVAL_MS, SQLITE_PROFILE_TOP_N, SQLITE_SLOW_CALL_MS, sqliteEngineStorm, SqliteOpProfiler, } from './query-profiler.js';
 export { SQLITE_JOURNAL_SIZE_LIMIT_BYTES, SQLITE_MMAP_CEILING_BYTES, SQLITE_MMAP_FLOOR_BYTES, SQLITE_PAGE_CACHE_CEILING_KIB, SQLITE_PAGE_CACHE_FLOOR_KIB, sqliteMmapSizeFor, sqlitePageCacheKibFor, } from './sqlite-pragmas.js';
 export { SqliteSettingsAddon } from './sqlite-settings.addon.js';
 export { SqliteSettingsBackend } from './sqlite-settings-backend.js';

package/dist/builtins/sqlite-storage/index.js

@@ -57,6 +57,7 @@ exports.DeviceStore = DeviceStore;
 exports.DeviceStore$1 = DeviceStore;
 exports.FilesystemStorageAddon = require_builtins_sqlite_storage_filesystem_storage_addon.FilesystemStorageAddon;
 exports.FilesystemStorageProvider = require_builtins_sqlite_storage_filesystem_storage_addon.FilesystemStorageProvider;
+exports.SQLITE_ENGINE_STORM_WALL_SHARE = require_builtins_sqlite_storage_sqlite_settings_addon.SQLITE_ENGINE_STORM_WALL_SHARE;
 exports.SQLITE_JOURNAL_SIZE_LIMIT_BYTES = require_builtins_sqlite_storage_sqlite_settings_addon.SQLITE_JOURNAL_SIZE_LIMIT_BYTES;
 exports.SQLITE_MMAP_CEILING_BYTES = require_builtins_sqlite_storage_sqlite_settings_addon.SQLITE_MMAP_CEILING_BYTES;
 exports.SQLITE_MMAP_FLOOR_BYTES = require_builtins_sqlite_storage_sqlite_settings_addon.SQLITE_MMAP_FLOOR_BYTES;
@@ -75,5 +76,6 @@ exports.WAL_IDLE_QUIET_MS = require_builtins_sqlite_storage_sqlite_settings_addo
 exports.WAL_MAINTENANCE_INTERVAL_MS = require_builtins_sqlite_storage_sqlite_settings_addon.WAL_MAINTENANCE_INTERVAL_MS;
 exports.WalMaintenance = require_builtins_sqlite_storage_sqlite_settings_addon.WalMaintenance;
 exports.default = require_builtins_sqlite_storage_filesystem_storage_addon.FilesystemStorageAddon;
+exports.sqliteEngineStorm = require_builtins_sqlite_storage_sqlite_settings_addon.sqliteEngineStorm;
 exports.sqliteMmapSizeFor = require_builtins_sqlite_storage_sqlite_settings_addon.sqliteMmapSizeFor;
 exports.sqlitePageCacheKibFor = require_builtins_sqlite_storage_sqlite_settings_addon.sqlitePageCacheKibFor;

package/dist/builtins/sqlite-storage/index.mjs

@@ -1,5 +1,5 @@
 import { FilesystemStorageAddon, t as FilesystemStorageProvider } from "./filesystem-storage.addon.mjs";
-import { SqliteSettingsAddon, _ as SQLITE_PROFILE_TOP_N, a as WalMaintenance, c as SQLITE_JOURNAL_SIZE_LIMIT_BYTES, d as SQLITE_PAGE_CACHE_CEILING_KIB, f as SQLITE_PAGE_CACHE_FLOOR_KIB, g as SQLITE_PROFILE_REPORT_INTERVAL_MS, h as SQLITE_PROFILE_REPORT_FLOOR_MS, i as WAL_MAINTENANCE_INTERVAL_MS, l as SQLITE_MMAP_CEILING_BYTES, m as sqlitePageCacheKibFor, n as WAL_HIGH_WATER_BYTES, o as SqliteSettingsBackend, p as sqliteMmapSizeFor, r as WAL_IDLE_QUIET_MS, t as WAL_CHECKPOINT_BUSY_TIMEOUT_MS, u as SQLITE_MMAP_FLOOR_BYTES, v as SQLITE_SLOW_CALL_MS, y as SqliteOpProfiler } from "./sqlite-settings.addon.mjs";
+import { SqliteSettingsAddon, _ as SQLITE_PROFILE_REPORT_INTERVAL_MS, a as WalMaintenance, b as SqliteOpProfiler, c as SQLITE_JOURNAL_SIZE_LIMIT_BYTES, d as SQLITE_PAGE_CACHE_CEILING_KIB, f as SQLITE_PAGE_CACHE_FLOOR_KIB, g as SQLITE_PROFILE_REPORT_FLOOR_MS, h as SQLITE_ENGINE_STORM_WALL_SHARE, i as WAL_MAINTENANCE_INTERVAL_MS, l as SQLITE_MMAP_CEILING_BYTES, m as sqlitePageCacheKibFor, n as WAL_HIGH_WATER_BYTES, o as SqliteSettingsBackend, p as sqliteMmapSizeFor, r as WAL_IDLE_QUIET_MS, t as WAL_CHECKPOINT_BUSY_TIMEOUT_MS, u as SQLITE_MMAP_FLOOR_BYTES, v as SQLITE_PROFILE_TOP_N, x as sqliteEngineStorm, y as SQLITE_SLOW_CALL_MS } from "./sqlite-settings.addon.mjs";
 //#region src/builtins/sqlite-storage/config-store.ts
 var ConfigStore = class {
 	db;
@@ -46,4 +46,4 @@ var DeviceStore = class {
 	}
 };
 //#endregion
-export { ConfigStore, DeviceStore, FilesystemStorageAddon, FilesystemStorageAddon as default, FilesystemStorageProvider, SQLITE_JOURNAL_SIZE_LIMIT_BYTES, SQLITE_MMAP_CEILING_BYTES, SQLITE_MMAP_FLOOR_BYTES, SQLITE_PAGE_CACHE_CEILING_KIB, SQLITE_PAGE_CACHE_FLOOR_KIB, SQLITE_PROFILE_REPORT_FLOOR_MS, SQLITE_PROFILE_REPORT_INTERVAL_MS, SQLITE_PROFILE_TOP_N, SQLITE_SLOW_CALL_MS, SqliteOpProfiler, SqliteSettingsAddon, SqliteSettingsBackend, WAL_CHECKPOINT_BUSY_TIMEOUT_MS, WAL_HIGH_WATER_BYTES, WAL_IDLE_QUIET_MS, WAL_MAINTENANCE_INTERVAL_MS, WalMaintenance, sqliteMmapSizeFor, sqlitePageCacheKibFor };
+export { ConfigStore, DeviceStore, FilesystemStorageAddon, FilesystemStorageAddon as default, FilesystemStorageProvider, SQLITE_ENGINE_STORM_WALL_SHARE, SQLITE_JOURNAL_SIZE_LIMIT_BYTES, SQLITE_MMAP_CEILING_BYTES, SQLITE_MMAP_FLOOR_BYTES, SQLITE_PAGE_CACHE_CEILING_KIB, SQLITE_PAGE_CACHE_FLOOR_KIB, SQLITE_PROFILE_REPORT_FLOOR_MS, SQLITE_PROFILE_REPORT_INTERVAL_MS, SQLITE_PROFILE_TOP_N, SQLITE_SLOW_CALL_MS, SqliteOpProfiler, SqliteSettingsAddon, SqliteSettingsBackend, WAL_CHECKPOINT_BUSY_TIMEOUT_MS, WAL_HIGH_WATER_BYTES, WAL_IDLE_QUIET_MS, WAL_MAINTENANCE_INTERVAL_MS, WalMaintenance, sqliteEngineStorm, sqliteMmapSizeFor, sqlitePageCacheKibFor };

package/dist/builtins/sqlite-storage/query-profiler.d.ts

@@ -133,6 +133,27 @@ export declare const SQLITE_PROFILE_REPORT_INTERVAL_MS = 60000;
 export declare const SQLITE_PROFILE_REPORT_FLOOR_MS = 250;
 /** Pairs named in one report line. Enough to see the shape, short enough to read. */
 export declare const SQLITE_PROFILE_TOP_N = 5;
+/**
+ * Share of window wall-clock at which ONE shape is a storm, not a busy engine.
+ *
+ * Measured 2026-08-31: the OFFSET census on `pipeline-analytics:media` was
+ * 88.7 % of wall for six hours. A healthy bounded census (20 s budget in a
+ * 60 s window) is 33 % and must not warn. Half the loop is the line between
+ * "the engine is working" and "the cluster is queuing behind one query".
+ *
+ * Cap-usage rate cannot name this class — see `sqliteEngineStorm`.
+ */
+export declare const SQLITE_ENGINE_STORM_WALL_SHARE = 0.5;
+/**
+ * The dominating shape if it held {@link SQLITE_ENGINE_STORM_WALL_SHARE} of
+ * the window, otherwise `null`.
+ *
+ * Share is of WINDOW wall, not of busy time: an engine that is 90 % busy with
+ * ten equal shapes is healthy; one shape at 50 % of wall is the 2026-08-31
+ * store saturation regardless of what else ran. `stats` must already be
+ * busiest-first (as {@link SqliteOpProfiler.drain} returns them).
+ */
+export declare function sqliteEngineStorm(stats: readonly SqliteOpStat[], windowMs: number): SqliteOpStat | null;
 export interface SqliteOpProfilerOptions {
     readonly logger: IScopedLogger;
     /** Injected for tests; production reads the wall clock. */

package/dist/index.js

@@ -26,7 +26,7 @@ require("./builtins/system-config/index.js");
 const require_builtins_winston_logging_index = require("./builtins/winston-logging/index.js");
 const require_file_data_plane = require("./file-data-plane-DO8KbxCe.js");
 const require_tls$1 = require("./tls-BxQlomxd.js");
-const require_manifest_system_deps = require("./manifest-system-deps-CJLqfJUs.js");
+const require_manifest_system_deps = require("./manifest-system-deps-uflHvHDB.js");
 const require_resource_monitor = require("./resource-monitor-CdnzxBLP.js");
 const require_custom_action_registry = require("./custom-action-registry-jY0NOZK8.js");
 let zod = require("zod");

package/dist/index.mjs

@@ -25,7 +25,7 @@ import "./builtins/system-config/index.mjs";
 import { WinstonDestination, WinstonLoggingAddon } from "./builtins/winston-logging/index.mjs";
 import { a as parseTokenizedUrl, c as collectModelFiles, d as downloadModel, f as ensureModel, h as isModelDownloaded, i as parseRangeHeader, l as deleteModelFromDisk, m as getModelFilePath, n as contentTypeFor, o as resolveFilePath, p as fetchJson, r as createAuthenticatedFileServer, s as ModelDownloadService, t as createFileDataPlaneHandler, u as downloadFile } from "./file-data-plane-BhKdxJgf.mjs";
 import { C as registerLanHttpHandler, S as readLanHttpState, _ as DEFAULT_LAN_HTTP_PORT, a as writeTlsMode, b as bindPendingLanHttp, c as loadTlsCert, d as collectCertIdentity, f as CA_VALIDITY_DAYS, g as evaluateExistingCert, h as SERVER_AUTH_OID, i as writeExtraSans, l as reissueTlsLeaf, m as MAX_LEAF_VALIDITY_DAYS, n as readTlsAccessStatus, o as validateUploadedTls, p as LEAF_RENEWAL_WINDOW_DAYS, r as readTlsMode, s as ensureTlsCert, t as readExtraSans, u as CA_COMMON_NAME, v as allFamiliesListenHost, x as closeLanHttp, y as applyLanHttp } from "./tls-DOTmtLCW.mjs";
-import { $ as FrameDecoder, $t as DECISIVE_HEAP_SPACES, A as createUdsEventBus, At as HEAP_WATCH_INTERVAL_MS, B as CapRouteError, Bt as buildHeapSample, C as ipcParentLink, Cn as diffEventPlane, Ct as resolveAddonClass, D as createHubCapForwardService, Dt as HEAP_RECLAIM_MIN_INTERVAL_MS, E as HUB_CAP_FWD_SERVICE, Et as createAddonDataPlaneFacility, F as LocalChildRegistry, Ft as RSS_BUDGET_REANNOUNCE_MIN_MS, G as PARENT_ROUTED_PROVIDER_ADDON_ID, Gt as hubMainRssBudget, H as callWithServiceDiscovery, Ht as createLoopDelayMeter, I as UDS_NO_ROUTE_PREFIX, It as RSS_BUDGET_RELEASE_RATIO, J as createLocalTransport, Jt as reclaimIntervalMs, K as __resetCapUsageRegistryForTests, Kt as nextRssBudgetState, L as AGENT_CAP_FWD_ACTION, Lt as RUNNER_HEAP_WATCH_INTERVAL_MS, M as createUdsLogger, Mt as HUB_MAIN_HEAP_WATCH_LABEL, N as createUdsLoggerWithControl, Nt as HUB_MAIN_RSS_BUDGET_MB, O as createParentUnownedCallHandler, Ot as HEAP_RECLAIM_STEADY_STATE_INTERVAL_MS, P as LocalChildClient, Pt as HUB_RSS_BUDGET_ENV, Q as localEndpointPath, Qt as strandedMb, R as AGENT_CAP_FWD_SERVICE, Rt as RUNNER_RSS_BUDGET_ENV, S as buildLinkChain, Sn as createEventPlaneReader, St as installManifestNativeDeps, T as HUB_CAP_FWD_ACTION, Tt as runNpm, U as readMoleculerFanoutMode, Ut as createV8Reclaimer, V as classifyCapRoute, Vt as createDeferredHeapWatchSink, W as CapUsageRegistry, Wt as describeRss, X as UdsLocalTransportServer, Xt as startHeapWatch, Y as UdsLocalTransportClient, Yt as shouldReclaim, Z as SocketChannel, Zt as startRunnerHeapWatch, _ as AddonDepsManager, _n as sampleSocketDirection, _t as serializeTypedArrays, a as createUdsAddonContext, an as heapSpaceField, b as brokerCallForCap, bn as EVENT_PLANE_TOP_N, bt as CapabilityUnavailableError, c as getOrInitReadinessRegistryForClient, cn as EMPTY_SOCKET_PLANE_BASELINE, ct as createAddonService, d as clusterEventTopic, dn as createSocketPlaneReader, dt as capActionName, en as HEAP_SPACE_REPORT_MIN_MB, et as encodeFrame, f as getBrokerEventBus, fn as diffSocketPlane, ft as capActionSuffix, g as subscribePassthrough, gn as recordSocketFrame, gt as deserializeTypedArrays, h as setNodeEventInterest, hn as createSocketDirectionCounters, ht as parseCapAction, i as createAddonContext, in as heapSnapshotAuthorised, j as udsChildLogToWorkerEntry, jt as HEAP_WATCH_WARN_RATIO, k as createUdsEventBridge, kt as HEAP_RECLAIM_TRIGGER_MB, l as setHubConnected, ln as SOCKET_PLANE_TOP_N, lt as validateProviderRegistrations, m as registerEventBusService, mn as EMPTY_SOCKET_DIRECTION, mt as capServiceName, n as installManifestPythonDeps, nn as emitHeapDiagnosticReport, nt as buildUdsNativeCapProxy, o as getWorkerDeviceRegistry, on as readHeapSpaces, ot as mountNativeCapService, p as getMoleculerEventStats, pn as formatSocketPlane, pt as capBareAction, q as getCapUsageRegistry, qt as parseRssBudgetMb, r as adaptBrokerToCluster, rn as formatHeapSpaces, rt as createBrokerDeviceManagerApi, s as getOrInitReadinessRegistry, sn as selectReportedSpaces, t as installManifestSystemDeps, tn as RUNNER_HEAP_SNAPSHOT_ENV, tt as buildNativeCapProxy, u as EVENT_TOPIC_PREFIX, un as createSocketPlaneMeter, ut as NATIVE_PROVIDER_SERVICE_INFIX, v as createKernelHwAccel, vn as socketDirectionBytes, vt as DeviceRegistry, w as localProviderLink, wn as formatEventPlane, wt as resolveNpmInvocation, x as brokerTransportLink, xn as createEventPlaneMeter, xt as copyBundledNativeModules, y as resolveHwAccel, yn as socketDirectionMessages, yt as CapabilityHandle, z as CapRouteResolver, zt as ZERO_LOOP_DELAY } from "./manifest-system-deps-Bk_XLYbB.mjs";
+import { $ as FrameDecoder, $t as DECISIVE_HEAP_SPACES, A as createUdsEventBus, At as HEAP_WATCH_INTERVAL_MS, B as CapRouteError, Bt as buildHeapSample, C as ipcParentLink, Cn as diffEventPlane, Ct as resolveAddonClass, D as createHubCapForwardService, Dt as HEAP_RECLAIM_MIN_INTERVAL_MS, E as HUB_CAP_FWD_SERVICE, Et as createAddonDataPlaneFacility, F as LocalChildRegistry, Ft as RSS_BUDGET_REANNOUNCE_MIN_MS, G as PARENT_ROUTED_PROVIDER_ADDON_ID, Gt as hubMainRssBudget, H as callWithServiceDiscovery, Ht as createLoopDelayMeter, I as UDS_NO_ROUTE_PREFIX, It as RSS_BUDGET_RELEASE_RATIO, J as createLocalTransport, Jt as reclaimIntervalMs, K as __resetCapUsageRegistryForTests, Kt as nextRssBudgetState, L as AGENT_CAP_FWD_ACTION, Lt as RUNNER_HEAP_WATCH_INTERVAL_MS, M as createUdsLogger, Mt as HUB_MAIN_HEAP_WATCH_LABEL, N as createUdsLoggerWithControl, Nt as HUB_MAIN_RSS_BUDGET_MB, O as createParentUnownedCallHandler, Ot as HEAP_RECLAIM_STEADY_STATE_INTERVAL_MS, P as LocalChildClient, Pt as HUB_RSS_BUDGET_ENV, Q as localEndpointPath, Qt as strandedMb, R as AGENT_CAP_FWD_SERVICE, Rt as RUNNER_RSS_BUDGET_ENV, S as buildLinkChain, Sn as createEventPlaneReader, St as installManifestNativeDeps, T as HUB_CAP_FWD_ACTION, Tt as runNpm, U as readMoleculerFanoutMode, Ut as createV8Reclaimer, V as classifyCapRoute, Vt as createDeferredHeapWatchSink, W as CapUsageRegistry, Wt as describeRss, X as UdsLocalTransportServer, Xt as startHeapWatch, Y as UdsLocalTransportClient, Yt as shouldReclaim, Z as SocketChannel, Zt as startRunnerHeapWatch, _ as AddonDepsManager, _n as sampleSocketDirection, _t as serializeTypedArrays, a as createUdsAddonContext, an as heapSpaceField, b as brokerCallForCap, bn as EVENT_PLANE_TOP_N, bt as CapabilityUnavailableError, c as getOrInitReadinessRegistryForClient, cn as EMPTY_SOCKET_PLANE_BASELINE, ct as createAddonService, d as clusterEventTopic, dn as createSocketPlaneReader, dt as capActionName, en as HEAP_SPACE_REPORT_MIN_MB, et as encodeFrame, f as getBrokerEventBus, fn as diffSocketPlane, ft as capActionSuffix, g as subscribePassthrough, gn as recordSocketFrame, gt as deserializeTypedArrays, h as setNodeEventInterest, hn as createSocketDirectionCounters, ht as parseCapAction, i as createAddonContext, in as heapSnapshotAuthorised, j as udsChildLogToWorkerEntry, jt as HEAP_WATCH_WARN_RATIO, k as createUdsEventBridge, kt as HEAP_RECLAIM_TRIGGER_MB, l as setHubConnected, ln as SOCKET_PLANE_TOP_N, lt as validateProviderRegistrations, m as registerEventBusService, mn as EMPTY_SOCKET_DIRECTION, mt as capServiceName, n as installManifestPythonDeps, nn as emitHeapDiagnosticReport, nt as buildUdsNativeCapProxy, o as getWorkerDeviceRegistry, on as readHeapSpaces, ot as mountNativeCapService, p as getMoleculerEventStats, pn as formatSocketPlane, pt as capBareAction, q as getCapUsageRegistry, qt as parseRssBudgetMb, r as adaptBrokerToCluster, rn as formatHeapSpaces, rt as createBrokerDeviceManagerApi, s as getOrInitReadinessRegistry, sn as selectReportedSpaces, t as installManifestSystemDeps, tn as RUNNER_HEAP_SNAPSHOT_ENV, tt as buildNativeCapProxy, u as EVENT_TOPIC_PREFIX, un as createSocketPlaneMeter, ut as NATIVE_PROVIDER_SERVICE_INFIX, v as createKernelHwAccel, vn as socketDirectionBytes, vt as DeviceRegistry, w as localProviderLink, wn as formatEventPlane, wt as resolveNpmInvocation, x as brokerTransportLink, xn as createEventPlaneMeter, xt as copyBundledNativeModules, y as resolveHwAccel, yn as socketDirectionMessages, yt as CapabilityHandle, z as CapRouteResolver, zt as ZERO_LOOP_DELAY } from "./manifest-system-deps-D2GebQTp.mjs";
 import { n as getSinglePidStats, t as getPidStats } from "./resource-monitor-BWmQ5i-o.mjs";
 import { t as CustomActionRegistry } from "./custom-action-registry-F__gp_VX.mjs";
 import { z } from "zod";

package/dist/kernel/deps/manifest-system-deps.d.ts

@@ -1,12 +1,15 @@
 import { AddonDeclaration, IScopedLogger } from '@camstack/types';
-/** Host package managers this mechanism knows how to drive. */
-export type SystemPackageManager = 'apt' | 'apk' | 'dnf' | 'brew';
+import { PackageInstallRequest, PackageInstallResult } from './system-package-broker.js';
+import { SystemPackageManager } from './system-package-allowlist.js';
+export type { SystemPackageManager } from './system-package-allowlist.js';
 /** Test seams — production callers omit these. */
 export interface InstallManifestSystemDepsOptions {
     readonly hasBinary?: (binary: string) => Promise<boolean>;
     readonly detectManager?: () => Promise<SystemPackageManager | null>;
     readonly run?: (command: string, args: readonly string[]) => Promise<void>;
     readonly platform?: NodeJS.Platform;
+    readonly helperAvailable?: () => Promise<boolean>;
+    readonly requestInstall?: (req: PackageInstallRequest) => Promise<PackageInstallResult>;
 }
 /**
  * Satisfy every `systemDependencies` entry the declaration carries.

package/dist/kernel/deps/system-package-allowlist.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Packages the privileged helper will install (D326).
+ *
+ * The helper process reads `scripts/docker/pkg-allowlist.json` (baked into
+ * the image). This module is the runner-side copy of the same list, so an
+ * unknown package is refused before a socket write. Keep them identical —
+ * `scripts/check-pkg-allowlist.ts` fails CI when they drift.
+ */
+export type SystemPackageManager = 'apt' | 'apk' | 'dnf' | 'brew';
+export type DistroPackageManager = Exclude<SystemPackageManager, 'brew'>;
+export declare const DISTRO_PACKAGE_ALLOWLIST: Readonly<Record<DistroPackageManager, readonly string[]>>;
+export declare function packageIsAllowlisted(manager: SystemPackageManager, packageName: string): boolean;

package/dist/kernel/deps/system-package-broker.d.ts

@@ -0,0 +1,31 @@
+import { SystemPackageManager } from './system-package-allowlist.js';
+export interface PackageInstallRequest {
+    readonly addonId: string;
+    readonly binary: string;
+    readonly manager: SystemPackageManager;
+    readonly packageName: string;
+}
+export interface PackageInstallResult {
+    readonly ok: boolean;
+    readonly error?: string;
+}
+export type PackageInstallDecision = {
+    readonly kind: 'helper';
+} | {
+    readonly kind: 'local';
+} | {
+    readonly kind: 'refuse';
+    readonly reason: 'not-allowlisted' | 'helper-unavailable';
+};
+/**
+ * Who is allowed to run the package manager for this request.
+ *
+ * Apt/apk/dnf need root. In the CamStack container that is the
+ * `camstack-pkgd` helper, not the runner and not hub-main (both uid
+ * 1001). Brew is owned by the logged-in user, so it stays in-process.
+ */
+export declare function decidePackageInstall(input: {
+    readonly manager: SystemPackageManager;
+    readonly packageName: string;
+    readonly helperAvailable: boolean;
+}): PackageInstallDecision;

package/dist/kernel/deps/system-package-client.d.ts

@@ -0,0 +1,9 @@
+import { PackageInstallRequest, PackageInstallResult } from './system-package-broker.js';
+/** Default path the entrypoint binds before dropping to uid 1001. */
+export declare const DEFAULT_PKGD_SOCKET = "/run/camstack/pkgd.sock";
+export declare function pkgdSocketPath(): string;
+export declare function privilegedHelperAvailable(socketPath?: string): boolean;
+/**
+ * One JSON object per line. The helper answers one request per connection.
+ */
+export declare function requestPrivilegedInstall(req: PackageInstallRequest, socketPath?: string, timeoutMs?: number): Promise<PackageInstallResult>;

package/dist/{manifest-system-deps-Bk_XLYbB.mjs → manifest-system-deps-D2GebQTp.mjs}

@@ -8,6 +8,7 @@ import { isAbsolute, join } from "node:path";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import * as fs from "node:fs";
+import { existsSync } from "node:fs";
 import * as os from "node:os";
 import { tmpdir } from "node:os";
 import { createServer } from "node:http";
@@ -15,7 +16,7 @@ import * as v8 from "node:v8";
 import { monitorEventLoopDelay } from "node:perf_hooks";
 import * as vm from "node:vm";
 import { BOOT_RECOVERY_BACKOFF_MS, DATAPLANE_SECRET_HEADER, DeviceType, DisposerChain, EventCategory, ReadinessRegistry, asJsonObject, asString, createDeviceProxy, createEventBusSliceSource, deviceOpsCapability, emitReadiness, errMsg, expandCapMethods, readNodePin, scopeKey, sleep, withCapInputDefaults } from "@camstack/types/addon";
-import { connect, createServer as createServer$1 } from "node:net";
+import { connect, createConnection, createServer as createServer$1 } from "node:net";
 import { TRPCClientError, createTRPCClient } from "@trpc/client";
 //#region src/kernel/event-plane-report.ts
 /**
@@ -9694,6 +9695,106 @@ async function installManifestPythonDeps(declaration, addonDir, deps, logger) {
 	await deps.installPythonRequirements(reqAbs);
 }
 //#endregion
+//#region src/kernel/deps/system-package-allowlist.ts
+var DISTRO_PACKAGE_ALLOWLIST = {
+	apt: ["smbclient"],
+	apk: ["samba-client"],
+	dnf: ["samba-client"]
+};
+function packageIsAllowlisted(manager, packageName) {
+	if (manager === "brew") return true;
+	if (packageName.length === 0) return false;
+	if (!/^[a-zA-Z0-9][a-zA-Z0-9+._-]*$/.test(packageName)) return false;
+	return DISTRO_PACKAGE_ALLOWLIST[manager].includes(packageName);
+}
+//#endregion
+//#region src/kernel/deps/system-package-broker.ts
+/**
+* Who is allowed to run the package manager for this request.
+*
+* Apt/apk/dnf need root. In the CamStack container that is the
+* `camstack-pkgd` helper, not the runner and not hub-main (both uid
+* 1001). Brew is owned by the logged-in user, so it stays in-process.
+*/
+function decidePackageInstall(input) {
+	if (input.manager === "brew") return { kind: "local" };
+	if (!packageIsAllowlisted(input.manager, input.packageName)) return {
+		kind: "refuse",
+		reason: "not-allowlisted"
+	};
+	if (!input.helperAvailable) return {
+		kind: "refuse",
+		reason: "helper-unavailable"
+	};
+	return { kind: "helper" };
+}
+function pkgdSocketPath() {
+	return process.env["CAMSTACK_PKGD_SOCKET"] ?? "/run/camstack/pkgd.sock";
+}
+function privilegedHelperAvailable(socketPath = pkgdSocketPath()) {
+	return existsSync(socketPath);
+}
+/**
+* One JSON object per line. The helper answers one request per connection.
+*/
+function requestPrivilegedInstall(req, socketPath = pkgdSocketPath(), timeoutMs = 360 * 1e3) {
+	return new Promise((resolve) => {
+		const socket = createConnection({ path: socketPath });
+		const chunks = [];
+		const finish = (result) => {
+			socket.destroy();
+			resolve(result);
+		};
+		const timer = setTimeout(() => {
+			finish({
+				ok: false,
+				error: `privileged helper timed out after ${timeoutMs}ms`
+			});
+		}, timeoutMs);
+		socket.on("connect", () => {
+			socket.write(`${JSON.stringify({
+				v: 1,
+				...req
+			})}\n`);
+		});
+		socket.on("data", (data) => {
+			chunks.push(data);
+			const text = Buffer.concat(chunks).toString("utf8");
+			const nl = text.indexOf("\n");
+			if (nl === -1) return;
+			clearTimeout(timer);
+			try {
+				const parsed = JSON.parse(text.slice(0, nl));
+				finish({
+					ok: parsed.ok === true,
+					...parsed.error !== void 0 ? { error: parsed.error } : {}
+				});
+			} catch (err) {
+				finish({
+					ok: false,
+					error: err instanceof Error ? err.message : String(err)
+				});
+			}
+		});
+		socket.on("error", (err) => {
+			clearTimeout(timer);
+			finish({
+				ok: false,
+				error: err.message
+			});
+		});
+		socket.on("end", () => {
+			if (chunks.length === 0) {
+				clearTimeout(timer);
+				finish({
+					ok: false,
+					error: "privileged helper closed without a reply"
+				});
+			}
+		});
+	});
+}
+//#endregion
 //#region src/kernel/deps/manifest-system-deps.ts
 /**
 * Auto-install the host binaries declared in an addon's manifest
@@ -9724,6 +9825,9 @@ async function installManifestPythonDeps(declaration, addonDir, deps, logger) {
 *  4. **Platform reality is stated, not assumed.** An unsupported host logs
 *     which manager it looked for and continues. Silence would read as
 *     "installed".
+*  5. **Apt is not the runner's.** Distro package managers need root. The
+*     runner and hub-main are uid 1001 (`gosu` in the entrypoint). Apt/apk/dnf
+*     go through `camstack-pkgd` (allowlisted). Brew stays in-process.
 *
 * Every branch that declines to install SAYS SO. A dependency step that
 * produced no line at all is indistinguishable from one that never ran, and
@@ -9746,12 +9850,16 @@ async function installManifestSystemDeps(declaration, logger, options = {}) {
 	const detectManager = options.detectManager ?? defaultDetectManager;
 	const run = options.run ?? defaultRun;
 	const platform = options.platform ?? process.platform;
+	const helperAvailable = options.helperAvailable ?? (async () => privilegedHelperAvailable());
+	const requestInstall = options.requestInstall ?? ((req) => requestPrivilegedInstall(req));
 	for (const dep of deps) try {
 		await satisfyOne(dep, declaration.id, {
 			hasBinary,
 			detectManager,
 			run,
-			platform
+			platform,
+			helperAvailable,
+			requestInstall
 		}, logger);
 	} catch (err) {
 		logger.warn("system dependency step failed", { meta: {
@@ -9789,15 +9897,43 @@ async function satisfyOne(dep, addonId, rt, logger) {
 		} });
 		return;
 	}
-	const plan = planFor(manager, packageName);
+	const decision = decidePackageInstall({
+		manager,
+		packageName,
+		helperAvailable: await rt.helperAvailable()
+	});
+	if (decision.kind === "refuse") {
+		const message = decision.reason === "helper-unavailable" ? "system dependency missing and the privileged helper is not running — apt cannot run as uid 1001" : "system dependency missing and the package is not on the helper allowlist";
+		logger.warn(message, { meta: {
+			addonId,
+			binary: dep.binary,
+			manager,
+			package: packageName,
+			reason: decision.reason,
+			...dep.reason !== void 0 ? { reason: dep.reason } : {}
+		} });
+		return;
+	}
 	logger.info("installing system dependency", { meta: {
 		addonId,
 		binary: dep.binary,
 		manager,
-		package: packageName
+		package: packageName,
+		via: decision.kind
 	} });
 	try {
-		for (const [command, args] of plan.steps) await rt.run(command, args);
+		if (decision.kind === "helper") {
+			const result = await rt.requestInstall({
+				addonId,
+				binary: dep.binary,
+				manager,
+				packageName
+			});
+			if (!result.ok) throw new Error(result.error ?? "privileged helper refused");
+		} else {
+			const plan = planFor(manager, packageName);
+			for (const [command, args] of plan.steps) await rt.run(command, args);
+		}
 	} catch (err) {
 		logger.warn("system dependency install failed — the addon loads, its capability must refuse", { meta: {
 			addonId,

package/dist/{manifest-system-deps-CJLqfJUs.js → manifest-system-deps-uflHvHDB.js}

@@ -9698,6 +9698,106 @@ async function installManifestPythonDeps(declaration, addonDir, deps, logger) {
 	await deps.installPythonRequirements(reqAbs);
 }
 //#endregion
+//#region src/kernel/deps/system-package-allowlist.ts
+var DISTRO_PACKAGE_ALLOWLIST = {
+	apt: ["smbclient"],
+	apk: ["samba-client"],
+	dnf: ["samba-client"]
+};
+function packageIsAllowlisted(manager, packageName) {
+	if (manager === "brew") return true;
+	if (packageName.length === 0) return false;
+	if (!/^[a-zA-Z0-9][a-zA-Z0-9+._-]*$/.test(packageName)) return false;
+	return DISTRO_PACKAGE_ALLOWLIST[manager].includes(packageName);
+}
+//#endregion
+//#region src/kernel/deps/system-package-broker.ts
+/**
+* Who is allowed to run the package manager for this request.
+*
+* Apt/apk/dnf need root. In the CamStack container that is the
+* `camstack-pkgd` helper, not the runner and not hub-main (both uid
+* 1001). Brew is owned by the logged-in user, so it stays in-process.
+*/
+function decidePackageInstall(input) {
+	if (input.manager === "brew") return { kind: "local" };
+	if (!packageIsAllowlisted(input.manager, input.packageName)) return {
+		kind: "refuse",
+		reason: "not-allowlisted"
+	};
+	if (!input.helperAvailable) return {
+		kind: "refuse",
+		reason: "helper-unavailable"
+	};
+	return { kind: "helper" };
+}
+function pkgdSocketPath() {
+	return process.env["CAMSTACK_PKGD_SOCKET"] ?? "/run/camstack/pkgd.sock";
+}
+function privilegedHelperAvailable(socketPath = pkgdSocketPath()) {
+	return (0, node_fs.existsSync)(socketPath);
+}
+/**
+* One JSON object per line. The helper answers one request per connection.
+*/
+function requestPrivilegedInstall(req, socketPath = pkgdSocketPath(), timeoutMs = 360 * 1e3) {
+	return new Promise((resolve) => {
+		const socket = (0, node_net.createConnection)({ path: socketPath });
+		const chunks = [];
+		const finish = (result) => {
+			socket.destroy();
+			resolve(result);
+		};
+		const timer = setTimeout(() => {
+			finish({
+				ok: false,
+				error: `privileged helper timed out after ${timeoutMs}ms`
+			});
+		}, timeoutMs);
+		socket.on("connect", () => {
+			socket.write(`${JSON.stringify({
+				v: 1,
+				...req
+			})}\n`);
+		});
+		socket.on("data", (data) => {
+			chunks.push(data);
+			const text = Buffer.concat(chunks).toString("utf8");
+			const nl = text.indexOf("\n");
+			if (nl === -1) return;
+			clearTimeout(timer);
+			try {
+				const parsed = JSON.parse(text.slice(0, nl));
+				finish({
+					ok: parsed.ok === true,
+					...parsed.error !== void 0 ? { error: parsed.error } : {}
+				});
+			} catch (err) {
+				finish({
+					ok: false,
+					error: err instanceof Error ? err.message : String(err)
+				});
+			}
+		});
+		socket.on("error", (err) => {
+			clearTimeout(timer);
+			finish({
+				ok: false,
+				error: err.message
+			});
+		});
+		socket.on("end", () => {
+			if (chunks.length === 0) {
+				clearTimeout(timer);
+				finish({
+					ok: false,
+					error: "privileged helper closed without a reply"
+				});
+			}
+		});
+	});
+}
+//#endregion
 //#region src/kernel/deps/manifest-system-deps.ts
 /**
 * Auto-install the host binaries declared in an addon's manifest
@@ -9728,6 +9828,9 @@ async function installManifestPythonDeps(declaration, addonDir, deps, logger) {
 *  4. **Platform reality is stated, not assumed.** An unsupported host logs
 *     which manager it looked for and continues. Silence would read as
 *     "installed".
+*  5. **Apt is not the runner's.** Distro package managers need root. The
+*     runner and hub-main are uid 1001 (`gosu` in the entrypoint). Apt/apk/dnf
+*     go through `camstack-pkgd` (allowlisted). Brew stays in-process.
 *
 * Every branch that declines to install SAYS SO. A dependency step that
 * produced no line at all is indistinguishable from one that never ran, and
@@ -9750,12 +9853,16 @@ async function installManifestSystemDeps(declaration, logger, options = {}) {
 	const detectManager = options.detectManager ?? defaultDetectManager;
 	const run = options.run ?? defaultRun;
 	const platform = options.platform ?? process.platform;
+	const helperAvailable = options.helperAvailable ?? (async () => privilegedHelperAvailable());
+	const requestInstall = options.requestInstall ?? ((req) => requestPrivilegedInstall(req));
 	for (const dep of deps) try {
 		await satisfyOne(dep, declaration.id, {
 			hasBinary,
 			detectManager,
 			run,
-			platform
+			platform,
+			helperAvailable,
+			requestInstall
 		}, logger);
 	} catch (err) {
 		logger.warn("system dependency step failed", { meta: {
@@ -9793,15 +9900,43 @@ async function satisfyOne(dep, addonId, rt, logger) {
 		} });
 		return;
 	}
-	const plan = planFor(manager, packageName);
+	const decision = decidePackageInstall({
+		manager,
+		packageName,
+		helperAvailable: await rt.helperAvailable()
+	});
+	if (decision.kind === "refuse") {
+		const message = decision.reason === "helper-unavailable" ? "system dependency missing and the privileged helper is not running — apt cannot run as uid 1001" : "system dependency missing and the package is not on the helper allowlist";
+		logger.warn(message, { meta: {
+			addonId,
+			binary: dep.binary,
+			manager,
+			package: packageName,
+			reason: decision.reason,
+			...dep.reason !== void 0 ? { reason: dep.reason } : {}
+		} });
+		return;
+	}
 	logger.info("installing system dependency", { meta: {
 		addonId,
 		binary: dep.binary,
 		manager,
-		package: packageName
+		package: packageName,
+		via: decision.kind
 	} });
 	try {
-		for (const [command, args] of plan.steps) await rt.run(command, args);
+		if (decision.kind === "helper") {
+			const result = await rt.requestInstall({
+				addonId,
+				binary: dep.binary,
+				manager,
+				packageName
+			});
+			if (!result.ok) throw new Error(result.error ?? "privileged helper refused");
+		} else {
+			const plan = planFor(manager, packageName);
+			for (const [command, args] of plan.steps) await rt.run(command, args);
+		}
 	} catch (err) {
 		logger.warn("system dependency install failed — the addon loads, its capability must refuse", { meta: {
 			addonId,

package/package.json

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