amalgm 0.1.245 → 0.1.246

package/runtime/scripts/amalgm-mcp/tests/repocard.storm.test.js

@@ -0,0 +1,284 @@
+'use strict';
+
+/**
+ * The repocard storm: seeded random sequences over the git alphabet —
+ * commits, branches, checkouts, merges (clean and conflicted), rebases,
+ * staging games, renames, deletions, binary edits, tags, detached HEAD —
+ * with a replica machine following via capture → apply after every round.
+ *
+ * Judged the same way as the observer storm:
+ *   1. apply() proves itself (ids re-derived from the replica must match).
+ *   2. An independent referee compares source and replica with git plumbing
+ *      only — refs, index blob hashes, status, and worktree bytes.
+ *   3. Busy states must be reported, never mis-captured.
+ *
+ * Seeded via AMALGM_STORM_SEED so any failure replays exactly.
+ */
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const { execFileSync } = require('child_process');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const { capture, apply } = require('../repocard');
+
+const SEED = Number(process.env.AMALGM_STORM_SEED || 20260729);
+
+const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'amalgm-repocard-storm-'));
+test.after(() => {
+  fs.rmSync(tempRoot, { recursive: true, force: true });
+});
+
+function mulberry32(seed) {
+  let a = seed >>> 0;
+  return () => {
+    a = (a + 0x6d2b79f5) >>> 0;
+    let t = a;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+function git(dir, ...args) {
+  return execFileSync('git', args, { cwd: dir, maxBuffer: 64 * 1024 * 1024, stdio: ['pipe', 'pipe', 'pipe'] }).toString('utf8').trim();
+}
+
+function tryGit(dir, ...args) {
+  try { return git(dir, ...args); } catch { return null; }
+}
+
+function assertReposIdentical(a, b, label) {
+  const sorted = (text) => text.split('\n').filter(Boolean).sort();
+  const headA = tryGit(a, 'symbolic-ref', '-q', 'HEAD');
+  const headB = tryGit(b, 'symbolic-ref', '-q', 'HEAD');
+  assert.equal(headA, headB, `${label}: HEAD ref`);
+  assert.equal(tryGit(a, 'rev-parse', '-q', '--verify', 'HEAD'), tryGit(b, 'rev-parse', '-q', '--verify', 'HEAD'), `${label}: HEAD commit`);
+  assert.deepEqual(
+    sorted(git(a, 'for-each-ref', '--format=%(refname) %(objectname)', 'refs/heads', 'refs/tags')),
+    sorted(git(b, 'for-each-ref', '--format=%(refname) %(objectname)', 'refs/heads', 'refs/tags')),
+    `${label}: refs`,
+  );
+  assert.deepEqual(sorted(git(a, 'ls-files', '-s')), sorted(git(b, 'ls-files', '-s')), `${label}: index`);
+  assert.deepEqual(
+    sorted(git(a, 'status', '--porcelain=v2', '--untracked-files=all')),
+    sorted(git(b, 'status', '--porcelain=v2', '--untracked-files=all')),
+    `${label}: status`,
+  );
+  const worktree = (dir) => {
+    const map = [];
+    const list = execFileSync('git', ['ls-files', '--cached', '--others', '--exclude-standard', '-z'], { cwd: dir })
+      .toString('utf8').split('\0').filter(Boolean);
+    for (const rel of list) {
+      const abs = path.join(dir, rel);
+      let stat;
+      try {
+        stat = fs.lstatSync(abs);
+      } catch {
+        map.push(`${rel}\tabsent`); // in the index, deleted from the worktree — a real state, compared like any other
+        continue;
+      }
+      map.push(`${rel}\t${stat.isSymbolicLink()
+        ? `link:${fs.readlinkSync(abs)}`
+        : `${stat.mode & 0o100 ? 'x' : '-'}:${fs.readFileSync(abs).toString('base64')}`}`);
+    }
+    return map.sort();
+  };
+  assert.deepEqual(worktree(a), worktree(b), `${label}: worktree bytes`);
+}
+
+test('storm: random git histories, a replica follows every round', () => {
+  const rng = mulberry32(SEED);
+  let stamp = 0;
+  const source = fs.realpathSync(fs.mkdtempSync(path.join(tempRoot, 'source-')));
+  git(source, 'init', '--quiet');
+  git(source, 'config', 'user.email', 'storm@amalgm.test');
+  git(source, 'config', 'user.name', 'Storm');
+  git(source, 'config', 'commit.gpgsign', 'false');
+  git(source, 'remote', 'add', 'origin', 'https://example.test/storm.git');
+
+  // A small set of core files makes merges and rebases collide often — the
+  // busy path is part of the alphabet, not an accident.
+  const CORE = ['a.md', 'b.md', 'c.md', 'bin.dat'];
+  for (const rel of CORE) fs.writeFileSync(path.join(source, rel), `seed ${rel}\n`);
+  git(source, 'add', '-A');
+  git(source, 'commit', '--quiet', '-m', 'seed');
+  const defaultBranch = git(source, 'symbolic-ref', '--short', 'HEAD');
+
+  const pick = (arr) => arr[Math.floor(rng() * arr.length)];
+  const tracked = () => git(source, 'ls-files').split('\n').filter(Boolean);
+  const branches = () => git(source, 'for-each-ref', '--format=%(refname:short)', 'refs/heads').split('\n').filter(Boolean);
+  const content = () => `edit ${(stamp++).toString(36)} ${'x'.repeat(Math.floor(rng() * 200))}\n`;
+
+  const ops = {
+    editTracked() {
+      const rel = pick(tracked());
+      if (rng() < 0.5) fs.writeFileSync(path.join(source, rel), content());
+      else fs.appendFileSync(path.join(source, rel), content());
+    },
+    binaryEdit() {
+      const bytes = Buffer.alloc(64 + Math.floor(rng() * 512));
+      for (let i = 0; i < bytes.length; i += 1) bytes[i] = Math.floor(rng() * 256);
+      fs.writeFileSync(path.join(source, 'bin.dat'), bytes);
+    },
+    newUntracked() {
+      fs.writeFileSync(path.join(source, `loose${(stamp++).toString(36)}.md`), content());
+    },
+    stageOne() {
+      const dirty = tryGit(source, 'diff', '--name-only');
+      const rel = pick((dirty || '').split('\n').filter(Boolean));
+      if (rel) git(source, 'add', rel);
+    },
+    stageAll() {
+      git(source, 'add', '-A');
+    },
+    unstageOne() {
+      const staged = tryGit(source, 'diff', '--cached', '--name-only');
+      const rel = pick((staged || '').split('\n').filter(Boolean));
+      if (rel) tryGit(source, 'restore', '--staged', rel);
+    },
+    commitAll() {
+      git(source, 'add', '-A');
+      tryGit(source, 'commit', '--quiet', '-m', `storm ${stamp++}`); // nothing to commit is fine
+    },
+    branchNew() {
+      git(source, 'checkout', '--quiet', '-b', `b${(stamp++).toString(36)}`);
+    },
+    checkoutOther() {
+      tryGit(source, 'checkout', '--quiet', pick(branches())); // may refuse over dirty work: fine
+    },
+    mergeOther() {
+      const target = pick(branches().filter((name) => name !== tryGit(source, 'symbolic-ref', '--short', '-q', 'HEAD')));
+      if (!target) return;
+      if (tryGit(source, 'merge', '--quiet', '--no-edit', target) === null) {
+        // Conflict (or dirty tree). If mid-merge, capture must say busy.
+        const snap = capture(source);
+        if (snap.busy) {
+          assert.equal(snap.busy, 'MERGE_HEAD');
+          git(source, 'add', '-A');
+          tryGit(source, 'commit', '--quiet', '--no-edit');
+        }
+      }
+    },
+    rebaseOther() {
+      const target = pick(branches());
+      if (tryGit(source, 'rebase', target) === null) {
+        const snap = capture(source);
+        if (snap.busy) {
+          assert.match(snap.busy, /^rebase/);
+          git(source, 'rebase', '--abort');
+        }
+      }
+    },
+    deleteTracked() {
+      const rel = pick(tracked().filter((name) => !CORE.includes(name)));
+      if (rel) tryGit(source, 'rm', '--quiet', '-f', rel);
+    },
+    renameTracked() {
+      const rel = pick(tracked().filter((name) => !CORE.includes(name)));
+      if (rel) tryGit(source, 'mv', rel, `moved${(stamp++).toString(36)}.md`);
+    },
+    tagNow() {
+      git(source, 'tag', `t${(stamp++).toString(36)}`);
+    },
+    detachToggle() {
+      if (tryGit(source, 'symbolic-ref', '-q', 'HEAD') === null) {
+        tryGit(source, 'checkout', '--quiet', defaultBranch);
+      } else {
+        tryGit(source, '-c', 'advice.detachedHead=false', 'checkout', '--quiet', '--detach', 'HEAD');
+      }
+    },
+    execToggle() {
+      const rel = pick(tracked().filter((name) => name.endsWith('.md')));
+      if (rel) fs.chmodSync(path.join(source, rel), rng() < 0.5 ? 0o755 : 0o644);
+    },
+  };
+
+  const table = [];
+  const weigh = (name, weight) => {
+    for (let i = 0; i < weight; i += 1) table.push(ops[name]);
+  };
+  weigh('editTracked', 18);
+  weigh('binaryEdit', 6);
+  weigh('newUntracked', 10);
+  weigh('stageOne', 8);
+  weigh('stageAll', 6);
+  weigh('unstageOne', 5);
+  weigh('commitAll', 12);
+  weigh('branchNew', 6);
+  weigh('checkoutOther', 8);
+  weigh('mergeOther', 6);
+  weigh('rebaseOther', 4);
+  weigh('deleteTracked', 5);
+  weigh('renameTracked', 5);
+  weigh('tagNow', 3);
+  weigh('detachToggle', 3);
+  weigh('execToggle', 4);
+
+  const replica = fs.realpathSync(fs.mkdtempSync(path.join(tempRoot, 'replica-')));
+  for (let round = 0; round < 30; round += 1) {
+    const opCount = 1 + Math.floor(rng() * 3);
+    for (let i = 0; i < opCount; i += 1) pick(table)();
+
+    let snap = capture(source);
+    if (snap.busy) {
+      // A round may end mid-operation; the resolution is the next event.
+      git(source, 'add', '-A');
+      tryGit(source, 'commit', '--quiet', '--no-edit');
+      snap = capture(source);
+    }
+    assert.ok(!snap.busy, `round ${round}: still busy after resolution (seed ${SEED})`);
+
+    apply(replica, snap); // incremental: same replica follows every round
+    assertReposIdentical(source, replica, `round ${round} (seed ${SEED})`);
+
+    if (round % 6 === 5) {
+      // Cold path: a brand-new machine joins from nothing but the state.
+      const fresh = fs.realpathSync(fs.mkdtempSync(path.join(tempRoot, `fresh-${round}-`)));
+      apply(fresh, snap);
+      assertReposIdentical(source, fresh, `round ${round} fresh (seed ${SEED})`);
+    }
+  }
+});
+
+test('performance: capture and apply costs on a working repo', () => {
+  const source = fs.realpathSync(fs.mkdtempSync(path.join(tempRoot, 'perf-')));
+  git(source, 'init', '--quiet');
+  git(source, 'config', 'user.email', 'storm@amalgm.test');
+  git(source, 'config', 'user.name', 'Storm');
+  git(source, 'config', 'commit.gpgsign', 'false');
+  for (let c = 0; c < 30; c += 1) {
+    for (let f = 0; f < 10; f += 1) {
+      fs.writeFileSync(path.join(source, `f${(c * 10 + f) % 120}.md`), `commit ${c} file ${f}\n`.repeat(30));
+    }
+    git(source, 'add', '-A');
+    git(source, 'commit', '--quiet', '-m', `c${c}`);
+  }
+  fs.writeFileSync(path.join(source, 'f1.md'), 'dirty edit\n');
+  fs.writeFileSync(path.join(source, 'loose.md'), 'untracked\n');
+
+  const ms = (from) => Number(process.hrtime.bigint() - from) / 1e6;
+  let t = process.hrtime.bigint();
+  const full = capture(source);
+  const captureMs = ms(t);
+
+  t = process.hrtime.bigint();
+  const light = capture(source, { withBundle: false });
+  const lightMs = ms(t);
+  assert.equal(light.stateId, full.stateId, 'the bundle never enters identity');
+
+  const replica = fs.realpathSync(fs.mkdtempSync(path.join(tempRoot, 'perf-replica-')));
+  t = process.hrtime.bigint();
+  apply(replica, full);
+  const applyMs = ms(t);
+
+  console.log(
+    `# perf (120 files, 30 commits): capture=${captureMs.toFixed(0)}ms ` +
+    `captureNoBundle=${lightMs.toFixed(0)}ms coldApply=${applyMs.toFixed(0)}ms`,
+  );
+  assert.ok(captureMs < 5000, `capture too slow: ${captureMs}ms`);
+  assert.ok(lightMs < 2000, `bundle-less capture too slow: ${lightMs}ms`);
+  assert.ok(applyMs < 10000, `cold apply too slow: ${applyMs}ms`);
+});

package/runtime/scripts/amalgm-mcp/tests/repocard.test.js

@@ -0,0 +1,371 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const { execFileSync } = require('child_process');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const { capture, apply, verify } = require('../repocard');
+
+const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'amalgm-repocard-test-'));
+test.after(() => {
+  fs.rmSync(tempRoot, { recursive: true, force: true });
+});
+
+function git(dir, ...args) {
+  return execFileSync('git', args, { cwd: dir, maxBuffer: 64 * 1024 * 1024, stdio: ['pipe', 'pipe', 'pipe'] }).toString('utf8').trim();
+}
+
+function tryRun(fn) {
+  try { return { ok: true, value: fn() }; } catch (error) { return { ok: false, error }; }
+}
+
+function makeRepo(name) {
+  const dir = fs.realpathSync(fs.mkdtempSync(path.join(tempRoot, `${name}-`)));
+  git(dir, 'init', '--quiet');
+  git(dir, 'config', 'user.email', 'storm@amalgm.test');
+  git(dir, 'config', 'user.name', 'Storm');
+  git(dir, 'config', 'commit.gpgsign', 'false');
+  return dir;
+}
+
+function blankDir(name) {
+  return fs.realpathSync(fs.mkdtempSync(path.join(tempRoot, `${name}-`)));
+}
+
+function commit(dir, message) {
+  git(dir, 'add', '-A');
+  git(dir, 'commit', '--quiet', '-m', message);
+}
+
+/**
+ * The referee: two repos are identical when git's own plumbing says so —
+ * same HEAD, same refs, same index (blob hashes + modes), same status, and
+ * byte-identical worktrees over every tracked and untracked file. Uses none
+ * of the repocard machinery.
+ */
+function assertReposIdentical(a, b, label) {
+  const probe = (dir, ...args) => tryRun(() => git(dir, ...args));
+  for (const args of [
+    ['symbolic-ref', '-q', 'HEAD'],
+    ['rev-parse', '-q', '--verify', 'HEAD'],
+  ]) {
+    const left = probe(a, ...args);
+    const right = probe(b, ...args);
+    assert.equal(left.ok, right.ok, `${label}: ${args.join(' ')} disagree on success`);
+    if (left.ok) assert.equal(left.value, right.value, `${label}: ${args.join(' ')}`);
+  }
+
+  const sorted = (text) => text.split('\n').filter(Boolean).sort();
+  assert.deepEqual(
+    sorted(git(a, 'for-each-ref', '--format=%(refname) %(objectname)', 'refs/heads', 'refs/tags')),
+    sorted(git(b, 'for-each-ref', '--format=%(refname) %(objectname)', 'refs/heads', 'refs/tags')),
+    `${label}: refs`,
+  );
+  assert.deepEqual(
+    sorted(git(a, 'ls-files', '-s')),
+    sorted(git(b, 'ls-files', '-s')),
+    `${label}: index`,
+  );
+  assert.deepEqual(
+    sorted(git(a, 'status', '--porcelain=v2', '--untracked-files=all')),
+    sorted(git(b, 'status', '--porcelain=v2', '--untracked-files=all')),
+    `${label}: status`,
+  );
+
+  const worktree = (dir) => {
+    const map = new Map();
+    const list = execFileSync('git', ['ls-files', '--cached', '--others', '--exclude-standard', '-z'], { cwd: dir })
+      .toString('utf8').split('\0').filter(Boolean);
+    for (const rel of list) {
+      const abs = path.join(dir, rel);
+      let stat;
+      try {
+        stat = fs.lstatSync(abs);
+      } catch {
+        map.set(rel, 'absent'); // in the index, deleted from the worktree — a real state, compared like any other
+        continue;
+      }
+      map.set(rel, stat.isSymbolicLink()
+        ? `link:${fs.readlinkSync(abs)}`
+        : `file:${stat.mode & 0o100 ? 'x' : '-'}:${fs.readFileSync(abs).toString('base64')}`);
+    }
+    return map;
+  };
+  assert.deepEqual([...worktree(a).entries()].sort(), [...worktree(b).entries()].sort(), `${label}: worktree bytes`);
+}
+
+function roundTrip(source, name) {
+  const state = capture(source);
+  assert.ok(!state.busy, `${name}: capture unexpectedly busy: ${state.busy}`);
+  const replica = blankDir(`${name}-replica`);
+  apply(replica, state); // throws unless the ids reproduce (axiom 4)
+  assertReposIdentical(source, replica, name);
+  return { state, replica };
+}
+
+// --- round trips -------------------------------------------------------------
+
+test('a committed repo round-trips exactly: branches, tags, remote, HEAD', () => {
+  const source = makeRepo('committed');
+  fs.writeFileSync(path.join(source, 'a.md'), 'one');
+  commit(source, 'first');
+  git(source, 'checkout', '--quiet', '-b', 'feature');
+  fs.writeFileSync(path.join(source, 'b.md'), 'two');
+  commit(source, 'second');
+  git(source, 'tag', 'light');
+  git(source, 'tag', '-a', 'heavy', '-m', 'annotated');
+  git(source, 'remote', 'add', 'origin', 'https://example.test/repo.git');
+
+  const { state, replica } = roundTrip(source, 'committed');
+  assert.equal(state.card.head.branch, 'feature');
+  assert.equal(git(replica, 'remote', 'get-url', 'origin'), 'https://example.test/repo.git');
+});
+
+test('staged, unstaged, untracked, binary, and exec-bit work rides the checkpoint', () => {
+  const source = makeRepo('dirty');
+  fs.writeFileSync(path.join(source, 'a.md'), 'line one\nline two\n');
+  fs.writeFileSync(path.join(source, 'bin.dat'), Buffer.from([0, 1, 2, 255, 254, 0, 7]));
+  fs.writeFileSync(path.join(source, 'gone.md'), 'to be deleted');
+  fs.writeFileSync(path.join(source, 'vanish.md'), 'deleted without git');
+  fs.writeFileSync(path.join(source, 'script.sh'), '#!/bin/sh\n');
+  commit(source, 'base');
+
+  fs.writeFileSync(path.join(source, 'a.md'), 'line one\nSTAGED\n');
+  git(source, 'add', 'a.md');
+  fs.appendFileSync(path.join(source, 'a.md'), 'UNSTAGED on top\n'); // staged AND unstaged
+  fs.writeFileSync(path.join(source, 'bin.dat'), Buffer.from([9, 9, 9, 0, 255])); // unstaged binary
+  git(source, 'rm', '--quiet', 'gone.md'); // staged deletion
+  fs.rmSync(path.join(source, 'vanish.md')); // unstaged deletion: index keeps it, disk loses it
+  fs.chmodSync(path.join(source, 'script.sh'), 0o755);
+  git(source, 'add', 'script.sh'); // staged mode change
+  fs.writeFileSync(path.join(source, 'staged-new.md'), 'brand new, staged');
+  git(source, 'add', 'staged-new.md');
+  fs.mkdirSync(path.join(source, 'deep', 'nest'), { recursive: true });
+  fs.writeFileSync(path.join(source, 'deep', 'nest', 'loose.md'), 'untracked');
+  fs.writeFileSync(path.join(source, 'loose.bin'), Buffer.from([255, 0, 128]));
+  fs.chmodSync(path.join(source, 'loose.bin'), 0o755);
+
+  roundTrip(source, 'dirty');
+});
+
+test('detached HEAD round-trips', () => {
+  const source = makeRepo('detached');
+  fs.writeFileSync(path.join(source, 'a.md'), 'v1');
+  commit(source, 'first');
+  fs.writeFileSync(path.join(source, 'a.md'), 'v2');
+  commit(source, 'second');
+  git(source, 'checkout', '--quiet', '--detach', 'HEAD~1');
+
+  const { state, replica } = roundTrip(source, 'detached');
+  assert.equal(state.card.head.detached, true);
+  assert.equal(tryRun(() => git(replica, 'symbolic-ref', '-q', 'HEAD')).ok, false);
+});
+
+test('an unborn repo with staged and untracked work round-trips', () => {
+  const source = makeRepo('unborn');
+  fs.writeFileSync(path.join(source, 'first.md'), 'staged before any commit');
+  git(source, 'add', 'first.md');
+  fs.writeFileSync(path.join(source, 'loose.md'), 'untracked');
+
+  const { state } = roundTrip(source, 'unborn');
+  assert.equal(state.card.head.commit, null);
+  assert.equal(state.card.bundle, null);
+});
+
+// --- identity ------------------------------------------------------------------
+
+test('capture is deterministic: same state, same ids, twice', () => {
+  const source = makeRepo('deterministic');
+  fs.writeFileSync(path.join(source, 'a.md'), 'content');
+  commit(source, 'first');
+  fs.writeFileSync(path.join(source, 'a.md'), 'dirty');
+
+  const first = capture(source);
+  const second = capture(source);
+  assert.equal(first.cardId, second.cardId);
+  assert.equal(first.checkpointId, second.checkpointId);
+  assert.equal(first.stateId, second.stateId);
+});
+
+test('ids separate committed truth from uncommitted work', () => {
+  const source = makeRepo('ids');
+  fs.writeFileSync(path.join(source, 'a.md'), 'v1');
+  commit(source, 'first');
+  const clean = capture(source);
+
+  fs.writeFileSync(path.join(source, 'a.md'), 'edited'); // uncommitted edit
+  const dirty = capture(source);
+  assert.equal(dirty.cardId, clean.cardId, 'an edit must not move the card');
+  assert.notEqual(dirty.checkpointId, clean.checkpointId);
+
+  commit(source, 'second'); // the commit moves the card and empties the checkpoint
+  const committed = capture(source);
+  assert.notEqual(committed.cardId, clean.cardId);
+});
+
+// --- busy ------------------------------------------------------------------------
+
+test('busy repos refuse to lie: merge and rebase conflicts', () => {
+  const source = makeRepo('busy');
+  fs.writeFileSync(path.join(source, 'a.md'), 'base\n');
+  commit(source, 'base');
+  git(source, 'checkout', '--quiet', '-b', 'left');
+  fs.writeFileSync(path.join(source, 'a.md'), 'left\n');
+  commit(source, 'left');
+  git(source, 'checkout', '--quiet', '-');
+  fs.writeFileSync(path.join(source, 'a.md'), 'right\n');
+  commit(source, 'right');
+
+  assert.equal(tryRun(() => git(source, 'merge', '--quiet', 'left')).ok, false);
+  assert.equal(capture(source).busy, 'MERGE_HEAD');
+  git(source, 'add', '-A');
+  git(source, 'commit', '--quiet', '--no-edit');
+  assert.ok(!capture(source).busy, 'a finished merge captures cleanly');
+
+  git(source, 'checkout', '--quiet', 'left');
+  fs.writeFileSync(path.join(source, 'a.md'), 'left again\n');
+  commit(source, 'left 2');
+  const rebase = tryRun(() => git(source, 'rebase', 'master')) // default branch name varies
+    .ok || tryRun(() => git(source, 'rebase', 'main')).ok;
+  if (!rebase) {
+    assert.match(capture(source).busy, /^rebase/);
+    git(source, 'rebase', '--abort');
+  }
+  assert.ok(!capture(source).busy);
+});
+
+test('bisect is a mode, not a busy state: its checkouts are captured', () => {
+  const source = makeRepo('bisect');
+  const shas = [];
+  for (let i = 0; i < 8; i += 1) {
+    fs.writeFileSync(path.join(source, 'a.md'), `version ${i}`);
+    commit(source, `version ${i}`);
+    shas.push(git(source, 'rev-parse', 'HEAD'));
+  }
+
+  const atTip = capture(source, { withBundle: false });
+  // 6 candidates between good and bad: two steps always mean two distinct checkouts.
+  git(source, 'bisect', 'start', shas[7], shas[0]);
+
+  // Mid-bisect: capture works and sees the detached checkout bisect made.
+  const midBisect = capture(source, { withBundle: false });
+  assert.ok(!midBisect.busy, `bisect wrongly reported busy: ${midBisect.busy}`);
+  assert.equal(midBisect.card.head.detached, true);
+  assert.notEqual(midBisect.cardId, atTip.cardId, 'the bisect checkout is a card change');
+
+  // Each bisect step is another detectable card change.
+  git(source, 'bisect', 'good');
+  const nextStep = capture(source, { withBundle: false });
+  assert.ok(!nextStep.busy);
+  assert.notEqual(nextStep.cardId, midBisect.cardId);
+
+  git(source, 'bisect', 'reset');
+  assert.equal(capture(source, { withBundle: false }).cardId, atTip.cardId);
+});
+
+// --- incremental -------------------------------------------------------------------
+
+test('checkpoint-only refresh: same card, new checkpoint, live replica follows', () => {
+  const source = makeRepo('incremental');
+  fs.writeFileSync(path.join(source, 'a.md'), 'v1');
+  commit(source, 'first');
+  const { state: v1, replica } = roundTrip(source, 'incremental');
+
+  fs.writeFileSync(path.join(source, 'a.md'), 'edited but uncommitted');
+  fs.writeFileSync(path.join(source, 'loose.md'), 'new untracked');
+  const v2 = capture(source);
+  assert.equal(v2.cardId, v1.cardId);
+  assert.notEqual(v2.checkpointId, v1.checkpointId);
+
+  apply(replica, v2); // same replica dir, no re-clone
+  assertReposIdentical(source, replica, 'incremental refresh');
+});
+
+test('a checkout on the source is one card change and the replica follows exactly', () => {
+  const source = makeRepo('checkout');
+  for (let i = 0; i < 20; i += 1) {
+    fs.writeFileSync(path.join(source, `f${i}.md`), `main ${i}`);
+  }
+  commit(source, 'main files');
+  git(source, 'checkout', '--quiet', '-b', 'other');
+  for (let i = 0; i < 20; i += 1) {
+    fs.writeFileSync(path.join(source, `f${i}.md`), `other ${i}`);
+  }
+  commit(source, 'other files');
+  git(source, 'checkout', '--quiet', '-');
+  const { state: before, replica } = roundTrip(source, 'checkout');
+
+  git(source, 'checkout', '--quiet', 'other'); // 20 files change on disk
+  const after = capture(source);
+  assert.notEqual(after.cardId, before.cardId, 'the checkout is a card change');
+  assert.equal(after.checkpoint.stagedPatch.length, 0, 'nothing rides the checkpoint');
+  assert.equal(after.checkpoint.unstagedPatch.length, 0);
+  apply(replica, after);
+  assertReposIdentical(source, replica, 'post-checkout');
+});
+
+// --- corruption ------------------------------------------------------------------------
+
+test('a corrupted bundle is rejected, never applied', () => {
+  const source = makeRepo('corrupt');
+  fs.writeFileSync(path.join(source, 'a.md'), 'v1');
+  commit(source, 'first');
+  const state = capture(source);
+  state.card.bundle.bytes = Buffer.concat([state.card.bundle.bytes, Buffer.from('tampered')]);
+
+  const replica = blankDir('corrupt-replica');
+  assert.throws(() => apply(replica, state), /bundle rejected/);
+});
+
+// --- nested repositories: territory boundaries -------------------------------
+
+test('a nested repository is its own territory: the parent captures around it', () => {
+  const dir = makeRepo('nested-parent');
+  fs.writeFileSync(path.join(dir, 'a.md'), 'parent\n');
+  commit(dir, 'parent');
+
+  const nested = path.join(dir, 'vendor', 'lib');
+  fs.mkdirSync(nested, { recursive: true });
+  git(nested, 'init', '--quiet');
+  git(nested, 'config', 'user.email', 'storm@amalgm.test');
+  git(nested, 'config', 'user.name', 'Storm');
+  git(nested, 'config', 'commit.gpgsign', 'false');
+  fs.writeFileSync(path.join(nested, 'inner.md'), 'child\n');
+  commit(nested, 'child');
+
+  fs.writeFileSync(path.join(dir, 'b.md'), 'untracked sibling\n');
+
+  const parent = capture(dir);
+  assert.ok(!parent.busy, 'a nested repo must not crash or block the parent capture');
+  assert.deepEqual(parent.checkpoint.untracked.map((file) => file.path), ['b.md'],
+    'the nested repository must not ride the parent checkpoint');
+
+  const child = capture(nested, { withBundle: false });
+  assert.ok(!child.busy && child.cardId, 'the nested repository captures as its own territory');
+
+  // The parent still round-trips (axiom 4) — minus the nested territory,
+  // which travels as its own card, never inside the parent.
+  const replica = blankDir('nested-replica');
+  apply(replica, parent);
+  assert.ok(!fs.existsSync(path.join(replica, 'vendor', 'lib')),
+    'the replica must not contain the nested territory');
+});
+
+test('a linked worktree (.git file) inside the checkout is excluded the same way', () => {
+  const dir = makeRepo('wt-parent');
+  fs.writeFileSync(path.join(dir, 'a.md'), 'v1\n');
+  commit(dir, 'first');
+  git(dir, 'worktree', 'add', '--quiet', path.join(dir, 'worktrees', 'wt1'), '-b', 'side');
+
+  const parent = capture(dir, { withBundle: false });
+  assert.ok(!parent.busy, 'a linked worktree must not crash the parent capture');
+  assert.equal(parent.checkpoint.untracked.some((file) => file.path.startsWith('worktrees/')), false,
+    'the linked worktree must not ride the parent checkpoint');
+
+  const child = capture(path.join(dir, 'worktrees', 'wt1'), { withBundle: false });
+  assert.ok(!child.busy, 'the linked worktree captures as its own territory');
+  assert.equal(child.card.head.branch, 'side');
+});