@camstack/server 1.1.42 → 1.1.44

package/dist/server-root/index.js

@@ -0,0 +1,1124 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __commonJS = (cb, mod) => function __require() {
+  return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget && __copyProps(secondTarget, mod, "default"));
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// ../../packages/node-root/dist/index.js
+var require_dist = __commonJS({
+  "../../packages/node-root/dist/index.js"(exports2, module2) {
+    "use strict";
+    var __create2 = Object.create;
+    var __defProp2 = Object.defineProperty;
+    var __getOwnPropDesc2 = Object.getOwnPropertyDescriptor;
+    var __getOwnPropNames2 = Object.getOwnPropertyNames;
+    var __getProtoOf2 = Object.getPrototypeOf;
+    var __hasOwnProp2 = Object.prototype.hasOwnProperty;
+    var __export2 = /* @__PURE__ */ __name((target, all) => {
+      for (var name in all) __defProp2(target, name, {
+        get: all[name],
+        enumerable: true
+      });
+    }, "__export");
+    var __copyProps2 = /* @__PURE__ */ __name((to, from, except, desc) => {
+      if (from && typeof from === "object" || typeof from === "function") {
+        for (let key of __getOwnPropNames2(from)) if (!__hasOwnProp2.call(to, key) && key !== except) __defProp2(to, key, {
+          get: /* @__PURE__ */ __name(() => from[key], "get"),
+          enumerable: !(desc = __getOwnPropDesc2(from, key)) || desc.enumerable
+        });
+      }
+      return to;
+    }, "__copyProps");
+    var __toESM2 = /* @__PURE__ */ __name((mod, isNodeMode, target) => (target = mod != null ? __create2(__getProtoOf2(mod)) : {}, __copyProps2(
+      // If the importer is in node compatibility mode or this is not an ESM
+      // file that has been converted to a CommonJS file using a Babel-
+      // compatible transform (i.e. "__esModule" has not been set), then set
+      // "default" to the CommonJS "module.exports" for node compatibility.
+      isNodeMode || !mod || !mod.__esModule ? __defProp2(target, "default", {
+        value: mod,
+        enumerable: true
+      }) : target,
+      mod
+    )), "__toESM");
+    var __toCommonJS2 = /* @__PURE__ */ __name((mod) => __copyProps2(__defProp2({}, "__esModule", {
+      value: true
+    }), mod), "__toCommonJS");
+    var src_exports = {};
+    __export2(src_exports, {
+      AGENT_ROOT_SPEC: /* @__PURE__ */ __name(() => AGENT_ROOT_SPEC, "AGENT_ROOT_SPEC"),
+      HOST_EXTERNAL_SPECIFIERS: /* @__PURE__ */ __name(() => HOST_EXTERNAL_SPECIFIERS, "HOST_EXTERNAL_SPECIFIERS"),
+      HUB_ROOT_SPEC: /* @__PURE__ */ __name(() => HUB_ROOT_SPEC2, "HUB_ROOT_SPEC"),
+      RESTART_INTENT_FILE: /* @__PURE__ */ __name(() => RESTART_INTENT_FILE, "RESTART_INTENT_FILE"),
+      RootUpdateService: /* @__PURE__ */ __name(() => RootUpdateService, "RootUpdateService"),
+      SERVER_ROOT_DIRNAME: /* @__PURE__ */ __name(() => SERVER_ROOT_DIRNAME, "SERVER_ROOT_DIRNAME"),
+      SERVER_ROOT_STATE_FILE: /* @__PURE__ */ __name(() => SERVER_ROOT_STATE_FILE, "SERVER_ROOT_STATE_FILE"),
+      clearRestartIntentMarker: /* @__PURE__ */ __name(() => clearRestartIntentMarker, "clearRestartIntentMarker"),
+      compareSemver: /* @__PURE__ */ __name(() => compareSemver, "compareSemver"),
+      detectWorkspaceRoot: /* @__PURE__ */ __name(() => detectWorkspaceRoot, "detectWorkspaceRoot"),
+      emptyServerRootState: /* @__PURE__ */ __name(() => emptyServerRootState, "emptyServerRootState"),
+      isHostExternal: /* @__PURE__ */ __name(() => isHostExternal, "isHostExternal"),
+      isServerRootState: /* @__PURE__ */ __name(() => isServerRootState, "isServerRootState"),
+      minNodeMajorOf: /* @__PURE__ */ __name(() => minNodeMajorOf, "minNodeMajorOf"),
+      planBoot: /* @__PURE__ */ __name(() => planBoot, "planBoot"),
+      readRestartIntentMarker: /* @__PURE__ */ __name(() => readRestartIntentMarker, "readRestartIntentMarker"),
+      readServerRootState: /* @__PURE__ */ __name(() => readServerRootState, "readServerRootState"),
+      registerActiveRootResolver: /* @__PURE__ */ __name(() => registerActiveRootResolver, "registerActiveRootResolver"),
+      restartIntentMarkerPath: /* @__PURE__ */ __name(() => restartIntentMarkerPath, "restartIntentMarkerPath"),
+      rootEntryPath: /* @__PURE__ */ __name(() => rootEntryPath2, "rootEntryPath"),
+      rootPackageDir: /* @__PURE__ */ __name(() => rootPackageDir2, "rootPackageDir"),
+      runNodeStarter: /* @__PURE__ */ __name(() => runNodeStarter, "runNodeStarter"),
+      serverRootDir: /* @__PURE__ */ __name(() => serverRootDir, "serverRootDir"),
+      stateFilePath: /* @__PURE__ */ __name(() => stateFilePath, "stateFilePath"),
+      validateVersionDir: /* @__PURE__ */ __name(() => validateVersionDir, "validateVersionDir"),
+      versionDir: /* @__PURE__ */ __name(() => versionDir, "versionDir"),
+      versionsDir: /* @__PURE__ */ __name(() => versionsDir, "versionsDir"),
+      writeRestartIntentMarker: /* @__PURE__ */ __name(() => writeRestartIntentMarker, "writeRestartIntentMarker"),
+      writeServerRootState: /* @__PURE__ */ __name(() => writeServerRootState, "writeServerRootState")
+    });
+    module2.exports = __toCommonJS2(src_exports);
+    var HUB_ROOT_SPEC2 = {
+      packageName: "@camstack/server",
+      entryRelPath: [
+        "dist",
+        "launcher.js"
+      ]
+    };
+    var AGENT_ROOT_SPEC = {
+      packageName: "@camstack/agent",
+      entryRelPath: [
+        "dist",
+        "cli.js"
+      ]
+    };
+    var fs = __toESM2(require("fs"));
+    var path = __toESM2(require("path"));
+    var SERVER_ROOT_DIRNAME = "server-root";
+    var SERVER_ROOT_STATE_FILE = "state.json";
+    var RESTART_INTENT_FILE = ".restart-intent";
+    function emptyServerRootState() {
+      return {
+        schemaVersion: 1,
+        currentVersion: null,
+        previousVersion: null,
+        pendingBoot: null,
+        rolledBack: null
+      };
+    }
+    __name(emptyServerRootState, "emptyServerRootState");
+    function serverRootDir(dataDir) {
+      return path.join(dataDir, SERVER_ROOT_DIRNAME);
+    }
+    __name(serverRootDir, "serverRootDir");
+    function versionsDir(rootDir) {
+      return path.join(rootDir, "versions");
+    }
+    __name(versionsDir, "versionsDir");
+    function versionDir(rootDir, version) {
+      return path.join(versionsDir(rootDir), version);
+    }
+    __name(versionDir, "versionDir");
+    function rootPackageDir2(versionDirPath, spec) {
+      return path.join(versionDirPath, "node_modules", ...spec.packageName.split("/"));
+    }
+    __name(rootPackageDir2, "rootPackageDir");
+    function rootEntryPath2(versionDirPath, spec) {
+      return path.join(rootPackageDir2(versionDirPath, spec), ...spec.entryRelPath);
+    }
+    __name(rootEntryPath2, "rootEntryPath");
+    function stateFilePath(rootDir) {
+      return path.join(rootDir, SERVER_ROOT_STATE_FILE);
+    }
+    __name(stateFilePath, "stateFilePath");
+    function isNullableString(v) {
+      return v === null || typeof v === "string";
+    }
+    __name(isNullableString, "isNullableString");
+    function isPendingBoot(v) {
+      if (typeof v !== "object" || v === null) return false;
+      const p = v;
+      return typeof p["version"] === "string" && isNullableString(p["fromVersion"]) && typeof p["requestedAtMs"] === "number" && typeof p["bootAttempts"] === "number";
+    }
+    __name(isPendingBoot, "isPendingBoot");
+    function isRollbackInfo(v) {
+      if (typeof v !== "object" || v === null) return false;
+      const r = v;
+      return typeof r["fromVersion"] === "string" && isNullableString(r["toVersion"]) && typeof r["atMs"] === "number" && typeof r["reason"] === "string";
+    }
+    __name(isRollbackInfo, "isRollbackInfo");
+    function isServerRootState(v) {
+      if (typeof v !== "object" || v === null) return false;
+      const s = v;
+      if (s["schemaVersion"] !== 1) return false;
+      if (!isNullableString(s["currentVersion"])) return false;
+      if (!isNullableString(s["previousVersion"])) return false;
+      if (s["pendingBoot"] !== null && !isPendingBoot(s["pendingBoot"])) return false;
+      if (s["rolledBack"] !== null && !isRollbackInfo(s["rolledBack"])) return false;
+      return true;
+    }
+    __name(isServerRootState, "isServerRootState");
+    function readServerRootState(rootDir) {
+      try {
+        const raw = JSON.parse(fs.readFileSync(stateFilePath(rootDir), "utf-8"));
+        return isServerRootState(raw) ? raw : null;
+      } catch {
+        return null;
+      }
+    }
+    __name(readServerRootState, "readServerRootState");
+    function writeServerRootState(rootDir, state) {
+      fs.mkdirSync(rootDir, {
+        recursive: true
+      });
+      const target = stateFilePath(rootDir);
+      const tmp = `${target}.tmp`;
+      fs.writeFileSync(tmp, JSON.stringify(state, null, 2), "utf-8");
+      fs.renameSync(tmp, target);
+    }
+    __name(writeServerRootState, "writeServerRootState");
+    function restartIntentMarkerPath(rootDir) {
+      return path.join(rootDir, RESTART_INTENT_FILE);
+    }
+    __name(restartIntentMarkerPath, "restartIntentMarkerPath");
+    function isRestartIntentMarker(v) {
+      if (typeof v !== "object" || v === null) return false;
+      const m = v;
+      return typeof m["requestedAtMs"] === "number" && typeof m["reason"] === "string";
+    }
+    __name(isRestartIntentMarker, "isRestartIntentMarker");
+    function writeRestartIntentMarker(rootDir, marker) {
+      fs.mkdirSync(rootDir, {
+        recursive: true
+      });
+      const target = restartIntentMarkerPath(rootDir);
+      const tmp = `${target}.tmp`;
+      fs.writeFileSync(tmp, JSON.stringify(marker, null, 2), "utf-8");
+      fs.renameSync(tmp, target);
+    }
+    __name(writeRestartIntentMarker, "writeRestartIntentMarker");
+    function readRestartIntentMarker(rootDir) {
+      try {
+        const raw = JSON.parse(fs.readFileSync(restartIntentMarkerPath(rootDir), "utf-8"));
+        return isRestartIntentMarker(raw) ? raw : null;
+      } catch {
+        return null;
+      }
+    }
+    __name(readRestartIntentMarker, "readRestartIntentMarker");
+    function clearRestartIntentMarker(rootDir) {
+      try {
+        fs.rmSync(restartIntentMarkerPath(rootDir), {
+          force: true
+        });
+      } catch {
+      }
+    }
+    __name(clearRestartIntentMarker, "clearRestartIntentMarker");
+    function minNodeMajorOf(enginesNode) {
+      const match = /(\d+)/.exec(enginesNode);
+      if (match === null) return null;
+      const major = Number.parseInt(match[1] ?? "", 10);
+      return Number.isNaN(major) ? null : major;
+    }
+    __name(minNodeMajorOf, "minNodeMajorOf");
+    function validateVersionDir(rootDir, version, nodeMajor, spec) {
+      const vDir = versionDir(rootDir, version);
+      const entry = rootEntryPath2(vDir, spec);
+      if (!fs.existsSync(entry)) {
+        return `root entry missing: ${entry}`;
+      }
+      const pkgJsonPath = path.join(rootPackageDir2(vDir, spec), "package.json");
+      let pkg;
+      try {
+        const raw = JSON.parse(fs.readFileSync(pkgJsonPath, "utf-8"));
+        if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+          return `package.json malformed: ${pkgJsonPath}`;
+        }
+        pkg = raw;
+      } catch {
+        return `package.json unreadable: ${pkgJsonPath}`;
+      }
+      if (pkg["name"] !== spec.packageName) {
+        return `package name mismatch: expected ${spec.packageName}, got ${String(pkg["name"])}`;
+      }
+      if (pkg["version"] !== version) {
+        return `package version mismatch: dir says ${version}, package.json says ${String(pkg["version"])}`;
+      }
+      const engines = pkg["engines"];
+      if (typeof engines === "object" && engines !== null) {
+        const enginesNode = engines["node"];
+        if (typeof enginesNode === "string") {
+          const minMajor = minNodeMajorOf(enginesNode);
+          if (minMajor !== null && nodeMajor < minMajor) {
+            return `engines.node "${enginesNode}" requires Node >= ${minMajor}, runtime is ${nodeMajor}`;
+          }
+        }
+      }
+      return null;
+    }
+    __name(validateVersionDir, "validateVersionDir");
+    function planBoot(state, isValidVersion, now) {
+      if (state === null) {
+        return {
+          kind: "baked",
+          reason: "no server-root state",
+          stateToWrite: null
+        };
+      }
+      let next = state;
+      let changed = false;
+      if (next.pendingBoot !== null) {
+        const pending = next.pendingBoot;
+        if (pending.bootAttempts >= 1) {
+          next = {
+            ...next,
+            pendingBoot: null,
+            rolledBack: {
+              fromVersion: pending.version,
+              toVersion: next.currentVersion,
+              atMs: now(),
+              reason: "probation boot did not reach ready \u2014 rolled back"
+            }
+          };
+          changed = true;
+        } else if (!isValidVersion(pending.version)) {
+          next = {
+            ...next,
+            pendingBoot: null,
+            rolledBack: {
+              fromVersion: pending.version,
+              toVersion: next.currentVersion,
+              atMs: now(),
+              reason: "staged version failed validation"
+            }
+          };
+          changed = true;
+        } else {
+          return {
+            kind: "data-root",
+            version: pending.version,
+            probation: true,
+            stateToWrite: {
+              ...next,
+              pendingBoot: {
+                ...pending,
+                bootAttempts: pending.bootAttempts + 1
+              }
+            }
+          };
+        }
+      }
+      if (next.currentVersion !== null) {
+        if (isValidVersion(next.currentVersion)) {
+          return {
+            kind: "data-root",
+            version: next.currentVersion,
+            probation: false,
+            stateToWrite: changed ? next : null
+          };
+        }
+        const broken = next.currentVersion;
+        if (next.previousVersion !== null && isValidVersion(next.previousVersion)) {
+          const fallback = next.previousVersion;
+          return {
+            kind: "data-root",
+            version: fallback,
+            probation: false,
+            stateToWrite: {
+              ...next,
+              currentVersion: fallback,
+              previousVersion: null,
+              rolledBack: {
+                fromVersion: broken,
+                toVersion: fallback,
+                atMs: now(),
+                reason: "active version failed validation"
+              }
+            }
+          };
+        }
+        return {
+          kind: "baked",
+          reason: `active version ${broken} failed validation and no valid previous version exists`,
+          stateToWrite: {
+            ...next,
+            currentVersion: null,
+            rolledBack: {
+              fromVersion: broken,
+              toVersion: null,
+              atMs: now(),
+              reason: "active version failed validation"
+            }
+          }
+        };
+      }
+      return {
+        kind: "baked",
+        reason: "no active data-root version",
+        stateToWrite: changed ? next : null
+      };
+    }
+    __name(planBoot, "planBoot");
+    function parse(version) {
+      const dashIdx = version.indexOf("-");
+      const base = dashIdx === -1 ? version : version.slice(0, dashIdx);
+      const prerelease = dashIdx === -1 ? null : version.slice(dashIdx + 1);
+      const nums = base.split(".").map((seg) => {
+        const n = Number.parseInt(seg, 10);
+        return Number.isNaN(n) ? 0 : n;
+      });
+      return {
+        nums,
+        prerelease
+      };
+    }
+    __name(parse, "parse");
+    function compareSemver(a, b) {
+      const pa = parse(a);
+      const pb = parse(b);
+      const len = Math.max(pa.nums.length, pb.nums.length);
+      for (let i = 0; i < len; i++) {
+        const na = pa.nums[i] ?? 0;
+        const nb = pb.nums[i] ?? 0;
+        if (na < nb) return -1;
+        if (na > nb) return 1;
+      }
+      if (pa.prerelease === null && pb.prerelease === null) return 0;
+      if (pa.prerelease === null) return 1;
+      if (pb.prerelease === null) return -1;
+      if (pa.prerelease < pb.prerelease) return -1;
+      if (pa.prerelease > pb.prerelease) return 1;
+      return 0;
+    }
+    __name(compareSemver, "compareSemver");
+    var fs2 = __toESM2(require("fs"));
+    var path2 = __toESM2(require("path"));
+    function detectWorkspaceRoot(fromDir) {
+      let dir = path2.resolve(fromDir);
+      for (; ; ) {
+        const pkgPath = path2.join(dir, "package.json");
+        try {
+          const raw = JSON.parse(fs2.readFileSync(pkgPath, "utf-8"));
+          if (typeof raw === "object" && raw !== null && raw["workspaces"] !== void 0) {
+            return dir;
+          }
+        } catch {
+        }
+        const parent = path2.dirname(dir);
+        if (parent === dir) return null;
+        dir = parent;
+      }
+    }
+    __name(detectWorkspaceRoot, "detectWorkspaceRoot");
+    var path3 = __toESM2(require("path"));
+    var import_node_url = require("url");
+    var HOST_EXTERNAL_SPECIFIERS = [
+      "@camstack/system",
+      "@camstack/shm-ring",
+      "@camstack/types",
+      "@camstack/sdk",
+      "zod",
+      "@trpc/server",
+      "@trpc/client",
+      "sharp",
+      "node-av"
+    ];
+    function isHostExternal(specifier) {
+      return HOST_EXTERNAL_SPECIFIERS.some((name) => specifier === name || specifier.startsWith(`${name}/`));
+    }
+    __name(isHostExternal, "isHostExternal");
+    function registerActiveRootResolver(activeRootDir) {
+      const moduleApi = require("module");
+      const registerHooks = moduleApi["registerHooks"];
+      if (typeof registerHooks !== "function") {
+        console.warn("[starter] module.registerHooks unavailable (Node < 22.15) \u2014 host-external redirect skipped");
+        return;
+      }
+      const anchorURL = (0, import_node_url.pathToFileURL)(path3.join(activeRootDir, "node_modules", "__camstack_starter_anchor__.js")).href;
+      const hooks = {
+        resolve: /* @__PURE__ */ __name((specifier, context, nextResolve) => {
+          if (isHostExternal(specifier)) {
+            try {
+              return nextResolve(specifier, {
+                ...context,
+                parentURL: anchorURL
+              });
+            } catch {
+            }
+          }
+          return nextResolve(specifier, context);
+        }, "resolve")
+      };
+      registerHooks(hooks);
+    }
+    __name(registerActiveRootResolver, "registerActiveRootResolver");
+    function runNodeStarter(options) {
+      const env = options.env ?? process.env;
+      const now = options.now ?? Date.now;
+      const registerResolver = options.registerResolver ?? registerActiveRootResolver;
+      const disabled = env[options.envNames.killSwitch] === "off";
+      const workspaceRoot = detectWorkspaceRoot(options.starterDir);
+      if (workspaceRoot !== null) {
+        console.log(`[starter] workspace checkout detected at ${workspaceRoot} \u2014 using plain resolution`);
+        env[options.envNames.bootMode] = "workspace";
+        options.loadEntry(options.seedEntry);
+        return;
+      }
+      if (disabled) {
+        console.log(`[starter] ${options.envNames.killSwitch}=off \u2014 booting the baked seed closure`);
+        env[options.envNames.bootMode] = "baked";
+        options.loadEntry(options.seedEntry);
+        return;
+      }
+      const rootDir = serverRootDir(options.dataDir);
+      const state = readServerRootState(rootDir);
+      const nodeMajor = options.nodeMajor ?? Number.parseInt(process.versions.node.split(".")[0] ?? "0", 10);
+      const isValidVersion = /* @__PURE__ */ __name((version) => {
+        const reason = validateVersionDir(rootDir, version, nodeMajor, options.spec);
+        if (reason !== null) console.warn(`[starter] version ${version} invalid: ${reason}`);
+        return reason === null;
+      }, "isValidVersion");
+      const plan = planBoot(state, isValidVersion, now);
+      if (plan.stateToWrite !== null) {
+        try {
+          writeServerRootState(rootDir, plan.stateToWrite);
+        } catch (err) {
+          console.error("[starter] FAILED to persist server-root state \u2014 booting baked seed:", err);
+          env[options.envNames.bootMode] = "baked";
+          options.loadEntry(options.seedEntry);
+          return;
+        }
+        if (plan.stateToWrite.rolledBack !== null && (state?.rolledBack ?? null) !== plan.stateToWrite.rolledBack) {
+          const rb = plan.stateToWrite.rolledBack;
+          console.warn(`[starter] ROLLED BACK ${rb.fromVersion} -> ${rb.toVersion ?? "baked seed"}: ${rb.reason}`);
+        }
+      }
+      if (plan.kind === "data-root") {
+        const activeRootDir = versionDir(rootDir, plan.version);
+        const entry = rootEntryPath2(activeRootDir, options.spec);
+        console.log(`[starter] booting ${options.spec.packageName}@${plan.version} from ${activeRootDir}` + (plan.probation ? " (probation boot \u2014 health-check armed)" : ""));
+        env[options.envNames.bootMode] = "data-root";
+        env[options.envNames.activeRoot] = activeRootDir;
+        env[options.envNames.activeVersion] = plan.version;
+        registerResolver(activeRootDir);
+        options.loadEntry(entry);
+        return;
+      }
+      console.log(`[starter] booting baked seed closure (${plan.reason})`);
+      env[options.envNames.bootMode] = "baked";
+      options.loadEntry(options.seedEntry);
+    }
+    __name(runNodeStarter, "runNodeStarter");
+    var import_node_child_process = require("child_process");
+    var fs3 = __toESM2(require("fs"));
+    var path4 = __toESM2(require("path"));
+    var import_node_util = require("util");
+    var execFileAsync = (0, import_node_util.promisify)(import_node_child_process.execFile);
+    function buildNpmRegistryArgs(registry) {
+      if (registry === void 0 || registry.length === 0) return [];
+      return [
+        "--registry",
+        registry,
+        `--@camstack:registry=${registry}`
+      ];
+    }
+    __name(buildNpmRegistryArgs, "buildNpmRegistryArgs");
+    var NPM_VIEW_TIMEOUT_MS = 2e4;
+    var NPM_INSTALL_TIMEOUT_MS = 15 * 6e4;
+    var RESTART_REASON_PREFIX = "server-update";
+    function readPackageVersion(pkgJsonPath) {
+      try {
+        const raw = JSON.parse(fs3.readFileSync(pkgJsonPath, "utf-8"));
+        if (typeof raw === "object" && raw !== null) {
+          const version = raw["version"];
+          if (typeof version === "string") return version;
+        }
+      } catch {
+      }
+      return null;
+    }
+    __name(readPackageVersion, "readPackageVersion");
+    var RootUpdateService = class _RootUpdateService {
+      static {
+        __name(this, "_RootUpdateService");
+      }
+      spec;
+      envNames;
+      logger;
+      restartServerFn;
+      dataDir;
+      execNpm;
+      env;
+      now;
+      runningPackageJsonPath;
+      workspaceProbeDir;
+      checkCache = null;
+      inFlight = "idle";
+      constructor(options) {
+        this.spec = options.spec;
+        this.envNames = options.envNames;
+        this.logger = options.logger;
+        this.restartServerFn = options.restartServer;
+        this.dataDir = path4.resolve(options.dataDir);
+        this.execNpm = options.execNpm ?? (async (args, opts) => {
+          const { stdout } = await execFileAsync("npm", [
+            ...args
+          ], {
+            cwd: opts.cwd,
+            timeout: opts.timeoutMs
+          });
+          return {
+            stdout
+          };
+        });
+        this.env = options.env ?? process.env;
+        this.now = options.now ?? Date.now;
+        this.runningPackageJsonPath = options.runningPackageJsonPath;
+        this.workspaceProbeDir = options.workspaceProbeDir;
+      }
+      // ── Status ────────────────────────────────────────────────────────────
+      resolveBootMode() {
+        const raw = this.env[this.envNames.bootMode];
+        if (raw === "workspace" || raw === "baked" || raw === "data-root") return raw;
+        return detectWorkspaceRoot(this.workspaceProbeDir) !== null ? "workspace" : "baked";
+      }
+      runningVersion() {
+        return readPackageVersion(this.runningPackageJsonPath);
+      }
+      /** The running root package's identity — feeds registerNode / topology rows. */
+      getRunningRootPackage() {
+        return {
+          name: this.spec.packageName,
+          version: this.runningVersion()
+        };
+      }
+      seedVersion() {
+        const seedDir = this.env[this.envNames.seedDir];
+        if (seedDir === void 0 || seedDir.length === 0) return null;
+        return readPackageVersion(path4.join(seedDir, "package.json"));
+      }
+      rootDir() {
+        return serverRootDir(this.dataDir);
+      }
+      readState() {
+        return readServerRootState(this.rootDir()) ?? emptyServerRootState();
+      }
+      /**
+      * Like `readState`, but distinguishes "state.json missing" (normal on a
+      * fresh node) from "state.json present but corrupt" — in the corrupt case
+      * the starter booted the baked seed while installed data-dir versions are
+      * silently ignored, which the status surface must make visible.
+      */
+      readStateInfo() {
+        const rootDir = this.rootDir();
+        const raw = readServerRootState(rootDir);
+        if (raw !== null) return {
+          state: raw,
+          corrupt: false
+        };
+        return {
+          state: emptyServerRootState(),
+          corrupt: fs3.existsSync(stateFilePath(rootDir))
+        };
+      }
+      updateState(state) {
+        if (this.inFlight === "checking") return "checking";
+        if (this.inFlight === "staging") return "staging";
+        if (state.pendingBoot !== null) {
+          const activeVersion = this.env[this.envNames.activeVersion] ?? null;
+          if (activeVersion !== null && activeVersion === state.pendingBoot.version) {
+            return "awaiting-confirmation";
+          }
+          return "pending-restart";
+        }
+        return "idle";
+      }
+      async getServerPackageStatus() {
+        const { state, corrupt } = this.readStateInfo();
+        const runningVersion = this.runningVersion();
+        const latestVersion = this.checkCache?.latestVersion ?? null;
+        const updateAvailable = latestVersion !== null && runningVersion !== null && compareSemver(latestVersion, runningVersion) > 0;
+        return {
+          packageName: this.spec.packageName,
+          runningVersion,
+          nodeRuntimeVersion: process.versions.node,
+          activeVersion: this.env[this.envNames.activeVersion] ?? state.currentVersion,
+          previousVersion: state.previousVersion,
+          seedVersion: this.seedVersion(),
+          latestVersion,
+          updateAvailable,
+          bootMode: this.resolveBootMode(),
+          updateState: this.updateState(state),
+          pendingVersion: state.pendingBoot?.version ?? null,
+          rolledBack: state.rolledBack,
+          stateFileCorrupt: corrupt,
+          lastCheckedAtMs: this.checkCache?.checkedAtMs ?? null
+        };
+      }
+      // ── Check ─────────────────────────────────────────────────────────────
+      async checkServerUpdate() {
+        const runningVersion = this.runningVersion();
+        if (this.inFlight !== "idle") {
+          return {
+            packageName: this.spec.packageName,
+            runningVersion,
+            latestVersion: this.checkCache?.latestVersion ?? null,
+            updateAvailable: false,
+            checkedAtMs: this.checkCache?.checkedAtMs ?? this.now(),
+            error: `busy: ${this.inFlight}`
+          };
+        }
+        this.inFlight = "checking";
+        try {
+          const registry = this.env["CAMSTACK_NPM_REGISTRY"];
+          const args = [
+            "view",
+            `${this.spec.packageName}@latest`,
+            "version",
+            ...buildNpmRegistryArgs(registry)
+          ];
+          const { stdout } = await this.execNpm(args, {
+            timeoutMs: NPM_VIEW_TIMEOUT_MS
+          });
+          const latestVersion = stdout.trim().length > 0 ? stdout.trim() : null;
+          this.checkCache = {
+            latestVersion,
+            checkedAtMs: this.now(),
+            error: null
+          };
+          const updateAvailable = latestVersion !== null && runningVersion !== null && compareSemver(latestVersion, runningVersion) > 0;
+          return {
+            packageName: this.spec.packageName,
+            runningVersion,
+            latestVersion,
+            updateAvailable,
+            checkedAtMs: this.checkCache.checkedAtMs,
+            error: null
+          };
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          this.checkCache = {
+            latestVersion: this.checkCache?.latestVersion ?? null,
+            checkedAtMs: this.now(),
+            error: message
+          };
+          this.logger.warn("root package update check failed", {
+            meta: {
+              error: message
+            }
+          });
+          return {
+            packageName: this.spec.packageName,
+            runningVersion,
+            latestVersion: this.checkCache.latestVersion,
+            updateAvailable: false,
+            checkedAtMs: this.checkCache.checkedAtMs,
+            error: message
+          };
+        } finally {
+          this.inFlight = "idle";
+        }
+      }
+      // ── Apply ─────────────────────────────────────────────────────────────
+      async applyServerUpdate(input) {
+        const bootMode = this.resolveBootMode();
+        if (bootMode === "workspace") {
+          return {
+            accepted: false,
+            targetVersion: input.version ?? null,
+            restarting: false,
+            message: "Refused: running from a workspace checkout \u2014 the dev loop resolves code from the workspace, a data-root update would never be loaded."
+          };
+        }
+        if (this.inFlight !== "idle") {
+          return {
+            accepted: false,
+            targetVersion: input.version ?? null,
+            restarting: false,
+            message: `Refused: another operation is in flight (${this.inFlight}).`
+          };
+        }
+        const stateBefore = this.readState();
+        if (stateBefore.pendingBoot !== null) {
+          return {
+            accepted: false,
+            targetVersion: input.version ?? null,
+            restarting: false,
+            message: `Refused: version ${stateBefore.pendingBoot.version} is already staged and awaiting restart.`
+          };
+        }
+        let target = input.version ?? null;
+        if (target === null) {
+          const check = await this.checkServerUpdate();
+          if (check.error !== null || check.latestVersion === null) {
+            return {
+              accepted: false,
+              targetVersion: null,
+              restarting: false,
+              message: `Refused: could not resolve the latest version (${check.error ?? "no version returned"}).`
+            };
+          }
+          target = check.latestVersion;
+        }
+        const runningVersion = this.runningVersion();
+        if (target === runningVersion) {
+          return {
+            accepted: false,
+            targetVersion: target,
+            restarting: false,
+            message: `Refused: ${this.spec.packageName}@${target} is already running.`
+          };
+        }
+        this.inFlight = "staging";
+        try {
+          await this.stageAndActivate(target);
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          this.logger.error("root package update staging failed", {
+            meta: {
+              targetVersion: target,
+              error: message
+            }
+          });
+          return {
+            accepted: false,
+            targetVersion: target,
+            restarting: false,
+            message: `Staging failed: ${message}`
+          };
+        } finally {
+          this.inFlight = "idle";
+        }
+        const state = this.readState();
+        writeServerRootState(this.rootDir(), {
+          ...state,
+          pendingBoot: {
+            version: target,
+            fromVersion: state.currentVersion,
+            requestedAtMs: this.now(),
+            bootAttempts: 0
+          },
+          rolledBack: null
+        });
+        this.logger.info("root package update staged \u2014 restarting to apply", {
+          meta: {
+            targetVersion: target,
+            fromVersion: state.currentVersion
+          }
+        });
+        this.restartServerFn(`${RESTART_REASON_PREFIX}: ${this.spec.packageName}@${target}`);
+        return {
+          accepted: true,
+          targetVersion: target,
+          restarting: true,
+          message: `Staged ${this.spec.packageName}@${target} \u2014 restarting to apply (probation boot with auto-rollback).`
+        };
+      }
+      /**
+      * npm-install the target closure into a SAME-FS staging dir inside
+      * `versions/`, validate it, then atomically rename it into place.
+      */
+      async stageAndActivate(target) {
+        const rootDir = this.rootDir();
+        const vDir = versionsDir(rootDir);
+        fs3.mkdirSync(vDir, {
+          recursive: true
+        });
+        const stagingDir = path4.join(vDir, `.staging-${target}-${process.pid}-${this.now()}`);
+        fs3.mkdirSync(stagingDir, {
+          recursive: true
+        });
+        try {
+          fs3.writeFileSync(path4.join(stagingDir, "package.json"), JSON.stringify({
+            name: "camstack-node-root",
+            private: true
+          }, null, 2), "utf-8");
+          const registry = this.env["CAMSTACK_NPM_REGISTRY"];
+          await this.execNpm([
+            "install",
+            "--omit=dev",
+            "--no-audit",
+            "--no-fund",
+            "--loglevel=error",
+            `${this.spec.packageName}@${target}`,
+            ...buildNpmRegistryArgs(registry)
+          ], {
+            cwd: stagingDir,
+            timeoutMs: NPM_INSTALL_TIMEOUT_MS
+          });
+          const entry = rootEntryPath2(stagingDir, this.spec);
+          if (!fs3.existsSync(entry)) {
+            throw new Error(`staged closure is missing the root entry (${entry})`);
+          }
+          const stagedVersion = readPackageVersion(path4.join(rootPackageDir2(stagingDir, this.spec), "package.json"));
+          if (stagedVersion !== target) {
+            throw new Error(`staged closure version mismatch: expected ${target}, got ${stagedVersion ?? "unknown"}`);
+          }
+          const dest = versionDir(rootDir, target);
+          if (fs3.existsSync(dest)) {
+            const aside = `${dest}.evicted-${this.now()}`;
+            await fs3.promises.rename(dest, aside);
+            await fs3.promises.rm(aside, {
+              recursive: true,
+              force: true
+            }).catch(() => void 0);
+          }
+          await fs3.promises.rename(stagingDir, dest);
+        } catch (err) {
+          await fs3.promises.rm(stagingDir, {
+            recursive: true,
+            force: true
+          }).catch(() => void 0);
+          throw err;
+        }
+      }
+      // ── Rollback ──────────────────────────────────────────────────────────
+      async rollbackServerUpdate() {
+        if (this.inFlight !== "idle") {
+          return {
+            accepted: false,
+            targetVersion: null,
+            restarting: false,
+            message: `Refused: another operation is in flight (${this.inFlight}).`
+          };
+        }
+        const state = this.readState();
+        if (state.pendingBoot !== null) {
+          return {
+            accepted: false,
+            targetVersion: null,
+            restarting: false,
+            message: `Refused: version ${state.pendingBoot.version} is already staged and awaiting restart.`
+          };
+        }
+        if (state.currentVersion === null || state.previousVersion === null) {
+          return {
+            accepted: false,
+            targetVersion: state.previousVersion,
+            restarting: false,
+            message: "Refused: no previous version available to roll back to."
+          };
+        }
+        const nodeMajor = Number.parseInt(process.versions.node.split(".")[0] ?? "0", 10);
+        const invalidReason = validateVersionDir(this.rootDir(), state.previousVersion, nodeMajor, this.spec);
+        if (invalidReason !== null) {
+          return {
+            accepted: false,
+            targetVersion: state.previousVersion,
+            restarting: false,
+            message: `Refused: previous version ${state.previousVersion} is not loadable (${invalidReason}).`
+          };
+        }
+        writeServerRootState(this.rootDir(), {
+          ...state,
+          pendingBoot: {
+            version: state.previousVersion,
+            fromVersion: state.currentVersion,
+            requestedAtMs: this.now(),
+            bootAttempts: 0
+          }
+        });
+        this.logger.info("root package rollback requested \u2014 restarting", {
+          meta: {
+            fromVersion: state.currentVersion,
+            toVersion: state.previousVersion
+          }
+        });
+        this.restartServerFn(`${RESTART_REASON_PREFIX}: rollback to ${this.spec.packageName}@${state.previousVersion}`);
+        return {
+          accepted: true,
+          targetVersion: state.previousVersion,
+          restarting: true,
+          message: `Rolling back to ${this.spec.packageName}@${state.previousVersion} \u2014 restarting.`
+        };
+      }
+      // ── Plain restart ─────────────────────────────────────────────────────
+      /**
+      * Plain process restart — no version change. Backs the `restartServer` cap
+      * method. Guards mirror apply/rollback: refuse while a stage is in flight
+      * (a concurrent npm install must not be interrupted) or while a version is
+      * already staged awaiting restart (a naive bounce would boot the OLD version
+      * and orphan the pending one — the operator should apply/rollback instead).
+      */
+      restartNode() {
+        const runningVersion = this.runningVersion();
+        if (this.inFlight !== "idle") {
+          return {
+            accepted: false,
+            targetVersion: runningVersion,
+            restarting: false,
+            message: `Refused: another operation is in flight (${this.inFlight}).`
+          };
+        }
+        const state = this.readState();
+        if (state.pendingBoot !== null) {
+          return {
+            accepted: false,
+            targetVersion: runningVersion,
+            restarting: false,
+            message: `Refused: version ${state.pendingBoot.version} is staged and awaiting restart \u2014 apply or roll it back instead of a plain restart.`
+          };
+        }
+        this.logger.info("plain node restart requested", {
+          meta: {
+            runningVersion
+          }
+        });
+        this.restartServerFn(`${RESTART_REASON_PREFIX}: manual restart`);
+        return {
+          accepted: true,
+          targetVersion: runningVersion,
+          restarting: true,
+          message: "Restarting the node \u2014 the supervisor relaunches it on the same version."
+        };
+      }
+      // ── Boot health confirmation ──────────────────────────────────────────
+      /**
+      * Called by the post-boot path once the node is READY (hub: post-boot
+      * pipeline; agent: first acked `$hub.registerNode`). When THIS process is
+      * the probation boot of a pending version, promote it: `currentVersion` ←
+      * pending, `previousVersion` ← the version it replaced (N-1 retained for
+      * rollback), clear `pendingBoot` + `rolledBack`, and prune every version
+      * dir beyond {current, previous}. No-op otherwise.
+      */
+      confirmBootHealthy() {
+        const state = readServerRootState(this.rootDir());
+        if (state === null || state.pendingBoot === null) return {
+          promoted: null
+        };
+        const activeVersion = this.env[this.envNames.activeVersion] ?? null;
+        if (activeVersion !== state.pendingBoot.version) {
+          return {
+            promoted: null
+          };
+        }
+        const promoted = {
+          ...state,
+          currentVersion: state.pendingBoot.version,
+          previousVersion: state.pendingBoot.fromVersion,
+          pendingBoot: null,
+          rolledBack: null
+        };
+        writeServerRootState(this.rootDir(), promoted);
+        this.pruneVersions([
+          promoted.currentVersion,
+          promoted.previousVersion
+        ].filter((v) => typeof v === "string"));
+        this.logger.info("root package update confirmed healthy", {
+          meta: {
+            version: promoted.currentVersion,
+            previousVersion: promoted.previousVersion
+          }
+        });
+        return {
+          promoted: promoted.currentVersion
+        };
+      }
+      /**
+      * Remove version dirs under `versions/` not in `keep`.
+      *
+      * Transient dot-entries (`.staging-*` / `.evicted-*`) are NOT pruned unless
+      * older than {@link RootUpdateService.STALE_TRANSIENT_MS}: the API starts
+      * serving BEFORE the post-boot `confirmBootHealthy()` runs, so a concurrent
+      * `applyServerUpdate` can be mid-npm-install into a fresh `.staging-*` dir
+      * when this prune fires — deleting it would corrupt that install. Fresh
+      * transient dirs are owned by their in-flight operation (which cleans up on
+      * failure); the staleness sweep only collects dirs orphaned by a crash.
+      */
+      pruneVersions(keep) {
+        const vDir = versionsDir(this.rootDir());
+        let entries;
+        try {
+          entries = fs3.readdirSync(vDir);
+        } catch {
+          return;
+        }
+        for (const entry of entries) {
+          if (keep.includes(entry)) continue;
+          const full = path4.join(vDir, entry);
+          if (entry.startsWith(".")) {
+            try {
+              const ageMs = this.now() - fs3.statSync(full).mtimeMs;
+              if (ageMs < _RootUpdateService.STALE_TRANSIENT_MS) continue;
+            } catch {
+              continue;
+            }
+          }
+          try {
+            fs3.rmSync(full, {
+              recursive: true,
+              force: true
+            });
+            this.logger.debug("pruned server-root version dir", {
+              meta: {
+                entry
+              }
+            });
+          } catch (err) {
+            this.logger.warn("failed to prune server-root version dir", {
+              meta: {
+                entry,
+                error: err instanceof Error ? err.message : String(err)
+              }
+            });
+          }
+        }
+      }
+      /** Transient (.staging- / .evicted-) dirs younger than this are never pruned. */
+      static STALE_TRANSIENT_MS = 24 * 60 * 60 * 1e3;
+    };
+  }
+});
+
+// src/server-root/index.ts
+var server_root_exports = {};
+__export(server_root_exports, {
+  SERVER_ROOT_PACKAGE_NAME: () => SERVER_ROOT_PACKAGE_NAME,
+  serverEntryPath: () => serverEntryPath,
+  serverPackageDir: () => serverPackageDir
+});
+module.exports = __toCommonJS(server_root_exports);
+var import_node_root = __toESM(require_dist());
+__reExport(server_root_exports, __toESM(require_dist()), module.exports);
+var SERVER_ROOT_PACKAGE_NAME = import_node_root.HUB_ROOT_SPEC.packageName;
+function serverPackageDir(versionDirPath) {
+  return (0, import_node_root.rootPackageDir)(versionDirPath, import_node_root.HUB_ROOT_SPEC);
+}
+__name(serverPackageDir, "serverPackageDir");
+function serverEntryPath(versionDirPath) {
+  return (0, import_node_root.rootEntryPath)(versionDirPath, import_node_root.HUB_ROOT_SPEC);
+}
+__name(serverEntryPath, "serverEntryPath");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  SERVER_ROOT_PACKAGE_NAME,
+  serverEntryPath,
+  serverPackageDir
+});