amalgm 0.1.245 → 0.1.246

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

@@ -0,0 +1,435 @@
+'use strict';
+
+/**
+ * The follower storm: seeded random git life — bulk checkouts, merges that
+ * conflict, ignored churn, cleans, tags, detached wanderings — driven
+ * through a REAL observer doorbell into a follower, judged per round:
+ *
+ *  - truth ids unchanged        -> the round must add zero events
+ *  - truth ids moved            -> exactly one event, right type, exact stateId
+ *  - truth busy                 -> zero events until the operation resolves
+ *
+ * The storm's ops are synchronous ON PURPOSE: emissions exist only in the
+ * quiet gaps whose endpoints the referee samples with plain capture(), so
+ * an emitted state the referee never saw is a state that never held still.
+ * That soundness costs the storm the mid-operation race — which is why the
+ * spawned-git tests below exist: git runs in its own process there, the
+ * event loop stays free, and capture attempts genuinely land while a bulk
+ * operation is rewriting the worktree.
+ *
+ * Seed via AMALGM_STORM_SEED for reproduction.
+ */
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const { execFileSync, spawn } = require('child_process');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const Database = require('better-sqlite3');
+const { createObserver } = require('../observer');
+const { capture, createFollower } = require('../repocard');
+
+const SEED = Number(process.env.AMALGM_STORM_SEED || 20260729);
+const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'amalgm-repofollow-storm-'));
+test.after(() => {
+  fs.rmSync(tempRoot, { recursive: true, force: true });
+});
+
+function mulberry32(seed) {
+  let a = seed >>> 0;
+  return () => {
+    a |= 0;
+    a = (a + 0x6D2B79F5) | 0;
+    let t = Math.imul(a ^ (a >>> 15), 1 | a);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+const int = (rng, n) => Math.floor(rng() * n);
+const pick = (rng, arr) => arr[int(rng, arr.length)];
+
+function git(dir, ...args) {
+  return execFileSync('git', args, { cwd: dir, stdio: ['pipe', 'pipe', 'pipe'] }).toString('utf8').trim();
+}
+function tryGit(dir, ...args) {
+  try { return git(dir, ...args); } catch { return null; }
+}
+/** Git in its own process, the event loop free — the production shape. */
+function spawnGit(dir, ...args) {
+  return new Promise((resolve, reject) => {
+    const child = spawn('git', args, { cwd: dir, stdio: 'ignore' });
+    child.on('error', reject);
+    child.on('exit', (code) => (code === 0 ? resolve() : reject(new Error(`git ${args.join(' ')} exited ${code}`))));
+  });
+}
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+async function until(predicate, ms) {
+  const deadline = Date.now() + ms;
+  while (!predicate() && Date.now() < deadline) await sleep(20);
+  return predicate();
+}
+
+const CORE = ['a.md', 'b.md', 'c.md'];
+const BULK = 400;
+
+/** main + two branches ('big-a', 'big-b') whose bulk/ files all differ. */
+function makeStormRepo(name) {
+  const dir = fs.realpathSync(fs.mkdtempSync(path.join(tempRoot, `${name}-`)));
+  git(dir, 'init', '--quiet', '-b', 'main');
+  git(dir, 'config', 'user.email', 'storm@amalgm.test');
+  git(dir, 'config', 'user.name', 'Storm');
+  git(dir, 'config', 'commit.gpgsign', 'false');
+  fs.writeFileSync(path.join(dir, '.gitignore'), 'ignored/\n');
+  for (const file of CORE) fs.writeFileSync(path.join(dir, file), `${file} base\n`);
+  fs.mkdirSync(path.join(dir, 'bulk'));
+  for (let i = 0; i < BULK; i += 1) {
+    fs.writeFileSync(path.join(dir, 'bulk', `f${i}.md`), `A ${i}\n`);
+  }
+  git(dir, 'add', '-A');
+  git(dir, 'commit', '--quiet', '-m', 'base');
+  git(dir, 'branch', 'big-a');
+  git(dir, 'checkout', '--quiet', '-b', 'big-b');
+  for (let i = 0; i < BULK; i += 1) {
+    fs.writeFileSync(path.join(dir, 'bulk', `f${i}.md`), `B ${i}\n`);
+  }
+  git(dir, 'add', '-A');
+  git(dir, 'commit', '--quiet', '-m', 'bulk flipped');
+  git(dir, 'checkout', '--quiet', 'main');
+  return dir;
+}
+
+/** Real doorbells: observer -> follower, no synthetic rings anywhere. */
+function makeRig(dir, overrides = {}) {
+  const rig = { lastRingAt: Date.now(), events: [], observerEvents: [] };
+  rig.observer = createObserver({
+    db: new Database(':memory:'),
+    emit: (event) => {
+      rig.observerEvents.push(event);
+      if (event.type === 'repo.changed') {
+        rig.lastRingAt = Date.now();
+        rig.follower.ring();
+      }
+    },
+    settleMs: 25,
+  });
+  rig.follower = createFollower({
+    repoPath: dir,
+    emit: (event) => rig.events.push(event),
+    settleMs: 120,
+    capMs: 1000,
+    last: capture(dir, { withBundle: false }),
+    ...overrides,
+  });
+  const root = rig.observer.enrollRoot(dir);
+  assert.equal(root.kind, 'repo', 'a git repo must enroll as repo territory');
+  rig.observer.start();
+  rig.stop = () => {
+    rig.observer.stop();
+    rig.follower.close();
+  };
+  return rig;
+}
+
+async function waitQuiet(rig, quietMs = 450, deadlineMs = 15_000) {
+  const ok = await until(() => Date.now() - rig.lastRingAt > quietMs, deadlineMs);
+  assert.ok(ok, `doorbells never went quiet (seed ${SEED})`);
+}
+
+test(`follower storm survives the referee (seed ${SEED})`, async () => {
+  const dir = makeStormRepo('storm');
+  const rig = makeRig(dir);
+  const rng = mulberry32(SEED);
+
+  const ops = {
+    editTracked: () => {
+      const file = pick(rng, CORE);
+      fs.writeFileSync(path.join(dir, file), `${file} edit r${round} ${rng()}\n`);
+    },
+    ignoredChurn: () => {
+      fs.mkdirSync(path.join(dir, 'ignored'), { recursive: true });
+      for (let i = 0; i < 30; i += 1) {
+        fs.writeFileSync(path.join(dir, 'ignored', `noise-${i}.log`), `${round} ${i}\n`);
+      }
+    },
+    commitAll: () => {
+      tryGit(dir, 'add', '-A');
+      tryGit(dir, 'commit', '--quiet', '-m', `round ${round}`);
+    },
+    checkoutSwap: () => {
+      const branch = tryGit(dir, 'symbolic-ref', '-q', '--short', 'HEAD');
+      tryGit(dir, 'checkout', '--quiet', branch === 'big-a' ? 'big-b' : 'big-a');
+    },
+    newBranchCommit: () => {
+      tryGit(dir, 'checkout', '--quiet', '-b', `br-${round}`);
+      fs.writeFileSync(path.join(dir, 'c.md'), `branch work r${round}\n`);
+      tryGit(dir, 'add', '-A');
+      tryGit(dir, 'commit', '--quiet', '-m', `branch ${round}`);
+    },
+    tagNow: () => {
+      tryGit(dir, 'tag', `t-${round}`);
+    },
+    untrackedBatch: () => {
+      fs.mkdirSync(path.join(dir, 'loose'), { recursive: true });
+      for (let i = 0; i < 25; i += 1) {
+        fs.writeFileSync(path.join(dir, 'loose', `u${round}-${i}.md`), `${i}\n`);
+      }
+    },
+    cleanBulk: () => {
+      tryGit(dir, 'clean', '-fdq'); // bulk deletion, famously lock-free
+    },
+    stageSome: () => {
+      tryGit(dir, 'add', pick(rng, CORE));
+    },
+    detachToggle: () => {
+      const branch = tryGit(dir, 'symbolic-ref', '-q', '--short', 'HEAD');
+      if (branch === null) tryGit(dir, 'checkout', '--quiet', 'main');
+      else tryGit(dir, 'checkout', '--quiet', '--detach', 'HEAD~1');
+    },
+    mergeConflict: () => {
+      const base = tryGit(dir, 'symbolic-ref', '-q', '--short', 'HEAD');
+      if (base === null) return; // detached: skip, another round will merge
+      tryGit(dir, 'checkout', '--quiet', '-b', `clash-${round}`);
+      fs.writeFileSync(path.join(dir, 'a.md'), `theirs r${round}\n`);
+      tryGit(dir, 'add', '-A');
+      tryGit(dir, 'commit', '--quiet', '-m', `theirs ${round}`);
+      tryGit(dir, 'checkout', '--quiet', base);
+      fs.writeFileSync(path.join(dir, 'a.md'), `ours r${round}\n`);
+      tryGit(dir, 'add', '-A');
+      tryGit(dir, 'commit', '--quiet', '-m', `ours ${round}`);
+      tryGit(dir, 'merge', '--quiet', `clash-${round}`); // conflicts on a.md
+    },
+    resolveBusy: () => {
+      fs.writeFileSync(path.join(dir, 'a.md'), `resolved r${round}\n`);
+      tryGit(dir, 'add', '-A');
+      tryGit(dir, 'commit', '--quiet', '--no-edit');
+    },
+  };
+  const deck = [
+    'editTracked', 'editTracked', 'editTracked',
+    'ignoredChurn', 'ignoredChurn',
+    'commitAll', 'commitAll',
+    'checkoutSwap', 'checkoutSwap',
+    'newBranchCommit', 'tagNow',
+    'untrackedBatch', 'cleanBulk',
+    'stageSome', 'detachToggle', 'mergeConflict',
+  ];
+
+  const ROUNDS = 26;
+  let round = 0;
+  let silentRounds = 0;
+  let busyRounds = 0;
+  let cardEvents = 0;
+
+  for (round = 1; round <= ROUNDS; round += 1) {
+    const before = capture(dir, { withBundle: false });
+    const name = before.busy ? 'resolveBusy' : pick(rng, deck);
+    const countBefore = rig.events.length;
+
+    ops[name]();
+
+    await waitQuiet(rig);
+    const after = capture(dir, { withBundle: false });
+    const label = `round ${round} (${name}, seed ${SEED})`;
+
+    if (after.busy) {
+      busyRounds += 1;
+      await sleep(600); // long enough for settle and the pending cap to tempt it
+      assert.equal(rig.events.length, countBefore, `${label}: a busy repo must never travel`);
+      continue;
+    }
+
+    // Convergence: the follower's beliefs must land exactly on the referee's truth.
+    const converged = await until(() => {
+      const ids = rig.follower.ids();
+      return ids && ids.cardId === after.cardId && ids.checkpointId === after.checkpointId;
+    }, 8_000);
+    assert.ok(converged, `${label}: follower never converged to disk truth`);
+
+    const added = rig.events.slice(countBefore);
+    if (!before.busy && before.stateId === after.stateId) {
+      silentRounds += 1;
+      assert.equal(added.length, 0, `${label}: ids never moved yet events appeared`);
+      continue;
+    }
+    assert.equal(added.length, 1, `${label}: one real change must be exactly one event, got ${added.length}`);
+    assert.equal(added[0].stateId, after.stateId, `${label}: the event carries a state the referee never saw`);
+    const expectCard = before.busy || before.cardId !== after.cardId;
+    assert.equal(added[0].type, expectCard ? 'card.changed' : 'checkpoint.changed', `${label}: wrong event type`);
+    if (added[0].type === 'card.changed') cardEvents += 1;
+  }
+
+  rig.stop();
+  assert.equal(
+    rig.observerEvents.filter((event) => event.type.startsWith('file.')).length,
+    0,
+    'repo territory leaked file events',
+  );
+  console.log(`[follower-storm] seed ${SEED}: ${ROUNDS} rounds, ${rig.events.length} events`
+    + ` (${cardEvents} card), ${silentRounds} silent, ${busyRounds} busy — referee satisfied`);
+});
+
+/** A repo whose 'main' and 'huge' branches differ in every one of n files. */
+function makeBulkRepo(name, n) {
+  const dir = fs.realpathSync(fs.mkdtempSync(path.join(tempRoot, `${name}-`)));
+  git(dir, 'init', '--quiet', '-b', 'main');
+  git(dir, 'config', 'user.email', 'storm@amalgm.test');
+  git(dir, 'config', 'user.name', 'Storm');
+  git(dir, 'config', 'commit.gpgsign', 'false');
+  for (let i = 0; i < n; i += 1) {
+    fs.writeFileSync(path.join(dir, `f${i}.md`), `main ${i}\n`);
+  }
+  git(dir, 'add', '-A');
+  git(dir, 'commit', '--quiet', '-m', 'main');
+  git(dir, 'checkout', '--quiet', '-b', 'huge');
+  for (let i = 0; i < n; i += 1) {
+    fs.writeFileSync(path.join(dir, `f${i}.md`), `huge ${i}\n`);
+  }
+  git(dir, 'add', '-A');
+  git(dir, 'commit', '--quiet', '-m', 'huge');
+  git(dir, 'checkout', '--quiet', 'main');
+  return dir;
+}
+
+test('a thousands-of-files checkout travels as exactly one card event', async () => {
+  const N = 2_000;
+  const dir = makeBulkRepo('bulk', N);
+
+  const rig = makeRig(dir);
+  await waitQuiet(rig); // swallow the start() catch-up doorbell
+  assert.equal(rig.events.length, 0, 'an unchanged repo must not announce itself');
+
+  const checkoutStart = Date.now();
+  git(dir, 'checkout', '--quiet', 'huge');
+  const checkoutMs = Date.now() - checkoutStart;
+
+  const spoke = await until(() => rig.events.length > 0, 20_000);
+  const detectMs = Date.now() - checkoutStart;
+  assert.ok(spoke, `the ${N}-file checkout was never detected`);
+  await waitQuiet(rig);
+  await sleep(1_200); // room for the cap to tempt a second emission
+  rig.stop();
+
+  assert.equal(rig.events.length, 1, `a checkout must be ONE event, got ${rig.events.length}`);
+  assert.equal(rig.events[0].type, 'card.changed');
+  assert.equal(rig.events[0].card.head.branch, 'huge');
+  assert.equal(rig.events[0].checkpoint.stagedPatch.length, 0, 'a clean checkout carries no checkpoint patch');
+  assert.equal(rig.events[0].checkpoint.unstagedPatch.length, 0);
+  assert.deepEqual(rig.events[0].checkpoint.untracked, []);
+  assert.equal(rig.observerEvents.filter((event) => event.type.startsWith('file.')).length, 0);
+
+  const truth = capture(dir, { withBundle: false });
+  assert.equal(rig.events[0].stateId, truth.stateId, 'the one event must be the exact final state');
+  console.log(`[follower-storm] bulk: ${N}-file checkout ${checkoutMs}ms,`
+    + ` detected as one card ${detectMs}ms after checkout began`);
+});
+
+// --- the hard case: git in its own process, the event loop free ---------------
+
+test('a live spawned checkout is raced by real fires and still travels as one card', async () => {
+  const N = 2_000;
+  const dir = makeBulkRepo('spawned-checkout', N);
+  let childRunning = false;
+  let midOpCaptures = 0;
+  let sawBlockedMidOp = false;
+  const rig = makeRig(dir, {
+    settleMs: 30,
+    capMs: 100, // aggressive on purpose: fire INTO the running checkout
+    captureFn: (repo) => {
+      if (childRunning) midOpCaptures += 1;
+      return capture(repo, { withBundle: false });
+    },
+  });
+  await waitQuiet(rig);
+  assert.equal(rig.events.length, 0, 'an unchanged repo must not announce itself');
+
+  const probe = setInterval(() => {
+    if (childRunning && rig.follower.status().blocked) sawBlockedMidOp = true;
+  }, 10);
+  childRunning = true;
+  const checkoutStart = Date.now();
+  await spawnGit(dir, 'checkout', '--quiet', 'huge');
+  childRunning = false;
+  const checkoutMs = Date.now() - checkoutStart;
+  clearInterval(probe);
+
+  const spoke = await until(() => rig.events.length > 0, 20_000);
+  const detectMs = Date.now() - checkoutStart;
+  assert.ok(spoke, `the spawned ${N}-file checkout was never detected`);
+  await waitQuiet(rig);
+  await sleep(500); // room for a pending cap to tempt a second emission
+  rig.stop();
+
+  // The witness is an assertion, not a log line: the hard case MUST occur.
+  assert.ok(
+    sawBlockedMidOp,
+    'no capture attempt met the live lock while the checkout ran — the test proved nothing',
+  );
+  assert.equal(rig.events.length, 1, `a live checkout must be ONE event, got ${rig.events.length}`);
+  assert.equal(rig.events[0].type, 'card.changed');
+  assert.equal(rig.events[0].card.head.branch, 'huge');
+  const truth = capture(dir, { withBundle: false });
+  assert.equal(rig.events[0].stateId, truth.stateId, 'a partial checkout state must never travel');
+  assert.equal(rig.observerEvents.filter((event) => event.type.startsWith('file.')).length, 0);
+  console.log(`[follower-storm] spawned checkout: ${N} files ${checkoutMs}ms,`
+    + ` lock-blocked fires mid-op (asserted), ${midOpCaptures} captures mid-op,`
+    + ` one card ${detectMs}ms after start`);
+});
+
+test('a spawned lock-free clean travels as one checkpoint under live capture pressure', async () => {
+  const dir = fs.realpathSync(fs.mkdtempSync(path.join(tempRoot, 'spawned-clean-')));
+  git(dir, 'init', '--quiet', '-b', 'main');
+  git(dir, 'config', 'user.email', 'storm@amalgm.test');
+  git(dir, 'config', 'user.name', 'Storm');
+  git(dir, 'config', 'commit.gpgsign', 'false');
+  fs.writeFileSync(path.join(dir, 'a.md'), 'committed\n');
+  git(dir, 'add', '-A');
+  git(dir, 'commit', '--quiet', '-m', 'base');
+  const N = 2_500;
+  fs.mkdirSync(path.join(dir, 'loose'));
+  for (let i = 0; i < N; i += 1) {
+    fs.writeFileSync(path.join(dir, 'loose', `u${i}.md`), `${i}\n`);
+  }
+
+  let childRunning = false;
+  let midOpCaptures = 0;
+  const rig = makeRig(dir, {
+    settleMs: 30,
+    capMs: 100,
+    captureFn: (repo) => {
+      if (childRunning) midOpCaptures += 1;
+      return capture(repo, { withBundle: false });
+    },
+  });
+  await waitQuiet(rig);
+  assert.equal(rig.events.length, 0, 'an unchanged repo must not announce itself');
+
+  childRunning = true;
+  const cleanStart = Date.now();
+  await spawnGit(dir, 'clean', '-fdq'); // bulk deletion, famously lock-free: only the torn-read guard stands
+  childRunning = false;
+  const cleanMs = Date.now() - cleanStart;
+
+  const spoke = await until(() => rig.events.length > 0, 20_000);
+  await waitQuiet(rig);
+  await sleep(500);
+  rig.stop();
+
+  assert.ok(spoke, 'the spawned clean was never detected');
+  // The witness is an assertion, not a log line: captures MUST have raced
+  // the running clean, or the torn-read guard was never actually tried.
+  assert.ok(midOpCaptures > 0, 'no capture landed while the clean ran — the test proved nothing');
+  // A running clean cannot hold still across a full capture pair, so no
+  // intermediate state should travel. If this ever fails, that is the named
+  // residual speaking — a descheduled git stalling across both reads — not
+  // a regression in the guard.
+  assert.equal(rig.events.length, 1, `a live clean must be ONE event, got ${rig.events.length}`);
+  assert.equal(rig.events[0].type, 'checkpoint.changed');
+  assert.deepEqual(rig.events[0].checkpoint.untracked, []);
+  const truth = capture(dir, { withBundle: false });
+  assert.equal(rig.events[0].stateId, truth.stateId, 'a half-cleaned state must never travel');
+  console.log(`[follower-storm] spawned clean: ${N} untracked removed in ${cleanMs}ms,`
+    + ` ${midOpCaptures} captures mid-op — one checkpoint event`);
+});