amalgm 0.1.245 → 0.1.246

package/runtime/scripts/amalgm-mcp/tests/doorbell.matrix.rig.js

@@ -0,0 +1,107 @@
+'use strict';
+
+/**
+ * The shared rig for the doorbell grammar matrix suites. Habitats and
+ * the transcript judge only — the grids themselves live in
+ * doorbell.matrix.life.test.js and doorbell.matrix.watch.test.js.
+ */
+
+const assert = require('node:assert/strict');
+const { execFileSync } = 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 tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'amalgm-matrix-'));
+
+function cleanup() {
+  fs.rmSync(tempRoot, { recursive: true, force: true });
+}
+
+function makeDir(name) {
+  return fs.realpathSync(fs.mkdtempSync(path.join(tempRoot, `${name}-`)));
+}
+
+function gitInit(dir) {
+  execFileSync('git', ['init', '-q'], { cwd: dir });
+}
+
+function makeObserver(options = {}) {
+  const events = [];
+  const observer = createObserver({
+    db: new Database(':memory:'),
+    emit: (event) => events.push(event),
+    ...options,
+  });
+  return { observer, events };
+}
+
+/** A files root over freshly laid ground, marked after enrollment. */
+function filesRoot(lay = () => {}) {
+  const dir = makeDir('cell');
+  lay(dir);
+  const { observer, events } = makeObserver();
+  const root = observer.enrollRoot(dir);
+  return { dir, events, observer, root, mark: events.length };
+}
+
+/**
+ * The restart column's shape: enroll, let the first observer die,
+ * mutate while nothing runs, and return a fresh observer's voice over
+ * the same store — converged by start() ALONE, the real startup
+ * entrance, never an assisted scan.
+ */
+function afterRestart(lay, mutate) {
+  const dir = makeDir('cell');
+  lay(dir);
+  const db = new Database(':memory:');
+  createObserver({ db, emit: () => {} }).enrollRoot(dir);
+  mutate(dir);
+  const events = [];
+  const observer = createObserver({ db, emit: (event) => events.push(event) });
+  observer.start(); // no scanNow: starting IS the catch-up event
+  observer.stop();
+  return { dir, events, observer, root: observer.listRoots()[0], mark: 0 };
+}
+
+/**
+ * What was spoken since the mark, reduced to the grammar under exam:
+ * the event type and its addresses. Order is not part of the grammar
+ * (scans batch), so both sides are sorted; WHAT is spoken, exactly
+ * once each, is the whole claim.
+ */
+const VOICE = ['path', 'from', 'to'];
+function said(spoken) {
+  return spoken
+    .map((event) => {
+      const fields = {};
+      for (const key of VOICE) if (event[key] !== undefined) fields[key] = event[key];
+      return [event.type, fields];
+    })
+    .sort((a, b) => (JSON.stringify(a) < JSON.stringify(b) ? -1 : 1));
+}
+function speaks(rig, expected, note) {
+  assert.deepEqual(
+    said(rig.events.slice(rig.mark)),
+    said(expected.map(([type, fields]) => ({ type, ...fields }))),
+    note);
+}
+
+function clean(rig) {
+  assert.deepEqual(rig.observer.verify(rig.root.rootId), []);
+}
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+async function until(arrived, deadlineMs = 5_000) {
+  const deadline = Date.now() + deadlineMs;
+  while (!arrived() && Date.now() < deadline) await sleep(20);
+  return arrived();
+}
+
+module.exports = {
+  afterRestart, clean, cleanup, filesRoot, gitInit, makeDir, makeObserver,
+  said, sleep, speaks, until,
+};

package/runtime/scripts/amalgm-mcp/tests/doorbell.matrix.watch.test.js

@@ -0,0 +1,213 @@
+'use strict';
+
+/**
+ * THE WORDING GRID + THE WATCHER ENTRANCES — the live half of the
+ * doorbell grammar matrix.
+ *
+ * The wording grid: one canonical mutation, delivered under every
+ * lawful doorbell wording, down to the worst cases the OS contract
+ * permits (a rename naming only the new name, a bare null, no doorbell
+ * at all). The conviction must be IDENTICAL under every wording: a
+ * doorbell is only a doorbell; disk decides. Proven total by
+ * construction against the ratified wording list.
+ *
+ * The watcher entrances: the observer opens exactly four genuinely
+ * distinct doorbell surfaces — the files-root recursive watcher, the
+ * repo-root recursive watcher, the single-file root's parent-directory
+ * doorbell, and every top-level root's address doorbell. One
+ * event-driven exam each proves the delivered ring converges without
+ * an assisted scan. No cross product: the life grid already proves the
+ * detection grammar these entrances feed.
+ */
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const path = require('path');
+
+const { installFakeWatch } = require('./fake-watch');
+const {
+  cleanup, gitInit, makeDir, makeObserver, sleep, speaks, until,
+} = require('./doorbell.matrix.rig');
+
+test.after(cleanup);
+
+/**
+ * A live observer over fresh ground, ringing through the fake watch so
+ * an exam can deliver exactly the wording it means to. Always torn
+ * down, watchers and fake alike.
+ */
+async function live(lay, run) {
+  const fake = installFakeWatch();
+  try {
+    const dir = makeDir('live');
+    lay(dir);
+    const { observer, events } = makeObserver({ settleMs: 25 });
+    const root = observer.enrollRoot(dir);
+    observer.start();
+    try {
+      await run({ fake, dir, observer, events, root, mark: events.length });
+    } finally {
+      observer.stop();
+    }
+  } finally {
+    fake.restore();
+  }
+}
+
+// --- the wording grid -----------------------------------------------------
+
+const WORDINGS = Object.freeze([
+  'the old name only',
+  'the new name only',
+  'both names',
+  'no filename',
+  'the ancestor directory only',
+  'the same name twice',
+  'a burst of unrelated names',
+  'a name for unchanged ground',
+  'nothing at all',
+]);
+
+/**
+ * The canonical mutation: `a/x.md` renamed to `a/y.md` behind a live
+ * observer. Whatever the doorbell says, the conviction must be this
+ * one identical sentence.
+ */
+const layCanon = (dir) => {
+  fs.mkdirSync(path.join(dir, 'a'));
+  fs.writeFileSync(path.join(dir, 'a', 'x.md'), 'steady');
+};
+
+function convictionUnder(deliver) {
+  return live(layCanon, async (rig) => {
+    fs.renameSync(path.join(rig.dir, 'a', 'x.md'), path.join(rig.dir, 'a', 'y.md'));
+    deliver(rig.fake, rig.dir);
+    assert.ok(await until(() => rig.events.slice(rig.mark).some((event) => event.type === 'file.renamed')),
+      'the wording was swallowed: no conviction arrived');
+    await sleep(100); // let any echo speak before judging the transcript
+    speaks(rig, [['file.renamed', { from: 'a/x.md', to: 'a/y.md' }]],
+      'one conviction, identical under every wording');
+    assert.deepEqual(rig.observer.verify(rig.root.rootId), []);
+  });
+}
+
+const WORDING_GRID = {
+  'the old name only': () => convictionUnder((fake, dir) => fake.deliver(dir, 'a/x.md')),
+  'the new name only': () => convictionUnder((fake, dir) => fake.deliver(dir, 'a/y.md')),
+  'both names': () => convictionUnder((fake, dir) => {
+    fake.deliver(dir, 'a/x.md');
+    fake.deliver(dir, 'a/y.md');
+  }),
+  'no filename': () => convictionUnder((fake, dir) => fake.deliver(dir, null)),
+  'the ancestor directory only': () => convictionUnder((fake, dir) => fake.deliver(dir, 'a')),
+  'the same name twice': () => convictionUnder((fake, dir) => {
+    fake.deliver(dir, 'a/y.md');
+    fake.deliver(dir, 'a/y.md');
+  }),
+  'a burst of unrelated names': () => convictionUnder((fake, dir) => {
+    for (const name of ['lore.md', 'a/zzz.png', 'a/x.md', 'b', 'a/y.md']) fake.deliver(dir, name);
+  }),
+
+  'a name for unchanged ground': () => live(layCanon, async (rig) => {
+    rig.fake.deliver(rig.dir, 'a/ghost.md');
+    await sleep(150);
+    assert.equal(rig.events.length, rig.mark,
+      'a doorbell cannot create belief: equal truth is silence');
+    assert.deepEqual(rig.observer.verify(rig.root.rootId), []);
+  }),
+
+  'nothing at all': () => live(layCanon, async (rig) => {
+    fs.renameSync(path.join(rig.dir, 'a', 'x.md'), path.join(rig.dir, 'a', 'y.md'));
+    await sleep(150);
+    assert.equal(rig.events.slice(rig.mark).filter((event) => event.type === 'file.renamed').length, 0,
+      'no doorbell, no conviction: the observer needs evidence, not luck');
+    assert.ok(rig.observer.verify(rig.root.rootId).length > 0,
+      'but the referee is not blind: unscanned truth is reported');
+    rig.observer.scanNow(rig.root.rootId);
+    speaks(rig, [['file.renamed', { from: 'a/x.md', to: 'a/y.md' }]],
+      'and the next look convicts identically');
+    assert.deepEqual(rig.observer.verify(rig.root.rootId), []);
+  }),
+};
+
+test('the wording grid is total: every lawful doorbell wording is faced', () => {
+  assert.deepEqual(Object.keys(WORDING_GRID), [...WORDINGS]);
+});
+
+for (const [wording, cell] of Object.entries(WORDING_GRID)) {
+  test(`wording grid — the doorbell says ${wording}`, cell);
+}
+
+// --- the watcher entrances ------------------------------------------------
+
+test('entrance — the files-root recursive watcher: a delivered ring convicts a member edit unassisted', () =>
+  live((dir) => fs.writeFileSync(path.join(dir, 'notes.md'), 'v1'), async (rig) => {
+    fs.writeFileSync(path.join(rig.dir, 'notes.md'), 'v2');
+    rig.fake.deliver(rig.dir, 'notes.md');
+    assert.ok(await until(() => rig.events.slice(rig.mark).some((event) => event.type === 'file.changed')),
+      'the member doorbell never convicted');
+    await sleep(100);
+    speaks(rig, [['file.changed', { path: 'notes.md' }]]);
+    assert.deepEqual(rig.observer.verify(rig.root.rootId), []);
+  }));
+
+test('entrance — the repo-root recursive watcher: a delivered ring forwards as one raw repo doorbell', () =>
+  live((dir) => {
+    gitInit(dir);
+    fs.writeFileSync(path.join(dir, 'a.md'), 'a');
+  }, async (rig) => {
+    assert.equal(rig.root.kind, 'repo', 'territory is decided by disk');
+    fs.writeFileSync(path.join(rig.dir, 'b.md'), 'b');
+    rig.fake.deliver(rig.dir, 'b.md');
+    assert.ok(await until(() => rig.events.slice(rig.mark).some((event) => event.type === 'repo.changed')),
+      'the repo doorbell never convicted');
+    await sleep(100);
+    speaks(rig, [['repo.changed', {}]],
+      'one raw repo doorbell, zero file events — classification into card or checkpoint is the follower\'s layer');
+    assert.deepEqual(rig.observer.verify(rig.root.rootId), []);
+  }));
+
+test('entrance — the single-file root\'s parent doorbell: the parent hears what the file\'s own inode cannot', async () => {
+  const fake = installFakeWatch();
+  try {
+    const holder = makeDir('single');
+    const file = path.join(holder, 'solo.md');
+    fs.writeFileSync(file, 'v1');
+    const { observer, events } = makeObserver({ settleMs: 25 });
+    const root = observer.enrollRoot(file);
+    assert.equal(root.kind, 'file', 'the smallest root: one channel');
+    observer.start();
+    try {
+      const mark = events.length;
+      fs.writeFileSync(file, 'v2');
+      fake.deliver(holder, 'solo.md');
+      assert.ok(await until(() => events.slice(mark).some((event) => event.type === 'file.changed')),
+        'the parent doorbell never convicted');
+      await sleep(100);
+      speaks({ events, mark }, [['file.changed', { path: '' }]],
+        'the smallest root is its own address: the one channel lives at the empty relative path');
+      assert.deepEqual(observer.verify(root.rootId), []);
+    } finally {
+      observer.stop();
+    }
+  } finally {
+    fake.restore();
+  }
+});
+
+test('entrance — the address doorbell: the parent observes a root rename and the follow rings unassisted', () =>
+  live((dir) => fs.writeFileSync(path.join(dir, 'notes.md'), 'n'), async (rig) => {
+    const renamed = `${rig.dir}-w2`;
+    fs.renameSync(rig.dir, renamed);
+    // The lawful worst case: only the NEW name is delivered, to the
+    // PARENT — the root's own recursive watcher heard nothing.
+    rig.fake.deliver(path.dirname(rig.dir), path.basename(renamed));
+    assert.ok(await until(() => rig.events.slice(rig.mark).some((event) => event.type === 'root.moved')),
+      'the address doorbell never convicted');
+    await sleep(100);
+    speaks(rig, [['root.moved', { from: rig.dir, to: renamed }]],
+      'same identity, new address — no unavailable flicker');
+    assert.equal(rig.observer.listRoots()[0].path, renamed);
+    assert.deepEqual(rig.observer.verify(rig.root.rootId), []);
+  }));

package/runtime/scripts/amalgm-mcp/tests/entity-oracle/adapter.js

@@ -0,0 +1,72 @@
+'use strict';
+
+/**
+ * The boundary adapter — the ONLY oracle file that knows what today's
+ * detection stack actually claims.
+ *
+ * Two slices, one per layer:
+ *
+ * `detectorSlice` reads the OBSERVER's claim: channel identity (fileId /
+ * linkId / dirId), address (rel_path), version (content_hash for a file;
+ * the written target for a link; a directory has none — existence is its
+ * whole claim), and repo-territory membership — channel evidence, judged
+ * against disk and the event ledger.
+ *
+ * `registrySlice` reads the REGISTRY's claim through its public API: the
+ * root record, active records by derived address, and the evidence layer's
+ * divergence report. The claimed slice: root identity, file AND folder
+ * records (uuid, slot, status, type, version — container membership
+ * translated through the identity binding), repo.git territory
+ * transitions, and divergence.
+ */
+
+function detectorSlice(observer, rootId, rootPath) {
+  const root = observer.listRoots().find((row) => row.rootId === rootId) ?? null;
+  const rows = root && root.kind === 'files' ? observer.filesForRoot(rootId) : [];
+  const files = new Map();
+  for (const row of rows) {
+    files.set(row.relPath, { uuid: row.fileId, version: row.contentHash });
+  }
+  const links = new Map();
+  for (const row of (root && root.kind === 'files' ? observer.linksForRoot(rootId) : [])) {
+    links.set(row.relPath, { uuid: row.linkId, target: row.target });
+  }
+  const dirs = new Map();
+  for (const row of (root && root.kind === 'files' ? observer.dirsForRoot(rootId) : [])) {
+    dirs.set(row.relPath, { uuid: row.dirId });
+  }
+  const territories = observer.listRoots()
+    .filter((row) => row.kind === 'repo'
+      && (row.path === rootPath || row.path.startsWith(`${rootPath}/`)))
+    .map((row) => row.path)
+    .sort();
+  return { root, files, links, dirs, territories };
+}
+
+function registrySlice(registry, evidence) {
+  // The oracle harness registers exactly one tree per registry, so its
+  // top record is the one parentless active.
+  const root = registry.roots()[0] ?? null;
+  return {
+    root,
+    divergence: evidence.divergence(),
+    /** Walk a derived address slot by slot — the registry's own chain answers. */
+    recordAtPath(address) {
+      let cursor = root;
+      if (address === '') return cursor;
+      for (const name of address.split('/')) {
+        if (!cursor) return null;
+        cursor = registry.activeAt(cursor.uuid, name);
+      }
+      return cursor;
+    },
+    /** The registry's own stored-active membership pairs for one container. */
+    activeChildren(uuid) {
+      return registry.children(uuid)
+        .filter((child) => child.status === 'active')
+        .map((child) => [child.uuid, child.name]);
+    },
+  };
+}
+
+module.exports = { detectorSlice, registrySlice };