@camstack/server 1.2.88 → 1.2.90

package/dist/main.js

@@ -39,7 +39,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 /* eslint-disable @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-argument -- pre-existing lint debt across this 800+ line bootstrap module. The flagged sites cross typed boundaries (Fastify request typing, AddonRouteRegistry, AuthService inherited methods) where the projectService context can't trace inheritance chains. Tracked separately; do not amend in unrelated edits. */
 const fastify_1 = require("@trpc/server/adapters/fastify");
 const ws_1 = require("@trpc/server/adapters/ws");
-const static_1 = __importDefault(require("@fastify/static"));
 const compress_1 = __importDefault(require("@fastify/compress"));
 const cookie_1 = __importDefault(require("@fastify/cookie"));
 const sse_no_compression_js_1 = require("./api/sse-no-compression.js");
@@ -879,6 +878,9 @@ async function bootstrap() {
             }
             const match = addonRouteRegistry.matchRoute(method, fullPath);
             if (!match) {
+                if ((0, spa_static_1.isRetiredPublicPath)(fullPath)) {
+                    return reply.status(404).send({ error: 'Not found' });
+                }
                 if (method === 'GET' && spaIndexHtml) {
                     return reply.type('text/html').send(fs.createReadStream(spaIndexHtml));
                 }
@@ -1074,216 +1076,168 @@ async function bootstrap() {
         await addonRegistry.setAppRouter(appRouter);
         console.log('[bootstrap] AddonRegistry wired with tRPC direct caller');
     }
-    // ScopedTokenManager and admin user creation handled by local-auth addon.
-    // Serve admin UI static files from the admin-ui singleton capability.
-    // Always enabled — in dev mode Vite runs on its own port and doesn't interfere.
-    //
-    // The admin-ui addon runs in its own dedicated runner subprocess and
-    // finishes registering 1-3s after bootstrap; poll briefly for it
-    // before giving up to avoid the 'admin-ui capability not registered —
-    // no static file serving' warn that left the SPA unserved until next
-    // restart.
-    try {
-        const bootAddonRegistry = app.get(addon_registry_service_1.AddonRegistryService);
-        const capRegistry = bootAddonRegistry.getCapabilityRegistry();
-        // HUB-NODE-SCOPED resolution — never the cluster-global singleton.
-        // Agent nodes register the same `admin-ui` cap through their own
-        // agent-ui addon (placement: agent-only), and the cluster-elected
-        // active provider can land on the AGENT's registration depending on
-        // node boot order. Its `getStaticDir()` then answers with a path on
-        // the agent's filesystem — nonexistent here — and the SPA catch-all
-        // silently never registers (every `GET /` 404s until the next
-        // restart re-rolls the election). `getSingletonForNode(cap, 'hub')`
-        // only ever resolves providers hosted on THIS node.
-        let adminUI = capRegistry?.getSingletonForNode('admin-ui', 'hub');
-        // CAMSTACK_SKIP_ADMIN_UI_WAIT — bypass the 60s poll. Used by the
-        // e2e harness, which doesn't need the SPA served and spawns hubs
-        // with strict boot timeouts. Production keeps the poll so cold
-        // boots wait for the forked admin-ui group to register.
-        const skipAdminUIWait = process.env['CAMSTACK_SKIP_ADMIN_UI_WAIT'] === '1';
-        if (!adminUI && capRegistry && !skipAdminUIWait) {
-            // Forked-addon spawn + Moleculer registration + tRPC hydration
-            // can take ~15-20s on cold boot, especially when several runners
-            // are spawning in parallel. The previous 10s window was racing
-            // the admin-ui runner's boot — fastify-static didn't register and
-            // every `GET /` returned 404. Bump to 60s; we only pay this
-            // wait once at boot.
-            const ADMIN_UI_WAIT_MS = 60_000;
-            const POLL_MS = 200;
-            const deadline = Date.now() + ADMIN_UI_WAIT_MS;
-            while (!adminUI && Date.now() < deadline) {
-                await new Promise((r) => setTimeout(r, POLL_MS));
-                adminUI = capRegistry.getSingletonForNode('admin-ui', 'hub');
+    const adminUiState = { staticDir: null, indexPath: null };
+    const viewerUiState = { staticDir: null, indexPath: null };
+    const VIEWER_MOUNT = '/viewer/camstack';
+    // Register UI routes before Fastify starts, but resolve their forked
+    // providers after listen. During a cold boot the control plane is therefore
+    // immediately reachable while the non-critical UI runners finish starting.
+    fastify.get('/viewer', async (_request, reply) => reply.redirect(`${VIEWER_MOUNT}/`));
+    fastify.get('/viewer/', async (_request, reply) => reply.redirect(`${VIEWER_MOUNT}/`));
+    fastify.get('/webrtc-test.html', async (_request, reply) => {
+        const webrtcTestPath = path.join(dataPath, 'webrtc-test.html');
+        if (!fs.existsSync(webrtcTestPath))
+            return reply.callNotFound();
+        return reply.type('text/html').send(fs.createReadStream(webrtcTestPath));
+    });
+    fastify.get('/viewer/*', async (request, reply) => {
+        const { staticDir, indexPath } = viewerUiState;
+        if (!staticDir || !indexPath) {
+            return reply.status(503).send({ error: 'Viewer UI is starting' });
+        }
+        const pathOnly = request.url.split('?')[0] ?? request.url;
+        let rel = '';
+        if (pathOnly.startsWith(`${VIEWER_MOUNT}/`)) {
+            rel = pathOnly.slice(VIEWER_MOUNT.length + 1);
+        }
+        if (rel && /\.[a-zA-Z0-9]+$/.test(pathOnly)) {
+            const abs = path.join(staticDir, rel);
+            if ((abs === staticDir || abs.startsWith(staticDir + path.sep)) && fs.existsSync(abs)) {
+                reply.header('cache-control', (0, spa_static_1.spaAssetCacheControl)(rel));
+                reply.type((0, spa_static_1.contentTypeForPath)(rel));
+                return sendMaybePrecompressed(reply, abs, request.headers['accept-encoding']);
             }
+            return reply.callNotFound();
         }
-        if (adminUI) {
-            const { staticDir } = await adminUI.getStaticDir();
-            const indexPath = path.join(staticDir, 'index.html');
-            if (fs.existsSync(staticDir) && fs.existsSync(indexPath)) {
-                spaIndexHtml = indexPath;
-                // `serve: false` registers no route — it only decorates
-                // `reply.sendFile`, so the single SPA `/*` handler below owns all
-                // routing and serves each asset LIVE from the current `staticDir`.
-                // The old `wildcard: false` registered one route per file enumerated
-                // AT BOOT, so a redeployed admin-ui's new content-hashed assets had no
-                // route and 404'd until a hub restart. Live `sendFile` removes that.
-                await fastify.register(static_1.default, {
-                    root: staticDir,
-                    serve: false,
-                    decorateReply: true,
-                    // Disable @fastify/static's automatic Cache-Control injection so
-                    // the per-file headers set by the route handler (immutable for
-                    // hashed assets, no-cache for index.html / SW) survive sendFile().
-                    cacheControl: false,
-                });
-                // Dev diagnostic: serve webrtc-test.html from dataPath if it exists.
-                const webrtcTestPath = path.join(dataPath, 'webrtc-test.html');
-                if (fs.existsSync(webrtcTestPath)) {
-                    fastify.get('/webrtc-test.html', async (_request, reply) => {
-                        return reply.type('text/html').send(fs.createReadStream(webrtcTestPath));
-                    });
+        reply.header('cache-control', 'no-cache, must-revalidate');
+        return reply.type('text/html').send(fs.createReadStream(indexPath));
+    });
+    fastify.get('/*', async (request, reply) => {
+        const url = request.url;
+        if ((0, spa_static_1.isRetiredPublicPath)(url))
+            return reply.callNotFound();
+        if (url.startsWith('/trpc') ||
+            url.startsWith('/api/') ||
+            url.startsWith('/agent') ||
+            url.startsWith('/health') ||
+            url.startsWith('/viewer')) {
+            return reply.callNotFound();
+        }
+        const { staticDir, indexPath } = adminUiState;
+        if (!staticDir || !indexPath) {
+            return reply.status(503).send({ error: 'Admin UI is starting' });
+        }
+        const pathOnly = url.split('?')[0] ?? url;
+        if (/\.[a-zA-Z0-9]+$/.test(pathOnly)) {
+            const rel = pathOnly.replace(/^\/+/, '');
+            const abs = path.join(staticDir, rel);
+            if ((abs === staticDir || abs.startsWith(staticDir + path.sep)) && fs.existsSync(abs)) {
+                reply.header('cache-control', (0, spa_static_1.spaAssetCacheControl)(rel));
+                return sendMaybePrecompressed(reply, abs, request.headers['accept-encoding']);
+            }
+            return reply.callNotFound();
+        }
+        reply.header('cache-control', 'no-cache, must-revalidate');
+        return reply.type('text/html').send(fs.createReadStream(indexPath));
+    });
+    const resolveAdminUi = async () => {
+        try {
+            const bootAddonRegistry = app.get(addon_registry_service_1.AddonRegistryService);
+            const capRegistry = bootAddonRegistry.getCapabilityRegistry();
+            // HUB-NODE-SCOPED resolution — never the cluster-global singleton.
+            // Agent nodes register the same `admin-ui` cap through their own
+            // agent-ui addon (placement: agent-only), and the cluster-elected
+            // active provider can land on the AGENT's registration depending on
+            // node boot order. Its `getStaticDir()` then answers with a path on
+            // the agent's filesystem — nonexistent here — and the SPA catch-all
+            // silently never registers (every `GET /` 404s until the next
+            // restart re-rolls the election). `getSingletonForNode(cap, 'hub')`
+            // only ever resolves providers hosted on THIS node.
+            let adminUI = capRegistry?.getSingletonForNode('admin-ui', 'hub');
+            // CAMSTACK_SKIP_ADMIN_UI_WAIT bypasses the background capability poll in
+            // e2e runs that do not need the SPA.
+            const skipAdminUIWait = process.env['CAMSTACK_SKIP_ADMIN_UI_WAIT'] === '1';
+            if (!adminUI && capRegistry && !skipAdminUIWait) {
+                // Forked-addon spawn + Moleculer registration + tRPC hydration
+                // can take ~15-20s on cold boot, especially when several runners
+                // are spawning in parallel. The previous 10s window was racing
+                // the admin-ui runner's boot — fastify-static didn't register and
+                // every `GET /` returned 404. Bump to 60s; we only pay this
+                // wait once at boot.
+                const ADMIN_UI_WAIT_MS = 60_000;
+                const POLL_MS = 200;
+                const deadline = Date.now() + ADMIN_UI_WAIT_MS;
+                while (!adminUI && Date.now() < deadline) {
+                    await new Promise((r) => setTimeout(r, POLL_MS));
+                    adminUI = capRegistry.getSingletonForNode('admin-ui', 'hub');
+                }
+            }
+            if (adminUI) {
+                const { staticDir } = await adminUI.getStaticDir();
+                const indexPath = path.join(staticDir, 'index.html');
+                if (fs.existsSync(staticDir) && fs.existsSync(indexPath)) {
+                    spaIndexHtml = indexPath;
+                    adminUiState.staticDir = staticDir;
+                    adminUiState.indexPath = indexPath;
+                    (0, precompressed_asset_js_1.warmPrecompressedAssets)(staticDir, (msg, meta) => console.log(`[static] ${msg} ${JSON.stringify(meta)}`));
+                    const { version } = await adminUI.getVersion();
+                    console.log(`[bootstrap] Admin UI served from: ${staticDir} (v${version})`);
+                }
+                else {
+                    console.warn(`[bootstrap] Admin UI dist not found at: ${staticDir} — run 'npm run build' in addon-admin-ui`);
                 }
-                // SPA fallback + live static serving: this single catch-all owns every
-                // GET. Core API prefixes fall through to their own routers via
-                // `callNotFound`. Uses a wildcard route instead of setNotFoundHandler.
-                fastify.get('/*', async (request, reply) => {
-                    const url = request.url;
-                    if (url.startsWith('/trpc') ||
-                        url.startsWith('/api/') ||
-                        url.startsWith('/agent') ||
-                        url.startsWith('/health') ||
-                        // The viewer SPA owns /viewer/** via its own catch-all (registered
-                        // below). Fall through here so admin-ui never serves it — and so
-                        // /viewer 404s cleanly when the viewer-ui addon isn't registered.
-                        url.startsWith('/viewer')) {
-                        return reply.callNotFound();
-                    }
-                    // A request whose last path segment has a file extension is a static
-                    // asset: serve it LIVE from the current dist so a redeployed
-                    // admin-ui's new content-hashed files are picked up without a hub
-                    // restart. When the file is missing, 404 — never the SPA
-                    // `index.html`: serving HTML under a `.js`/`.css` URL makes upstream
-                    // caches (Cloudflare, the browser) pin `text/html`, which then fails
-                    // the module MIME check long after the file is actually available.
-                    const pathOnly = url.split('?')[0] ?? url;
-                    if (/\.[a-zA-Z0-9]+$/.test(pathOnly)) {
-                        const rel = pathOnly.replace(/^\/+/, '');
-                        const abs = path.join(staticDir, rel);
-                        if ((abs === staticDir || abs.startsWith(staticDir + path.sep)) && fs.existsSync(abs)) {
-                            // Cache policy that lets PWA updates actually propagate (the
-                            // stale-bundle bug): the service worker + registration + manifest
-                            // MUST be revalidated every load or a redeploy never reaches the
-                            // client (the SW keeps serving the old precache). Content-hashed
-                            // build assets (assets/index-<hash>.js) are immutable. Everything
-                            // else gets a short cache.
-                            reply.header('cache-control', (0, spa_static_1.spaAssetCacheControl)(rel));
-                            return sendMaybePrecompressed(reply, abs, request.headers['accept-encoding']);
-                        }
-                        return reply.callNotFound();
-                    }
-                    // index.html (the SPA shell) must never be cached — it references the
-                    // content-hashed bundles, so a stale copy pins the old app forever.
-                    reply.header('cache-control', 'no-cache, must-revalidate');
-                    return reply.type('text/html').send(fs.createReadStream(spaIndexHtml));
-                });
-                // Compress the dist in the background so the first CLIENT does not pay
-                // for it — a 5 MB bundle takes ~6.7s at quality 11, and that is a worse
-                // first load than the per-request compression this replaced.
-                (0, precompressed_asset_js_1.warmPrecompressedAssets)(staticDir, (msg, meta) => console.log(`[static] ${msg} ${JSON.stringify(meta)}`));
-                const { version } = await adminUI.getVersion();
-                console.log(`[bootstrap] Admin UI served from: ${staticDir} (v${version})`);
             }
             else {
-                console.warn(`[bootstrap] Admin UI dist not found at: ${staticDir} — run 'npm run build' in addon-admin-ui`);
+                console.warn('[bootstrap] admin-ui capability not registered — no static file serving');
             }
         }
-        else {
-            console.warn('[bootstrap] admin-ui capability not registered — no static file serving');
+        catch (err) {
+            console.error('[bootstrap] Failed to set up admin UI static serving:', err);
         }
-    }
-    catch (err) {
-        console.error('[bootstrap] Failed to set up admin UI static serving:', err);
-    }
-    // Serve the CamStack viewer SPA from the viewer-ui singleton capability.
-    // The viewer is built (Expo web export) with EXPO_PUBLIC_WEB_BASE_PATH=/viewer,
-    // so its baseUrl — and therefore every asset URL — is /viewer/camstack/**. We
-    // mount it at exactly that prefix and redirect /viewer → the SPA root. Mirrors
-    // the admin-ui poll+serve, but streams assets directly from its own dist root
-    // so it stays independent of the admin-ui @fastify/static decorator.
-    try {
-        const bootAddonRegistry = app.get(addon_registry_service_1.AddonRegistryService);
-        const capRegistry = bootAddonRegistry.getCapabilityRegistry();
-        // Hub-node-scoped for the same reason as admin-ui above: a remote
-        // node's registration must never win the election for the provider
-        // whose staticDir this process reads from local disk.
-        let viewerUI = capRegistry?.getSingletonForNode('viewer-ui', 'hub');
-        const skipViewerUIWait = process.env['CAMSTACK_SKIP_VIEWER_UI_WAIT'] === '1';
-        if (!viewerUI && capRegistry && !skipViewerUIWait) {
-            // The viewer-ui addon runs in its own forked runner and registers a few
-            // seconds after boot. Poll briefly (shorter than admin-ui's 60s — the
-            // viewer is non-critical and admin-ui already gated the slow cold boot).
-            const VIEWER_UI_WAIT_MS = 30_000;
-            const POLL_MS = 200;
-            const deadline = Date.now() + VIEWER_UI_WAIT_MS;
-            while (!viewerUI && Date.now() < deadline) {
-                await new Promise((r) => setTimeout(r, POLL_MS));
-                viewerUI = capRegistry.getSingletonForNode('viewer-ui', 'hub');
+    };
+    const resolveViewerUi = async () => {
+        try {
+            const bootAddonRegistry = app.get(addon_registry_service_1.AddonRegistryService);
+            const capRegistry = bootAddonRegistry.getCapabilityRegistry();
+            // Hub-node-scoped for the same reason as admin-ui above: a remote
+            // node's registration must never win the election for the provider
+            // whose staticDir this process reads from local disk.
+            let viewerUI = capRegistry?.getSingletonForNode('viewer-ui', 'hub');
+            const skipViewerUIWait = process.env['CAMSTACK_SKIP_VIEWER_UI_WAIT'] === '1';
+            if (!viewerUI && capRegistry && !skipViewerUIWait) {
+                // The viewer-ui addon runs in its own forked runner and registers a few
+                // seconds after boot. Poll briefly (shorter than admin-ui's 60s — the
+                // viewer is non-critical and admin-ui already gated the slow cold boot).
+                const VIEWER_UI_WAIT_MS = 30_000;
+                const POLL_MS = 200;
+                const deadline = Date.now() + VIEWER_UI_WAIT_MS;
+                while (!viewerUI && Date.now() < deadline) {
+                    await new Promise((r) => setTimeout(r, POLL_MS));
+                    viewerUI = capRegistry.getSingletonForNode('viewer-ui', 'hub');
+                }
             }
-        }
-        if (viewerUI) {
-            const { staticDir } = await viewerUI.getStaticDir();
-            const indexPath = path.join(staticDir, 'index.html');
-            if (fs.existsSync(staticDir) && fs.existsSync(indexPath)) {
-                // The Expo baseUrl (`${webBasePath}/camstack`) is the on-hub mount.
-                const VIEWER_MOUNT = '/viewer/camstack';
-                // Clean entry point: /viewer and /viewer/ → the SPA root.
-                fastify.get('/viewer', async (_request, reply) => reply.redirect(`${VIEWER_MOUNT}/`));
-                fastify.get('/viewer/', async (_request, reply) => reply.redirect(`${VIEWER_MOUNT}/`));
-                // Single catch-all owns every GET under /viewer/**: assets stream LIVE
-                // from the current dist; everything else is the SPA shell.
-                fastify.get('/viewer/*', async (request, reply) => {
-                    const pathOnly = request.url.split('?')[0] ?? request.url;
-                    // Map the request path to a dist-relative path by stripping the mount
-                    // prefix. Anything not under the mount is treated as the SPA shell.
-                    let rel = '';
-                    if (pathOnly === VIEWER_MOUNT || pathOnly === `${VIEWER_MOUNT}/`) {
-                        rel = '';
-                    }
-                    else if (pathOnly.startsWith(`${VIEWER_MOUNT}/`)) {
-                        rel = pathOnly.slice(VIEWER_MOUNT.length + 1);
-                    }
-                    // A path whose last segment has a file extension is a static asset:
-                    // serve it, or 404 — NEVER the SPA shell (serving HTML under a
-                    // .js/.css URL pins text/html in caches and breaks the module MIME
-                    // check long after the file is actually available).
-                    if (rel && /\.[a-zA-Z0-9]+$/.test(pathOnly)) {
-                        const abs = path.join(staticDir, rel);
-                        if ((abs === staticDir || abs.startsWith(staticDir + path.sep)) && fs.existsSync(abs)) {
-                            reply.header('cache-control', (0, spa_static_1.spaAssetCacheControl)(rel));
-                            reply.type((0, spa_static_1.contentTypeForPath)(rel));
-                            return sendMaybePrecompressed(reply, abs, request.headers['accept-encoding']);
-                        }
-                        return reply.callNotFound();
-                    }
-                    // SPA shell — never cached (it references content-hashed bundles).
-                    reply.header('cache-control', 'no-cache, must-revalidate');
-                    return reply.type('text/html').send(fs.createReadStream(indexPath));
-                });
-                (0, precompressed_asset_js_1.warmPrecompressedAssets)(staticDir, (msg, meta) => console.log(`[static] ${msg} ${JSON.stringify(meta)}`));
-                const { version } = await viewerUI.getVersion();
-                console.log(`[bootstrap] Viewer UI served from: ${staticDir} at ${VIEWER_MOUNT} (v${version})`);
+            if (viewerUI) {
+                const { staticDir } = await viewerUI.getStaticDir();
+                const indexPath = path.join(staticDir, 'index.html');
+                if (fs.existsSync(staticDir) && fs.existsSync(indexPath)) {
+                    viewerUiState.staticDir = staticDir;
+                    viewerUiState.indexPath = indexPath;
+                    (0, precompressed_asset_js_1.warmPrecompressedAssets)(staticDir, (msg, meta) => console.log(`[static] ${msg} ${JSON.stringify(meta)}`));
+                    const { version } = await viewerUI.getVersion();
+                    console.log(`[bootstrap] Viewer UI served from: ${staticDir} at ${VIEWER_MOUNT} (v${version})`);
+                }
+                else {
+                    console.warn(`[bootstrap] Viewer UI dist not found at: ${staticDir} — run 'npm run build' in addon-viewer-ui`);
+                }
             }
             else {
-                console.warn(`[bootstrap] Viewer UI dist not found at: ${staticDir} — run 'npm run build' in addon-viewer-ui`);
+                console.warn('[bootstrap] viewer-ui capability not registered — viewer not served');
             }
         }
-        else {
-            console.warn('[bootstrap] viewer-ui capability not registered — viewer not served');
+        catch (err) {
+            console.error('[bootstrap] Failed to set up viewer UI static serving:', err);
         }
-    }
-    catch (err) {
-        console.error('[bootstrap] Failed to set up viewer UI static serving:', err);
-    }
+    };
     try {
         await app.listen(port, host);
     }
@@ -1300,6 +1254,9 @@ async function bootstrap() {
     const logger = app.get(logging_service_1.LoggingService).createLogger('System');
     const protocol = tlsOptions ? 'https' : 'http';
     logger.info('CamStack server listening', { meta: { protocol, host, port, trpcRegistered } });
+    // UI runners are not part of control-plane readiness. Their mutable route
+    // state switches from 503 to static serving as soon as each capability is up.
+    void Promise.all([resolveAdminUi(), resolveViewerUi()]);
     // Post-boot: fork workers, register device streams, emit system.boot
     const postBoot = app.get(post_boot_service_1.PostBootService);
     await postBoot.run({ port, host, dataPath, trpcRegistered });

package/dist/manual-boot.js

@@ -220,6 +220,7 @@ async function bootManual(opts) {
     const serverUpdateService = new server_update_service_1.ServerUpdateService({
         logger: loggingService.createLogger('ServerUpdate'),
         restartServer: (requestedBy) => addonPackageService.restartServer(requestedBy),
+        eventBus: eventBusService,
     });
     const topologyEmitterService = new topology_emitter_service_1.TopologyEmitterService(eventBusService, agentRegistryService, addonRegistryService, (0, cap_providers_1.createNodeRootPackageLookup)(moleculerService, serverUpdateService));
     const postBootService = new post_boot_service_1.PostBootService(addonRegistryService, eventBusService, loggingService);

package/dist/request-framework-swap.js

@@ -0,0 +1,41 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.requestFrameworkSwapAndRestart = requestFrameworkSwapAndRestart;
+/**
+ * The single seam that joins the two halves of a framework-swap request:
+ *   1. write the durable `.pending-framework-swap.json` marker (consumed by the
+ *      zero-dep launcher on the NEXT boot), and
+ *   2. schedule the self-restart that makes the launcher actually run.
+ *
+ * The launcher (`launcher-framework-swap.ts`) runs before `@camstack/system`
+ * is imported and is deliberately zero-dep, so it cannot own the restart — that
+ * lives in `@camstack/system`. This module is the ONLY owner of "stage a
+ * framework swap → reboot": every engine path that stages the framework (single
+ * `updateFrameworkPackage`, the "Update all" bulk job, and the auto-update
+ * scheduler) wires its `requestFrameworkSwap` dep to this helper and gets the
+ * reboot for free. The lifecycle engine assumes the process exits after
+ * `requestFrameworkSwap` returns; without the restart here the marker is written
+ * but never applied, silently stranding the update on disk.
+ */
+const system_1 = require("@camstack/system");
+const launcher_framework_swap_js_1 = require("./launcher-framework-swap.js");
+/** Delay before the hub exits — lets the in-flight startJob reply drain first. */
+const FRAMEWORK_SWAP_RESTART_DELAY_MS = 500;
+/**
+ * Write the pending-swap marker, then schedule the self-restart. The restart is
+ * UNCONDITIONAL: a staged framework swap is inert until the launcher applies it
+ * on reboot, so staging without restarting would silently lose the update.
+ */
+function requestFrameworkSwapAndRestart(dataDir, input, deps = {}) {
+    const writeMarker = deps.writeMarker ?? launcher_framework_swap_js_1.writePendingFrameworkSwap;
+    const scheduleRestart = deps.scheduleRestart ?? system_1.scheduleSelfRestart;
+    const now = deps.now ?? Date.now;
+    writeMarker(dataDir, {
+        jobId: input.jobId,
+        taskId: input.taskId,
+        packages: input.packages,
+        requestedAtMs: now(),
+        schemaVersion: 1,
+    });
+    scheduleRestart({ delayMs: FRAMEWORK_SWAP_RESTART_DELAY_MS });
+}

package/dist/server-root/boot-plan.js

@@ -0,0 +1,110 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.planBoot = planBoot;
+/**
+ * Decide the boot target. Never throws; never mutates `state`.
+ * `stateToWrite` is non-null whenever the durable state must change
+ * (probation counter bump, rollback, invalid-version eviction).
+ */
+function planBoot(state, isValidVersion, now) {
+    if (state === null) {
+        return { kind: 'baked', reason: 'no server-root state', stateToWrite: null };
+    }
+    let next = state;
+    let changed = false;
+    // ── Pending (freshly-staged) version ──────────────────────────────────
+    if (next.pendingBoot !== null) {
+        const pending = next.pendingBoot;
+        if (pending.bootAttempts >= 1) {
+            // Previous probation boot never confirmed healthy — roll back.
+            next = {
+                ...next,
+                pendingBoot: null,
+                rolledBack: {
+                    fromVersion: pending.version,
+                    toVersion: next.currentVersion,
+                    atMs: now(),
+                    reason: 'probation boot did not reach ready — 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 {
+            // Probation boot: bump the attempt counter durably, keep currentVersion
+            // untouched until the hub confirms the boot healthy.
+            return {
+                kind: 'data-root',
+                version: pending.version,
+                probation: true,
+                stateToWrite: {
+                    ...next,
+                    pendingBoot: { ...pending, bootAttempts: pending.bootAttempts + 1 },
+                },
+            };
+        }
+    }
+    // ── Confirmed current version ──────────────────────────────────────────
+    if (next.currentVersion !== null) {
+        if (isValidVersion(next.currentVersion)) {
+            return {
+                kind: 'data-root',
+                version: next.currentVersion,
+                probation: false,
+                stateToWrite: changed ? next : null,
+            };
+        }
+        // Current version dir is broken — try N-1, else baked.
+        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,
+    };
+}

package/dist/server-root/semver-compare.js

@@ -0,0 +1,45 @@
+"use strict";
+/**
+ * Minimal semver comparison — zero-dep (used by the starter, which must never
+ * import from node_modules). Handles `MAJOR.MINOR.PATCH[-prerelease]`:
+ * numeric segment compare, missing segments = 0, prerelease < its release,
+ * prereleases of the same base compare lexically. Malformed segments compare
+ * as 0 (best effort — never throws).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compareSemver = compareSemver;
+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 };
+}
+/** Returns -1 when a < b, 0 when equal, 1 when a > b. */
+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;
+}