@camstack/system 1.2.390 → 1.2.392

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

@@ -1,631 +1,631 @@
-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';
+* 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";
 /** The one bootstrap package the server closure carries itself. */
 export declare const CLOSURE_PROVIDED_PACKAGE = "@camstack/system";
 /**
- * Should the bootstrap SKIP seeding `packageName` into /data/addons?
- *
- * True only for the package the closure provides, and only when it actually
- * resolves. Both halves are load-bearing:
- *
- *  - seeding a copy the closure already provides creates one that WINS over
- *    the closure and is never refreshed (bootstrap is seed-only, and
- *    `camstack deploy` of a framework package is rejected on an image hub), so
- *    the node runs first-boot builtins forever while reporting the new
- *    version;
- *  - skipping it when it does NOT resolve is how a fresh deployment was once
- *    made unbootable ("No addon provides required infrastructure capability
- *    storage-provider"). That is why the guard is resolvability rather than a
- *    blanket removal from the bootstrap list.
- */
+* Should the bootstrap SKIP seeding `packageName` into /data/addons?
+*
+* True only for the package the closure provides, and only when it actually
+* resolves. Both halves are load-bearing:
+*
+*  - seeding a copy the closure already provides creates one that WINS over
+*    the closure and is never refreshed (bootstrap is seed-only, and
+*    `camstack deploy` of a framework package is rejected on an image hub), so
+*    the node runs first-boot builtins forever while reporting the new
+*    version;
+*  - skipping it when it does NOT resolve is how a fresh deployment was once
+*    made unbootable ("No addon provides required infrastructure capability
+*    storage-provider"). That is why the guard is resolvability rather than a
+*    blanket removal from the bootstrap list.
+*/
 export declare function shouldSkipClosureProvidedSeed(packageName: string, isResolvable: boolean): boolean;
 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;
-    /**
-     * Override for "does the running closure already provide this package?".
-     * Production leaves it unset (real `require.resolve`); a spec sets it to
-     * reach the branch that still seeds `@camstack/system`, which is otherwise
-     * unreachable in a process where that package always resolves.
-     */
-    readonly isPackageResolvable?: (packageName: string) => boolean;
-    /**
-     * The server closure's node_modules to dedupe addon trees against.
-     * Production leaves it unset (derived from `CAMSTACK_FRAMEWORK_DIR`);
-     * specs point it at a fabricated closure dir.
-     */
-    readonly closureNodeModulesDir?: string;
+	/** 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;
+	/**
+	* Override for "does the running closure already provide this package?".
+	* Production leaves it unset (real `require.resolve`); a spec sets it to
+	* reach the branch that still seeds `@camstack/system`, which is otherwise
+	* unreachable in a process where that package always resolves.
+	*/
+	readonly isPackageResolvable?: (packageName: string) => boolean;
+	/**
+	* The server closure's node_modules to dedupe addon trees against.
+	* Production leaves it unset (derived from `CAMSTACK_FRAMEWORK_DIR`);
+	* specs point it at a fabricated closure dir.
+	*/
+	readonly closureNodeModulesDir?: string;
 }
+import type { InstalledPackage, IScopedLogger } from "@camstack/types";
+import { AddonManifest } from "./addon-manifest.js";
 export type { InstalledPackage };
 /** Outcome of {@link AddonInstaller.ensureAddonRuntimeDeps}. */
 export interface EnsureAddonDepsResult {
-    /** Installed addon packages examined. */
-    readonly checked: number;
-    /** `"<package>:<dep>"` entries satisfied by a new closure link — no npm. */
-    readonly linked: readonly string[];
-    /** Packages whose deps required an in-place npm install. */
-    readonly reinstalled: readonly string[];
-    /** Packages whose deps could not be ensured (logged loudly, boot continues). */
-    readonly failed: readonly string[];
+	/** Installed addon packages examined. */
+	readonly checked: number;
+	/** `"<package>:<dep>"` entries satisfied by a new closure link — no npm. */
+	readonly linked: readonly string[];
+	/** Packages whose deps required an in-place npm install. */
+	readonly reinstalled: readonly string[];
+	/** Packages whose deps could not be ensured (logged loudly, boot continues). */
+	readonly failed: readonly string[];
 }
 /** Outcome of {@link AddonInstaller.sweepBackups}. Absolute paths. */
 export interface BackupSweepResult {
-    /** Backup dirs reclaimed by the sweep. */
-    readonly removed: readonly string[];
-    /** Backup dirs deliberately retained (rollback target / last copy). */
-    readonly kept: readonly string[];
+	/** Backup dirs reclaimed by the sweep. */
+	readonly removed: readonly string[];
+	/** Backup dirs deliberately retained (rollback target / last copy). */
+	readonly kept: readonly string[];
 }
 /**
- * A staging tree younger than this may belong to an install still running —
- * possibly in another process. Only older trees are residue worth sweeping.
- * Generous on purpose: an addon's runtime-dependency `npm install` on a slow
- * host is minutes, and the cost of leaving residue one deploy longer is disk,
- * while the cost of sweeping a live one is a FAILED deploy.
- */
+* A staging tree younger than this may belong to an install still running —
+* possibly in another process. Only older trees are residue worth sweeping.
+* Generous on purpose: an addon's runtime-dependency `npm install` on a slow
+* host is minutes, and the cost of leaving residue one deploy longer is disk,
+* while the cost of sweeping a live one is a FAILED deploy.
+*/
 export declare const STAGING_RESIDUE_MIN_AGE_MS: number;
 export interface StagingEntryAge {
-    readonly name: string;
-    /** Age of the entry's mtime, in ms. */
-    readonly ageMs: number;
+	readonly name: string;
+	/** Age of the entry's mtime, in ms. */
+	readonly ageMs: number;
 }
 /**
- * Pick the staging entries that are safe to delete.
- *
- * `installFromTgz` used to clear the WHOLE `.staging` root before creating its
- * own dir. Two deploys arriving within one install's lifetime — the normal case
- * when the hub propagates two packages back to back — meant the second one
- * deleted the first one's tree out from under its running `npm install`:
- *
- *   npm error code ENOENT
- *   npm error path …/.staging/install-14820-2026-08-07T12-28-28-875Z/package/package.json
- *
- * which the propagation then reported as `runtime dependency install failed`.
- * Observed on the Mac desktop agent and on little-unraid on 2026-08-07.
- *
- * So a sweep only removes what cannot be live: not a tree this process is
- * building, and not one young enough to belong to anybody's in-flight install.
- */
+* Pick the staging entries that are safe to delete.
+*
+* `installFromTgz` used to clear the WHOLE `.staging` root before creating its
+* own dir. Two deploys arriving within one install's lifetime — the normal case
+* when the hub propagates two packages back to back — meant the second one
+* deleted the first one's tree out from under its running `npm install`:
+*
+*   npm error code ENOENT
+*   npm error path …/.staging/install-14820-2026-08-07T12-28-28-875Z/package/package.json
+*
+* which the propagation then reported as `runtime dependency install failed`.
+* Observed on the Mac desktop agent and on little-unraid on 2026-08-07.
+*
+* So a sweep only removes what cannot be live: not a tree this process is
+* building, and not one young enough to belong to anybody's in-flight install.
+*/
 export declare function selectSweepableStaging(entries: readonly StagingEntryAge[], inFlight: ReadonlySet<string>, minAgeMs?: number): readonly string[];
 export declare class AddonInstaller {
-    readonly addonsDir: string;
-    private readonly registry;
-    readonly workspaceDir: string | undefined;
-    readonly installSource: InstallSource;
-    private readonly logger;
-    private readonly isPackageResolvable?;
-    /** Test seam — production resolves via `CAMSTACK_FRAMEWORK_DIR`. */
-    private readonly closureNodeModulesDir;
-    /**
-     * 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;
-    /**
-     * Basenames under `.staging` this process is currently building. Never swept
-     * — see {@link selectSweepableStaging}.
-     */
-    private readonly inFlightStaging;
-    constructor(config: AddonInstallerConfig, logger?: IScopedLogger);
-    /**
-     * Where a bootstrapped npm lives when the host has none on PATH (packaged
-     * Electron agents ship a bare node binary). Persistent — sibling of the
-     * installed addons, survives restarts, downloaded at most once per host.
-     */
-    private get npmCacheDir();
-    /** Shared options for every npm invocation this installer performs. */
-    private npmRunOptions;
-    /**
-     * 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.
-     */
-    /**
-     * Is `packageName` reachable through normal resolution — i.e. does the
-     * running closure already provide it?
-     *
-     * Overridable via `AddonInstallerConfig.isPackageResolvable` so a spec can
-     * exercise BOTH sides. That matters more than it looks: the branch that
-     * still seeds is the one protecting a fresh deployment from an unbootable
-     * node, and it is unreachable in a test process where `@camstack/system`
-     * always resolves.
-     */
-    private isResolvableFromClosure;
-    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/server`
-     * meta-package's `camstack.agentBootstrapAddons` manifest field (single
-     * source of truth; the separate agent meta-package is gone).
-     * The agent runtime boots from the SAME `@camstack/server` closure, so its
-     * bootstrap addon set is declared alongside the hub's. Adding an agent
-     * bootstrap addon = adding it to `server/backend/package.json`'s
-     * `camstack.agentBootstrapAddons`.
-     */
-    static readonly AGENT_PACKAGES: readonly string[];
-    /**
-     * Derive the agent bootstrap addon list from a meta-package's
-     * `camstack.agentBootstrapAddons` manifest field, prepending
-     * `@camstack/system` (the required infrastructure builtins carrier — same
-     * rationale as `deriveBootstrapList`). Mirrors `deriveBootstrapList`'s
-     * `require.resolve` nuance: the meta-package may be absent in a deployment
-     * (this field is eagerly evaluated at class-load), so a failed resolve
-     * yields an empty list rather than throwing.
-     */
-    private static deriveAgentBootstrapList;
-    /**
-     * 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.
-     *
-     * There is no version argument and there is deliberately no pin: the system is
-     * addons-agnostic and `latest` is the whole contract at first boot (operator,
-     * 2026-08-13). A copy already under the addon root is never replaced either —
-     * bootstrap is seed-only, and overwriting a deployed bundle would be an
-     * un-deploy ([D90](../../../../docs/decisions/adr-0090.md)).
-     *
-     * @param packages — optional custom package list (default: REQUIRED_PACKAGES)
-     */
-    ensureRequiredPackages(packages?: readonly string[]): Promise<void>;
-    /**
-     * Reconcile the install manifest against the addons actually present on
-     * disk: register seeded addons, correct a version that disagrees with the
-     * installed `package.json`, and drop entries naming a directory that does
-     * not exist. Call once after `ensureRequiredPackages`, before any update
-     * can be in flight. See `AddonManifest.reconcileFromDisk` for the rules.
-     *
-     * Every correction is logged by name — a manifest that silently disagreed
-     * with disk is what made "@camstack/system 1.2.29" read as installed on a
-     * hub that deliberately has no copy of it.
-     *
-     * Returns the number of changes.
-     */
-    reconcileManifest(): number;
-    /**
-     * Make every INSTALLED addon's runtime dependencies resolvable — doing the
-     * least work that achieves it. Runs at boot on hub and agent, which is what
-     * turns a restore back into a working node: a system backup archives no
-     * node_modules (D338), so before this pass every restored non-bootstrap
-     * addon failed its first import until someone redeployed it by hand.
-     *
-     * Per addon, in order:
-     *  1. drop closure links that no longer hold (dangling, or the closure
-     *     moved to a version the addon tree's recorded ranges refuse) — those
-     *     addons get a reinstall;
-     *  2. a declared dep that already resolves in the addon tree costs nothing;
-     *  3. a missing declared dep the closure provides at a COMPATIBLE version
-     *     becomes a link — no npm, no network;
-     *  4. only an addon left with a genuinely unresolvable dep gets an npm
-     *     install (then dedupe + native ensure, same tail as a fresh install).
-     *
-     * "Only when necessary" is the contract: an addon whose deps are all
-     * satisfied is not touched at all. Failures are per-addon and non-fatal —
-     * a dep that cannot be re-fetched leaves that addon exactly as broken as
-     * it already was, but LOUDLY, and never blocks the rest of the boot.
-     */
-    ensureAddonRuntimeDeps(): Promise<EnsureAddonDepsResult>;
-    /**
-     * One addon's dependency audit (steps 1–3 of `ensureAddonRuntimeDeps`).
-     * Pure decision + link creation; the npm fallback is the caller's.
-     */
-    private ensureOneAddonDeps;
-    /**
-     * npm-install an installed addon's runtime deps IN PLACE (the restore /
-     * repair path — the tree is not yet running at boot), then the same tail
-     * every fresh install gets: closure dedupe + native deps + prebuild ensure.
-     * Closure links are stripped first so npm reifies against plain missing
-     * dirs instead of symlinks it does not own.
-     */
-    private reinstallAddonDeps;
-    /**
-     * 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.
-     */
-    /**
-     * Re-install one addon from the running server closure.
-     *
-     * The closure carries a copy of every addon it declares as a dependency, and
-     * NOTHING loads an addon from there — `AddonLoader` reads the addon root and
-     * only the addon root, on every role. So those copies are transport, and
-     * this is the only thing that moves them into the place that runs code.
-     *
-     * Without it a server update advances the closure and changes nothing: six
-     * addons on the hub were behind by up to nineteen versions on 2026-09-17,
-     * each frozen at whenever somebody last ran `camstack deploy`.
-     *
-     * WHICH addons deserve this is not decided here — see `planAddonRealignment`,
-     * which needs two gates because a version comparison alone would overwrite a
-     * deliberate deploy. This only carries out a decision already made.
-     */
-    realignFromClosure(packageName: string, closureDir: string): Promise<{
-        name: string;
-        version: string;
-    }>;
-    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;
-    /**
-     * Evict an existing install dir by atomic rename-aside, then best-effort
-     * delete the aside copy.
-     *
-     * Why not a plain `fs.promises.rm(targetDir, {recursive})`: during a
-     * `camstack deploy` the addon's live runner still holds its native
-     * prebuilds (`.node`/`.so`) open. On the hub's shfs/FUSE `/data/addons`,
-     * a recursive rm of a held subdir fails `ENOTEMPTY` mid-walk and leaves
-     * the dir gutted. A rename only touches the dirent (metadata), so it
-     * succeeds with the inodes still open — the old runner keeps its fds on
-     * the moved inodes until it restarts.
-     *
-     * The aside copy is removed best-effort: the held native libs are only
-     * released once the post-install `restartAddon` recycles the runner, so a
-     * failure to delete it now must NOT fail the install. Any residue is swept
-     * on the next deploy.
-     */
-    private evictInstallDir;
-    /**
-     * Best-effort removal of `.staging` residue left by a CRASHED earlier deploy.
-     *
-     * Deliberately not `sweepGraveyard`: an evicted `.evicting/*` dir is dead by
-     * construction, but a `.staging/*` dir may be an install still running — in
-     * this process or another one. Deleting one of those fails a live deploy with
-     * an ENOENT on its own package.json, which is what happened on 2026-08-07.
-     */
-    private sweepStagingResidue;
-    /** Best-effort removal of leftover `.evicting/*` dirs from earlier deploys. */
-    private sweepGraveyard;
-    /**
-     * Make `pkgDir` (an addon tree that has NOT been swapped in yet) runnable:
-     * strip the host-provided deps from its manifest, then `npm install` whatever
-     * survives.
-     *
-     * ONE implementation for every path that materialises an addon tree —
-     * `installFromTgz` (deploy/upload) and `applyUpdateFromStaged` (OTA). The OTA
-     * path did not have it, and that is a whole outage class: an addon declaring
-     * `camstack.runtimeDependencies` was broken by its FIRST OTA update, its dist
-     * landing without `node_modules`. Every load then threw `Cannot find module`
-     * and the retry loop replayed it — `@camstack/addon-export-hap`, 126 failed
-     * load retries over 10.5h on 2026-08-12; `@camstack/addon-remote-storage`
-     * (`@aws-sdk/*`, `webdav`) is the same landmine.
-     *
-     * **Strip.** `@camstack/*` are host-provided system packages that resolve via
-     * the host's node_modules (Node walks up from the installed addon dir). Left
-     * in, this `npm install` pulls the LAST PUBLISHED `@camstack/types` (etc.)
-     * into the addon's OWN node_modules where it SHADOWS the host's fresh copy —
-     * local additions to a system package silently never reach the deployed
-     * addon. Addon dists are self-contained besides, so `stripBundledDeps` keeps
-     * only what the manifest explicitly declares in
-     * `camstack.runtimeDependencies` (see fs-utils / ADR-0027). Nothing left to
-     * install is the COMMON case: skip npm rather than pay an empty round-trip.
-     *
-     * **Failure is FATAL.** This used to warn-and-continue on the tgz path ("the
-     * addon may still load if imports are lazy") — live cost: a host with no npm
-     * (packaged Electron Mac agent) installed every runtime-dep addon WITHOUT its
-     * node_modules for DAYS; each reported "running" while its entry failed at
-     * import (`Cannot find module 'sharp'`), the detection group ran 1/3 members,
-     * and the node silently dropped out of the balancer. Throwing here is what
-     * keeps the PREVIOUS install intact: every caller builds the tree before it
-     * swaps, so an abort simply means the swap never happens.
-     *
-     * A missing/unreadable manifest is NOT fatal — it is logged and skipped. The
-     * callers validate the tree themselves, and a tree with no readable
-     * package.json has no declared deps to install (the loader will skip the
-     * package entirely).
-     */
-    private installRuntimeDependencies;
-    /**
-     * Make `pkgDir`'s NATIVE modules loadable on THIS host, before it is swapped
-     * in: install whatever `camstack.nativeDependencies` declares, then ensure
-     * every traditional native present in the tree actually carries a compiled
-     * `.node` for the running ABI.
-     *
-     * ONE implementation, for the same reason as {@link installRuntimeDependencies}
-     * — every path that materialises an addon tree calls it, so no call site can
-     * forget it. `installFromTgz` (deploy/upload) always ran these two steps; the
-     * OTA staged-swap path ran NEITHER even after the runtime-dep fix (2026-08-12,
-     * task #15, which named this gap explicitly). Same outage class one layer
-     * down: an addon with native modules was broken by its FIRST OTA update, its
-     * dist landing without an ABI-matched binary, and every load dying at the
-     * binding (`Could not locate the bindings file`) — from the outside
-     * indistinguishable from a bad bundle.
-     *
-     * **Two distinct steps, both load-bearing.**
-     * `installManifestNativeDeps` fetches the DECLARED natives (prebuilt host copy
-     * first — offline — then npm + an ABI rebuild), and is idempotent through a
-     * content-hash marker. `ensureAddonNativePrebuilds` is the post-install pass:
-     * npm can leave a traditional native (`better-sqlite3`) SOURCE-ONLY on a
-     * toolchain-less host, so it re-fetches the prebuild for the running ABI and
-     * THROWS naming module + addon if the binary is still absent. No bundled
-     * source is available on this path (unlike `installCopy`) — fetch only.
-     *
-     * **Failure is FATAL**, mirroring the tgz path: callers complete the tree
-     * BEFORE they swap, so an abort simply means the swap never happens and the
-     * previous version keeps serving. Shipping a native-less copy instead would
-     * trade one broken version for a crash-loop.
-     *
-     * A missing/unreadable manifest is logged and skipped — `installRuntimeDependencies`
-     * has already said so loudly, and a tree with no readable package.json
-     * declares no natives.
-     */
-    private installNativeDependencies;
-    /**
-     * Stop copying what the server closure already provides: replace each
-     * top-level `node_modules` entry the closure serves at a COMPATIBLE version
-     * with a symlink into the closure (see `deps/closure-dedupe.ts` for the
-     * plan rules and the live measurements). Runs LAST in tree
-     * materialisation — after the runtime-dep npm install AND the native-dep
-     * steps — so no later npm invocation can fight the links.
-     *
-     * Non-fatal by design: dedupe is an optimisation, and its failure mode is
-     * "the addon keeps its own copies", which is exactly today's behaviour. A
-     * refusal on version grounds is logged loudly — that line is the answer to
-     * "why does this addon still carry its own zod".
-     */
-    private dedupeTreeAgainstClosure;
-    /** 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
-     *   4. Prune every OTHER backup of this addon — the previous one just
-     *      lost its only pointer and would otherwise be orphaned forever.
-     *
-     * The post-install caller (restart + health-check) is responsible for
-     * verifying the new version actually works, and for calling either
-     * `clearBackup()` on success or `rollbackAddon()` on failure. This
-     * method must NOT delete the backup itself: at this point the new
-     * version has not been proven to work.
-     *
-     * 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;
-    }>;
-    /**
-     * Apply an update from a pre-validated staged directory — the fast
-     * swap-from-staged path that skips npm entirely.
-     *
-     * Mirrors `applyUpdate` exactly for backup/restore/manifest, but
-     * replaces step 2 ("install new version") with an atomic directory
-     * move of `stagedPath` into `addonDir`.
-     *
-     * "Skips npm entirely" is true only of the REGISTRY round-trip: the staged
-     * tree is the raw unpacked tarball, so the addon's own
-     * `camstack.runtimeDependencies` AND `camstack.nativeDependencies` still have
-     * to be installed into it, exactly as `installFromTgz` does. Skipping the
-     * first broke every runtime-dep addon on its first OTA update; skipping the
-     * second broke every addon with a native module the same way, one layer down
-     * (`Could not locate the bindings file` instead of `Cannot find module`) —
-     * see {@link installRuntimeDependencies} and {@link installNativeDependencies}.
-     *
-     * Order matters and is `installFromTgz`'s: the tree is COMPLETED FIRST, and
-     * the live install is only then backed up and replaced. So the addon keeps
-     * serving the old version for the whole (minutes-long) npm install, the swap
-     * window stays two renames wide, and a dependency failure aborts with the
-     * previous version untouched instead of leaving a dependency-less copy live.
-     *
-     * On cross-device move (EXDEV) falls back to a recursive copy followed
-     * by removal of the staged directory. On any swap failure the backup is
-     * restored and the error is rethrown — identical recovery to `applyUpdate`.
-     *
-     * Throws if the package is not tracked in the manifest, if `addonDir`
-     * is missing (same preconditions as `applyUpdate`), or if the runtime-dep /
-     * native-dep install fails.
-     */
-    applyUpdateFromStaged(packageName: string, version: string, stagedPath: 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>;
-    /** Root of the pre-update rollback copies: `{addonsDir}/.backups`. */
-    private get backupsRoot();
-    /**
-     * True only when `target` resolves to something strictly INSIDE
-     * `{addonsDir}/.backups/`.
-     *
-     * Every deletion in this section funnels through here. `lastBackupDir`
-     * is read back from a manifest file on disk — an operator edit, a
-     * restored manifest from another host, or a `..` in the recorded path
-     * must never turn "reclaim a backup" into "delete the live install".
-     */
-    private isInsideBackups;
-    /**
-     * Best-effort removal of one path under `.backups/`.
-     *
-     * Never throws: an undeleted backup is a disk-space problem, whereas a
-     * throw on the post-update success path would turn a working update into
-     * a reported outage. Returns true only when the path is gone.
-     */
-    private removeBackupPath;
-    /** List the timestamped backup dirs recorded for one package. */
-    private listBackupsFor;
-    /**
-     * Keep at most ONE backup per addon: drop every backup dir for
-     * `packageName` except `keepDir`.
-     *
-     * Called right after a new backup is recorded. Without this, a second
-     * update overwrites `lastBackupDir` and the previous backup becomes
-     * unreachable — no pointer, so neither `rollbackAddon` nor `clearBackup`
-     * can ever see it again. That is how the live hub accumulated two 398 MiB
-     * copies of one addon. Never throws.
-     */
-    private pruneBackups;
-    /** Drop `.backups/{pkg}` (and its `@scope` parent) once they are empty. */
-    private removeEmptyBackupDirs;
-    /**
-     * Drop the recorded backup for an addon — call once the post-update
-     * health check confirms the new version actually works.
-     *
-     * Never throws and never rejects. The manifest pointer is cleared even
-     * when the bytes could not be removed: a pointer at a half-deleted tree
-     * would make `rollbackAddon` restore a gutted install, and the boot sweep
-     * reclaims the residue on the next start.
-     */
-    clearBackup(packageName: string): Promise<void>;
-    /**
-     * Boot-time retention sweep over `{addonsDir}/.backups/`.
-     *
-     * RULE: for each addon, the ONLY backup that survives is the one the
-     * manifest's `lastBackupDir` points at — everything else is unreachable
-     * by construction (no pointer ⇒ neither `rollbackAddon` nor `clearBackup`
-     * can ever reach it). One exception: when the addon's LIVE install dir is
-     * missing, the newest backup is the only surviving copy of that addon (a
-     * crash between the rename-aside and the manifest write in `applyUpdate`),
-     * so it is kept instead of reclaimed.
-     *
-     * Why not "delete everything once the addon is healthy": this installer
-     * has no health signal, and the pointed-at backup is precisely the one a
-     * failed update left for the operator's Rollback button. Bounding to one
-     * per addon is enough — the observed 814 MiB was duplicate copies, not a
-     * single retained rollback target.
-     *
-     * Never throws. Safe to run on every boot; runs before any update can be
-     * in flight.
-     */
-    sweepBackups(): Promise<BackupSweepResult>;
-    /**
-     * Which backup of `packageName` survives the sweep: the manifest's
-     * rollback target, or — when the live install is gone — the newest copy,
-     * which is then the only one that exists. `null` means "reclaim them all".
-     */
-    private resolveBackupToKeep;
-    /** Package names that have a `.backups/{pkg}` directory, scoped or not. */
-    private listBackedUpPackages;
-    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;
+	readonly addonsDir: string;
+	private readonly registry;
+	readonly workspaceDir: string | undefined;
+	readonly installSource: InstallSource;
+	private readonly logger;
+	private readonly isPackageResolvable?;
+	/** Test seam — production resolves via `CAMSTACK_FRAMEWORK_DIR`. */
+	private readonly closureNodeModulesDir;
+	/**
+	* 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;
+	/**
+	* Basenames under `.staging` this process is currently building. Never swept
+	* — see {@link selectSweepableStaging}.
+	*/
+	private readonly inFlightStaging;
+	constructor(config: AddonInstallerConfig, logger?: IScopedLogger);
+	/**
+	* Where a bootstrapped npm lives when the host has none on PATH (packaged
+	* Electron agents ship a bare node binary). Persistent — sibling of the
+	* installed addons, survives restarts, downloaded at most once per host.
+	*/
+	private get npmCacheDir();
+	/** Shared options for every npm invocation this installer performs. */
+	private npmRunOptions;
+	/**
+	* 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.
+	*/
+	/**
+	* Is `packageName` reachable through normal resolution — i.e. does the
+	* running closure already provide it?
+	*
+	* Overridable via `AddonInstallerConfig.isPackageResolvable` so a spec can
+	* exercise BOTH sides. That matters more than it looks: the branch that
+	* still seeds is the one protecting a fresh deployment from an unbootable
+	* node, and it is unreachable in a test process where `@camstack/system`
+	* always resolves.
+	*/
+	private isResolvableFromClosure;
+	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/server`
+	* meta-package's `camstack.agentBootstrapAddons` manifest field (single
+	* source of truth; the separate agent meta-package is gone).
+	* The agent runtime boots from the SAME `@camstack/server` closure, so its
+	* bootstrap addon set is declared alongside the hub's. Adding an agent
+	* bootstrap addon = adding it to `server/backend/package.json`'s
+	* `camstack.agentBootstrapAddons`.
+	*/
+	static readonly AGENT_PACKAGES: readonly string[];
+	/**
+	* Derive the agent bootstrap addon list from a meta-package's
+	* `camstack.agentBootstrapAddons` manifest field, prepending
+	* `@camstack/system` (the required infrastructure builtins carrier — same
+	* rationale as `deriveBootstrapList`). Mirrors `deriveBootstrapList`'s
+	* `require.resolve` nuance: the meta-package may be absent in a deployment
+	* (this field is eagerly evaluated at class-load), so a failed resolve
+	* yields an empty list rather than throwing.
+	*/
+	private static deriveAgentBootstrapList;
+	/**
+	* 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.
+	*
+	* There is no version argument and there is deliberately no pin: the system is
+	* addons-agnostic and `latest` is the whole contract at first boot (operator,
+	* 2026-08-13). A copy already under the addon root is never replaced either —
+	* bootstrap is seed-only, and overwriting a deployed bundle would be an
+	* un-deploy ([D90](../../../../docs/decisions/adr-0090.md)).
+	*
+	* @param packages — optional custom package list (default: REQUIRED_PACKAGES)
+	*/
+	ensureRequiredPackages(packages?: readonly string[]): Promise<void>;
+	/**
+	* Reconcile the install manifest against the addons actually present on
+	* disk: register seeded addons, correct a version that disagrees with the
+	* installed `package.json`, and drop entries naming a directory that does
+	* not exist. Call once after `ensureRequiredPackages`, before any update
+	* can be in flight. See `AddonManifest.reconcileFromDisk` for the rules.
+	*
+	* Every correction is logged by name — a manifest that silently disagreed
+	* with disk is what made "@camstack/system 1.2.29" read as installed on a
+	* hub that deliberately has no copy of it.
+	*
+	* Returns the number of changes.
+	*/
+	reconcileManifest(): number;
+	/**
+	* Make every INSTALLED addon's runtime dependencies resolvable — doing the
+	* least work that achieves it. Runs at boot on hub and agent, which is what
+	* turns a restore back into a working node: a system backup archives no
+	* node_modules (D338), so before this pass every restored non-bootstrap
+	* addon failed its first import until someone redeployed it by hand.
+	*
+	* Per addon, in order:
+	*  1. drop closure links that no longer hold (dangling, or the closure
+	*     moved to a version the addon tree's recorded ranges refuse) — those
+	*     addons get a reinstall;
+	*  2. a declared dep that already resolves in the addon tree costs nothing;
+	*  3. a missing declared dep the closure provides at a COMPATIBLE version
+	*     becomes a link — no npm, no network;
+	*  4. only an addon left with a genuinely unresolvable dep gets an npm
+	*     install (then dedupe + native ensure, same tail as a fresh install).
+	*
+	* "Only when necessary" is the contract: an addon whose deps are all
+	* satisfied is not touched at all. Failures are per-addon and non-fatal —
+	* a dep that cannot be re-fetched leaves that addon exactly as broken as
+	* it already was, but LOUDLY, and never blocks the rest of the boot.
+	*/
+	ensureAddonRuntimeDeps(): Promise<EnsureAddonDepsResult>;
+	/**
+	* One addon's dependency audit (steps 1–3 of `ensureAddonRuntimeDeps`).
+	* Pure decision + link creation; the npm fallback is the caller's.
+	*/
+	private ensureOneAddonDeps;
+	/**
+	* npm-install an installed addon's runtime deps IN PLACE (the restore /
+	* repair path — the tree is not yet running at boot), then the same tail
+	* every fresh install gets: closure dedupe + native deps + prebuild ensure.
+	* Closure links are stripped first so npm reifies against plain missing
+	* dirs instead of symlinks it does not own.
+	*/
+	private reinstallAddonDeps;
+	/**
+	* 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.
+	*/
+	/**
+	* Re-install one addon from the running server closure.
+	*
+	* The closure carries a copy of every addon it declares as a dependency, and
+	* NOTHING loads an addon from there — `AddonLoader` reads the addon root and
+	* only the addon root, on every role. So those copies are transport, and
+	* this is the only thing that moves them into the place that runs code.
+	*
+	* Without it a server update advances the closure and changes nothing: six
+	* addons on the hub were behind by up to nineteen versions on 2026-09-17,
+	* each frozen at whenever somebody last ran `camstack deploy`.
+	*
+	* WHICH addons deserve this is not decided here — see `planAddonRealignment`,
+	* which needs two gates because a version comparison alone would overwrite a
+	* deliberate deploy. This only carries out a decision already made.
+	*/
+	realignFromClosure(packageName: string, closureDir: string): Promise<{
+		name: string;
+		version: string;
+	}>;
+	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;
+	/**
+	* Evict an existing install dir by atomic rename-aside, then best-effort
+	* delete the aside copy.
+	*
+	* Why not a plain `fs.promises.rm(targetDir, {recursive})`: during a
+	* `camstack deploy` the addon's live runner still holds its native
+	* prebuilds (`.node`/`.so`) open. On the hub's shfs/FUSE `/data/addons`,
+	* a recursive rm of a held subdir fails `ENOTEMPTY` mid-walk and leaves
+	* the dir gutted. A rename only touches the dirent (metadata), so it
+	* succeeds with the inodes still open — the old runner keeps its fds on
+	* the moved inodes until it restarts.
+	*
+	* The aside copy is removed best-effort: the held native libs are only
+	* released once the post-install `restartAddon` recycles the runner, so a
+	* failure to delete it now must NOT fail the install. Any residue is swept
+	* on the next deploy.
+	*/
+	private evictInstallDir;
+	/**
+	* Best-effort removal of `.staging` residue left by a CRASHED earlier deploy.
+	*
+	* Deliberately not `sweepGraveyard`: an evicted `.evicting/*` dir is dead by
+	* construction, but a `.staging/*` dir may be an install still running — in
+	* this process or another one. Deleting one of those fails a live deploy with
+	* an ENOENT on its own package.json, which is what happened on 2026-08-07.
+	*/
+	private sweepStagingResidue;
+	/** Best-effort removal of leftover `.evicting/*` dirs from earlier deploys. */
+	private sweepGraveyard;
+	/**
+	* Make `pkgDir` (an addon tree that has NOT been swapped in yet) runnable:
+	* strip the host-provided deps from its manifest, then `npm install` whatever
+	* survives.
+	*
+	* ONE implementation for every path that materialises an addon tree —
+	* `installFromTgz` (deploy/upload) and `applyUpdateFromStaged` (OTA). The OTA
+	* path did not have it, and that is a whole outage class: an addon declaring
+	* `camstack.runtimeDependencies` was broken by its FIRST OTA update, its dist
+	* landing without `node_modules`. Every load then threw `Cannot find module`
+	* and the retry loop replayed it — `@camstack/addon-export-hap`, 126 failed
+	* load retries over 10.5h on 2026-08-12; `@camstack/addon-remote-storage`
+	* (`@aws-sdk/*`, `webdav`) is the same landmine.
+	*
+	* **Strip.** `@camstack/*` are host-provided system packages that resolve via
+	* the host's node_modules (Node walks up from the installed addon dir). Left
+	* in, this `npm install` pulls the LAST PUBLISHED `@camstack/types` (etc.)
+	* into the addon's OWN node_modules where it SHADOWS the host's fresh copy —
+	* local additions to a system package silently never reach the deployed
+	* addon. Addon dists are self-contained besides, so `stripBundledDeps` keeps
+	* only what the manifest explicitly declares in
+	* `camstack.runtimeDependencies` (see fs-utils / ADR-0027). Nothing left to
+	* install is the COMMON case: skip npm rather than pay an empty round-trip.
+	*
+	* **Failure is FATAL.** This used to warn-and-continue on the tgz path ("the
+	* addon may still load if imports are lazy") — live cost: a host with no npm
+	* (packaged Electron Mac agent) installed every runtime-dep addon WITHOUT its
+	* node_modules for DAYS; each reported "running" while its entry failed at
+	* import (`Cannot find module 'sharp'`), the detection group ran 1/3 members,
+	* and the node silently dropped out of the balancer. Throwing here is what
+	* keeps the PREVIOUS install intact: every caller builds the tree before it
+	* swaps, so an abort simply means the swap never happens.
+	*
+	* A missing/unreadable manifest is NOT fatal — it is logged and skipped. The
+	* callers validate the tree themselves, and a tree with no readable
+	* package.json has no declared deps to install (the loader will skip the
+	* package entirely).
+	*/
+	private installRuntimeDependencies;
+	/**
+	* Make `pkgDir`'s NATIVE modules loadable on THIS host, before it is swapped
+	* in: install whatever `camstack.nativeDependencies` declares, then ensure
+	* every traditional native present in the tree actually carries a compiled
+	* `.node` for the running ABI.
+	*
+	* ONE implementation, for the same reason as {@link installRuntimeDependencies}
+	* — every path that materialises an addon tree calls it, so no call site can
+	* forget it. `installFromTgz` (deploy/upload) always ran these two steps; the
+	* OTA staged-swap path ran NEITHER even after the runtime-dep fix (2026-08-12,
+	* task #15, which named this gap explicitly). Same outage class one layer
+	* down: an addon with native modules was broken by its FIRST OTA update, its
+	* dist landing without an ABI-matched binary, and every load dying at the
+	* binding (`Could not locate the bindings file`) — from the outside
+	* indistinguishable from a bad bundle.
+	*
+	* **Two distinct steps, both load-bearing.**
+	* `installManifestNativeDeps` fetches the DECLARED natives (prebuilt host copy
+	* first — offline — then npm + an ABI rebuild), and is idempotent through a
+	* content-hash marker. `ensureAddonNativePrebuilds` is the post-install pass:
+	* npm can leave a traditional native (`better-sqlite3`) SOURCE-ONLY on a
+	* toolchain-less host, so it re-fetches the prebuild for the running ABI and
+	* THROWS naming module + addon if the binary is still absent. No bundled
+	* source is available on this path (unlike `installCopy`) — fetch only.
+	*
+	* **Failure is FATAL**, mirroring the tgz path: callers complete the tree
+	* BEFORE they swap, so an abort simply means the swap never happens and the
+	* previous version keeps serving. Shipping a native-less copy instead would
+	* trade one broken version for a crash-loop.
+	*
+	* A missing/unreadable manifest is logged and skipped — `installRuntimeDependencies`
+	* has already said so loudly, and a tree with no readable package.json
+	* declares no natives.
+	*/
+	private installNativeDependencies;
+	/**
+	* Stop copying what the server closure already provides: replace each
+	* top-level `node_modules` entry the closure serves at a COMPATIBLE version
+	* with a symlink into the closure (see `deps/closure-dedupe.ts` for the
+	* plan rules and the live measurements). Runs LAST in tree
+	* materialisation — after the runtime-dep npm install AND the native-dep
+	* steps — so no later npm invocation can fight the links.
+	*
+	* Non-fatal by design: dedupe is an optimisation, and its failure mode is
+	* "the addon keeps its own copies", which is exactly today's behaviour. A
+	* refusal on version grounds is logged loudly — that line is the answer to
+	* "why does this addon still carry its own zod".
+	*/
+	private dedupeTreeAgainstClosure;
+	/** 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
+	*   4. Prune every OTHER backup of this addon — the previous one just
+	*      lost its only pointer and would otherwise be orphaned forever.
+	*
+	* The post-install caller (restart + health-check) is responsible for
+	* verifying the new version actually works, and for calling either
+	* `clearBackup()` on success or `rollbackAddon()` on failure. This
+	* method must NOT delete the backup itself: at this point the new
+	* version has not been proven to work.
+	*
+	* 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;
+	}>;
+	/**
+	* Apply an update from a pre-validated staged directory — the fast
+	* swap-from-staged path that skips npm entirely.
+	*
+	* Mirrors `applyUpdate` exactly for backup/restore/manifest, but
+	* replaces step 2 ("install new version") with an atomic directory
+	* move of `stagedPath` into `addonDir`.
+	*
+	* "Skips npm entirely" is true only of the REGISTRY round-trip: the staged
+	* tree is the raw unpacked tarball, so the addon's own
+	* `camstack.runtimeDependencies` AND `camstack.nativeDependencies` still have
+	* to be installed into it, exactly as `installFromTgz` does. Skipping the
+	* first broke every runtime-dep addon on its first OTA update; skipping the
+	* second broke every addon with a native module the same way, one layer down
+	* (`Could not locate the bindings file` instead of `Cannot find module`) —
+	* see {@link installRuntimeDependencies} and {@link installNativeDependencies}.
+	*
+	* Order matters and is `installFromTgz`'s: the tree is COMPLETED FIRST, and
+	* the live install is only then backed up and replaced. So the addon keeps
+	* serving the old version for the whole (minutes-long) npm install, the swap
+	* window stays two renames wide, and a dependency failure aborts with the
+	* previous version untouched instead of leaving a dependency-less copy live.
+	*
+	* On cross-device move (EXDEV) falls back to a recursive copy followed
+	* by removal of the staged directory. On any swap failure the backup is
+	* restored and the error is rethrown — identical recovery to `applyUpdate`.
+	*
+	* Throws if the package is not tracked in the manifest, if `addonDir`
+	* is missing (same preconditions as `applyUpdate`), or if the runtime-dep /
+	* native-dep install fails.
+	*/
+	applyUpdateFromStaged(packageName: string, version: string, stagedPath: 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>;
+	/** Root of the pre-update rollback copies: `{addonsDir}/.backups`. */
+	private get backupsRoot();
+	/**
+	* True only when `target` resolves to something strictly INSIDE
+	* `{addonsDir}/.backups/`.
+	*
+	* Every deletion in this section funnels through here. `lastBackupDir`
+	* is read back from a manifest file on disk — an operator edit, a
+	* restored manifest from another host, or a `..` in the recorded path
+	* must never turn "reclaim a backup" into "delete the live install".
+	*/
+	private isInsideBackups;
+	/**
+	* Best-effort removal of one path under `.backups/`.
+	*
+	* Never throws: an undeleted backup is a disk-space problem, whereas a
+	* throw on the post-update success path would turn a working update into
+	* a reported outage. Returns true only when the path is gone.
+	*/
+	private removeBackupPath;
+	/** List the timestamped backup dirs recorded for one package. */
+	private listBackupsFor;
+	/**
+	* Keep at most ONE backup per addon: drop every backup dir for
+	* `packageName` except `keepDir`.
+	*
+	* Called right after a new backup is recorded. Without this, a second
+	* update overwrites `lastBackupDir` and the previous backup becomes
+	* unreachable — no pointer, so neither `rollbackAddon` nor `clearBackup`
+	* can ever see it again. That is how the live hub accumulated two 398 MiB
+	* copies of one addon. Never throws.
+	*/
+	private pruneBackups;
+	/** Drop `.backups/{pkg}` (and its `@scope` parent) once they are empty. */
+	private removeEmptyBackupDirs;
+	/**
+	* Drop the recorded backup for an addon — call once the post-update
+	* health check confirms the new version actually works.
+	*
+	* Never throws and never rejects. The manifest pointer is cleared even
+	* when the bytes could not be removed: a pointer at a half-deleted tree
+	* would make `rollbackAddon` restore a gutted install, and the boot sweep
+	* reclaims the residue on the next start.
+	*/
+	clearBackup(packageName: string): Promise<void>;
+	/**
+	* Boot-time retention sweep over `{addonsDir}/.backups/`.
+	*
+	* RULE: for each addon, the ONLY backup that survives is the one the
+	* manifest's `lastBackupDir` points at — everything else is unreachable
+	* by construction (no pointer ⇒ neither `rollbackAddon` nor `clearBackup`
+	* can ever reach it). One exception: when the addon's LIVE install dir is
+	* missing, the newest backup is the only surviving copy of that addon (a
+	* crash between the rename-aside and the manifest write in `applyUpdate`),
+	* so it is kept instead of reclaimed.
+	*
+	* Why not "delete everything once the addon is healthy": this installer
+	* has no health signal, and the pointed-at backup is precisely the one a
+	* failed update left for the operator's Rollback button. Bounding to one
+	* per addon is enough — the observed 814 MiB was duplicate copies, not a
+	* single retained rollback target.
+	*
+	* Never throws. Safe to run on every boot; runs before any update can be
+	* in flight.
+	*/
+	sweepBackups(): Promise<BackupSweepResult>;
+	/**
+	* Which backup of `packageName` survives the sweep: the manifest's
+	* rollback target, or — when the live install is gone — the newest copy,
+	* which is then the only one that exists. `null` means "reclaim them all".
+	*/
+	private resolveBackupToKeep;
+	/** Package names that have a `.backups/{pkg}` directory, scoped or not. */
+	private listBackedUpPackages;
+	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;
 }