chati-dev 4.5.28 → 4.5.29

package/src/terminal/rail-readonly-workspace.js

@@ -257,12 +257,60 @@ function extractArchiveIntoPinnedSubject(archivePath, subjectDir) {
   }
 }
 
-/** Materialize exactly one immutable Git commit without linking its .git dir. */
-export function createRailReadOnlyCommitWorkspace({ projectDir, baseCommitRef, resultCommitRef } = {}) {
+function archiveVerificationCommit({ projectDir, root, resultCommitRef, archivePath }) {
+  // A separate empty metadata repository prevents local/info/global attributes,
+  // export-ignore and export-subst from changing the committed verification
+  // subject. Only the object database is read, never checked-out metadata.
+  const metadata = join(root, 'export.git');
+  const attributes = join(root, 'empty-attributes');
+  mkdirSync(attributes, { mode: 0o700 });
+  const environment = trustedGitEnvironment();
+  execFileSync('git', ['init', '--quiet', '--bare', '--template=',
+    `--object-format=${resultCommitRef.length === 64 ? 'sha256' : 'sha1'}`, metadata], { env: environment, stdio: 'pipe' });
+  const objects = git(projectDir, ['rev-parse', '--git-path', 'objects'], { encoding: 'utf8' }).trim();
+  execFileSync('git', ['--git-dir', metadata, '--work-tree', attributes,
+    '-c', 'core.attributesFile=/dev/null', 'archive', '--worktree-attributes',
+    '--format=tar', '--output', archivePath, resultCommitRef], {
+    env: { ...environment, GIT_OBJECT_DIRECTORY: realpathSync(resolve(projectDir, objects)) }, stdio: 'pipe',
+  });
+}
+
+export const RAIL_READ_ONLY_WORKSPACE_PREFIX = 'chati-rail-review-subject-';
+export const RETAINED_WORKSPACE_SWEEP_AFTER_MS = 24 * 60 * 60 * 1000;
+
+/** Darwin retains finished review/verification workspaces because scoped group
+ * completion cannot prove that every detached reader died. Without a reaper
+ * they accumulate on every ordinary run. Reclaim retained roots that are older
+ * than a generous bound: any reader still alive that long is not a legitimate
+ * review process. Best effort, never throws, never touches recent roots. */
+export function sweepRetainedReadOnlyWorkspaces({
+  directory = tmpdir(), prefixes = [RAIL_READ_ONLY_WORKSPACE_PREFIX],
+  olderThanMs = RETAINED_WORKSPACE_SWEEP_AFTER_MS, now = Date.now(),
+} = {}) {
+  const removed = [];
+  let entries;
+  try { entries = readdirSync(directory); } catch { return removed; }
+  for (const name of entries) {
+    if (!prefixes.some((prefix) => name.startsWith(prefix))) continue;
+    const path = join(directory, name);
+    try {
+      const stat = lstatSync(path);
+      if (!stat.isDirectory() || stat.isSymbolicLink() || stat.uid !== process.getuid?.()) continue;
+      if (now - stat.mtimeMs < olderThanMs) continue;
+      rmSync(path, { recursive: true, force: true });
+      removed.push(path);
+    } catch { /* best effort: a concurrent owner or a permission boundary keeps it */ }
+  }
+  return removed;
+}
+
+/** Materialize one immutable commit without linking its .git dir to the child. */
+export function createRailReadOnlyCommitWorkspace({ projectDir, baseCommitRef, resultCommitRef, verificationSubject = false } = {}) {
   const canonicalProject = realpathSync(resolve(projectDir));
   const resolvedBase = resolveExactCommit(canonicalProject, baseCommitRef, 'RAIL_REVIEW_BASE_COMMIT_INVALID', 'base');
   const resolvedCommit = resolveExactCommit(canonicalProject, resultCommitRef, 'RAIL_REVIEW_RESULT_COMMIT_INVALID', 'result');
-  const root = mkdtempSync(join(tmpdir(), 'chati-rail-review-subject-'));
+  if (process.platform === 'darwin') sweepRetainedReadOnlyWorkspaces();
+  const root = mkdtempSync(join(tmpdir(), RAIL_READ_ONLY_WORKSPACE_PREFIX));
   const rootStat = lstatSync(root);
   const rootIdentity = {
     dev: rootStat.dev,
@@ -275,10 +323,11 @@ export function createRailReadOnlyCommitWorkspace({ projectDir, baseCommitRef, r
   try {
     mkdirSync(subjectDir, { mode: 0o700 });
     runReadOnlyWorkspaceTestHook('afterSubjectDirectoryCreate', { root, subjectDir });
-    git(canonicalProject, ['archive', '--format=tar', '--output', archivePath, resultCommitRef], { stdio: 'ignore' });
+    if (verificationSubject) archiveVerificationCommit({ projectDir: canonicalProject, root, resultCommitRef, archivePath });
+    else git(canonicalProject, ['archive', '--format=tar', '--output', archivePath, resultCommitRef], { stdio: 'ignore' });
     extractArchiveIntoPinnedSubject(archivePath, subjectDir);
     rmSync(archivePath);
-    materializeReviewDelta({
+    if (!verificationSubject) materializeReviewDelta({
       projectDir: canonicalProject, baseCommitRef: resolvedBase, resultCommitRef: resolvedCommit, subjectDir,
     });
     const baseline = captureCommitSubject(subjectDir, resolvedCommit, resolvedBase);

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

@@ -0,0 +1,315 @@
+import { createHash } from 'node:crypto';
+import { closeSync, constants, fstatSync, openSync, readSync } from 'node:fs';
+import { basename, join, parse, resolve, sep } from 'node:path';
+import { canonicalize, canonicalSerialize, sha256, openAtSync, lstatAtSync, readDirectorySync, readlinkAtSync } from '@chati/core';
+import { persistImmutableInstallationFile, readSafeInstallationStorageFile } from '../installer-v2/catalog-client.js';
+import { signHostAuthorityPayload, verifyHostAuthorityPayload } from '../installer-v2/installation-authority.js';
+import { railRepositoryIdentity, readRailGitState as git } from './rail-execution-worktree.js';
+import { verifyTerminalAuthorityReceipt } from './spawner.js';
+
+const DOMAIN = 'chati.rail-worktree-checkpoint.v1';
+const MAX_BYTES = 128 * 1024 * 1024;
+const MAX_ENTRIES = 10_000;
+const MANIFEST_BYTES = 4 * 1024 * 1024;
+const O_DIRECTORY = constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW;
+const HASH = /^[a-f0-9]{64}$/;
+const OID = /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/;
+const hooks = Symbol.for('chati.checkpoint.security-test-hooks');
+const rawHash = (bytes) => createHash('sha256').update(bytes).digest('hex');
+function fail(code, message) { throw Object.assign(new Error(message), { code }); }
+function hook(name, detail) { globalThis[hooks]?.[name]?.(detail); }
+function decode(bytes) {
+  try { return new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes); }
+  catch { return fail('CHECKPOINT_PATH_ENCODING_UNSUPPORTED', 'checkpoint paths must be losslessly representable as UTF-8'); }
+}
+function excluded(path) { return ['.chati', '.chati.dev'].includes(path.split('/')[0]); }
+function components(path) {
+  const parts = path.split('/');
+  if (!path || parts.some((part) => !part || ['.', '..', '.git'].includes(part) || /[\\\0]/.test(part) || Buffer.byteLength(part) > 255)) {
+    fail('CHECKPOINT_UNSAFE_PATH', 'checkpoint path must stay inside the worktree without Git control entries');
+  }
+  return parts;
+}
+function sameSnapshot(a, b) {
+  return ['dev', 'ino', 'mode', 'nlink', 'size', 'mtimeNs', 'ctimeNs'].every((key) => a[key] === b[key]);
+}
+function openDirectory(path) {
+  const absolute = resolve(path);
+  const root = parse(absolute).root;
+  let fd = openSync(root, O_DIRECTORY);
+  try {
+    for (const part of absolute.slice(root.length).split(sep).filter(Boolean)) {
+      const next = openAtSync(fd, part, O_DIRECTORY);
+      closeSync(fd); fd = next;
+    }
+    return fd;
+  } catch (error) { closeSync(fd); throw error; }
+}
+function readFileAt(fd, name, { allowMissing = false } = {}) {
+  let source;
+  try { source = openAtSync(fd, name, constants.O_RDONLY | constants.O_NONBLOCK | constants.O_NOFOLLOW); }
+  catch (error) { if (allowMissing && error.code === 'ENOENT') return null; throw error; }
+  try {
+    const before = fstatSync(source, { bigint: true });
+    if (!before.isFile() || before.nlink !== 1n) fail('CHECKPOINT_UNSAFE_FILE', 'checkpoint input must be a regular single-link file');
+    if (before.size > BigInt(MAX_BYTES)) fail('CHECKPOINT_SIZE_LIMIT', 'checkpoint input exceeds 128 MiB');
+    const chunks = []; let total = 0;
+    while (total <= MAX_BYTES) {
+      const bytes = Buffer.allocUnsafe(Math.min(65536, MAX_BYTES + 1 - total));
+      const count = readSync(source, bytes, 0, bytes.length, null);
+      if (!count) break;
+      chunks.push(bytes.subarray(0, count)); total += count;
+    }
+    if (total > MAX_BYTES) fail('CHECKPOINT_SIZE_LIMIT', 'checkpoint input grew beyond 128 MiB');
+    if (!sameSnapshot(before, fstatSync(source, { bigint: true }))) fail('CHECKPOINT_SOURCE_CHANGED', 'file changed during checkpoint capture');
+    return { bytes: Buffer.concat(chunks, total), mode: Number(before.mode & 0o777n) };
+  } finally { closeSync(source); }
+}
+function readGitFile(repository, path, options) {
+  const parent = resolve(path, '..');
+  if (![repository.git_dir.path, repository.common_git_dir.path].includes(parent)) {
+    fail('CHECKPOINT_GIT_STORAGE_MISMATCH', 'Git metadata must belong to the signed repository storage');
+  }
+  const fd = openDirectory(parent);
+  try { return readFileAt(fd, basename(path), options); } finally { closeSync(fd); }
+}
+function nulEntries(bytes) {
+  const value = decode(bytes);
+  if (value && !value.endsWith('\0')) fail('CHECKPOINT_GIT_OUTPUT_INVALID', 'Git inventory must be NUL terminated');
+  return value ? value.slice(0, -1).split('\0') : [];
+}
+function checkpointId(dispatch) {
+  return sha256({ attempt_id: dispatch.payload.attempt_id, dispatch_event_id: dispatch.event_id,
+    launch_nonce: dispatch.payload.invocation.launch_nonce });
+}
+function storage(projectDir, id) {
+  if (!HASH.test(id)) fail('CHECKPOINT_REFERENCE_INVALID', 'checkpoint ID must be a SHA-256 digest');
+  return join(resolve(projectDir), '.chati/v2/rail/worktree-checkpoints', id);
+}
+function blobReader(directory) {
+  return (ref) => {
+    if (!ref || !HASH.test(ref.sha256) || !Number.isSafeInteger(ref.size) || ref.size < 0 || ref.size > MAX_BYTES) {
+      fail('CHECKPOINT_BLOB_INVALID', 'checkpoint blob reference is invalid');
+    }
+    const bytes = readSafeInstallationStorageFile(join(directory, 'blobs', ref.sha256), { encoding: null, maxBytes: MAX_BYTES }).content;
+    if (bytes.length !== ref.size || rawHash(bytes) !== ref.sha256) fail('CHECKPOINT_BLOB_MISMATCH', 'checkpoint blob is missing or changed');
+    return bytes;
+  };
+}
+
+function checkpointConfiguration(projectDir) {
+  // Inspect the same effective configuration Git loads, including includes and
+  // enabled worktree config. Do not disclose values in receipts or diagnostics.
+  const bytes = git(projectDir, ['config', '--null', '--list', '--includes'], { encoding: null });
+  if (bytes.length && bytes.at(-1) !== 0) fail('CHECKPOINT_GIT_CONFIG_INVALID', 'Git configuration inventory is incomplete');
+  let offset = 0;
+  while (offset < bytes.length) {
+    const end = bytes.indexOf(0, offset);
+    const entry = bytes.subarray(offset, end);
+    const newline = entry.indexOf(10);
+    const key = entry.subarray(0, newline < 0 ? entry.length : newline).toString('latin1');
+    if (/^(?:extensions\.partialclone|remote\..*\.(?:promisor|partialclonefilter))$/i.test(key)) {
+      fail('CHECKPOINT_PARTIAL_CLONE_UNSUPPORTED', 'checkpoint does not support partial-clone/promisor configuration; Git and worktree were not changed');
+    }
+    offset = end + 1;
+  }
+  return rawHash(bytes);
+}
+
+function captureState(projectDir, repository, base, blob, configurationDigest) {
+  if (checkpointConfiguration(projectDir) !== configurationDigest) fail('CHECKPOINT_SOURCE_CHANGED', 'Git configuration changed before capture');
+  const head = git(projectDir, ['rev-parse', '--verify', 'HEAD^{commit}']).trim();
+  if (!OID.test(head)) fail('CHECKPOINT_GIT_OUTPUT_INVALID', 'checkpoint requires an exact partial HEAD');
+  const headFile = readGitFile(repository, join(repository.git_dir.path, 'HEAD'));
+  const rawHead = decode(headFile.bytes).trim();
+  const headRef = rawHead.startsWith('ref: ') ? rawHead.slice(5) : null;
+  if ((headRef !== null && !/^refs\/[^\s\0]+$/.test(headRef)) || (headRef === null && rawHead !== head)) {
+    fail('CHECKPOINT_GIT_OUTPUT_INVALID', 'HEAD must have a recoverable symbolic or detached identity');
+  }
+  const indexPath = resolve(projectDir, git(projectDir, ['rev-parse', '--git-path', 'index']).trim());
+  const index = readGitFile(repository, indexPath, { allowMissing: true });
+  const sharedPath = git(projectDir, ['rev-parse', '--shared-index-path']).trim();
+  let shared = null;
+  if (sharedPath) {
+    if (!/^sharedindex\.(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(basename(sharedPath))) fail('CHECKPOINT_GIT_OUTPUT_INVALID', 'split index dependency is invalid');
+    shared = { name: basename(sharedPath), blob: blob(readGitFile(repository, resolve(projectDir, sharedPath)).bytes) };
+  }
+  const shallowPath = resolve(projectDir, git(projectDir, ['rev-parse', '--git-path', 'shallow']).trim());
+  const shallow = readGitFile(repository, shallowPath, { allowMissing: true });
+  const stageBytes = git(projectDir, ['ls-files', '--stage', '-z'], { encoding: null });
+  const paths = new Set(); const objectIds = new Set([base, head]);
+  const addPath = (path) => { if (!excluded(path)) { components(path); paths.add(path); } };
+  for (const entry of nulEntries(stageBytes)) {
+    const match = /^(\d{6}) ([a-f0-9]{40,64}) [0-3]\t([\s\S]+)$/.exec(entry);
+    if (!match || !OID.test(match[2])) fail('CHECKPOINT_GIT_OUTPUT_INVALID', 'Git index inventory is malformed');
+    if (match[1] === '160000') fail('CHECKPOINT_GITLINK_UNSUPPORTED', 'submodule storage requires an explicit recursive checkpoint before restoration');
+    if (!/^0+$/.test(match[2])) objectIds.add(match[2]);
+    addPath(match[3]);
+  }
+  for (const commit of [base, head]) {
+    for (const entry of nulEntries(git(projectDir, ['ls-tree', '-r', '-z', '--full-tree', commit], { encoding: null }))) {
+      const match = /^(\d{6}) (?:blob|commit) [a-f0-9]{40,64}\t([\s\S]+)$/.exec(entry);
+      if (!match) fail('CHECKPOINT_GIT_OUTPUT_INVALID', 'Git tree inventory is malformed');
+      if (match[1] === '160000') fail('CHECKPOINT_GITLINK_UNSUPPORTED', 'submodule storage requires an explicit recursive checkpoint before restoration');
+      addPath(match[2]);
+    }
+  }
+  for (const path of nulEntries(git(projectDir, ['ls-files', '--others', '--exclude-standard', '-z'], { encoding: null }))) addPath(path);
+  // Include cache-tree and resolve-undo dependencies, not only visible staged
+  // blobs. Restrict enumeration to this index, never other linked worktrees.
+  const reachable = git(projectDir, ['rev-list', '--objects', '--no-object-names', '--single-worktree', '--indexed-objects', base, head]);
+  for (const oid of reachable.trim().split('\n').filter(Boolean)) {
+    if (!OID.test(oid)) fail('CHECKPOINT_GIT_OUTPUT_INVALID', 'Git object closure is malformed');
+    objectIds.add(oid);
+  }
+  if (paths.size > MAX_ENTRIES) fail('CHECKPOINT_ENTRY_LIMIT', 'checkpoint exceeds 10,000 paths');
+  const trie = { children: new Map(), full: false };
+  for (const path of paths) {
+    let node = trie;
+    for (const part of components(path)) {
+      if (!node.children.has(part)) node.children.set(part, { children: new Map(), full: false });
+      node = node.children.get(part);
+    }
+    node.full = true;
+  }
+  const files = [];
+  const walk = (parent, name, path, node, inheritedFull = false) => {
+    if (files.length >= MAX_ENTRIES) fail('CHECKPOINT_ENTRY_LIMIT', 'checkpoint exceeds 10,000 entries');
+    components(path);
+    let before;
+    try { before = lstatAtSync(parent, name, { bigint: true }); }
+    catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+      files.push({ path, type: 'absent' }); return;
+    }
+    if (before.isSymbolicLink()) {
+      const bytes = readlinkAtSync(parent, name);
+      if (!sameSnapshot(before, lstatAtSync(parent, name, { bigint: true }))) fail('CHECKPOINT_SOURCE_CHANGED', 'symlink changed while captured');
+      files.push({ path, type: 'symlink', blob: blob(bytes) });
+    } else if (before.isFile()) {
+      const content = readFileAt(parent, name);
+      if (!sameSnapshot(before, lstatAtSync(parent, name, { bigint: true }))) fail('CHECKPOINT_SOURCE_CHANGED', 'file path changed while captured');
+      files.push({ path, type: 'file', mode: content.mode, blob: blob(content.bytes) });
+    } else if (before.isDirectory()) {
+      const fd = openAtSync(parent, name, O_DIRECTORY);
+      try {
+        const pinned = fstatSync(fd, { bigint: true });
+        if (pinned.dev !== before.dev || pinned.ino !== before.ino) fail('CHECKPOINT_SOURCE_CHANGED', 'directory changed before capture');
+        const full = inheritedFull || node.full;
+        const names = full ? readDirectorySync(fd, { encoding: 'buffer' }).map(decode).sort() : [...node.children.keys()].sort();
+        files.push({ path, type: 'directory', mode: Number(before.mode & 0o777n), complete: full });
+        for (const child of names) walk(fd, child, `${path}/${child}`, node.children.get(child) ?? { children: new Map(), full: true }, full);
+        if (!sameSnapshot(before, fstatSync(fd, { bigint: true }))
+          || !sameSnapshot(before, lstatAtSync(parent, name, { bigint: true }))) fail('CHECKPOINT_SOURCE_CHANGED', 'directory changed while captured');
+      } finally { closeSync(fd); }
+    } else fail('CHECKPOINT_UNSAFE_FILE', 'special files cannot be silently omitted from a checkpoint');
+  };
+  const rootFd = openDirectory(projectDir);
+  try { for (const name of [...trie.children.keys()].sort()) walk(rootFd, name, name, trie.children.get(name)); }
+  finally { closeSync(rootFd); }
+  if (sha256(railRepositoryIdentity(projectDir)) !== sha256(repository)) fail('CHECKPOINT_REPOSITORY_CHANGED', 'repository identity changed during capture');
+  if (checkpointConfiguration(projectDir) !== configurationDigest) fail('CHECKPOINT_SOURCE_CHANGED', 'Git configuration changed during capture');
+  return canonicalize({ git: { head, head_ref: headRef, head_file: blob(headFile.bytes), index: index ? blob(index.bytes) : null,
+    shared_index: shared, shallow: shallow ? blob(shallow.bytes) : null, index_listing: blob(stageBytes),
+    configuration_digest: configurationDigest,
+    object_format: git(projectDir, ['rev-parse', '--show-object-format']).trim(), object_ids: [...objectIds].sort() }, files });
+}
+
+export function readRailWorktreeCheckpoint({ projectDir, receipt, expected = {} }) {
+  const { authority_id, authority_signature, ...payload } = receipt ?? {};
+  if (payload.schema_version !== 1 || payload.purpose !== 'rail_execution_checkpoint'
+    || !verifyHostAuthorityPayload(payload, { domain: DOMAIN, authorityId: authority_id, signature: authority_signature })
+    || payload.project_dir !== resolve(projectDir)
+    || Object.entries(expected).some(([key, value]) => sha256(payload[key] ?? null) !== sha256(value))) {
+    fail('CHECKPOINT_AUTHORITY_MISMATCH', 'checkpoint receipt must authenticate the exact canonical execution');
+  }
+  const directory = storage(projectDir, payload.checkpoint_id);
+  const bytes = readSafeInstallationStorageFile(join(directory, 'manifest.json'), { encoding: null, maxBytes: MANIFEST_BYTES }).content;
+  if (rawHash(bytes) !== payload.manifest_sha256) fail('CHECKPOINT_MANIFEST_MISMATCH', 'checkpoint manifest changed');
+  const manifest = JSON.parse(decode(bytes));
+  if (!manifest.state || !Array.isArray(manifest.state.files) || manifest.state.files.length > MAX_ENTRIES
+    || sha256(manifest.binding) !== sha256(payload.binding) || sha256(manifest.state) !== payload.source_state_digest) {
+    fail('CHECKPOINT_MANIFEST_MISMATCH', 'checkpoint state or binding does not match its receipt');
+  }
+  const readBlob = blobReader(directory);
+  const refs = [manifest.pack, manifest.state.git.head_file, manifest.state.git.index_listing,
+    manifest.state.git.index, manifest.state.git.shared_index?.blob, manifest.state.git.shallow,
+    ...manifest.state.files.map((file) => file.blob)].filter(Boolean);
+  const seen = new Set(); let size = 0;
+  for (const ref of refs) {
+    if (seen.has(ref.sha256)) continue;
+    seen.add(ref.sha256); size += ref.size;
+    if (size > MAX_BYTES) fail('CHECKPOINT_SIZE_LIMIT', 'checkpoint exceeds 128 MiB');
+    readBlob(ref);
+  }
+  return Object.freeze({ receipt, manifest: Object.freeze(manifest), readBlob });
+}
+
+/** Capture only. No reset, clean, stash, index write, ref write or provider launch. */
+export function captureRailWorktreeCheckpoint({ projectDir, dispatch, interruption }) {
+  const launch = dispatch?.payload?.launch_receipt;
+  const nonce = dispatch?.payload?.invocation?.launch_nonce;
+  if (!verifyTerminalAuthorityReceipt(launch, { purpose: 'terminal_launch', authority_kind: 'rail_execution',
+    working_dir: resolve(projectDir), launch_nonce: nonce })
+    || interruption?.payload?.dispatch_event_id !== dispatch.event_id
+    || interruption.payload.launch_receipt_digest !== sha256(launch)
+    || interruption.payload.process?.status !== 'exited') {
+    fail('CHECKPOINT_DISPATCH_MISMATCH', 'checkpoint requires the canonical launch and its observed interruption');
+  }
+  // Must precede every object-resolution command. Transport denial alone is
+  // insufficient on old Git: lazy fetch can modify config before it is denied.
+  const configurationDigest = checkpointConfiguration(projectDir);
+  const repository = railRepositoryIdentity(projectDir);
+  if (sha256(repository) !== launch.execution_repository_identity_digest) fail('CHECKPOINT_REPOSITORY_CHANGED', 'repository differs from its signed launch identity');
+  const binding = canonicalize({ attempt_id: dispatch.payload.attempt_id, dispatch_event_id: dispatch.event_id,
+    interruption_event_id: interruption.event_id, launch_nonce: nonce, claim_id: dispatch.payload.claim_id,
+    launch_receipt_digest: sha256(launch), base_commit_ref: launch.execution_base_commit_ref,
+    repository_identity_digest: sha256(repository) });
+  const id = checkpointId(dispatch); const directory = storage(projectDir, id);
+  const existing = readSafeInstallationStorageFile(join(directory, 'receipt.json'), { allowMissing: true });
+  if (existing) return readRailWorktreeCheckpoint({ projectDir, receipt: JSON.parse(existing.content), expected: { binding } }).receipt;
+  const stored = new Map(); let total = 0;
+  const blob = (bytes, persist = true) => {
+    const digest = rawHash(bytes);
+    if (!stored.has(digest)) {
+      total += bytes.length;
+      if (total > MAX_BYTES) fail('CHECKPOINT_SIZE_LIMIT', 'checkpoint exceeds its 128 MiB total byte budget');
+      stored.set(digest, bytes.length);
+      if (persist) persistImmutableInstallationFile(join(directory, 'blobs', digest), bytes, { maxBytes: MAX_BYTES, label: 'worktree checkpoint blob' });
+    }
+    return { sha256: digest, size: bytes.length };
+  };
+  const state = captureState(projectDir, repository, binding.base_commit_ref, blob, configurationDigest);
+  const pack = blob(git(projectDir, ['pack-objects', '--stdout', '--threads=1', '--window=0', '--no-reuse-delta', '--no-reuse-object'], {
+    encoding: null, input: `${state.git.object_ids.join('\n')}\n`,
+  }));
+  hook('afterCheckpointCapture', { projectDir });
+  const after = captureState(projectDir, repository, binding.base_commit_ref, (bytes) => ({ sha256: rawHash(bytes), size: bytes.length }), configurationDigest);
+  if (sha256(state) !== sha256(after)) fail('CHECKPOINT_SOURCE_CHANGED', 'worktree or index changed before checkpoint commit');
+  const manifest = canonicalize({ schema_version: 1, binding, state, pack });
+  const bytes = Buffer.from(canonicalSerialize(manifest));
+  const material = { schema_version: 1, purpose: 'rail_execution_checkpoint', project_dir: resolve(projectDir),
+    checkpoint_id: id, binding, manifest_sha256: rawHash(bytes), source_state_digest: sha256(state) };
+  const signed = signHostAuthorityPayload(material, { domain: DOMAIN });
+  const receipt = canonicalize({ ...material, authority_id: signed.authority_id, authority_signature: signed.signature });
+  persistImmutableInstallationFile(join(directory, 'manifest.json'), bytes, { maxBytes: MANIFEST_BYTES, label: 'worktree checkpoint manifest' });
+  readRailWorktreeCheckpoint({ projectDir, receipt, expected: { binding } });
+  persistImmutableInstallationFile(join(directory, 'receipt.json'), canonicalSerialize(receipt));
+  return Object.freeze(receipt);
+}
+
+/** Used only by the host restoration adapter, before committing its intent. */
+export function assertRailCheckpointSourceUnchanged(projectDir, checkpoint) {
+  const repository = railRepositoryIdentity(projectDir);
+  const binding = checkpoint.manifest.binding;
+  if (sha256(repository) !== binding.repository_identity_digest) fail('CHECKPOINT_REPOSITORY_CHANGED', 'checkpoint repository identity changed');
+  const configuration = checkpointConfiguration(projectDir);
+  const state = captureState(projectDir, repository, binding.base_commit_ref,
+    (bytes) => ({ sha256: rawHash(bytes), size: bytes.length }), configuration);
+  if (sha256(state) !== checkpoint.receipt.source_state_digest) fail('CHECKPOINT_SOURCE_CHANGED', 'current source differs from the original checkpoint');
+  return repository;
+}
+
+// Internal shared I/O, not a new public recovery entrypoint.
+export { openDirectory as openCheckpointDirectory, readFileAt as readCheckpointFileAt,
+  checkpointConfiguration as readCheckpointConfiguration, components as checkpointPathComponents };