amalgm 0.1.245 → 0.1.246

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

@@ -0,0 +1,389 @@
+'use strict';
+
+/**
+ * The conclusive detection test: seeded storms over the full alphabet of
+ * file operations, judged three ways.
+ *
+ *   1. The referee (observer.verify()) re-hashes every byte on disk and
+ *      compares against the observer's beliefs — zero mismatches or fail.
+ *   2. The ledger replay: the emitted events ALONE must reconstruct the
+ *      exact final disk state — proving nothing was missed and nothing was
+ *      invented.
+ *   3. Silence rules: no event may ever name an excluded path.
+ *
+ * Every possible change is a composition of the alphabet below; covering the
+ * alphabet under random composition is the completeness claim. Storms are
+ * seeded (AMALGM_STORM_SEED) so any failure replays exactly.
+ *
+ * Echo suppression (noteWrite) is deliberately absent here — storms are
+ * all-external by construction; noteWrite has its own tests in
+ * observer.test.js.
+ */
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const crypto = require('crypto');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const Database = require('better-sqlite3');
+const { createObserver } = require('../observer');
+const { walkRoot } = require('../observer/scan');
+const inclusion = require('../workspace/tree/inclusion');
+
+/** The judge's own hash — deliberately independent of the production
+ * primitive, so a broken detector cannot grade its own homework. */
+const hashFile = (absPath) =>
+  crypto.createHash('sha256').update(fs.readFileSync(absPath)).digest('hex');
+
+const SEED = Number(process.env.AMALGM_STORM_SEED || 20260729);
+
+const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'amalgm-observer-storm-'));
+test.after(() => {
+  fs.rmSync(tempRoot, { recursive: true, force: true });
+});
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+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;
+  };
+}
+
+let stamp = 0;
+
+/** Deterministic, always-distinct content of an exact byte length (>= 12). */
+function bytes(size) {
+  const head = `#${(stamp++).toString(36)}-`;
+  return (head + 'x'.repeat(size)).slice(0, size);
+}
+
+function makeObserver(options = {}) {
+  const events = [];
+  const observer = createObserver({
+    db: new Database(':memory:'),
+    emit: (event) => events.push(event),
+    ...options,
+  });
+  return { observer, events };
+}
+
+function makeStormRoot(name) {
+  const dir = fs.mkdtempSync(path.join(tempRoot, `${name}-`));
+  const root = fs.realpathSync(dir);
+  fs.mkdirSync(path.join(root, 'node_modules'));
+  return root;
+}
+
+/**
+ * The alphabet. Each op mutates the workspace like a real writer would and
+ * keeps its own bookkeeping of what should exist — the judges never use it;
+ * only op-picking does.
+ */
+function makeStorm(rng, root, { timestampLies }) {
+  const dirs = [''];
+  const live = new Set();
+  const abs = (rel) => path.join(root, rel);
+  const join = (dir, name) => (dir ? `${dir}/${name}` : name);
+  const dirname = (rel) => (rel.includes('/') ? rel.slice(0, rel.lastIndexOf('/')) : '');
+  const pick = (arr) => arr[Math.floor(rng() * arr.length)];
+  const pickLive = () => pick([...live]);
+  const newName = () => `f${(stamp++).toString(36)}.md`;
+  const size = () => 12 + Math.floor(rng() * 1500);
+  const write = (rel, n) => fs.writeFileSync(abs(rel), bytes(n));
+
+  const ops = {
+    create() {
+      const rel = join(pick(dirs), newName());
+      write(rel, size());
+      live.add(rel);
+    },
+    mkdirTree() {
+      // New nested dirs with files born instantly inside — the watcher-race case.
+      const a = join(pick(dirs), `d${(stamp++).toString(36)}`);
+      const b = `${a}/d${(stamp++).toString(36)}`;
+      fs.mkdirSync(abs(b), { recursive: true });
+      dirs.push(a, b);
+      for (let i = 0; i < 2; i += 1) {
+        const rel = join(b, newName());
+        write(rel, size());
+        live.add(rel);
+      }
+    },
+    edit() {
+      write(pickLive(), size());
+    },
+    sameSizeEdit() {
+      const rel = pickLive();
+      write(rel, fs.statSync(abs(rel)).size); // bytes() is always distinct
+    },
+    atomicSave() {
+      const rel = pickLive();
+      const tmp = `${rel}.tmp${(stamp++).toString(36)}`;
+      fs.writeFileSync(abs(tmp), bytes(size()));
+      fs.renameSync(abs(tmp), abs(rel));
+    },
+    rename() {
+      const rel = pickLive();
+      const to = join(dirname(rel), newName());
+      fs.renameSync(abs(rel), abs(to));
+      live.delete(rel);
+      live.add(to);
+    },
+    move() {
+      const rel = pickLive();
+      const to = join(pick(dirs), newName());
+      fs.renameSync(abs(rel), abs(to));
+      live.delete(rel);
+      live.add(to);
+    },
+    swapNames() {
+      const [a, b] = [...live];
+      if (!a || !b) return ops.create();
+      const tmp = join(dirname(a), `swap${(stamp++).toString(36)}.md`);
+      fs.renameSync(abs(a), abs(tmp));
+      fs.renameSync(abs(b), abs(a));
+      fs.renameSync(abs(tmp), abs(b));
+      return undefined;
+    },
+    remove() {
+      const rel = pickLive();
+      fs.rmSync(abs(rel));
+      live.delete(rel);
+    },
+    recreate() {
+      const rel = pickLive();
+      fs.rmSync(abs(rel));
+      write(rel, size());
+    },
+    burst() {
+      const rel = pickLive();
+      const n = fs.statSync(abs(rel)).size;
+      for (let i = 0; i < 5; i += 1) write(rel, n); // rapid same-size versions
+    },
+    excludedChurn() {
+      // Must never surface as any event.
+      fs.writeFileSync(abs(`node_modules/junk${(stamp++).toString(36)}.js`), 'x');
+      fs.writeFileSync(abs('.env'), `SECRET=${stamp}`);
+    },
+    backdate() {
+      // The timestamp lie: same size, same inode, mtime restored. Only the
+      // doorbell's word says anything happened.
+      const rel = pickLive();
+      const before = fs.statSync(abs(rel));
+      write(rel, before.size);
+      fs.utimesSync(abs(rel), before.atime, before.mtime);
+    },
+  };
+
+  const table = [];
+  const weigh = (name, weight) => {
+    for (let i = 0; i < weight; i += 1) table.push(ops[name]);
+  };
+  weigh('create', 15);
+  weigh('mkdirTree', 6);
+  weigh('edit', 20);
+  weigh('sameSizeEdit', 12);
+  weigh('atomicSave', 10);
+  weigh('rename', 8);
+  weigh('move', 8);
+  weigh('swapNames', 4);
+  weigh('remove', 8);
+  weigh('recreate', 5);
+  weigh('burst', 6);
+  weigh('excludedChurn', 8);
+  if (timestampLies) weigh('backdate', 10);
+
+  return {
+    step() {
+      if (live.size < 5) return ops.create();
+      return pick(table)();
+    },
+  };
+}
+
+// --- the judges -------------------------------------------------------------
+
+/** Judge 2: the ledger alone must rebuild the exact final disk state. */
+function assertLedgerReconstructsDisk(events, root, label) {
+  const model = new Map(); // fileId -> { path, hash }
+  for (const event of events) {
+    if (event.type === 'file.created') {
+      model.set(event.fileId, { path: event.path, hash: event.hash });
+    } else if (event.type === 'file.renamed') {
+      const file = model.get(event.fileId);
+      assert.ok(file, `${label}: rename on a channel the ledger never created`);
+      assert.equal(file.path, event.from, `${label}: rename .from disagrees with the ledger`);
+      file.path = event.to;
+    } else if (event.type === 'file.changed') {
+      const file = model.get(event.fileId);
+      assert.ok(file, `${label}: change on a channel the ledger never created`);
+      assert.equal(event.previousHash, file.hash, `${label}: hash chain broken at ${event.path}`);
+      file.hash = event.hash;
+      file.path = event.path;
+    } else if (event.type === 'file.deleted') {
+      assert.ok(model.delete(event.fileId), `${label}: delete on a channel the ledger never created`);
+    }
+  }
+
+  const fromLedger = new Map();
+  for (const file of model.values()) {
+    assert.ok(!fromLedger.has(file.path), `${label}: two live channels claim ${file.path}`);
+    fromLedger.set(file.path, file.hash);
+  }
+  const fromDisk = new Map();
+  for (const entry of walkRoot(root, inclusion.shouldEnroll).files) {
+    fromDisk.set(entry.relPath, hashFile(path.join(root, entry.relPath)));
+  }
+  assert.deepEqual(
+    [...fromLedger.entries()].sort(),
+    [...fromDisk.entries()].sort(),
+    `${label}: replaying the ledger does not reproduce disk (seed ${SEED})`,
+  );
+}
+
+/** Judge 3: excluded territory never surfaces. */
+function assertNoExcludedEvents(events, label) {
+  for (const event of events) {
+    for (const rel of [event.path, event.from, event.to]) {
+      if (!rel) continue;
+      assert.ok(
+        inclusion.shouldEnroll(rel),
+        `${label}: event named excluded path "${rel}" (seed ${SEED})`,
+      );
+    }
+  }
+}
+
+// --- sanity: the referee itself ----------------------------------------------
+
+test('the referee is not blind: unscanned changes are reported, then heal', () => {
+  const root = makeStormRoot('referee');
+  fs.writeFileSync(path.join(root, 'a.md'), bytes(20));
+  const { observer } = makeObserver();
+  observer.enrollRoot(root);
+  assert.deepEqual(observer.verify(), []);
+
+  // Three ways to drift, none scanned yet: the referee must see all three.
+  fs.writeFileSync(path.join(root, 'a.md'), bytes(20)); // stale
+  fs.writeFileSync(path.join(root, 'b.md'), bytes(20)); // unknown
+  const problems = observer.verify().map((m) => m.problem.split(':')[0]).sort();
+  assert.deepEqual(problems, ['stale', 'unknown']);
+
+  observer.scanNow();
+  fs.rmSync(path.join(root, 'a.md')); // ghost
+  assert.deepEqual(observer.verify().map((m) => m.problem.split(':')[0]), ['ghost']);
+
+  observer.scanNow();
+  assert.deepEqual(observer.verify(), []);
+});
+
+// --- storm 1: the compare engine, deterministic -------------------------------
+
+test('storm (engine): ~1000 random operations, scans interleaved, judged three ways', () => {
+  const rng = mulberry32(SEED);
+  const root = makeStormRoot('engine');
+  const { observer, events } = makeObserver();
+  observer.enrollRoot(root);
+  const storm = makeStorm(rng, root, { timestampLies: false });
+
+  for (let batch = 0; batch < 150; batch += 1) {
+    const opCount = 4 + Math.floor(rng() * 6);
+    for (let i = 0; i < opCount; i += 1) storm.step();
+    if (rng() < 0.85) observer.scanNow(); // sometimes several batches coalesce
+  }
+  observer.scanNow();
+
+  assert.deepEqual(observer.verify(), [], `referee found mismatches (seed ${SEED})`);
+  assertLedgerReconstructsDisk(events, root, 'engine storm');
+  assertNoExcludedEvents(events, 'engine storm');
+});
+
+// --- storm 2: live watchers + timestamp lies -----------------------------------
+
+test('storm (live): real watchers, bursts, and backdated timestamps', async () => {
+  const rng = mulberry32(SEED + 1);
+  const root = makeStormRoot('live');
+  const { observer, events } = makeObserver({ settleMs: 25 });
+  observer.enrollRoot(root);
+  observer.start();
+  const storm = makeStorm(rng, root, { timestampLies: true });
+
+  for (let i = 0; i < 200; i += 1) {
+    storm.step();
+    if (rng() < 0.3) await sleep(1 + Math.floor(rng() * 8));
+  }
+
+  // Event-only convergence: after start() this test NEVER calls scanNow —
+  // the doorbells' own settle scans are the only detection allowed to run.
+  // verify() is read-only and repairs nothing; we just watch until the
+  // referee is satisfied or the deadline rules a miss.
+  const deadline = Date.now() + 15_000;
+  let mismatches = observer.verify();
+  while (mismatches.length > 0 && Date.now() < deadline) {
+    await sleep(100);
+    mismatches = observer.verify();
+  }
+  observer.stop();
+
+  assert.deepEqual(mismatches, [], `referee found mismatches (seed ${SEED + 1})`);
+  assertLedgerReconstructsDisk(events, root, 'live storm');
+  assertNoExcludedEvents(events, 'live storm');
+});
+
+// --- performance ----------------------------------------------------------------
+
+test('performance: costs are one walk per scan and hashes only for suspects', async () => {
+  const root = makeStormRoot('perf');
+  for (let d = 0; d < 40; d += 1) {
+    fs.mkdirSync(path.join(root, `d${d}`));
+    for (let f = 0; f < 50; f += 1) {
+      fs.writeFileSync(path.join(root, `d${d}`, `f${f}.md`), bytes(1024));
+    }
+  }
+  const { observer, events } = makeObserver({ settleMs: 50 });
+  const ms = (from) => Number(process.hrtime.bigint() - from) / 1e6;
+
+  let t = process.hrtime.bigint();
+  observer.enrollRoot(root);
+  const enrollMs = ms(t);
+  assert.equal(events.filter((e) => e.type === 'file.created').length, 2000);
+
+  events.length = 0;
+  t = process.hrtime.bigint();
+  observer.scanNow();
+  const quietMs = ms(t);
+  assert.equal(events.length, 0, 'a quiet scan must be silent');
+
+  fs.writeFileSync(path.join(root, 'd7', 'f7.md'), bytes(1024));
+  t = process.hrtime.bigint();
+  observer.scanNow();
+  const editMs = ms(t);
+  assert.equal(events.length, 1, 'one edit is one event');
+
+  observer.start();
+  events.length = 0;
+  t = process.hrtime.bigint();
+  fs.writeFileSync(path.join(root, 'd9', 'f9.md'), bytes(1024));
+  const deadline = Date.now() + 5_000;
+  while (events.length === 0 && Date.now() < deadline) await sleep(5);
+  const latencyMs = ms(t);
+  observer.stop();
+  assert.equal(events.length, 1, 'live edit must arrive as one event');
+
+  console.log(
+    `# perf (2000 files, 1KB): enroll=${enrollMs.toFixed(0)}ms ` +
+    `quietScan=${quietMs.toFixed(1)}ms oneEditScan=${editMs.toFixed(1)}ms ` +
+    `saveToEventLatency=${latencyMs.toFixed(0)}ms (settle=50ms)`,
+  );
+  assert.ok(quietMs < 1000, `quiet scan too slow: ${quietMs}ms`);
+  assert.ok(editMs < 1000, `one-edit scan too slow: ${editMs}ms`);
+  assert.ok(latencyMs < 3000, `save-to-event latency too slow: ${latencyMs}ms`);
+});