@astralyn/sash 0.1.0 → 0.1.2

package/dist/core-update.js

@@ -1,804 +1,168 @@
 import fs from "node:fs";
 import { verifyCoreExecutable } from "./core.js";
-import { installRecordsEqual, parseInstallRecord, readInstallRecord, validateCoreReleaseTag, writeInstallRecord, } from "./core-install-record.js";
+import { installRecordsEqual, parseInstallRecord, readInstallRecord, writeInstallRecord, } from "./core-install-record.js";
 import { atomicWriteFileSync, durableRemoveFileSync, durableRenameSync, pathEntryExists, } from "./fs-atomic.js";
-import { hasExactOwnKeys, isCanonicalIsoTimestamp, isPlainObject } from "./json-shape.js";
+import { hasExactOwnKeys, isPlainObject } from "./json-shape.js";
 import { waitForBinaryUnlocked } from "./process.js";
-const UPDATE_TRANSACTION_SIZE_LIMIT = 16 * 1024;
-function parseTargetRecord(value, createdAt) {
-    const targetRecord = parseInstallRecord(value);
-    return targetRecord?.installedAt === createdAt ? targetRecord : undefined;
+function verifyBinary(file, version, verify) {
+    if (!fs.lstatSync(file).isFile())
+        throw new Error(`Core binary must be a regular file: ${file}`);
+    verify(file, version);
 }
-function parseNormalTransaction(value) {
-    if (!hasExactOwnKeys(value, [
-        "createdAt",
-        "deferredHealth",
-        "phase",
-        "previousRecord",
-        "targetRecord",
-        "version",
-    ]) ||
-        value.version !== 1 ||
-        (value.phase !== "prepared" &&
-            value.phase !== "swapped" &&
-            value.phase !== "health-verified") ||
-        !isCanonicalIsoTimestamp(value.createdAt) ||
-        typeof value.deferredHealth !== "boolean") {
-        return undefined;
-    }
-    let previousRecord = null;
-    if (value.previousRecord !== null) {
-        const parsedPrevious = parseInstallRecord(value.previousRecord);
-        if (!parsedPrevious)
-            return undefined;
-        previousRecord = parsedPrevious;
-    }
-    const targetRecord = parseTargetRecord(value.targetRecord, value.createdAt);
-    if (!targetRecord)
-        return undefined;
-    return {
-        version: 1,
-        phase: value.phase,
-        createdAt: value.createdAt,
-        previousRecord,
-        targetRecord,
-        deferredHealth: value.deferredHealth,
-    };
-}
-function parseRepairTransaction(value) {
-    if (!hasExactOwnKeys(value, [
-        "createdAt",
-        "deferredHealth",
-        "phase",
-        "previousRecord",
-        "repair",
-        "targetRecord",
-        "version",
-    ]) ||
-        value.version !== 2 ||
-        (value.phase !== "repair-prepared" &&
-            value.phase !== "repair-restoring" &&
-            value.phase !== "prepared" &&
-            value.phase !== "swapped" &&
-            value.phase !== "health-verified") ||
-        !isCanonicalIsoTimestamp(value.createdAt) ||
-        typeof value.deferredHealth !== "boolean" ||
-        value.previousRecord !== null ||
-        !isPlainObject(value.repair) ||
-        !hasExactOwnKeys(value.repair, ["binaryExisted", "installRecordExisted"]) ||
-        typeof value.repair.binaryExisted !== "boolean" ||
-        typeof value.repair.installRecordExisted !== "boolean" ||
-        (!value.repair.binaryExisted && !value.repair.installRecordExisted)) {
-        return undefined;
-    }
-    const targetRecord = parseTargetRecord(value.targetRecord, value.createdAt);
-    if (!targetRecord)
-        return undefined;
-    return {
-        version: 2,
-        phase: value.phase,
-        createdAt: value.createdAt,
-        previousRecord: null,
-        targetRecord,
-        deferredHealth: value.deferredHealth,
-        repair: {
-            binaryExisted: value.repair.binaryExisted,
-            installRecordExisted: value.repair.installRecordExisted,
-        },
-    };
-}
-function parseTransaction(value) {
-    if (!isPlainObject(value))
-        return undefined;
-    return value.version === 1
-        ? parseNormalTransaction(value)
-        : value.version === 2
-            ? parseRepairTransaction(value)
-            : undefined;
-}
-function backupPath(layout) {
-    return `${layout.coreExe}.bak`;
-}
-function repairBinaryBackupPath(layout) {
-    return `${layout.coreExe}.repair.bak`;
-}
-function repairInstallBackupPath(layout) {
-    return `${layout.installFile}.repair.bak`;
-}
-function defaultVerifier(exe, expectedVersion) {
-    verifyCoreExecutable(exe, 5000, expectedVersion);
-}
-function verifyTransactionBinary(file, expectedVersion, verifier, role) {
-    let stat;
-    try {
-        stat = fs.lstatSync(file);
-    }
-    catch (err) {
-        throw new Error(`${role} is missing: ${file}: ${err.message}`);
-    }
-    if (!stat.isFile())
-        throw new Error(`${role} is not a regular file: ${file}`);
-    try {
-        verifier(file, expectedVersion);
-    }
-    catch (err) {
-        throw new Error(`${role} does not match expected version ${expectedVersion}: ${file}: ${err.message}`);
-    }
-}
-function writeTransaction(transaction, layout) {
-    atomicWriteFileSync(layout.coreUpdateTransactionFile, `${JSON.stringify(transaction, null, 2)}\n`);
+function defaultVerifier(exe, version) {
+    verifyCoreExecutable(exe, 5000, version);
 }
 export function readCoreUpdateTransaction(layout) {
-    let stat;
+    let text;
     try {
-        stat = fs.lstatSync(layout.coreUpdateTransactionFile);
-    }
-    catch (err) {
-        if (err.code === "ENOENT")
+        const stat = fs.lstatSync(layout.coreUpdateTransactionFile);
+        if (!stat.isFile() || stat.size > 16 * 1024)
+            throw new Error("Core update journal must be a bounded regular file");
+        text = fs.readFileSync(layout.coreUpdateTransactionFile, "utf8");
+        if (Buffer.byteLength(text) > 16 * 1024)
+            throw new Error("Core update journal is too large");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
             return undefined;
-        throw new Error(`Cannot inspect Core update transaction ${layout.coreUpdateTransactionFile}: ${err.message}`);
-    }
-    if (!stat.isFile()) {
-        throw new Error(`Core update transaction is not a regular file: ${layout.coreUpdateTransactionFile}`);
-    }
-    if (stat.size > UPDATE_TRANSACTION_SIZE_LIMIT) {
-        throw new Error(`Core update transaction exceeds ${UPDATE_TRANSACTION_SIZE_LIMIT} bytes: ${layout.coreUpdateTransactionFile}`);
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(fs.readFileSync(layout.coreUpdateTransactionFile, "utf8"));
-    }
-    catch (err) {
-        throw new Error(`Core update transaction is not valid JSON: ${layout.coreUpdateTransactionFile} (${err.message})`);
-    }
-    const transaction = parseTransaction(parsed);
-    if (!transaction) {
-        throw new Error(`Core update transaction has an invalid version, phase, timestamp, records, repair snapshot, or shape: ${layout.coreUpdateTransactionFile}`);
-    }
-    return transaction;
-}
-function assertRollbackSlotsClear(layout) {
-    for (const file of [
-        backupPath(layout),
-        repairBinaryBackupPath(layout),
-        repairInstallBackupPath(layout),
-    ]) {
-        if (pathEntryExists(file))
-            throw new Error(`Previous Core rollback state still exists: ${file}`);
-    }
-}
-export function beginCoreUpdateTransaction(layout, targetVersion, previousRecord, deferredHealth, createdAt = new Date().toISOString()) {
-    const targetRecord = {
-        coreVersion: validateCoreReleaseTag(targetVersion),
-        installedAt: createdAt,
-    };
-    if (!isCanonicalIsoTimestamp(createdAt)) {
-        throw new Error(`Invalid Core update timestamp: ${createdAt}`);
-    }
-    if (readCoreUpdateTransaction(layout)) {
-        throw new Error(`A Core update transaction is already pending: ${layout.coreUpdateTransactionFile}`);
-    }
-    assertRollbackSlotsClear(layout);
-    const currentExists = pathEntryExists(layout.coreExe);
-    const installEntryExists = pathEntryExists(layout.installFile);
-    if (currentExists !== Boolean(previousRecord) || installEntryExists !== Boolean(previousRecord)) {
-        throw new Error("Cannot begin Core update with inconsistent binary/install metadata state");
-    }
-    const transaction = {
-        version: 1,
-        phase: "prepared",
-        createdAt,
-        previousRecord: previousRecord ?? null,
-        targetRecord,
-        deferredHealth,
-    };
-    writeTransaction(transaction, layout);
-    return transaction;
-}
-function isRegularFile(file) {
-    try {
-        return fs.lstatSync(file).isFile();
-    }
-    catch {
-        return false;
-    }
-}
-function assertRepairableCoreEntry(file, role) {
-    if (!pathEntryExists(file))
-        return;
-    if (fs.lstatSync(file).isDirectory()) {
-        throw new Error(`Cannot repair Core installation: ${role} path is a directory: ${file}`);
-    }
-}
-export function beginCoreRepairUpdateTransaction(layout, targetVersion, deferredHealth, createdAt = new Date().toISOString()) {
-    const targetRecord = {
-        coreVersion: validateCoreReleaseTag(targetVersion),
-        installedAt: createdAt,
-    };
-    if (!isCanonicalIsoTimestamp(createdAt)) {
-        throw new Error(`Invalid Core update timestamp: ${createdAt}`);
-    }
-    if (readCoreUpdateTransaction(layout)) {
-        throw new Error(`A Core update transaction is already pending: ${layout.coreUpdateTransactionFile}`);
-    }
-    assertRollbackSlotsClear(layout);
-    const binaryExisted = pathEntryExists(layout.coreExe);
-    const installRecordExisted = pathEntryExists(layout.installFile);
-    const previousRecord = readInstallRecord(layout);
-    if ((!binaryExisted && !installRecordExisted) ||
-        (binaryExisted && installRecordExisted && isRegularFile(layout.coreExe) && previousRecord)) {
-        throw new Error("Core installation does not require forced repair");
-    }
-    assertRepairableCoreEntry(layout.coreExe, "executable");
-    assertRepairableCoreEntry(layout.installFile, "install metadata");
-    const transaction = {
-        version: 2,
-        phase: "repair-prepared",
-        createdAt,
-        previousRecord: null,
-        targetRecord,
-        deferredHealth,
-        repair: { binaryExisted, installRecordExisted },
-    };
-    writeTransaction(transaction, layout);
-    return transaction;
-}
-function assertSameTransaction(expected, current) {
-    const sameRepair = expected.version === 1
-        ? current?.version === 1
-        : current?.version === 2 &&
-            current.repair.binaryExisted === expected.repair.binaryExisted &&
-            current.repair.installRecordExisted === expected.repair.installRecordExisted;
-    if (!current ||
-        current.version !== expected.version ||
-        current.createdAt !== expected.createdAt ||
-        current.targetRecord.coreVersion !== expected.targetRecord.coreVersion ||
-        current.targetRecord.installedAt !== expected.targetRecord.installedAt ||
-        !sameRepair) {
-        throw new Error("Core update transaction changed during publication");
-    }
-}
-export function quarantineCoreInstallationForUpdate(transaction, layout) {
-    const current = readCoreUpdateTransaction(layout);
-    assertSameTransaction(transaction, current);
-    if (current.version !== 2 || current.phase !== "repair-prepared") {
-        throw new Error("Core repair transaction is not ready for quarantine");
-    }
-    if (current.repair.binaryExisted) {
-        if (!pathEntryExists(layout.coreExe)) {
-            throw new Error("Core repair executable disappeared before quarantine");
-        }
-        durableRenameSync(layout.coreExe, repairBinaryBackupPath(layout));
-    }
-    else if (pathEntryExists(layout.coreExe)) {
-        throw new Error("Core executable appeared before repair quarantine");
-    }
-    if (current.repair.installRecordExisted) {
-        if (!pathEntryExists(layout.installFile)) {
-            throw new Error("Core install metadata disappeared before quarantine");
-        }
-        durableRenameSync(layout.installFile, repairInstallBackupPath(layout));
+        throw error;
     }
-    else if (pathEntryExists(layout.installFile)) {
-        throw new Error("Core install metadata appeared before repair quarantine");
-    }
-    if (pathEntryExists(layout.coreExe) ||
-        pathEntryExists(layout.installFile) ||
-        pathEntryExists(repairBinaryBackupPath(layout)) !== current.repair.binaryExisted ||
-        pathEntryExists(repairInstallBackupPath(layout)) !== current.repair.installRecordExisted) {
-        throw new Error("Core repair quarantine could not be verified");
-    }
-    const prepared = { ...current, phase: "prepared" };
-    writeTransaction(prepared, layout);
-    return prepared;
-}
-export function markCoreUpdateSwapped(transaction, layout) {
-    const current = readCoreUpdateTransaction(layout);
-    assertSameTransaction(transaction, current);
-    if (current.phase !== "prepared")
-        throw new Error("Core update is not ready to mark swapped");
-    const swapped = { ...current, phase: "swapped" };
-    writeTransaction(swapped, layout);
-    return swapped;
-}
-export function markCoreUpdateHealthVerified(transaction, layout) {
-    const current = readCoreUpdateTransaction(layout);
-    assertSameTransaction(transaction, current);
-    if (current.phase !== "swapped") {
-        throw new Error("Core update is not ready to mark health-verified");
+    const value = JSON.parse(text);
+    if (!isPlainObject(value) ||
+        !hasExactOwnKeys(value, ["version", "phase", "previous", "target"]) ||
+        value.version !== 1 ||
+        typeof value.phase !== "string" ||
+        !["prepared", "swapped", "verified"].includes(value.phase)) {
+        throw new Error("Invalid Core update journal");
     }
-    const verified = { ...current, phase: "health-verified" };
-    writeTransaction(verified, layout);
-    return verified;
+    const previous = value.previous === null ? null : parseInstallRecord(value.previous);
+    const target = parseInstallRecord(value.target);
+    if (previous === undefined || !target)
+        throw new Error("Invalid Core update install records");
+    return { version: 1, phase: value.phase, previous, target };
 }
-function markCoreRepairRestoring(transaction, layout) {
-    const current = readCoreUpdateTransaction(layout);
-    assertSameTransaction(transaction, current);
-    if (current.version !== 2)
-        throw new Error("Core update is not a repair transaction");
-    if (current.phase === "repair-restoring")
-        return current;
-    const restoring = { ...current, phase: "repair-restoring" };
-    writeTransaction(restoring, layout);
-    return restoring;
+function writeJournal(layout, transaction) {
+    atomicWriteFileSync(layout.coreUpdateTransactionFile, `${JSON.stringify(transaction, null, 2)}\n`);
 }
-export function clearCoreUpdateTransaction(layout) {
+function clearJournal(layout) {
     durableRemoveFileSync(layout.coreUpdateTransactionFile);
 }
-function restoreInstallRecord(record, layout) {
-    if (record)
-        writeInstallRecord(record, layout);
-    else
-        durableRemoveFileSync(layout.installFile);
-}
-function rollbackNormalCoreUpdate(transaction, layout, verifier) {
-    const backup = backupPath(layout);
-    const currentExists = pathEntryExists(layout.coreExe);
-    const backupExists = pathEntryExists(backup);
-    if (transaction.previousRecord) {
-        if (backupExists) {
-            verifyTransactionBinary(backup, transaction.previousRecord.coreVersion, verifier, "Core rollback backup");
-            if (currentExists) {
-                verifyTransactionBinary(layout.coreExe, transaction.targetRecord.coreVersion, verifier, "Core update candidate");
+function restoreFiles(layout, transaction, verify) {
+    const backup = `${layout.coreExe}.bak`;
+    if (transaction.previous) {
+        if (pathEntryExists(backup)) {
+            verifyBinary(backup, transaction.previous.coreVersion, verify);
+            if (pathEntryExists(layout.coreExe)) {
+                verifyBinary(layout.coreExe, transaction.target.coreVersion, verify);
                 durableRemoveFileSync(layout.coreExe);
             }
             durableRenameSync(backup, layout.coreExe);
         }
         else {
-            if (!currentExists) {
-                throw new Error("Core update rollback has neither the previous binary nor its backup");
-            }
-            verifyTransactionBinary(layout.coreExe, transaction.previousRecord.coreVersion, verifier, "Previous Core binary");
+            verifyBinary(layout.coreExe, transaction.previous.coreVersion, verify);
         }
+        writeInstallRecord(transaction.previous, layout);
     }
     else {
-        if (backupExists) {
-            throw new Error(`Unexpected rollback backup for an update without a previous Core: ${backup}`);
-        }
-        if (currentExists) {
-            verifyTransactionBinary(layout.coreExe, transaction.targetRecord.coreVersion, verifier, "Core update candidate");
+        if (pathEntryExists(backup))
+            throw new Error("Unexpected Core backup for a first install");
+        if (pathEntryExists(layout.coreExe)) {
+            verifyBinary(layout.coreExe, transaction.target.coreVersion, verify);
             durableRemoveFileSync(layout.coreExe);
         }
-    }
-    restoreInstallRecord(transaction.previousRecord, layout);
-    clearCoreUpdateTransaction(layout);
-    return transaction.previousRecord;
-}
-function removeRepairCandidateBinary(transaction, layout, verifier) {
-    if (!pathEntryExists(layout.coreExe))
-        return;
-    verifyTransactionBinary(layout.coreExe, transaction.targetRecord.coreVersion, verifier, "Core repair candidate");
-    durableRemoveFileSync(layout.coreExe);
-}
-function verifyRepairCandidateRecord(transaction, layout) {
-    const current = readInstallRecord(layout);
-    if (!installRecordsEqual(current, transaction.targetRecord)) {
-        throw new Error("Core repair candidate install metadata does not match its journal");
-    }
-}
-function removeRepairCandidateRecord(transaction, layout) {
-    if (!pathEntryExists(layout.installFile))
-        return;
-    verifyRepairCandidateRecord(transaction, layout);
-    durableRemoveFileSync(layout.installFile);
-}
-function assertRepairRollbackOwnership(transaction, layout, verifier) {
-    if (pathEntryExists(backupPath(layout))) {
-        throw new Error(`Core repair has an unexpected normal rollback slot: ${backupPath(layout)}`);
-    }
-    if (transaction.phase === "repair-restoring")
-        return;
-    const binaryCurrent = pathEntryExists(layout.coreExe);
-    const binaryBackup = pathEntryExists(repairBinaryBackupPath(layout));
-    if (transaction.repair.binaryExisted) {
-        if (transaction.phase === "repair-prepared") {
-            if (binaryCurrent === binaryBackup) {
-                throw new Error("Core repair cannot identify the original executable during rollback");
-            }
-        }
-        else if (!binaryBackup) {
-            throw new Error("Core repair rollback lost the quarantined executable");
+        if (pathEntryExists(layout.installFile)) {
+            if (!installRecordsEqual(readInstallRecord(layout), transaction.target))
+                throw new Error("Unrecognized Core install metadata; preserved for inspection");
+            durableRemoveFileSync(layout.installFile);
         }
     }
-    else if (binaryBackup) {
-        throw new Error(`Core repair has an unexpected executable backup: ${repairBinaryBackupPath(layout)}`);
-    }
-    if (transaction.phase === "repair-prepared" &&
-        !transaction.repair.binaryExisted &&
-        binaryCurrent) {
-        throw new Error("Core executable appeared during repair preparation");
-    }
-    if (transaction.phase !== "repair-prepared" && binaryCurrent) {
-        verifyTransactionBinary(layout.coreExe, transaction.targetRecord.coreVersion, verifier, "Core repair candidate");
-    }
-    if ((transaction.phase === "swapped" || transaction.phase === "health-verified") &&
-        !binaryCurrent) {
-        throw new Error("Core repair candidate disappeared before rollback");
-    }
-    const installCurrent = pathEntryExists(layout.installFile);
-    const installBackup = pathEntryExists(repairInstallBackupPath(layout));
-    if (transaction.repair.installRecordExisted) {
-        if (transaction.phase === "repair-prepared") {
-            if (installCurrent === installBackup) {
-                throw new Error("Core repair cannot identify the original install metadata during rollback");
-            }
-        }
-        else if (!installBackup) {
-            throw new Error("Core repair rollback lost the quarantined install metadata");
-        }
-    }
-    else if (installBackup) {
-        throw new Error(`Core repair has an unexpected install metadata backup: ${repairInstallBackupPath(layout)}`);
-    }
-    if (transaction.phase === "repair-prepared") {
-        if (!transaction.repair.installRecordExisted && installCurrent) {
-            throw new Error("Core install metadata appeared during repair preparation");
-        }
-        return;
-    }
-    if (transaction.phase === "prepared") {
-        if (installCurrent) {
-            throw new Error("Core install metadata appeared before the candidate swap was journaled");
-        }
-        return;
-    }
-    const shouldHaveTargetRecord = transaction.phase === "health-verified" || transaction.deferredHealth;
-    if (shouldHaveTargetRecord !== installCurrent) {
-        throw new Error("Core repair candidate install metadata does not match its journal phase");
-    }
-    if (installCurrent)
-        verifyRepairCandidateRecord(transaction, layout);
 }
-function rollbackRepairCoreUpdate(transaction, layout, verifier) {
-    assertRepairRollbackOwnership(transaction, layout, verifier);
-    const restoring = markCoreRepairRestoring(transaction, layout);
-    const binaryBackup = repairBinaryBackupPath(layout);
-    const installBackup = repairInstallBackupPath(layout);
-    if (restoring.repair.binaryExisted) {
-        if (pathEntryExists(binaryBackup)) {
-            removeRepairCandidateBinary(restoring, layout, verifier);
-            durableRenameSync(binaryBackup, layout.coreExe);
-        }
-        else if (!pathEntryExists(layout.coreExe)) {
-            throw new Error("Core repair rollback lost the quarantined executable");
-        }
-    }
-    else {
-        if (pathEntryExists(binaryBackup)) {
-            throw new Error(`Core repair has an unexpected executable backup: ${binaryBackup}`);
-        }
-        removeRepairCandidateBinary(restoring, layout, verifier);
-    }
-    if (restoring.repair.installRecordExisted) {
-        if (pathEntryExists(installBackup)) {
-            removeRepairCandidateRecord(restoring, layout);
-            durableRenameSync(installBackup, layout.installFile);
-        }
-        else if (!pathEntryExists(layout.installFile)) {
-            throw new Error("Core repair rollback lost the quarantined install metadata");
-        }
-    }
-    else {
-        if (pathEntryExists(installBackup)) {
-            throw new Error(`Core repair has an unexpected install metadata backup: ${installBackup}`);
-        }
-        removeRepairCandidateRecord(restoring, layout);
-    }
-    if (pathEntryExists(binaryBackup) ||
-        pathEntryExists(installBackup) ||
-        pathEntryExists(layout.coreExe) !== restoring.repair.binaryExisted ||
-        pathEntryExists(layout.installFile) !== restoring.repair.installRecordExisted) {
-        throw new Error("Core repair rollback could not restore the exact prior entry presence");
-    }
-    clearCoreUpdateTransaction(layout);
-    return null;
-}
-export function rollbackCoreUpdateTransaction(layout, verifier = defaultVerifier) {
-    const transaction = readCoreUpdateTransaction(layout);
-    if (!transaction)
-        return undefined;
-    return transaction.version === 1
-        ? rollbackNormalCoreUpdate(transaction, layout, verifier)
-        : rollbackRepairCoreUpdate(transaction, layout, verifier);
-}
-function assertRepairBackupEntry(file, role) {
-    if (!pathEntryExists(file))
-        return;
-    if (fs.lstatSync(file).isDirectory()) {
-        throw new Error(`Pending Core repair ${role} backup is a directory: ${file}`);
-    }
-}
-function validatePendingRepairAssets(transaction, layout) {
-    if (pathEntryExists(backupPath(layout))) {
-        throw new Error(`Pending Core repair has an unexpected normal backup: ${backupPath(layout)}`);
-    }
-    const allowRemoved = transaction.phase === "health-verified";
-    const binaryBackup = repairBinaryBackupPath(layout);
-    const installBackup = repairInstallBackupPath(layout);
-    assertRepairBackupEntry(binaryBackup, "executable");
-    assertRepairBackupEntry(installBackup, "install metadata");
-    if (transaction.repair.binaryExisted && !allowRemoved && !pathEntryExists(binaryBackup)) {
-        throw new Error(`Pending Core repair is missing its executable backup: ${binaryBackup}`);
-    }
-    if (!transaction.repair.binaryExisted && pathEntryExists(binaryBackup)) {
-        throw new Error(`Pending Core repair has an unexpected executable backup: ${binaryBackup}`);
-    }
-    if (transaction.repair.installRecordExisted && !allowRemoved && !pathEntryExists(installBackup)) {
-        throw new Error(`Pending Core repair is missing its install metadata backup: ${installBackup}`);
-    }
-    if (!transaction.repair.installRecordExisted && pathEntryExists(installBackup)) {
-        throw new Error(`Pending Core repair has an unexpected install metadata backup: ${installBackup}`);
-    }
-}
-function validatePendingTransaction(transaction, layout, verifier) {
-    if (transaction.phase !== "swapped" && transaction.phase !== "health-verified") {
-        throw new Error("Core update is not pending a managed health decision");
+function finishVerified(layout, transaction, verify) {
+    verifyBinary(layout.coreExe, transaction.target.coreVersion, verify);
+    if (!installRecordsEqual(readInstallRecord(layout), transaction.target))
+        throw new Error("Verified Core install metadata changed");
+    const backup = `${layout.coreExe}.bak`;
+    if (pathEntryExists(backup)) {
+        if (!transaction.previous)
+            throw new Error("Unexpected backup for a first install");
+        verifyBinary(backup, transaction.previous.coreVersion, verify);
+        durableRemoveFileSync(backup);
     }
-    verifyTransactionBinary(layout.coreExe, transaction.targetRecord.coreVersion, verifier, "Pending Core update candidate");
-    if (transaction.version === 1) {
-        const backup = backupPath(layout);
-        if (transaction.previousRecord) {
-            if (pathEntryExists(backup)) {
-                verifyTransactionBinary(backup, transaction.previousRecord.coreVersion, verifier, "Pending Core rollback backup");
-            }
-            else if (transaction.phase !== "health-verified") {
-                throw new Error(`Pending Core update is missing its rollback backup: ${backup}`);
-            }
-        }
-        else if (pathEntryExists(backup)) {
-            throw new Error(`Pending first Core update has an unexpected rollback backup: ${backup}`);
-        }
-    }
-    else {
-        validatePendingRepairAssets(transaction, layout);
-    }
-    const currentRecord = readInstallRecord(layout);
-    if (!currentRecord && pathEntryExists(layout.installFile)) {
-        throw new Error("Pending Core update install metadata is malformed or non-regular");
-    }
-    const recordMatchesPhase = transaction.version === 2
-        ? transaction.phase === "health-verified" || transaction.deferredHealth
-            ? installRecordsEqual(currentRecord, transaction.targetRecord)
-            : currentRecord === undefined
-        : transaction.phase === "health-verified"
-            ? installRecordsEqual(currentRecord, transaction.targetRecord) ||
-                installRecordsEqual(currentRecord, transaction.previousRecord)
-            : installRecordsEqual(currentRecord, transaction.previousRecord ?? transaction.targetRecord);
-    if (!recordMatchesPhase) {
-        throw new Error("Pending Core update install metadata does not match its journal phase");
-    }
-}
-function rollbackRequired(transaction) {
-    return (transaction.phase === "repair-prepared" ||
-        transaction.phase === "repair-restoring" ||
-        transaction.phase === "prepared" ||
-        (!transaction.deferredHealth && transaction.phase === "swapped"));
+    clearJournal(layout);
 }
-export function recoverCoreUpdateTransaction(layout, verifier = defaultVerifier) {
+export function recoverCoreUpdateTransaction(layout, verify = defaultVerifier) {
     const transaction = readCoreUpdateTransaction(layout);
     if (!transaction) {
-        recoverLegacyInterruptedCoreUpdate(layout, verifier);
-        return undefined;
-    }
-    if (rollbackRequired(transaction)) {
-        rollbackCoreUpdateTransaction(layout, verifier);
-        return undefined;
-    }
-    validatePendingTransaction(transaction, layout, verifier);
-    if (transaction.phase === "health-verified") {
-        writeInstallRecord(transaction.targetRecord, layout);
-    }
-    return transaction;
-}
-export function pendingCoreUpdateVersion(layout) {
-    const transaction = readCoreUpdateTransaction(layout);
-    return transaction?.phase === "swapped" || transaction?.phase === "health-verified"
-        ? transaction.targetRecord.coreVersion
-        : undefined;
-}
-function removeCommittedRollbackAssets(transaction, layout) {
-    if (transaction.version === 1) {
-        durableRemoveFileSync(backupPath(layout));
+        if (pathEntryExists(`${layout.coreExe}.bak`))
+            throw new Error("Core backup has no ownership journal; preserved for inspection");
         return;
     }
-    durableRemoveFileSync(repairBinaryBackupPath(layout));
-    durableRemoveFileSync(repairInstallBackupPath(layout));
-}
-function rollbackAssetsExist(transaction, layout) {
-    return transaction.version === 1
-        ? pathEntryExists(backupPath(layout))
-        : pathEntryExists(repairBinaryBackupPath(layout)) ||
-            pathEntryExists(repairInstallBackupPath(layout));
-}
-export function completePendingCoreUpdateAfterStart(layout, verifier = defaultVerifier) {
-    let transaction = readCoreUpdateTransaction(layout);
-    if (!transaction)
-        return undefined;
-    if (transaction.phase !== "swapped" && transaction.phase !== "health-verified") {
-        throw new Error("Cannot complete a Core update which has not been swapped");
-    }
-    validatePendingTransaction(transaction, layout, verifier);
-    if (transaction.phase === "swapped") {
-        if (!transaction.deferredHealth) {
-            throw new Error("Cannot complete a Core update whose in-command health check was interrupted");
-        }
-        transaction = markCoreUpdateHealthVerified(transaction, layout);
-    }
-    writeInstallRecord(transaction.targetRecord, layout);
-    removeCommittedRollbackAssets(transaction, layout);
-    clearCoreUpdateTransaction(layout);
-    return transaction.targetRecord.coreVersion;
-}
-export function finalizeCoreUpdateTransaction(layout, verifier = defaultVerifier) {
-    const transaction = readCoreUpdateTransaction(layout);
-    if (!transaction) {
-        recoverLegacyInterruptedCoreUpdate(layout, verifier, true);
-        return;
-    }
-    if (transaction.phase !== "health-verified") {
-        throw new Error(`Core update still requires a health check: ${transaction.targetRecord.coreVersion}`);
-    }
-    validatePendingTransaction(transaction, layout, verifier);
-    writeInstallRecord(transaction.targetRecord, layout);
-    removeCommittedRollbackAssets(transaction, layout);
-    clearCoreUpdateTransaction(layout);
-}
-export async function commitCoreUpdate(opts) {
-    try {
-        return await commitCoreUpdateUnlocked(opts);
-    }
-    finally {
-        fs.rmSync(opts.staged.exe, { force: true });
-    }
-}
-async function commitCoreUpdateUnlocked(opts) {
-    const { layout, staged, runtime } = opts;
-    const verifier = opts.verifyExecutable ?? defaultVerifier;
-    let transaction;
-    let transactionStarted = false;
-    let swapped = false;
-    let runtimeStopped = false;
+    if (transaction.phase === "verified")
+        finishVerified(layout, transaction, verify);
+    else {
+        restoreFiles(layout, transaction, verify);
+        clearJournal(layout);
+    }
+}
+export async function commitCoreUpdate(options) {
+    const { layout, staged, runtime } = options;
+    const verify = options.verifyExecutable ?? defaultVerifier;
+    if (readCoreUpdateTransaction(layout) || pathEntryExists(`${layout.coreExe}.bak`)) {
+        throw new Error("An unfinished Core update requires recovery before another update");
+    }
+    const previous = readInstallRecord(layout) ?? null;
+    if (pathEntryExists(layout.coreExe) !== Boolean(previous) ||
+        pathEntryExists(layout.installFile) !== Boolean(previous)) {
+        throw new Error("Core installation is inconsistent; preserve its files and reinstall into a clean data directory");
+    }
+    if (previous)
+        verifyBinary(layout.coreExe, previous.coreVersion, verify);
+    verifyBinary(staged.exe, staged.version, verify);
+    await runtime.stop();
+    let transaction = {
+        version: 1,
+        phase: "prepared",
+        previous,
+        target: { coreVersion: staged.version, installedAt: new Date().toISOString() },
+    };
+    let committed = false;
     try {
-        if (readCoreUpdateTransaction(layout))
-            recoverCoreUpdateTransaction(layout, verifier);
+        writeJournal(layout, transaction);
+        await waitForBinaryUnlocked(layout.coreExe);
+        if (previous)
+            durableRenameSync(layout.coreExe, `${layout.coreExe}.bak`);
+        durableRenameSync(staged.exe, layout.coreExe);
+        writeInstallRecord(transaction.target, layout);
+        transaction = { ...transaction, phase: "swapped" };
+        writeJournal(layout, transaction);
+        await runtime.startAndVerify(staged.version);
+        if (runtime.wasRunning)
+            await runtime.applySystemProxy();
         else
-            recoverLegacyInterruptedCoreUpdate(layout, verifier, true);
-        if (readCoreUpdateTransaction(layout)) {
-            throw new Error(`A Core update is pending managed startup/finalization: ${layout.coreUpdateTransactionFile}`);
-        }
-        let previousRecord = readInstallRecord(layout);
-        const binaryExists = pathEntryExists(layout.coreExe);
-        const installEntryExists = pathEntryExists(layout.installFile);
-        const consistentEmpty = !binaryExists && !installEntryExists;
-        const consistentInstalled = binaryExists && installEntryExists && isRegularFile(layout.coreExe) && previousRecord;
-        const repairRequired = !consistentEmpty && !consistentInstalled;
-        if (repairRequired && !opts.forceRepair) {
-            throw new Error("Cannot update inconsistent Core binary/install metadata state");
-        }
-        const deferredHealth = runtime?.verifyRuntime !== true;
-        if (repairRequired) {
-            transaction = beginCoreRepairUpdateTransaction(layout, staged.version, deferredHealth);
-            previousRecord = undefined;
-        }
-        else {
-            transaction = beginCoreUpdateTransaction(layout, staged.version, previousRecord, deferredHealth);
-        }
-        transactionStarted = true;
-        if (runtime?.verifyRuntime) {
             await runtime.stop();
-            runtimeStopped = true;
-        }
-        if (transaction.version === 2) {
-            transaction = quarantineCoreInstallationForUpdate(transaction, layout);
-        }
-        else if (previousRecord) {
-            await waitForBinaryUnlocked(layout.coreExe);
-            durableRenameSync(layout.coreExe, backupPath(layout));
-        }
-        durableRenameSync(staged.exe, layout.coreExe);
-        swapped = true;
-        transaction = markCoreUpdateSwapped(transaction, layout);
-        if (deferredHealth && !previousRecord)
-            writeInstallRecord(transaction.targetRecord, layout);
-        if (runtime?.verifyRuntime) {
-            await runtime.startAndVerify(staged.version);
-            transaction = markCoreUpdateHealthVerified(transaction, layout);
-            writeInstallRecord(transaction.targetRecord, layout);
-        }
-        return {
-            version: staged.version,
-            backupRemoved: !rollbackAssetsExist(transaction, layout),
-            pendingStartupValidation: deferredHealth,
-        };
-    }
-    catch (err) {
-        const rollbackErrors = [];
-        let mayRestoreFiles = true;
-        if (runtime?.verifyRuntime && swapped) {
-            try {
-                await runtime.stop();
-                runtimeStopped = true;
-            }
-            catch (rollbackErr) {
-                mayRestoreFiles = false;
-                rollbackErrors.push(rollbackErr.message);
-            }
-        }
-        let restored;
-        if (mayRestoreFiles) {
-            try {
-                await opts.beforeRollback?.();
-            }
-            catch (rollbackErr) {
-                rollbackErrors.push(`managed state: ${rollbackErr.message}`);
-            }
-            if (transactionStarted) {
-                try {
-                    restored = rollbackCoreUpdateTransaction(layout, verifier);
-                }
-                catch (rollbackErr) {
-                    rollbackErrors.push(`Core binary: ${rollbackErr.message}`);
-                }
-            }
-            if (runtime?.verifyRuntime && runtimeStopped && restored) {
-                try {
-                    await runtime.startAndVerify(restored.coreVersion);
-                }
-                catch (rollbackErr) {
-                    rollbackErrors.push(`previous runtime: ${rollbackErr.message}`);
-                }
-            }
-        }
-        const message = err.message;
-        if (rollbackErrors.length) {
-            throw new Error(`${message}; rollback also failed: ${rollbackErrors.join("; ")}`);
-        }
-        throw err;
-    }
-}
-function recoverLegacyInterruptedCoreUpdate(layout, verifier = defaultVerifier, finalizeCommittedBackup = false) {
-    for (const repairBackup of [repairBinaryBackupPath(layout), repairInstallBackupPath(layout)]) {
-        if (pathEntryExists(repairBackup)) {
-            throw new Error(`Cannot recover Core repair backup without its transaction journal: ${repairBackup}`);
-        }
-    }
-    const backup = backupPath(layout);
-    if (!pathEntryExists(backup))
-        return;
-    const previousRecord = readInstallRecord(layout);
-    if (!previousRecord) {
-        throw new Error(`Cannot recover ambiguous Core backup without install metadata: ${backup}`);
-    }
-    if (!pathEntryExists(layout.coreExe)) {
-        verifyTransactionBinary(backup, previousRecord.coreVersion, verifier, "Core backup");
-        durableRenameSync(backup, layout.coreExe);
-        return;
-    }
-    let currentMatches = false;
-    let backupMatches = false;
-    try {
-        verifier(layout.coreExe, previousRecord.coreVersion);
-        currentMatches = true;
-    }
-    catch {
-    }
-    if (!currentMatches) {
+        transaction = { ...transaction, phase: "verified" };
+        writeJournal(layout, transaction);
+        committed = true;
+        finishVerified(layout, transaction, verify);
+        return { version: staged.version };
+    }
+    catch (error) {
+        if (committed || readCoreUpdateTransaction(layout)?.phase === "verified")
+            throw error;
         try {
-            verifier(backup, previousRecord.coreVersion);
-            backupMatches = true;
+            await runtime.stop();
+            const journal = readCoreUpdateTransaction(layout);
+            if (journal)
+                restoreFiles(layout, journal, verify);
+            if (runtime.wasRunning && previous) {
+                await runtime.startAndVerify(previous.coreVersion);
+                await runtime.applySystemProxy();
+            }
+            clearJournal(layout);
         }
-        catch {
+        catch (rollback) {
+            throw new Error(`${error instanceof Error ? error.message : String(error)}; Core rollback failed: ${rollback instanceof Error ? rollback.message : String(rollback)}`, { cause: error });
         }
-    }
-    if (currentMatches) {
-        if (finalizeCommittedBackup)
-            durableRemoveFileSync(backup);
-    }
-    else if (backupMatches) {
-        durableRemoveFileSync(layout.coreExe);
-        durableRenameSync(backup, layout.coreExe);
-    }
-    else {
-        throw new Error(`Cannot determine a safe Core after an interrupted update; preserved ${layout.coreExe} and ${backup}`);
+        throw error;
     }
 }