Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

fix: finalize restored checkouts with reviewed metadata evidence

[._.]/ Adam Eivy9c20f6a2e193
diff --git a/docs/features/branch-reconciliation.md b/docs/features/branch-reconciliation.md
index 446a53de02..2d7196ef07 100644
--- a/docs/features/branch-reconciliation.md
+++ b/docs/features/branch-reconciliation.md
@@ -172,6 +172,48 @@ rows. Existing malformed numbered rows are never silently ignored or replaced.
After an interrupted recovery, read status again and obtain a new review for
the new journal digest rather than replaying an old approval.
+### Finalizing originals that have already been restored
+
+Metadata can change after the post-move proof succeeds. In an observed case,
+directory modification times changed and some residual compression attributes
+returned with exactly their archived original bytes. The writer was not
+established. The restore's final verification correctly retained its reservation.
+
+When both original directories are already back at their exact original inode
+identities, a separate completion path can record this narrow delta without
+moving or repairing anything:
+
+1. `POST /review-restored-finalization` accepts the transaction identifiers and
+ fresh journal digest. It binds the previous accepted restore review and its
+ immutable post-move observations, verifies the archive, and captures a new
+ immutable full source snapshot under the existing reservation and executor.
+2. Independently review the new digest and complete evidence. Only directory
+ modification-time changes and reappearance of original residual
+ `com.apple.decmpfs` bytes are eligible. Reappeared attributes must match both
+ their prior raw preimages and the verified archive; the file must remain
+ uncompressed. Administration, file contents and modification times, paths,
+ identities, permissions, ownership, ACLs, flags, and all other attributes
+ remain exact. Unknown drift stays held.
+3. `POST /finalize-restored` accepts that separately reviewed digest. It repeats
+ the review, verifies the exact snapshot again, and rechecks the branch,
+ ownership, policy and reservation before recording completion and releasing
+ the exact reservation. It performs no directory moves, metadata writes,
+ branch changes or cleanup. Original manifests, raw values, observations,
+ archives and journal evidence remain retained.
+
+The bootstrap CLI exposes the same separate operations:
+
+```sh
+node scripts/recover-initialized-checkout.js review-finalization /absolute/request.json \
+ --install-root /absolute/PortOS --output /absolute/new-finalization-review.jsonl
+node scripts/recover-initialized-checkout.js finalize /absolute/approved-request.json \
+ --install-root /absolute/PortOS --output /absolute/new-finalization.jsonl
+```
+
+These operations do not relax normal retirement or restore-move checks, and
+finalization does not authorize branch deletion. Any subsequent retirement
+requires a fresh review and preservation proof for the current checkout.
+
Managed checkout creation/adoption/removal, claim binding, the full workspace
preparation through agent registration/spawn, and supported Git API writers
share admission under the canonical common Git directory. Synthetic read-only
diff --git a/scripts/lib/initialized_checkout_archive.py b/scripts/lib/initialized_checkout_archive.py
index 9c399e4cd7..742814cb1b 100644
--- a/scripts/lib/initialized_checkout_archive.py
+++ b/scripts/lib/initialized_checkout_archive.py
@@ -923,7 +923,164 @@ def review_metadata_recovery(request):
'changedPaths': len({(row['part'], row['path']) for row in changes})}
+def load_bound_evidence(root, reference, prefix):
+ if (not isinstance(reference, dict) or set(reference) != {'file', 'sha256', 'digest'}
+ or not isinstance(reference['digest'], str)
+ or not re.fullmatch(r'[0-9a-f]{64}', reference['digest'])
+ or reference['file'] != prefix + reference['digest'] + '.json'):
+ fail('restored-finalization-evidence-invalid')
+ path = root / reference['file']
+ with os.fdopen(os.open(path, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK), 'rb') as source:
+ info = os.fstat(source.fileno())
+ if (not stat.S_ISREG(info.st_mode) or info.st_nlink != 1
+ or stat.S_IMODE(info.st_mode) != 0o600 or info.st_uid != os.getuid()
+ or info.st_size > 256 * 1024 ** 2):
+ fail('restored-finalization-evidence-unsafe')
+ encoded = source.read(256 * 1024 ** 2 + 1)
+ evidence = json.loads(encoded)
+ # All supported publishers use this canonical encoding. Exact equality also
+ # rejects duplicate JSON keys rather than interpreting an ambiguous ledger.
+ if (hashlib.sha256(encoded).hexdigest() != reference['sha256']
+ or digest(evidence) != reference['digest']
+ or encoded != (json.dumps(evidence, sort_keys=True) + '\n').encode('utf-8')):
+ fail('restored-finalization-evidence-changed')
+ return evidence
+
+
+def restored_finalization_context(root, saved, request):
+ prior = load_metadata_recovery(root, saved, request)
+ accepted = request['metadataRecovery']
+ canonical_prior = load_bound_evidence(root, {
+ 'file': accepted['evidenceFile'], 'sha256': accepted['evidenceSha256'],
+ 'digest': accepted['digest']}, 'metadata-recovery-')
+ if canonical_prior != prior:
+ fail('restored-finalization-prior-review-changed')
+ located, sources = original_sources(root, saved['facts'])
+ if any(row['state'] != 'original' for row in located.values()):
+ fail('restored-finalization-original-placement-required')
+ if metadata_recovery_changes(root, saved, located, prior['sources']) != prior['changes']:
+ fail('restored-finalization-prior-review-changed')
+ references = request.get('postMoveObservations')
+ if not isinstance(references, list) or len(references) != 2:
+ fail('restored-finalization-postmove-proof-required')
+ for part, reference in zip(('administration', 'working'), references):
+ # An already-original administration restore is an authenticated no-op,
+ # so the old move command legitimately produced no postmove artifact.
+ if (reference is None and part == 'administration'
+ and prior['initialPlacements'][part] == 'original'
+ and sources[part] == saved['facts']['sources'][part]):
+ continue
+ observation = load_bound_evidence(root, reference, 'metadata-recovery-postmove-')
+ positions = {
+ label: {'original': 'matching' if state == 'original' else 'absent',
+ 'quarantine': 'absent' if state == 'original' else 'matching', 'state': state}
+ for label, state in {'administration': 'original',
+ 'working': 'original' if part == 'working' else 'quarantine'}.items()}
+ if observation != {'version': 1, 'manifestSha256': request['manifestSha256'],
+ 'acceptedMetadataRecovery': accepted, 'part': part,
+ 'placements': positions, 'sources': prior['sources']}:
+ fail('restored-finalization-postmove-proof-changed')
+ return prior, located, sources
+
+
+def restored_finalization_changes(root, saved, prior, sources):
+ # This is a record-only acceptance after both moves, never a move policy.
+ # Directory mtimes are evidence of an observed change, not a causal claim.
+ baseline = saved['facts']['sources']
+ if sources['administration'] != baseline['administration']:
+ fail('restored-finalization-administration-changed')
+ expected, actual = prior['sources']['working'], sources['working']
+ if len(expected) != len(actual):
+ fail('restored-finalization-source-layout-changed')
+ preimages = {(row['part'], row['path'], row['attribute']): row for row in prior['changes']}
+ changes, total = [], 0
+ for original, before, after in zip(baseline['working'], expected, actual):
+ excluded = {'xattrs', 'mtimeNs'} if before['kind'] == 'directory' else {'xattrs'}
+ if {k: v for k, v in before.items() if k not in excluded} != {
+ k: v for k, v in after.items() if k not in excluded}:
+ fail('restored-finalization-source-content-or-identity-changed')
+ if before['mtimeNs'] != after['mtimeNs']:
+ changes.append({'part': 'working', 'path': before['path'], 'field': 'mtimeNs',
+ 'before': before['mtimeNs'], 'after': after['mtimeNs']})
+ for name in sorted(set(before['xattrs']) | set(after['xattrs'])):
+ old, new = before['xattrs'].get(name), after['xattrs'].get(name)
+ if old == new:
+ continue
+ preimage = preimages.get(('working', before['path'], name), {})
+ if (name != 'com.apple.decmpfs' or old is not None or new is None
+ or before['kind'] != 'file' or before['flags'] & 0x20
+ or original['xattrs'].get(name) != new
+ or preimage.get('beforeSha256') != new or preimage.get('afterSha256') is not None
+ or 'beforeBase64' not in preimage):
+ fail('restored-finalization-unsupported-attribute-change:' + name)
+ archived = raw_xattrs(root / 'archive/working' / before['path']).get(name)
+ current = raw_xattrs(Path(saved['facts']['release']['path']) / before['path']).get(name)
+ if (archived is None or current != archived
+ or hashlib.sha256(archived).hexdigest() != new
+ or base64.b64encode(archived).decode('ascii') != preimage['beforeBase64']):
+ fail('restored-finalization-preimage-missing-or-changed')
+ total += len(archived) + len(current)
+ if total > 16 * 1024 ** 2:
+ fail('metadata-recovery-evidence-budget-exceeded')
+ changes.append({'part': 'working', 'path': before['path'], 'attribute': name,
+ 'beforeSha256': None, 'afterSha256': new,
+ 'originalSha256': original['xattrs'][name],
+ 'originalBase64': preimage['beforeBase64'],
+ 'afterBase64': base64.b64encode(current).decode('ascii')})
+ return changes
+
+
+def restored_finalization_snapshot(request):
+ if not re.fullmatch(r'[0-9a-f]{64}', request.get('manifestSha256', '')):
+ fail('restored-finalization-manifest-proof-required')
+ root, saved = load_transaction(request)
+ verify_saved_archive(root, saved)
+ prior, located, sources = restored_finalization_context(root, saved, request)
+ changes = restored_finalization_changes(root, saved, prior, sources)
+ verify_live_common(root, saved, restoring=True)
+ if original_sources(root, saved['facts']) != (located, sources):
+ fail('restored-finalization-observation-changed')
+ evidence = {'version': 1, 'manifestSha256': request['manifestSha256'],
+ 'transactionIdentity': saved['transactionIdentity'],
+ 'originalFingerprint': saved['facts']['fingerprint'],
+ 'acceptedMetadataRecovery': request['metadataRecovery'],
+ 'postMoveObservations': request['postMoveObservations'],
+ 'placements': located, 'sources': sources, 'changes': changes}
+ return root, evidence
+
+
+def review_restored_finalization(request):
+ root, evidence = restored_finalization_snapshot(request)
+ stored = immutable_recovery_evidence(root, 'restored-finalization-', evidence)
+ return {'restoredFinalization': {'version': 1, 'evidenceFile': stored['file'],
+ 'evidenceSha256': stored['sha256'], 'digest': stored['digest']},
+ 'placements': {label: row['state'] for label, row in evidence['placements'].items()},
+ 'changeCounts': {
+ 'directoryMtimeChanged': sum(row.get('field') == 'mtimeNs' for row in evidence['changes']),
+ 'residualCompressionReappeared': sum(row.get('attribute') == 'com.apple.decmpfs'
+ for row in evidence['changes'])},
+ 'changedPaths': len({(row['part'], row['path']) for row in evidence['changes']})}
+
+
+def verify_restored_finalization(request):
+ accepted = request.get('restoredFinalization')
+ if (not isinstance(accepted, dict)
+ or set(accepted) != {'version', 'evidenceFile', 'evidenceSha256', 'digest'}
+ or accepted['version'] != 1):
+ fail('restored-finalization-proof-invalid')
+ root, evidence = restored_finalization_snapshot(request)
+ recorded = load_bound_evidence(root, {'file': accepted['evidenceFile'],
+ 'sha256': accepted['evidenceSha256'],
+ 'digest': accepted['digest']}, 'restored-finalization-')
+ if recorded != evidence:
+ fail('restored-finalization-review-changed')
+ return {'verified': True, 'alreadyRestored': True, 'placements': evidence['placements'],
+ 'fingerprint': evidence['originalFingerprint'], 'restoredFinalizationAccepted': True}
+
+
def verify(request):
+ if 'restoredFinalization' in request:
+ fail('restored-finalization-separate-command-required')
root, saved = load_transaction(request)
facts = saved['facts']
recovering = 'metadataRecovery' in request
@@ -1044,11 +1201,14 @@ def main():
elif action == 'status':
root, saved = load_transaction(request)
result = {'placements': placements(root, saved['facts']), 'fingerprint': saved['facts']['fingerprint']}
- elif action in ('preserve', 'verify', 'move', 'review-metadata-recovery'):
+ elif action in ('preserve', 'verify', 'move', 'review-metadata-recovery',
+ 'review-restored-finalization', 'verify-restored-finalization'):
fd = lock_file(transaction(request['transactionDir']), 'backend.lock')
try:
result = {'preserve': preserve, 'verify': verify, 'move': move,
- 'review-metadata-recovery': review_metadata_recovery}[action](request)
+ 'review-metadata-recovery': review_metadata_recovery,
+ 'review-restored-finalization': review_restored_finalization,
+ 'verify-restored-finalization': verify_restored_finalization}[action](request)
finally:
os.close(fd)
else:
diff --git a/scripts/lib/initialized_checkout_archive_test.py b/scripts/lib/initialized_checkout_archive_test.py
index 60bb3e870e..3bdc853a30 100644
--- a/scripts/lib/initialized_checkout_archive_test.py
+++ b/scripts/lib/initialized_checkout_archive_test.py
@@ -615,6 +615,127 @@ class NativeArchive(unittest.TestCase):
self.assertTrue(archive.verify({**accepted, 'mode': 'restore'})['metadataRecoveryAccepted'])
self.assertEqual((self.txn / 'manifest.json').read_bytes(), before)
+ def restored_finalization_fixture(self, move_administration=False):
+ subprocess.run(['/usr/bin/xattr', '-w', 'com.apple.decmpfs', 'fixture-residual',
+ str(self.work / 'base.txt')], check=True)
+ self.preserve()
+ for part in (('administration', 'working') if move_administration else ('working',)):
+ archive.move({**self.request, 'part': part, 'direction': 'quarantine'})
+ moved = self.txn / 'quarantine/working/base.txt'
+ if 'com.apple.decmpfs' in archive.raw_xattrs(moved):
+ subprocess.run(['/usr/bin/xattr', '-d', 'com.apple.decmpfs', str(moved)], check=True)
+ review = archive.review_metadata_recovery(self.request)
+ request = {**self.request, 'metadataRecovery': review['metadataRecovery']}
+ observations = [archive.move({**request, 'part': part, 'direction': 'restore'}).get('postMoveObservation')
+ for part in ('administration', 'working')]
+ self.assertTrue(archive.verify({**request, 'mode': 'restore'})['verified'])
+ # Actual disposable-file operations reproduce a delayed reappearance and
+ # directory timestamp change after both original-inode moves succeeded.
+ subprocess.run(['/usr/bin/xattr', '-w', 'com.apple.decmpfs', 'fixture-residual',
+ str(self.work / 'base.txt')], check=True)
+ directory = self.work / 'empty'
+ info = directory.stat()
+ os.utime(directory, ns=(info.st_atime_ns, info.st_mtime_ns + 1_000_000_000))
+ return {**request, 'postMoveObservations': observations}
+
+ def test_restored_finalization_records_delayed_metadata_without_moving_or_rewriting_originals(self):
+ request = self.restored_finalization_fixture()
+ baseline = (self.txn / 'manifest.json').read_bytes()
+ before = archive.original_sources(self.txn, archive.load_transaction(request)[1]['facts'])
+ with self.assertRaisesRegex(RuntimeError, 'metadata-recovery-review-changed'):
+ archive.verify({**request, 'mode': 'restore'})
+ result = subprocess.run([sys.executable, str(Path(archive.__file__))],
+ input=json.dumps({**request, 'command': 'review-restored-finalization'}) + '\n',
+ env=self.env, capture_output=True, text=True, check=True)
+ reviewed = json.loads(result.stdout)
+ self.assertEqual(reviewed['changeCounts'], {'directoryMtimeChanged': 1, 'residualCompressionReappeared': 1})
+ accepted = {**request, 'restoredFinalization': reviewed['restoredFinalization']}
+ evidence = json.loads((self.txn / reviewed['restoredFinalization']['evidenceFile']).read_text())
+ returned = next(row for row in evidence['changes'] if row.get('attribute') == 'com.apple.decmpfs')
+ self.assertEqual(archive.base64.b64decode(returned['originalBase64']), b'fixture-residual')
+ self.assertEqual(returned['afterBase64'], returned['originalBase64'])
+ with patch.object(archive, 'exclusive_rename', side_effect=AssertionError('no move allowed')):
+ self.assertTrue(archive.verify_restored_finalization(accepted)['restoredFinalizationAccepted'])
+ self.assertTrue(archive.verify_restored_finalization(accepted)['alreadyRestored'])
+ for command in ({'command': 'verify', 'mode': 'restore'},
+ {'command': 'move', 'direction': 'restore', 'part': 'working'}):
+ result = subprocess.run([sys.executable, str(Path(archive.__file__))],
+ input=json.dumps({**accepted, **command}) + '\n',
+ env=self.env, capture_output=True, text=True)
+ self.assertEqual(result.returncode, 1)
+ self.assertEqual(json.loads(result.stdout)['reason'], 'restored-finalization-separate-command-required')
+ self.assertEqual(archive.original_sources(self.txn, archive.load_transaction(request)[1]['facts']), before)
+ self.assertEqual((self.txn / 'manifest.json').read_bytes(), baseline)
+ self.assertTrue(archive.verify({**self.request, 'mode': 'standalone'})['standalone'])
+
+ def test_restored_finalization_refuses_stale_snapshot_and_noneligible_changes(self):
+ request = self.restored_finalization_fixture()
+ review = archive.review_restored_finalization(request)
+ accepted = {**request, 'restoredFinalization': review['restoredFinalization']}
+ original_manifest = archive.manifest
+ mutations = {
+ 'content': lambda row: row.update(sha256='0' * 64),
+ 'file mtime': lambda row: row.update(mtimeNs=row['mtimeNs'] + 1),
+ 'flags': lambda row: row.update(flags=row['flags'] | 0x20),
+ 'ownership': lambda row: row.update(uid=row['uid'] + 1),
+ 'acl': lambda row: row.update(acl='changed'),
+ 'identity': lambda row: row['filesystemIdentity'].update(ino=0),
+ 'security attribute': lambda row: row['xattrs'].update({'com.apple.quarantine': '0' * 64}),
+ 'wrong compression': lambda row: row['xattrs'].update({'com.apple.decmpfs': '0' * 64}),
+ }
+ for name, mutation in mutations.items():
+ def observe(path, reject_links=False):
+ rows = original_manifest(path, reject_links)
+ if path == self.work:
+ rows = copy.deepcopy(rows)
+ mutation(next(row for row in rows if row['path'] == 'base.txt'))
+ return rows
+ with self.subTest(change=name), patch.object(archive, 'manifest', observe):
+ with self.assertRaisesRegex(RuntimeError, 'restored-finalization-source-content-or-identity-changed|restored-finalization-unsupported-attribute-change'):
+ archive.review_restored_finalization(request)
+ directory = self.work / 'empty'
+ info = directory.stat()
+ os.utime(directory, ns=(info.st_atime_ns, info.st_mtime_ns + 1))
+ with self.assertRaisesRegex(RuntimeError, 'restored-finalization-review-changed'):
+ archive.verify_restored_finalization(accepted)
+ refreshed = archive.review_restored_finalization(request)
+ self.assertNotEqual(refreshed['restoredFinalization']['digest'], review['restoredFinalization']['digest'])
+ self.assertTrue(archive.verify_restored_finalization(
+ {**request, 'restoredFinalization': refreshed['restoredFinalization']})['verified'])
+
+ def test_restored_finalization_requires_exact_prior_observations_and_raw_preimages(self):
+ request = self.restored_finalization_fixture(move_administration=True)
+ self.assertTrue(archive.review_restored_finalization(request)['restoredFinalization'])
+ for references in ([], request['postMoveObservations'][::-1],
+ [request['postMoveObservations'][0]] * 2,
+ [None, request['postMoveObservations'][1]],
+ [request['postMoveObservations'][0], None]):
+ with self.subTest(references=references), self.assertRaisesRegex(RuntimeError, 'restored-finalization-postmove-proof|restored-finalization-evidence-invalid'):
+ archive.review_restored_finalization({**request, 'postMoveObservations': references})
+ reference = request['postMoveObservations'][0]
+ path = self.txn / reference['file']
+ encoded = path.read_bytes()
+ path.write_bytes(encoded + b' ')
+ with self.assertRaisesRegex(RuntimeError, 'restored-finalization-evidence-changed'):
+ archive.review_restored_finalization(request)
+ path.write_bytes(encoded)
+ attributes = archive.raw_xattrs
+ def invalid_raw(path):
+ values = attributes(path)
+ return {**values, 'com.apple.decmpfs': b'wrong'} if path == self.work / 'base.txt' else values
+ # Keep the observed manifest hashes stable to isolate the separate raw
+ # preimage check against a racing attribute read.
+ manifest = archive.manifest(self.work)
+ real_manifest = archive.manifest
+ def stable_manifest(path, reject_links=False):
+ return manifest if path == self.work else real_manifest(path, reject_links)
+ with patch.object(archive, 'raw_xattrs', invalid_raw), patch.object(archive, 'manifest', stable_manifest):
+ with self.assertRaisesRegex(RuntimeError, 'restored-finalization-preimage-missing-or-changed'):
+ archive.review_restored_finalization(request)
+ archive.exclusive_rename(self.work, self.txn / 'quarantine/working')
+ with self.assertRaisesRegex(RuntimeError, 'restored-finalization-original-placement-required'):
+ archive.review_restored_finalization(request)
+
def test_fresh_process_refuses_foreign_rollback_target(self):
self.preserve()
archive.move({**self.request, 'part': 'working', 'direction': 'quarantine'})
diff --git a/scripts/recover-initialized-checkout.js b/scripts/recover-initialized-checkout.js
index 0375040d96..5c6813f75e 100644
--- a/scripts/recover-initialized-checkout.js
+++ b/scripts/recover-initialized-checkout.js
@@ -4,7 +4,7 @@
* Run reviewed code from an independent checkout when its install's durable
* retirement cut prevents the normal update. Never edits the install's code.
*
- * node scripts/recover-initialized-checkout.js review|restore request.json \
+ * node scripts/recover-initialized-checkout.js review|restore|review-finalization|finalize request.json \
* --install-root /absolute/install --output /absolute/new-private-record.jsonl
*
* Output is an exclusive 0600 JSONL journal: a durable pending intent precedes
@@ -23,13 +23,19 @@ const MAX_REQUEST_BYTES = 16 * 1024;
const MAX_RESPONSE_BYTES = 1024 * 1024;
const HASH = /^[a-f0-9]{64}$/;
const ID = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/;
+const ACTIONS = {
+ review: { method: 'reviewMetadataRestore', acceptedReview: false },
+ restore: { method: 'restoreMetadata', acceptedReview: true },
+ 'review-finalization': { method: 'reviewRestoredFinalization', acceptedReview: false },
+ finalize: { method: 'finalizeRestored', acceptedReview: true },
+};
const fail = code => { throw Object.assign(new Error(code), { recoveryCode: code }); };
const object = value => value !== null && typeof value === 'object' && !Array.isArray(value);
const exactKeys = (value, keys) => object(value) && Object.keys(value).sort().join(',') === [...keys].sort().join(',');
export function parseRecoveryArgs(argv) {
const [action, requestPath, ...options] = argv;
- if (!['review', 'restore'].includes(action) || !requestPath || requestPath.startsWith('--')) fail('recovery-usage');
+ if (!Object.hasOwn(ACTIONS, action) || !requestPath || requestPath.startsWith('--')) fail('recovery-usage');
const parsed = { action, requestPath };
for (let i = 0; i < options.length; i += 2) {
const key = { '--install-root': 'installRoot', '--output': 'outputPath' }[options[i]];
@@ -58,11 +64,12 @@ async function readJson(path, limit) {
}
function validateRequest(action, request) {
- const keys = ['appId', 'transactionId', 'journalDigest', ...(action === 'restore' ? ['review'] : [])];
+ const acceptedReview = ACTIONS[action].acceptedReview;
+ const keys = ['appId', 'transactionId', 'journalDigest', ...(acceptedReview ? ['review'] : [])];
if (!exactKeys(request, keys) || typeof request.appId !== 'string' || !/^[a-zA-Z0-9_-]{1,128}$/.test(request.appId)
|| typeof request.transactionId !== 'string' || !ID.test(request.transactionId)
|| typeof request.journalDigest !== 'string' || !HASH.test(request.journalDigest)
- || (action === 'restore' && (!exactKeys(request.review, ['digest'])
+ || (acceptedReview && (!exactKeys(request.review, ['digest'])
|| typeof request.review.digest !== 'string' || !HASH.test(request.review.digest)))) fail('recovery-request-invalid');
return request;
}
@@ -121,7 +128,7 @@ export async function runRecovery(argv, { load = loadRecovery, stdout = value =>
}
process.env.PORTOS_DATA_ROOT = options.installRoot;
const service = await load(deps, options.installRoot);
- const response = await service[options.action === 'review' ? 'reviewMetadataRestore' : 'restoreMetadata'](request);
+ const response = await service[ACTIONS[options.action].method](request);
const completion = { completedAt: new Date().toISOString(), outcome: 'response-recorded', response };
const serialized = JSON.stringify(completion);
if (Buffer.byteLength(serialized) > MAX_RESPONSE_BYTES) fail('recovery-response-exceeds-budget');
diff --git a/scripts/recover-initialized-checkout.test.js b/scripts/recover-initialized-checkout.test.js
index 7d69597378..f2e71d6403 100644
--- a/scripts/recover-initialized-checkout.test.js
+++ b/scripts/recover-initialized-checkout.test.js
@@ -18,7 +18,7 @@ async function fixture(action = 'review') {
const apps = { apps: { 'portos-default': { repoPath: root } } };
await writeFile(join(root, 'data/apps.json'), JSON.stringify(apps));
await writeFile(join(root, 'data/cos/state.json'), JSON.stringify({ agents: {} }));
- const body = { ...request, ...(action === 'restore' ? { review: { digest: 'b'.repeat(64) } } : {}) };
+ const body = { ...request, ...(['restore', 'finalize'].includes(action) ? { review: { digest: 'b'.repeat(64) } } : {}) };
const input = join(root, 'request.json');
const output = join(root, 'result.jsonl');
await writeFile(input, JSON.stringify(body));
@@ -26,11 +26,12 @@ async function fixture(action = 'review') {
}
describe('initialized checkout recovery CLI', () => {
- it.each(['review', 'restore'])('pins the existing install, journals intent first, and invokes only guarded %s', async action => {
+ it.each(['review', 'restore', 'review-finalization', 'finalize'])('pins the existing install, journals intent first, and invokes only guarded %s', async action => {
const f = await fixture(action);
const before = process.env.PORTOS_DATA_ROOT;
const stdout = vi.fn();
- const method = action === 'review' ? 'reviewMetadataRestore' : 'restoreMetadata';
+ const method = { review: 'reviewMetadataRestore', restore: 'restoreMetadata',
+ 'review-finalization': 'reviewRestoredFinalization', finalize: 'finalizeRestored' }[action];
const load = vi.fn(async (deps, root) => {
expect(root).toBe(f.root);
expect(process.env.PORTOS_DATA_ROOT).toBe(f.root);
@@ -54,6 +55,15 @@ describe('initialized checkout recovery CLI', () => {
expect(JSON.parse(stdout.mock.calls[0][0]).reviewDigest).toBe('c'.repeat(64));
});
+ it('requires a separate exact review for finalization and never falls back to restore', async () => {
+ const f = await fixture('finalize');
+ await writeFile(f.input, JSON.stringify(request));
+ const load = vi.fn();
+ expect(await runRecovery(f.args, { load, stdout: () => {} })).toBe(1);
+ expect(load).not.toHaveBeenCalled();
+ await expect(stat(f.output)).rejects.toMatchObject({ code: 'ENOENT' });
+ });
+
it.each(['missing-install', 'missing-agents', 'invalid-state', 'wrong-app-root', 'conflicting-app-id', 'inherited-app-id', 'invalid-json', 'extra-request-key', 'missing-review', 'unknown-option', 'existing-output'])(
'refuses %s before invoking recovery', async change => {
const f = await fixture('restore');
diff --git a/server/lib/hostControlRoutes.js b/server/lib/hostControlRoutes.js
index 6edcbb2cdc..641114cc72 100644
--- a/server/lib/hostControlRoutes.js
+++ b/server/lib/hostControlRoutes.js
@@ -422,6 +422,8 @@ export const HOST_CONTROL_ROUTES = Object.freeze([
'POST /api/cos/schedule/branch-reconcile/initialized-checkouts/restore',
'POST /api/cos/schedule/branch-reconcile/initialized-checkouts/review-metadata-restore',
'POST /api/cos/schedule/branch-reconcile/initialized-checkouts/restore-metadata',
+ 'POST /api/cos/schedule/branch-reconcile/initialized-checkouts/review-restored-finalization',
+ 'POST /api/cos/schedule/branch-reconcile/initialized-checkouts/finalize-restored',
'POST /api/cos/schedule/branch-reconcile/initialized-checkouts/verify-archive',
'POST /api/cos/schedule/branch-reconcile/initialized-checkouts/review-branch',
'POST /api/cos/schedule/branch-reconcile/initialized-checkouts/retire-branch',
diff --git a/server/lib/validation.js b/server/lib/validation.js
index 8c05f98cde..68d4614666 100644
--- a/server/lib/validation.js
+++ b/server/lib/validation.js
@@ -2885,6 +2885,7 @@ export const initializedCheckoutBranchRetireSchema = initializedCheckoutRestoreS
export const initializedCheckoutMetadataRestoreSchema = initializedCheckoutRestoreSchema.extend({
review: z.object({ digest: z.string().regex(/^[a-f0-9]{64}$/) }).strict(),
}).strict();
+export const initializedCheckoutFinalizationSchema = initializedCheckoutMetadataRestoreSchema;
// Per-app task-type overrides (routes/apps/taskTypes.js)
export const appTaskTypeToggleBodySchema = z.object({ enabled: z.boolean() });
diff --git a/server/routes/cosScheduleRoutes.js b/server/routes/cosScheduleRoutes.js
index 2e3991ac62..c170107d3d 100644
--- a/server/routes/cosScheduleRoutes.js
+++ b/server/routes/cosScheduleRoutes.js
@@ -9,7 +9,7 @@ import { z } from 'zod';
import * as taskSchedule from '../services/taskSchedule.js';
import { logCosScheduleUpdate } from '../services/userActionScheduleLog.js';
import { asyncHandler, ServerError } from '../lib/errorHandler.js';
-import { sanitizeTaskMetadata, taskDataInputsSchema, validateRequest, parsePagination, cosScheduleTargetBodySchema, heldCheckoutRetireBodySchema, heldCheckoutReviewBodySchema, initializedCheckoutRetireBodySchema, initializedCheckoutTransactionSchema, initializedCheckoutRestoreSchema, initializedCheckoutBranchRetireSchema, initializedCheckoutMetadataRestoreSchema } from '../lib/validation.js';
+import { sanitizeTaskMetadata, taskDataInputsSchema, validateRequest, parsePagination, cosScheduleTargetBodySchema, heldCheckoutRetireBodySchema, heldCheckoutReviewBodySchema, initializedCheckoutRetireBodySchema, initializedCheckoutTransactionSchema, initializedCheckoutRestoreSchema, initializedCheckoutBranchRetireSchema, initializedCheckoutMetadataRestoreSchema, initializedCheckoutFinalizationSchema } from '../lib/validation.js';
import { promptSourceSchema, PROMPT_SOURCES, scheduleExecutionFieldsSchema } from '../lib/cosValidation.js';
import { EFFORT_LEVELS } from '../lib/providerModels.js';
import { INTERVAL_TYPES, decodeIntervalType, isCronExpression, isKnownIntervalType } from '../services/taskScheduleConstants.js';
@@ -356,6 +356,20 @@ router.post('/schedule/branch-reconcile/initialized-checkouts/restore-metadata',
res.status(result.ok ? 200 : 409).json(result);
}));
+router.post('/schedule/branch-reconcile/initialized-checkouts/review-restored-finalization', asyncHandler(async (req, res) => {
+ const input = validateRequest(initializedCheckoutRestoreSchema, req.body);
+ const { reviewInitializedCheckoutRestoredFinalization } = await import('../services/initializedCheckoutRecovery.js');
+ const result = await reviewInitializedCheckoutRestoredFinalization(input);
+ res.status(result.ok ? 200 : 409).json(result);
+}));
+
+router.post('/schedule/branch-reconcile/initialized-checkouts/finalize-restored', asyncHandler(async (req, res) => {
+ const input = validateRequest(initializedCheckoutFinalizationSchema, req.body);
+ const { finalizeInitializedCheckoutRestored } = await import('../services/initializedCheckoutRecovery.js');
+ const result = await finalizeInitializedCheckoutRestored(input);
+ res.status(result.ok ? 200 : 409).json(result);
+}));
+
router.post('/schedule/branch-reconcile/initialized-checkouts/verify-archive', asyncHandler(async (req, res) => {
const input = validateRequest(initializedCheckoutRestoreSchema, req.body);
const { verifyInitializedCheckoutArchive } = await import('../services/initializedCheckoutRecovery.js');
diff --git a/server/routes/cosScheduleRoutes.test.js b/server/routes/cosScheduleRoutes.test.js
index b4a02120b1..df9102ab99 100644
--- a/server/routes/cosScheduleRoutes.test.js
+++ b/server/routes/cosScheduleRoutes.test.js
@@ -10,7 +10,7 @@ vi.mock('../services/maintenanceRun.js', () => maintenance);
const recovery = vi.hoisted(() => ({ prepareInventoriedCheckoutRetirement: vi.fn(), retireInventoriedCheckout: vi.fn() }));
vi.mock('../services/heldCheckoutRecovery.js', () => recovery);
-const initialized = vi.hoisted(() => ({ reviewInitializedCheckout: vi.fn(), retireInitializedCheckout: vi.fn(), initializedCheckoutStatus: vi.fn(), restoreInitializedCheckout: vi.fn(), verifyInitializedCheckoutArchive: vi.fn(), reviewInitializedCheckoutBranch: vi.fn(), retireInitializedCheckoutBranch: vi.fn(), reviewInitializedCheckoutMetadataRestore: vi.fn(), restoreInitializedCheckoutMetadata: vi.fn() }));
+const initialized = vi.hoisted(() => ({ reviewInitializedCheckout: vi.fn(), retireInitializedCheckout: vi.fn(), initializedCheckoutStatus: vi.fn(), restoreInitializedCheckout: vi.fn(), verifyInitializedCheckoutArchive: vi.fn(), reviewInitializedCheckoutBranch: vi.fn(), retireInitializedCheckoutBranch: vi.fn(), reviewInitializedCheckoutMetadataRestore: vi.fn(), restoreInitializedCheckoutMetadata: vi.fn(), reviewInitializedCheckoutRestoredFinalization: vi.fn(), finalizeInitializedCheckoutRestored: vi.fn() }));
vi.mock('../services/initializedCheckoutRecovery.js', () => initialized);
vi.mock('../services/taskSchedule.js', () => ({
@@ -109,6 +109,22 @@ describe('CoS Schedule Routes', () => {
expect(initialized.restoreInitializedCheckoutMetadata).toHaveBeenCalledWith(approved);
});
+ it('requires a distinct finalization digest and never accepts caller-supplied metadata allowances', async () => {
+ const base = '/api/cos/schedule/branch-reconcile/initialized-checkouts';
+ const input = { appId: 'app', transactionId: '2f800be9-682c-4726-813d-8d9ea0b2c1dc', journalDigest: 'a'.repeat(64) };
+ initialized.reviewInitializedCheckoutRestoredFinalization.mockResolvedValue({ ok: true, review: { digest: 'b'.repeat(64) } });
+ expect((await request(app).post(`${base}/review-restored-finalization`).send(input)).status).toBe(200);
+ expect(initialized.reviewInitializedCheckoutRestoredFinalization).toHaveBeenCalledWith(input);
+ expect((await request(app).post(`${base}/finalize-restored`).send(input)).status).toBe(400);
+ const approved = { ...input, review: { digest: 'b'.repeat(64) } };
+ expect((await request(app).post(`${base}/finalize-restored`).send({ ...approved, ignoreMtime: true })).status).toBe(400);
+ expect((await request(app).post(`${base}/finalize-restored`).send({ ...approved, review: { ...approved.review, acceptChanges: true } })).status).toBe(400);
+ expect(initialized.finalizeInitializedCheckoutRestored).not.toHaveBeenCalled();
+ initialized.finalizeInitializedCheckoutRestored.mockResolvedValue({ ok: false, reason: 'restored-finalization-review-changed' });
+ expect((await request(app).post(`${base}/finalize-restored`).send(approved)).status).toBe(409);
+ expect(initialized.finalizeInitializedCheckoutRestored).toHaveBeenCalledWith(approved);
+ });
+
describe('GET /api/cos/schedule', () => {
it('surfaces unavailable schedule inputs as errors and recovers on the next read', async () => {
taskSchedule.getScheduleStatus
diff --git a/server/services/initializedCheckoutRecovery.js b/server/services/initializedCheckoutRecovery.js
index b4be7e5366..313b95ac0f 100644
--- a/server/services/initializedCheckoutRecovery.js
+++ b/server/services/initializedCheckoutRecovery.js
@@ -363,6 +363,10 @@ export function _createInitializedCheckoutRecovery(deps = {}) {
...(state.metadataRestoreReview ? { metadataRecovery: state.metadataRestoreReview.metadataRecovery,
metadataChangeCounts: state.metadataRestoreReview.changeCounts,
metadataRestored: state.phase === 'restored-with-metadata-transitions' } : {}),
+ ...(state.restoredFinalizationReview ? {
+ restoredFinalization: state.restoredFinalizationReview.restoredFinalization,
+ restoredFinalizationComplete: state.phase === 'restored-with-reviewed-finalization',
+ } : {}),
...(['branch-retired', 'retired'].includes(state.phase) ? { recoveryAction: 'retire-branch' } : {}) };
};
@@ -480,7 +484,7 @@ export function _createInitializedCheckoutRecovery(deps = {}) {
if (current.digest !== input.review?.digest) fail('metadata-recovery-review-changed');
const { directory } = bound;
let state = await appendStep(directory, bound.state, 'metadata-restore-approved',
- { metadataRestoreReview: current, reservation });
+ { metadataRestoreReview: current, metadataRestoreObservations: [], reservation });
const proof = { transactionDir: directory, manifestSha256: state.proof.manifestSha256,
metadataRecovery: current.metadataRecovery };
for (const part of ['administration', 'working']) {
@@ -502,7 +506,88 @@ export function _createInitializedCheckoutRecovery(deps = {}) {
return { ok: true, transactionId: state.id, phase: state.phase, restored: true, archivesRetained: true,
metadataTransitionsPreserved: true, metadataRecovery: current.metadataRecovery, archiveDir: directory };
});
- return { review, retire, status, restore, verifyArchive, reviewBranch, retireBranch, reviewMetadataRestore, restoreMetadata };
+ const restoredFinalizationInputs = ({ directory, state, ctx }) => {
+ const prior = state.metadataRestoreReview;
+ const observations = state.metadataRestoreObservations;
+ const unsigned = { ...prior };
+ delete unsigned.digest;
+ if (!state.proof?.manifestSha256 || state.branchDeleted || !prior
+ || prior.mode !== 'restore-metadata-only' || prior.digest !== hash(unsigned)
+ || prior.transactionId !== state.id || prior.repoPath !== ctx.repoPath || !sameRelease(prior.release, state.release)
+ || !Array.isArray(observations) || observations.length !== 2
+ || observations.some((row, index) => row?.part !== ['administration', 'working'][index]
+ || (row.proof == null ? index !== 0 || prior.initialPlacements?.administration !== 'original'
+ : !/^[a-f0-9]{64}$/.test(row.proof.sha256 || '')
+ || !/^[a-f0-9]{64}$/.test(row.proof.digest || '')))) fail('restored-finalization-evidence-missing');
+ return { transactionDir: directory, manifestSha256: state.proof.manifestSha256,
+ metadataRecovery: prior.metadataRecovery, postMoveObservations: observations.map(row => row.proof ?? null) };
+ };
+ // A separate endpoint can acknowledge a narrowly reviewed post-restoration
+ // transition. It never passes that permission to a move or ordinary verifier.
+ const finalizationReview = async (bound, reservation) => {
+ const { state, ctx } = bound;
+ if (!['metadata-restored-working', 'restored-finalization-approved'].includes(state.phase)) fail('restored-finalization-phase-not-ready');
+ const input = restoredFinalizationInputs(bound);
+ const policy = await metadataRestoreSafety(bound);
+ const proof = await native({ command: 'review-restored-finalization', ...input });
+ if (proof.placements?.working !== 'original' || proof.placements?.administration !== 'original') fail('restored-finalization-originals-not-restored');
+ const evidence = { version: 1, mode: 'finalize-already-restored', transactionId: state.id,
+ repoPath: ctx.repoPath, release: state.release, journalDigest: hash(state), phase: state.phase, policy,
+ reservation, priorMetadataRestoreReview: state.metadataRestoreReview,
+ postMoveObservations: state.metadataRestoreObservations, restoredFinalization: proof.restoredFinalization,
+ placements: proof.placements, changeCounts: proof.changeCounts, changedPaths: proof.changedPaths };
+ return { digest: hash(evidence), ...evidence };
+ };
+ const withRestoredFinalization = (input, work, allowReleased = false) => fenced(async () => {
+ const directory = location(input.transactionId);
+ const executor = await native({ command: 'lock', transactionDir: directory }, { keepOpen: true });
+ try {
+ const bound = await loadBoundTransaction(input);
+ const gate = await admission();
+ const reservation = await gate.readCheckoutReservation(bound.ctx.repoPath, bound.state.id).catch(error => {
+ if (error.code === 'ENOENT' && allowReleased && bound.state.phase === 'restored-with-reviewed-finalization') return null;
+ throw error;
+ });
+ if (reservation && JSON.stringify(reservation) !== JSON.stringify(bound.state.reservation)) fail('restored-finalization-reservation-changed');
+ const run = async () => {
+ executor.assertHeld();
+ if (hash(await readJournal(directory)) !== hash(bound.state)) fail('retirement-journal-changed');
+ return work(bound, { executor, gate, reservation });
+ };
+ return reservation ? await gate.withCheckoutReservation(reservation, run)
+ : await gate.withCheckoutPublication(bound.ctx.repoPath, run);
+ } finally { await executor.release(); }
+ }).catch(error => ({ ok: false, reason: error.message, transactionId: input.transactionId, recoveryRequired: true }));
+ const reviewRestoredFinalization = input => withRestoredFinalization(input,
+ async (bound, { reservation }) => ({ ok: true, review: await finalizationReview(bound, reservation) }));
+ const finalizeRestored = input => withRestoredFinalization(input, async (bound, { executor, gate, reservation }) => {
+ const { directory } = bound;
+ let state = bound.state;
+ const replay = state.phase === 'restored-with-reviewed-finalization';
+ const current = replay ? state.restoredFinalizationReview : await finalizationReview(bound, reservation);
+ const unsigned = { ...current };
+ delete unsigned.digest;
+ if (!current || current.mode !== 'finalize-already-restored' || current.digest !== hash(unsigned)
+ || current.digest !== input.review?.digest) fail('restored-finalization-review-changed');
+ if (!replay) state = await appendStep(directory, state, 'restored-finalization-approved', { restoredFinalizationReview: current });
+ const policy = await metadataRestoreSafety({ ...bound, state });
+ if (JSON.stringify(policy) !== JSON.stringify(current.policy)) fail('retirement-evidence-changed');
+ executor.assertHeld();
+ const proof = await native({ command: 'verify-restored-finalization', ...restoredFinalizationInputs({ ...bound, state }),
+ restoredFinalization: current.restoredFinalization });
+ if (proof.verified !== true || proof.alreadyRestored !== true || proof.restoredFinalizationAccepted !== true
+ || ['working', 'administration'].some(part => proof.placements?.[part]?.state !== 'original')) fail('restored-finalization-proof-refused');
+ const finalPolicy = await metadataRestoreSafety({ ...bound, state });
+ if (JSON.stringify(finalPolicy) !== JSON.stringify(current.policy)) fail('retirement-evidence-changed');
+ executor.assertHeld();
+ if (!replay) state = await appendStep(directory, state, 'restored-with-reviewed-finalization');
+ if (reservation) await gate.releaseCheckoutReservation(reservation);
+ return { ok: true, transactionId: state.id, phase: state.phase, restored: true, alreadyRestored: true,
+ archivesRetained: true, metadataTransitionsPreserved: true, restoredFinalization: current.restoredFinalization,
+ archiveDir: directory };
+ }, true);
+ return { review, retire, status, restore, verifyArchive, reviewBranch, retireBranch, reviewMetadataRestore, restoreMetadata,
+ reviewRestoredFinalization, finalizeRestored };
}
const recovery = _createInitializedCheckoutRecovery();
@@ -517,3 +602,5 @@ export const reviewInitializedCheckoutBranch = recovery.reviewBranch;
export const retireInitializedCheckoutBranch = recovery.retireBranch;
export const reviewInitializedCheckoutMetadataRestore = recovery.reviewMetadataRestore;
export const restoreInitializedCheckoutMetadata = recovery.restoreMetadata;
+export const reviewInitializedCheckoutRestoredFinalization = recovery.reviewRestoredFinalization;
+export const finalizeInitializedCheckoutRestored = recovery.finalizeRestored;
diff --git a/server/services/initializedCheckoutRecovery.test.js b/server/services/initializedCheckoutRecovery.test.js
index 17cfe6c44f..bcb2464940 100644
--- a/server/services/initializedCheckoutRecovery.test.js
+++ b/server/services/initializedCheckoutRecovery.test.js
@@ -69,7 +69,7 @@ beforeEach(async () => {
const facts = { prUrl, prHead: release.head, defaultHead: 'b'.repeat(40) };
const snapshot = { fingerprint: 'c'.repeat(64), administrationFingerprint: 'd'.repeat(64), identity: { working: 1, administration: 2, common: 3 } };
fixture = { cut: null, facts, snapshot, headExists: true, placement: { working: 'original', administration: 'original' }, failPart: null,
- metadataToken: 'f'.repeat(64) };
+ metadataToken: 'f'.repeat(64), finalizationToken: '7'.repeat(64) };
const admission = {
withCheckoutPublication: async (_repo, work) => { if (fixture.cut) throw new Error('checkout-retirement-reserved'); return work(); },
reserveCheckoutRetirement: vi.fn(async (_repo, id) => {
@@ -96,9 +96,23 @@ beforeEach(async () => {
metadataRecovery: { version: 1, digest: fixture.metadataToken, evidenceFile: 'private-proof.json', evidenceSha256: fixture.metadataToken },
initialPlacements: { ...fixture.placement }, changeCounts: { residualCompressionRemoved: 3, rootProvenanceAdded: 1 }, changedPaths: 4,
};
+ if (input.command === 'review-restored-finalization') {
+ if (fixture.failArchive) throw new Error('archive-changed');
+ return { restoredFinalization: { version: 1, evidenceFile: 'finalization.json',
+ evidenceSha256: fixture.finalizationToken, digest: fixture.finalizationToken },
+ placements: { ...fixture.placement }, changeCounts: { directoryMtimeChanged: 2, residualCompressionReappeared: 1 }, changedPaths: 3 };
+ }
+ if (input.command === 'verify-restored-finalization') {
+ if (fixture.failFinalization || input.restoredFinalization?.digest !== fixture.finalizationToken) throw new Error('finalization-evidence-changed');
+ return { verified: true, alreadyRestored: true, restoredFinalizationAccepted: true,
+ placements: Object.fromEntries(Object.entries(fixture.placement).map(([part, state]) => [part, { state }])) };
+ }
if (['verify', 'move', 'status'].includes(input.command) && input.manifestSha256 !== 'e'.repeat(64)) throw new Error('archive-manifest-proof-changed');
+ if (fixture.delayedRestoreDrift && input.command === 'verify' && input.mode === 'restore'
+ && Object.values(fixture.placement).every(value => value === 'original')) throw new Error('source-content-or-identity-changed:working');
if (fixture.metadataDrift && ['verify', 'move'].includes(input.command) && input.mode !== 'standalone'
&& input.metadataRecovery?.digest !== fixture.metadataToken) throw new Error('source-content-or-identity-changed:working');
+ const alreadyRestored = input.command === 'move' && input.direction === 'restore' && fixture.placement[input.part] === 'original';
if (input.command === 'move') {
if (fixture.failPart === input.part && input.direction === 'quarantine') throw new Error('move-refused');
if (fixture.failRestorePart === input.part && input.direction === 'restore') throw new Error('restore-interrupted');
@@ -106,7 +120,9 @@ beforeEach(async () => {
}
if (fixture.failArchive && input.command === 'verify') throw new Error('archive-changed');
return { ok: true, placement: fixture.placement, fingerprint: fixture.snapshot.fingerprint,
- ...(input.metadataRecovery ? { postMoveObservation: { file: 'post-move.json', sha256: fixture.metadataToken } } : {}),
+ ...(input.metadataRecovery && !alreadyRestored ? {
+ postMoveObservation: { file: `${input.part}-post-move.json`, sha256: fixture.metadataToken, digest: fixture.metadataToken },
+ } : {}),
placements: Object.fromEntries(Object.entries(fixture.placement).map(([part, state]) => [part, { state: state === 'quarantined' ? 'quarantine' : state }])) };
});
const deps = { root: () => root, fenced: work => work(), admission, native,
@@ -328,6 +344,145 @@ describe('initialized checkout transaction', () => {
.toMatchObject({ ok: true, restored: true });
expect(fixture.cut).toBeNull();
});
+ const restoredWithDelayedDrift = async () => {
+ const input = await interruptedMetadata();
+ const prepared = await fixture.service.reviewMetadataRestore(input);
+ fixture.delayedRestoreDrift = true;
+ expect(await fixture.service.restoreMetadata({ ...input, review: { digest: prepared.review.digest } }))
+ .toMatchObject({ ok: false, reason: 'source-content-or-identity-changed:working' });
+ const status = await fixture.service.status(input);
+ expect(status.phase).toBe('metadata-restored-working');
+ expect(fixture.placement).toEqual({ working: 'original', administration: 'original' });
+ return { ...input, journalDigest: status.journalDigest };
+ };
+ it('finalizes a retried restore using only its current observations while retaining earlier immutable evidence', async () => {
+ const original = fixture.deps.native.getMockImplementation();
+ fixture.deps.native.mockImplementation(async input => {
+ const result = await original(input);
+ if (input.command === 'move' && input.direction === 'quarantine' && input.part === 'administration') {
+ fixture.metadataDrift = true;
+ }
+ return result;
+ });
+ const retired = await fixture.service.retire(await reviewed());
+ expect(retired).toMatchObject({ ok: false, reason: 'source-content-or-identity-changed:working' });
+ expect(fixture.placement).toEqual({ working: 'quarantined', administration: 'quarantined' });
+ const status = await fixture.service.status({ appId: 'app', transactionId: retired.transactionId });
+ const input = { appId: 'app', transactionId: retired.transactionId, journalDigest: status.journalDigest };
+ const firstReview = await fixture.service.reviewMetadataRestore(input);
+ fixture.failRestorePart = 'working';
+ expect(await fixture.service.restoreMetadata({ ...input, review: { digest: firstReview.review.digest } }))
+ .toMatchObject({ ok: false, reason: 'restore-interrupted' });
+ expect(fixture.placement).toEqual({ working: 'quarantined', administration: 'original' });
+ const directory = join(root, input.transactionId);
+ const names = (await readdir(directory)).filter(name => /^\d{6}\.json$/.test(name)).sort();
+ const previousFile = join(directory, names.at(-1));
+ const previousBytes = await readFile(previousFile, 'utf8');
+ expect(JSON.parse(previousBytes).metadataRestoreObservations)
+ .toEqual([{ part: 'administration', proof: expect.objectContaining({ file: 'administration-post-move.json' }) }]);
+ const retryStatus = await fixture.service.status(input);
+ const retry = { ...input, journalDigest: retryStatus.journalDigest };
+ const nextReview = await fixture.service.reviewMetadataRestore(retry);
+ fixture.failRestorePart = null;
+ fixture.delayedRestoreDrift = true;
+ expect(await fixture.service.restoreMetadata({ ...retry, review: { digest: nextReview.review.digest } }))
+ .toMatchObject({ ok: false, reason: 'source-content-or-identity-changed:working' });
+ const finalStatus = await fixture.service.status(input);
+ const finalInput = { ...input, journalDigest: finalStatus.journalDigest };
+ const finalReview = await fixture.service.reviewRestoredFinalization(finalInput);
+ expect(finalReview).toMatchObject({ ok: true, review: { postMoveObservations: [
+ { part: 'administration' }, { part: 'working', proof: { file: 'working-post-move.json' } },
+ ] } });
+ expect(finalReview.review.postMoveObservations).toHaveLength(2);
+ expect(await fixture.service.finalizeRestored({ ...finalInput, review: { digest: finalReview.review.digest } }))
+ .toMatchObject({ ok: true, restored: true });
+ expect(await readFile(previousFile, 'utf8')).toBe(previousBytes);
+ expect(fixture.cut).toBeNull();
+ expect(fixture.deps.deleteRef).not.toHaveBeenCalled();
+ });
+ it('finalizes already-restored originals only with a new review bound to the actual no-op and move evidence', async () => {
+ const input = await restoredWithDelayedDrift();
+ const before = fixture.deps.native.mock.calls.filter(([row]) => row.command === 'move').length;
+ const prepared = await fixture.service.reviewRestoredFinalization(input);
+ expect(prepared).toMatchObject({ ok: true, review: { mode: 'finalize-already-restored',
+ postMoveObservations: [{ part: 'administration' }, { part: 'working', proof: { digest: fixture.metadataToken } }] } });
+ const result = await fixture.service.finalizeRestored({ ...input, review: { digest: prepared.review.digest } });
+ expect(result).toMatchObject({ ok: true, alreadyRestored: true, phase: 'restored-with-reviewed-finalization', archivesRetained: true });
+ expect(fixture.cut).toBeNull();
+ expect(fixture.headExists).toBe(true);
+ expect(fixture.deps.deleteRef).not.toHaveBeenCalled();
+ expect(fixture.deps.native.mock.calls.filter(([row]) => row.command === 'move')).toHaveLength(before);
+ expect(fixture.deps.native).toHaveBeenCalledWith(expect.objectContaining({
+ command: 'verify-restored-finalization', postMoveObservations: [null, expect.objectContaining({ file: 'working-post-move.json' })],
+ }));
+ expect(await readFile(join(root, input.transactionId, 'manifest.json'), 'utf8')).toBe('{}');
+ expect(await fixture.service.status(input)).toMatchObject({ restoredFinalizationComplete: true });
+ });
+ it.each(['delta', 'owner', 'ref', 'holder', 'cut', 'archive'])('retains the cut when finalization %s evidence changes', async change => {
+ const input = await restoredWithDelayedDrift();
+ const prepared = await fixture.service.reviewRestoredFinalization(input);
+ if (change === 'delta') fixture.finalizationToken = '8'.repeat(64);
+ if (change === 'owner') fixture.deps.ownership.mockResolvedValue({ ok: false, reason: 'active-owner' });
+ if (change === 'ref') fixture.headExists = false;
+ if (change === 'holder') fixture.newHolder = true;
+ if (change === 'cut') fixture.cut.owner.id = 'different-owner';
+ if (change === 'archive') fixture.failArchive = true;
+ const releases = fixture.deps.admission.releaseCheckoutReservation.mock.calls.length;
+ expect(await fixture.service.finalizeRestored({ ...input, review: { digest: prepared.review.digest } })).toMatchObject({ ok: false, recoveryRequired: true });
+ expect(fixture.cut).not.toBeNull();
+ expect(fixture.deps.admission.releaseCheckoutReservation).toHaveBeenCalledTimes(releases);
+ expect(fixture.deps.deleteRef).not.toHaveBeenCalled();
+ });
+ it('requires a new finalization approval after a durable approved phase is interrupted', async () => {
+ const input = await restoredWithDelayedDrift();
+ const prepared = await fixture.service.reviewRestoredFinalization(input);
+ fixture.failFinalization = true;
+ expect(await fixture.service.finalizeRestored({ ...input, review: { digest: prepared.review.digest } }))
+ .toMatchObject({ ok: false, reason: 'finalization-evidence-changed' });
+ const restarted = _createInitializedCheckoutRecovery(fixture.deps);
+ const status = await restarted.status(input);
+ expect(status.phase).toBe('restored-finalization-approved');
+ expect(await restarted.finalizeRestored({ ...input, review: { digest: prepared.review.digest } }))
+ .toMatchObject({ ok: false, reason: 'retirement-journal-changed' });
+ const fresh = { ...input, journalDigest: status.journalDigest };
+ expect(await restarted.finalizeRestored({ ...fresh, review: { digest: prepared.review.digest } }))
+ .toMatchObject({ ok: false, reason: 'restored-finalization-review-changed' });
+ fixture.failFinalization = false;
+ const next = await restarted.reviewRestoredFinalization(fresh);
+ expect(await restarted.finalizeRestored({ ...fresh, review: { digest: next.review.digest } })).toMatchObject({ ok: true });
+ });
+ it.each([false, true])('replays only final proof and release after uncertain release, cutAlreadyReleased=%s', async released => {
+ const input = await restoredWithDelayedDrift();
+ const prepared = await fixture.service.reviewRestoredFinalization(input);
+ fixture.deps.admission.releaseCheckoutReservation.mockImplementationOnce(async () => {
+ if (released) fixture.cut = null;
+ throw new Error('release-acknowledgement-lost');
+ });
+ expect(await fixture.service.finalizeRestored({ ...input, review: { digest: prepared.review.digest } }))
+ .toMatchObject({ ok: false, reason: 'release-acknowledgement-lost' });
+ const restarted = _createInitializedCheckoutRecovery(fixture.deps);
+ const status = await restarted.status(input);
+ expect(status.phase).toBe('restored-with-reviewed-finalization');
+ const commands = fixture.deps.native.mock.calls.length;
+ expect(await restarted.finalizeRestored({ ...input, journalDigest: status.journalDigest, review: { digest: prepared.review.digest } }))
+ .toMatchObject({ ok: true, alreadyRestored: true });
+ expect(fixture.deps.native.mock.calls.slice(commands).map(([row]) => row.command)).toEqual(['lock', 'verify-restored-finalization']);
+ expect(fixture.cut).toBeNull();
+ expect(fixture.deps.deleteRef).not.toHaveBeenCalled();
+ });
+ it('rechecks ownership after final native verification and retains the reservation on a new owner', async () => {
+ const input = await restoredWithDelayedDrift();
+ const prepared = await fixture.service.reviewRestoredFinalization(input);
+ const original = fixture.deps.native.getMockImplementation();
+ fixture.deps.native.mockImplementation(async value => {
+ const result = await original(value);
+ if (value.command === 'verify-restored-finalization') fixture.deps.ownership.mockResolvedValue({ ok: false, reason: 'active-owner' });
+ return result;
+ });
+ expect(await fixture.service.finalizeRestored({ ...input, review: { digest: prepared.review.digest } }))
+ .toMatchObject({ ok: false, reason: 'active-owner' });
+ expect(fixture.cut).not.toBeNull();
+ });
it('exposes only source-verified cancellation after durable preservation loses its proof journal', async () => {
fixture.failProofJournal = true;
const result = await fixture.service.retire(await reviewed());