@adamchanadam/agent-handoff-kit 0.3.47 → 0.3.48
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.en.md +1 -1
- package/README.md +1 -1
- package/bin/agent-handoff-kit.mjs +510 -42
- package/bin/migration-baselines/official-origin-catalog.json +1462 -332
- package/bin/official-origin-catalog.mjs +16 -7
- package/package.json +1 -1
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
import { createInterface } from "node:readline/promises";
|
|
4
4
|
import { stdin as input, stdout as output } from "node:process";
|
|
5
|
-
import { chmod, copyFile, link, lstat, mkdir, open, readFile, readdir, realpath, stat, unlink, writeFile } from "node:fs/promises";
|
|
5
|
+
import { chmod, copyFile, link, lstat, mkdir, open, readFile, readdir, realpath, rename, rmdir, stat, unlink, writeFile } from "node:fs/promises";
|
|
6
6
|
import { createHash, randomUUID } from "node:crypto";
|
|
7
7
|
import { hostname } from "node:os";
|
|
8
8
|
import path from "node:path";
|
|
@@ -930,21 +930,26 @@ async function executeInstallTransaction(command, root, mode, plan, version, can
|
|
|
930
930
|
// transaction already has a runtime acceptance, bind the pre-transaction
|
|
931
931
|
// root-source witness into the same current-state digest before the journal
|
|
932
932
|
// directory itself is created.
|
|
933
|
+
const archiveMigrations = command === "upgrade"
|
|
934
|
+
? await prepareArchiveCasingMigrations(root)
|
|
935
|
+
: [];
|
|
933
936
|
const sourceConservation = command === "upgrade" && resolveRuntimeAcceptance(outputs)
|
|
934
|
-
? await createSourceConservation(root, outputs)
|
|
937
|
+
? await createSourceConservation(root, outputs, archiveMigrations)
|
|
935
938
|
: null;
|
|
936
939
|
// A repair may restore the exact bytes of a prior committed state. Keep the
|
|
937
940
|
// causal replacement relation inside the existing sealed journal so ordinary
|
|
938
941
|
// doctor can select the freshly read-back transaction without falling back
|
|
939
942
|
// to mtime or a separate current-state registry.
|
|
940
943
|
const supersedesCurrentStateDigests = command === "upgrade"
|
|
941
|
-
? await findRestoredCurrentStateDigests(root, outputs)
|
|
944
|
+
? await findRestoredCurrentStateDigests(root, outputs, archiveMigrations)
|
|
942
945
|
: [];
|
|
943
|
-
const transaction = await prepareTransaction(root, command, version, outputs, mode, plan, sourceConservation, supersedesCurrentStateDigests);
|
|
946
|
+
const transaction = await prepareTransaction(root, command, version, outputs, mode, plan, sourceConservation, supersedesCurrentStateDigests, archiveMigrations);
|
|
944
947
|
try {
|
|
945
|
-
transaction.journal.state = "committing";
|
|
946
|
-
await writeSecureJson(transaction.journalPath, transaction.journal);
|
|
947
|
-
|
|
948
|
+
transaction.journal.state = "committing";
|
|
949
|
+
await writeSecureJson(transaction.journalPath, transaction.journal);
|
|
950
|
+
|
|
951
|
+
await applyArchiveCasingMigrations(root, transaction);
|
|
952
|
+
|
|
948
953
|
let committedCount = 0;
|
|
949
954
|
const qaFailAfterCommit = Number.parseInt(process.env.AGENT_HANDOFF_KIT_QA_FAIL_AFTER_COMMIT ?? "", 10);
|
|
950
955
|
const qaFailAfterCommitTarget = process.env.AGENT_HANDOFF_KIT_QA_FAIL_AFTER_COMMIT_TARGET ?? null;
|
|
@@ -1043,7 +1048,13 @@ async function executeInstallTransaction(command, root, mode, plan, version, can
|
|
|
1043
1048
|
console.log("✅ project health: passed");
|
|
1044
1049
|
}
|
|
1045
1050
|
} catch (error) {
|
|
1046
|
-
if ([
|
|
1051
|
+
if ([
|
|
1052
|
+
"ACK_QA_INTERRUPT_AFTER_REPLACE",
|
|
1053
|
+
"ACK_QA_INTERRUPT_AFTER_JOURNAL_COMMIT",
|
|
1054
|
+
"ACK_QA_INTERRUPT_AFTER_ARCHIVE_RELOCATE_BEFORE_STAGE",
|
|
1055
|
+
"ACK_QA_INTERRUPT_AFTER_ARCHIVE_STAGE",
|
|
1056
|
+
"ACK_QA_INTERRUPT_AFTER_ARCHIVE_MATERIALIZE_BEFORE_JOURNAL"
|
|
1057
|
+
].includes(error?.code)) throw error;
|
|
1047
1058
|
if (isNoClobberConflict(error)) {
|
|
1048
1059
|
transaction.journal.state = "manual-recovery-required";
|
|
1049
1060
|
transaction.journal.committedVersion = null;
|
|
@@ -1269,18 +1280,20 @@ function createFormalUserRulesWitness(entries, state, acceptanceDigest) {
|
|
|
1269
1280
|
});
|
|
1270
1281
|
}
|
|
1271
1282
|
|
|
1272
|
-
async function prepareTransaction(root, command, version, outputs, mode, plan, sourceConservation = null, supersedesCurrentStateDigests = []) {
|
|
1283
|
+
async function prepareTransaction(root, command, version, outputs, mode, plan, sourceConservation = null, supersedesCurrentStateDigests = [], archiveMigrations = []) {
|
|
1273
1284
|
const id = `${new Date().toISOString().replace(/[:.]/g, "-")}-${randomUUID()}`;
|
|
1274
1285
|
const migrationsRoot = path.join(root, "dev", "governance_migrations");
|
|
1275
1286
|
const migrationDir = path.join(migrationsRoot, id);
|
|
1276
1287
|
const backupDir = path.join(migrationDir, "backup");
|
|
1277
1288
|
const stageDir = path.join(migrationDir, "stage");
|
|
1278
1289
|
const escrowDir = path.join(migrationDir, "no-clobber-escrow");
|
|
1290
|
+
const archiveBackupDir = path.join(migrationDir, "archive-backup");
|
|
1279
1291
|
const journalPath = path.join(migrationDir, "transaction.json");
|
|
1280
1292
|
const lockPath = path.join(migrationsRoot, ".upgrade.lock");
|
|
1281
1293
|
await mkdir(backupDir, { recursive: true });
|
|
1282
1294
|
await mkdir(stageDir, { recursive: true });
|
|
1283
1295
|
await mkdir(escrowDir, { recursive: true });
|
|
1296
|
+
await mkdir(archiveBackupDir, { recursive: true });
|
|
1284
1297
|
await tightenPermissions(migrationsRoot, 0o700);
|
|
1285
1298
|
await tightenPermissions(migrationDir, 0o700);
|
|
1286
1299
|
const lock = await open(lockPath, "wx", 0o600).catch((error) => {
|
|
@@ -1321,6 +1334,11 @@ async function prepareTransaction(root, command, version, outputs, mode, plan, s
|
|
|
1321
1334
|
runtimeAcceptance: resolveRuntimeAcceptance(outputs),
|
|
1322
1335
|
runtimeAcceptanceReadback: null,
|
|
1323
1336
|
sourceConservation,
|
|
1337
|
+
archiveMigrations: archiveMigrations.map((migration, index) => ({
|
|
1338
|
+
...migration,
|
|
1339
|
+
stageRel: `archive-backup/${index}`,
|
|
1340
|
+
state: "prepared"
|
|
1341
|
+
})),
|
|
1324
1342
|
...(supersedesCurrentStateDigests.length > 0 ? { supersedesCurrentStateDigests } : {}),
|
|
1325
1343
|
currentStateWitness: null,
|
|
1326
1344
|
currentStateReadback: null
|
|
@@ -1330,8 +1348,281 @@ async function prepareTransaction(root, command, version, outputs, mode, plan, s
|
|
|
1330
1348
|
// independently authorise doctor/report/success.
|
|
1331
1349
|
journal.currentStateWitness = createCurrentStateWitness(journal);
|
|
1332
1350
|
await writeSecureJson(journalPath, journal);
|
|
1333
|
-
return { id, migrationDir, backupDir, stageDir, escrowDir, journalPath, lockPath, journal };
|
|
1334
|
-
}
|
|
1351
|
+
return { id, migrationDir, backupDir, stageDir, escrowDir, archiveBackupDir, journalPath, lockPath, journal };
|
|
1352
|
+
}
|
|
1353
|
+
|
|
1354
|
+
async function prepareArchiveCasingMigrations(root) {
|
|
1355
|
+
const devDir = path.join(root, "dev");
|
|
1356
|
+
let entries;
|
|
1357
|
+
try {
|
|
1358
|
+
entries = await readdir(devDir, { withFileTypes: true });
|
|
1359
|
+
} catch (error) {
|
|
1360
|
+
if (error?.code === "ENOENT") return [];
|
|
1361
|
+
throw error;
|
|
1362
|
+
}
|
|
1363
|
+
const matches = entries
|
|
1364
|
+
.filter((entry) => entry.isDirectory() && entry.name.toLowerCase() === "session_log_archive")
|
|
1365
|
+
.map((entry) => entry.name)
|
|
1366
|
+
.sort((left, right) => left.localeCompare(right));
|
|
1367
|
+
if (matches.length === 0 || (matches.length === 1 && matches[0] === "SESSION_LOG_archive")) return [];
|
|
1368
|
+
if (matches.includes("SESSION_LOG_archive") || matches.length !== 1) {
|
|
1369
|
+
throw new Error(`archive casing migration is ambiguous: ${matches.map((name) => `dev/${name}`).join(", ")}`);
|
|
1370
|
+
}
|
|
1371
|
+
const originalRel = `dev/${matches[0]}`;
|
|
1372
|
+
return [{
|
|
1373
|
+
schemaVersion: 1,
|
|
1374
|
+
originalRel,
|
|
1375
|
+
canonicalRel: "dev/SESSION_LOG_archive",
|
|
1376
|
+
snapshot: await snapshotDirectoryTree(root, originalRel)
|
|
1377
|
+
}];
|
|
1378
|
+
}
|
|
1379
|
+
|
|
1380
|
+
async function applyArchiveCasingMigrations(root, transaction) {
|
|
1381
|
+
for (const migration of transaction.journal.archiveMigrations ?? []) {
|
|
1382
|
+
const migrationDir = transaction.migrationDir;
|
|
1383
|
+
const originalAbs = path.join(root, migration.originalRel);
|
|
1384
|
+
const canonicalAbs = path.join(root, migration.canonicalRel);
|
|
1385
|
+
const stageAbs = path.join(migrationDir, migration.stageRel);
|
|
1386
|
+
if (migration.state === "prepared") {
|
|
1387
|
+
await assertExactDirectorySnapshot(root, migration.originalRel, migration.snapshot, "archive migration source changed before transaction commit");
|
|
1388
|
+
await assertExactProjectDirectoryAbsent(root, migration.canonicalRel, "canonical archive path appeared before transaction commit");
|
|
1389
|
+
if (await pathExists(stageAbs)) throw noClobberConflict(`${migration.originalRel}: transaction archive backup already exists; recovery lock retained`);
|
|
1390
|
+
await mkdir(path.dirname(stageAbs), { recursive: true });
|
|
1391
|
+
migration.state = "relocating";
|
|
1392
|
+
await writeSecureJson(transaction.journalPath, transaction.journal);
|
|
1393
|
+
}
|
|
1394
|
+
if (migration.state === "relocating") {
|
|
1395
|
+
await rename(originalAbs, stageAbs);
|
|
1396
|
+
await assertExactProjectDirectoryAbsent(root, migration.originalRel, "archive source remains after relocation");
|
|
1397
|
+
await assertDirectorySnapshotAtPath(stageAbs, migration.snapshot, "archive backup differs after relocation");
|
|
1398
|
+
if (process.env.AGENT_HANDOFF_KIT_QA_INTERRUPT_AFTER_ARCHIVE_RELOCATE_BEFORE_STAGE === "1") {
|
|
1399
|
+
const interruption = new Error("QA interruption after archive relocation before staged journal");
|
|
1400
|
+
interruption.code = "ACK_QA_INTERRUPT_AFTER_ARCHIVE_RELOCATE_BEFORE_STAGE";
|
|
1401
|
+
throw interruption;
|
|
1402
|
+
}
|
|
1403
|
+
migration.state = "staged";
|
|
1404
|
+
await writeSecureJson(transaction.journalPath, transaction.journal);
|
|
1405
|
+
if (process.env.AGENT_HANDOFF_KIT_QA_INTERRUPT_AFTER_ARCHIVE_STAGE === "1") {
|
|
1406
|
+
const interruption = new Error("QA interruption after archive relocation");
|
|
1407
|
+
interruption.code = "ACK_QA_INTERRUPT_AFTER_ARCHIVE_STAGE";
|
|
1408
|
+
throw interruption;
|
|
1409
|
+
}
|
|
1410
|
+
}
|
|
1411
|
+
if (migration.state === "staged") {
|
|
1412
|
+
migration.state = "materializing";
|
|
1413
|
+
await writeSecureJson(transaction.journalPath, transaction.journal);
|
|
1414
|
+
}
|
|
1415
|
+
if (migration.state === "materializing") {
|
|
1416
|
+
await materializeArchiveCanonicalPath(root, migration, stageAbs);
|
|
1417
|
+
if (process.env.AGENT_HANDOFF_KIT_QA_INTERRUPT_AFTER_ARCHIVE_MATERIALIZE_BEFORE_JOURNAL === "1") {
|
|
1418
|
+
const interruption = new Error("QA interruption after archive canonical materialization before materialized journal");
|
|
1419
|
+
interruption.code = "ACK_QA_INTERRUPT_AFTER_ARCHIVE_MATERIALIZE_BEFORE_JOURNAL";
|
|
1420
|
+
throw interruption;
|
|
1421
|
+
}
|
|
1422
|
+
migration.state = "materialized";
|
|
1423
|
+
await writeSecureJson(transaction.journalPath, transaction.journal);
|
|
1424
|
+
if (process.env.AGENT_HANDOFF_KIT_QA_FAIL_AFTER_ARCHIVE_MATERIALIZE === "1") {
|
|
1425
|
+
throw new Error("QA fault injection after archive canonical materialization");
|
|
1426
|
+
}
|
|
1427
|
+
}
|
|
1428
|
+
if (migration.state !== "materialized") throw new Error("archive migration journal state is invalid during commit");
|
|
1429
|
+
}
|
|
1430
|
+
}
|
|
1431
|
+
|
|
1432
|
+
async function materializeArchiveCanonicalPath(root, migration, stageAbs) {
|
|
1433
|
+
await assertDirectorySnapshotAtPath(stageAbs, migration.snapshot, "archive backup changed before canonical materialization");
|
|
1434
|
+
await assertExactProjectDirectoryAbsent(root, migration.canonicalRel, "canonical archive path appeared during transaction");
|
|
1435
|
+
const canonicalAbs = path.join(root, migration.canonicalRel);
|
|
1436
|
+
try {
|
|
1437
|
+
await mkdir(canonicalAbs);
|
|
1438
|
+
} catch (error) {
|
|
1439
|
+
if (error?.code === "EEXIST") throw noClobberConflict(`${migration.canonicalRel}: canonical archive path appeared during transaction; recovery lock retained`);
|
|
1440
|
+
throw error;
|
|
1441
|
+
}
|
|
1442
|
+
for (const directory of migration.snapshot.directories.filter((item) => item).sort((left, right) => left.localeCompare(right))) {
|
|
1443
|
+
try {
|
|
1444
|
+
await mkdir(path.join(canonicalAbs, directory));
|
|
1445
|
+
} catch (error) {
|
|
1446
|
+
if (error?.code === "EEXIST") throw noClobberConflict(`${migration.canonicalRel}/${directory}: archive directory appeared during transaction; recovery lock retained`);
|
|
1447
|
+
throw error;
|
|
1448
|
+
}
|
|
1449
|
+
}
|
|
1450
|
+
for (const file of migration.snapshot.files) {
|
|
1451
|
+
const source = path.join(stageAbs, file.path);
|
|
1452
|
+
const target = path.join(canonicalAbs, file.path);
|
|
1453
|
+
const sourceBytes = await readFile(source);
|
|
1454
|
+
if (sourceBytes.length !== file.bytes || sha256(sourceBytes) !== file.sha256) {
|
|
1455
|
+
throw new Error(`${migration.originalRel}/${file.path}: archive backup bytes changed before canonical materialization`);
|
|
1456
|
+
}
|
|
1457
|
+
try {
|
|
1458
|
+
await writeFile(target, sourceBytes, { mode: 0o600, flag: "wx" });
|
|
1459
|
+
} catch (error) {
|
|
1460
|
+
if (error?.code === "EEXIST") throw noClobberConflict(`${migration.canonicalRel}/${file.path}: archive file appeared during transaction; recovery lock retained`);
|
|
1461
|
+
throw error;
|
|
1462
|
+
}
|
|
1463
|
+
}
|
|
1464
|
+
await assertExactDirectorySnapshot(root, migration.canonicalRel, migration.snapshot, "canonical archive materialization did not retain source bytes");
|
|
1465
|
+
}
|
|
1466
|
+
|
|
1467
|
+
async function snapshotDirectoryTree(root, relative) {
|
|
1468
|
+
const absolute = path.join(root, relative);
|
|
1469
|
+
return snapshotDirectoryTreeAtPath(absolute);
|
|
1470
|
+
}
|
|
1471
|
+
|
|
1472
|
+
async function snapshotDirectoryTreeAtPath(absolute) {
|
|
1473
|
+
const rootStats = await lstat(absolute).catch((error) => error?.code === "ENOENT" ? null : Promise.reject(error));
|
|
1474
|
+
if (!rootStats?.isDirectory() || rootStats.isSymbolicLink()) throw new Error("archive migration directory is missing or unsafe");
|
|
1475
|
+
const directories = [""];
|
|
1476
|
+
const files = [];
|
|
1477
|
+
async function visit(current, relative) {
|
|
1478
|
+
const entries = await readdir(current, { withFileTypes: true });
|
|
1479
|
+
for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
|
|
1480
|
+
const childRelative = relative ? `${relative}/${entry.name}` : entry.name;
|
|
1481
|
+
const child = path.join(current, entry.name);
|
|
1482
|
+
if (entry.isDirectory()) {
|
|
1483
|
+
const stats = await lstat(child);
|
|
1484
|
+
if (stats.isSymbolicLink()) throw new Error(`${childRelative}: archive migration does not accept symbolic links or junctions`);
|
|
1485
|
+
directories.push(childRelative);
|
|
1486
|
+
await visit(child, childRelative);
|
|
1487
|
+
} else if (entry.isFile()) {
|
|
1488
|
+
const stats = await lstat(child);
|
|
1489
|
+
if (stats.isSymbolicLink()) throw new Error(`${childRelative}: archive migration does not accept symbolic links`);
|
|
1490
|
+
const bytes = await readFile(child);
|
|
1491
|
+
files.push({ path: childRelative, sha256: sha256(bytes), bytes: bytes.length });
|
|
1492
|
+
} else {
|
|
1493
|
+
throw new Error(`${childRelative}: archive migration accepts only regular files and directories`);
|
|
1494
|
+
}
|
|
1495
|
+
}
|
|
1496
|
+
}
|
|
1497
|
+
await visit(absolute, "");
|
|
1498
|
+
directories.sort((left, right) => left.localeCompare(right));
|
|
1499
|
+
files.sort((left, right) => left.path.localeCompare(right.path));
|
|
1500
|
+
const body = { schemaVersion: 1, directories, files };
|
|
1501
|
+
return { ...body, manifestSha256: sha256(Buffer.from(`${JSON.stringify(body)}\n`, "utf8")) };
|
|
1502
|
+
}
|
|
1503
|
+
|
|
1504
|
+
function validateArchiveSnapshot(snapshot) {
|
|
1505
|
+
if (!snapshot || typeof snapshot !== "object" || Array.isArray(snapshot)
|
|
1506
|
+
|| snapshot.schemaVersion !== 1
|
|
1507
|
+
|| !Array.isArray(snapshot.directories) || snapshot.directories[0] !== ""
|
|
1508
|
+
|| !Array.isArray(snapshot.files)
|
|
1509
|
+
|| typeof snapshot.manifestSha256 !== "string" || !/^[a-f0-9]{64}$/.test(snapshot.manifestSha256)) {
|
|
1510
|
+
throw new Error("archive migration snapshot is invalid; no recovery writes attempted");
|
|
1511
|
+
}
|
|
1512
|
+
const seenDirectories = new Set();
|
|
1513
|
+
let previousDirectory = null;
|
|
1514
|
+
for (const directory of snapshot.directories) {
|
|
1515
|
+
if (typeof directory !== "string" || (directory && !isSafeProjectRelative(directory)) || seenDirectories.has(directory)
|
|
1516
|
+
|| (previousDirectory != null && previousDirectory.localeCompare(directory) >= 0)) {
|
|
1517
|
+
throw new Error("archive migration directory snapshot is invalid; no recovery writes attempted");
|
|
1518
|
+
}
|
|
1519
|
+
seenDirectories.add(directory);
|
|
1520
|
+
previousDirectory = directory;
|
|
1521
|
+
}
|
|
1522
|
+
const seenFiles = new Set();
|
|
1523
|
+
let previousFile = null;
|
|
1524
|
+
for (const file of snapshot.files) {
|
|
1525
|
+
if (!file || typeof file !== "object" || Array.isArray(file)
|
|
1526
|
+
|| !isSafeProjectRelative(file.path) || seenFiles.has(file.path)
|
|
1527
|
+
|| !Number.isInteger(file.bytes) || file.bytes < 0
|
|
1528
|
+
|| typeof file.sha256 !== "string" || !/^[a-f0-9]{64}$/.test(file.sha256)
|
|
1529
|
+
|| (previousFile != null && previousFile.localeCompare(file.path) >= 0)) {
|
|
1530
|
+
throw new Error("archive migration file snapshot is invalid; no recovery writes attempted");
|
|
1531
|
+
}
|
|
1532
|
+
seenFiles.add(file.path);
|
|
1533
|
+
previousFile = file.path;
|
|
1534
|
+
}
|
|
1535
|
+
const body = { schemaVersion: snapshot.schemaVersion, directories: snapshot.directories, files: snapshot.files };
|
|
1536
|
+
if (sha256(Buffer.from(`${JSON.stringify(body)}\n`, "utf8")) !== snapshot.manifestSha256) {
|
|
1537
|
+
throw new Error("archive migration snapshot digest is invalid; no recovery writes attempted");
|
|
1538
|
+
}
|
|
1539
|
+
return snapshot;
|
|
1540
|
+
}
|
|
1541
|
+
|
|
1542
|
+
function archiveMigrationWitness(migration) {
|
|
1543
|
+
return {
|
|
1544
|
+
schemaVersion: migration.schemaVersion,
|
|
1545
|
+
originalRel: migration.originalRel,
|
|
1546
|
+
canonicalRel: migration.canonicalRel,
|
|
1547
|
+
snapshot: migration.snapshot
|
|
1548
|
+
};
|
|
1549
|
+
}
|
|
1550
|
+
|
|
1551
|
+
function validateArchiveMigrations(value, { requireMaterialized = false } = {}) {
|
|
1552
|
+
if (!Array.isArray(value) || value.length === 0) {
|
|
1553
|
+
throw new Error("archive migration journal is missing or invalid; no recovery writes attempted");
|
|
1554
|
+
}
|
|
1555
|
+
const seenOriginal = new Set();
|
|
1556
|
+
const seenCanonical = new Set();
|
|
1557
|
+
let previous = null;
|
|
1558
|
+
for (const migration of value) {
|
|
1559
|
+
if (!migration || typeof migration !== "object" || Array.isArray(migration)
|
|
1560
|
+
|| migration.schemaVersion !== 1
|
|
1561
|
+
|| !isSafeProjectRelative(migration.originalRel) || !migration.originalRel.startsWith("dev/")
|
|
1562
|
+
|| migration.canonicalRel !== "dev/SESSION_LOG_archive"
|
|
1563
|
+
|| seenOriginal.has(migration.originalRel) || seenCanonical.has(migration.canonicalRel)
|
|
1564
|
+
|| (previous != null && previous.localeCompare(migration.originalRel) >= 0)) {
|
|
1565
|
+
throw new Error("archive migration journal entry is invalid; no recovery writes attempted");
|
|
1566
|
+
}
|
|
1567
|
+
if (migration.stageRel !== undefined && (!isSafeProjectRelative(migration.stageRel) || !migration.stageRel.startsWith("archive-backup/"))) {
|
|
1568
|
+
throw new Error("archive migration backup path is invalid; no recovery writes attempted");
|
|
1569
|
+
}
|
|
1570
|
+
if (migration.state !== undefined && !["prepared", "relocating", "staged", "materializing", "materialized"].includes(migration.state)) {
|
|
1571
|
+
throw new Error("archive migration state is invalid; no recovery writes attempted");
|
|
1572
|
+
}
|
|
1573
|
+
if (requireMaterialized && migration.state !== undefined && migration.state !== "materialized") {
|
|
1574
|
+
throw new Error("committed archive migration is not materialized; no recovery writes attempted");
|
|
1575
|
+
}
|
|
1576
|
+
validateArchiveSnapshot(migration.snapshot);
|
|
1577
|
+
seenOriginal.add(migration.originalRel);
|
|
1578
|
+
seenCanonical.add(migration.canonicalRel);
|
|
1579
|
+
previous = migration.originalRel;
|
|
1580
|
+
}
|
|
1581
|
+
return value;
|
|
1582
|
+
}
|
|
1583
|
+
|
|
1584
|
+
async function assertDirectorySnapshotAtPath(absolute, expected, reason) {
|
|
1585
|
+
const actual = await snapshotDirectoryTreeAtPath(absolute);
|
|
1586
|
+
if (actual.manifestSha256 !== expected.manifestSha256) throw new Error(reason);
|
|
1587
|
+
}
|
|
1588
|
+
|
|
1589
|
+
async function assertExactDirectorySnapshot(root, relative, expected, reason) {
|
|
1590
|
+
const exact = await findExactProjectPath(root, relative);
|
|
1591
|
+
if (!exact) throw new Error(reason);
|
|
1592
|
+
await assertDirectorySnapshotAtPath(exact, expected, reason);
|
|
1593
|
+
}
|
|
1594
|
+
|
|
1595
|
+
async function assertExactProjectDirectoryAbsent(root, relative, reason) {
|
|
1596
|
+
if (await findExactProjectPath(root, relative)) throw noClobberConflict(reason);
|
|
1597
|
+
}
|
|
1598
|
+
|
|
1599
|
+
async function findExactProjectPath(root, relative) {
|
|
1600
|
+
if (!isSafeProjectRelative(relative)) throw new Error("archive migration path is unsafe");
|
|
1601
|
+
let current = root;
|
|
1602
|
+
for (const segment of relative.split("/")) {
|
|
1603
|
+
let entries;
|
|
1604
|
+
try {
|
|
1605
|
+
entries = await readdir(current, { withFileTypes: true });
|
|
1606
|
+
} catch (error) {
|
|
1607
|
+
if (error?.code === "ENOENT") return null;
|
|
1608
|
+
throw error;
|
|
1609
|
+
}
|
|
1610
|
+
const match = entries.find((entry) => entry.name === segment);
|
|
1611
|
+
if (!match) return null;
|
|
1612
|
+
current = path.join(current, match.name);
|
|
1613
|
+
}
|
|
1614
|
+
return current;
|
|
1615
|
+
}
|
|
1616
|
+
|
|
1617
|
+
async function pathExists(filePath) {
|
|
1618
|
+
try {
|
|
1619
|
+
await lstat(filePath);
|
|
1620
|
+
return true;
|
|
1621
|
+
} catch (error) {
|
|
1622
|
+
if (error?.code === "ENOENT") return false;
|
|
1623
|
+
throw error;
|
|
1624
|
+
}
|
|
1625
|
+
}
|
|
1335
1626
|
|
|
1336
1627
|
async function validateTransactionRoot(root, plan, { createMissingRoot = true } = {}) {
|
|
1337
1628
|
let rootStats;
|
|
@@ -1595,32 +1886,46 @@ async function validateRecoveryJournal(root, journal, journalPath, lockId = null
|
|
|
1595
1886
|
const seen = new Set();
|
|
1596
1887
|
const formalWitness = validateFormalUserRulesWitness(journal.formalUserRules);
|
|
1597
1888
|
const runtimeAcceptance = validateRuntimeAcceptance(journal.runtimeAcceptance);
|
|
1889
|
+
const hasArchiveMigrationField = journal.archiveMigrations !== undefined;
|
|
1890
|
+
const requiresArchiveBackup = journal.command === "upgrade" && hasArchiveMigrationField;
|
|
1891
|
+
if (journal.archiveMigrations != null && !Array.isArray(journal.archiveMigrations)) throw new Error("upgrade journal archive migrations are invalid; no recovery writes attempted");
|
|
1892
|
+
const archiveMigrations = (journal.archiveMigrations ?? []).length > 0
|
|
1893
|
+
? validateArchiveMigrations(journal.archiveMigrations, { requireMaterialized: journal.state === "committed" })
|
|
1894
|
+
: [];
|
|
1895
|
+
if (requiresArchiveBackup && archiveMigrations.some((migration) => !migration.stageRel || migration.state === undefined)) {
|
|
1896
|
+
throw new Error("upgrade journal archive migration recovery fields are missing; no recovery writes attempted");
|
|
1897
|
+
}
|
|
1598
1898
|
const rootStats = await lstat(root);
|
|
1599
1899
|
if (!rootStats.isDirectory() || rootStats.isSymbolicLink()) throw new Error("selected recovery root is not a safe directory; no recovery writes attempted");
|
|
1600
1900
|
const rootReal = await realpath(root);
|
|
1601
1901
|
const backupRoot = path.join(migrationDir, "backup");
|
|
1602
|
-
const stageRoot = path.join(migrationDir, "stage");
|
|
1902
|
+
const stageRoot = path.join(migrationDir, "stage");
|
|
1903
|
+
const archiveBackupRoot = path.join(migrationDir, "archive-backup");
|
|
1603
1904
|
const migrationsStats = await lstat(migrationsRoot).catch(() => null);
|
|
1604
1905
|
const migrationStats = await lstat(migrationDir).catch(() => null);
|
|
1605
1906
|
const journalStats = await lstat(journalPath).catch(() => null);
|
|
1606
1907
|
const backupStats = await lstat(backupRoot).catch(() => null);
|
|
1607
|
-
const stageStats = await lstat(stageRoot).catch(() => null);
|
|
1908
|
+
const stageStats = await lstat(stageRoot).catch(() => null);
|
|
1909
|
+
const archiveBackupStats = requiresArchiveBackup ? await lstat(archiveBackupRoot).catch(() => null) : null;
|
|
1608
1910
|
if (!migrationsStats?.isDirectory() || migrationsStats.isSymbolicLink()
|
|
1609
1911
|
|| !migrationStats?.isDirectory() || migrationStats.isSymbolicLink()
|
|
1610
1912
|
|| !journalStats?.isFile() || journalStats.isSymbolicLink()
|
|
1611
1913
|
|| !backupStats?.isDirectory() || backupStats.isSymbolicLink()
|
|
1612
|
-
|| !stageStats?.isDirectory() || stageStats.isSymbolicLink()
|
|
1914
|
+
|| !stageStats?.isDirectory() || stageStats.isSymbolicLink()
|
|
1915
|
+
|| (requiresArchiveBackup && (!archiveBackupStats?.isDirectory() || archiveBackupStats.isSymbolicLink()))) {
|
|
1613
1916
|
throw new Error("upgrade transaction directories or journal are missing or unsafe; no recovery writes attempted");
|
|
1614
1917
|
}
|
|
1615
1918
|
const migrationsReal = await realpath(migrationsRoot);
|
|
1616
1919
|
const migrationReal = await realpath(migrationDir);
|
|
1617
1920
|
const journalReal = await realpath(journalPath);
|
|
1618
1921
|
const backupRealRoot = await realpath(backupRoot);
|
|
1619
|
-
const stageRealRoot = await realpath(stageRoot);
|
|
1922
|
+
const stageRealRoot = await realpath(stageRoot);
|
|
1923
|
+
const archiveBackupRealRoot = requiresArchiveBackup ? await realpath(archiveBackupRoot) : null;
|
|
1620
1924
|
if (!isInside(rootReal, migrationsReal) || !isInside(migrationsReal, migrationReal)
|
|
1621
1925
|
|| !isInside(migrationReal, journalReal) || !isInside(migrationReal, backupRealRoot) || !isInside(migrationReal, stageRealRoot)
|
|
1622
1926
|
|| !samePath(path.dirname(migrationReal), migrationsReal)
|
|
1623
|
-
|| !samePath(path.dirname(backupRealRoot), migrationReal) || !samePath(path.dirname(stageRealRoot), migrationReal)
|
|
1927
|
+
|| !samePath(path.dirname(backupRealRoot), migrationReal) || !samePath(path.dirname(stageRealRoot), migrationReal)
|
|
1928
|
+
|| (requiresArchiveBackup && !samePath(path.dirname(archiveBackupRealRoot), migrationReal))) {
|
|
1624
1929
|
throw new Error("upgrade transaction paths resolve outside the selected root or transaction; no recovery writes attempted");
|
|
1625
1930
|
}
|
|
1626
1931
|
const validated = [];
|
|
@@ -1676,6 +1981,19 @@ async function validateRecoveryJournal(root, journal, journalPath, lockId = null
|
|
|
1676
1981
|
if (journal.state === "committed" && validated.some(({ entry }) => !entry.committed)) {
|
|
1677
1982
|
throw new Error("committed upgrade journal contains an uncommitted entry; no recovery writes attempted");
|
|
1678
1983
|
}
|
|
1984
|
+
if (requiresArchiveBackup) {
|
|
1985
|
+
for (const migration of archiveMigrations) {
|
|
1986
|
+
const stageAbs = path.resolve(migrationDir, migration.stageRel);
|
|
1987
|
+
if (!isInside(archiveBackupRoot, stageAbs)) throw new Error("upgrade archive migration backup escapes this transaction; no recovery writes attempted");
|
|
1988
|
+
const stageStats = await lstat(stageAbs).catch((error) => error?.code === "ENOENT" ? null : Promise.reject(error));
|
|
1989
|
+
if (stageStats) {
|
|
1990
|
+
if (!stageStats.isDirectory() || stageStats.isSymbolicLink()) throw new Error("upgrade archive migration backup is unsafe; no recovery writes attempted");
|
|
1991
|
+
const stageReal = await realpath(stageAbs);
|
|
1992
|
+
if (!isInside(archiveBackupRealRoot, stageReal)) throw new Error("upgrade archive migration backup resolves outside this transaction; no recovery writes attempted");
|
|
1993
|
+
await assertDirectorySnapshotAtPath(stageAbs, migration.snapshot, "upgrade archive migration backup hash does not match the recorded input; no recovery writes attempted");
|
|
1994
|
+
}
|
|
1995
|
+
}
|
|
1996
|
+
}
|
|
1679
1997
|
if (runtimeAcceptance) {
|
|
1680
1998
|
for (const accepted of runtimeAcceptance.entries) {
|
|
1681
1999
|
const transactionEntry = validated.find(({ entry }) => entry.targetRel === accepted.targetRel)?.entry;
|
|
@@ -1693,10 +2011,11 @@ async function validateRecoveryJournal(root, journal, journalPath, lockId = null
|
|
|
1693
2011
|
return validated;
|
|
1694
2012
|
}
|
|
1695
2013
|
|
|
1696
|
-
async function rollbackTransaction(root, journal, journalPath, lockId = null) {
|
|
1697
|
-
const validated = await validateRecoveryJournal(root, journal, journalPath, lockId);
|
|
1698
|
-
const conflicts = [];
|
|
1699
|
-
const operations = [];
|
|
2014
|
+
async function rollbackTransaction(root, journal, journalPath, lockId = null) {
|
|
2015
|
+
const validated = await validateRecoveryJournal(root, journal, journalPath, lockId);
|
|
2016
|
+
const conflicts = [];
|
|
2017
|
+
const operations = [];
|
|
2018
|
+
const archiveRollbackPlans = [];
|
|
1700
2019
|
// Do not trust the committed flag: the process can stop after replacement
|
|
1701
2020
|
// but before the journal flag is persisted. Inspect every target hash first.
|
|
1702
2021
|
for (const item of [...validated].reverse()) {
|
|
@@ -1707,9 +2026,16 @@ async function rollbackTransaction(root, journal, journalPath, lockId = null) {
|
|
|
1707
2026
|
conflicts.push(`${item.entry.targetRel}: current content differs from both transaction input and candidate`);
|
|
1708
2027
|
continue;
|
|
1709
2028
|
}
|
|
1710
|
-
operations.push(item);
|
|
1711
|
-
}
|
|
1712
|
-
|
|
2029
|
+
operations.push(item);
|
|
2030
|
+
}
|
|
2031
|
+
for (const migration of [...(journal.archiveMigrations ?? [])].reverse()) {
|
|
2032
|
+
try {
|
|
2033
|
+
archiveRollbackPlans.push(await planArchiveRollback(root, path.dirname(journalPath), migration));
|
|
2034
|
+
} catch (error) {
|
|
2035
|
+
conflicts.push(safeErrorLabel(error));
|
|
2036
|
+
}
|
|
2037
|
+
}
|
|
2038
|
+
if (conflicts.length > 0) {
|
|
1713
2039
|
journal.state = "manual-recovery-required";
|
|
1714
2040
|
journal.committedVersion = null;
|
|
1715
2041
|
journal.recoveryConflicts = conflicts;
|
|
@@ -1736,15 +2062,97 @@ async function rollbackTransaction(root, journal, journalPath, lockId = null) {
|
|
|
1736
2062
|
}
|
|
1737
2063
|
const restored = await readOptionalBuffer(targetAbs);
|
|
1738
2064
|
const restoredHash = restored ? sha256(restored) : null;
|
|
1739
|
-
if (restoredHash !== entry.beforeHash) throw new Error(`${entry.targetRel}: rollback verification failed; recovery lock retained`);
|
|
1740
|
-
}
|
|
1741
|
-
|
|
2065
|
+
if (restoredHash !== entry.beforeHash) throw new Error(`${entry.targetRel}: rollback verification failed; recovery lock retained`);
|
|
2066
|
+
}
|
|
2067
|
+
for (const plan of archiveRollbackPlans) {
|
|
2068
|
+
try {
|
|
2069
|
+
await executeArchiveRollback(root, journal, plan, rollbackEscrowDir);
|
|
2070
|
+
} catch (error) {
|
|
2071
|
+
if (!isNoClobberConflict(error)) throw error;
|
|
2072
|
+
conflicts.push(safeErrorLabel(error));
|
|
2073
|
+
journal.state = "manual-recovery-required";
|
|
2074
|
+
journal.committedVersion = null;
|
|
2075
|
+
journal.recoveryConflicts = conflicts;
|
|
2076
|
+
await writeSecureJson(journalPath, journal);
|
|
2077
|
+
return { ok: false, conflicts };
|
|
2078
|
+
}
|
|
2079
|
+
}
|
|
2080
|
+
journal.state = "rolled-back";
|
|
1742
2081
|
journal.committedVersion = null;
|
|
1743
2082
|
journal.rollbackAt = new Date().toISOString();
|
|
1744
2083
|
journal.recoveryConflicts = [];
|
|
1745
2084
|
await writeSecureJson(journalPath, journal);
|
|
1746
|
-
return { ok: true, conflicts: [] };
|
|
1747
|
-
}
|
|
2085
|
+
return { ok: true, conflicts: [] };
|
|
2086
|
+
}
|
|
2087
|
+
|
|
2088
|
+
async function planArchiveRollback(root, migrationDir, migration) {
|
|
2089
|
+
const original = await findExactProjectPath(root, migration.originalRel);
|
|
2090
|
+
const canonical = await findExactProjectPath(root, migration.canonicalRel);
|
|
2091
|
+
const stage = path.join(migrationDir, migration.stageRel);
|
|
2092
|
+
const stageExists = await pathExists(stage);
|
|
2093
|
+
if (original) {
|
|
2094
|
+
await assertDirectorySnapshotAtPath(original, migration.snapshot, `${migration.originalRel}: original archive has concurrent bytes; recovery lock retained`);
|
|
2095
|
+
if (canonical) throw noClobberConflict(`${migration.canonicalRel}: both archive paths exist during rollback; recovery lock retained`);
|
|
2096
|
+
if (stageExists) throw noClobberConflict(`${migration.originalRel}: both original and backup archive paths exist during rollback; recovery lock retained`);
|
|
2097
|
+
return { migration, original, canonical: null, stage: null, restore: false };
|
|
2098
|
+
}
|
|
2099
|
+
if (!stageExists) throw noClobberConflict(`${migration.originalRel}: transaction archive backup is missing; recovery lock retained`);
|
|
2100
|
+
await assertDirectorySnapshotAtPath(stage, migration.snapshot, `${migration.originalRel}: transaction archive backup has concurrent bytes; recovery lock retained`);
|
|
2101
|
+
if (canonical) await assertDirectorySnapshotSubsetAtPath(canonical, migration.snapshot, `${migration.canonicalRel}: canonical archive has concurrent bytes; recovery lock retained`);
|
|
2102
|
+
return { migration, original: null, canonical, stage, restore: true };
|
|
2103
|
+
}
|
|
2104
|
+
|
|
2105
|
+
async function executeArchiveRollback(root, journal, plan, rollbackEscrowDir) {
|
|
2106
|
+
if (!plan.restore) return;
|
|
2107
|
+
if (plan.canonical) {
|
|
2108
|
+
await removeArchiveSubsetNoClobber(root, plan.migration, plan.canonical, rollbackEscrowDir, journal.id);
|
|
2109
|
+
await assertExactProjectDirectoryAbsent(root, plan.migration.canonicalRel, `${plan.migration.canonicalRel}: canonical archive remains after rollback cleanup`);
|
|
2110
|
+
}
|
|
2111
|
+
await assertExactProjectDirectoryAbsent(root, plan.migration.originalRel, `${plan.migration.originalRel}: original archive appeared during rollback; recovery lock retained`);
|
|
2112
|
+
await rename(plan.stage, path.join(root, plan.migration.originalRel));
|
|
2113
|
+
await assertExactDirectorySnapshot(root, plan.migration.originalRel, plan.migration.snapshot, `${plan.migration.originalRel}: rollback did not restore original archive bytes`);
|
|
2114
|
+
}
|
|
2115
|
+
|
|
2116
|
+
async function assertDirectorySnapshotSubsetAtPath(absolute, expected, reason) {
|
|
2117
|
+
const actual = await snapshotDirectoryTreeAtPath(absolute);
|
|
2118
|
+
const expectedFiles = new Map(expected.files.map((file) => [file.path, file]));
|
|
2119
|
+
const expectedDirectories = new Set(expected.directories);
|
|
2120
|
+
if (actual.directories.some((directory) => !expectedDirectories.has(directory))
|
|
2121
|
+
|| actual.files.some((file) => {
|
|
2122
|
+
const source = expectedFiles.get(file.path);
|
|
2123
|
+
return !source || source.bytes !== file.bytes || source.sha256 !== file.sha256;
|
|
2124
|
+
})) {
|
|
2125
|
+
throw noClobberConflict(reason);
|
|
2126
|
+
}
|
|
2127
|
+
}
|
|
2128
|
+
|
|
2129
|
+
async function removeArchiveSubsetNoClobber(root, migration, canonicalAbs, escrowDir, id) {
|
|
2130
|
+
const actual = await snapshotDirectoryTreeAtPath(canonicalAbs);
|
|
2131
|
+
const expectedFiles = new Map(migration.snapshot.files.map((file) => [file.path, file]));
|
|
2132
|
+
for (const file of [...actual.files].reverse()) {
|
|
2133
|
+
const expected = expectedFiles.get(file.path);
|
|
2134
|
+
if (!expected || expected.sha256 !== file.sha256 || expected.bytes !== file.bytes) {
|
|
2135
|
+
throw noClobberConflict(`${migration.canonicalRel}/${file.path}: canonical archive has concurrent bytes; recovery lock retained`);
|
|
2136
|
+
}
|
|
2137
|
+
await atomicReplaceFromBuffer(root, path.join(canonicalAbs, file.path), null, `${id}-archive-rollback`, file.sha256, {
|
|
2138
|
+
targetRel: `${migration.canonicalRel}/${file.path}`,
|
|
2139
|
+
escrowDir,
|
|
2140
|
+
phase: "archive-rollback"
|
|
2141
|
+
});
|
|
2142
|
+
}
|
|
2143
|
+
for (const directory of [...actual.directories].sort((left, right) => right.localeCompare(left))) {
|
|
2144
|
+
const target = directory ? path.join(canonicalAbs, directory) : canonicalAbs;
|
|
2145
|
+
try {
|
|
2146
|
+
await rmdir(target);
|
|
2147
|
+
} catch (error) {
|
|
2148
|
+
if (error?.code === "ENOENT") continue;
|
|
2149
|
+
if (error?.code === "ENOTEMPTY" || error?.code === "EEXIST") {
|
|
2150
|
+
throw noClobberConflict(`${migration.canonicalRel}${directory ? `/${directory}` : ""}: archive directory changed during rollback; recovery lock retained`, error);
|
|
2151
|
+
}
|
|
2152
|
+
throw error;
|
|
2153
|
+
}
|
|
2154
|
+
}
|
|
2155
|
+
}
|
|
1748
2156
|
|
|
1749
2157
|
async function recoverInterruptedTransaction(root) {
|
|
1750
2158
|
const lockPath = path.join(root, "dev", "governance_migrations", ".upgrade.lock");
|
|
@@ -2390,7 +2798,7 @@ function resolveRuntimeAcceptance(outputs) {
|
|
|
2390
2798
|
return validateRuntimeAcceptance(witnesses[0]);
|
|
2391
2799
|
}
|
|
2392
2800
|
|
|
2393
|
-
async function createSourceConservation(root, outputs) {
|
|
2801
|
+
async function createSourceConservation(root, outputs, archiveMigrations = []) {
|
|
2394
2802
|
// `freezeGate5Set` is an existing read-only discovery witness. Reuse it
|
|
2395
2803
|
// here rather than creating a registry, pointer, or component authority.
|
|
2396
2804
|
// Its ordered source records become one component of the journal's existing
|
|
@@ -2398,13 +2806,23 @@ async function createSourceConservation(root, outputs) {
|
|
|
2398
2806
|
const frozen = await freezeGate5Set({ root });
|
|
2399
2807
|
assertGate5FrozenSet(frozen);
|
|
2400
2808
|
const outputByTarget = new Map(outputs.map((item) => [item.targetRel, item]));
|
|
2809
|
+
const pathRebindings = archiveMigrations.map((migration) => ({
|
|
2810
|
+
sourcePrefix: `${migration.originalRel}/`,
|
|
2811
|
+
targetPrefix: `${migration.canonicalRel}/`
|
|
2812
|
+
}));
|
|
2401
2813
|
const entries = frozen.items.map((item) => {
|
|
2402
2814
|
const output = outputByTarget.get(item.sourcePath) ?? null;
|
|
2815
|
+
const rebind = pathRebindings.find((candidate) => item.sourcePath.startsWith(candidate.sourcePrefix)) ?? null;
|
|
2816
|
+
const sourcePath = rebind
|
|
2817
|
+
? `${rebind.targetPrefix}${item.sourcePath.slice(rebind.sourcePrefix.length)}`
|
|
2818
|
+
: item.sourcePath;
|
|
2403
2819
|
const sourceWitness = Object.freeze({ sha256: item.sourceIdentity.sha256, bytes: item.sourceIdentity.bytes });
|
|
2404
2820
|
const accepted = output
|
|
2405
2821
|
? Object.freeze({ sha256: output.afterHash, bytes: output.after.length })
|
|
2406
2822
|
: sourceWitness;
|
|
2407
|
-
const disposition =
|
|
2823
|
+
const disposition = rebind
|
|
2824
|
+
? "canonical-path-migration"
|
|
2825
|
+
: output?.preservedRuntimeItem
|
|
2408
2826
|
? "preserve"
|
|
2409
2827
|
: output
|
|
2410
2828
|
? "transaction-output"
|
|
@@ -2414,7 +2832,8 @@ async function createSourceConservation(root, outputs) {
|
|
|
2414
2832
|
? "outside-known-kit-reachability"
|
|
2415
2833
|
: "unchanged-source";
|
|
2416
2834
|
return Object.freeze({
|
|
2417
|
-
sourcePath
|
|
2835
|
+
sourcePath,
|
|
2836
|
+
...(rebind ? { sourceOriginPath: item.sourcePath } : {}),
|
|
2418
2837
|
sourceWitness,
|
|
2419
2838
|
accepted,
|
|
2420
2839
|
// A single exact whole-file range proves the source itself was not
|
|
@@ -2428,7 +2847,7 @@ async function createSourceConservation(root, outputs) {
|
|
|
2428
2847
|
});
|
|
2429
2848
|
});
|
|
2430
2849
|
return Object.freeze({
|
|
2431
|
-
schemaVersion: 1,
|
|
2850
|
+
schemaVersion: archiveMigrations.length > 0 ? 2 : 1,
|
|
2432
2851
|
frozenSetSha256: frozen.frozenSetSha256,
|
|
2433
2852
|
entries: Object.freeze(entries)
|
|
2434
2853
|
});
|
|
@@ -2444,8 +2863,9 @@ function currentStateWitnessBody(journal) {
|
|
|
2444
2863
|
if (Array.isArray(journal.supersedesCurrentStateDigests) && journal.supersedesCurrentStateDigests.length > 0) {
|
|
2445
2864
|
transaction.supersedesCurrentStateDigests = journal.supersedesCurrentStateDigests;
|
|
2446
2865
|
}
|
|
2866
|
+
const hasArchiveMigrations = Array.isArray(journal.archiveMigrations) && journal.archiveMigrations.length > 0;
|
|
2447
2867
|
const body = {
|
|
2448
|
-
schemaVersion: journal.sourceConservation ? 2 : 1,
|
|
2868
|
+
schemaVersion: hasArchiveMigrations ? 3 : journal.sourceConservation ? 2 : 1,
|
|
2449
2869
|
transaction,
|
|
2450
2870
|
// `committed` changes while the transaction runs. The ordered target
|
|
2451
2871
|
// identities below do not, so they are safe to seal before the first
|
|
@@ -2461,6 +2881,7 @@ function currentStateWitnessBody(journal) {
|
|
|
2461
2881
|
runtimeAcceptance: journal.runtimeAcceptance ?? null
|
|
2462
2882
|
};
|
|
2463
2883
|
if (journal.sourceConservation) body.sourceConservation = journal.sourceConservation;
|
|
2884
|
+
if (hasArchiveMigrations) body.archiveMigrations = journal.archiveMigrations.map(archiveMigrationWitness);
|
|
2464
2885
|
return body;
|
|
2465
2886
|
}
|
|
2466
2887
|
|
|
@@ -2474,7 +2895,7 @@ function createCurrentStateWitness(journal) {
|
|
|
2474
2895
|
|
|
2475
2896
|
function validateCurrentStateWitnessValue(value) {
|
|
2476
2897
|
if (!value || typeof value !== "object" || Array.isArray(value)
|
|
2477
|
-
|| ![1, 2].includes(value.schemaVersion)
|
|
2898
|
+
|| ![1, 2, 3].includes(value.schemaVersion)
|
|
2478
2899
|
|| !value.transaction || typeof value.transaction !== "object" || Array.isArray(value.transaction)
|
|
2479
2900
|
|| typeof value.transaction.id !== "string" || !value.transaction.id
|
|
2480
2901
|
|| !["init", "upgrade", "finalize-closeout"].includes(value.transaction.command)
|
|
@@ -2497,7 +2918,13 @@ function validateCurrentStateWitnessValue(value) {
|
|
|
2497
2918
|
if (value.schemaVersion === 1 && value.sourceConservation != null) {
|
|
2498
2919
|
throw new Error("legacy shared current-state witness cannot contain source conservation; no recovery writes attempted");
|
|
2499
2920
|
}
|
|
2500
|
-
const sourceConservation = validateSourceConservation(value.sourceConservation, { required: value.schemaVersion
|
|
2921
|
+
const sourceConservation = validateSourceConservation(value.sourceConservation, { required: value.schemaVersion >= 2 });
|
|
2922
|
+
if (value.schemaVersion < 3 && value.archiveMigrations != null) {
|
|
2923
|
+
throw new Error("legacy shared current-state witness cannot contain archive migrations; no recovery writes attempted");
|
|
2924
|
+
}
|
|
2925
|
+
const archiveMigrations = value.schemaVersion === 3
|
|
2926
|
+
? validateArchiveMigrations(value.archiveMigrations, { requireMaterialized: true })
|
|
2927
|
+
: [];
|
|
2501
2928
|
const knownTargets = new Set([
|
|
2502
2929
|
...requiredTargets,
|
|
2503
2930
|
...upgradeStateTargets,
|
|
@@ -2531,6 +2958,12 @@ function validateCurrentStateWitnessValue(value) {
|
|
|
2531
2958
|
}
|
|
2532
2959
|
}
|
|
2533
2960
|
}
|
|
2961
|
+
for (const migration of archiveMigrations) {
|
|
2962
|
+
const migrated = sourceConservation?.entries.filter((entry) => entry.sourceOriginPath?.startsWith(`${migration.originalRel}/`) && entry.sourcePath.startsWith(`${migration.canonicalRel}/`)) ?? [];
|
|
2963
|
+
if (migrated.length !== migration.snapshot.files.length) {
|
|
2964
|
+
throw new Error("archive migration is detached from the rebound source witness; no recovery writes attempted");
|
|
2965
|
+
}
|
|
2966
|
+
}
|
|
2534
2967
|
const body = {
|
|
2535
2968
|
schemaVersion: value.schemaVersion,
|
|
2536
2969
|
transaction: value.transaction,
|
|
@@ -2539,6 +2972,10 @@ function validateCurrentStateWitnessValue(value) {
|
|
|
2539
2972
|
runtimeAcceptance: value.runtimeAcceptance ?? null
|
|
2540
2973
|
};
|
|
2541
2974
|
if (value.schemaVersion === 2) body.sourceConservation = value.sourceConservation;
|
|
2975
|
+
if (value.schemaVersion === 3) {
|
|
2976
|
+
body.sourceConservation = value.sourceConservation;
|
|
2977
|
+
body.archiveMigrations = value.archiveMigrations;
|
|
2978
|
+
}
|
|
2542
2979
|
if (sha256(Buffer.from(`${JSON.stringify(body)}\n`, "utf8")) !== value.currentStateDigest) {
|
|
2543
2980
|
throw new Error("shared current-state witness digest does not match its ordered components; no recovery writes attempted");
|
|
2544
2981
|
}
|
|
@@ -2551,7 +2988,7 @@ function validateSourceConservation(value, { required = false } = {}) {
|
|
|
2551
2988
|
return null;
|
|
2552
2989
|
}
|
|
2553
2990
|
if (!value || typeof value !== "object" || Array.isArray(value)
|
|
2554
|
-
|| value.schemaVersion
|
|
2991
|
+
|| ![1, 2].includes(value.schemaVersion)
|
|
2555
2992
|
|| typeof value.frozenSetSha256 !== "string" || !/^[a-f0-9]{64}$/.test(value.frozenSetSha256)
|
|
2556
2993
|
|| !Array.isArray(value.entries) || value.entries.length === 0) {
|
|
2557
2994
|
throw new Error("shared current-state source conservation is invalid; no recovery writes attempted");
|
|
@@ -2565,7 +3002,7 @@ function validateSourceConservation(value, { required = false } = {}) {
|
|
|
2565
3002
|
|| !Array.isArray(entry.sourceByteRanges) || entry.sourceByteRanges.length !== 1
|
|
2566
3003
|
|| entry.sourceByteRanges[0]?.start !== 0 || entry.sourceByteRanges[0]?.end !== entry.sourceWitness.bytes
|
|
2567
3004
|
|| entry.sourceByteRanges[0]?.sha256 !== entry.sourceWitness.sha256
|
|
2568
|
-
|| !["preserve", "transaction-output", "unchanged-source", "retained-historical-state", "outside-known-kit-reachability", "closeout-state-finalize"].includes(entry.disposition)
|
|
3005
|
+
|| !["preserve", "transaction-output", "unchanged-source", "retained-historical-state", "outside-known-kit-reachability", "closeout-state-finalize", "canonical-path-migration", "canonical-path-migration-closeout"].includes(entry.disposition)
|
|
2569
3006
|
|| !Array.isArray(entry.existingReaders)
|
|
2570
3007
|
|| entry.existingReaders.some((reader) => !reader || typeof reader !== "object" || Array.isArray(reader) || typeof reader.reader !== "string" || !reader.reader || typeof reader.via !== "string" || !reader.via)
|
|
2571
3008
|
|| typeof entry.priorityRelation !== "string" || !entry.priorityRelation
|
|
@@ -2573,6 +3010,15 @@ function validateSourceConservation(value, { required = false } = {}) {
|
|
|
2573
3010
|
|| !Array.isArray(entry.classifications) || entry.classifications.length === 0 || entry.classifications.some((classification) => typeof classification !== "string" || !classification)) {
|
|
2574
3011
|
throw new Error("shared current-state source conservation entry is invalid; no recovery writes attempted");
|
|
2575
3012
|
}
|
|
3013
|
+
if (["canonical-path-migration", "canonical-path-migration-closeout"].includes(entry.disposition)) {
|
|
3014
|
+
if (value.schemaVersion !== 2 || !isSafeProjectRelative(entry.sourceOriginPath)
|
|
3015
|
+
|| entry.sourceOriginPath === entry.sourcePath
|
|
3016
|
+
|| !entry.sourceOriginPath.startsWith("dev/") || !entry.sourcePath.startsWith("dev/SESSION_LOG_archive/")) {
|
|
3017
|
+
throw new Error("archive source-path rebinding is invalid; no recovery writes attempted");
|
|
3018
|
+
}
|
|
3019
|
+
} else if (entry.sourceOriginPath !== undefined) {
|
|
3020
|
+
throw new Error("unexpected source-origin binding is invalid; no recovery writes attempted");
|
|
3021
|
+
}
|
|
2576
3022
|
if (prior != null && prior.localeCompare(entry.sourcePath) >= 0) {
|
|
2577
3023
|
throw new Error("shared current-state source conservation entries are not in source-path order; no recovery writes attempted");
|
|
2578
3024
|
}
|
|
@@ -2598,7 +3044,8 @@ function validateCurrentStateWitness(journal) {
|
|
|
2598
3044
|
formalUserRules: witness.formalUserRules ?? null,
|
|
2599
3045
|
runtimeAcceptance: witness.runtimeAcceptance ?? null
|
|
2600
3046
|
};
|
|
2601
|
-
if (witness.schemaVersion
|
|
3047
|
+
if (witness.schemaVersion >= 2) actual.sourceConservation = witness.sourceConservation;
|
|
3048
|
+
if (witness.schemaVersion === 3) actual.archiveMigrations = witness.archiveMigrations;
|
|
2602
3049
|
if (JSON.stringify(actual) !== JSON.stringify(expected)) {
|
|
2603
3050
|
throw new Error("shared current-state witness is detached from its transaction components; no recovery writes attempted");
|
|
2604
3051
|
}
|
|
@@ -3334,7 +3781,7 @@ async function loadCommittedCurrentStateWitness(root) {
|
|
|
3334
3781
|
return validateCurrentStateWitness(currentCandidates[0].journal);
|
|
3335
3782
|
}
|
|
3336
3783
|
|
|
3337
|
-
async function findRestoredCurrentStateDigests(root, outputs) {
|
|
3784
|
+
async function findRestoredCurrentStateDigests(root, outputs, archiveMigrations = []) {
|
|
3338
3785
|
const migrationsRoot = path.join(root, "dev", "governance_migrations");
|
|
3339
3786
|
let names;
|
|
3340
3787
|
try { names = await readdir(migrationsRoot); } catch (error) { if (error?.code === "ENOENT") return []; throw error; }
|
|
@@ -3349,7 +3796,8 @@ async function findRestoredCurrentStateDigests(root, outputs) {
|
|
|
3349
3796
|
const journal = JSON.parse(await readFile(journalPath, "utf8"));
|
|
3350
3797
|
if (journal.state !== "committed" || !journal.currentStateWitness) continue;
|
|
3351
3798
|
await validateRecoveryJournal(root, journal, journalPath);
|
|
3352
|
-
if (await
|
|
3799
|
+
if (await journalMatchesCurrentState(root, journal)
|
|
3800
|
+
|| await journalIsRestoredByOutputs(root, journal, outputWitnesses, archiveMigrations)) {
|
|
3353
3801
|
restored.push(journal.currentStateWitness.currentStateDigest);
|
|
3354
3802
|
}
|
|
3355
3803
|
} catch (error) {
|
|
@@ -3359,8 +3807,19 @@ async function findRestoredCurrentStateDigests(root, outputs) {
|
|
|
3359
3807
|
return [...new Set(restored)].sort((left, right) => left.localeCompare(right));
|
|
3360
3808
|
}
|
|
3361
3809
|
|
|
3362
|
-
async function journalIsRestoredByOutputs(root, journal, outputWitnesses) {
|
|
3810
|
+
async function journalIsRestoredByOutputs(root, journal, outputWitnesses, archiveMigrations = []) {
|
|
3363
3811
|
const witness = validateCurrentStateWitness(journal);
|
|
3812
|
+
const archiveRebindings = new Map();
|
|
3813
|
+
for (const migration of archiveMigrations) {
|
|
3814
|
+
for (const file of migration.snapshot.files) {
|
|
3815
|
+
archiveRebindings.set(`${migration.originalRel}/${file.path}`, {
|
|
3816
|
+
sourcePath: `${migration.originalRel}/${file.path}`,
|
|
3817
|
+
reboundPath: `${migration.canonicalRel}/${file.path}`,
|
|
3818
|
+
sha256: file.sha256,
|
|
3819
|
+
bytes: file.bytes
|
|
3820
|
+
});
|
|
3821
|
+
}
|
|
3822
|
+
}
|
|
3364
3823
|
for (const entry of journal.entries) {
|
|
3365
3824
|
const replacement = outputWitnesses.get(entry.targetRel);
|
|
3366
3825
|
if (replacement) {
|
|
@@ -3376,6 +3835,11 @@ async function journalIsRestoredByOutputs(root, journal, outputWitnesses) {
|
|
|
3376
3835
|
if (replacement.sha256 !== entry.accepted.sha256 || replacement.bytes !== entry.accepted.bytes) return false;
|
|
3377
3836
|
continue;
|
|
3378
3837
|
}
|
|
3838
|
+
const archiveRebinding = archiveRebindings.get(entry.sourcePath);
|
|
3839
|
+
if (archiveRebinding) {
|
|
3840
|
+
if (archiveRebinding.sha256 !== entry.accepted.sha256 || archiveRebinding.bytes !== entry.accepted.bytes) return false;
|
|
3841
|
+
continue;
|
|
3842
|
+
}
|
|
3379
3843
|
const bytes = await readOptionalBuffer(path.join(root, entry.sourcePath));
|
|
3380
3844
|
if (!bytes || sha256(bytes) !== entry.accepted.sha256 || bytes.length !== entry.accepted.bytes) return false;
|
|
3381
3845
|
}
|
|
@@ -3557,11 +4021,14 @@ async function writeCloseoutFinalizeJournal(root, version, prior) {
|
|
|
3557
4021
|
const changed = currentWitness.sha256 !== sourceWitness.sha256 || currentWitness.bytes !== sourceWitness.bytes;
|
|
3558
4022
|
return {
|
|
3559
4023
|
sourcePath: item.sourcePath,
|
|
4024
|
+
...(entry?.sourceOriginPath ? { sourceOriginPath: entry.sourceOriginPath } : {}),
|
|
3560
4025
|
sourceWitness,
|
|
3561
4026
|
accepted: currentWitness,
|
|
3562
4027
|
sourceByteRanges: [{ start: 0, end: sourceWitness.bytes, sha256: sourceWitness.sha256 }],
|
|
3563
4028
|
disposition: isCloseoutFinalizeTarget(item.sourcePath) && changed
|
|
3564
|
-
?
|
|
4029
|
+
? entry?.sourceOriginPath
|
|
4030
|
+
? "canonical-path-migration-closeout"
|
|
4031
|
+
: "closeout-state-finalize"
|
|
3565
4032
|
: entry?.disposition ?? (item.classifications.includes("transaction-state") ? "retained-historical-state" : "unchanged-source"),
|
|
3566
4033
|
existingReaders: entry?.existingReaders ?? item.existingReaders.map((reader) => ({ reader: reader.reader, via: reader.via })),
|
|
3567
4034
|
priorityRelation: entry?.priorityRelation ?? item.priorityConflict.relation,
|
|
@@ -3590,6 +4057,7 @@ async function writeCloseoutFinalizeJournal(root, version, prior) {
|
|
|
3590
4057
|
runtimeAcceptance: null,
|
|
3591
4058
|
runtimeAcceptanceReadback: null,
|
|
3592
4059
|
sourceConservation,
|
|
4060
|
+
archiveMigrations: oldWitness.archiveMigrations ?? [],
|
|
3593
4061
|
supersedesCurrentStateDigests: [oldWitness.currentStateDigest],
|
|
3594
4062
|
currentStateWitness: null,
|
|
3595
4063
|
currentStateReadback: null
|