amalgm 0.1.245 → 0.1.246

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

@@ -0,0 +1,289 @@
+'use strict';
+
+/**
+ * LINK exams: a pointer is a channel whose whole payload is its written
+ * address — recorded verbatim, never followed — plus the enrollment
+ * policy's edge-following, which turns a pointer into a reason to
+ * enroll the ground it names (and only that ground).
+ */
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const { execFileSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const { followEdges } = require('../observer/edges');
+const {
+  cleanup, eventsOf, makeDir, makeObserver,
+} = require('./observer.rig');
+
+test.after(cleanup);
+
+// --- links: a pointer is a channel whose payload is its written address ---
+
+test('a symlink is a channel whose payload is its written address — recorded verbatim, never followed', () => {
+  const dir = makeDir('links');
+  fs.mkdirSync(path.join(dir, 'real'));
+  fs.writeFileSync(path.join(dir, 'real', 'doc.md'), 'doc');
+  fs.symlinkSync('real', path.join(dir, 'shortcut')); // relative, into enrolled ground
+  fs.symlinkSync('no/such/path', path.join(dir, 'dangling')); // broken: a full citizen
+  fs.symlinkSync('/outside/absolute', path.join(dir, 'away')); // absolute, outside
+
+  const { observer, events } = makeObserver();
+  const root = observer.enrollRoot(dir);
+
+  assert.deepEqual(eventsOf(events, 'link.created').map((event) => [event.path, event.target]).sort(),
+    [['away', '/outside/absolute'], ['dangling', 'no/such/path'], ['shortcut', 'real']],
+    'every pointer is a channel — broken or absolute included — its address verbatim, never stat\'d');
+  assert.deepEqual(eventsOf(events, 'file.created').map((event) => event.path), ['real/doc.md'],
+    'the pointer was never traversed: real ground is walked once, at its real address');
+  assert.deepEqual(observer.verify(root.rootId), []);
+});
+
+test('a retarget is the same channel: the address absorbs the inode churn, like an atomic save', () => {
+  const dir = makeDir('retarget');
+  fs.mkdirSync(path.join(dir, 'v1'));
+  fs.mkdirSync(path.join(dir, 'v2'));
+  fs.symlinkSync('v1', path.join(dir, 'current'));
+  const { observer, events } = makeObserver();
+  const root = observer.enrollRoot(dir);
+  const linkId = eventsOf(events, 'link.created')[0].linkId;
+
+  // A retarget IS unlink + recreate: a new inode under the old name with a
+  // new written address, and the address is the whole change.
+  fs.unlinkSync(path.join(dir, 'current'));
+  fs.symlinkSync('v2', path.join(dir, 'current'));
+  const mark = events.length;
+  observer.scanNow(root.rootId);
+  assert.deepEqual(eventsOf(events.slice(mark), 'link.changed')
+    .map((event) => [event.linkId, event.target, event.previousTarget]),
+  [[linkId, 'v2', 'v1']], 'same channel, new address, previous address named');
+  assert.equal(events.length - mark, 1, 'nothing else spoke');
+
+  // Recreation with the SAME address: the same pointer wearing a new inode.
+  fs.unlinkSync(path.join(dir, 'current'));
+  fs.symlinkSync('v2', path.join(dir, 'current'));
+  const quiet = events.length;
+  observer.scanNow(root.rootId);
+  assert.equal(events.length, quiet, 'recreating the same pointer is silence');
+  assert.equal(observer.linksForRoot(root.rootId).find((row) => row.relPath === 'current').linkId,
+    linkId, 'the recreated pointer wears the same channel');
+  assert.deepEqual(observer.verify(root.rootId), []);
+});
+
+test('mv moves the channel by inode; an exchange of names reads as two retargets', () => {
+  const dir = makeDir('link-moves');
+  fs.mkdirSync(path.join(dir, 'a'));
+  fs.mkdirSync(path.join(dir, 'b'));
+  fs.symlinkSync('a', path.join(dir, 'to-a'));
+  fs.symlinkSync('b', path.join(dir, 'to-b'));
+  const { observer, events } = makeObserver();
+  const root = observer.enrollRoot(dir);
+  const before = new Map(observer.linksForRoot(root.rootId).map((row) => [row.relPath, row.linkId]));
+
+  fs.renameSync(path.join(dir, 'to-a'), path.join(dir, 'renamed'));
+  let mark = events.length;
+  observer.scanNow(root.rootId);
+  assert.deepEqual(eventsOf(events.slice(mark), 'link.renamed')
+    .map((event) => [event.from, event.to, event.linkId]),
+  [['to-a', 'renamed', before.get('to-a')]], 'mv preserves the inode, and the inode rescues the orphan');
+  assert.equal(events.length - mark, 1);
+
+  // Two links exchanging names: the address claims first, so each address
+  // keeps its channel and reports a new pointer — a link's meaning IS its
+  // written address, exactly like two files exchanging content.
+  fs.renameSync(path.join(dir, 'renamed'), path.join(dir, 'limbo'));
+  fs.renameSync(path.join(dir, 'to-b'), path.join(dir, 'renamed'));
+  fs.renameSync(path.join(dir, 'limbo'), path.join(dir, 'to-b'));
+  mark = events.length;
+  observer.scanNow(root.rootId);
+  assert.deepEqual(eventsOf(events.slice(mark), 'link.changed')
+    .map((event) => [event.path, event.target, event.previousTarget, event.linkId]).sort(),
+  [['renamed', 'b', 'a', before.get('to-a')], ['to-b', 'a', 'b', before.get('to-b')]].sort(),
+    'path-first: each address keeps its channel and reports the new pointer');
+  assert.equal(events.length - mark, 2, 'no rename spoke: an exchange of names is two retargets');
+  assert.deepEqual(observer.verify(root.rootId), []);
+});
+
+test('link channels close when the root becomes repo territory', () => {
+  const dir = makeDir('links-repo');
+  fs.mkdirSync(path.join(dir, 'real'));
+  fs.symlinkSync('real', path.join(dir, 'shortcut'));
+  const { observer, events } = makeObserver();
+  const root = observer.enrollRoot(dir);
+  const linkId = eventsOf(events, 'link.created')[0].linkId;
+
+  fs.mkdirSync(path.join(dir, '.git'));
+  const mark = events.length;
+  observer.scanNow(root.rootId);
+  assert.deepEqual(eventsOf(events.slice(mark), 'link.deleted').map((event) => event.linkId), [linkId],
+    'repo territory travels as one card: the pointer channel closes with the rest');
+  assert.equal(observer.linksForRoot(root.rootId).length, 0);
+});
+
+test('the referee catches a retarget behind the observer\'s back', () => {
+  const dir = makeDir('link-referee');
+  fs.mkdirSync(path.join(dir, 'v1'));
+  fs.mkdirSync(path.join(dir, 'v2'));
+  fs.symlinkSync('v1', path.join(dir, 'current'));
+  const { observer } = makeObserver();
+  const root = observer.enrollRoot(dir);
+  assert.deepEqual(observer.verify(root.rootId), []);
+
+  fs.unlinkSync(path.join(dir, 'current'));
+  fs.symlinkSync('v2', path.join(dir, 'current'));
+  assert.deepEqual(observer.verify(root.rootId).map((m) => [m.path, m.problem]),
+    [['current', 'stale: the link was retargeted, the observer did not notice']],
+    'the referee re-reads every pointer with none of the observer\'s machinery');
+});
+
+// --- edges: enrollment follows pointers to real ground (ratified policy) --
+
+test('enrollment follows edges: an outside target becomes enrolled ground, exactly once', () => {
+  const outside = makeDir('edge-target');
+  fs.writeFileSync(path.join(outside, 'shared.md'), 'shared');
+  const dir = makeDir('edge-ws');
+  fs.symlinkSync(outside, path.join(dir, 'shared'));
+  fs.symlinkSync(outside, path.join(dir, 'also-shared'));
+
+  const { observer } = makeObserver();
+  observer.enrollRoot(dir);
+  const { enrolled, reported } = followEdges(observer);
+  assert.deepEqual(enrolled, [outside], 'two pointers, one real ground, one enrollment');
+  assert.deepEqual(reported, []);
+  const target = observer.listRoots().find((root) => root.path === outside);
+  assert.ok(target, 'the real target is enrolled ground now');
+  assert.ok(observer.filesForRoot(target.rootId).some((row) => row.relPath === 'shared.md'),
+    'its tree got channels at its real address');
+  assert.deepEqual(followEdges(observer), { enrolled: [], reported: [], settled: true },
+    'idempotent: nothing left to follow');
+});
+
+test('edge cascade terminates: a cycle of grounds enrolls each exactly once', () => {
+  const a = makeDir('cycle-a');
+  const b = makeDir('cycle-b');
+  fs.symlinkSync(b, path.join(a, 'to-b'));
+  fs.symlinkSync(a, path.join(b, 'to-a'));
+
+  const { observer } = makeObserver();
+  observer.enrollRoot(a);
+  const { enrolled } = followEdges(observer);
+  assert.deepEqual(enrolled, [b], 'b via a\'s edge; a was already ground when b\'s edge came up');
+  assert.equal(observer.listRoots().length, 2, 'the cycle added no third root and never looped');
+});
+
+test('edge verdicts: broken is silence, would-swallow is refused, a file target enrolls itself alone', () => {
+  const holder = makeDir('edge-holder');
+  const ws = path.join(holder, 'inner', 'ws');
+  fs.mkdirSync(ws, { recursive: true });
+  const filePath = path.join(makeDir('edge-file'), 'single.txt');
+  fs.writeFileSync(filePath, 'one');
+  fs.symlinkSync(path.join(holder, 'gone'), path.join(ws, 'dangling'));
+  fs.symlinkSync(filePath, path.join(ws, 'one-file'));
+  fs.symlinkSync(holder, path.join(ws, 'up')); // contains the enrolled ws
+
+  const { observer } = makeObserver();
+  observer.enrollRoot(ws);
+  const { enrolled, reported } = followEdges(observer);
+  assert.deepEqual(enrolled, [filePath],
+    'a real file target is real ground: it enrolls as its own single-file root');
+  assert.deepEqual(reported.map((entry) => [entry.path, entry.via]),
+    [[holder, 'up']],
+    'the would-swallow edge is refused by name; a broken pointer is silence, not a refusal');
+  const fileRoot = observer.listRoots().find((root) => root.path === filePath);
+  assert.equal(fileRoot.kind, 'file', 'the smallest root there is');
+  assert.ok(!observer.listRoots().some((root) => root.path === path.dirname(filePath)),
+    'never its parent: siblings the edge never named stay unshared');
+});
+
+test('a retarget enrolls the new target; following only ever adds', () => {
+  const first = makeDir('edge-old');
+  const second = makeDir('edge-new');
+  const dir = makeDir('edge-retarget');
+  fs.symlinkSync(first, path.join(dir, 'ptr'));
+
+  const { observer } = makeObserver();
+  const root = observer.enrollRoot(dir);
+  followEdges(observer);
+  fs.unlinkSync(path.join(dir, 'ptr'));
+  fs.symlinkSync(second, path.join(dir, 'ptr'));
+  observer.scanNow(root.rootId);
+  const { enrolled } = followEdges(observer);
+  assert.deepEqual(enrolled, [second], 'the new ground is followed');
+  assert.ok(observer.listRoots().some((other) => other.path === first),
+    'the old target stays enrolled — removing coverage is an explicit act, never a side effect');
+});
+
+test('a repository exposes its edges too: the census reads the worktree, and following enrolls the target', () => {
+  const outside = makeDir('repo-edge-target');
+  fs.writeFileSync(path.join(outside, 'shared.md'), 'shared');
+  const repo = makeDir('repo-edge');
+  execFileSync('git', ['init', '-q'], { cwd: repo });
+  fs.mkdirSync(path.join(repo, 'docs'));
+  fs.symlinkSync(outside, path.join(repo, 'docs', 'shared'));
+  fs.symlinkSync('../elsewhere', path.join(repo, 'inward')); // broken: silence
+
+  const { observer } = makeObserver();
+  const root = observer.enrollRoot(repo);
+  assert.equal(root.kind, 'repo');
+  assert.deepEqual(observer.linkEdges(root.rootId),
+    { edges: [{ relPath: 'docs/shared', target: outside }, { relPath: 'inward', target: '../elsewhere' }], unsettled: [] },
+    'a repo\'s edges come from a fresh worktree census — stored nowhere, git owns the repo\'s memory');
+  const { enrolled, reported } = followEdges(observer);
+  assert.deepEqual(enrolled, [outside],
+    'a link inside repo territory reaches real ground exactly like one in files territory');
+  assert.deepEqual(reported, []);
+  const target = observer.listRoots().find((other) => other.path === outside);
+  assert.ok(observer.filesForRoot(target.rootId).some((row) => row.relPath === 'shared.md'),
+    'the external target is watched ground now');
+});
+
+test('exactly the named target enrolls: a link authorizes its ground, never the repository around it', () => {
+  const elsewhere = makeDir('exact-holder');
+  const repo = path.join(elsewhere, 'lib-repo');
+  fs.mkdirSync(path.join(repo, 'src'), { recursive: true });
+  execFileSync('git', ['init', '-q'], { cwd: repo });
+  fs.writeFileSync(path.join(repo, 'src', 'util.js'), 'x');
+  const ws = makeDir('exact-ws');
+  fs.symlinkSync(path.join(repo, 'src'), path.join(ws, 'lib-src'));
+
+  const { observer } = makeObserver();
+  observer.enrollRoot(ws);
+  const { enrolled } = followEdges(observer);
+  assert.deepEqual(enrolled, [path.join(repo, 'src')],
+    'the edge named src, so src is the ground that enrolls — an enclosing .git the user never named authorizes nothing');
+  assert.equal(observer.listRoots().find((root) => root.path === path.join(repo, 'src')).kind, 'files');
+  assert.ok(!observer.listRoots().some((root) => root.path === repo),
+    'the repository around the named ground stays unshared');
+
+  // Named directly, a repository is its own ground: the exact target IS
+  // the repo root, so it enrolls as one card.
+  const ws2 = makeDir('exact-ws2');
+  const repo2 = makeDir('exact-repo2');
+  execFileSync('git', ['init', '-q'], { cwd: repo2 });
+  fs.symlinkSync(repo2, path.join(ws2, 'lib'));
+  const second = makeObserver().observer;
+  second.enrollRoot(ws2);
+  followEdges(second);
+  assert.equal(second.listRoots().find((root) => root.path === repo2).kind, 'repo',
+    'a target that is itself a repository root enrolls as the repository');
+});
+
+test('the enrollment policy gates every route: an excluded edge target is refused and reported', () => {
+  const holder = makeDir('policy-holder');
+  const envPath = path.join(holder, '.env');
+  fs.writeFileSync(envPath, 'SECRET=1');
+  const ws = makeDir('policy-ws');
+  fs.symlinkSync(envPath, path.join(ws, 'config'));
+
+  const { observer } = makeObserver(); // the DEFAULT policy — the one production runs
+  observer.enrollRoot(ws);
+  const { enrolled, reported } = followEdges(observer);
+  assert.deepEqual(enrolled, []);
+  assert.deepEqual(reported.map((entry) => [entry.path, entry.via]), [[envPath, 'config']],
+    'the refusal is loud, never silent');
+  assert.match(reported[0].reason, /enrollment policy/);
+  assert.ok(!observer.listRoots().some((root) => root.path === envPath),
+    'a secret stays unwatched: an edge is never a way around the policy');
+});

package/runtime/scripts/amalgm-mcp/tests/observer.rig.js

@@ -0,0 +1,103 @@
+'use strict';
+
+/**
+ * The shared rig for the observer suites — a sandbox with a real
+ * observer over an in-memory store, real git repositories, and the
+ * deterministic doorbell. The exams live beside it, one file per
+ * seam: observer.test.js (enrollment and the compare function),
+ * observer.links.test.js (pointers and edge-following),
+ * observer.roots.test.js (root continuity and the smallest ground),
+ * observer.territory.test.js (repositories and unsettled ground).
+ *
+ * This file may require production code — it drives the system under
+ * exam.
+ */
+
+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-observer-test-'));
+
+function cleanup() {
+  fs.rmSync(tempRoot, { recursive: true, force: true });
+}
+
+/** A fresh observer over an in-memory db, capturing every emitted event. */
+function makeObserver(options = {}) {
+  const events = [];
+  const observer = createObserver({
+    db: new Database(':memory:'),
+    emit: (event) => events.push(event),
+    ...options,
+  });
+  return { observer, events };
+}
+
+function makeDir(name) {
+  const dir = fs.mkdtempSync(path.join(tempRoot, `${name}-`));
+  return fs.realpathSync(dir);
+}
+
+function eventsOf(events, type) {
+  return events.filter((event) => event.type === type);
+}
+
+/**
+ * OS watchers are lossy by contract — a write landing in a just-started
+ * stream's warm-up window can vanish without a doorbell (axiom 2; the
+ * system heals this with catch-up scans). The live tests here claim
+ * routing and classification, not first-write delivery, so the write is
+ * repeated until a doorbell answers. Writes must be idempotent (same
+ * content) so repetition never changes what the test asserts.
+ */
+async function nudgeUntil(write, arrived, deadlineMs = 10_000) {
+  const deadline = Date.now() + deadlineMs;
+  write();
+  let lastNudge = Date.now();
+  while (!arrived() && Date.now() < deadline) {
+    await new Promise((resolve) => setTimeout(resolve, 25));
+    if (!arrived() && Date.now() - lastNudge > 300) {
+      write();
+      lastNudge = Date.now();
+    }
+  }
+  return arrived();
+}
+function realGit(dir, ...args) {
+  return execFileSync('git', args, { cwd: dir, stdio: ['pipe', 'pipe', 'pipe'] }).toString('utf8').trim();
+}
+
+function realRepo(name) {
+  const dir = makeDir(name);
+  realGit(dir, 'init', '--quiet');
+  realGit(dir, 'config', 'user.email', 'obs@amalgm.test');
+  realGit(dir, 'config', 'user.name', 'Obs');
+  realGit(dir, 'config', 'commit.gpgsign', 'false');
+  return dir;
+}
+
+/**
+ * A deterministic doorbell: delivers nothing on its own and hands the test
+ * each root's bell, so it can ring exactly what fs.watch rarely delivers
+ * (null filenames, chosen paths) through the production wiring.
+ */
+function fakeWatchKit() {
+  const bells = new Map(); // rootPath -> onDirty
+  return {
+    watch: (rootPath, onDirty) => {
+      bells.set(rootPath, onDirty);
+      return { degraded: false, close: () => bells.delete(rootPath) };
+    },
+    ring: (rootPath, relPath) => bells.get(rootPath)(relPath),
+  };
+}
+
+
+module.exports = {
+  cleanup, eventsOf, fakeWatchKit, makeDir, makeObserver, nudgeUntil, realGit, realRepo,
+};