@camstack/system 1.0.2

package/dist/intel-accelerators-Gg0P5mnl.js

@@ -0,0 +1,20 @@
+require("./chunk-Cek0wNdY.js");
+//#region src/builtins/platform-probe/intel-accelerators.ts
+var INTEL_VENDOR = "0x8086";
+function classifyIntelAccelerators(fsx) {
+	let gpu = null;
+	for (const node of fsx.listRenderNodes()) if (fsx.readVendor(node).trim() === INTEL_VENDOR) {
+		gpu = {
+			type: "intel",
+			name: `Intel iGPU (${node.split("/").pop()})`
+		};
+		break;
+	}
+	const npu = fsx.exists("/dev/accel/accel0") ? { type: "intel-npu" } : null;
+	return {
+		gpu,
+		npu
+	};
+}
+//#endregion
+exports.classifyIntelAccelerators = classifyIntelAccelerators;

package/dist/intel-accelerators-hGgpZ0pX.mjs

@@ -0,0 +1,19 @@
+//#region src/builtins/platform-probe/intel-accelerators.ts
+var INTEL_VENDOR = "0x8086";
+function classifyIntelAccelerators(fsx) {
+	let gpu = null;
+	for (const node of fsx.listRenderNodes()) if (fsx.readVendor(node).trim() === INTEL_VENDOR) {
+		gpu = {
+			type: "intel",
+			name: `Intel iGPU (${node.split("/").pop()})`
+		};
+		break;
+	}
+	const npu = fsx.exists("/dev/accel/accel0") ? { type: "intel-npu" } : null;
+	return {
+		gpu,
+		npu
+	};
+}
+//#endregion
+export { classifyIntelAccelerators };

package/dist/kernel/addon-class-resolver.d.ts

@@ -0,0 +1,4 @@
+import { ICamstackAddon } from '@camstack/types';
+type AddonConstructor = new () => ICamstackAddon;
+export declare function resolveAddonClass(mod: Record<string, unknown>): AddonConstructor | undefined;
+export {};

package/dist/kernel/addon-engine-manager.d.ts

@@ -0,0 +1,22 @@
+import { ICamstackAddon, AddonContext, IEngineManager, IEngineInstance } from '@camstack/types';
+import { AddonLoader } from './addon-loader.js';
+export declare class AddonEngineManager implements IEngineManager {
+    private readonly loader;
+    private readonly baseContext;
+    private engines;
+    constructor(loader: AddonLoader, baseContext: Partial<Omit<AddonContext, 'addonConfig'>>);
+    /**
+     * Get or create an addon engine for the given effective config.
+     * Cameras with the same addonId + effective config share the same engine.
+     */
+    getOrCreateEngine(addonId: string, globalConfig: Record<string, unknown>, cameraOverride?: Record<string, unknown>): Promise<IEngineInstance>;
+    /** Get all active engines */
+    getActiveEngines(): Map<string, ICamstackAddon>;
+    /** Shutdown a specific engine by its config key */
+    shutdownEngine(configKey: string): Promise<void>;
+    /** Shutdown all engines */
+    shutdownAll(): Promise<void>;
+    /** Compute a deterministic config key (visible for tests) */
+    computeConfigKey(addonId: string, effectiveConfig: Record<string, unknown>): string;
+    private hashConfig;
+}

package/dist/kernel/addon-health-monitor.d.ts

@@ -0,0 +1,154 @@
+import { IEventBus, IScopedLogger } from '@camstack/types';
+/**
+ * Kernel-level addon health monitor.
+ *
+ * Tracks load + initialize + crash failures across the addon population
+ * and drives an aggressive auto-retry loop independent of any single
+ * addon's logic. Mirrors the spec the operator approved:
+ *
+ *   - Boot grace: 5 minutes from `start()`. Failures during this window
+ *     are silently retried (slow-starting addons must have a chance to
+ *     come up before alarming).
+ *   - Retry cadence: 60s after first failure, 120s after second, then
+ *     300s for every subsequent attempt — never gives up.
+ *   - Tick interval: 30s. Faster than the shortest retry interval (60s)
+ *     so a scheduled retry never waits more than ~30s past its target.
+ *   - Post-grace alerting: emits `AddonLoadFailed` exactly once per
+ *     failure-streak; AlertCenter consumes the event to create a
+ *     persistent operator-visible alert. Recovery emits
+ *     `AddonLoadRecovered` so the alert can dismiss itself.
+ *   - In-memory state only. Server restart resets the grace window
+ *     (operator's call — they want a clean slate after a manual restart).
+ *
+ * The monitor never restarts addons itself: it knows nothing about
+ * tarball install / dist paths / dependency injection. It calls a
+ * caller-injected `retryFn(packageName)` which is the AddonRegistry's
+ * existing reload path — the monitor is just the scheduler + alert
+ * gate. This keeps the kernel package addon-agnostic.
+ *
+ * Group-runner / fork crashes: `process-service.ts` already respawns
+ * crashed children with exponential backoff. The monitor doesn't
+ * duplicate that loop — it only marks the addon `failed` when the
+ * crash supervisor reports it (via `recordFailure`) and clears it on
+ * `READY:<nodeId>` recovery (via `recordSuccess`). The kernel's
+ * spawn handler wires both edges.
+ */
+export declare const HEALTH_MONITOR_TICK_MS = 30000;
+export declare const HEALTH_MONITOR_GRACE_PERIOD_MS: number;
+/** Retry intervals after each failure (capped — never stops). */
+export declare const HEALTH_MONITOR_RETRY_INTERVALS_MS: readonly number[];
+export type AddonHealthPhase = 'pending' | 'healthy' | 'failed';
+export interface AddonHealthState {
+    readonly packageName: string;
+    readonly addonId?: string;
+    phase: AddonHealthPhase;
+    retryCount: number;
+    firstFailureAt: number | null;
+    lastAttemptAt: number | null;
+    lastError: {
+        readonly message: string;
+        readonly stack?: string;
+    } | null;
+    nextRetryAt: number | null;
+    /** True once `AddonLoadFailed` has been emitted for the current streak. */
+    alertEmitted: boolean;
+    /** True if a retry attempt is currently in flight. */
+    retrying: boolean;
+}
+export interface AddonHealthSnapshot {
+    readonly packageName: string;
+    readonly addonId?: string;
+    readonly phase: AddonHealthPhase;
+    readonly retryCount: number;
+    readonly firstFailureAt: number | null;
+    readonly lastAttemptAt: number | null;
+    readonly lastError: {
+        readonly message: string;
+        readonly stack?: string;
+    } | null;
+    readonly nextRetryAt: number | null;
+    readonly alertEmitted: boolean;
+    readonly retrying: boolean;
+    /** Whether the boot grace window is still open (suppresses alerts). */
+    readonly inGracePeriod: boolean;
+}
+export interface AddonHealthMonitorOptions {
+    readonly eventBus: IEventBus;
+    readonly logger: IScopedLogger;
+    /**
+     * Called by the monitor's tick loop when a failed package is due
+     * for a retry attempt. Should perform the actual reload (tarball
+     * extract + addon-loader re-import + initialize). Returns true on
+     * success; throws on failure (the monitor records the new error).
+     */
+    readonly retryFn: (packageName: string) => Promise<void>;
+    /** Override for tests. Defaults to `HEALTH_MONITOR_TICK_MS`. */
+    readonly tickIntervalMs?: number;
+    /** Override for tests. Defaults to `HEALTH_MONITOR_GRACE_PERIOD_MS`. */
+    readonly gracePeriodMs?: number;
+    /** Override for tests. Defaults to `HEALTH_MONITOR_RETRY_INTERVALS_MS`. */
+    readonly retryIntervalsMs?: readonly number[];
+    /** Override clock for deterministic tests. */
+    readonly now?: () => number;
+}
+export declare class AddonHealthMonitor {
+    private readonly state;
+    private readonly bootAt;
+    private readonly tickIntervalMs;
+    private readonly gracePeriodMs;
+    private readonly retryIntervalsMs;
+    private readonly eventBus;
+    private readonly logger;
+    private readonly retryFn;
+    private readonly now;
+    private timer;
+    private graceEmittedFor;
+    constructor(opts: AddonHealthMonitorOptions);
+    /** True while we're still inside the post-boot grace window. */
+    inGracePeriod(): boolean;
+    /**
+     * Record a successful load/init/recovery for a package. Clears any
+     * existing failure state and emits `AddonLoadRecovered` if the
+     * package was previously in `failed` state with an alert emitted.
+     */
+    recordSuccess(packageName: string, addonId?: string): void;
+    /**
+     * Record a load/init/crash failure. Schedules the next retry per
+     * `retryIntervalsMs` and (post-grace) emits `AddonLoadFailed` if
+     * this is the first alert for the current streak.
+     */
+    recordFailure(packageName: string, err: unknown, addonId?: string): void;
+    /**
+     * Force an immediate retry attempt for a package, resetting the
+     * counter back to 0 (next failure goes to the 60s interval again).
+     * Used by the user-facing `addons.retryLoad` tRPC procedure and by
+     * the explicit reinstall path.
+     */
+    retryNow(packageName: string): Promise<void>;
+    /** Snapshot of all tracked packages (read-only, for tRPC list / UI). */
+    getHealthSnapshot(): readonly AddonHealthSnapshot[];
+    /** Get health for a single package (or null if unknown). */
+    getHealth(packageName: string): AddonHealthSnapshot | null;
+    /**
+     * Drop tracking for a package (used on uninstall — we don't want
+     * the monitor to keep retrying a package the user explicitly removed).
+     */
+    forget(packageName: string): void;
+    /** Begin the retry tick loop. Idempotent. */
+    start(): void;
+    /** Stop the retry loop (cleanup on shutdown). */
+    stop(): void;
+    /**
+     * Public for tests. Production callers go through `start()`.
+     *
+     * Each tick:
+     *   1. If grace JUST ended on this tick, emit `AddonLoadFailed` for
+     *      every package still in `failed` state that hasn't alerted yet.
+     *   2. For every `failed` package whose `nextRetryAt` <= now, run
+     *      `retryFn`. On success, recordSuccess; on failure, recordFailure
+     *      (which recomputes the next interval).
+     */
+    tick(): Promise<void>;
+    private attemptRetry;
+    private emit;
+}

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

@@ -0,0 +1,208 @@
+import { InstalledPackage, IScopedLogger } from '@camstack/types';
+import { AddonManifest } from './addon-manifest.js';
+/**
+ * Addon install source mode:
+ * - 'npm'     — download from npm registry (production + dev default).
+ * - 'local'   — copy dist/ from local workspace `packages/` (used by
+ *               `installFromWorkspace` + the Electron-packaged bundled
+ *               addons path).
+ * - 'symlink' — point `data/addons/<pkg>` directly at the workspace
+ *               source dir. Dev-only: workspace edits → next addon
+ *               load picks them up after a `npm run build` of the
+ *               package, without re-copying. Costs ~80ms per addon at
+ *               cold boot instead of the ~200ms-per-package copy.
+ *               Windows fallback: drops back to `'local'` if symlink
+ *               creation fails (needs admin / developer-mode on Win10).
+ *
+ * The previous symlink mode (auto-on when workspace was detected) was
+ * removed in `eb96df3c` once addons moved to self-contained bundles —
+ * the legacy `symlinkAddonsToNodeModules` / `symlinkPeerDepsIntoAddonsDir`
+ * helpers it relied on are GONE. This is the narrower successor: no
+ * symlinks into the hub's `node_modules`, no peer-dep planting — just
+ * `addonsDir/<pkg>` → `packages/<pkg>`.
+ */
+export type InstallSource = 'npm' | 'local' | 'symlink';
+export interface AddonInstallerConfig {
+    /** Directory where addons are stored (e.g., {dataDir}/addons) */
+    readonly addonsDir: string;
+    /** npm registry URL */
+    readonly registry?: string;
+    /** Workspace packages directory (e.g., /path/to/camstack-server/packages) */
+    readonly workspacePackagesDir?: string;
+    /** Install source mode. Default: auto-detect */
+    readonly installSource?: InstallSource;
+}
+export type { InstalledPackage };
+export declare class AddonInstaller {
+    readonly addonsDir: string;
+    private readonly registry;
+    readonly workspaceDir: string | undefined;
+    readonly installSource: InstallSource;
+    private readonly logger;
+    /**
+     * Central manifest of installed addons. Tracks version + source +
+     * timestamps + last-backup pointer per package, written atomically
+     * after every install/uninstall. Replaces the legacy per-addon
+     * `.install-source` markers (which we still write for backward
+     * compatibility with code that reads them directly — see fs-utils
+     * `getAddonInstallSource`).
+     */
+    readonly manifest: AddonManifest;
+    constructor(config: AddonInstallerConfig, logger?: IScopedLogger);
+    /**
+     * Derive the bootstrap addon list from a meta-package's runtime dependencies.
+     * Single source of truth: the meta-package's `package.json` declares which
+     * `@camstack/addon-*` packages the deployment needs. Replaces previously
+     * hardcoded lists — see design spec
+     * docs/superpowers/specs/2026-05-20-docker-install-from-npm-design.md.
+     */
+    private static deriveBootstrapList;
+    /**
+     * Bootstrap packages installed on first boot — derived from the
+     * `@camstack/server` meta-package's runtime dependencies. Adding a
+     * bootstrap addon = adding it to `server/backend/package.json`.
+     * See design spec
+     * docs/superpowers/specs/2026-05-20-docker-install-from-npm-design.md.
+     *
+     * Camera provider drivers are NOT preinstalled with the hub — users
+     * pick providers from the admin UI ("Install addon"). Saves ~80MB per
+     * hub install and avoids shipping driver code unused on most hubs.
+     */
+    static readonly REQUIRED_PACKAGES: readonly string[];
+    /**
+     * Agent-only bootstrap packages — derived from the `@camstack/agent`
+     * meta-package's runtime dependencies. Adding an agent bootstrap addon
+     * = adding it to `packages/agent/package.json`.
+     */
+    static readonly AGENT_PACKAGES: readonly string[];
+    /**
+     * Ensure all required packages are installed in the addons directory.
+     *
+     * Bootstrap-only — prefers the workspace/bundle copy when available
+     * (offline-first, faster, container-self-contained). On-demand
+     * installs from the admin UI go through `install()` instead, which
+     * defaults to npm in production.
+     *
+     * @param packages — optional custom package list (default: REQUIRED_PACKAGES)
+     */
+    ensureRequiredPackages(packages?: readonly string[]): Promise<void>;
+    /**
+     * Install a single addon — on-demand installer used by AddonPackageService
+     * (admin UI "Install addon" / "Reinstall" buttons).
+     *
+     * Always npm. The legacy "auto-use workspace symlink in dev" branch
+     * was removed; local development pushes via `camstack deploy` (CLI
+     * tarball upload). Operators wanting to install from workspace use
+     * `installFromWorkspace` (explicit `'local'` codepath) instead.
+     */
+    install(packageName: string, version?: string): Promise<{
+        name: string;
+        version: string;
+    }>;
+    /**
+     * Install addon from a local workspace package. Two strategies
+     * depending on `installSource`:
+     *   - `'symlink'` (dev): create a directory symlink
+     *     `addonsDir/<pkg>` → `<workspace>/packages/<pkg>`. Edits to
+     *     the workspace are visible at the next addon load after a
+     *     `npm run build` of that package — no copy step. Falls back
+     *     to `'local'` if symlink creation fails (Windows w/o
+     *     developer-mode).
+     *   - `'local'` (default): copy `package.json` (stripped) + `dist/`
+     *     into `addonsDir/<pkg>/`. The Electron bundled-addons path
+     *     uses this so the runtime owns its on-disk copy.
+     */
+    private installLocal;
+    /**
+     * Symlink `addonsDir/<pkg>` at the workspace source dir. Dev-only.
+     * After this, the AddonLoader resolves `<addonsDir>/<pkg>/dist/...`
+     * through the symlink straight to `packages/<pkg>/dist/...` — a fresh
+     * `npm run build` of the package is immediately picked up by the
+     * next addon load.
+     *
+     * Auto-runs `ensureBuilt` so a workspace freshly cloned (with no
+     * dist/ yet) still boots — same auto-build hook installCopy uses.
+     *
+     * Does NOT plant peer-dep symlinks into `<targetDir>/node_modules/`
+     * the way the pre-`eb96df3c` symlink mode did. Self-contained
+     * addons bundle their own copy of types/zod/sdk — no shared
+     * workspace symlinks needed.
+     */
+    private installSymlink;
+    private installCopy;
+    /**
+     * Install addon from npm (download tgz, then extract). Tries the
+     * registry HTTPS API first (works inside packaged Electron — no need
+     * for `npm` on PATH); falls back to `npm pack` for parity with the
+     * legacy path when the registry call fails (private registries with
+     * unusual auth, offline mode, etc).
+     */
+    installFromNpm(packageName: string, version?: string): Promise<{
+        name: string;
+        version: string;
+    }>;
+    /**
+     * Resolve `{packageName, version?}` against the configured registry
+     * over HTTPS and download the tarball into `tmpDir`. Returns the path
+     * to the downloaded `.tgz`.
+     *
+     * Versioning rules (mirrors `npm pack` semantics):
+     *   - `version === undefined` → uses `dist-tags.latest`
+     *   - exact semver string → looked up in `versions[version]`
+     *   - dist-tag name (e.g. `next`, `beta`) → resolved via `dist-tags`
+     *
+     * Range specs (`^1.0.0`, `~1.2`, `>=2`) are NOT supported here — the
+     * caller should resolve those upstream. `npm pack` handles them, so
+     * the legacy fallback path remains the right answer for those.
+     */
+    private downloadNpmTarball;
+    /** Install addon from a tgz file (uploaded or downloaded) */
+    installFromTgz(tgzPath: string): Promise<{
+        name: string;
+        version: string;
+    }>;
+    /**
+     * Apply an update to an installed addon, backing up the current
+     * version first so the caller can roll back atomically on failure.
+     *
+     * Steps:
+     *   1. Rename current install dir → {addonsDir}/.backups/{name}/{ts}/
+     *   2. Run a fresh install (npm or local depending on installSource)
+     *   3. Record `lastBackupDir` in the manifest entry
+     *
+     * The post-install caller (kernel.restartAddon + health-check) is
+     * responsible for verifying the new version actually works and for
+     * triggering `rollbackAddon()` if the health check fails.
+     *
+     * Throws if there is no installed version to update — caller should
+     * prefer plain `install()` for first-time installs.
+     */
+    applyUpdate(packageName: string, version?: string): Promise<{
+        name: string;
+        version: string;
+        backupDir: string;
+    }>;
+    /**
+     * Roll back an addon to its most recent backup. Used after an update
+     * passes installation but fails its post-restart health check.
+     *
+     * Returns the version that was restored, or `null` if there was no
+     * backup to roll back to.
+     */
+    rollbackAddon(packageName: string): Promise<string | null>;
+    /**
+     * Drop the recorded backup for an addon (e.g. after a successful
+     * post-update health check confirms the new version is healthy).
+     * Frees disk space without affecting the running install.
+     */
+    clearBackup(packageName: string): void;
+    uninstall(packageName: string): Promise<void>;
+    listInstalled(): InstalledPackage[];
+    isInstalled(packageName: string): boolean;
+    getInstalledPackage(packageName: string): InstalledPackage | null;
+    private findLocalPackage;
+    /** Ensure a package is built (dist/ exists and page bundles present) */
+    private ensureBuilt;
+    /** Check if page bundles declared in package.json are missing from dist/ */
+    private isDistIncomplete;
+}

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

@@ -0,0 +1,106 @@
+import { AddonDeclaration, ICamstackAddon, IScopedLogger, StorageLocationDeclaration } from '@camstack/types';
+export interface RegisteredAddon {
+    readonly declaration: AddonDeclaration;
+    readonly packageName: string;
+    readonly packageVersion: string;
+    /** Human-readable package name from camstack.displayName in package.json */
+    readonly packageDisplayName?: string;
+    /**
+     * Optional bundle metadata when the npm package ships multiple addon
+     * entries. Mirrors `AddonPackageManifest.bundle`. Drives the
+     * collapsible bundle card in the Addons admin UI.
+     */
+    readonly bundle?: {
+        displayName: string;
+        description?: string;
+        icon?: string;
+    };
+    readonly addonClass: new () => ICamstackAddon;
+    /**
+     * Full raw module namespace. Consumers can read additional named exports
+     * (e.g. `customActions`) without instantiating the addon — lets the hub
+     * register a forkable addon's custom-action catalog with real zod
+     * schemas before the child process is up.
+     */
+    readonly module: Readonly<Record<string, unknown>>;
+}
+/**
+ * Per-package failure record. Surfaced via `listLoadFailures()` so the
+ * AddonRegistry can hand the failures to the kernel's
+ * `AddonHealthMonitor` after `loadFromDirectory()` completes — the
+ * health monitor then schedules the retry loop and emits operator-
+ * visible alerts post-grace.
+ *
+ * Two failure shapes are tracked:
+ *   - **package-level**: package.json couldn't be read/parsed, or the
+ *     manifest was malformed. `addonId` undefined.
+ *   - **declaration-level**: per-addon load failure inside
+ *     `loadDeclaration` (entry import threw, addon class resolution
+ *     failed, etc). `addonId` set to `declaration.id`.
+ */
+export interface AddonLoadFailure {
+    readonly packageName: string;
+    readonly addonDir: string;
+    readonly addonId?: string;
+    readonly error: Error;
+    readonly timestamp: number;
+}
+/**
+ * Pure extraction of per-addon storage-location declarations from a set of
+ * registered addons. Each registered addon carries its manifest declaration
+ * (`RegisteredAddon.declaration`), whose optional `storageLocations` array is
+ * the `camstack.addons[].storageLocations` entry authored in package.json.
+ *
+ * Returns ONE inner array per addon that declared at least one location;
+ * addons declaring nothing are omitted entirely (no empty arrays). The result
+ * is the `perAddon` input shape consumed by
+ * {@link buildStorageLocationRegistry}.
+ */
+export declare function extractStorageLocationDeclarations(addons: Iterable<RegisteredAddon>): StorageLocationDeclaration[][];
+export declare class AddonLoader {
+    private addons;
+    private readonly loadFailures;
+    private readonly logger;
+    constructor(logger?: IScopedLogger);
+    /**
+     * Failures encountered during the most recent `loadFromDirectory` /
+     * `loadFromAddonDir` pass. Cleared (per-package) on a successful
+     * subsequent reload so retries don't see stale entries. Cumulative
+     * across multiple loads otherwise.
+     */
+    listLoadFailures(): readonly AddonLoadFailure[];
+    /** Forget any tracked failures for a given package — uninstall path. */
+    clearLoadFailures(packageName: string): void;
+    /** Scan addons directory and load all addon packages.
+     *  Supports scoped layout: addons/@scope/package-name/ */
+    loadFromDirectory(addonsDir: string): Promise<void>;
+    private tryLoadAddon;
+    /** Load addon from a specific directory (package.json + dist/) */
+    loadFromAddonDir(addonDir: string): Promise<void>;
+    private loadDeclaration;
+    /** Load addon from a direct path (for development/testing) */
+    loadFromPath(addonId: string, modulePath: string, packageName: string, declaration?: Partial<AddonDeclaration>, packageVersion?: string): Promise<void>;
+    /** Get a registered addon by ID */
+    getAddon(addonId: string): RegisteredAddon | undefined;
+    /** List all registered addons */
+    listAddons(): RegisteredAddon[];
+    /**
+     * Per-addon storage-location declarations across every registered addon.
+     *
+     * Each registered addon's `declaration.storageLocations` (the
+     * `camstack.addons[].storageLocations` array from package.json) is surfaced
+     * as one inner array; addons declaring nothing are omitted. The result is
+     * fed directly to `buildStorageLocationRegistry(perAddon)` so the
+     * storage-orchestrator can aggregate declarations and seed `<id>:default`
+     * instances.
+     */
+    listStorageLocationDeclarations(): StorageLocationDeclaration[][];
+    /** Check if an addon is registered */
+    hasAddon(addonId: string): boolean;
+    /**
+     * Create a new instance of an addon (not yet initialized).
+     * Injects the manifest from package.json (AddonDeclaration) so the
+     * addon class doesn't need to declare it.
+     */
+    createInstance(addonId: string): ICamstackAddon;
+}

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

@@ -0,0 +1,77 @@
+export type AddonInstallSource = 'npm' | 'local' | 'upload' | 'bundled' | 'seed';
+export interface AddonManifestEntry {
+    /** Full pkg name, e.g. `@camstack/addon-pipeline`. */
+    name: string;
+    /** Semver currently installed. */
+    version: string;
+    /** Where this version came from. */
+    source: AddonInstallSource;
+    /** ISO 8601 of first install. */
+    installedAt: string;
+    /** ISO 8601 of last update (== installedAt for first install). */
+    updatedAt: string;
+    /**
+     * Path (absolute) of the most recent pre-update backup, if any.
+     * Used by `applyUpdate` rollback when an upgrade fails its post-restart
+     * health check. Cleared once the new version is confirmed healthy.
+     */
+    lastBackupDir?: string;
+    /**
+     * Free-form, addon-specific metadata. Currently unused but reserved so
+     * future fields (e.g. integrity hash, peer-dep checks) don't require a
+     * manifest schema bump.
+     */
+    meta?: Record<string, unknown>;
+}
+export interface AddonManifestFile {
+    /**
+     * Schema version. Increment whenever the on-disk shape changes
+     * incompatibly so older readers can refuse to load.
+     */
+    version: 1;
+    /** Per-package state, keyed by full pkg name. */
+    addons: Record<string, AddonManifestEntry>;
+    /** ISO 8601 of last manifest write. */
+    updatedAt: string;
+}
+export declare class AddonManifest {
+    private readonly manifestPath;
+    private cache;
+    constructor(addonsDir: string);
+    /**
+     * Read the manifest from disk. Returns an empty manifest if the file is
+     * missing or corrupted (logs a warning to stderr in the corrupted case).
+     * Cached per instance — call `invalidate()` to force a re-read.
+     */
+    read(): AddonManifestFile;
+    /**
+     * Atomic write — writes to a tmpfile in the same directory, then renames.
+     * Rename is atomic on the same filesystem, so readers can never observe
+     * a half-written file.
+     */
+    write(manifest: AddonManifestFile): void;
+    /** Lookup a single addon's manifest entry, or `null` if not tracked. */
+    get(name: string): AddonManifestEntry | null;
+    /** List every tracked entry. */
+    list(): AddonManifestEntry[];
+    /**
+     * Insert or replace an addon entry. `installedAt` is preserved if the
+     * entry already exists; only `updatedAt` advances on subsequent writes.
+     */
+    upsert(name: string, fields: Omit<AddonManifestEntry, 'name' | 'installedAt' | 'updatedAt'>): void;
+    /** Remove an addon from tracking (e.g. uninstall). */
+    remove(name: string): void;
+    /**
+     * Drop the in-memory cache so the next `read()` re-loads from disk.
+     * Useful when an external process may have written the manifest.
+     */
+    invalidate(): void;
+    /**
+     * Migration helper: if the manifest is empty but the addons directory
+     * has packages with `.install-source` markers (the legacy per-addon
+     * tracking), seed the manifest from those markers. Runs once at boot.
+     * Returns the number of entries migrated.
+     */
+    migrateFromInstallSourceMarkers(addonsDir: string): number;
+    private empty;
+}

package/dist/kernel/capability-handle.d.ts

@@ -0,0 +1,46 @@
+import { ReadinessRegistry, ReadinessScope, ICapabilityHandle } from '@camstack/types';
+export declare class CapabilityUnavailableError extends Error {
+    readonly capName: string;
+    readonly scope: ReadinessScope;
+    readonly timeoutMs: number;
+    constructor(capName: string, scope: ReadinessScope, timeoutMs: number);
+}
+/**
+ * A stable reference to a capability that tracks its readiness state and
+ * gates calls on that state.
+ *
+ * Obtained via `ctx.useCapability()` (non-blocking) or `ctx.acquireCapability()`
+ * (blocks until the cap is ready). The handle is cached per `(capName, scope)` in
+ * AddonContextImpl so repeated calls return the same instance.
+ *
+ * The generic `T` is a phantom type documenting the expected provider interface;
+ * the handle itself does not expose a typed proxy surface in v1.
+ */
+export declare class CapabilityHandle<T = unknown> implements ICapabilityHandle<T> {
+    readonly capName: string;
+    readonly scope: ReadinessScope;
+    private readonly registry;
+    readonly defaultTimeoutMs: number;
+    private state;
+    private readonly unsubscribeReadiness;
+    constructor(capName: string, scope: ReadinessScope, registry: ReadinessRegistry, defaultTimeoutMs: number);
+    get isReady(): boolean;
+    /**
+     * Block until the capability is ready, or throw `CapabilityUnavailableError`
+     * if it does not become ready within `timeoutMs`.
+     */
+    awaitReady(timeoutMs?: number): Promise<void>;
+    /**
+     * Execute `fn` with readiness gating: if the cap is not ready, blocks
+     * until it becomes ready (or throws CapabilityUnavailableError on timeout),
+     * then calls `fn`.
+     *
+     * Preferred over calling awaitReady() + fn() separately because it
+     * re-gates after a down→ready transition that happens between the
+     * await and the call.
+     */
+    call<R>(fn: () => Promise<R>, timeoutMs?: number): Promise<R>;
+    /** Unsubscribe from ReadinessRegistry. Called by AddonContextImpl on shutdown. */
+    dispose(): void;
+    readonly _provider: T;
+}