amalgm 0.1.238 → 0.1.240

package/runtime/scripts/amalgm-mcp/workspace/transition.js

@@ -7,23 +7,47 @@
  * no shell, pinned cwd, no prompts, and config armor so repo-configured
  * programs (hooks, fsmonitor) can never run under an executed transition.
  *
- * The verbs are deliberately few and exact — fetch one branch from a
- * named remote, fast-forward to an exact commit, apply or reverse a
- * captured patch. Anything messier is a human act on one machine; the
- * rail carries its settled outcome. Every execution, success or failure,
- * lands as one line in a visible journal before control returns.
+ * The verbs are deliberately few and exact — import verified objects,
+ * move Git metadata with expected-old guards, and replace file/index
+ * state only when the observed local state is unchanged. Anything messier
+ * is a human act on one machine; the rail carries its settled outcome.
+ * Every execution, success or failure, lands as one line in a visible
+ * journal before control returns.
  */
 
 const fs = require('fs');
 const path = require('path');
-const { execFile } = require('child_process');
+const crypto = require('crypto');
+const { execFile, execFileSync } = require('child_process');
 const { promisify } = require('util');
 const { AMALGM_DIR } = require('../config');
+const durable = require('./durable');
+const nativeFileTransaction = require('./native-file-transaction/client');
 
 const execFileAsync = promisify(execFile);
 
 const JOURNAL_FILE = path.join(AMALGM_DIR, 'state', 'workspace-transitions.jsonl');
-const HYDRATION_DIR = path.join(AMALGM_DIR, 'state', 'repo-hydration');
+const FILE_TRANSACTION_CONTRACT = 'workspace-file-transaction@4';
+const GIT_METADATA_TRANSACTION_CONTRACT = 'workspace-git-metadata-transaction@1';
+const GIT_WORKTREE_NAMESPACE_GUARD_CONTRACT = 'workspace-git-worktree-namespace-guard@2';
+const APPLY_RECEIPT_DIRECTORY = /^\.amalgm-apply-[0-9a-f]{64}$/;
+const APPLY_RECEIPT_EXCLUDE = `.amalgm-apply-${'[0-9a-f]'.repeat(64)}/`;
+
+function processLifetime(pid) {
+  return nativeFileTransaction.processLifetime(pid);
+}
+
+const PROCESS_LIFETIME = processLifetime(process.pid);
+if (!PROCESS_LIFETIME?.live) {
+  throw new Error('workspace transitions cannot identify their process lifetime');
+}
+const PROCESS_START_IDENTITY = PROCESS_LIFETIME.identity;
+
+function guardOwnerIsActive(transaction) {
+  const owner = processLifetime(transaction.ownerPid);
+  if (owner === null) return true;
+  return owner.live && owner.identity === transaction.ownerStarted;
+}
 
 const TRANSITION_ENV = {
   GIT_TERMINAL_PROMPT: '0',
@@ -54,14 +78,43 @@ function journal(entry) {
   }
 }
 
-async function run(action, worktreeRoot, args, { timeoutMs = 120_000, journalResult = true } = {}) {
+function execFileWithInput(file, args, options, input) {
+  return new Promise((resolve, reject) => {
+    const child = execFile(file, args, options, (error, stdout, stderr) => {
+      if (error) {
+        error.stdout = stdout;
+        error.stderr = stderr;
+        reject(error);
+        return;
+      }
+      resolve({ stdout, stderr });
+    });
+    child.stdin.on('error', () => {});
+    child.stdin.end(input);
+  });
+}
+
+async function run(
+  action,
+  worktreeRoot,
+  args,
+  {
+    timeoutMs = 120_000,
+    journalResult = true,
+    input = null,
+    env = {},
+  } = {},
+) {
   try {
-    const { stdout } = await execFileAsync('git', args, {
+    const options = {
       cwd: worktreeRoot,
-      env: { ...process.env, ...TRANSITION_ENV },
+      env: { ...process.env, ...TRANSITION_ENV, ...env },
       timeout: timeoutMs,
       maxBuffer: 32 * 1024 * 1024,
-    });
+    };
+    const { stdout } = input === null
+      ? await execFileAsync('git', args, options)
+      : await execFileWithInput('git', args, options, input);
     if (journalResult) journal({ action, worktree: worktreeRoot, args, ok: true });
     return stdout;
   } catch (error) {
@@ -73,14 +126,6 @@ async function run(action, worktreeRoot, args, { timeoutMs = 120_000, journalRes
   }
 }
 
-/** Bring one branch's objects and remote-tracking ref in from a named remote. */
-function fetchBranch(worktreeRoot, remote, branch) {
-  return run('fetch-branch', worktreeRoot, [
-    '-C', worktreeRoot, 'fetch', '--no-tags', remote,
-    `+refs/heads/${branch}:refs/remotes/${remote}/${branch}`,
-  ]);
-}
-
 async function createBundle(worktreeRoot, oid, bundleFile, exportRef) {
   await run('prepare-bundle-ref', worktreeRoot, [
     '-C', worktreeRoot, 'update-ref', exportRef, oid,
@@ -128,60 +173,18 @@ async function initializeRepo(worktreeRoot, remote) {
   }
 }
 
-async function checkoutInitialCard(worktreeRoot, { branch, oid }) {
-  await run('checkout-initial-card', worktreeRoot, branch
-    ? ['-C', worktreeRoot, 'checkout', '-B', branch, oid]
-    : ['-C', worktreeRoot, 'checkout', '--detach', oid], {
-    timeoutMs: 60_000,
-  });
-  const after = await currentHead(worktreeRoot);
-  if (after.branch !== (branch || null) || after.oid !== oid) {
-    throw new TransitionError(
-      'checkout-initial-card',
+async function currentHead(worktreeRoot) {
+  let oid = null;
+  try {
+    oid = (await run(
+      'observe-head',
       worktreeRoot,
-      `expected ${branch || '(detached)'}@${oid}, observed ${after.branch || '(detached)'}@${after.oid}`,
-    );
-  }
-}
-
-function holdInitialFiles(worktreeRoot) {
-  const entries = fs.readdirSync(worktreeRoot).filter((entry) => entry !== '.git');
-  if (!entries.length) return null;
-  fs.mkdirSync(HYDRATION_DIR, { recursive: true });
-  const holding = fs.mkdtempSync(path.join(HYDRATION_DIR, 'hold-'));
-  for (const entry of entries) {
-    fs.renameSync(path.join(worktreeRoot, entry), path.join(holding, entry));
+      ['-C', worktreeRoot, 'rev-parse', '--verify', 'HEAD'],
+      { journalResult: false },
+    )).trim();
+  } catch (error) {
+    if (!(error instanceof TransitionError)) throw error;
   }
-  journal({ action: 'hold-initial-files', worktree: worktreeRoot, holding, entries, ok: true });
-  return holding;
-}
-
-function restoreInitialFiles(worktreeRoot, holding) {
-  if (!holding) return;
-  fs.cpSync(holding, worktreeRoot, {
-    recursive: true,
-    force: true,
-    dereference: false,
-    verbatimSymlinks: true,
-  });
-  fs.rmSync(holding, { recursive: true, force: true });
-  journal({ action: 'restore-initial-files', worktree: worktreeRoot, holding, ok: true });
-}
-
-/** Fast-forward the current branch to an exact commit. Refuses anything but a ff. */
-function fastForwardTo(worktreeRoot, oid) {
-  return run('fast-forward', worktreeRoot, ['-C', worktreeRoot, 'merge', '--ff-only', oid], {
-    timeoutMs: 60_000,
-  });
-}
-
-async function currentHead(worktreeRoot) {
-  const oid = (await run(
-    'observe-head',
-    worktreeRoot,
-    ['-C', worktreeRoot, 'rev-parse', '--verify', 'HEAD'],
-    { journalResult: false },
-  )).trim();
   let branch = null;
   try {
     branch = (await run(
@@ -196,151 +199,476 @@ async function currentHead(worktreeRoot) {
   return { branch, oid };
 }
 
+async function branchOid(worktreeRoot, branch) {
+  try {
+    return (await run(
+      'observe-branch-oid',
+      worktreeRoot,
+      ['-C', worktreeRoot, 'rev-parse', '--verify', `refs/heads/${branch}`],
+      { journalResult: false },
+    )).trim();
+  } catch (error) {
+    if (error instanceof TransitionError) return null;
+    throw error;
+  }
+}
+
+function syncDirectory(directory) {
+  const descriptor = fs.openSync(directory, 'r');
+  try {
+    fs.fsyncSync(descriptor);
+  } finally {
+    fs.closeSync(descriptor);
+  }
+}
+
 /**
- * Materialize one exact card. Branch and OID are one instruction:
- * either the expected old pair still exists and the target pair lands,
- * or the command refuses without moving another branch.
+ * Change only HEAD's attachment, under Git's own HEAD lock. The index and
+ * working files are deliberately untouched. A process death therefore
+ * cannot discard local bytes; the reducer's durable apply record can replay
+ * the remaining content-addressed steps.
  */
-async function moveToCard(worktreeRoot, {
+async function compareAndSwapHead(worktreeRoot, {
   expectedBranch,
   expectedOid,
   targetBranch,
   targetOid,
+  operation,
 }) {
-  const before = await currentHead(worktreeRoot);
-  if (before.branch !== expectedBranch || before.oid !== expectedOid) {
-    throw new TransitionError('move-to-card', worktreeRoot, 'local card changed before movement');
+  if (!/^[0-9a-f]{64}$/.test(operation || '')) {
+    throw new Error('HEAD movement has no durable operation identity');
   }
+  const expected = Buffer.from(expectedBranch
+    ? `ref: refs/heads/${expectedBranch}\n`
+    : `${expectedOid}\n`);
+  const target = Buffer.from(targetBranch
+    ? `ref: refs/heads/${targetBranch}\n`
+    : `${targetOid}\n`);
+  if (expected.equals(target)) return;
+  applyGitMetadataTransaction(
+    worktreeRoot,
+    'HEAD',
+    expected,
+    target,
+    operation,
+  );
+}
 
-  if (before.branch === targetBranch) {
-    await fastForwardTo(worktreeRoot, targetOid);
-  } else {
-    await run(
-      'switch-card',
+/**
+ * Move only repository metadata to an exact card.
+ *
+ * Branch refs use compare-and-swap. Switching attachment uses Git's HEAD
+ * lock. Neither operation touches the index or working tree, so replay after
+ * a crash is idempotent and cannot erase pending local work.
+ */
+async function moveHeadToCard(worktreeRoot, {
+  expectedBranch,
+  expectedOid,
+  expectedTargetOid,
+  targetBranch,
+  targetOid,
+  operation,
+}) {
+  const before = await currentHead(worktreeRoot);
+  if (before.branch === (targetBranch || null) && before.oid === targetOid) {
+    if (
+      expectedBranch === (targetBranch || null)
+      && expectedOid === targetOid
+    ) return;
+    if (
+      /^[0-9a-f]{64}$/.test(operation || '')
+      && (
+        (
+          expectedBranch === (targetBranch || null)
+          && await branchReceiptCrossed(worktreeRoot, operation, targetBranch)
+        )
+        || (
+          expectedBranch !== (targetBranch || null)
+          && gitMetadataReceiptCrossed(worktreeRoot, operation, 'HEAD')
+        )
+      )
+    ) return;
+    throw new TransitionError(
+      'move-head-to-card',
       worktreeRoot,
-      ['-C', worktreeRoot, 'checkout', '-B', targetBranch, targetOid],
-      { timeoutMs: 60_000 },
+      'local HEAD reached the target without this ordered apply',
     );
   }
+  if (before.branch !== expectedBranch || before.oid !== expectedOid) {
+    throw new TransitionError('move-head-to-card', worktreeRoot, 'local card changed before movement');
+  }
+
+  if (targetBranch) {
+    const observedTarget = await branchOid(worktreeRoot, targetBranch);
+    if (observedTarget !== targetOid) {
+      if (observedTarget !== (expectedTargetOid || null)) {
+        throw new TransitionError(
+          'move-head-to-card',
+          worktreeRoot,
+          `target branch changed from ${expectedTargetOid || '(absent)'} to ${observedTarget || '(absent)'}`,
+        );
+      }
+      await updateBranchRefs(worktreeRoot, [{
+        branch: targetBranch,
+        expectedOid: observedTarget,
+        oid: targetOid,
+      }], operation);
+    }
+  }
+
+  if (!targetBranch || expectedBranch !== targetBranch) {
+    await compareAndSwapHead(worktreeRoot, {
+      expectedBranch,
+      expectedOid,
+      targetBranch,
+      targetOid,
+      operation,
+    });
+  }
 
   const after = await currentHead(worktreeRoot);
-  if (after.branch !== targetBranch || after.oid !== targetOid) {
+  if (after.branch !== (targetBranch || null) || after.oid !== targetOid) {
     throw new TransitionError(
-      'move-to-card',
+      'move-head-to-card',
       worktreeRoot,
-      `expected ${targetBranch}@${targetOid}, observed ${after.branch}@${after.oid}`,
+      `expected ${targetBranch || '(detached)'}@${targetOid}, observed ${after.branch || '(detached)'}@${after.oid}`,
     );
   }
 }
 
-/** Keep a commit reachable under one content-derived internal ref. */
-function parkCommit(worktreeRoot, oid) {
-  const ref = `refs/amalgm/parked/${oid}`;
-  return run('park-commit', worktreeRoot, [
-    '-C', worktreeRoot, 'update-ref', ref, oid,
-  ]).then(() => ref);
+async function emptyTree(worktreeRoot) {
+  return (await run(
+    'empty-tree',
+    worktreeRoot,
+    ['-C', worktreeRoot, 'mktree'],
+    { input: '', journalResult: false },
+  )).trim();
 }
 
-/** Delete internal parked refs that are no longer part of shared checkpoint state. */
-async function pruneParkedCommits(worktreeRoot, keepOids) {
-  const output = await run('list-parked-commits', worktreeRoot, [
-    '-C', worktreeRoot, 'for-each-ref', '--format=%(refname)', 'refs/amalgm/parked',
-  ], { journalResult: false });
-  const prefix = 'refs/amalgm/parked/';
-  for (const ref of output.trim().split('\n').filter(Boolean)) {
-    if (!ref.startsWith(prefix) || keepOids.has(ref.slice(prefix.length))) continue;
-    await run('remove-parked-commit', worktreeRoot, [
-      '-C', worktreeRoot, 'update-ref', '-d', ref,
-    ]);
+async function ensureEmptyIndex(worktreeRoot, operation, testHooks = {}) {
+  if (!/^[0-9a-f]{64}$/.test(operation || '')) {
+    throw new Error('index initialization has no durable operation identity');
+  }
+  const value = (await run(
+    'observe-index-file',
+    worktreeRoot,
+    ['-C', worktreeRoot, 'rev-parse', '--git-path', 'index'],
+    { journalResult: false },
+  )).trim();
+  const file = path.isAbsolute(value) ? value : path.resolve(worktreeRoot, value);
+  if (gitMetadataReceiptCrossed(worktreeRoot, operation, 'index')) {
+    if (testHooks.retainReceipt !== true) {
+      releaseGitMetadataReceipts(worktreeRoot, operation, 'index');
+    }
+    return;
+  }
+  if (fs.existsSync(file)) return;
+  if (typeof testHooks.afterAbsent === 'function') {
+    await testHooks.afterAbsent();
+  }
+  const stateDir = path.join(AMALGM_DIR, 'state');
+  fs.mkdirSync(stateDir, { recursive: true });
+  const scratch = path.join(
+    stateDir,
+    `empty-index-${process.pid}-${crypto.randomBytes(8).toString('hex')}`,
+  );
+  try {
+    await run(
+      'prepare-empty-index',
+      worktreeRoot,
+      ['-C', worktreeRoot, 'read-tree', '--empty'],
+      { env: { GIT_INDEX_FILE: scratch } },
+    );
+    applyGitMetadataTransaction(
+      worktreeRoot,
+      'index',
+      null,
+      fs.readFileSync(scratch),
+      operation,
+    );
+    if (testHooks.retainReceipt !== true) {
+      releaseGitMetadataReceipts(worktreeRoot, operation, 'index');
+    }
+  } finally {
+    fs.rmSync(scratch, { force: true });
   }
-}
-
-function setBranchRef(worktreeRoot, branch, oid) {
-  return run('set-branch-ref', worktreeRoot, [
-    '-C', worktreeRoot, 'update-ref', `refs/heads/${branch}`, oid,
-  ]);
-}
-
-function deleteBranchRef(worktreeRoot, branch) {
-  return run('delete-branch-ref', worktreeRoot, [
-    '-C', worktreeRoot, 'update-ref', '-d', `refs/heads/${branch}`,
-  ]);
 }
 
 /**
- * Exact card movement after the caller has durably parked the old commit
- * and captured the working tree. This deliberately discards the local
- * checkout copy; the caller immediately pours the preserved work back as
- * the checkpoint layer.
+ * Give an unborn repository its first exact card without checking out files.
+ * Existing files remain local pending work and are materialized separately.
  */
-async function forceMoveToCard(worktreeRoot, {
-  expectedBranch,
-  expectedOid,
+async function initializeHeadToCard(worktreeRoot, {
   targetBranch,
   targetOid,
+  operation,
 }) {
-  const before = await currentHead(worktreeRoot);
-  if (before.branch !== expectedBranch || before.oid !== expectedOid) {
-    throw new TransitionError('force-move-to-card', worktreeRoot, 'local card changed before movement');
+  try {
+    const current = await currentHead(worktreeRoot);
+    if (current.branch === (targetBranch || null) && current.oid === targetOid) return;
+    throw new TransitionError('initialize-head-to-card', worktreeRoot, 'repository already has another card');
+  } catch (error) {
+    if (!(error instanceof TransitionError) || error.action !== 'observe-head') throw error;
+  }
+
+  let expectedBranch = null;
+  try {
+    expectedBranch = (await run(
+      'observe-unborn-branch',
+      worktreeRoot,
+      ['-C', worktreeRoot, 'symbolic-ref', '--quiet', '--short', 'HEAD'],
+      { journalResult: false },
+    )).trim() || null;
+  } catch (error) {
+    if (!(error instanceof TransitionError)) throw error;
   }
   if (targetBranch) {
-    await run('force-move-to-card', worktreeRoot, [
-      '-C', worktreeRoot, 'checkout', '--force', '-B', targetBranch, targetOid,
-    ], { timeoutMs: 60_000 });
-  } else {
-    await run('force-move-to-card', worktreeRoot, [
-      '-C', worktreeRoot, 'checkout', '--force', '--detach', targetOid,
-    ], { timeoutMs: 60_000 });
+    const observedTarget = await branchOid(worktreeRoot, targetBranch);
+    if (observedTarget !== null && observedTarget !== targetOid) {
+      throw new TransitionError(
+        'initialize-head-to-card',
+        worktreeRoot,
+        'target branch already has another commit',
+      );
+    }
+    if (observedTarget === null) {
+      await updateBranchRefs(worktreeRoot, [{
+        branch: targetBranch,
+        expectedOid: null,
+        oid: targetOid,
+      }], operation);
+    }
   }
+  await compareAndSwapHead(worktreeRoot, {
+    expectedBranch,
+    expectedOid: null,
+    targetBranch,
+    targetOid,
+    operation,
+  });
   const after = await currentHead(worktreeRoot);
   if (after.branch !== (targetBranch || null) || after.oid !== targetOid) {
-    throw new TransitionError(
-      'force-move-to-card',
-      worktreeRoot,
-      `expected ${targetBranch || '(detached)'}@${targetOid}, observed ${after.branch || '(detached)'}@${after.oid}`,
-    );
+    throw new TransitionError('initialize-head-to-card', worktreeRoot, 'initial card did not land');
   }
 }
 
 /**
- * Apply a captured worktree patch — or reverse one — from a file on disk.
- * The patch file lives outside the repo (in the state dir), so what was
- * applied stays inspectable after the fact.
+ * Move a set of branch refs as one compare-and-swap transaction.
+ * Each change is { branch, expectedOid, oid }; null expectedOid means create
+ * only if absent, and null oid means delete only from the expected commit.
  */
-function applyPatch(worktreeRoot, patchFile, { reverse = false } = {}) {
-  return run(reverse ? 'reverse-patch' : 'apply-patch', worktreeRoot, [
-    '-C', worktreeRoot, 'apply', ...(reverse ? ['-R'] : []), '--whitespace=nowarn', patchFile,
-  ], { timeoutMs: 60_000 });
+function branchReceiptPrefix(operation) {
+  if (!/^[0-9a-f]{64}$/.test(operation || '')) {
+    throw new Error('branch receipt has no operation identity');
+  }
+  return `refs/amalgm/apply/${operation}/branches`;
+}
+
+function branchReceiptRef(operation, branch) {
+  if (typeof branch !== 'string' || branch.length === 0) {
+    throw new Error('branch receipt has no branch identity');
+  }
+  const digest = crypto.createHash('sha256').update(branch).digest('hex');
+  return `${branchReceiptPrefix(operation)}/${digest}`;
+}
+
+async function updateBranchRefs(
+  worktreeRoot,
+  changes,
+  operation = null,
+  testHooks = {},
+) {
+  if (changes.length === 0) return Promise.resolve('');
+  const deletions = changes.filter((change) => change.oid === null);
+  const nonDeletions = changes.filter((change) => change.oid !== null);
+  if (deletions.length > 0 && nonDeletions.length > 0) {
+    const checked = new Set(
+      (await listedWorktreeHeads(worktreeRoot))
+        .map((entry) => entry.branch)
+        .filter(Boolean),
+    );
+    if (nonDeletions.some((change) => checked.has(change.branch))) {
+      await updateBranchRefs(worktreeRoot, nonDeletions, operation);
+      if (typeof testHooks.afterNonDeletionBatch === 'function') {
+        await testHooks.afterNonDeletionBatch();
+      }
+      return updateBranchRefs(worktreeRoot, deletions, operation, testHooks);
+    }
+  }
+  let input = 'start\0';
+  for (const { branch, expectedOid, oid } of changes) {
+    const ref = `refs/heads/${branch}`;
+    if (oid === null) {
+      input += `delete ${ref}\0${expectedOid}\0`;
+    } else if (expectedOid === null) {
+      input += `create ${ref}\0${oid}\0`;
+    } else {
+      input += `update ${ref}\0${oid}\0${expectedOid}\0`;
+    }
+  }
+  if (operation !== null) {
+    for (const change of changes) {
+      const receiptOid = change.oid || change.expectedOid;
+      if (!/^[0-9a-f]{40,64}$/.test(receiptOid || '')) {
+        throw new Error('branch receipt has no object');
+      }
+      input += `create ${branchReceiptRef(operation, change.branch)}\0${receiptOid}\0`;
+    }
+  }
+  input += 'prepare\0commit\0';
+  const apply = (commonRoot = null) => run(
+    'update-branch-refs',
+    worktreeRoot,
+    commonRoot === null
+      ? ['-C', worktreeRoot, 'update-ref', '--stdin', '-z']
+      : [`--git-dir=${commonRoot}`, 'update-ref', '--stdin', '-z'],
+    { input },
+  );
+  if (!changes.some((change) => change.oid === null)) return apply();
+  return withGitHeadGuard(
+    worktreeRoot,
+    changes,
+    testHooks,
+    apply,
+  );
+}
+
+async function branchReceiptCrossed(worktreeRoot, operation, branch = null) {
+  try {
+    if (branch === null) {
+      const observed = await run(
+        'observe-branch-receipts',
+        worktreeRoot,
+        [
+          '-C', worktreeRoot,
+          'for-each-ref',
+          '--count=1',
+          '--format=%(refname)',
+          `${branchReceiptPrefix(operation)}/`,
+        ],
+        { journalResult: false },
+      );
+      return observed.trim() !== '';
+    }
+    await run(
+      'observe-branch-receipt',
+      worktreeRoot,
+      ['-C', worktreeRoot, 'rev-parse', '--verify', branchReceiptRef(operation, branch)],
+      { journalResult: false },
+    );
+    return true;
+  } catch (error) {
+    if (error instanceof TransitionError) return false;
+    throw error;
+  }
+}
+
+async function releaseBranchReceipt(worktreeRoot, operation) {
+  const observed = await run(
+    'observe-branch-receipts',
+    worktreeRoot,
+    [
+      '-C', worktreeRoot,
+      'for-each-ref',
+      '--format=%(refname)',
+      `${branchReceiptPrefix(operation)}/`,
+    ],
+    { journalResult: false },
+  );
+  for (const ref of observed.trim().split('\n').filter(Boolean)) {
+    await run('release-branch-receipt', worktreeRoot, [
+      '-C', worktreeRoot, 'update-ref', '-d', ref,
+    ]);
+  }
 }
 
 /**
- * Apply only the index change the reducer computed. Git locks the index and
- * verifies the patch's preimage, so a concurrent commit is serialized instead
- * of being replaced by an old whole-index snapshot.
+ * Apply only the index change the reducer computed. The current exact index
+ * bytes must first derive the reducer's sealed source tree. The patch must
+ * then derive the named target tree before Git's index lock may replace those
+ * exact bytes. A concurrent staged change therefore stops the movement
+ * instead of becoming a new expected-old value.
  */
-async function applyIndexPatch(worktreeRoot, patch) {
+async function applyIndexPatch(
+  worktreeRoot,
+  patch,
+  operation,
+  { expectedTree, targetTree } = {},
+) {
   if (!patch) return;
+  if (!/^[0-9a-f]{64}$/.test(operation || '')) {
+    throw new Error('index movement has no durable operation identity');
+  }
+  if (
+    !/^[0-9a-f]{40,64}$/.test(expectedTree || '')
+    || !/^[0-9a-f]{40,64}$/.test(targetTree || '')
+  ) {
+    throw new Error('index movement has no sealed tree endpoints');
+  }
   const stateDir = path.join(AMALGM_DIR, 'state');
   fs.mkdirSync(stateDir, { recursive: true });
   const dir = fs.mkdtempSync(path.join(stateDir, 'index-patch-'));
   const patchFile = path.join(dir, 'patch');
+  const scratchIndex = path.join(dir, 'index');
+  const index = gitPath(worktreeRoot, 'index');
   try {
     fs.writeFileSync(patchFile, patch);
+    const expected = fs.existsSync(index) ? fs.readFileSync(index) : null;
+    if (expected === null) {
+      await run(
+        'prepare-empty-index',
+        worktreeRoot,
+        ['-C', worktreeRoot, 'read-tree', '--empty'],
+        { env: { GIT_INDEX_FILE: scratchIndex } },
+      );
+    } else {
+      fs.writeFileSync(scratchIndex, expected);
+    }
+    const observedTree = (await run(
+      'verify-index-patch-source',
+      worktreeRoot,
+      ['-C', worktreeRoot, 'write-tree'],
+      {
+        env: { GIT_INDEX_FILE: scratchIndex },
+        journalResult: false,
+      },
+    )).trim();
+    if (observedTree !== expectedTree) {
+      throw new TransitionError(
+        'apply-index-patch',
+        worktreeRoot,
+        `local index changed from sealed tree ${expectedTree} to ${observedTree}`,
+      );
+    }
     await run('apply-index-patch', worktreeRoot, [
       '-C', worktreeRoot, 'apply', '--cached', '--whitespace=nowarn', patchFile,
-    ]);
+    ], { env: { GIT_INDEX_FILE: scratchIndex } });
+    const appliedTree = (await run(
+      'verify-index-patch-target',
+      worktreeRoot,
+      ['-C', worktreeRoot, 'write-tree'],
+      {
+        env: { GIT_INDEX_FILE: scratchIndex },
+        journalResult: false,
+      },
+    )).trim();
+    if (appliedTree !== targetTree) {
+      throw new Error(
+        `index patch target mismatch: expected ${targetTree}, derived ${appliedTree}`,
+      );
+    }
+    applyGitMetadataTransaction(
+      worktreeRoot,
+      'index',
+      expected,
+      fs.readFileSync(scratchIndex),
+      operation,
+    );
   } finally {
     fs.rmSync(dir, { recursive: true, force: true });
   }
 }
 
-/** Set only Git's index; working files are left exactly as they are. */
-function setIndexTree(worktreeRoot, treeOid) {
-  return run('set-index-tree', worktreeRoot, [
-    '-C', worktreeRoot, 'read-tree', treeOid,
-  ]);
-}
-
 /**
  * Apply one ordered file write set to a working tree. Each entry is
  * { path, content, mode } (content a
@@ -349,58 +677,1267 @@ function setIndexTree(worktreeRoot, treeOid) {
  * as one journal line.
  */
 function applyFiles(worktreeRoot, writes, label) {
-  const root = path.resolve(worktreeRoot);
+  const root = fs.realpathSync(worktreeRoot);
+  const operation = typeof label === 'string' && label
+    ? label
+    : `anonymous-${crypto.randomBytes(32).toString('hex')}`;
   const written = [];
   const removed = [];
   try {
+    ensureFileTransactionExcluded(root);
+    recoverFileTransactions(root);
     for (const write of writes) {
-      const abs = path.resolve(root, write.path);
-      if (abs !== root && !abs.startsWith(root + path.sep)) {
-        throw new Error(`unsafe path: ${write.path}`);
-      }
-      if (write.content === null) {
-        fs.rmSync(abs, { force: true });
-        removed.push(write.path);
-        continue;
-      }
-      fs.mkdirSync(path.dirname(abs), { recursive: true });
-      if (write.mode === '120000') {
-        fs.rmSync(abs, { force: true });
-        fs.symlinkSync(write.content.toString('utf8'), abs);
-      } else {
-        fs.writeFileSync(abs, write.content);
-        fs.chmodSync(abs, write.mode === '100755' ? 0o755 : 0o644);
-      }
-      written.push(write.path);
+      applyFileTransaction(root, write, operation);
+      if (write.content === null) removed.push(write.path);
+      else written.push(write.path);
     }
-    journal({ action: 'apply-files', worktree: root, label, written, removed, ok: true });
+    journal({ action: 'apply-files', worktree: root, operation, written, removed, ok: true });
+    return { operation };
   } catch (error) {
     journal({
-      action: 'apply-files', worktree: root, label, written, removed, ok: false,
+      action: 'apply-files', worktree: root, operation, written, removed, ok: false,
       error: String(error.message).slice(0, 500),
     });
     throw new TransitionError('apply-files', root, String(error.message));
   }
 }
 
+function gitDirectory(worktreeRoot) {
+  const marker = path.join(worktreeRoot, '.git');
+  if (fs.statSync(marker).isDirectory()) return marker;
+  const match = fs.readFileSync(marker, 'utf8').trim().match(/^gitdir:\s*(.+)$/);
+  if (!match) throw new Error('worktree has no Git directory');
+  return path.resolve(worktreeRoot, match[1]);
+}
+
+function gitPath(worktreeRoot, relativePath) {
+  const value = execFileSync(
+    'git',
+    ['-C', worktreeRoot, 'rev-parse', '--git-path', relativePath],
+    {
+      cwd: worktreeRoot,
+      env: { ...process.env, ...TRANSITION_ENV },
+      encoding: 'utf8',
+      timeout: 120_000,
+      maxBuffer: 32 * 1024 * 1024,
+    },
+  ).trim();
+  return path.isAbsolute(value) ? value : path.resolve(worktreeRoot, value);
+}
+
+function fileTransactionDirectory(worktreeRoot) {
+  return path.join(gitDirectory(worktreeRoot), 'amalgm-apply');
+}
+
+/**
+ * Receipts live beside their destination so the kernel can consume prepared
+ * targets atomically even when a linked worktree's Git directory is on
+ * another device. They are implementation state, never workspace content.
+ */
+function isApplyReceiptPath(relativePath) {
+  return String(relativePath)
+    .split(/[\\/]/)
+    .some((component) => APPLY_RECEIPT_DIRECTORY.test(component));
+}
+
+function ensureFileTransactionExcluded(worktreeRoot) {
+  // Linked worktrees have a private Git directory, but Git reads exclusions
+  // from the common path named by `--git-path`. The command is the authority;
+  // reconstructing this path from `.git` makes receipt bytes look user-owned.
+  const exclude = gitPath(worktreeRoot, 'info/exclude');
+  let content = '';
+  let mode = 0o644;
+  try {
+    content = fs.readFileSync(exclude, 'utf8');
+    mode = fs.statSync(exclude).mode & 0o777;
+  } catch (error) {
+    if (error?.code !== 'ENOENT') throw error;
+  }
+  if (content.split(/\r?\n/).includes(APPLY_RECEIPT_EXCLUDE)) return;
+  fs.mkdirSync(path.dirname(exclude), { recursive: true });
+  // Append instead of replacing a read snapshot: a concurrent user edit to
+  // info/exclude must survive. A racing apply may append the same harmless
+  // rule twice, while every later call observes it and stops.
+  const descriptor = fs.openSync(exclude, 'a', mode);
+  try {
+    fs.writeFileSync(descriptor, `\n${APPLY_RECEIPT_EXCLUDE}\n`);
+    fs.fsyncSync(descriptor);
+  } finally {
+    fs.closeSync(descriptor);
+  }
+  syncDirectory(path.dirname(exclude));
+}
+
+function ensureDurableDirectory(directory) {
+  try {
+    fs.mkdirSync(directory);
+    syncDirectory(path.dirname(directory));
+  } catch (error) {
+    if (error?.code !== 'EEXIST') throw error;
+    if (!fs.statSync(directory).isDirectory()) {
+      throw new Error(`workspace transaction path is not a directory: ${directory}`);
+    }
+  }
+}
+
+function confinedPath(worktreeRoot, relativePath) {
+  if (
+    typeof relativePath !== 'string'
+    || !relativePath
+    || path.isAbsolute(relativePath)
+    || relativePath.split(/[\\/]/).includes('..')
+  ) throw new Error(`unsafe path: ${relativePath}`);
+  const root = fs.realpathSync(worktreeRoot);
+  const absolute = path.resolve(root, relativePath);
+  if (!absolute.startsWith(root + path.sep)) throw new Error(`unsafe path: ${relativePath}`);
+  let current = root;
+  for (const component of relativePath.split(/[\\/]/).slice(0, -1)) {
+    if (!component || component === '.') continue;
+    current = path.join(current, component);
+    let stat;
+    try {
+      stat = fs.lstatSync(current);
+    } catch (error) {
+      if (error?.code === 'ENOENT') break;
+      throw error;
+    }
+    if (stat.isSymbolicLink()) {
+      throw new Error(`unsafe symlink parent: ${relativePath}`);
+    }
+    if (!stat.isDirectory()) throw new Error(`unsafe non-directory parent: ${relativePath}`);
+  }
+  return absolute;
+}
+
+function fileStateIdentity(state) {
+  if (state === null) return null;
+  if (state?.kind === 'other') return { kind: 'other' };
+  if (!Buffer.isBuffer(state?.content)) throw new Error('file state has no exact bytes');
+  return {
+    kind: state.kind,
+    exec: state.exec === true,
+    bytes: state.content.length,
+    sha256: crypto.createHash('sha256').update(state.content).digest('hex'),
+  };
+}
+
+function transactionPaths(worktreeRoot, operation, relativePath, rootStat) {
+  const recordDirectory = fileTransactionDirectory(worktreeRoot);
+  ensureDurableDirectory(recordDirectory);
+  const id = crypto.createHash('sha256')
+    .update(
+      `${FILE_TRANSACTION_CONTRACT}\0${rootStat.dev}\0${rootStat.ino}`
+      + `\0${operation}\0${relativePath}`,
+    )
+    .digest('hex');
+  return {
+    id,
+    recordDirectory,
+    record: path.join(recordDirectory, `${id}.json`),
+  };
+}
+
+function removeTransactionRecord(record) {
+  try {
+    fs.unlinkSync(record);
+  } catch (error) {
+    if (error?.code !== 'ENOENT') throw error;
+  }
+  syncDirectory(path.dirname(record));
+}
+
+function readFileTransaction(record) {
+  try {
+    const value = JSON.parse(fs.readFileSync(record, 'utf8'));
+    if (
+      value?.contract !== FILE_TRANSACTION_CONTRACT
+      || typeof value.root !== 'string'
+      || !/^\d+$/.test(value.rootDev)
+      || !/^\d+$/.test(value.rootIno)
+      || typeof value.path !== 'string'
+      || typeof value.id !== 'string'
+      || typeof value.operation !== 'string'
+      || !value.operation
+      || value.id !== path.basename(record, '.json')
+      || !/^[a-f0-9]{64}$/.test(value.id)
+      || (value.expected !== null && typeof value.expected !== 'object')
+      || (value.target !== null && typeof value.target !== 'object')
+    ) throw new Error('invalid file transaction');
+    return { ...value, record };
+  } catch (error) {
+    throw new Error(`invalid workspace file transaction ${record}: ${error.message}`);
+  }
+}
+
+function runNativeFileTransaction(transaction, action, content = null, testHooks = {}) {
+  try {
+    return nativeFileTransaction.run(transaction, action, content, testHooks);
+  } catch (error) {
+    throw new Error(
+      String(error?.message || error).replace(
+        /^native file transaction/,
+        'native workspace file transaction',
+      ),
+    );
+  }
+}
+
+function fileTransactionRecords(worktreeRoot, operation = null) {
+  const directory = fileTransactionDirectory(worktreeRoot);
+  if (!fs.existsSync(directory)) return [];
+  return fs.readdirSync(directory)
+    .filter((name) => name.endsWith('.json'))
+    .sort()
+    .map((name) => readFileTransaction(path.join(directory, name)))
+    .filter((transaction) => operation === null || transaction.operation === operation);
+}
+
+/**
+ * Resolve an interrupted expected-source → official-target file movement
+ * before any new repo observation. The retained source is either the exact
+ * expected floor (safe to finish/rollback) or a third value (a local save
+ * that is restored without overwriting anything newer).
+ */
+function recoverFileTransactions(worktreeRoot) {
+  const root = fs.realpathSync(worktreeRoot);
+  ensureFileTransactionExcluded(root);
+  for (const transaction of fileTransactionRecords(root)) {
+    if (transaction.root !== root) {
+      throw new Error(`workspace file transaction escaped its repository: ${transaction.record}`);
+    }
+    const result = runNativeFileTransaction(transaction, 'recover');
+    if (result.status === 'pending') {
+      throw new Error(
+        `workspace file transaction is waiting for local writer ownership: `
+        + `${transaction.path}: ${result.reason || 'pending'}`,
+      );
+    }
+    // A crossed operation is evidence until the verified cursor passes it.
+    // Only a transaction proven not to have crossed can retire here.
+    if (result.status === 'changed') removeTransactionRecord(transaction.record);
+  }
+}
+
+function sameTransaction(left, right) {
+  return (
+    left.contract === right.contract
+    && left.root === right.root
+    && left.rootDev === right.rootDev
+    && left.rootIno === right.rootIno
+    && left.path === right.path
+    && left.id === right.id
+    && left.operation === right.operation
+    && JSON.stringify(left.expected) === JSON.stringify(right.expected)
+    && JSON.stringify(left.target) === JSON.stringify(right.target)
+  );
+}
+
+function applyFileTransaction(worktreeRoot, write, operation) {
+  if (typeof operation !== 'string' || !operation || operation.length > 1024) {
+    throw new Error('workspace file transaction has no operation identity');
+  }
+  const rootStat = fs.statSync(worktreeRoot, { bigint: true });
+  const paths = transactionPaths(worktreeRoot, operation, write.path, rootStat);
+  const target = write.content === null
+    ? null
+    : {
+      ...fileStateIdentity({
+        kind: write.mode === '120000' ? 'symlink' : 'file',
+        content: write.content,
+        exec: write.mode === '100755',
+      }),
+    };
+  const transaction = {
+    contract: FILE_TRANSACTION_CONTRACT,
+    root: worktreeRoot,
+    rootDev: rootStat.dev.toString(),
+    rootIno: rootStat.ino.toString(),
+    path: write.path,
+    id: paths.id,
+    operation,
+    expected: fileStateIdentity(write.expected),
+    target,
+  };
+  if (fs.existsSync(paths.record)) {
+    const retained = readFileTransaction(paths.record);
+    if (!sameTransaction(retained, transaction)) {
+      throw new Error(`workspace file transaction identity changed: ${write.path}`);
+    }
+    const recovered = runNativeFileTransaction(retained, 'recover');
+    if (recovered.status === 'applied') return;
+    if (recovered.status === 'pending') {
+      throw new Error(
+        `local writer ownership is unresolved: ${write.path}: `
+        + `${recovered.reason || 'pending'}`,
+      );
+    }
+    removeTransactionRecord(paths.record);
+  }
+  durable.writeJson(paths.record, transaction);
+  const result = runNativeFileTransaction(
+    transaction,
+    'apply',
+    write.content,
+    {
+      pauseAfterParentOpen: Number(write.testPauseAfterParentOpenMillis || 0),
+      pauseAfterExtraction: Number(write.testPauseAfterExtractionMillis || 0),
+      pauseBeforeInstall: Number(write.testPauseBeforeInstallMillis || 0),
+      crashAfterExtraction: write.testCrashAfterExtraction === true,
+      crashBeforeInstall: write.testCrashBeforeInstall === true,
+    },
+  );
+  if (result.status === 'pending') {
+    throw new Error(
+      `local writer ownership is unresolved: ${write.path}: ${result.reason || 'pending'}`,
+    );
+  }
+  if (result.status === 'changed') {
+    removeTransactionRecord(paths.record);
+    throw new Error(`local file changed before ordered apply: ${write.path}`);
+  }
+}
+
+/**
+ * The transaction artifact, not ambient file metadata, says whether an
+ * operation crossed. A later local write may return the pathname to either
+ * endpoint without changing this answer.
+ */
+function crossedFileReceiptPaths(worktreeRoot, operation, relativePaths) {
+  const root = fs.realpathSync(worktreeRoot);
+  const requested = new Set(relativePaths);
+  const crossed = new Set();
+  recoverFileTransactions(root);
+  for (const transaction of fileTransactionRecords(root, operation)) {
+    if (!requested.has(transaction.path)) continue;
+    const result = runNativeFileTransaction(transaction, 'receipt');
+    if (result.status === 'crossed') crossed.add(transaction.path);
+    else if (result.status !== 'not-crossed') {
+      throw new Error(
+        `workspace file receipt is unresolved: ${transaction.path}: `
+        + `${result.reason || result.status}`,
+      );
+    }
+  }
+  return crossed;
+}
+
+/**
+ * Receipt retirement is safe only after the caller's verified cursor is
+ * durable. Repeating release after any crash is harmless.
+ */
+function releaseFileReceipts(worktreeRoot, operation) {
+  const root = fs.realpathSync(worktreeRoot);
+  for (const transaction of fileTransactionRecords(root, operation)) {
+    const result = runNativeFileTransaction(transaction, 'release');
+    if (result.status === 'pending') {
+      throw new Error(
+        `workspace file receipt cannot be released: ${transaction.path}: `
+        + `${result.reason || 'pending'}`,
+      );
+    }
+    if (result.status !== 'released') {
+      throw new Error(
+        `workspace file receipt release failed: ${transaction.path}: ${result.status}`,
+      );
+    }
+    removeTransactionRecord(transaction.record);
+  }
+}
+
+function gitMetadataTransactionDirectoryForRoot(root) {
+  return path.join(fs.realpathSync(root), 'amalgm-metadata-apply');
+}
+
+function gitMetadataTransactionDirectory(worktreeRoot) {
+  return gitMetadataTransactionDirectoryForRoot(gitDirectory(worktreeRoot));
+}
+
+async function listedWorktreeHeads(worktreeRoot) {
+  const output = await run(
+    'observe-worktree-heads',
+    worktreeRoot,
+    ['-C', worktreeRoot, 'worktree', 'list', '--porcelain', '-z'],
+    { journalResult: false },
+  );
+  const entries = [];
+  let current = null;
+  for (const token of output.split('\0')) {
+    if (!token) {
+      if (current?.path) entries.push(current);
+      current = null;
+    } else if (token.startsWith('worktree ')) {
+      current = { path: token.slice('worktree '.length), branch: null };
+    } else if (current && token.startsWith('branch refs/heads/')) {
+      current.branch = token.slice('branch refs/heads/'.length);
+    }
+  }
+  if (current?.path) entries.push(current);
+  return entries;
+}
+
+async function withOneGitHeadGuard(
+  gitRoot,
+  label,
+  changes,
+  guarded,
+) {
+  const root = fs.realpathSync(gitRoot);
+  recoverGitMetadataTransactionsAtRoot(root, label);
+  const head = path.join(root, 'HEAD');
+  const expected = fs.readFileSync(head);
+  const attached = expected.toString('utf8').match(/^ref: refs\/heads\/(.+)\n$/)?.[1] || null;
+  const deleted = new Set(
+    changes.filter((change) => change.oid === null).map((change) => change.branch),
+  );
+  if (attached && deleted.has(attached)) {
+    throw new TransitionError(
+      'guard-branch-delete',
+      label,
+      `HEAD is attached to branch ${attached}`,
+    );
+  }
+  // A logical branch operation may be attempted concurrently. Its transient
+  // guard artifacts must still have exactly one process owner.
+  const guardOperation = crypto.randomBytes(32).toString('hex');
+  const rootStat = fs.statSync(root, { bigint: true });
+  const paths = gitMetadataTransactionPathsForRoot(
+    root,
+    guardOperation,
+    'HEAD',
+    rootStat,
+  );
+  const identity = gitMetadataIdentity(expected);
+  const transaction = {
+    contract: GIT_METADATA_TRANSACTION_CONTRACT,
+    backend: 'git-guard',
+    root,
+    rootDev: rootStat.dev.toString(),
+    rootIno: rootStat.ino.toString(),
+    path: 'HEAD',
+    id: paths.id,
+    operation: guardOperation,
+    ownerPid: process.pid,
+    ownerStarted: PROCESS_START_IDENTITY,
+    expected: identity,
+    target: identity,
+    record: paths.record,
+    prepared: paths.target,
+    claimed: paths.claimed,
+  };
+
+  if (fs.existsSync(paths.record)) {
+    const retained = readGitMetadataTransaction(paths.record);
+    if (!sameGitMetadataTransaction(retained, transaction)) {
+      throw new Error('Git HEAD guard identity changed');
+    }
+    if (guardOwnerIsActive(retained)) {
+      throw new TransitionError(
+        'recover-head-guard',
+        label,
+        `guard owner ${retained.ownerPid} is still active`,
+      );
+    }
+    const recovered = runNativeFileTransaction(retained, 'recover');
+    if (recovered.status !== 'released') {
+      throw new TransitionError(
+        'recover-head-guard',
+        label,
+        recovered.reason || recovered.status,
+      );
+    }
+    removeGitMetadataTransaction(retained);
+  }
+
+  durable.writeJson(paths.record, {
+    contract: transaction.contract,
+    backend: transaction.backend,
+    root: transaction.root,
+    rootDev: transaction.rootDev,
+    rootIno: transaction.rootIno,
+    path: transaction.path,
+    id: transaction.id,
+    operation: transaction.operation,
+    ownerPid: transaction.ownerPid,
+    ownerStarted: transaction.ownerStarted,
+    expected: transaction.expected,
+    target: transaction.target,
+  });
+  durable.writeFile(paths.target, expected, 0o644);
+  const claimed = runNativeFileTransaction(transaction, 'guard');
+  if (claimed.status !== 'guarded') {
+    removeGitMetadataTransaction(transaction);
+    throw new TransitionError(
+      'guard-branch-delete',
+      label,
+      claimed.reason || claimed.status,
+    );
+  }
+  try {
+    return await guarded();
+  } finally {
+    const released = runNativeFileTransaction(transaction, 'unguard');
+    if (released.status !== 'released') {
+      throw new Error(`Git HEAD guard release failed: ${released.reason || released.status}`);
+    }
+    removeGitMetadataTransaction(transaction);
+  }
+}
+
+function gitWorktreeNamespaceTransactionDirectory() {
+  return path.join(AMALGM_DIR, 'state', 'workspace-git-worktree-guards');
+}
+
+function physicalDirectoryIdentity(directory) {
+  const realpath = fs.realpathSync(directory);
+  const stat = fs.statSync(realpath, { bigint: true });
+  if (!stat.isDirectory()) {
+    throw new Error(`physical directory identity is not a directory: ${realpath}`);
+  }
+  return {
+    realpath,
+    dev: stat.dev.toString(),
+    ino: stat.ino.toString(),
+  };
+}
+
+function pinPhysicalDirectory(directory) {
+  const realpath = fs.realpathSync(directory);
+  const fd = fs.openSync(
+    realpath,
+    fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | fs.constants.O_DIRECTORY,
+  );
+  try {
+    const stat = fs.fstatSync(fd, { bigint: true });
+    if (!stat.isDirectory()) {
+      throw new Error(`physical directory pin is not a directory: ${realpath}`);
+    }
+    return {
+      fd,
+      realpath,
+      dev: stat.dev.toString(),
+      ino: stat.ino.toString(),
+    };
+  } catch (error) {
+    fs.closeSync(fd);
+    throw error;
+  }
+}
+
+function closePhysicalDirectoryPins(pins) {
+  for (const pin of [...pins].reverse()) fs.closeSync(pin.fd);
+}
+
+function samePhysicalDirectory(left, right) {
+  return (
+    left !== null
+    && right !== null
+    && left.dev === right.dev
+    && left.ino === right.ino
+  );
+}
+
+function gitCommonDirectory(worktreeRoot) {
+  const value = execFileSync(
+    'git',
+    ['-C', worktreeRoot, 'rev-parse', '--git-common-dir'],
+    {
+      cwd: worktreeRoot,
+      env: { ...process.env, ...TRANSITION_ENV },
+      encoding: 'utf8',
+      timeout: 120_000,
+      maxBuffer: 32 * 1024 * 1024,
+    },
+  ).trim();
+  return fs.realpathSync(path.isAbsolute(value) ? value : path.resolve(worktreeRoot, value));
+}
+
+function gitCommonDirectoryFromMarker(worktreeRoot) {
+  const root = fs.realpathSync(worktreeRoot);
+  const marker = path.join(root, '.git');
+  if (fs.statSync(marker).isDirectory()) return fs.realpathSync(marker);
+  const match = fs.readFileSync(marker, 'utf8').trim().match(/^gitdir:\s*(.+)$/);
+  if (!match) throw new Error('worktree has no Git directory');
+  const privateDirectory = path.resolve(root, match[1]);
+  const registrations = path.dirname(privateDirectory);
+  return fs.realpathSync(
+    path.basename(registrations) === 'worktrees'
+      ? path.dirname(registrations)
+      : privateDirectory,
+  );
+}
+
+function physicalGitWorktreeRegistrations(directory) {
+  return fs.readdirSync(directory)
+    .sort()
+    .map((name) => {
+      const stat = fs.lstatSync(path.join(directory, name), { bigint: true });
+      if (!stat.isDirectory()) {
+        throw new Error(`Git worktree registration is not a directory: ${name}`);
+      }
+      return {
+        name,
+        dev: stat.dev.toString(),
+        ino: stat.ino.toString(),
+      };
+    });
+}
+
+function ensureGitWorktreeNamespace(commonRoot) {
+  const directory = path.join(commonRoot, 'worktrees');
+  try {
+    fs.statSync(directory);
+  } catch (error) {
+    if (error?.code !== 'ENOENT') throw error;
+    fs.mkdirSync(directory, { mode: 0o755 });
+    syncDirectory(commonRoot);
+  }
+  return directory;
+}
+
+function pinGitWorktreeNamespace(commonRoot) {
+  const directory = ensureGitWorktreeNamespace(commonRoot);
+  const pins = [];
+  try {
+    const namespace = pinPhysicalDirectory(directory);
+    pins.push(namespace);
+    const entries = fs.readdirSync(directory)
+      .sort()
+      .map((name) => {
+        const pin = pinPhysicalDirectory(path.join(directory, name));
+        pins.push(pin);
+        return { name, dev: pin.dev, ino: pin.ino };
+      });
+    return { namespace, entries, pins };
+  } catch (error) {
+    closePhysicalDirectoryPins(pins);
+    throw error;
+  }
+}
+
+function gitWorktreeNamespacePaths(commonRoot, operation, rootStat) {
+  const receiptDirectory = path.join(commonRoot, 'amalgm-metadata-apply');
+  const recordDirectory = gitWorktreeNamespaceTransactionDirectory();
+  ensureDurableDirectory(receiptDirectory);
+  ensureDurableDirectory(AMALGM_DIR);
+  ensureDurableDirectory(path.join(AMALGM_DIR, 'state'));
+  ensureDurableDirectory(recordDirectory);
+  const id = crypto.createHash('sha256')
+    .update(
+      `${GIT_WORKTREE_NAMESPACE_GUARD_CONTRACT}\0${rootStat.dev}\0${rootStat.ino}`
+      + `\0${operation}\0worktrees`,
+    )
+    .digest('hex');
+  return {
+    id,
+    record: path.join(recordDirectory, `${id}.json`),
+    target: path.join(receiptDirectory, `${id}.target`),
+    claimed: path.join(receiptDirectory, `${id}.claimed`),
+  };
+}
+
+function readGitWorktreeNamespaceTransaction(record) {
+  try {
+    const value = JSON.parse(fs.readFileSync(record, 'utf8'));
+    if (
+      value?.contract !== GIT_WORKTREE_NAMESPACE_GUARD_CONTRACT
+      || value.backend !== 'git-worktree-guard'
+      || typeof value.worktree !== 'string'
+      || !path.isAbsolute(value.worktree)
+      || !/^\d+$/.test(value.worktreeDev)
+      || !/^\d+$/.test(value.worktreeIno)
+      || typeof value.root !== 'string'
+      || !path.isAbsolute(value.root)
+      || !/^\d+$/.test(value.rootDev)
+      || !/^\d+$/.test(value.rootIno)
+      || value.path !== 'worktrees'
+      || value.id !== path.basename(record, '.json')
+      || !/^[a-f0-9]{64}$/.test(value.id || '')
+      || !/^[a-f0-9]{64}$/.test(value.operation || '')
+      || !Number.isSafeInteger(value.ownerPid)
+      || value.ownerPid < 1
+      || typeof value.ownerStarted !== 'string'
+      || !value.ownerStarted
+      || value.expected?.kind !== 'directory'
+      || !/^\d+$/.test(value.expected?.dev || '')
+      || !/^\d+$/.test(value.expected?.ino || '')
+      || value.target?.kind !== 'file'
+      || !Array.isArray(value.entries)
+      || value.entries.some((entry) => (
+        entry === null
+        || typeof entry !== 'object'
+        || typeof entry.name !== 'string'
+        || !entry.name
+        || entry.name === '.'
+        || entry.name === '..'
+        || entry.name.includes('/')
+        || entry.name.includes('\\')
+        || !/^\d+$/.test(entry.dev || '')
+        || !/^\d+$/.test(entry.ino || '')
+      ))
+    ) throw new Error('invalid Git worktree namespace transaction');
+    return {
+      ...value,
+      record,
+      prepared: path.join(value.root, 'amalgm-metadata-apply', `${value.id}.target`),
+      claimed: path.join(value.root, 'amalgm-metadata-apply', `${value.id}.claimed`),
+    };
+  } catch (error) {
+    throw new Error(
+      `invalid workspace Git worktree namespace transaction ${record}: ${error.message}`,
+    );
+  }
+}
+
+function gitWorktreeNamespaceTransactionRecords(worktreeRoot) {
+  const directory = gitWorktreeNamespaceTransactionDirectory();
+  if (!fs.existsSync(directory)) return [];
+  const requested = physicalDirectoryIdentity(worktreeRoot);
+  let common = null;
+  try {
+    common = physicalDirectoryIdentity(gitCommonDirectoryFromMarker(worktreeRoot));
+  } catch {
+    // A nonstandard Git layout may require Git's own common-dir resolution.
+    // That is available whenever the shared registration namespace is open.
+    try {
+      common = physicalDirectoryIdentity(gitCommonDirectory(worktreeRoot));
+    } catch {
+      // The checkout identity may still surface a record for diagnosis, but
+      // only a resolved matching common repository can authorize recovery.
+    }
+  }
+  return fs.readdirSync(directory)
+    .filter((name) => name.endsWith('.json'))
+    .sort()
+    .map((name) => readGitWorktreeNamespaceTransaction(path.join(directory, name)))
+    .map((transaction) => {
+      const worktreeMatches = samePhysicalDirectory(
+        { dev: transaction.worktreeDev, ino: transaction.worktreeIno },
+        requested,
+      );
+      const commonMatches = samePhysicalDirectory(
+        { dev: transaction.rootDev, ino: transaction.rootIno },
+        common,
+      );
+      if (!worktreeMatches && !commonMatches) return null;
+      if (!commonMatches) {
+        throw new Error(
+          `workspace Git worktree guard belongs to another common repository: `
+          + `${transaction.record}`,
+        );
+      }
+      return {
+        ...transaction,
+        root: common.realpath,
+        prepared: path.join(
+          common.realpath,
+          'amalgm-metadata-apply',
+          `${transaction.id}.target`,
+        ),
+        claimed: path.join(
+          common.realpath,
+          'amalgm-metadata-apply',
+          `${transaction.id}.claimed`,
+        ),
+      };
+    })
+    .filter(Boolean);
+}
+
+function removeGitWorktreeNamespaceTransaction(transaction) {
+  try {
+    fs.unlinkSync(transaction.record);
+  } catch (error) {
+    if (error?.code !== 'ENOENT') throw error;
+  }
+  if (fs.existsSync(path.dirname(transaction.record))) {
+    syncDirectory(path.dirname(transaction.record));
+  }
+}
+
+function recoverGitWorktreeNamespaceTransactions(worktreeRoot) {
+  for (const transaction of gitWorktreeNamespaceTransactionRecords(worktreeRoot)) {
+    if (guardOwnerIsActive(transaction)) {
+      throw new TransitionError(
+        'recover-git-worktree-guard',
+        transaction.worktree,
+        `guard owner ${transaction.ownerPid} is still active`,
+      );
+    }
+    const result = runNativeFileTransaction(transaction, 'recover');
+    if (result.status !== 'released') {
+      throw new TransitionError(
+        'recover-git-worktree-guard',
+        transaction.root,
+        result.reason || result.status,
+      );
+    }
+    removeGitWorktreeNamespaceTransaction(transaction);
+  }
+}
+
+function prepareGitWorktreeNamespaceGuard(worktreeRoot) {
+  recoverGitWorktreeNamespaceTransactions(worktreeRoot);
+  const worktree = physicalDirectoryIdentity(worktreeRoot);
+  const common = physicalDirectoryIdentity(gitCommonDirectory(worktree.realpath));
+  const root = common.realpath;
+  const pinned = pinGitWorktreeNamespace(root);
+  const guardOperation = crypto.randomBytes(32).toString('hex');
+  const paths = gitWorktreeNamespacePaths(root, guardOperation, {
+    dev: common.dev,
+    ino: common.ino,
+  });
+  const target = gitMetadataIdentity(Buffer.alloc(0));
+  return {
+    contract: GIT_WORKTREE_NAMESPACE_GUARD_CONTRACT,
+    backend: 'git-worktree-guard',
+    worktree: worktree.realpath,
+    worktreeDev: worktree.dev,
+    worktreeIno: worktree.ino,
+    root,
+    rootDev: common.dev,
+    rootIno: common.ino,
+    path: 'worktrees',
+    id: paths.id,
+    operation: guardOperation,
+    ownerPid: process.pid,
+    ownerStarted: PROCESS_START_IDENTITY,
+    expected: {
+      kind: 'directory',
+      dev: pinned.namespace.dev,
+      ino: pinned.namespace.ino,
+    },
+    target,
+    entries: pinned.entries,
+    pins: pinned.pins,
+    gitRoots: [
+      root,
+      ...pinned.pins.slice(1).map((pin) => pin.realpath),
+    ].sort(),
+    record: paths.record,
+    prepared: paths.target,
+    claimed: paths.claimed,
+  };
+}
+
+async function withGitWorktreeNamespaceGuard(transaction, testHooks, guarded) {
+  try {
+    durable.writeJson(transaction.record, {
+      contract: transaction.contract,
+      backend: transaction.backend,
+      worktree: transaction.worktree,
+      worktreeDev: transaction.worktreeDev,
+      worktreeIno: transaction.worktreeIno,
+      root: transaction.root,
+      rootDev: transaction.rootDev,
+      rootIno: transaction.rootIno,
+      path: transaction.path,
+      id: transaction.id,
+      operation: transaction.operation,
+      ownerPid: transaction.ownerPid,
+      ownerStarted: transaction.ownerStarted,
+      expected: transaction.expected,
+      target: transaction.target,
+      entries: transaction.entries,
+    });
+    durable.writeFile(transaction.prepared, Buffer.alloc(0), 0o644);
+    const result = runNativeFileTransaction(transaction, 'guard');
+    if (result.status !== 'guarded') {
+      throw new TransitionError(
+        'guard-git-worktree-namespace',
+        transaction.root,
+        result.reason || result.status,
+      );
+    }
+    const guardedEntries = physicalGitWorktreeRegistrations(transaction.prepared);
+    if (JSON.stringify(guardedEntries) !== JSON.stringify(transaction.entries)) {
+      throw new TransitionError(
+        'guard-git-worktree-namespace',
+        transaction.root,
+        'Git worktree registrations changed before namespace exclusion',
+      );
+    }
+    if (typeof testHooks.afterWorktreeNamespaceGuard === 'function') {
+      await testHooks.afterWorktreeNamespaceGuard();
+    }
+    return await guarded(transaction.root);
+  } finally {
+    const released = runNativeFileTransaction(transaction, 'unguard');
+    if (released.status !== 'released') {
+      throw new Error(
+        `Git worktree namespace guard release failed: ${released.reason || released.status}`,
+      );
+    }
+    removeGitWorktreeNamespaceTransaction(transaction);
+  }
+}
+
+async function withGitHeadGuard(
+  worktreeRoot,
+  changes,
+  testHooks,
+  guarded,
+) {
+  const namespace = prepareGitWorktreeNamespaceGuard(worktreeRoot);
+  try {
+    const acquire = (index) => (
+      index === namespace.gitRoots.length
+        ? (async () => {
+          if (typeof testHooks.afterHeadGuard === 'function') {
+            await testHooks.afterHeadGuard();
+          }
+          return withGitWorktreeNamespaceGuard(namespace, testHooks, guarded);
+        })()
+        : withOneGitHeadGuard(
+          namespace.gitRoots[index],
+          worktreeRoot,
+          changes,
+          () => acquire(index + 1),
+        )
+    );
+    return await acquire(0);
+  } finally {
+    closePhysicalDirectoryPins(namespace.pins);
+  }
+}
+
+function gitMetadataIdentity(content) {
+  if (content === null) return null;
+  if (!Buffer.isBuffer(content)) throw new Error('Git metadata has no exact bytes');
+  return {
+    kind: 'file',
+    exec: false,
+    bytes: content.length,
+    sha256: crypto.createHash('sha256').update(content).digest('hex'),
+  };
+}
+
+function gitMetadataTransactionPathsForRoot(root, operation, component, rootStat) {
+  if (!/^[0-9a-f]{64}$/.test(operation || '')) {
+    throw new Error('Git metadata transaction has no operation identity');
+  }
+  if (component !== 'index' && component !== 'HEAD') {
+    throw new Error(`unsupported Git metadata component: ${component}`);
+  }
+  const directory = gitMetadataTransactionDirectoryForRoot(root);
+  ensureDurableDirectory(directory);
+  const id = crypto.createHash('sha256')
+    .update(
+      `${GIT_METADATA_TRANSACTION_CONTRACT}\0${rootStat.dev}\0${rootStat.ino}`
+      + `\0${operation}\0${component}`,
+    )
+    .digest('hex');
+  return {
+    id,
+    directory,
+    record: path.join(directory, `${id}.json`),
+    target: path.join(directory, `${id}.target`),
+    claimed: path.join(directory, `${id}.claimed`),
+  };
+}
+
+function gitMetadataTransactionPaths(worktreeRoot, operation, component, rootStat) {
+  return gitMetadataTransactionPathsForRoot(
+    gitDirectory(worktreeRoot),
+    operation,
+    component,
+    rootStat,
+  );
+}
+
+function readGitMetadataTransaction(record) {
+  try {
+    const value = JSON.parse(fs.readFileSync(record, 'utf8'));
+    if (
+      value?.contract !== GIT_METADATA_TRANSACTION_CONTRACT
+      || (value.backend !== 'git-lock' && value.backend !== 'git-guard')
+      || typeof value.root !== 'string'
+      || !/^\d+$/.test(value.rootDev)
+      || !/^\d+$/.test(value.rootIno)
+      || (value.path !== 'index' && value.path !== 'HEAD')
+      || typeof value.id !== 'string'
+      || value.id !== path.basename(record, '.json')
+      || !/^[a-f0-9]{64}$/.test(value.id)
+      || !/^[a-f0-9]{64}$/.test(value.operation || '')
+      || (
+        value.backend === 'git-guard'
+        && (
+          !Number.isSafeInteger(value.ownerPid)
+          || value.ownerPid < 1
+          || typeof value.ownerStarted !== 'string'
+          || !value.ownerStarted
+        )
+      )
+      || (value.expected !== null && typeof value.expected !== 'object')
+      || typeof value.target !== 'object'
+    ) throw new Error('invalid Git metadata transaction');
+    return {
+      ...value,
+      record,
+      prepared: path.join(path.dirname(record), `${value.id}.target`),
+      claimed: path.join(path.dirname(record), `${value.id}.claimed`),
+    };
+  } catch (error) {
+    throw new Error(`invalid workspace Git metadata transaction ${record}: ${error.message}`);
+  }
+}
+
+function gitMetadataTransactionRecordsAtRoot(rootInput, operation = null, component = null) {
+  const root = physicalDirectoryIdentity(rootInput);
+  const directory = gitMetadataTransactionDirectoryForRoot(root.realpath);
+  if (!fs.existsSync(directory)) return [];
+  return fs.readdirSync(directory)
+    .filter((name) => name.endsWith('.json'))
+    .sort()
+    .map((name) => readGitMetadataTransaction(path.join(directory, name)))
+    .map((transaction) => {
+      if (!samePhysicalDirectory(
+        { dev: transaction.rootDev, ino: transaction.rootIno },
+        root,
+      )) {
+        throw new Error(`Git metadata transaction escaped its worktree: ${transaction.record}`);
+      }
+      return { ...transaction, root: root.realpath };
+    })
+    .filter((transaction) => operation === null || transaction.operation === operation)
+    .filter((transaction) => component === null || transaction.path === component);
+}
+
+function gitMetadataTransactionRecords(worktreeRoot, operation = null, component = null) {
+  return gitMetadataTransactionRecordsAtRoot(
+    gitDirectory(worktreeRoot),
+    operation,
+    component,
+  );
+}
+
+function sameGitMetadataTransaction(left, right) {
+  return (
+    left.contract === right.contract
+    && left.backend === right.backend
+    && left.rootDev === right.rootDev
+    && left.rootIno === right.rootIno
+    && left.path === right.path
+    && left.id === right.id
+    && left.operation === right.operation
+    && JSON.stringify(left.expected) === JSON.stringify(right.expected)
+    && JSON.stringify(left.target) === JSON.stringify(right.target)
+  );
+}
+
+function removeGitMetadataTransaction(transaction) {
+  for (const file of [transaction.record, transaction.prepared, transaction.claimed]) {
+    try {
+      fs.unlinkSync(file);
+    } catch (error) {
+      if (error?.code !== 'ENOENT') throw error;
+    }
+  }
+  if (fs.existsSync(path.dirname(transaction.record))) {
+    syncDirectory(path.dirname(transaction.record));
+  }
+}
+
+/**
+ * Apply one exact index or HEAD byte transition through Git's canonical lock.
+ * The prepared bytes stay in the per-worktree Git directory and are hard
+ * linked to index.lock/HEAD.lock by the native helper, so even very large
+ * indexes never travel through JSON.
+ */
+function applyGitMetadataTransaction(
+  worktreeRoot,
+  component,
+  expected,
+  target,
+  operation,
+  testHooks = {},
+) {
+  if (expected !== null && !Buffer.isBuffer(expected)) {
+    throw new Error('Git metadata expected value has no exact bytes');
+  }
+  if (!Buffer.isBuffer(target)) throw new Error('Git metadata target has no exact bytes');
+  const root = fs.realpathSync(gitDirectory(worktreeRoot));
+  const rootStat = fs.statSync(root, { bigint: true });
+  const paths = gitMetadataTransactionPaths(worktreeRoot, operation, component, rootStat);
+  const transaction = {
+    contract: GIT_METADATA_TRANSACTION_CONTRACT,
+    backend: 'git-lock',
+    root,
+    rootDev: rootStat.dev.toString(),
+    rootIno: rootStat.ino.toString(),
+    path: component,
+    id: paths.id,
+    operation,
+    expected: gitMetadataIdentity(expected),
+    target: gitMetadataIdentity(target),
+    record: paths.record,
+    prepared: paths.target,
+    claimed: paths.claimed,
+  };
+
+  if (fs.existsSync(paths.record)) {
+    const retained = readGitMetadataTransaction(paths.record);
+    if (!sameGitMetadataTransaction(retained, transaction)) {
+      throw new Error(`Git metadata transaction identity changed: ${component}`);
+    }
+    const recovered = runNativeFileTransaction(retained, 'recover');
+    if (recovered.status === 'applied') return;
+    if (recovered.status === 'pending') {
+      throw new TransitionError(
+        'apply-git-metadata',
+        worktreeRoot,
+        `${component}: ${recovered.reason || 'ownership is pending'}`,
+      );
+    }
+    removeGitMetadataTransaction(retained);
+  }
+
+  durable.writeJson(paths.record, {
+    contract: transaction.contract,
+    backend: transaction.backend,
+    root: transaction.root,
+    rootDev: transaction.rootDev,
+    rootIno: transaction.rootIno,
+    path: transaction.path,
+    id: transaction.id,
+    operation: transaction.operation,
+    expected: transaction.expected,
+    target: transaction.target,
+  });
+  durable.writeFile(paths.target, target, 0o644);
+  const result = runNativeFileTransaction(transaction, 'apply', null, {
+    crashBeforeInstall: testHooks.crashBeforeInstall === true,
+    crashAfterInstall: testHooks.crashAfterInstall === true,
+  });
+  if (result.status === 'pending') {
+    throw new TransitionError(
+      'apply-git-metadata',
+      worktreeRoot,
+      `${component}: ${result.reason || 'ownership is pending'}`,
+    );
+  }
+  if (result.status === 'changed') {
+    removeGitMetadataTransaction(transaction);
+    throw new TransitionError(
+      'apply-git-metadata',
+      worktreeRoot,
+      `${component} changed before ordered apply`,
+    );
+  }
+}
+
+function recoverGitMetadataTransactionsAtRoot(root, label) {
+  for (const transaction of gitMetadataTransactionRecordsAtRoot(root)) {
+    if (transaction.backend === 'git-guard' && guardOwnerIsActive(transaction)) {
+      throw new TransitionError(
+        'recover-git-head-guard',
+        label,
+        `guard owner ${transaction.ownerPid} is still active`,
+      );
+    }
+    const result = runNativeFileTransaction(transaction, 'recover');
+    if (transaction.backend === 'git-guard') {
+      if (result.status !== 'released') {
+        throw new TransitionError(
+          'recover-git-head-guard',
+          label,
+          result.reason || result.status,
+        );
+      }
+      removeGitMetadataTransaction(transaction);
+      continue;
+    }
+    if (result.status === 'pending') {
+      throw new TransitionError(
+        'recover-git-metadata',
+        label,
+        `${transaction.path}: ${result.reason || 'ownership is pending'}`,
+      );
+    }
+    if (result.status === 'changed') removeGitMetadataTransaction(transaction);
+  }
+}
+
+function gitHeadRoots(worktreeRoot) {
+  const common = gitCommonDirectoryFromMarker(worktreeRoot);
+  const registrations = path.join(common, 'worktrees');
+  let names = [];
+  try {
+    names = fs.readdirSync(registrations).sort();
+  } catch (error) {
+    if (error?.code !== 'ENOENT') throw error;
+  }
+  return [
+    common,
+    ...names.map((name) => path.join(registrations, name)),
+  ];
+}
+
+function recoverGitMetadataTransactions(worktreeRoot) {
+  recoverGitWorktreeNamespaceTransactions(worktreeRoot);
+  for (const root of gitHeadRoots(worktreeRoot)) {
+    try {
+      recoverGitMetadataTransactionsAtRoot(root, worktreeRoot);
+    } catch (error) {
+      if (error?.code === 'ENOENT') continue;
+      throw error;
+    }
+  }
+}
+
+function gitMetadataReceiptCrossed(worktreeRoot, operation, component) {
+  recoverGitMetadataTransactions(worktreeRoot);
+  const records = gitMetadataTransactionRecords(worktreeRoot, operation, component);
+  if (records.length > 1) {
+    throw new Error(`multiple Git metadata receipts exist for ${component}`);
+  }
+  if (records.length === 0) return false;
+  const result = runNativeFileTransaction(records[0], 'receipt');
+  if (result.status === 'crossed') return true;
+  if (result.status === 'not-crossed') return false;
+  throw new Error(
+    `Git metadata receipt is unresolved: ${component}: ${result.reason || result.status}`,
+  );
+}
+
+function releaseGitMetadataReceipts(worktreeRoot, operation, component = null) {
+  for (const transaction of gitMetadataTransactionRecords(worktreeRoot, operation, component)) {
+    const result = runNativeFileTransaction(transaction, 'release');
+    if (result.status === 'pending') {
+      throw new Error(
+        `Git metadata receipt cannot be released: ${transaction.path}: `
+        + `${result.reason || 'pending'}`,
+      );
+    }
+    if (result.status !== 'released') {
+      throw new Error(
+        `Git metadata receipt release failed: ${transaction.path}: ${result.status}`,
+      );
+    }
+    removeGitMetadataTransaction(transaction);
+  }
+}
+
 module.exports = {
   TransitionError,
+  applyGitMetadataTransaction,
   applyIndexPatch,
   applyFiles,
-  applyPatch,
-  checkoutInitialCard,
+  branchReceiptCrossed,
+  confinedPath,
   createBundle,
-  deleteBranchRef,
-  fastForwardTo,
-  fetchBranch,
-  forceMoveToCard,
-  holdInitialFiles,
+  emptyTree,
+  ensureEmptyIndex,
+  gitMetadataReceiptCrossed,
   importBundle,
+  initializeHeadToCard,
   initializeRepo,
-  moveToCard,
-  parkCommit,
-  pruneParkedCommits,
-  restoreInitialFiles,
-  setBranchRef,
-  setIndexTree,
+  isApplyReceiptPath,
+  moveHeadToCard,
+  crossedFileReceiptPaths,
+  recoverFileTransactions,
+  recoverGitMetadataTransactions,
+  releaseBranchReceipt,
+  releaseFileReceipts,
+  releaseGitMetadataReceipts,
+  updateBranchRefs,
 };