amalgm 0.1.245 → 0.1.246

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

@@ -0,0 +1,239 @@
+'use strict';
+
+/**
+ * The shared rig for the entity oracle suites — the sandbox with the full
+ * cast (real observer, registry, evidence intake, operation model, ledger,
+ * binders) and the generator helpers that perform each real filesystem
+ * operation AND record it in the model. The exams live in
+ * entity.oracle.test.js; the storms in entity.storm.test.js.
+ *
+ * This file may require production code — it drives the system under exam.
+ * The judge itself (tests/entity-oracle/) may not, and a meta-test holds it
+ * to that.
+ */
+
+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 { createRegistry } = require('../registry');
+const { createEvidence, createEvidenceMemory } = require('../registry/evidence');
+const { createModel } = require('./entity-oracle/graph');
+const { createLedger } = require('./entity-oracle/ledger');
+const { createBinder, createChannelBinder } = require('./entity-oracle/bind');
+const { assertQuietPoint } = require('./entity-oracle/assert');
+
+const defaultPolicy = require('../workspace/tree/inclusion').shouldEnroll;
+
+// The RIG's explicit classification policy — injected into the model
+// exactly like the enrollment policy. "NUL byte means binary" is a choice
+// these tests make; the model owns no such rule.
+const classify = (bytes) => (
+  (Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes)).includes(0) ? 'file.binary' : 'file.text');
+
+const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'amalgm-entity-rig-'));
+
+function cleanup() {
+  fs.rmSync(tempRoot, { recursive: true, force: true });
+}
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/**
+ * Read-only convergence for event-only exams. `act` rings doorbells; the
+ * production chain those doorbells drive — the settle scan, then the
+ * scheduled registry intake — must finish ON ITS OWN. This waits by
+ * looking only (the detector spoke: events grew; the intake drained:
+ * dirty is false); it never scans, flushes, or repairs, so a system
+ * that needed help still fails — loudly at the deadline, never by
+ * stopwatch luck under parallel load. (The settle scan is one
+ * synchronous batch and its scheduled reconcile runs before the next
+ * timer tick, so "grew and drained" observed from a timer callback
+ * means the whole chain completed.)
+ */
+async function converged(kit, act, deadlineMs = 5_000) {
+  const before = kit.events.length;
+  act();
+  const deadline = Date.now() + deadlineMs;
+  while (kit.events.length === before || kit.evidence.dirty()) {
+    assert.ok(Date.now() < deadline,
+      'oracle: the event-driven chain did not converge before the deadline');
+    await sleep(5);
+  }
+}
+
+/**
+ * A sandbox with the full cast: real observer, operation model, ledger,
+ * binder, and generator helpers that perform each real filesystem operation
+ * AND record it in the model.
+ */
+function makeKit(name, { policy = defaultPolicy, watch, settleMs } = {}) {
+  const dir = fs.realpathSync(fs.mkdtempSync(path.join(tempRoot, `${name}-`)));
+  const events = [];
+  const regEvents = [];
+  let evidence; // wired below; observer events are hints into its intake
+  const observer = createObserver({
+    db: new Database(':memory:'),
+    emit: (event) => {
+      events.push(event);
+      evidence?.onEvent();
+    },
+    shouldEnroll: policy,
+    ...(watch ? { watch } : {}),
+    ...(settleMs !== undefined ? { settleMs } : {}),
+  });
+  const registryDb = new Database(':memory:');
+  const registry = createRegistry({
+    db: registryDb,
+    ephemeral: true,
+    emit: (event) => regEvents.push(event),
+  });
+  const memory = createEvidenceMemory(registryDb);
+  const model = createModel({ shouldEnroll: policy, classify });
+  const kit = {
+    dir, events, observer, model, policy,
+    registry, evidence, regEvents,
+    ledger: createLedger(),
+    binder: createChannelBinder(),
+    // Model uuid ↔ registry uuid, observe-only: records are permanent
+    // identity, so a registry-side rebind is an identity break.
+    registryBinder: createBinder(),
+    cursor: { value: 0 },
+    rootPath: dir,
+    rootId: null,
+
+    abs: (rel) => path.join(dir, rel),
+    enroll() {
+      kit.rootId = observer.enrollRoot(dir).rootId;
+      // The lens is keyed by the tree's permanent identity, so it is
+      // born here — birth reads store truth, exactly like the boundary.
+      evidence = createEvidence({
+        observer, registry, memory, rootId: kit.rootId,
+        // The evidence layer's injected classification policy reads the
+        // ground it is classifying — the same NUL rule the model got.
+        classify: (absPath) => classify(fs.readFileSync(absPath)),
+      });
+      kit.evidence = evidence;
+      evidence.reconcile();
+      return kit.rootId;
+    },
+    point(options) {
+      return assertQuietPoint(kit, options);
+    },
+
+    // --- generator: real op + model record, always in that order ---------
+    write(rel, data) {
+      fs.mkdirSync(path.dirname(kit.abs(rel)), { recursive: true });
+      fs.writeFileSync(kit.abs(rel), data);
+      model.write(rel, data);
+    },
+    replace(rel, data) {
+      const tmp = `${kit.abs(rel)}.tmp`;
+      fs.writeFileSync(tmp, data);
+      fs.renameSync(tmp, kit.abs(rel));
+      model.replace(rel, data);
+    },
+    touchSame(rel) {
+      const future = new Date(Date.now() + 5_000);
+      fs.utimesSync(kit.abs(rel), future, future);
+      model.touch();
+    },
+    mv(from, to) {
+      fs.mkdirSync(path.dirname(kit.abs(to)), { recursive: true });
+      fs.renameSync(kit.abs(from), kit.abs(to));
+      model.rename(from, to);
+    },
+    mvDir(from, to) {
+      fs.renameSync(kit.abs(from), kit.abs(to));
+      model.renameDir(from, to);
+    },
+    mkdir(rel) {
+      fs.mkdirSync(kit.abs(rel), { recursive: true });
+      model.mkdir(rel);
+    },
+    copy(from, to, data) {
+      fs.copyFileSync(kit.abs(from), kit.abs(to));
+      model.write(to, data);
+    },
+    rm(rel) {
+      fs.rmSync(kit.abs(rel));
+      model.remove(rel);
+    },
+    rmDir(rel) {
+      fs.rmSync(kit.abs(rel), { recursive: true, force: true });
+      model.removeDir(rel);
+    },
+    gitInit(rel) {
+      fs.mkdirSync(kit.abs(rel), { recursive: true });
+      execFileSync('git', ['init', '--quiet'], { cwd: kit.abs(rel) });
+      model.gitInit(rel);
+    },
+    gitRemove(rel) {
+      fs.rmSync(path.join(kit.abs(rel), '.git'), { recursive: true, force: true });
+      model.gitRemove(rel);
+    },
+
+    // --- link ground: a pointer's whole payload is its written target ----
+    symlink(rel, target) {
+      fs.mkdirSync(path.dirname(kit.abs(rel)), { recursive: true });
+      fs.symlinkSync(target, kit.abs(rel));
+      model.writeLink(rel, target);
+    },
+    /** Retarget IS unlink + recreate — the address absorbs the churn. */
+    retarget(rel, target) {
+      fs.rmSync(kit.abs(rel));
+      fs.symlinkSync(target, kit.abs(rel));
+      model.writeLink(rel, target);
+    },
+    mvLink(from, to) {
+      fs.mkdirSync(path.dirname(kit.abs(to)), { recursive: true });
+      fs.renameSync(kit.abs(from), kit.abs(to));
+      model.renameLink(from, to);
+    },
+    rmLink(rel) {
+      fs.rmSync(kit.abs(rel));
+      model.removeLink(rel);
+    },
+  };
+  return kit;
+}
+
+function fakeWatchKit() {
+  const bells = new Map();
+  return {
+    watch: (rootPath, onDirty) => {
+      bells.set(rootPath, onDirty);
+      return { degraded: false, close: () => bells.delete(rootPath) };
+    },
+    ring: (rootPath, relPath) => bells.get(rootPath)(relPath),
+    /** Every open watcher whose ground covers this absolute path rings,
+     * exactly as a real OS event fans out to nested recursive watchers. */
+    ringAt(absPath) {
+      for (const [watched, onDirty] of bells) {
+        if (absPath === watched) onDirty('');
+        else if (absPath.startsWith(`${watched}/`)) onDirty(absPath.slice(watched.length + 1));
+      }
+    },
+  };
+}
+
+function fileIdAt(kit, rel) {
+  const row = kit.observer.filesForRoot(kit.rootId).find((r) => r.relPath === rel);
+  assert.ok(row, `expected a store row at ${rel}`);
+  return row.fileId;
+}
+
+function linkIdAt(kit, rel) {
+  const row = kit.observer.linksForRoot(kit.rootId).find((r) => r.relPath === rel);
+  assert.ok(row, `expected a link row at ${rel}`);
+  return row.linkId;
+}
+
+module.exports = {
+  cleanup, converged, defaultPolicy, fakeWatchKit, fileIdAt,
+  linkIdAt, makeKit, sleep,
+};