@timurproko/a1 0.1.8-dev.49ff83a → 0.1.8-dev.508

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

@@ -0,0 +1,356 @@
+import { createHash, randomUUID } from "node:crypto";
+import { spawn } from "node:child_process";
+import { chmod, lstat, mkdir, open, readFile, readdir, realpath, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { PRODUCT_IDENTITY, PRODUCT_TEXT } from "../../product-identity.js";
+import { processIsAlive } from "./process-cleanup.js";
+import { PRIVATE_LAUNCH_CONTRACT, assertCurrentLaunchContract } from "../launch-context/index.js";
+export const UPDATE_RECOVERY_SCHEMA = "a1-update-recovery-v1";
+const WORKER_TIMEOUT_MS = 15 * 60 * 1_000;
+const POLL_MS = 50;
+/** Resolve the complete public launcher set npm owns for the active platform. */
+export function updateLauncherPaths(globalRoot, platform = process.platform) {
+    const launcherRoot = platform === "win32" ? dirname(globalRoot) : resolve(globalRoot, "..", "..", "bin");
+    return platform === "win32"
+        ? [resolve(launcherRoot, "a1"), resolve(launcherRoot, "a1.cmd"), resolve(launcherRoot, "a1.ps1")]
+        : [resolve(launcherRoot, "a1")];
+}
+/** Validate transaction-scoped recovery authority without trusting npm temporary names. */
+export async function readUpdateRecoveryCapsule(manifestPath, platform = process.platform) {
+    const capsule = JSON.parse(await readFile(manifestPath, "utf8"));
+    assertCurrentLaunchContract(capsule);
+    if (capsule.schema !== UPDATE_RECOVERY_SCHEMA || !/^[0-9a-f-]{36}$/i.test(capsule.transactionId) || typeof capsule.targetVersion !== "string"
+        || capsule.packageName !== PRODUCT_TEXT.packageName || typeof capsule.packageRoot !== "string" || typeof capsule.globalRoot !== "string"
+        || typeof capsule.launcherRoot !== "string" || !Array.isArray(capsule.launchers) || typeof capsule.priorReleaseId !== "string"
+        || typeof capsule.priorReleaseRoot !== "string" || !/^[a-f0-9]{64}$/.test(capsule.priorContentDigest) || capsule.releaseManifestName !== PRODUCT_IDENTITY.manifest.releaseFilename || typeof capsule.recoveryEntry !== "string"
+        || !/^[a-f0-9]{64}$/.test(capsule.recoveryEntryDigest) || typeof capsule.nodeExecutable !== "string" || typeof capsule.npmCli !== "string" || !Array.isArray(capsule.npmArguments)
+        || typeof capsule.cancellationPath !== "string" || typeof capsule.resultPath !== "string" || typeof capsule.ownerPath !== "string") {
+        throw new Error("invalid A1 update recovery capsule");
+    }
+    const canonicalGlobal = await realpath(capsule.globalRoot);
+    const canonicalPackage = await realpath(capsule.packageRoot).catch(() => resolve(capsule.packageRoot));
+    const expectedPackage = resolve(canonicalGlobal, ...capsule.packageName.split("/"));
+    if (!samePath(canonicalPackage, expectedPackage) || !containedBy(canonicalGlobal, canonicalPackage))
+        throw new Error("recovery package root is outside npm global root");
+    const expectedNpmArguments = ["install", "--global", "--loglevel=error", "--no-fund", "--no-audit", `${capsule.packageName}@${capsule.targetVersion}`];
+    if (JSON.stringify(capsule.npmArguments) !== JSON.stringify(expectedNpmArguments))
+        throw new Error("recovery npm arguments differ from the selected target");
+    const expectedLaunchers = updateLauncherPaths(canonicalGlobal, platform);
+    if (JSON.stringify(capsule.launchers.map(path => resolve(path))) !== JSON.stringify(expectedLaunchers.map(path => resolve(path)))) {
+        throw new Error("recovery launcher set differs from the canonical npm launcher set");
+    }
+    for (const path of capsule.launchers)
+        assertDirectChild(resolve(capsule.launcherRoot), resolve(path));
+    const lexicalCapsuleRoot = dirname(resolve(manifestPath));
+    if (lexicalCapsuleRoot.split(sep).at(-1) !== capsule.transactionId)
+        throw new Error("recovery capsule path differs from its transaction identity");
+    const capsuleRoot = await realpath(lexicalCapsuleRoot);
+    const entry = await realpath(capsule.recoveryEntry);
+    assertDirectChild(capsuleRoot, entry);
+    if (!samePath(entry, resolve(capsuleRoot, "recovery.js")))
+        throw new Error("recovery entry path differs from the managed capsule");
+    const expectedSidecars = [resolve(lexicalCapsuleRoot, "cancel.json"), resolve(lexicalCapsuleRoot, "result.json"), resolve(lexicalCapsuleRoot, "owner.json")];
+    if (![capsule.cancellationPath, capsule.resultPath, capsule.ownerPath].every((path, index) => samePath(resolve(path), expectedSidecars[index]))) {
+        throw new Error("recovery sidecar paths differ from the managed capsule");
+    }
+    const dataDir = dirname(dirname(capsuleRoot));
+    const releasesRoot = await realpath(resolve(dataDir, "releases"));
+    const priorReleaseRoot = await realpath(capsule.priorReleaseRoot);
+    assertDirectChild(releasesRoot, priorReleaseRoot);
+    if (priorReleaseRoot.split(sep).at(-1) !== capsule.priorReleaseId)
+        throw new Error("recovery prior release identity is invalid");
+    const priorManifest = JSON.parse(await readFile(resolve(priorReleaseRoot, capsule.releaseManifestName), "utf8"));
+    assertCurrentLaunchContract(priorManifest);
+    if (priorManifest.releaseId !== capsule.priorReleaseId || priorManifest.contentDigest !== capsule.priorContentDigest) {
+        throw new Error("recovery prior release manifest differs from the capsule");
+    }
+    if (resolve(capsule.nodeExecutable) !== resolve(process.execPath))
+        throw new Error("recovery Node executable differs from the current runtime");
+    const npmMetadata = await lstat(capsule.npmCli);
+    if (!npmMetadata.isFile() || npmMetadata.isSymbolicLink())
+        throw new Error("recovery npm entry is invalid");
+    const digest = createHash("sha256").update(await readFile(entry)).digest("hex");
+    if (digest !== capsule.recoveryEntryDigest)
+        throw new Error("recovery entry digest differs from capsule");
+    return capsule;
+}
+/** Prepare durable recovery authority before npm can mutate the live launcher set. */
+export async function prepareUpdateRecoveryCapsule(options) {
+    const root = resolve(options.dataDir, "update-recovery");
+    await mkdir(root, { recursive: true, mode: 0o700 });
+    const finalRoot = resolve(root, options.transaction.transactionId);
+    const existingManifest = resolve(finalRoot, "capsule.json");
+    if (await lstat(existingManifest).catch(() => null))
+        return { capsule: await readUpdateRecoveryCapsule(existingManifest, options.platform), manifestPath: existingManifest };
+    const candidate = resolve(root, `.candidate-${options.transaction.transactionId}-${randomUUID()}`);
+    await mkdir(candidate, { mode: 0o700 });
+    try {
+        const sourceEntry = fileURLToPath(new URL("../../../bin/update-recovery.js", import.meta.url));
+        const entryBytes = await readFile(sourceEntry);
+        const candidateEntry = resolve(candidate, "recovery.js");
+        const recoveryEntry = resolve(finalRoot, "recovery.js");
+        await writeFile(candidateEntry, entryBytes, { flag: "wx", mode: 0o500 });
+        await chmod(candidateEntry, 0o500);
+        const canonicalGlobal = await realpath(options.globalRoot);
+        const platform = options.platform ?? process.platform;
+        const launcherRoot = platform === "win32" ? dirname(canonicalGlobal) : resolve(canonicalGlobal, "..", "..", "bin");
+        const npmCli = await resolveNpmCli(canonicalGlobal, options.environment ?? process.env);
+        const capsule = {
+            schema: UPDATE_RECOVERY_SCHEMA,
+            launchContract: PRIVATE_LAUNCH_CONTRACT,
+            transactionId: options.transaction.transactionId,
+            packageName: PRODUCT_TEXT.packageName,
+            targetVersion: options.transaction.targetVersion,
+            packageRoot: resolve(options.packageRoot),
+            globalRoot: canonicalGlobal,
+            launcherRoot,
+            launchers: updateLauncherPaths(canonicalGlobal, platform),
+            priorReleaseId: options.priorRelease.releaseId,
+            priorReleaseRoot: resolve(options.priorRelease.releaseRoot),
+            priorContentDigest: options.priorRelease.contentDigest,
+            releaseManifestName: PRODUCT_IDENTITY.manifest.releaseFilename,
+            recoveryEntry,
+            recoveryEntryDigest: createHash("sha256").update(entryBytes).digest("hex"),
+            nodeExecutable: process.execPath,
+            npmCli,
+            npmArguments: ["install", "--global", "--loglevel=error", "--no-fund", "--no-audit", `${PRODUCT_TEXT.packageName}@${options.transaction.targetVersion}`],
+            cancellationPath: resolve(finalRoot, "cancel.json"),
+            resultPath: resolve(finalRoot, "result.json"),
+            ownerPath: resolve(finalRoot, "owner.json"),
+            createdAt: new Date().toISOString(),
+        };
+        await writeDurableJson(resolve(candidate, "capsule.json"), capsule);
+        try {
+            await rename(candidate, finalRoot);
+        }
+        catch (error) {
+            if (!await lstat(finalRoot).catch(() => null))
+                throw error;
+            await rm(candidate, { recursive: true, force: true });
+        }
+        const manifestPath = resolve(finalRoot, "capsule.json");
+        return { capsule: await readUpdateRecoveryCapsule(manifestPath, options.platform), manifestPath };
+    }
+    catch (error) {
+        await rm(candidate, { recursive: true, force: true });
+        throw error;
+    }
+}
+/** Execute global replacement behind a detached owner and coordinate terminal cancellation. */
+export async function runProtectedPackageReplacement(options) {
+    const prepared = await prepareUpdateRecoveryCapsule(options);
+    const capsule = prepared.capsule;
+    await options.onRecoveryState?.({
+        capsulePath: prepared.manifestPath,
+        status: "prepared",
+        guardianPid: null,
+        guardianStartIdentity: null,
+        cancellationRequested: false,
+        launcherDisposition: "pending",
+    });
+    let owner = await readLiveRecoveryOwner(capsule.ownerPath, capsule.transactionId);
+    const ownerIsLive = owner !== null;
+    const priorResult = await readRecoveryResult(capsule.resultPath, capsule.transactionId).catch(() => null);
+    if (!ownerIsLive && priorResult?.outcome !== "installed") {
+        const startLease = resolve(dirname(prepared.manifestPath), "worker-starting.lock");
+        if (await acquireStartLease(startLease)) {
+            await Promise.all([rm(capsule.resultPath, { force: true }), rm(capsule.cancellationPath, { force: true }), rm(capsule.ownerPath, { force: true })]);
+            owner = null;
+            try {
+                await (options.workerSpawner ?? spawnRecoveryWorker)(capsule.recoveryEntry, prepared.manifestPath, options.environment ?? process.env);
+            }
+            catch (error) {
+                await rm(startLease, { force: true });
+                throw error;
+            }
+        }
+    }
+    let runningRecorded = false;
+    let cancellationReported = false;
+    let cancellationWrite = null;
+    const requestCancellation = (signal) => {
+        cancellationWrite ??= writeDurableJson(capsule.cancellationPath, { schema: UPDATE_RECOVERY_SCHEMA, transactionId: capsule.transactionId, signal, requestedAt: new Date().toISOString() });
+        if (!cancellationReported) {
+            cancellationReported = true;
+            options.output.stderr(`${PRODUCT_TEXT.diagnostic("cancellation requested; restoring a callable launcher before exiting.")}\n`);
+        }
+    };
+    const onSigint = () => requestCancellation("SIGINT");
+    const onSigterm = () => requestCancellation("SIGTERM");
+    process.on("SIGINT", onSigint);
+    process.on("SIGTERM", onSigterm);
+    try {
+        const deadline = Date.now() + (options.timeoutMs ?? WORKER_TIMEOUT_MS);
+        while (Date.now() < deadline) {
+            const result = await readRecoveryResult(capsule.resultPath, capsule.transactionId).catch(() => null);
+            if (result) {
+                const recovery = {
+                    capsulePath: prepared.manifestPath,
+                    status: result.outcome === "installed" ? "package-installed" : "recovery-launcher",
+                    guardianPid: typeof owner?.pid === "number" ? owner.pid : null,
+                    guardianStartIdentity: typeof owner?.startIdentity === "string" ? owner.startIdentity : null,
+                    cancellationRequested: result.cancelled,
+                    launcherDisposition: result.launcherDisposition,
+                };
+                if (cancellationWrite)
+                    await cancellationWrite;
+                await options.onRecoveryState?.(recovery);
+                return { ...result, recovery };
+            }
+            owner = await readLiveRecoveryOwner(capsule.ownerPath, capsule.transactionId) ?? owner;
+            if (!runningRecorded && owner?.transactionId === capsule.transactionId && typeof owner.pid === "number" && typeof owner.startIdentity === "string") {
+                runningRecorded = true;
+                await rm(resolve(dirname(prepared.manifestPath), "worker-starting.lock"), { force: true });
+                await options.onRecoveryState?.({
+                    capsulePath: prepared.manifestPath,
+                    status: "running",
+                    guardianPid: owner.pid,
+                    guardianStartIdentity: owner.startIdentity,
+                    cancellationRequested: false,
+                    launcherDisposition: "pending",
+                });
+            }
+            await new Promise(resolvePromise => setTimeout(resolvePromise, POLL_MS));
+        }
+        requestCancellation("SIGTERM");
+        if (cancellationWrite)
+            await cancellationWrite;
+        throw new Error("A1 update recovery guardian timed out before establishing a callable launcher");
+    }
+    finally {
+        process.off("SIGINT", onSigint);
+        process.off("SIGTERM", onSigterm);
+        try {
+            await cancellationWrite;
+        }
+        catch { }
+    }
+}
+export async function removeUpdateRecoveryCapsule(dataDir, transactionId) {
+    if (!/^[0-9a-f-]+$/i.test(transactionId))
+        throw new Error("invalid update recovery transaction identity");
+    await rm(resolve(dataDir, "update-recovery", transactionId), { recursive: true, force: true });
+}
+/** Classify a complete launcher set without following linked or mixed launcher files. */
+export async function inspectUpdateLauncherSet(capsule, platform = process.platform) {
+    let disposition = null;
+    const targetToken = `node_modules/${capsule.packageName}/bin/cli.js`;
+    for (const path of capsule.launchers) {
+        const metadata = await lstat(path).catch(() => null);
+        if (!metadata?.isFile() || metadata.isSymbolicLink() || (platform !== "win32" && (metadata.mode & 0o111) === 0))
+            return "unavailable";
+        const source = (await readFile(path, "utf8")).replaceAll("\\", "/");
+        const current = source.includes(capsule.recoveryEntry.replaceAll("\\", "/")) ? "recovery"
+            : source.includes(targetToken) ? "target" : null;
+        if (current === null || disposition !== null && disposition !== current)
+            return "unavailable";
+        disposition = current;
+    }
+    return disposition ?? "unavailable";
+}
+/** Remove terminal recovery capsules only after no canonical launcher references them. */
+export async function cleanupUpdateRecoveryCapsules(dataDir) {
+    const root = resolve(dataDir, "update-recovery");
+    for (const entry of await readdir(root, { withFileTypes: true }).catch(() => [])) {
+        if (!entry.isDirectory() || entry.name.startsWith(".candidate-"))
+            continue;
+        const capsuleRoot = resolve(root, entry.name);
+        const manifestPath = resolve(capsuleRoot, "capsule.json");
+        try {
+            const capsule = await readUpdateRecoveryCapsule(manifestPath);
+            if (await inspectUpdateLauncherSet(capsule) !== "recovery")
+                await rm(capsuleRoot, { recursive: true, force: true });
+        }
+        catch {
+            // Security: malformed recovery authority is retained for diagnostics rather than used as deletion authority.
+        }
+    }
+}
+async function spawnRecoveryWorker(entry, manifestPath, environment) {
+    const child = spawn(process.execPath, [entry, "--worker", manifestPath], { detached: true, stdio: "ignore", windowsHide: true, env: environment });
+    await new Promise((resolvePromise, rejectPromise) => {
+        child.once("spawn", resolvePromise);
+        child.once("error", rejectPromise);
+    });
+    child.unref();
+}
+async function resolveNpmCli(globalRoot, environment) {
+    const candidates = [environment.npm_execpath, resolve(globalRoot, "npm", "bin", "npm-cli.js")].filter((value) => typeof value === "string" && value.length > 0);
+    for (const candidate of candidates) {
+        const canonical = await realpath(candidate).catch(() => null);
+        if (canonical && await lstat(canonical).then(metadata => metadata.isFile()).catch(() => false))
+            return canonical;
+    }
+    throw new Error("could not resolve npm's JavaScript entry for protected package replacement");
+}
+async function readLiveRecoveryOwner(path, transactionId) {
+    const owner = await readJson(path).catch(() => null);
+    const metadata = await lstat(path).catch(() => null);
+    if (!owner || owner.transactionId !== transactionId || typeof owner.pid !== "number" || typeof owner.startIdentity !== "string"
+        || !metadata || Date.now() - metadata.mtimeMs > 2_000 || !processIsAlive(owner.pid))
+        return null;
+    return owner;
+}
+async function acquireStartLease(path) {
+    try {
+        const file = await open(path, "wx", 0o600);
+        await file.writeFile(JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString() }));
+        await file.close();
+        return true;
+    }
+    catch (error) {
+        if (!(error instanceof Error && "code" in error && error.code === "EEXIST"))
+            throw error;
+        const metadata = await lstat(path).catch(() => null);
+        if (metadata && Date.now() - metadata.mtimeMs > 5_000) {
+            await rm(path, { force: true });
+            return await acquireStartLease(path);
+        }
+        return false;
+    }
+}
+async function readRecoveryResult(path, transactionId) {
+    const value = await readJson(path).catch(error => {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return null;
+        throw error;
+    });
+    if (value === null)
+        return null;
+    if (value.schema !== UPDATE_RECOVERY_SCHEMA || value.transactionId !== transactionId || !["installed", "recovery-launcher", "failed"].includes(value.outcome)
+        || !["target", "recovery", "unavailable"].includes(value.launcherDisposition) || typeof value.cancelled !== "boolean"
+        || typeof value.stdout !== "string" || typeof value.stderr !== "string")
+        throw new Error("invalid A1 update recovery result");
+    return value;
+}
+async function writeDurableJson(path, value) {
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    const file = await open(temporary, "wx", 0o600);
+    try {
+        await file.writeFile(JSON.stringify(value, null, 2));
+        await file.sync();
+    }
+    finally {
+        await file.close();
+    }
+    await rename(temporary, path);
+}
+async function readJson(path) { return JSON.parse(await readFile(path, "utf8")); }
+function samePath(left, right) {
+    return process.platform === "win32" ? resolve(left).toLowerCase() === resolve(right).toLowerCase() : resolve(left) === resolve(right);
+}
+function containedBy(parent, child) {
+    const fromParent = relative(parent, child);
+    return fromParent.length > 0 && fromParent !== ".." && !fromParent.startsWith(`..${sep}`) && !isAbsolute(fromParent);
+}
+function assertDirectChild(parent, child) {
+    const expectedParent = resolve(parent);
+    const actualParent = dirname(resolve(child));
+    const matches = process.platform === "win32"
+        ? actualParent.toLowerCase() === expectedParent.toLowerCase()
+        : actualParent === expectedParent;
+    if (!matches)
+        throw new Error(`update recovery path is outside its managed root: ${child}`);
+}

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

@@ -0,0 +1,42 @@
+export declare const UPDATE_JOURNAL_SCHEMA: string;
+import type { UpdateChannel } from "./types.js";
+export type UpdateTransactionPhase = "shutdown-intent" | "ownership-released" | "package-installed" | "materialized" | "certified" | "active-reference-committed" | "supervisor-verified";
+export interface UpdateRecoveryState {
+    readonly capsulePath: string;
+    readonly status: "prepared" | "running" | "package-installed" | "recovery-launcher";
+    readonly guardianPid: number | null;
+    readonly guardianStartIdentity: string | null;
+    readonly cancellationRequested: boolean;
+    readonly launcherDisposition: "pending" | "target" | "recovery" | "unavailable";
+}
+export interface UpdateTransaction {
+    readonly schema: typeof UPDATE_JOURNAL_SCHEMA;
+    readonly transactionId: string;
+    readonly channel: UpdateChannel;
+    readonly targetVersion: string;
+    readonly packageRoot: string;
+    readonly priorActiveReleaseId: string | null;
+    readonly phase: UpdateTransactionPhase;
+    readonly status: "active" | "completed" | "rolled-back" | "failed";
+    readonly error: string | null;
+    readonly recovery?: UpdateRecoveryState;
+    readonly startedAt: string;
+    readonly updatedAt: string;
+}
+/** Persists the durable update journal and permits only validated forward transaction phases. */
+export declare class UpdateTransactionStore {
+    #private;
+    readonly path: string;
+    constructor(dataDir: string);
+    read(): Promise<UpdateTransaction | null>;
+    begin(input: {
+        channel: UpdateChannel;
+        targetVersion: string;
+        packageRoot: string;
+        priorActiveReleaseId: string | null;
+    }): Promise<UpdateTransaction>;
+    advance(phase: UpdateTransactionPhase): Promise<UpdateTransaction>;
+    setRecovery(recovery: UpdateRecoveryState): Promise<UpdateTransaction>;
+    finish(status: "completed" | "rolled-back" | "failed", error?: string | null): Promise<UpdateTransaction>;
+    clearCompleted(): Promise<void>;
+}

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

@@ -0,0 +1,101 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, open, readFile, rename, rm } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { PRODUCT_IDENTITY, PRODUCT_TEXT } from "../../product-identity.js";
+export const UPDATE_JOURNAL_SCHEMA = PRODUCT_IDENTITY.protocol.updateJournalSchema;
+/** Persists the durable update journal and permits only validated forward transaction phases. */
+export class UpdateTransactionStore {
+    path;
+    constructor(dataDir) { this.path = resolve(dataDir, "update-transaction.json"); }
+    async read() {
+        try {
+            const value = JSON.parse(await readFile(this.path, "utf8"));
+            validate(value);
+            return value;
+        }
+        catch (error) {
+            if (error instanceof Error && "code" in error && error.code === "ENOENT")
+                return null;
+            throw error;
+        }
+    }
+    async begin(input) {
+        const current = await this.read();
+        if (current?.status === "active") {
+            if (current.targetVersion !== input.targetVersion || current.channel !== input.channel) {
+                throw new Error(PRODUCT_TEXT.diagnostic(`has unfinished update ${current.transactionId} targeting ${current.targetVersion}; reconcile it before starting ${input.targetVersion}`));
+            }
+            return current;
+        }
+        const now = new Date().toISOString();
+        return await this.#write({
+            schema: UPDATE_JOURNAL_SCHEMA,
+            transactionId: randomUUID(),
+            ...input,
+            phase: "shutdown-intent",
+            status: "active",
+            error: null,
+            startedAt: now,
+            updatedAt: now,
+        });
+    }
+    async advance(phase) {
+        const current = await this.#requiredActive();
+        if (phaseOrder(phase) < phaseOrder(current.phase))
+            return current;
+        return await this.#write({ ...current, phase, updatedAt: new Date().toISOString() });
+    }
+    async setRecovery(recovery) {
+        const current = await this.#requiredActive();
+        return await this.#write({ ...current, recovery, updatedAt: new Date().toISOString() });
+    }
+    async finish(status, error = null) {
+        const current = await this.read();
+        if (!current)
+            throw new Error(`no ${PRODUCT_TEXT.displayName} update transaction is recorded`);
+        return await this.#write({ ...current, status, error, updatedAt: new Date().toISOString() });
+    }
+    async clearCompleted() {
+        const current = await this.read();
+        if (current && current.status !== "active")
+            await rm(this.path, { force: true });
+    }
+    async #requiredActive() {
+        const current = await this.read();
+        if (!current || current.status !== "active")
+            throw new Error(`no active ${PRODUCT_TEXT.displayName} update transaction is recorded`);
+        return current;
+    }
+    async #write(value) {
+        validate(value);
+        await mkdir(dirname(this.path), { recursive: true, mode: 0o700 });
+        const temporary = `${this.path}.${process.pid}.${randomUUID()}.tmp`;
+        const file = await open(temporary, "wx", 0o600);
+        try {
+            await file.writeFile(JSON.stringify(value, null, 2));
+            await file.sync();
+        }
+        finally {
+            await file.close();
+        }
+        await rename(temporary, this.path);
+        return value;
+    }
+}
+function phaseOrder(phase) {
+    return ["shutdown-intent", "ownership-released", "package-installed", "materialized", "certified", "active-reference-committed", "supervisor-verified"].indexOf(phase);
+}
+function validate(value) {
+    if (value.schema !== UPDATE_JOURNAL_SCHEMA || typeof value.transactionId !== "string" || !["stable", "next"].includes(value.channel)
+        || typeof value.targetVersion !== "string" || typeof value.packageRoot !== "string" || typeof value.startedAt !== "string"
+        || typeof value.updatedAt !== "string" || phaseOrder(value.phase) < 0 || !["active", "completed", "rolled-back", "failed"].includes(value.status)
+        || (value.recovery !== undefined && !validRecovery(value.recovery))) {
+        throw new Error(`invalid ${PRODUCT_TEXT.displayName} update transaction journal`);
+    }
+}
+function validRecovery(value) {
+    return typeof value.capsulePath === "string" && ["prepared", "running", "package-installed", "recovery-launcher"].includes(value.status)
+        && (value.guardianPid === null || Number.isSafeInteger(value.guardianPid) && value.guardianPid > 0)
+        && (value.guardianStartIdentity === null || typeof value.guardianStartIdentity === "string")
+        && typeof value.cancellationRequested === "boolean" && ["pending", "target", "recovery", "unavailable"].includes(value.launcherDisposition);
+}

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

@@ -0,0 +1,119 @@
+import type { UpdateChannel } from "./types.js";
+import { type UpdateRecoveryState, type UpdateTransaction, type UpdateTransactionPhase } from "./update-transaction.js";
+import { type ProtectedPackageReplacementResult } from "./update-recovery.js";
+export declare const PRODUCT_PACKAGE: string;
+export type { UpdateChannel } from "./types.js";
+export interface ProcessRequest {
+    captureStdout: boolean;
+}
+export interface ProcessResult {
+    code: number | null;
+    stdout: string;
+}
+export type UpdateProcessRunner = (command: string, arguments_: readonly string[], request: ProcessRequest) => Promise<ProcessResult>;
+export interface UpdateFileSystem {
+    readFile(path: string): Promise<string>;
+    realpath(path: string): Promise<string>;
+    access?(path: string): Promise<void>;
+}
+export interface UpdateOutput {
+    stdout(message: string): void;
+    stderr(message: string): void;
+}
+export type UpdateMeasuredPhase = "package-version" | "target-resolution" | "global-root" | "ownership-release" | "npm-install" | "materialized" | "certified" | "active-reference-committed" | "warmup" | "supervisor-verified" | "transaction-complete";
+export interface UpdatePhaseTimingEvent {
+    readonly phase: UpdateMeasuredPhase;
+    readonly durationMs: number;
+}
+export interface UpdatePerformanceEvidence {
+    readonly fileCount: number;
+    readonly sourceReads: number;
+    readonly candidateWrites: number;
+    readonly verificationReads: number;
+    readonly layerWrites?: number;
+    readonly layerReusedFiles?: number;
+    readonly layerReusedBytes?: number;
+    readonly payloadExcludedFiles?: number;
+    readonly payloadExcludedBytes?: number;
+    readonly warmupDurationMs?: number;
+    readonly postNpmDurationMs: number;
+}
+export interface SelfUpdateOptions {
+    packageRoot: string;
+    channel?: UpdateChannel;
+    /** A specific preview to install, named by its development number or full version. */
+    target?: string;
+    environment?: NodeJS.ProcessEnv;
+    fileSystem?: UpdateFileSystem;
+    output?: UpdateOutput;
+    runner?: UpdateProcessRunner;
+    lifecycle?: UpdateLifecycleCoordinator;
+    transactionStore?: UpdateTransactionJournal;
+    /** Test seam for protected global package replacement. */
+    packageReplacement?: (input: UpdatePackageReplacementInput) => Promise<ProtectedPackageReplacementResult>;
+    /** Test or embedding seam for post-activation release maintenance. */
+    maintenance?: () => Promise<void>;
+    progress?: boolean;
+    onPhaseTiming?: (event: UpdatePhaseTimingEvent) => void;
+    now?: () => number;
+}
+export type UpdateActivationPhase = Extract<UpdateTransactionPhase, "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 UpdateLifecycleCoordinator {
+    targetIsActive(targetVersion: string): Promise<boolean>;
+    shutdownVerifiedOwners(targetVersion: string): Promise<{
+        priorActiveVersion: string | null;
+    }>;
+    verifyPackageUnlocked(packageRoot: string): Promise<void>;
+    activateInstalled(packageRoot: string, targetVersion: string, phase: (phase: UpdateActivationPhase) => Promise<void>, onMaterializing?: (progress: UpdateMaterializationProgress) => void, onWarmup?: (state: "started" | "completed") => void): Promise<void>;
+}
+export interface UpdateTransactionJournal {
+    readonly path: string;
+    read(): Promise<UpdateTransaction | null>;
+    begin(input: {
+        channel: UpdateChannel;
+        targetVersion: string;
+        packageRoot: string;
+        priorActiveReleaseId: string | null;
+    }): Promise<UpdateTransaction>;
+    advance(phase: UpdateTransactionPhase): Promise<UpdateTransaction>;
+    setRecovery?(recovery: UpdateRecoveryState): Promise<UpdateTransaction>;
+    finish(status: "completed" | "rolled-back" | "failed", error?: string | null): Promise<UpdateTransaction>;
+    clearCompleted(): Promise<void>;
+}
+export interface UpdatePackageReplacementInput {
+    readonly dataDir: string;
+    readonly globalRoot: string;
+    readonly packageRoot: string;
+    readonly transaction: UpdateTransaction;
+    readonly priorRelease: {
+        readonly releaseId: string;
+        readonly releaseRoot: string;
+        readonly contentDigest: string;
+    };
+    readonly output: UpdateOutput;
+    readonly environment: NodeJS.ProcessEnv;
+    readonly onRecoveryState: (state: UpdateRecoveryState) => Promise<void>;
+}
+export declare function createNpmProcessRunner(platform?: NodeJS.Platform): UpdateProcessRunner;
+export type UpdateOwnershipAction = "clean-dead-record" | "leave-running" | "end-session";
+/**
+ * What an update does about the owner it found. A cohort running from retained immutable
+ * content keeps its work: the installation replaces files it does not read, and it listens on
+ * its own endpoint. A cohort running from the mutable installation is the one exception,
+ * because that installation is exactly what is about to be replaced under it.
+ */
+export declare function planUpdateOwnership(ownership: "live-verified" | "dead", runsFromRetainedRelease: boolean): UpdateOwnershipAction;
+export declare function createUpdateLifecycleCoordinator(environment?: NodeJS.ProcessEnv, fileSystem?: UpdateFileSystem, output?: UpdateOutput): UpdateLifecycleCoordinator;
+/** Renders the terminal-only update meter; the visual preview shares this exact frame. */
+export declare function renderUpdateProgressBar(percent: number): string;
+export declare function runSelfUpdate(options: SelfUpdateOptions): Promise<number>;
+export declare function assertUpdatePerformanceBudget(evidence: UpdatePerformanceEvidence, maximumPostNpmDurationMs?: number): void;