chati-dev 4.5.28 → 4.5.29

package/src/terminal/rail-worktree-restoration.js

@@ -0,0 +1,485 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { closeSync, constants, fchmodSync, fstatSync, fsyncSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, relative, resolve } from 'node:path';
+import { canonicalSerialize, canonicalize, sha256, lstatAtSync, mkdirAtSync, openAtSync,
+  readDirectorySync, readlinkAtSync, renameNoReplaceAtSync, symlinkAtSync } from '@chati/core';
+import { tryExclusiveFileLockSync, unlinkAtSync } from '@chati/core';
+import { persistImmutableInstallationFile, readSafeInstallationStorageFile } from '../installer-v2/catalog-client.js';
+import { signHostAuthorityPayload, verifyHostAuthorityPayload } from '../installer-v2/installation-authority.js';
+import { readRailGitState as git, railRepositoryIdentity, railRepositoryStorageIdentity, captureRailExecutionWorktree } from './rail-execution-worktree.js';
+import { readRailWorktreeCheckpoint, assertRailCheckpointSourceUnchanged, openCheckpointDirectory,
+  readCheckpointFileAt, readCheckpointConfiguration, checkpointPathComponents } from './rail-worktree-checkpoint.js';
+
+const DOMAIN = 'chati.rail-worktree-restoration.v1';
+const MAX_BYTES = 128 * 1024 * 1024;
+const MAX_PLAN_BYTES = 16 * 1024 * 1024;
+const O_DIRECTORY = constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW;
+const ABSENT = Object.freeze({ type: 'absent' });
+const hash = (bytes) => createHash('sha256').update(bytes).digest('hex');
+const ref = (bytes) => ({ sha256: hash(bytes), size: bytes.length });
+const hooks = Symbol.for('chati.restoration.security-test-hooks');
+const hook = (name, detail) => globalThis[hooks]?.[name]?.(detail);
+function fail(code, message, details) { throw Object.assign(new Error(message), { code, details }); }
+function decode(bytes) { return new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes); }
+function excluded(path) { return ['.chati', '.chati.dev'].includes(path.split('/')[0]); }
+function signed(payload) {
+  const result = signHostAuthorityPayload(payload, { domain: DOMAIN });
+  return canonicalize({ ...payload, authority_id: result.authority_id, authority_signature: result.signature });
+}
+function verify(value, expected) {
+  const { authority_id, authority_signature, ...payload } = value ?? {};
+  if (!verifyHostAuthorityPayload(payload, { domain: DOMAIN, authorityId: authority_id, signature: authority_signature })
+    || Object.entries(expected).some(([key, item]) => sha256(payload[key] ?? null) !== sha256(item))) {
+    fail('RESTORATION_AUTHORITY_MISMATCH', 'restoration evidence must authenticate this exact checkpoint and step');
+  }
+  return payload;
+}
+function baseDirectory(projectDir, checkpoint) {
+  return join(resolve(projectDir), '.chati/v2/rail/worktree-checkpoints', checkpoint.receipt.checkpoint_id, 'restoration');
+}
+function comparable(state) {
+  const value = { ...state }; delete value.complete;
+  return value;
+}
+const same = (left, right) => sha256(comparable(left)) === sha256(comparable(right));
+function entryKey(scope, path) { checkpointPathComponents(path); return `${scope}:${path}`; }
+function entryPath(roots, entry) {
+  if (!Object.hasOwn(roots, entry.scope)) fail('RESTORATION_PATH_INVALID', 'unknown restoration storage scope');
+  checkpointPathComponents(entry.path);
+  if (entry.scope === 'worktree' && excluded(entry.path)) fail('RESTORATION_PATH_INVALID', 'restoration cannot modify the CHATI control plane');
+  return join(roots[entry.scope], entry.path);
+}
+function openParent(roots, entry, { allowMissing = false } = {}) {
+  entryPath(roots, entry);
+  let fd = openCheckpointDirectory(roots[entry.scope]);
+  const parts = checkpointPathComponents(entry.path); const name = parts.pop();
+  try {
+    for (const part of parts) {
+      let next;
+      try { next = openAtSync(fd, part, O_DIRECTORY); }
+      catch (error) {
+        if (allowMissing && ['ENOENT', 'ENOTDIR', 'ELOOP'].includes(error.code)) { closeSync(fd); return null; }
+        throw error;
+      }
+      closeSync(fd); fd = next;
+    }
+    return { fd, name };
+  } catch (error) { closeSync(fd); throw error; }
+}
+function readEntryAt(fd, name) {
+  let stat;
+  try { stat = lstatAtSync(fd, name); }
+  catch (error) { if (error.code === 'ENOENT') return ABSENT; throw error; }
+  if (stat.isSymbolicLink()) return { type: 'symlink', blob: ref(readlinkAtSync(fd, name)) };
+  if (stat.isDirectory()) return { type: 'directory', mode: stat.mode & 0o777 };
+  if (stat.isFile()) {
+    const saved = readCheckpointFileAt(fd, name);
+    return { type: 'file', mode: saved.mode, blob: ref(saved.bytes) };
+  }
+  return fail('RESTORATION_UNSAFE_FILE', 'special entries cannot be overwritten during restoration');
+}
+function readEntry(roots, entry) {
+  const parent = openParent(roots, entry, { allowMissing: true });
+  if (!parent) return ABSENT;
+  try { return readEntryAt(parent.fd, parent.name); } finally { closeSync(parent.fd); }
+}
+function persistJson(path, value, maxBytes = MAX_PLAN_BYTES) {
+  persistImmutableInstallationFile(path, canonicalSerialize(value), { maxBytes });
+}
+function privateDirectory(path) {
+  // Reuse the protected immutable writer to create/validate the ancestor chain.
+  persistImmutableInstallationFile(join(path, '.storage'), 'restoration-v1');
+  return openCheckpointDirectory(path);
+}
+
+function checkpointBase(checkpoint, storeBlob) {
+  // Every Git write is confined to this owned disposable repository. No Git
+  // mutating subprocess operates on the source, even if its parent is killed.
+  const scratch = mkdtempSync(join(tmpdir(), 'chati-restoration-base-'));
+  try {
+    git(scratch, ['init', '--bare', '-q', `--object-format=${checkpoint.manifest.state.git.object_format}`]);
+    git(scratch, ['index-pack', '--stdin'], { encoding: null, input: checkpoint.readBlob(checkpoint.manifest.pack) });
+    const base = checkpoint.manifest.binding.base_commit_ref;
+    git(scratch, ['-c', 'core.splitIndex=false', '-c', 'index.version=2', 'read-tree', base]);
+    const index = storeBlob(readFileSync(join(scratch, 'index')));
+    const bytes = git(scratch, ['ls-tree', '-r', '-z', '--full-tree', base], { encoding: null });
+    if (bytes.length && bytes.at(-1) !== 0) fail('RESTORATION_BASE_INVALID', 'base inventory is incomplete');
+    const files = [];
+    for (const line of decode(bytes).split('\0').filter(Boolean)) {
+      const match = /^(100644|100755|120000) blob ([a-f0-9]{40,64})\t([\s\S]+)$/.exec(line);
+      if (!match) fail('RESTORATION_BASE_UNSUPPORTED', 'base must contain ordinary files and symlinks only');
+      if (excluded(match[3])) continue;
+      checkpointPathComponents(match[3]);
+      const blob = storeBlob(git(scratch, ['cat-file', 'blob', match[2]], { encoding: null }));
+      files.push({ path: match[3], state: match[1] === '120000' ? { type: 'symlink', blob }
+        : { type: 'file', mode: match[1] === '100755' ? 0o755 : 0o644, blob } });
+    }
+    return { files, index };
+  } finally { rmSync(scratch, { recursive: true, force: true }); }
+}
+
+function createPlan(projectDir, checkpoint, directory) {
+  const repository = assertRailCheckpointSourceUnchanged(projectDir, checkpoint);
+  const roots = { worktree: resolve(projectDir), git: repository.git_dir.path, common: repository.common_git_dir.path };
+  const rootDevice = repository.root.dev;
+  const entries = new Map(); const desired = new Map();
+  let blobBytes = 0; const blobs = new Map();
+  const storeBlob = (bytes) => {
+    const value = ref(bytes);
+    if (!blobs.has(value.sha256)) {
+      blobBytes += bytes.length;
+      if (blobBytes > MAX_BYTES) fail('RESTORATION_SIZE_LIMIT', 'restoration base exceeds 128 MiB');
+      persistImmutableInstallationFile(join(directory, 'blobs', value.sha256), bytes, { maxBytes: MAX_BYTES });
+      blobs.set(value.sha256, value);
+    }
+    return value;
+  };
+  for (const file of checkpoint.manifest.state.files) {
+    const { path, ...before } = file;
+    entries.set(entryKey('worktree', path), { scope: 'worktree', path, before });
+  }
+  const add = (scope, path, after) => {
+    const key = entryKey(scope, path);
+    if (!entries.has(key)) entries.set(key, { scope, path, before: readEntry(roots, { scope, path }) });
+    desired.set(key, after);
+    for (let parent = dirname(path); parent !== '.'; parent = dirname(parent)) {
+      const parentKey = entryKey(scope, parent);
+      if (!entries.has(parentKey)) entries.set(parentKey, { scope, path: parent, before: readEntry(roots, { scope, path: parent }) });
+      const original = entries.get(parentKey).before;
+      desired.set(parentKey, original.type === 'directory' ? original : { type: 'directory', mode: 0o755 });
+    }
+  };
+  const base = checkpointBase(checkpoint, storeBlob);
+  for (const file of base.files) add('worktree', file.path, file.state);
+  add('git', 'index', { type: 'file', mode: 0o600, blob: base.index });
+  const saved = checkpoint.manifest.state.git;
+  // Preserve symbolic HEAD spelling; only its exact ref value returns to base.
+  let refScope = 'git'; let refPath = 'HEAD';
+  if (saved.head_ref) {
+    const absolute = resolve(projectDir, git(projectDir, ['rev-parse', '--git-path', saved.head_ref]).trim());
+    refScope = absolute.startsWith(roots.git + '/') ? 'git' : 'common';
+    refPath = relative(roots[refScope], absolute).split('\\').join('/');
+    if (!refPath.startsWith('refs/')) fail('RESTORATION_REF_STORAGE_UNSUPPORTED', 'restoration requires descriptor-relative files ref storage');
+    add('git', 'HEAD', { type: 'file', mode: readEntry(roots, { scope: 'git', path: 'HEAD' }).mode, blob: saved.head_file });
+  }
+  add(refScope, refPath, { type: 'file', mode: 0o644, blob: storeBlob(Buffer.from(checkpoint.manifest.binding.base_commit_ref + '\n')) });
+  // Packed refs are a guard, never rewritten. This catches movement of a ref
+  // that had no loose file when the restoration intent was committed.
+  const packed = { scope: 'common', path: 'packed-refs' };
+  const guards = [{ ...packed, before: readEntry(roots, packed) }];
+  const lockPaths = new Map([['git', 'index.lock'], ['git', 'HEAD.lock'], [refScope, refPath + '.lock'], ['common', 'packed-refs.lock']]
+    .map(([scope, path]) => [join(roots[scope], path), { scope, path }]));
+  for (const lock of lockPaths.values()) {
+    if (readEntry(roots, lock).type !== 'absent') fail('RESTORATION_GIT_LOCK_PRESENT', 'an unowned Git transaction lock must not be removed or bypassed', { path: entryPath(roots, lock) });
+  }
+  const operations = [];
+  const sorted = [...entries.entries()].sort((a, b) => a[1].path.localeCompare(b[1].path, 'en'));
+  const willRemove = [];
+  for (const [key, entry] of sorted) {
+    let after = desired.get(key) ?? ABSENT;
+    if (after.type === 'absent' && entry.before.type === 'directory' && entry.before.complete !== true) after = entry.before;
+    desired.set(key, after);
+    if (entry.before.type !== 'absent' && !same(entry.before, after)) willRemove.push({ ...entry, after: ABSENT, kind: 'retire' });
+  }
+  // Children leave first, so retiring a directory can only move an empty one.
+  willRemove.sort((a, b) => b.path.split('/').length - a.path.split('/').length || a.path.localeCompare(b.path, 'en'));
+  const gitRemovals = willRemove.filter((entry) => entry.scope !== 'worktree');
+  operations.push(...willRemove.filter((entry) => entry.scope === 'worktree'));
+  const additions = sorted.filter(([key, entry]) => desired.get(key).type !== 'absent' && !same(entry.before, desired.get(key)))
+    .map(([key, entry]) => ({ scope: entry.scope, path: entry.path, before: ABSENT, after: desired.get(key), kind: 'publish' }));
+  additions.sort((a, b) => a.path.split('/').length - b.path.split('/').length || a.path.localeCompare(b.path, 'en'));
+  operations.push(...additions.filter((entry) => entry.scope === 'worktree'));
+  // Index first, then ref/HEAD. All source mutations are synchronous syscalls,
+  // not detached Git children; the caller retains journal exclusion throughout.
+  for (const path of ['index', null]) {
+    operations.push(...gitRemovals.filter((entry) => path === 'index' ? entry.path === path : entry.path !== 'index'));
+    operations.push(...additions.filter((entry) => entry.scope !== 'worktree' && (path === 'index' ? entry.path === path : entry.path !== 'index')));
+  }
+  if (entries.size > 20_000 || operations.length > 40_000) fail('RESTORATION_ENTRY_LIMIT', 'restoration exceeds its bounded path inventory');
+  for (const entry of entries.values()) {
+    const parent = openParent(roots, entry, { allowMissing: true });
+    if (parent) {
+      try {
+        if (fstatSync(parent.fd).dev !== rootDevice) fail('RESTORATION_CROSS_DEVICE_UNSUPPORTED', 'restoration requires one filesystem for atomic preservation');
+        if (readEntryAt(parent.fd, parent.name).type !== 'absent' && lstatAtSync(parent.fd, parent.name).dev !== rootDevice) {
+          fail('RESTORATION_CROSS_DEVICE_UNSUPPORTED', 'restoration cannot relocate a mounted entry');
+        }
+      }
+      finally { closeSync(parent.fd); }
+    }
+  }
+  const storage = openCheckpointDirectory(directory);
+  try { if (fstatSync(storage).dev !== rootDevice) fail('RESTORATION_CROSS_DEVICE_UNSUPPORTED', 'checkpoint storage must share the worktree filesystem'); }
+  finally { closeSync(storage); }
+  assertRailCheckpointSourceUnchanged(projectDir, checkpoint);
+  return canonicalize({ schema_version: 1, checkpoint_receipt_digest: sha256(checkpoint.receipt),
+    binding: checkpoint.manifest.binding, roots, configuration_digest: saved.configuration_digest,
+    entries: [...entries.values()], guards, operations, blobs: [...blobs.values()],
+    locks: [...lockPaths.values()].map((lock) => ({ ...lock, nonce: randomUUID() })) });
+}
+
+function loadIntent(projectDir, checkpoint, directory) {
+  const stored = readSafeInstallationStorageFile(join(directory, 'intent.json'), { allowMissing: true, maxBytes: MAX_PLAN_BYTES });
+  if (stored) {
+    const intent = JSON.parse(stored.content);
+    verify(intent, { purpose: 'rail_restoration_intent', checkpoint_receipt_digest: sha256(checkpoint.receipt) });
+    return intent;
+  }
+  const plan = createPlan(projectDir, checkpoint, directory);
+  const intent = signed({ purpose: 'rail_restoration_intent', checkpoint_receipt_digest: sha256(checkpoint.receipt), plan });
+  persistJson(join(directory, 'intent.json'), intent);
+  return intent;
+}
+function expectedEntries(plan, cursor) {
+  const values = new Map(plan.entries.map((entry) => [entryKey(entry.scope, entry.path), { ...entry, state: entry.before }]));
+  for (const operation of plan.operations.slice(0, cursor)) values.get(entryKey(operation.scope, operation.path)).state = operation.after;
+  return [...values.values()];
+}
+function assertState(plan, cursor) {
+  const physical = railRepositoryStorageIdentity(plan.roots.worktree, { gitDir: plan.roots.git, commonGitDir: plan.roots.common });
+  if (sha256(physical) !== plan.binding.repository_identity_digest) fail('RESTORATION_SOURCE_CHANGED', 'repository storage identity changed');
+  const entries = expectedEntries(plan, cursor);
+  for (const entry of [...entries, ...plan.guards.map((guard) => ({ ...guard, state: guard.before }))]) {
+    if (!same(readEntry(plan.roots, entry), entry.state)) fail('RESTORATION_SOURCE_CHANGED', 'path differs from the durable restoration position', { scope: entry.scope, path: entry.path });
+    if (entry.state.type === 'directory' && entry.state.complete) {
+      const fd = openCheckpointDirectory(entryPath(plan.roots, entry));
+      try {
+        const actual = readDirectorySync(fd, { encoding: 'buffer' }).map(decode).sort();
+        const expected = entries.filter((child) => child.scope === entry.scope && dirname(child.path) === entry.path && child.state.type !== 'absent').map((child) => child.path.slice(entry.path.length + 1)).sort();
+        if (sha256(actual) !== sha256(expected)) fail('RESTORATION_SOURCE_CHANGED', 'complete directory has uninventoried children', { path: entry.path });
+      } finally { closeSync(fd); }
+    }
+  }
+  const head = entries.find((entry) => entry.scope === 'git' && entry.path === 'HEAD');
+  if (head?.state.type === 'absent') {
+    const next = plan.operations[cursor];
+    if (next?.scope !== 'git' || next.path !== 'HEAD' || next.kind !== 'publish') {
+      fail('RESTORATION_SOURCE_CHANGED', 'HEAD absence is not the authenticated retirement/publication interval');
+    }
+    // Every physical entry above matched the signed prefix. Only the following
+    // HEAD publication can proceed; Git/config/inventory are checked again as
+    // soon as the repository can be discovered, before any final receipt.
+    return;
+  }
+  if (sha256(railRepositoryIdentity(plan.roots.worktree)) !== plan.binding.repository_identity_digest
+    || readCheckpointConfiguration(plan.roots.worktree) !== plan.configuration_digest) fail('RESTORATION_SOURCE_CHANGED', 'repository or effective configuration changed');
+  const known = new Set(entries.filter((entry) => entry.scope === 'worktree').map((entry) => entry.path));
+  const untracked = decode(git(plan.roots.worktree, ['ls-files', '--others', '--exclude-standard', '-z'], { encoding: null }));
+  for (const path of untracked.split('\0').filter(Boolean)) {
+    if (!excluded(path) && !known.has(path)) fail('RESTORATION_SOURCE_CHANGED', 'new untracked work is outside the original checkpoint', { path });
+  }
+}
+function readBaseBlob(directory, checkpoint, blob) {
+  const stored = readSafeInstallationStorageFile(join(directory, 'blobs', blob.sha256), { allowMissing: true, encoding: null, maxBytes: MAX_BYTES });
+  const bytes = stored ? stored.content : checkpoint.readBlob(blob);
+  if (sha256(ref(bytes)) !== sha256(blob)) fail('RESTORATION_BLOB_CHANGED', 'restoration blob changed');
+  return bytes;
+}
+function prepareEntry(directory, checkpoint, state) {
+  const stage = privateDirectory(join(directory, 'staging', randomUUID()));
+  try {
+    if (state.type === 'symlink') symlinkAtSync(readBaseBlob(directory, checkpoint, state.blob), stage, 'entry');
+    else if (state.type === 'directory') {
+      mkdirAtSync(stage, 'entry');
+      const fd = openAtSync(stage, 'entry', O_DIRECTORY);
+      try { fchmodSync(fd, state.mode); fsyncSync(fd); } finally { closeSync(fd); }
+    } else {
+      const fd = openAtSync(stage, 'entry', constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, 0o600);
+      try { writeFileSync(fd, readBaseBlob(directory, checkpoint, state.blob)); fchmodSync(fd, state.mode); fsyncSync(fd); }
+      finally { closeSync(fd); }
+    }
+    fsyncSync(stage);
+    return stage;
+  } catch (error) { closeSync(stage); throw error; }
+}
+function verifyRetired(fd, index, operation, directory) {
+  const preservedPath = join(directory, 'retired', String(index));
+  if (!same(readEntryAt(fd, String(index)), operation.before)) fail('RESTORATION_SOURCE_CHANGED', 'entry changed during retirement; its bytes remain preserved', { preserved_path: preservedPath });
+  if (operation.before.type === 'directory') {
+    const child = openAtSync(fd, String(index), O_DIRECTORY);
+    try {
+      if (readDirectorySync(child, { encoding: 'buffer' }).length) fail('RESTORATION_SOURCE_CHANGED', 'concurrent directory contents remain preserved', { preserved_path: preservedPath });
+    } finally { closeSync(child); }
+  }
+}
+
+function acquireGitLocks(plan, intentDigest, directory) {
+  const held = [];
+  const assertHeld = () => {
+    for (const lock of held) {
+      const current = lstatAtSync(lock.parent.fd, lock.parent.name);
+      const pinned = fstatSync(lock.fd);
+      if (current.dev !== pinned.dev || current.ino !== pinned.ino || current.nlink !== 1
+        || !readCheckpointFileAt(lock.parent.fd, lock.parent.name).bytes.equals(lock.bytes)) {
+        fail('RESTORATION_GIT_LOCK_CHANGED', 'restoration no longer owns its exact Git lock');
+      }
+    }
+  };
+  const release = () => {
+    let failure;
+    for (const lock of held.reverse()) {
+      try {
+        const current = lstatAtSync(lock.parent.fd, lock.parent.name);
+        const pinned = fstatSync(lock.fd);
+        if (current.dev !== pinned.dev || current.ino !== pinned.ino || current.nlink !== 1
+          || !readCheckpointFileAt(lock.parent.fd, lock.parent.name).bytes.equals(lock.bytes)) {
+          fail('RESTORATION_GIT_LOCK_CHANGED', 'changed Git lock was not removed');
+        }
+        unlinkAtSync(lock.parent.fd, lock.parent.name); fsyncSync(lock.parent.fd);
+      } catch (error) { failure ??= error; }
+      finally { closeSync(lock.fd); closeSync(lock.parent.fd); }
+    }
+    held.length = 0;
+    if (failure) throw failure;
+  };
+  try {
+    for (const lock of plan.locks) {
+      const parent = openParent(plan.roots, lock);
+      const bytes = Buffer.from(canonicalSerialize({ purpose: 'rail_restoration_lock', intent_digest: intentDigest, nonce: lock.nonce }));
+      let fd;
+      try {
+        if (readEntryAt(parent.fd, parent.name).type === 'absent') {
+          const stage = privateDirectory(join(directory, 'lock-staging', randomUUID()));
+          try {
+            const staged = openAtSync(stage, 'entry', constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY, 0o600);
+            try { writeFileSync(staged, bytes); fsyncSync(staged); } finally { closeSync(staged); }
+            try { renameNoReplaceAtSync(stage, 'entry', parent.fd, parent.name); fsyncSync(stage); fsyncSync(parent.fd); }
+            catch (error) { if (error.code !== 'EEXIST') throw error; }
+          } finally { closeSync(stage); }
+        }
+        if (!readCheckpointFileAt(parent.fd, parent.name).bytes.equals(bytes)) {
+          fail('RESTORATION_GIT_LOCK_PRESENT', 'another Git transaction owns this lock', { path: entryPath(plan.roots, lock) });
+        }
+        fd = openAtSync(parent.fd, parent.name, constants.O_RDWR | constants.O_NONBLOCK);
+        if (!tryExclusiveFileLockSync(fd)) fail('RESTORATION_ALREADY_RUNNING', 'another restoration process still holds the Git lock');
+        held.push({ parent, fd, bytes }); fd = undefined;
+      } catch (error) { if (fd !== undefined) closeSync(fd); closeSync(parent.fd); throw error; }
+    }
+    assertHeld();
+    return { assertHeld, release };
+  } catch (error) { release(); throw error; }
+}
+
+function applyOperation(plan, operation, index, directory, checkpoint) {
+  hook('beforeOperation', { projectDir: plan.roots.worktree, operation, index });
+  const parent = openParent(plan.roots, operation);
+  try {
+    if (!same(readEntryAt(parent.fd, parent.name), operation.before)) fail('RESTORATION_SOURCE_CHANGED', 'entry changed before its restoration step', { path: operation.path });
+    if (operation.kind === 'retire') {
+      if (operation.before.type === 'directory') {
+        const fd = openAtSync(parent.fd, parent.name, O_DIRECTORY);
+        try { if (readDirectorySync(fd, { encoding: 'buffer' }).length) fail('RESTORATION_SOURCE_CHANGED', 'directory gained unpreserved contents'); }
+        finally { closeSync(fd); }
+      }
+      const retired = privateDirectory(join(directory, 'retired'));
+      try {
+        renameNoReplaceAtSync(parent.fd, parent.name, retired, String(index));
+        fsyncSync(parent.fd); fsyncSync(retired);
+        hook('afterRetire', { operation, preservedPath: join(directory, 'retired', String(index)) });
+        verifyRetired(retired, index, operation, directory);
+      } finally { closeSync(retired); }
+    } else {
+      const stage = prepareEntry(directory, checkpoint, operation.after);
+      try {
+        hook('beforePublish', { operation, projectDir: plan.roots.worktree });
+        try { renameNoReplaceAtSync(stage, 'entry', parent.fd, parent.name); }
+        catch (error) {
+          if (error.code === 'EEXIST') fail('RESTORATION_SOURCE_CHANGED', 'a concurrently created entry was preserved', { path: operation.path });
+          throw error;
+        }
+        fsyncSync(stage); fsyncSync(parent.fd);
+      }
+      finally { closeSync(stage); }
+    }
+    if (!same(readEntryAt(parent.fd, parent.name), operation.after)) fail('RESTORATION_SOURCE_CHANGED', 'entry changed after restoration step', { path: operation.path });
+    hook('afterMutation', { projectDir: plan.roots.worktree, operation, index });
+  } finally { closeSync(parent.fd); }
+}
+
+/** Host adapter only: caller must hold the canonical journal exclusion and
+ * revalidate stopped owner, lease, admission and effects before invoking it. */
+export function restoreRailWorktreeCheckpoint({ projectDir, receipt }) {
+  const checkpoint = readRailWorktreeCheckpoint({ projectDir, receipt });
+  const directory = baseDirectory(projectDir, checkpoint);
+  const fd = privateDirectory(directory); closeSync(fd);
+  const intent = loadIntent(projectDir, checkpoint, directory);
+  const plan = intent.plan; const intentDigest = sha256(intent);
+  for (const blob of plan.blobs) readBaseBlob(directory, checkpoint, blob);
+  const locks = acquireGitLocks(plan, intentDigest, directory);
+  try {
+  let cursor = 0;
+  for (; cursor < plan.operations.length; cursor += 1) {
+    const existing = readSafeInstallationStorageFile(join(directory, 'steps', `${cursor}.json`), { allowMissing: true });
+    if (!existing) break;
+    verify(JSON.parse(existing.content), { purpose: 'rail_restoration_step', intent_digest: intentDigest, step_index: cursor });
+  }
+  // One syscall may be durable while its progress receipt is not. Recognize
+  // only that exact next state, never an arbitrary later prefix or new snapshot.
+  try { assertState(plan, cursor); }
+  catch (error) {
+    if (error.code !== 'RESTORATION_SOURCE_CHANGED' || cursor === plan.operations.length) throw error;
+    assertState(plan, cursor + 1);
+    const operation = plan.operations[cursor];
+    if (operation.kind === 'retire') {
+      const retired = openCheckpointDirectory(join(directory, 'retired'));
+      try { verifyRetired(retired, cursor, operation, directory); }
+      finally { closeSync(retired); }
+    }
+    persistJson(join(directory, 'steps', `${cursor}.json`), signed({ purpose: 'rail_restoration_step', intent_digest: intentDigest, step_index: cursor }));
+    hook('afterProgress', { projectDir, operation: plan.operations[cursor], index: cursor });
+    cursor += 1;
+  }
+  for (; cursor < plan.operations.length; cursor += 1) {
+    locks.assertHeld();
+    applyOperation(plan, plan.operations[cursor], cursor, directory, checkpoint);
+    persistJson(join(directory, 'steps', `${cursor}.json`), signed({ purpose: 'rail_restoration_step', intent_digest: intentDigest, step_index: cursor }));
+    hook('afterProgress', { projectDir, operation: plan.operations[cursor], index: cursor });
+  }
+  assertState(plan, cursor);
+  locks.assertHeld();
+  captureRailExecutionWorktree({ projectDir, baseCommitRef: plan.binding.base_commit_ref });
+  const result = signed({ purpose: 'rail_execution_restoration', schema_version: 1, project_dir: resolve(projectDir),
+    checkpoint_receipt_digest: sha256(receipt), intent_digest: intentDigest,
+    binding: plan.binding, restored_base_commit_ref: plan.binding.base_commit_ref, step_count: cursor });
+  const existing = readSafeInstallationStorageFile(join(directory, 'receipt.json'), { allowMissing: true });
+  if (existing) {
+    const value = JSON.parse(existing.content);
+    verify(value, { purpose: result.purpose, checkpoint_receipt_digest: result.checkpoint_receipt_digest, intent_digest: intentDigest });
+    return value;
+  }
+  persistJson(join(directory, 'receipt.json'), result);
+  return result;
+  } finally { locks.release(); }
+}
+
+/** Authenticate durable history without requiring later executions to remain at
+ * this old base. Current-state validation is mandatory at claim recovery only. */
+export function readRailWorktreeRestoration({ projectDir, receipt, checkpointReceipt, expected = {}, current = false }) {
+  const checkpoint = readRailWorktreeCheckpoint({ projectDir, receipt: checkpointReceipt });
+  const directory = baseDirectory(projectDir, checkpoint);
+  const readJson = (path) => JSON.parse(readSafeInstallationStorageFile(path, { maxBytes: MAX_PLAN_BYTES }).content);
+  const intent = readJson(join(directory, 'intent.json'));
+  verify(intent, { purpose: 'rail_restoration_intent', checkpoint_receipt_digest: sha256(checkpointReceipt) });
+  const plan = intent.plan;
+  const stored = readJson(join(directory, 'receipt.json'));
+  if (sha256(stored) !== sha256(receipt)) fail('RESTORATION_AUTHORITY_MISMATCH', 'restoration receipt differs from durable storage');
+  verify(stored, { ...expected, purpose: 'rail_execution_restoration', schema_version: 1,
+    project_dir: resolve(projectDir), checkpoint_receipt_digest: sha256(checkpointReceipt),
+    intent_digest: sha256(intent), binding: checkpoint.manifest.binding,
+    restored_base_commit_ref: checkpoint.manifest.binding.base_commit_ref, step_count: plan.operations.length });
+  if (sha256(plan.binding) !== sha256(checkpoint.manifest.binding)
+    || plan.checkpoint_receipt_digest !== sha256(checkpointReceipt)) {
+    fail('RESTORATION_AUTHORITY_MISMATCH', 'restoration plan is not bound to this checkpoint');
+  }
+  for (const blob of plan.blobs) readBaseBlob(directory, checkpoint, blob);
+  for (let index = 0; index < plan.operations.length; index += 1) {
+    verify(readJson(join(directory, 'steps', `${index}.json`)), {
+      purpose: 'rail_restoration_step', intent_digest: sha256(intent), step_index: index });
+  }
+  if (current) {
+    assertState(plan, plan.operations.length);
+    captureRailExecutionWorktree({ projectDir, baseCommitRef: plan.binding.base_commit_ref });
+  }
+  return stored;
+}