@camstack/system 1.2.179 → 1.2.180

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

@@ -57,8 +57,25 @@ export interface AddonInstallerConfig {
      * 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;
 }
 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[];
+}
 /** Outcome of {@link AddonInstaller.sweepBackups}. Absolute paths. */
 export interface BackupSweepResult {
     /** Backup dirs reclaimed by the sweep. */
@@ -104,6 +121,8 @@ export declare class AddonInstaller {
     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
@@ -209,6 +228,42 @@ export declare class AddonInstaller {
      * 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).
@@ -382,6 +437,20 @@ export declare class AddonInstaller {
      * 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;

package/dist/kernel/deps/closure-dedupe.d.ts

@@ -0,0 +1,105 @@
+import { IScopedLogger } from '@camstack/types';
+/**
+ * Does `version` satisfy `range`, for the range forms this module is willing
+ * to vouch for?
+ *
+ * Supported: exact (`1.2.3`, `=1.2.3`), caret (`^1.2.3`, incl. the 0.x rules)
+ * and tilde (`~1.2.3`). EVERYTHING else — `*`, `>=`, unions, hyphen ranges,
+ * dist-tags, bases with prereleases — returns false: an unprovable range must
+ * keep the addon's own copy, never borrow the closure's.
+ *
+ * A prerelease `version` satisfies only an exact string match — semver range
+ * semantics around prereleases are precisely the kind of subtlety a
+ * hand-rolled parser must refuse rather than approximate.
+ */
+export declare function closureSatisfiesRange(range: string, version: string): boolean;
+/**
+ * Belt over the range check: the closure copy must live in the same major
+ * line as the copy npm actually materialised (same minor while major is 0).
+ * The range check should already guarantee this; if the two ever disagree
+ * the safe answer is "do not link".
+ */
+export declare function sameCompatLine(a: string, b: string): boolean;
+/** A real (non-symlink) top-level entry of an addon's node_modules. */
+export interface DedupeCandidate {
+    readonly name: string;
+    readonly version: string;
+}
+export type ClosureKeepReason = 'camstack-package' | 'never-link' | 'not-in-closure' | 'version-incompatible';
+export interface ClosureLink {
+    readonly name: string;
+    readonly closureVersion: string;
+}
+export interface ClosureKeep {
+    readonly name: string;
+    readonly reason: ClosureKeepReason;
+}
+export interface ClosureDedupePlan {
+    readonly links: readonly ClosureLink[];
+    readonly keeps: readonly ClosureKeep[];
+}
+export interface ClosureDedupeInput {
+    readonly candidates: readonly DedupeCandidate[];
+    /** name → version installed in the server closure's node_modules. */
+    readonly closureVersions: ReadonlyMap<string, string>;
+    /**
+     * name → every requirement range the addon tree records for it (the addon's
+     * own manifest + every dependent that resolves to the top-level copy).
+     */
+    readonly requirements: ReadonlyMap<string, readonly string[]>;
+    /** Names that must never be linked (e.g. `camstack.nativeDependencies`). */
+    readonly neverLink: ReadonlySet<string>;
+}
+/**
+ * Decide, per top-level entry, whether the closure's copy can serve in place
+ * of the addon's own. Identical versions always link; otherwise every
+ * recorded requirement range must accept the closure version, and the two
+ * copies must share a compat line. Anything unprovable keeps the local copy.
+ */
+export declare function planClosureDedupe(input: ClosureDedupeInput): ClosureDedupePlan;
+export interface AddonTreeState {
+    /** Real directories eligible for linking (symlinks are excluded). */
+    readonly candidates: readonly DedupeCandidate[];
+    /** name → requirement ranges collected across the tree. */
+    readonly requirements: ReadonlyMap<string, readonly string[]>;
+    /** Top-level entries that are already symlinks (with their targets). */
+    readonly existingLinks: readonly {
+        readonly name: string;
+        readonly target: string;
+    }[];
+}
+/**
+ * Read an addon tree's dedupe-relevant state: which top-level packages exist
+ * (and their versions), and which requirement ranges apply to each. A
+ * dependent's range for `X` is recorded only when that dependent resolves to
+ * the TOP-LEVEL `X` — a nested override copy (`dep/node_modules/X`) means the
+ * flat copy is not what that dependent loads, so its range must not block the
+ * flat copy's dedupe.
+ */
+export declare function collectAddonTreeState(addonDir: string): AddonTreeState;
+/** Read `name → version` from a closure node_modules for the given names. */
+export declare function readClosureVersions(closureNodeModulesDir: string, names: Iterable<string>): Map<string, string>;
+/**
+ * Where the running node's server closure keeps its node_modules, or null
+ * when there is none to dedupe against (dev workspace, tests without a
+ * closure). `CAMSTACK_FRAMEWORK_DIR` is set by the starter/launcher on every
+ * deployed node — the same directory the framework resolver hook and
+ * NODE_PATH extension already point at.
+ */
+export declare function resolveClosureNodeModulesDir(explicitDir: string | undefined): string | null;
+/**
+ * Replace each planned entry with a symlink into the closure. Probes symlink
+ * support once (Windows without developer mode cannot create them — in that
+ * case every copy is kept, which is exactly today's behaviour). Each link
+ * re-verifies the closure version right before the swap so a closure updated
+ * mid-flight can only cause a KEEP, never a wrong link.
+ *
+ * Returns the names actually linked.
+ */
+export declare function executeClosureDedupe(addonDir: string, closureNodeModulesDir: string, plan: ClosureDedupePlan, logger: IScopedLogger): readonly string[];
+/**
+ * Is `linkTarget` (as read from `readlink`) a path inside the closure's
+ * node_modules? Only such links belong to this mechanism — workspace/npm
+ * `file:` links must never be touched by dedupe maintenance.
+ */
+export declare function isClosureLinkTarget(linkTarget: string, closureNodeModulesDir: string): boolean;

package/dist/{manifest-system-deps-PAIfmNun.js → manifest-system-deps-BVIr3MYJ.js}

@@ -1,5 +1,5 @@
 const require_chunk = require("./chunk-Cek0wNdY.js");
-require("./dist-C7qWwrK1.js");
+require("./dist-TEwQZL3g.js");
 require("./hub-cap-forward-DmHNjbB0.js");
 let node_crypto = require("node:crypto");
 node_crypto = require_chunk.__toESM(node_crypto);

package/dist/{manifest-system-deps-CMOGc5nC.mjs → manifest-system-deps-Ci-jhrxY.mjs}

@@ -1,4 +1,4 @@
-import "./dist-L_39vRmH.mjs";
+import "./dist-DqNTelT4.mjs";
 import "./hub-cap-forward-BdT320dq.mjs";
 import * as crypto$1 from "node:crypto";
 import { randomBytes, randomUUID } from "node:crypto";

package/dist/{retired-settings-keys-CnbKAxmX.mjs → retired-settings-keys-CeSITpIX.mjs}

@@ -1,4 +1,4 @@
-import { Gt as asJsonObject } from "./dist-L_39vRmH.mjs";
+import { Gt as asJsonObject } from "./dist-DqNTelT4.mjs";
 //#region src/builtins/sqlite-storage/retired-settings-keys.ts
 /**
 * Is THIS node the one whose settings store is the cluster's authority?

package/dist/{retired-settings-keys-3soU9pfP.js → retired-settings-keys-DauPtbFR.js}

@@ -1,4 +1,4 @@
-const require_dist = require("./dist-C7qWwrK1.js");
+const require_dist = require("./dist-TEwQZL3g.js");
 //#region src/builtins/sqlite-storage/retired-settings-keys.ts
 /**
 * Is THIS node the one whose settings store is the cluster's authority?

package/package.json

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