@timurproko/a1 0.1.8-dev.de7821a → 0.2.0

package/dist/foundation/release/restart-certification.js

@@ -0,0 +1,227 @@
+import { createHash } from "node:crypto";
+import { lstat, readFile, realpath, stat } from "node:fs/promises";
+import { basename, isAbsolute, relative, resolve, sep } from "node:path";
+import { PRODUCT_IDENTITY } from "../../product-identity.js";
+import { PRIVATE_LAUNCH_CONTRACT, launchContractTarget } from "../launch-context/index.js";
+import { DEPENDENCY_LAYER_MANIFEST, dependencyLayerCertificationPath, legacyDependencyLayerCertificationPath, readCertifiedDependencyLayer } from "./dependency-layer.js";
+import { managedDependencyCertificationPath } from "./dependency-certification.js";
+import { immutablePlatformPolicy } from "./immutable-platform.js";
+import { PRODUCT_PACKAGE_NAME } from "./release.js";
+import { RELEASE_MANIFEST_FILENAME } from "./release-store.js";
+import { UpdateTransactionStore } from "./update-transaction.js";
+const RESTART_SEAL_VERSION = 1;
+const REQUIRED_LAUNCH_ENTRIES = ["bin/supervisor.js", "bin/guardian.js"];
+/** Build compact restart authority after complete content verification established read-only payload files. */
+export async function createRestartSeal(release, dataDir) {
+    const policy = immutablePlatformPolicy();
+    if (policy === null)
+        return null;
+    const canonicalData = await realpath(dataDir);
+    const releasesRoot = await realpath(resolve(canonicalData, "releases"));
+    const releaseRoot = await realpath(release.releaseRoot);
+    assertDirectChild(releasesRoot, releaseRoot, release.releaseId, "release");
+    const manifestPath = resolve(releaseRoot, RELEASE_MANIFEST_FILENAME);
+    const launchEntries = REQUIRED_LAUNCH_ENTRIES.map(path => release.files.find(candidate => candidate.path === path));
+    if (launchEntries.some(file => file === undefined))
+        return null;
+    const certifiedLaunchEntries = launchEntries;
+    const layersRoot = release.dependencyLayers?.length ? await realpath(resolve(canonicalData, "dependency-layers")) : null;
+    const dependencyLayers = await Promise.all((release.dependencyLayers ?? []).map(async (reference) => {
+        if (layersRoot === null)
+            throw new Error("restart certification has no dependency-layer root");
+        await readCertifiedDependencyLayer(canonicalData, reference.layerId, reference);
+        const layerRoot = await realpath(resolve(layersRoot, reference.layerId));
+        assertDirectChild(layersRoot, layerRoot, reference.layerId, "dependency layer");
+        const bindingPath = resolve(releaseRoot, reference.binding);
+        const bindingTarget = await realpath(bindingPath);
+        const expectedTarget = await realpath(resolve(layerRoot, "node_modules"));
+        if (bindingTarget !== expectedTarget)
+            throw new Error(`restart certification dependency binding targets unexpected content: ${bindingPath}`);
+        return {
+            ...reference,
+            layerRoot: await pathEvidence(layerRoot, "directory"),
+            manifest: await pathEvidence(resolve(layerRoot, DEPENDENCY_LAYER_MANIFEST), "file"),
+            certification: await pathEvidence(dependencyLayerCertificationPath(canonicalData, reference.layerId), "file"),
+            bindingEvidence: await pathEvidence(bindingPath, "binding", true),
+            bindingTarget,
+        };
+    }));
+    const core = {
+        version: RESTART_SEAL_VERSION,
+        launchContract: launchContractTarget(release),
+        platform: process.platform,
+        platformPolicy: policy,
+        releaseId: release.releaseId,
+        packageVersion: release.packageVersion,
+        contentDigest: release.contentDigest,
+        packageRoot: release.packageRoot,
+        releaseRoot: await pathEvidence(releaseRoot, "directory"),
+        manifest: await pathEvidence(manifestPath, "file"),
+        launchEntries: certifiedLaunchEntries,
+        launchEntryEvidence: await Promise.all(certifiedLaunchEntries.map(file => pathEvidence(resolve(releaseRoot, file.path), "file"))),
+        dependencyLayers,
+        certifiedAt: new Date().toISOString(),
+    };
+    return { ...core, sealDigest: restartSealDigest(core) };
+}
+/** Recover an approved release from durable bounded evidence without traversing its payload. */
+export async function readRestartCertifiedRelease(record, dataDir, onEvent) {
+    const transaction = await new UpdateTransactionStore(dataDir).read();
+    if (transaction?.status === "active")
+        throw new Error("restart certification is unavailable during an active update transaction");
+    const certificationPath = resolve(dataDir, `certification-${record.releaseId}.json`);
+    if (record.diagnosticsPath !== undefined && record.diagnosticsPath !== certificationPath) {
+        throw new Error("restart certification path differs from the approved release record");
+    }
+    const certificationMetadata = await lstat(certificationPath);
+    onEvent?.({ operation: "restart-evidence-read", path: certificationPath });
+    if (!certificationMetadata.isFile() || certificationMetadata.isSymbolicLink() || (certificationMetadata.mode & 0o222) !== 0) {
+        throw new Error("restart certification is not an immutable regular file");
+    }
+    const certification = await readJson(certificationPath, onEvent);
+    if (certification.schema !== PRODUCT_IDENTITY.evidence.releaseCertificationSchema
+        || certification.releaseId !== record.releaseId || certification.contentDigest !== record.contentDigest
+        || !certification.checks.some(check => check.id === "immutable-content" && check.passed)) {
+        throw new Error("restart certification differs from the approved release record");
+    }
+    const seal = normalizeRestartSeal(certification.restartSeal);
+    // Invariant: a seal is restart authority only for a handoff this build can still
+    // perform, which is the contract it emits or the pre-cutover one it retains.
+    if (seal.launchContract !== PRIVATE_LAUNCH_CONTRACT && seal.launchContract !== "superseded") {
+        throw new Error(`restart seal declares an unsupported launch contract: ${String(seal.launchContract)}`);
+    }
+    if (seal.platform !== process.platform || seal.platformPolicy !== immutablePlatformPolicy()) {
+        throw new Error("restart certification platform immutability evidence is unsupported");
+    }
+    if (seal.releaseId !== record.releaseId || seal.contentDigest !== record.contentDigest
+        || resolve(seal.releaseRoot.path) !== resolve(record.releaseRoot)
+        || (record.packageVersion !== undefined && seal.packageVersion !== record.packageVersion)) {
+        throw new Error("restart seal differs from the approved release identity");
+    }
+    const { sealDigest, ...core } = seal;
+    if (restartSealDigest(core) !== sealDigest)
+        throw new Error("restart seal digest is invalid");
+    const canonicalData = await observedRealpath(dataDir, onEvent);
+    const releasesRoot = await observedRealpath(resolve(canonicalData, "releases"), onEvent);
+    const releaseRoot = await observedRealpath(seal.releaseRoot.path, onEvent);
+    assertDirectChild(releasesRoot, releaseRoot, seal.releaseId, "release");
+    await assertPathEvidence(seal.releaseRoot, onEvent);
+    await assertPathEvidence(seal.manifest, onEvent);
+    for (let index = 0; index < seal.launchEntries.length; index += 1) {
+        const file = seal.launchEntries[index];
+        if (!REQUIRED_LAUNCH_ENTRIES.includes(file.path)) {
+            throw new Error(`restart seal contains an unexpected launch entry: ${file.path}`);
+        }
+        const evidence = seal.launchEntryEvidence[index];
+        if (!evidence || evidence.path !== resolve(releaseRoot, file.path) || file.bytes !== Number(evidence.size)) {
+            throw new Error(`restart launch entry evidence differs: ${file.path}`);
+        }
+        await assertPathEvidence(evidence, onEvent);
+    }
+    if (seal.launchEntries.length !== REQUIRED_LAUNCH_ENTRIES.length)
+        throw new Error("restart seal launch entries are incomplete");
+    const layersRoot = seal.dependencyLayers.length ? await observedRealpath(resolve(canonicalData, "dependency-layers"), onEvent) : null;
+    for (const layer of seal.dependencyLayers) {
+        if (layersRoot === null)
+            throw new Error("restart seal has no dependency-layer root");
+        const layerRoot = await observedRealpath(layer.layerRoot.path, onEvent);
+        assertDirectChild(layersRoot, layerRoot, layer.layerId, "dependency layer");
+        await assertPathEvidence(layer.layerRoot, onEvent);
+        await assertPathEvidence(layer.manifest, onEvent);
+        const legacyPath = legacyDependencyLayerCertificationPath(canonicalData, layer.layerId);
+        const canonicalPath = dependencyLayerCertificationPath(canonicalData, layer.layerId);
+        if (layer.certification.path !== legacyPath && layer.certification.path !== canonicalPath) {
+            throw new Error("restart dependency certification path is outside managed storage");
+        }
+        await managedDependencyCertificationPath(canonicalData, layer.layerId, layer.certification.path === legacyPath);
+        await assertPathEvidence(layer.certification, onEvent);
+        await assertPathEvidence(layer.bindingEvidence, onEvent, true);
+        const bindingTarget = await observedRealpath(layer.bindingEvidence.path, onEvent);
+        const expectedTarget = await observedRealpath(resolve(layerRoot, "node_modules"), onEvent);
+        if (bindingTarget !== layer.bindingTarget || bindingTarget !== expectedTarget) {
+            throw new Error(`restart dependency binding targets unexpected content: ${layer.bindingEvidence.path}`);
+        }
+    }
+    return {
+        packageName: PRODUCT_PACKAGE_NAME,
+        launchContract: seal.launchContract,
+        packageVersion: seal.packageVersion,
+        contentDigest: seal.contentDigest,
+        releaseId: seal.releaseId,
+        packageRoot: seal.packageRoot,
+        files: seal.launchEntries,
+        ...(seal.dependencyLayers.length === 0 ? {} : {
+            dependencyLayers: seal.dependencyLayers.map(({ layerId, contentDigest, binding }) => ({ layerId, contentDigest, binding })),
+        }),
+        releaseRoot,
+    };
+}
+export function releaseCertificationDocument(release, restartSeal, verifiedAt = new Date().toISOString()) {
+    return {
+        schema: PRODUCT_IDENTITY.evidence.releaseCertificationSchema,
+        releaseId: release.releaseId,
+        contentDigest: release.contentDigest,
+        verifiedAt,
+        checks: [{ id: "immutable-content", passed: true }],
+        restartSeal,
+    };
+}
+export function restartSealDigest(core) {
+    return createHash("sha256").update(JSON.stringify(core)).digest("hex");
+}
+async function assertPathEvidence(evidence, onEvent, symbolic = false) {
+    const actual = await pathEvidence(evidence.path, evidence.kind, symbolic, onEvent);
+    if (JSON.stringify(actual) !== JSON.stringify(evidence))
+        throw new Error(`restart path evidence changed: ${evidence.path}`);
+}
+async function pathEvidence(path, kind, symbolic = false, onEvent) {
+    onEvent?.({ operation: "restart-evidence-read", path });
+    const metadata = symbolic ? await lstat(path, { bigint: true }) : await stat(path, { bigint: true });
+    if ((kind === "directory") !== metadata.isDirectory())
+        throw new Error(`restart evidence kind changed: ${path}`);
+    if (kind === "file" && !metadata.isFile())
+        throw new Error(`restart evidence file changed: ${path}`);
+    if (kind === "binding" && !metadata.isSymbolicLink())
+        throw new Error(`restart evidence binding changed: ${path}`);
+    if (kind === "file" && (metadata.mode & 146n) !== 0n)
+        throw new Error(`restart evidence file is writable: ${path}`);
+    return {
+        path: resolve(path),
+        kind,
+        device: metadata.dev.toString(),
+        inode: metadata.ino.toString(),
+        mode: Number(metadata.mode),
+        size: metadata.size.toString(),
+        modifiedNs: metadata.mtimeNs.toString(),
+        changedNs: metadata.ctimeNs.toString(),
+        bornNs: metadata.birthtimeNs.toString(),
+    };
+}
+function normalizeRestartSeal(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("release certification has no durable restart seal");
+    const seal = value;
+    if (seal.version !== RESTART_SEAL_VERSION || typeof seal.platform !== "string" || typeof seal.platformPolicy !== "string"
+        || typeof seal.releaseId !== "string" || typeof seal.packageVersion !== "string" || typeof seal.contentDigest !== "string"
+        || typeof seal.packageRoot !== "string" || typeof seal.certifiedAt !== "string" || typeof seal.sealDigest !== "string"
+        || !seal.releaseRoot || !seal.manifest || !Array.isArray(seal.launchEntries) || !Array.isArray(seal.launchEntryEvidence)
+        || !Array.isArray(seal.dependencyLayers)) {
+        throw new Error("durable restart seal is invalid");
+    }
+    return seal;
+}
+async function readJson(path, onEvent) {
+    onEvent?.({ operation: "restart-evidence-read", path });
+    return JSON.parse(await readFile(path, "utf8"));
+}
+async function observedRealpath(path, onEvent) {
+    onEvent?.({ operation: "restart-evidence-read", path });
+    return await realpath(path);
+}
+function assertDirectChild(parent, child, expectedName, kind) {
+    const fromParent = relative(parent, child);
+    if (isAbsolute(fromParent) || fromParent === ".." || fromParent.startsWith(`..${sep}`) || fromParent.includes(sep)
+        || basename(child) !== expectedName) {
+        throw new Error(`restart ${kind} is outside its managed store: ${child}`);
+    }
+}

package/dist/foundation/release/types.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Leaf types shared across the release subsystem. They live here so that the transaction store,
+ * launch selection, and dependency layers can name them without importing the update command or
+ * the release reader, which is what closed the subsystem's import cycles.
+ */
+export type UpdateChannel = "stable" | "next";
+export interface DependencyLayerReference {
+    readonly layerId: string;
+    readonly contentDigest: string;
+    readonly binding: "node_modules";
+}

package/dist/foundation/release/types.js

@@ -0,0 +1 @@
+export {};

package/dist/foundation/release/update-activation.d.ts

@@ -0,0 +1,72 @@
+/**
+ * The one activation contract an installed tree can offer the updater that installed it.
+ * The updater knows nothing else about the tree: the manifest names the contracts the tree
+ * serves, and this entry drives its activation with the tree's own release code.
+ */
+export declare const UPDATE_ACTIVATION_CONTRACT = "activate-v1";
+export declare const UPDATE_ACTIVATION_ENTRY = "bin/activate.js";
+/** Manifest field listing the activation contracts an installed tree serves. */
+export declare const UPDATE_ACTIVATION_MANIFEST_FIELD = "updateActivationContracts";
+export type UpdateActivationPhase = "materialized" | "certified" | "active-reference-committed";
+/**
+ * Copying the release is the longest step with nothing to say for itself, so it
+ * reports the files it has written against the files it must write. A caller that
+ * shows progress can then move with the work instead of guessing at it.
+ */
+export interface UpdateMaterializationProgress {
+    readonly completed: number;
+    readonly total: number;
+}
+export interface UpdateActivationCallbacks {
+    readonly phase: (phase: UpdateActivationPhase) => Promise<void>;
+    readonly onMaterializing?: (progress: UpdateMaterializationProgress) => void;
+    readonly onWarmup?: (state: "started" | "completed") => void;
+}
+export interface UpdateActivationRequest {
+    readonly packageRoot: string;
+    readonly dataDir: string;
+    readonly targetVersion: string;
+    readonly environment: NodeJS.ProcessEnv;
+}
+/** One line of the activator's progress stream; `failed` carries the reason and ends it. */
+export type UpdateActivationEvent = {
+    readonly event: "materializing";
+    readonly completed: number;
+    readonly total: number;
+} | {
+    readonly event: "phase";
+    readonly phase: UpdateActivationPhase;
+} | {
+    readonly event: "warmup";
+    readonly state: "started" | "completed";
+} | {
+    readonly event: "completed";
+} | {
+    readonly event: "failed";
+    readonly message: string;
+};
+/**
+ * Activate the installed tree at `packageRoot` with this process's own release code:
+ * materialize it into the immutable store, certify, warm, verify supervision, and only
+ * then move the active reference. This is what the installed tree runs for itself through
+ * its activation entry, and what an updater runs in-process for a tree older than the contract.
+ */
+export declare function activateInstalledRelease(request: UpdateActivationRequest, callbacks: UpdateActivationCallbacks): Promise<void>;
+/**
+ * Which activation contracts the installed tree serves, read from its manifest. A tree
+ * without the field, or without a readable manifest, serves none and is activated in-process.
+ */
+export declare function readActivationContracts(packageRoot: string, read?: (path: string) => Promise<string>): Promise<readonly string[]>;
+/**
+ * Drive the installed tree's own activator and relay its progress. The updater passes
+ * the tree what the tree cannot know (the data directory, the target it must match) and
+ * learns from it only the phases it reached; every path inside the tree is the tree's business.
+ */
+export declare function delegateActivation(request: UpdateActivationRequest, callbacks: UpdateActivationCallbacks): Promise<void>;
+/**
+ * Body of the installed tree's activation entry: activate the tree this code ships in,
+ * writing one progress event per line so the updater that started it can follow along.
+ */
+export declare function runActivationEntry(argv: readonly string[], entryUrl: string, io?: {
+    write(line: string): void;
+}, environment?: NodeJS.ProcessEnv): Promise<number>;

package/dist/foundation/release/update-activation.js

@@ -0,0 +1,204 @@
+import { spawn } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { PRODUCT_TEXT } from "../../product-identity.js";
+import { certifyMaterializedRelease, ensureSupervisor } from "./bootstrap.js";
+import { CohortStateStore } from "./cohort-state.js";
+import { encodeFrame, LineFrameDecoder } from "../protocol/index.js";
+import { resolveProductPaths } from "../lifecycle/index.js";
+import { materializeRelease } from "./release-store.js";
+import { warmMaterializedRelease } from "./warmup.js";
+/**
+ * The one activation contract an installed tree can offer the updater that installed it.
+ * The updater knows nothing else about the tree: the manifest names the contracts the tree
+ * serves, and this entry drives its activation with the tree's own release code.
+ */
+export const UPDATE_ACTIVATION_CONTRACT = "activate-v1";
+export const UPDATE_ACTIVATION_ENTRY = "bin/activate.js";
+/** Manifest field listing the activation contracts an installed tree serves. */
+export const UPDATE_ACTIVATION_MANIFEST_FIELD = "updateActivationContracts";
+const ACTIVATION_DIAGNOSTIC_LIMIT = 2_000;
+/**
+ * Activate the installed tree at `packageRoot` with this process's own release code:
+ * materialize it into the immutable store, certify, warm, verify supervision, and only
+ * then move the active reference. This is what the installed tree runs for itself through
+ * its activation entry, and what an updater runs in-process for a tree older than the contract.
+ */
+export async function activateInstalledRelease(request, callbacks) {
+    const stateStore = new CohortStateStore(request.dataDir);
+    let total = 0;
+    let completed = 0;
+    const candidate = await materializeRelease(request.packageRoot, request.dataDir, {
+        onProgress: event => {
+            total = event.fileCount;
+            callbacks.onMaterializing?.({ completed, total });
+        },
+        onOperation: event => {
+            if (event.operation !== "candidate-write" && event.operation !== "layer-write")
+                return;
+            completed += 1;
+            callbacks.onMaterializing?.({ completed, total });
+        },
+    });
+    if (candidate.packageVersion !== request.targetVersion)
+        throw new Error(`installed ${PRODUCT_TEXT.displayName} version ${candidate.packageVersion} does not match target ${request.targetVersion}`);
+    await stateStore.recordCandidate(candidate);
+    await callbacks.phase("materialized");
+    const diagnostics = await certifyMaterializedRelease(candidate, request.dataDir);
+    await stateStore.approve(candidate.releaseId, diagnostics);
+    await callbacks.phase("certified");
+    callbacks.onWarmup?.("started");
+    await warmMaterializedRelease(candidate, request.environment);
+    callbacks.onWarmup?.("completed");
+    await ensureSupervisor(candidate, request.environment);
+    // Invariant: warmup and authenticated readiness precede changing the active reference.
+    await stateStore.activate(candidate.releaseId);
+    await callbacks.phase("active-reference-committed");
+}
+/**
+ * Which activation contracts the installed tree serves, read from its manifest. A tree
+ * without the field, or without a readable manifest, serves none and is activated in-process.
+ */
+export async function readActivationContracts(packageRoot, read = path => readFile(path, "utf8")) {
+    try {
+        const manifest = JSON.parse(await read(resolve(packageRoot, "package.json")));
+        const declared = manifest[UPDATE_ACTIVATION_MANIFEST_FIELD];
+        return Array.isArray(declared) ? declared.filter((value) => typeof value === "string") : [];
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Drive the installed tree's own activator and relay its progress. The updater passes
+ * the tree what the tree cannot know (the data directory, the target it must match) and
+ * learns from it only the phases it reached; every path inside the tree is the tree's business.
+ */
+export async function delegateActivation(request, callbacks) {
+    const entry = resolve(request.packageRoot, UPDATE_ACTIVATION_ENTRY);
+    const child = spawn(process.execPath, [entry, "--data-dir", request.dataDir, "--target-version", request.targetVersion], {
+        env: request.environment,
+        stdio: ["ignore", "pipe", "pipe"],
+        windowsHide: true,
+    });
+    const decoder = new LineFrameDecoder();
+    let diagnostics = "";
+    let failure = null;
+    let completed = false;
+    // Concurrency: callbacks are awaited in order so a phase is journaled before the next one is read.
+    let relay = Promise.resolve();
+    child.stderr?.setEncoding("utf8");
+    child.stderr?.on("data", chunk => { diagnostics = `${diagnostics}${chunk}`.slice(-ACTIVATION_DIAGNOSTIC_LIMIT); });
+    child.stdout?.on("data", chunk => {
+        let events;
+        try {
+            events = decoder.push(chunk);
+        }
+        catch (error) {
+            failure ??= errorMessage(error);
+            return;
+        }
+        for (const event of events) {
+            relay = relay.then(async () => {
+                const parsed = parseActivationEvent(event);
+                if (!parsed) {
+                    failure ??= `unrecognized activation event ${JSON.stringify(event).slice(0, 200)}`;
+                    return;
+                }
+                if (parsed.event === "materializing")
+                    callbacks.onMaterializing?.({ completed: parsed.completed, total: parsed.total });
+                else if (parsed.event === "phase")
+                    await callbacks.phase(parsed.phase);
+                else if (parsed.event === "warmup")
+                    callbacks.onWarmup?.(parsed.state);
+                else if (parsed.event === "completed")
+                    completed = true;
+                else
+                    failure ??= parsed.message;
+            }).catch(error => { failure ??= errorMessage(error); });
+        }
+    });
+    const exit = await new Promise((resolvePromise, rejectPromise) => {
+        child.once("error", rejectPromise);
+        child.once("close", (code, signal) => resolvePromise({ code, signal }));
+    });
+    await relay;
+    if (failure)
+        throw new Error(failure);
+    if (exit.code !== 0 || !completed) {
+        const status = exit.code === null ? exit.signal ?? "unknown status" : `status ${exit.code}`;
+        throw new Error(`installed release activation exited with ${status}${summarize(diagnostics)}`);
+    }
+}
+/**
+ * Body of the installed tree's activation entry: activate the tree this code ships in,
+ * writing one progress event per line so the updater that started it can follow along.
+ */
+export async function runActivationEntry(argv, entryUrl, io = { write: line => process.stdout.write(line) }, environment = process.env) {
+    const emit = (event) => io.write(encodeFrame(event));
+    try {
+        const arguments_ = parseEntryArguments(argv);
+        const packageRoot = resolve(fileURLToPath(new URL("..", entryUrl)));
+        await activateInstalledRelease({
+            packageRoot,
+            dataDir: arguments_.dataDir ?? resolveProductPaths(environment).dataDir,
+            targetVersion: arguments_.targetVersion,
+            environment,
+        }, {
+            phase: async (phase) => emit({ event: "phase", phase }),
+            onMaterializing: progress => emit({ event: "materializing", ...progress }),
+            onWarmup: state => emit({ event: "warmup", state }),
+        });
+        emit({ event: "completed" });
+        return 0;
+    }
+    catch (error) {
+        emit({ event: "failed", message: errorMessage(error) });
+        return 1;
+    }
+}
+function parseEntryArguments(argv) {
+    let dataDir = null;
+    let targetVersion = null;
+    for (let index = 0; index < argv.length; index += 1) {
+        const value = argv[index + 1];
+        if (argv[index] === "--data-dir" && value !== undefined) {
+            dataDir = value;
+            index += 1;
+        }
+        else if (argv[index] === "--target-version" && value !== undefined) {
+            targetVersion = value;
+            index += 1;
+        }
+        else
+            throw new Error(`unexpected activation argument ${argv[index]}`);
+    }
+    if (targetVersion === null)
+        throw new Error("activation requires --target-version");
+    return { dataDir, targetVersion };
+}
+function parseActivationEvent(value) {
+    if (typeof value !== "object" || value === null || !("event" in value))
+        return null;
+    const record = value;
+    switch (record.event) {
+        case "materializing":
+            return typeof record.completed === "number" && typeof record.total === "number" ? { event: "materializing", completed: record.completed, total: record.total } : null;
+        case "phase":
+            return record.phase === "materialized" || record.phase === "certified" || record.phase === "active-reference-committed" ? { event: "phase", phase: record.phase } : null;
+        case "warmup":
+            return record.state === "started" || record.state === "completed" ? { event: "warmup", state: record.state } : null;
+        case "completed":
+            return { event: "completed" };
+        case "failed":
+            return typeof record.message === "string" ? { event: "failed", message: record.message } : null;
+        default:
+            return null;
+    }
+}
+function summarize(text) {
+    const lines = text.split(/\r?\n/).map(line => line.trim()).filter(line => line.length > 0);
+    return lines.length === 0 ? "" : `: ${lines.slice(0, 4).join(" | ")}`;
+}
+function errorMessage(error) { return error instanceof Error ? error.message : String(error); }

package/dist/foundation/release/update-launch.d.ts

@@ -0,0 +1,6 @@
+import type { CohortState, ReleaseRecord } from "./cohort-state.js";
+import type { UpdateTransaction } from "./update-transaction.js";
+/** Keep interactive launches on the last successful release until the update commits success. */
+export declare function selectUpdateLaunchRelease(state: CohortState, transaction: UpdateTransaction | null): ReleaseRecord | null;
+/** Pause cohort retirement during preparation; afterward only the successful launch release admits new sessions. */
+export declare function selectSupervisorLaunchReleaseId(state: CohortState, transaction: UpdateTransaction | null): string | null;

package/dist/foundation/release/update-launch.js

@@ -0,0 +1,17 @@
+/** Keep interactive launches on the last successful release until the update commits success. */
+export function selectUpdateLaunchRelease(state, transaction) {
+    if (transaction === null || transaction.status === "completed")
+        return null;
+    const prior = transaction.priorActiveReleaseId === null ? undefined : state.releases[transaction.priorActiveReleaseId];
+    if (!prior || prior.approval !== "approved") {
+        throw new Error("unfinished update has no verified previous release available for launch; resume the update");
+    }
+    return prior;
+}
+/** Pause cohort retirement during preparation; afterward only the successful launch release admits new sessions. */
+export function selectSupervisorLaunchReleaseId(state, transaction) {
+    // Concurrency: both the previous cohort and the warming candidate must remain available until cutover.
+    if (transaction?.status === "active")
+        return null;
+    return selectUpdateLaunchRelease(state, transaction)?.releaseId ?? state.references.active;
+}

package/dist/foundation/release/update-recovery.d.ts

@@ -0,0 +1,82 @@
+import { PRIVATE_LAUNCH_CONTRACT } from "../launch-context/index.js";
+import type { UpdateTransaction, UpdateRecoveryState } from "./update-transaction.js";
+export declare const UPDATE_RECOVERY_SCHEMA: "a1-update-recovery-v1";
+export interface UpdateRecoveryCapsule {
+    readonly schema: typeof UPDATE_RECOVERY_SCHEMA;
+    readonly launchContract: typeof PRIVATE_LAUNCH_CONTRACT;
+    readonly transactionId: string;
+    readonly packageName: string;
+    readonly targetVersion: string;
+    readonly packageRoot: string;
+    readonly globalRoot: string;
+    readonly launcherRoot: string;
+    readonly launchers: readonly string[];
+    readonly priorReleaseId: string;
+    readonly priorReleaseRoot: string;
+    readonly priorContentDigest: string;
+    readonly releaseManifestName: string;
+    readonly recoveryEntry: string;
+    readonly recoveryEntryDigest: string;
+    readonly nodeExecutable: string;
+    readonly npmCli: string;
+    readonly npmArguments: readonly string[];
+    readonly cancellationPath: string;
+    readonly resultPath: string;
+    readonly ownerPath: string;
+    readonly createdAt: string;
+}
+export interface UpdateRecoveryResult {
+    readonly schema: typeof UPDATE_RECOVERY_SCHEMA;
+    readonly transactionId: string;
+    readonly outcome: "installed" | "recovery-launcher" | "failed";
+    readonly npmExitCode: number | null;
+    readonly cancelled: boolean;
+    readonly launcherDisposition: "target" | "recovery" | "unavailable";
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly completedAt: string;
+}
+export interface ProtectedPackageReplacementOptions {
+    readonly dataDir: string;
+    readonly globalRoot: string;
+    /** Root used only to locate the active npm implementation; installation remains pinned to globalRoot. */
+    readonly npmCliRoot?: string;
+    readonly packageRoot: string;
+    readonly transaction: UpdateTransaction;
+    readonly priorRelease: {
+        readonly releaseId: string;
+        readonly releaseRoot: string;
+        readonly contentDigest: string;
+    };
+    readonly output: {
+        stderr(message: string): void;
+    };
+    readonly environment?: NodeJS.ProcessEnv;
+    readonly platform?: NodeJS.Platform;
+    readonly timeoutMs?: number;
+    readonly workerSpawner?: (entry: string, manifestPath: string, environment: NodeJS.ProcessEnv) => Promise<void>;
+    readonly onRecoveryState?: (state: UpdateRecoveryState) => Promise<void>;
+}
+export interface ProtectedPackageReplacementResult extends UpdateRecoveryResult {
+    readonly recovery: UpdateRecoveryState;
+}
+/** Derive the only npm prefix that can own a platform's canonical global package root. */
+export declare function npmPrefixForGlobalRoot(globalRoot: string, platform?: NodeJS.Platform): string;
+/** Fixed replacement arguments pin npm to the installation that owns the invoked launcher. */
+export declare function updateNpmInstallArguments(globalRoot: string, targetVersion: string, platform?: NodeJS.Platform): readonly string[];
+/** Resolve the complete public launcher set npm owns for the selected platform and prefix. */
+export declare function updateLauncherPaths(globalRoot: string, platform?: NodeJS.Platform): readonly string[];
+/** Validate transaction-scoped recovery authority without trusting npm temporary names. */
+export declare function readUpdateRecoveryCapsule(manifestPath: string, platform?: NodeJS.Platform): Promise<UpdateRecoveryCapsule>;
+/** Prepare durable recovery authority before npm can mutate the live launcher set. */
+export declare function prepareUpdateRecoveryCapsule(options: ProtectedPackageReplacementOptions): Promise<{
+    capsule: UpdateRecoveryCapsule;
+    manifestPath: string;
+}>;
+/** Execute global replacement behind a detached owner and coordinate terminal cancellation. */
+export declare function runProtectedPackageReplacement(options: ProtectedPackageReplacementOptions): Promise<ProtectedPackageReplacementResult>;
+export declare function removeUpdateRecoveryCapsule(dataDir: string, transactionId: string): Promise<void>;
+/** Classify a complete launcher set without following linked or mixed launcher files. */
+export declare function inspectUpdateLauncherSet(capsule: UpdateRecoveryCapsule, platform?: NodeJS.Platform): Promise<"target" | "recovery" | "unavailable">;
+/** Remove terminal recovery capsules only after no canonical launcher references them. */
+export declare function cleanupUpdateRecoveryCapsules(dataDir: string): Promise<void>;