@timurproko/a1 0.1.8-dev.ece8cef → 0.2.1-dev.590

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

@@ -1,89 +0,0 @@
-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;
-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 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)) {
-        throw new Error(`invalid ${PRODUCT_TEXT.displayName} update transaction journal`);
-    }
-}

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

@@ -1,80 +0,0 @@
-import { type UpdateTransaction, type UpdateTransactionPhase } from "./update-transaction.js";
-export declare const PRODUCT_PACKAGE: string;
-export type UpdateChannel = "stable" | "next";
-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" | "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 postNpmDurationMs: number;
-}
-export interface SelfUpdateOptions {
-    packageRoot: string;
-    channel?: UpdateChannel;
-    environment?: NodeJS.ProcessEnv;
-    fileSystem?: UpdateFileSystem;
-    output?: UpdateOutput;
-    runner?: UpdateProcessRunner;
-    lifecycle?: UpdateLifecycleCoordinator;
-    transactionStore?: UpdateTransactionJournal;
-    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): 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>;
-    finish(status: "completed" | "rolled-back" | "failed", error?: string | null): Promise<UpdateTransaction>;
-    clearCompleted(): Promise<void>;
-}
-export declare function createNpmProcessRunner(platform?: NodeJS.Platform): UpdateProcessRunner;
-export declare function createUpdateLifecycleCoordinator(environment?: NodeJS.ProcessEnv, fileSystem?: UpdateFileSystem, output?: UpdateOutput): UpdateLifecycleCoordinator;
-export declare function runSelfUpdate(options: SelfUpdateOptions): Promise<number>;
-export declare function assertUpdatePerformanceBudget(evidence: UpdatePerformanceEvidence, maximumPostNpmDurationMs?: number): void;

package/dist/src/foundation/release/update.js

@@ -1,458 +0,0 @@
-import { spawn } from "node:child_process";
-import { access, readFile, realpath } from "node:fs/promises";
-import { connect } from "node:net";
-import { isAbsolute, relative, resolve, sep } from "node:path";
-import crossSpawn from "cross-spawn";
-import { valid as validSemver } from "semver";
-import { PRODUCT_IDENTITY, PRODUCT_TEXT } from "../../product-identity.js";
-import { certifyMaterializedRelease, probeOwnership, readEndpointMetadata, removeEndpointArtifacts, startSupervisor, waitForProcessExit, waitForVerifiedEndpoint, } from "./bootstrap.js";
-import { resolveProductPaths } from "../lifecycle/index.js";
-import { encodeFrame, LineFrameDecoder } from "../protocol/index.js";
-import { CohortStateStore } from "./cohort-state.js";
-import { cleanupVerifiedOwner, processIsAlive } from "./process-cleanup.js";
-import { materializeRelease, readMaterializedRelease } from "./release-store.js";
-import { UpdateTransactionStore } from "./update-transaction.js";
-export const PRODUCT_PACKAGE = PRODUCT_TEXT.packageName;
-const UPDATE_DIST_TAGS = { stable: "latest", next: "next" };
-const defaultFileSystem = {
-    async readFile(path) { return await readFile(path, "utf8"); },
-    realpath,
-    access,
-};
-const defaultOutput = {
-    stdout(message) { process.stdout.write(message); },
-    stderr(message) { process.stderr.write(message); },
-};
-export function createNpmProcessRunner(platform = process.platform) {
-    return async (command, arguments_, request) => await new Promise((resolvePromise, rejectPromise) => {
-        const stdio = request.captureStdout ? ["ignore", "pipe", "inherit"] : ["inherit", "inherit", "inherit"];
-        const child = platform === "win32" ? crossSpawn(command, [...arguments_], { stdio }) : spawn(command, [...arguments_], { stdio });
-        const stdout = [];
-        child.stdout?.on("data", chunk => stdout.push(Buffer.from(chunk)));
-        let settled = false;
-        child.once("error", error => { if (!settled) {
-            settled = true;
-            rejectPromise(error);
-        } });
-        child.once("close", code => { if (!settled) {
-            settled = true;
-            resolvePromise({ code, stdout: Buffer.concat(stdout).toString("utf8") });
-        } });
-    });
-}
-export function createUpdateLifecycleCoordinator(environment = process.env, fileSystem = defaultFileSystem, output = defaultOutput) {
-    const paths = resolveProductPaths(environment);
-    const stateStore = new CohortStateStore(paths.dataDir);
-    return {
-        async targetIsActive(targetVersion) {
-            const state = await stateStore.read();
-            const activeId = state.references.active;
-            if (!activeId || state.releases[activeId]?.packageVersion !== targetVersion)
-                return false;
-            const endpoint = await readEndpointMetadata(paths.endpointMetadataPath);
-            return endpoint?.releaseId === activeId && await probeOwnership(endpoint) === "live-verified";
-        },
-        async shutdownVerifiedOwners(targetVersion) {
-            const state = await stateStore.read();
-            const priorActiveVersion = state.references.active ? state.releases[state.references.active]?.packageVersion ?? null : null;
-            const endpoint = await readEndpointMetadata(paths.endpointMetadataPath);
-            if (!endpoint)
-                return { priorActiveVersion };
-            const ownership = await probeOwnership(endpoint);
-            if (ownership !== "live-verified" && ownership !== "dead") {
-                throw new Error(PRODUCT_TEXT.diagnostic(`refused update shutdown because supervisor ownership is ${ownership}`));
-            }
-            const immutableRoot = await canonicalImmutableRoot(paths.dataDir, endpoint.releaseRoot);
-            const legacyMutableInstall = ownership === "live-verified" && !immutableRoot;
-            const identity = ownership === "dead"
-                ? { accepted: false, reason: "recorded owner is dead" }
-                : await requestUpdateShutdown(endpoint, targetVersion, 2_000);
-            if (!identity.accepted && processIsAlive(endpoint.pid)) {
-                // Explicit update consent permits bounded cleanup of an authenticated
-                // older owner that predates the update-shutdown message.
-                const cleanup = await cleanupVerifiedOwner(endpoint, {
-                    allowLiveInstances: true,
-                    reason: legacyMutableInstall ? "legacy-mutable-install" : "explicit-update",
-                });
-                if (!cleanup.terminated)
-                    throw new Error(`verified ${PRODUCT_TEXT.displayName} owner ${endpoint.pid} rejected shutdown and could not be terminated: ${identity.reason}`);
-            }
-            else if (identity.accepted) {
-                await waitForProcessExit(endpoint.pid, 3_000).catch(async () => {
-                    const cleanup = await cleanupVerifiedOwner(endpoint, {
-                        allowLiveInstances: true,
-                        reason: legacyMutableInstall ? "legacy-mutable-install" : "explicit-update",
-                    });
-                    if (!cleanup.terminated)
-                        throw new Error(`verified ${PRODUCT_TEXT.displayName} owner ${endpoint.pid} did not terminate`);
-                });
-            }
-            await removeEndpointArtifacts(paths.endpointMetadataPath, paths.endpoint);
-            return { priorActiveVersion };
-        },
-        async verifyPackageUnlocked(packageRoot) {
-            if (fileSystem.access)
-                await fileSystem.access(packageRoot);
-            const probe = `${packageRoot}.${PRODUCT_IDENTITY.filesystem.slug}-unlock-probe`;
-            const { rename } = await import("node:fs/promises");
-            try {
-                await rename(packageRoot, probe);
-                await rename(probe, packageRoot);
-            }
-            catch (error) {
-                // Best-effort rollback if the first rename succeeded and the second did not.
-                await rename(probe, packageRoot).catch(() => { });
-                throw new Error(PRODUCT_TEXT.diagnostic(`package remains locked after verified shutdown: ${errorMessage(error)}`));
-            }
-        },
-        async activateInstalled(packageRoot, targetVersion, phase, onMaterializing) {
-            let total = 0;
-            let completed = 0;
-            const candidate = await materializeRelease(packageRoot, paths.dataDir, {
-                onProgress: event => {
-                    total = event.fileCount;
-                    onMaterializing?.({ completed, total });
-                },
-                onOperation: event => {
-                    if (event.operation !== "candidate-write")
-                        return;
-                    completed += 1;
-                    onMaterializing?.({ completed, total });
-                },
-            });
-            if (candidate.packageVersion !== targetVersion)
-                throw new Error(`installed ${PRODUCT_TEXT.displayName} version ${candidate.packageVersion} does not match target ${targetVersion}`);
-            await stateStore.recordCandidate(candidate);
-            await phase("materialized");
-            const diagnostics = await certifyMaterializedRelease(candidate, paths.dataDir);
-            await stateStore.approve(candidate.releaseId, diagnostics);
-            await phase("certified");
-            await stateStore.activate(candidate.releaseId);
-            await phase("active-reference-committed");
-            await startSupervisor(candidate, environment);
-            await waitForVerifiedEndpoint(paths.endpointMetadataPath, candidate, 8_000);
-        },
-    };
-}
-const PROGRESS_BAR_WIDTH = 39;
-const PROGRESS_TICK_MS = 200;
-/**
- * Copying the release owns 78–92 and is reported file by file, so the bar crosses
- * that span with the work rather than parking at its start. What follows is short,
- * which is why the remaining milestones sit close together.
- */
-const MATERIALIZE_PROGRESS = Object.freeze({ from: 78, to: 92 });
-const ACTIVATION_PROGRESS = {
-    materialized: { at: 92, creepTo: 94 },
-    certified: { at: 94, creepTo: 96 },
-    "active-reference-committed": { at: 96, creepTo: 99 },
-};
-function renderProgressBar(percent) {
-    const bounded = Math.min(100, Math.max(0, Math.round(percent)));
-    const filled = Math.round((bounded / 100) * PROGRESS_BAR_WIDTH);
-    return `${"█".repeat(filled)}${"░".repeat(PROGRESS_BAR_WIDTH - filled)} ${bounded}%`;
-}
-function createUpdateProgress(output, enabled) {
-    let visible = false;
-    let current = 0;
-    let shown = -1;
-    let timer = null;
-    const draw = () => {
-        const rounded = Math.round(current);
-        if (rounded === shown)
-            return;
-        shown = rounded;
-        visible = true;
-        output.stdout(`\r${renderProgressBar(rounded)}`);
-    };
-    const stopCreep = () => {
-        if (timer !== null) {
-            clearInterval(timer);
-            timer = null;
-        }
-    };
-    return {
-        set(percent, creepTo = percent) {
-            if (!enabled)
-                return;
-            stopCreep();
-            current = Math.max(current, percent);
-            shown = -1;
-            draw();
-            if (creepTo <= current)
-                return;
-            // Creep asymptotically toward (but never reach) the next milestone so
-            // long opaque phases such as npm install still show visible motion. The
-            // ceiling stays a whole point below the milestone: settling on `creepTo`
-            // itself would render as that milestone and make arriving at it invisible,
-            // which is what a stalled bar looks like.
-            timer = setInterval(() => {
-                current = Math.min(creepTo - 1, current + (creepTo - current) * 0.04);
-                draw();
-            }, PROGRESS_TICK_MS);
-            timer.unref?.();
-        },
-        finish() {
-            stopCreep();
-            if (!visible)
-                return;
-            output.stdout(`\r${renderProgressBar(100)}\n`);
-            visible = false;
-        },
-        clear() {
-            stopCreep();
-            if (!visible)
-                return;
-            output.stdout(`\r${" ".repeat(PROGRESS_BAR_WIDTH + 6)}\r`);
-            visible = false;
-            shown = -1;
-        },
-    };
-}
-export async function runSelfUpdate(options) {
-    const fileSystem = options.fileSystem ?? defaultFileSystem;
-    const output = options.output ?? defaultOutput;
-    const runner = options.runner ?? createNpmProcessRunner();
-    const channel = options.channel ?? "stable";
-    const distTag = UPDATE_DIST_TAGS[channel];
-    const now = options.now ?? (() => performance.now());
-    const measure = async (phase, operation) => {
-        const startedAt = now();
-        try {
-            return await operation();
-        }
-        finally {
-            options.onPhaseTiming?.({ phase, durationMs: Math.max(0, now() - startedAt) });
-        }
-    };
-    let runningVersion;
-    try {
-        const packageJson = JSON.parse(await measure("package-version", async () => await fileSystem.readFile(resolve(options.packageRoot, "package.json"))));
-        const parsedVersion = typeof packageJson.version === "string" ? validSemver(packageJson.version) : null;
-        if (parsedVersion === null)
-            throw new Error("package.json does not contain a valid semantic version");
-        runningVersion = parsedVersion;
-    }
-    catch (error) {
-        output.stderr(`${PRODUCT_TEXT.diagnostic(`could not read its running package version: ${errorMessage(error)}`)}\n`);
-        return 1;
-    }
-    const targetLookup = await measure("target-resolution", async () => await runNpm(runner, ["view", `${PRODUCT_PACKAGE}@${distTag}`, "version"], true, output, `query the npm ${distTag} channel`));
-    if (targetLookup.result === null)
-        return targetLookup.exitCode;
-    const targetVersion = validSemver(targetLookup.result.stdout.trim());
-    if (targetVersion === null) {
-        output.stderr(`${PRODUCT_TEXT.diagnostic(`received a malformed ${distTag} version from npm: ${JSON.stringify(targetLookup.result.stdout.trim())}.`)}\n`);
-        return 1;
-    }
-    output.stdout(`${PRODUCT_TEXT.commandName} update (${channel}): ${runningVersion} → ${targetVersion}.\n`);
-    const progress = createUpdateProgress(output, options.progress ?? (options.output === undefined && process.stdout.isTTY === true));
-    const rootLookup = await measure("global-root", async () => await runNpm(runner, ["root", "--global"], true, output, "resolve npm's global package root"));
-    if (rootLookup.result === null)
-        return rootLookup.exitCode;
-    if (rootLookup.result.stdout.trim().length === 0) {
-        output.stderr(`${PRODUCT_TEXT.diagnostic("could not verify its installation because npm returned an empty global package root.")}\n`);
-        return 1;
-    }
-    let packageRoot;
-    let globalRoot;
-    try {
-        [packageRoot, globalRoot] = await Promise.all([fileSystem.realpath(options.packageRoot), fileSystem.realpath(rootLookup.result.stdout.trim())]);
-    }
-    catch (error) {
-        output.stderr(`${PRODUCT_TEXT.diagnostic(`could not canonicalize the running and global npm paths: ${errorMessage(error)}`)}\n`);
-        return 1;
-    }
-    if (!isContainedBy(globalRoot, packageRoot)) {
-        output.stderr(`${PRODUCT_TEXT.diagnostic(`refused to update automatically because ${packageRoot} is not managed beneath npm's global package root ${globalRoot}.`)}\n`);
-        return 1;
-    }
-    const environment = options.environment ?? process.env;
-    const paths = resolveProductPaths(environment);
-    const lifecycle = options.lifecycle ?? createUpdateLifecycleCoordinator(environment, fileSystem, output);
-    const transactionStore = options.transactionStore ?? new UpdateTransactionStore(paths.dataDir);
-    let transaction = await transactionStore.read();
-    try {
-        if (await lifecycle.targetIsActive(targetVersion)) {
-            if (transaction?.status === "active") {
-                await transactionStore.advance("supervisor-verified");
-                await transactionStore.finish("completed");
-            }
-            await transactionStore.clearCompleted();
-            output.stdout(`${PRODUCT_TEXT.commandName} is up to date — no update needed.\n`);
-            return 0;
-        }
-        // The bar first appears here so a no-change run never flashes it.
-        progress.set(3, 15);
-        const cohortState = await new CohortStateStore(paths.dataDir).read();
-        transaction = await transactionStore.begin({
-            channel,
-            targetVersion,
-            packageRoot,
-            priorActiveReleaseId: cohortState.references.active,
-        });
-        if (phaseBefore(transaction.phase, "ownership-released")) {
-            await measure("ownership-release", async () => {
-                await lifecycle.shutdownVerifiedOwners(targetVersion);
-                await lifecycle.verifyPackageUnlocked(packageRoot);
-            });
-            transaction = await transactionStore.advance("ownership-released");
-        }
-        progress.set(15, 70);
-        if (phaseBefore(transaction.phase, "package-installed")) {
-            const installation = await measure("npm-install", async () => await runNpm(runner, ["install", "--global", "--loglevel=error", "--no-fund", "--no-audit", `${PRODUCT_PACKAGE}@${targetVersion}`], true, output, "start the global npm installation", false));
-            if (installation.result === null)
-                throw new UpdateFailure(installation.exitCode, "npm process failed");
-            if (installation.result.code !== 0) {
-                if (installation.result.stdout.trim().length > 0)
-                    output.stderr(`${installation.result.stdout.trimEnd()}\n`);
-                throw new UpdateFailure(unsuccessfulCode(installation.result.code), `npm exited with status ${formatExitCode(installation.result.code)}`);
-            }
-            transaction = await transactionStore.advance("package-installed");
-        }
-        progress.set(70, 75);
-        // Ownership can be reacquired after an interrupted installation (for
-        // example, if bare A1 is launched before the update is resumed). Recheck
-        // immediately before activation so recovery cannot start a second cohort.
-        await measure("ownership-release", async () => { await lifecycle.shutdownVerifiedOwners(targetVersion); });
-        progress.set(75, MATERIALIZE_PROGRESS.from);
-        let activationPhaseStartedAt = now();
-        await lifecycle.activateInstalled(packageRoot, targetVersion, async (phase) => {
-            options.onPhaseTiming?.({ phase, durationMs: Math.max(0, now() - activationPhaseStartedAt) });
-            transaction = await transactionStore.advance(phase);
-            progress.set(ACTIVATION_PROGRESS[phase].at, ACTIVATION_PROGRESS[phase].creepTo);
-            activationPhaseStartedAt = now();
-        }, ({ completed, total }) => {
-            const span = MATERIALIZE_PROGRESS.to - MATERIALIZE_PROGRESS.from;
-            const done = total > 0 ? Math.min(1, completed / total) : 0;
-            progress.set(MATERIALIZE_PROGRESS.from + span * done);
-        });
-        options.onPhaseTiming?.({ phase: "supervisor-verified", durationMs: Math.max(0, now() - activationPhaseStartedAt) });
-        const transactionStartedAt = now();
-        await transactionStore.advance("supervisor-verified");
-        await transactionStore.finish("completed");
-        await transactionStore.clearCompleted();
-        options.onPhaseTiming?.({ phase: "transaction-complete", durationMs: Math.max(0, now() - transactionStartedAt) });
-        progress.finish();
-        output.stdout(`${PRODUCT_TEXT.commandName} updated successfully: ${targetVersion} (${channel}).\n`);
-        return 0;
-    }
-    catch (error) {
-        progress.clear();
-        const message = errorMessage(error);
-        const rollback = options.lifecycle
-            ? "previous test lifecycle retained"
-            : await rollbackPriorCohort(paths.dataDir, environment, transaction?.priorActiveReleaseId ?? null).catch(rollbackError => `rollback failed: ${errorMessage(rollbackError)}`);
-        if (transaction)
-            await transactionStore.finish(rollback === "rolled back" ? "rolled-back" : "failed", `${message}; ${rollback}`);
-        output.stderr(`${PRODUCT_TEXT.diagnostic(`update failed: ${message}. ${rollback}. Diagnostics: ${transactionStore.path}`)}\n`);
-        return error instanceof UpdateFailure ? error.exitCode : 1;
-    }
-}
-export function assertUpdatePerformanceBudget(evidence, maximumPostNpmDurationMs = 30_000) {
-    const failures = [];
-    if (evidence.fileCount < 1)
-        failures.push("fixture contains no payload files");
-    if (evidence.sourceReads !== evidence.fileCount)
-        failures.push(`source payload read count is ${evidence.sourceReads} for ${evidence.fileCount} files`);
-    if (evidence.candidateWrites !== evidence.fileCount)
-        failures.push(`candidate payload write count is ${evidence.candidateWrites} for ${evidence.fileCount} files`);
-    if (evidence.verificationReads > 0)
-        failures.push(`fresh certification reread ${evidence.verificationReads} candidate files`);
-    if (evidence.postNpmDurationMs > maximumPostNpmDurationMs)
-        failures.push(`post-npm activation took ${Math.round(evidence.postNpmDurationMs)}ms; budget is ${maximumPostNpmDurationMs}ms`);
-    if (failures.length > 0)
-        throw new Error(`update performance budget failed: ${failures.join("; ")}`);
-}
-async function requestUpdateShutdown(metadata, targetVersion, timeoutMs) {
-    if (!processIsAlive(metadata.pid))
-        return { accepted: false, reason: "recorded owner is dead" };
-    return await new Promise(resolvePromise => {
-        const socket = connect(metadata.endpoint);
-        const decoder = new LineFrameDecoder();
-        let settled = false;
-        const finish = (value) => {
-            if (settled)
-                return;
-            settled = true;
-            socket.destroy();
-            resolvePromise(value);
-        };
-        socket.once("error", () => finish({ accepted: false, reason: "verified endpoint did not respond" }));
-        socket.once("connect", () => socket.write(encodeFrame({ type: "release-update-ownership", bootNonce: metadata.bootNonce, targetVersion })));
-        socket.on("data", chunk => {
-            try {
-                const message = decoder.push(chunk)[0];
-                if (message?.type === "release-update-result")
-                    finish({ accepted: message.accepted === true, reason: String(message.reason ?? "shutdown rejected") });
-            }
-            catch {
-                finish({ accepted: false, reason: "invalid shutdown response" });
-            }
-        });
-        setTimeout(() => finish({ accepted: false, reason: "verified endpoint shutdown timed out" }), timeoutMs).unref();
-    });
-}
-async function runNpm(runner, arguments_, captureStdout, output, action, reportNonzero = true) {
-    let result;
-    try {
-        result = await runner("npm", arguments_, { captureStdout });
-    }
-    catch (error) {
-        output.stderr(`${PRODUCT_TEXT.diagnostic(`could not execute npm to ${action}: ${errorMessage(error)}`)}\n`);
-        return { result: null, exitCode: 1 };
-    }
-    if (result.code !== 0 && reportNonzero) {
-        output.stderr(`${PRODUCT_TEXT.diagnostic(`could not ${action}; npm exited with status ${formatExitCode(result.code)}. Review npm's diagnostics above.`)}\n`);
-        return { result: null, exitCode: unsuccessfulCode(result.code) };
-    }
-    return { result, exitCode: 0 };
-}
-async function rollbackPriorCohort(dataDir, environment, priorReleaseId) {
-    if (!priorReleaseId)
-        return "no prior cohort was available for rollback";
-    const stateStore = new CohortStateStore(dataDir);
-    const state = await stateStore.read();
-    const prior = state.releases[priorReleaseId];
-    if (!prior || prior.approval !== "approved")
-        return "prior cohort is not a verified rollback candidate";
-    if (state.references.active !== priorReleaseId) {
-        if (state.references.rollback === priorReleaseId)
-            await stateStore.rollback(true);
-        else
-            throw new Error(`prior release ${priorReleaseId} is not the recorded rollback cohort`);
-    }
-    const release = await readMaterializedRelease(prior.releaseRoot);
-    const paths = resolveProductPaths(environment);
-    await startSupervisor(release, environment);
-    await waitForVerifiedEndpoint(paths.endpointMetadataPath, release, 8_000);
-    return "rolled back";
-}
-function phaseBefore(current, target) {
-    const phases = ["shutdown-intent", "ownership-released", "package-installed", "materialized", "certified", "active-reference-committed", "supervisor-verified"];
-    return phases.indexOf(current) < phases.indexOf(target);
-}
-class UpdateFailure extends Error {
-    exitCode;
-    constructor(exitCode, message) {
-        super(message);
-        this.exitCode = exitCode;
-    }
-}
-async function canonicalImmutableRoot(dataDir, releaseRoot) {
-    try {
-        const [store, selected] = await Promise.all([realpath(resolve(dataDir, "releases")), realpath(releaseRoot)]);
-        const fromStore = relative(store, selected);
-        return fromStore.length > 0 && fromStore !== ".." && !fromStore.startsWith(`..${sep}`) && !isAbsolute(fromStore);
-    }
-    catch {
-        return false;
-    }
-}
-function isContainedBy(parent, child) {
-    const pathFromParent = relative(parent, child);
-    return pathFromParent.length > 0 && pathFromParent !== ".." && !pathFromParent.startsWith(`..${sep}`) && !isAbsolute(pathFromParent);
-}
-function unsuccessfulCode(code) { return code === null || code === 0 ? 1 : code; }
-function formatExitCode(code) { return code === null ? "unknown" : String(code); }
-function errorMessage(error) { return error instanceof Error ? error.message : String(error); }