@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.
@@ -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 (["ACK_QA_INTERRUPT_AFTER_REPLACE", "ACK_QA_INTERRUPT_AFTER_JOURNAL_COMMIT"].includes(error?.code)) throw error;
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
- if (conflicts.length > 0) {
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
- journal.state = "rolled-back";
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 = output?.preservedRuntimeItem
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: item.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 === 2 });
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 !== 1
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 === 2) actual.sourceConservation = witness.sourceConservation;
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 journalIsRestoredByOutputs(root, journal, outputWitnesses)) {
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
- ? "closeout-state-finalize"
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