amalgm 0.1.245 → 0.1.246

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

@@ -0,0 +1,497 @@
+'use strict';
+
+/**
+ * The quiet-point verdict — every assertion the oracle makes, in one place.
+ *
+ * Four witnesses must tell one story at every proven quiet point:
+ *   the operation model (graph.js)   — what the test actually did,
+ *   the disk referee   (referee.js)  — what disk actually holds,
+ *   the detector slice (adapter.js)  — what the observer believes,
+ *   the event ledger   (ledger.js)   — what the observer ever claimed.
+ *
+ * Model vs referee catches a drifting test. The records block judges every
+ * field of every six-field record the model holds — unique identity, one
+ * parentless root (the workspace, or the repo the lens makes of it),
+ * addresses that re-derive through the parent chain, departed records that
+ * persist untouched, and versions (membership payloads and canonical
+ * envelopes alike) that recompute from the records + evidence alone.
+ * Lifecycle is EXPLICIT registry law and detection never writes it: every
+ * record here must be `active`, and a status that moved is a conviction.
+ * The git lens is derived independently — covered when any ancestor is a
+ * repo, never a stored rollup — and the exposed slice is exactly the
+ * present, uncovered files. An active entity owns its (parent, name) slot,
+ * so at most one active child per name — reappearing ground reconnects,
+ * never doubles. Only containers (workspace, folder, repo.git) hold active
+ * children, so ground the canonical graph refuses — a file swapped onto an
+ * occupied folder's slot, or CONTESTED ground carrying two identity claims
+ * at once — must be accounted as entity-less DIVERGENCE: reported, claimed
+ * by nobody, records unmoved. Slice vs referee catches a blind detector.
+ * Ledger vs slice catches a lying event stream. The channel binder follows
+ * the channel law's four sentences: one channel claims at most one entity;
+ * an entity may temporarily hold several channels; only one stands as its
+ * canonical ground; and every other live claim must be reported contest or
+ * an honestly closed channel — whose id never rises again. Emitted-truth
+ * is judged per entity — or at the address the channel claimed, which is
+ * where contested ground and never-settled transients answer. The closing
+ * re-scan proves catch-up convergence: a settled detector, asked again,
+ * says nothing.
+ *
+ * Two modes, named for what they prove:
+ *   { scan: true }  — catch-up: the verdict drives a scan and the registry
+ *                     intake's reconciliation, then judges.
+ *   { scan: false } — event-only: detection must already be true; the
+ *                     referee stays read-only, no scan is invoked, and the
+ *                     doorbell-driven registry intake must already have
+ *                     converged — the verdict never repairs what it judges.
+ */
+
+const assert = require('node:assert/strict');
+const crypto = require('node:crypto');
+const path = require('path');
+
+const { detectorSlice, registrySlice } = require('./adapter');
+const { allBoundaries, readGround } = require('./referee');
+
+const sha256 = (bytes) => crypto.createHash('sha256').update(bytes).digest('hex');
+
+const FILE_TYPES = new Set(['file.text', 'file.binary']);
+
+/**
+ * Judge the model's records on their own terms, so a drifted model cannot
+ * hide behind the narrower slice today's detector claims. Returns the
+ * derived view (address + lens coverage per uuid) and the stored-active
+ * membership pairs per container, for the identity and version checks
+ * downstream.
+ */
+function assertRecords(snap) {
+  const byUuid = new Map();
+  for (const record of snap.records) {
+    assert.ok(!byUuid.has(record.uuid), `oracle: two records share the uuid ${record.uuid}`);
+    // Lifecycle (active | trashed | deleted) moves only by explicit
+    // registry action — trash, restore, empty-trash. Detection performs
+    // none, these tests perform none, so a non-active status IS the
+    // conviction: something inferred lifecycle from disk.
+    assert.equal(record.status, 'active',
+      `oracle: record ${record.uuid} is "${record.status}" — detection never writes lifecycle`);
+    assert.ok(snap.payloads.has(record.uuid),
+      `oracle: record ${record.uuid} has no payload evidence`);
+    if (record.type === 'repo.git') {
+      assert.equal(snap.payloads.get(record.uuid), null,
+        'oracle: repo.git payload is null-gated until card/checkpoint evidence is adapted');
+    }
+    byUuid.set(record.uuid, record);
+  }
+
+  const roots = snap.records.filter((record) => record.parentUUID === null);
+  assert.equal(roots.length, 1, 'oracle: exactly one parentless record must root the graph');
+  assert.ok(roots[0].type === 'workspace' || roots[0].type === 'repo.git',
+    'oracle: the root record is the workspace — or the repo the lens makes of it');
+
+  // One parent may have at most one ACTIVE child with a given name: an
+  // active entity owns its slot, present or absent, so reappearing ground
+  // must reconnect — a second active claimant is a conviction. (Every
+  // record here is active; when registry actions exist, this filters.)
+  // And only CONTAINERS hold active children: an active child hanging
+  // from a file-typed parent means an invalid type transition was
+  // canonicalized.
+  const CONTAINERS = new Set(['workspace', 'folder', 'repo.git']);
+  const slots = new Set();
+  for (const record of snap.records) {
+    if (record.parentUUID === null || record.status !== 'active') continue;
+    const parent = byUuid.get(record.parentUUID);
+    assert.ok(parent && CONTAINERS.has(parent.type),
+      `oracle: active entity ${record.uuid} hangs from a non-container — only workspace, folder, and repo.git may hold active children`);
+    const slot = `${record.parentUUID}\0${record.name}`;
+    assert.ok(!slots.has(slot),
+      `oracle: two active entities claim one slot — "${record.name}" under ${record.parentUUID}`);
+    slots.add(slot);
+  }
+
+  // Walk each record to the root once: address and lens coverage both
+  // derive from the same chain — never from a stored rollup.
+  const derived = new Map(); // uuid -> { address, covered }
+  const derive = (record) => {
+    if (derived.has(record.uuid)) return derived.get(record.uuid);
+    const names = [];
+    let covered = false;
+    let current = record;
+    while (current.parentUUID !== null) {
+      names.unshift(current.name);
+      assert.ok(names.length <= byUuid.size, 'oracle: the parent graph has a cycle');
+      const parent = byUuid.get(current.parentUUID);
+      assert.ok(parent, `oracle: record ${current.uuid} names a parent with no record`);
+      if (parent.type === 'repo.git') covered = true;
+      current = parent;
+    }
+    const view = { address: names.join('/'), covered };
+    derived.set(record.uuid, view);
+    return view;
+  };
+  for (const record of snap.records) derive(record);
+
+  // The exposed slice ⇔ exactly the locally-present, uncovered files.
+  // Presence is evidence beside the records: a departed entity's record is
+  // untouched, it simply is not here.
+  const exposed = snap.records.filter((record) => {
+    if (!FILE_TYPES.has(record.type)) return false;
+    return snap.present.has(record.uuid) && !derived.get(record.uuid).covered;
+  });
+  assert.equal(exposed.length, snap.files.size,
+    'oracle: exposed file records and the model file slice disagree in count');
+  for (const record of exposed) {
+    const rel = derived.get(record.uuid).address;
+    const slot = snap.files.get(rel);
+    assert.ok(slot, `oracle: record ${record.uuid} derives address ${rel}, which the model does not hold`);
+    assert.equal(slot.uuid, record.uuid, `oracle: record and file slice disagree on who owns ${rel}`);
+    assert.equal(snap.payloads.get(record.uuid), slot.hash,
+      `oracle: payload evidence drifted from content at ${rel}`);
+  }
+  // And the same for pointer ground: exposed link records ⇔ the link slice,
+  // payload the written target.
+  const exposedLinks = snap.records.filter((record) => record.type === 'link'
+    && snap.present.has(record.uuid) && !derived.get(record.uuid).covered);
+  assert.equal(exposedLinks.length, snap.links.size,
+    'oracle: exposed link records and the model link slice disagree in count');
+  for (const record of exposedLinks) {
+    const rel = derived.get(record.uuid).address;
+    const slot = snap.links.get(rel);
+    assert.ok(slot, `oracle: link record ${record.uuid} derives address ${rel}, which the model does not hold`);
+    assert.equal(slot.uuid, record.uuid, `oracle: record and link slice disagree on who owns ${rel}`);
+    assert.equal(snap.payloads.get(record.uuid), slot.target,
+      `oracle: payload evidence drifted from the written target at ${rel}`);
+  }
+
+  // Both halves of the version formula recompute from records + evidence.
+  // Membership counts stored-active children — a locally-absent child is
+  // still a child, which is why a disappearance moves no record.
+  const memberships = new Map();
+  for (const record of snap.records) {
+    if (record.status !== 'active' || record.parentUUID === null) continue;
+    if (!memberships.has(record.parentUUID)) memberships.set(record.parentUUID, []);
+    memberships.get(record.parentUUID).push([record.uuid, record.name]);
+  }
+  for (const record of snap.records) {
+    if (record.type === 'folder' || record.type === 'workspace') {
+      assert.equal(snap.payloads.get(record.uuid),
+        sha256(JSON.stringify((memberships.get(record.uuid) ?? []).sort())),
+        `oracle: membership version of ${record.uuid} does not recompute from its stored-active children`);
+    }
+    assert.equal(record.version,
+      sha256(JSON.stringify(
+        [record.type, record.parentUUID, record.name, record.status, snap.payloads.get(record.uuid)])),
+      `oracle: canonical version of ${record.uuid} does not recompute from its fields + evidence`);
+  }
+
+  return { derived, memberships };
+}
+
+function assertQuietPoint(kit, { scan = true } = {}) {
+  const { observer, events, model, ledger, binder, rootPath, rootId, policy, cursor } = kit;
+
+  if (scan) observer.scanNow(rootId);
+  // A quiet point is a consumer lifecycle moment — but only CATCH-UP mode
+  // may reconcile here (the ratified startup/flush comparison). Event-only
+  // mode judges without helping: the doorbell-driven intake must already
+  // have converged, or a missed observer→registry doorbell would be
+  // silently repaired by the referee and never convicted.
+  if (kit.evidence) {
+    if (scan) kit.evidence.reconcile();
+    else {
+      assert.equal(kit.evidence.dirty(), false,
+        'oracle: the event-driven intake had not converged — its scheduled reconciliation failed and no one may repair it here');
+    }
+  }
+
+  const snap = model.settle();
+  const truth = readGround(rootPath, policy);
+  const boundaries = allBoundaries(rootPath, policy);
+
+  // --- the two independent truths must agree, or the test itself is wrong.
+  // Disk = entity ground ∪ divergence: every on-disk file is either an
+  // entity's ground or reported entity-less divergence — never unaccounted.
+  for (const [relPath, hash] of truth.files) {
+    const expected = snap.files.get(relPath);
+    if (expected) {
+      assert.equal(expected.hash, hash, `oracle: model hash for ${relPath} drifted from disk`);
+    } else {
+      assert.equal(snap.divergent.get(relPath), hash,
+        `oracle: model missing ${relPath} — neither an entity's ground nor reported divergence`);
+    }
+  }
+  for (const relPath of snap.files.keys()) {
+    assert.ok(truth.files.has(relPath), `oracle: model believes in ${relPath}, disk does not`);
+  }
+  // Pointer ground under the same accounting: every on-disk symlink is a
+  // link entity's ground or reported divergence, never unaccounted.
+  for (const [relPath, target] of truth.links) {
+    const expected = snap.links.get(relPath);
+    if (expected) {
+      assert.equal(expected.target, target, `oracle: model target for ${relPath} drifted from disk`);
+    } else {
+      assert.equal(snap.divergent.get(relPath), target,
+        `oracle: model missing link ${relPath} — neither an entity's ground nor reported divergence`);
+    }
+  }
+  for (const relPath of snap.links.keys()) {
+    assert.ok(truth.links.has(relPath), `oracle: model believes in link ${relPath}, disk does not`);
+  }
+  // Directories are ground too: every on-disk directory is an entity's
+  // ground or reported divergence, never unaccounted — and never a ghost.
+  for (const relDir of truth.dirs) {
+    assert.ok(snap.dirs.has(relDir) || snap.divergent.has(relDir),
+      `oracle: model missing directory ${relDir} — neither an entity's ground nor reported divergence`);
+  }
+  for (const relDir of snap.dirs.keys()) {
+    assert.ok(truth.dirs.has(relDir), `oracle: model believes in directory ${relDir}, disk does not`);
+  }
+  for (const relPath of snap.divergent.keys()) {
+    assert.ok(truth.files.has(relPath) || truth.links.has(relPath) || truth.dirs.has(relPath),
+      `oracle: model claims divergent ground at ${relPath}, disk holds nothing`);
+    assert.ok(!snap.files.has(relPath) && !snap.links.has(relPath) && !snap.dirs.has(relPath),
+      `oracle: ${relPath} is claimed as entity ground AND divergence at once`);
+  }
+  const modelBounds = [...snap.territories]
+    .map((rel) => (rel === '' ? rootPath : path.join(rootPath, rel)))
+    .sort();
+  assert.deepEqual(modelBounds, boundaries, 'oracle: model territories drifted from disk');
+
+  // --- every field of every record is judged; lifecycle + lens derive here
+  const { derived, memberships } = assertRecords(snap);
+
+  // --- detector slice vs disk truth
+  const slice = detectorSlice(observer, rootId, rootPath);
+  assert.ok(slice.root, 'oracle: the enrolled root vanished from the store');
+  for (const [relPath, hash] of truth.files) {
+    const claimed = slice.files.get(relPath);
+    assert.ok(claimed, `oracle: detector never saw ${relPath} (missing channel)`);
+    assert.equal(claimed.version, hash, `oracle: detector is stale at ${relPath}`);
+  }
+  for (const relPath of slice.files.keys()) {
+    assert.ok(truth.files.has(relPath), `oracle: detector believes a ghost at ${relPath}`);
+  }
+  for (const [relPath, target] of truth.links) {
+    const claimed = slice.links.get(relPath);
+    assert.ok(claimed, `oracle: detector never saw link ${relPath} (missing channel)`);
+    assert.equal(claimed.target, target, `oracle: detector is stale at link ${relPath}`);
+  }
+  for (const relPath of slice.links.keys()) {
+    assert.ok(truth.links.has(relPath), `oracle: detector believes a ghost link at ${relPath}`);
+  }
+  for (const relDir of truth.dirs) {
+    assert.ok(slice.dirs.has(relDir), `oracle: detector never saw directory ${relDir} (missing channel)`);
+  }
+  for (const relDir of slice.dirs.keys()) {
+    assert.ok(truth.dirs.has(relDir), `oracle: detector believes a ghost directory at ${relDir}`);
+  }
+  assert.deepEqual(slice.territories, boundaries,
+    'oracle: detector territory set diverges from the census referee');
+
+  // --- the ledger replays the fresh events
+  const fresh = events.slice(cursor.value);
+  ledger.ingest(fresh);
+  cursor.value = events.length;
+
+  // --- the event stream and the store must tell one story
+  const believed = ledger.liveFiles(rootId);
+  for (const [relPath, { fileId, hash }] of believed) {
+    const claimed = slice.files.get(relPath);
+    assert.ok(claimed, `oracle: events say ${relPath} lives, the store does not`);
+    assert.equal(claimed.uuid, fileId, `oracle: events and store disagree on the identity at ${relPath}`);
+    assert.equal(claimed.version, hash, `oracle: events and store disagree on the version at ${relPath}`);
+  }
+  for (const relPath of slice.files.keys()) {
+    assert.ok(believed.has(relPath), `oracle: the store believes ${relPath} without events to justify it`);
+  }
+  const believedLinks = ledger.liveLinks(rootId);
+  for (const [relPath, { linkId, target }] of believedLinks) {
+    const claimed = slice.links.get(relPath);
+    assert.ok(claimed, `oracle: events say link ${relPath} lives, the store does not`);
+    assert.equal(claimed.uuid, linkId, `oracle: events and store disagree on the identity at link ${relPath}`);
+    assert.equal(claimed.target, target, `oracle: events and store disagree on the target at ${relPath}`);
+  }
+  for (const relPath of slice.links.keys()) {
+    assert.ok(believedLinks.has(relPath), `oracle: the store believes link ${relPath} without events to justify it`);
+  }
+  const believedDirs = ledger.liveDirs(rootId);
+  for (const [relPath, { dirId }] of believedDirs) {
+    const claimed = slice.dirs.get(relPath);
+    assert.ok(claimed, `oracle: events say directory ${relPath} lives, the store does not`);
+    assert.equal(claimed.uuid, dirId, `oracle: events and store disagree on the identity at directory ${relPath}`);
+  }
+  for (const relPath of slice.dirs.keys()) {
+    assert.ok(believedDirs.has(relPath), `oracle: the store believes directory ${relPath} without events to justify it`);
+  }
+  const ledgerBounds = [...ledger.liveTerritories().keys()]
+    .filter((abs) => abs === rootPath || abs.startsWith(`${rootPath}/`))
+    .sort();
+  assert.deepEqual(ledgerBounds, boundaries, 'oracle: event-stream territories diverge from disk');
+
+  // --- identity: the channel law's accounting, kind-blind. Canonical
+  // claims are observed from the exposed slices; then EVERY live claim
+  // must be exactly one of — canonical ground at its entity's own address,
+  // contested ground the model attributes to that same entity, or a
+  // channel that closed honestly (and is retired forever). Channels are
+  // evidence; entities are identity — a record never moves for any of this.
+  for (const [relPath, { uuid }] of snap.files) {
+    binder.observe(uuid, slice.files.get(relPath).uuid, ` at ${relPath}`);
+  }
+  for (const [relPath, { uuid }] of snap.links) {
+    binder.observe(uuid, slice.links.get(relPath).uuid, ` at link ${relPath}`);
+  }
+  for (const [relPath, { uuid }] of snap.dirs) {
+    binder.observe(uuid, slice.dirs.get(relPath).uuid, ` at directory ${relPath}`);
+  }
+  const channelPlace = new Map(); // live channel -> its address in the store
+  for (const [relPath, claimed] of slice.files) channelPlace.set(claimed.uuid, relPath);
+  for (const [relPath, claimed] of slice.links) channelPlace.set(claimed.uuid, relPath);
+  for (const [relPath, claimed] of slice.dirs) channelPlace.set(claimed.uuid, relPath);
+  for (const [channelId, nodeUuid] of binder.claims()) {
+    const at = channelPlace.get(channelId);
+    if (at !== undefined
+      && (snap.files.get(at)?.uuid === nodeUuid
+        || snap.links.get(at)?.uuid === nodeUuid
+        || snap.dirs.get(at)?.uuid === nodeUuid)) continue; // canonical ground
+    if (at !== undefined && snap.contested.get(at) === nodeUuid) continue; // reported contest — resolves nothing
+    assert.ok(ledger.isDeleted(channelId),
+      `oracle: channel ${channelId} of entity ${nodeUuid} is neither canonical ground, nor reported contest, nor honestly closed`);
+    binder.retire(channelId);
+  }
+  const retired = binder.retiredIds();
+  for (const [relPath, claimed] of slice.files) {
+    assert.ok(!retired.has(claimed.uuid),
+      `oracle: retired identity ${claimed.uuid} still lives in the store at ${relPath}`);
+  }
+  for (const [relPath, claimed] of slice.links) {
+    assert.ok(!retired.has(claimed.uuid),
+      `oracle: retired identity ${claimed.uuid} still lives in the store at link ${relPath}`);
+  }
+  for (const [relPath, claimed] of slice.dirs) {
+    assert.ok(!retired.has(claimed.uuid),
+      `oracle: retired identity ${claimed.uuid} still lives in the store at directory ${relPath}`);
+  }
+
+  // --- emitted-truth: a version claimed for a channel must have been true
+  // for THAT channel's entity. The address answers instead only where the
+  // entity has no history to answer with: contested ground the model
+  // attributes to this same claimant at either boundary of the just-closed
+  // interval — a contest moves with its ground mid-interval, and an honest
+  // event at the old address answers with the boundary it fired under —
+  // and a channel born and dead inside one interval, never settled, never
+  // bound. An uncontested bound channel gets no address escape: bytes true
+  // at an address it claimed but under someone else's tenure are still a
+  // lie about this entity.
+  for (const event of fresh) {
+    if (event.type === 'file.created' || event.type === 'file.changed') {
+      const nodeUuid = binder.nodeOf(event.fileId);
+      if (nodeUuid !== undefined) {
+        assert.ok(
+          model.nodeEverTrue(nodeUuid, event.hash)
+            || (model.addressContestedFor(event.path, nodeUuid) && model.addressEverTrue(event.path, event.hash)),
+          `oracle: ${event.path} emitted a version never true for that entity nor at its contested ground`);
+      } else {
+        assert.ok(model.addressEverTrue(event.path, event.hash),
+          `oracle: ${event.path} emitted a version never true at that address — short-lived channels may not lie either`);
+      }
+    } else if (event.type === 'link.created' || event.type === 'link.changed') {
+      // The same law for pointer ground: a claimed target must have been
+      // written for THAT channel's entity — or at the address, where the
+      // entity has no history to answer with.
+      const nodeUuid = binder.nodeOf(event.linkId);
+      if (nodeUuid !== undefined) {
+        assert.ok(
+          model.nodeEverTrue(nodeUuid, event.target)
+            || (model.addressContestedFor(event.path, nodeUuid) && model.addressLinkEverTrue(event.path, event.target)),
+          `oracle: link ${event.path} emitted a target never written for that entity nor at its contested ground`);
+      } else {
+        assert.ok(model.addressLinkEverTrue(event.path, event.target),
+          `oracle: link ${event.path} emitted a target never written at that address — short-lived channels may not lie either`);
+      }
+    }
+  }
+
+  // --- the registry: durable records judged against model truth — root
+  // identity, file AND folder records, repo.git territory transitions,
+  // and divergence. Folder detection put folder identity inside the
+  // slice: a folder record answers for its own uuid across directory
+  // renames, and its membership version recomputes from the model's
+  // stored-active pairs translated through the identity binding. Model
+  // uuid ↔ registry uuid rides an observe-only binder: records are
+  // permanent identity, so a registry rebind — a reconnect that minted a
+  // second entity — is a conviction.
+  if (kit.registry) {
+    const reg = registrySlice(kit.registry, kit.evidence);
+    const modelRoot = snap.records.find((record) => record.parentUUID === null);
+    assert.ok(reg.root, 'oracle: the registry holds no root record');
+    kit.registryBinder.observe(modelRoot.uuid, reg.root.uuid, ' at the enrolled root');
+    assert.equal(reg.root.type, modelRoot.type,
+      'oracle: the registry root must ride the lens on its own uuid — workspace ↔ repo.git with the model');
+    assert.equal(reg.root.status, 'active',
+      'oracle: the registry wrote lifecycle on the root — detection never does');
+    // Identity first, judgment second: every compared record is bound
+    // before any container's membership recomputes, because membership
+    // pairs translate model uuids through this very binding.
+    const compared = [];
+    for (const record of snap.records) {
+      if (record.parentUUID === null) continue;
+      if (!FILE_TYPES.has(record.type) && record.type !== 'repo.git'
+        && record.type !== 'folder' && record.type !== 'link') continue;
+      const view = derived.get(record.uuid);
+      if (view.covered) continue; // under the lens: card evidence is not adapted yet
+      const regRec = reg.recordAtPath(view.address);
+      assert.ok(regRec, `oracle: the registry holds no record at ${view.address}`);
+      kit.registryBinder.observe(record.uuid, regRec.uuid, ` at ${view.address}`);
+      compared.push({ record, regRec, view });
+    }
+    const translated = (modelUuid, regUuid) => {
+      const pairs = (memberships.get(modelUuid) ?? []).map(([childUuid, name]) => {
+        const bound = kit.registryBinder.boundOf(childUuid);
+        assert.ok(bound !== undefined,
+          `oracle: container ${modelUuid} counts child ${childUuid} that no registry record answered for`);
+        return [bound, name];
+      });
+      // Registry children no model node answers for are records born of
+      // observation FINER than the model's settle points: a transient that
+      // lived and died inside one interval was truthfully observed and
+      // birthed, and explicit-only lifecycle keeps its record forever.
+      // They join the expected membership as the registry's own pairs —
+      // extras, never replacements: a registry record standing in for a
+      // model-known entity is a rebind the identity binder convicts, and
+      // a missing or misparented model child still breaks this recompute.
+      for (const [childUuid, name] of reg.activeChildren(regUuid)) {
+        if (kit.registryBinder.nodeOfBound(childUuid) === undefined) pairs.push([childUuid, name]);
+      }
+      return sha256(JSON.stringify(pairs.sort()));
+    };
+    for (const { record, regRec, view } of compared) {
+      assert.equal(regRec.type, record.type,
+        `oracle: registry type drifted from the model at ${view.address}`);
+      assert.equal(regRec.status, 'active',
+        `oracle: the registry wrote lifecycle at ${view.address} — detection never does`);
+      const payload = record.type === 'folder' ? translated(record.uuid, regRec.uuid) : snap.payloads.get(record.uuid);
+      assert.equal(regRec.version, sha256(JSON.stringify(
+        [regRec.type, regRec.parentUUID, regRec.name, regRec.status, payload])),
+      `oracle: registry version at ${view.address} does not recompute from its record + the model's payload evidence`);
+    }
+    const rootPayload = modelRoot.type === 'workspace' ? translated(modelRoot.uuid, reg.root.uuid) : null;
+    assert.equal(reg.root.version, sha256(JSON.stringify(
+      [reg.root.type, null, reg.root.name, reg.root.status, rootPayload])),
+    'oracle: registry root version does not recompute from its record + translated membership');
+    assert.deepEqual([...reg.divergence].sort(), [...snap.divergent].sort(),
+      'oracle: registry divergence and model divergence must be one report');
+  }
+
+  // --- catch-up convergence: a settled detector, asked again, says
+  // nothing. (repo.changed is a raw catch-up doorbell, not a state claim.)
+  if (scan) {
+    const before = events.length;
+    observer.scanNow(rootId);
+    const noise = events.slice(before).filter((event) => event.type !== 'repo.changed');
+    assert.deepEqual(noise, [], 'oracle: the detector had not converged — a second scan still spoke');
+    ledger.ingest(events.slice(before));
+    cursor.value = events.length;
+  }
+
+  return snap;
+}
+
+module.exports = { assertQuietPoint };

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

@@ -0,0 +1,91 @@
+'use strict';
+
+/**
+ * Binding — the identity half of the oracle's verdict. Two different laws,
+ * so two binders, neither carrying exceptions:
+ *
+ * `createBinder` is PERMANENT identity, strictly one-to-one: model entity ↔
+ * registry uuid, bound at first observation, forever. A bound pair that
+ * changes on either side is a conviction — a registry that minted a second
+ * record for one entity, or reused one record for two.
+ *
+ * `createChannelBinder` is EVIDENCE, and follows the channel law's four
+ * sentences: one channel claims at most one entity, ever. An entity may
+ * temporarily hold several evidence channels. Only one channel may stand
+ * as its canonical ground. Every other live claim must be accounted as
+ * reported divergence — or the channel must have closed honestly. The
+ * binder holds the claims; the judge runs that accounting at every quiet
+ * point and retires channels it proves closed. A retired id surfacing
+ * anywhere again is a resurrection, which the axioms forbid.
+ */
+
+const assert = require('node:assert/strict');
+
+/** Permanent one-to-one identity (model record ↔ registry record). */
+function createBinder() {
+  const forward = new Map(); // nodeId -> boundId
+  const reverse = new Map();
+
+  return {
+    observe(nodeId, boundId, context = '') {
+      const bound = forward.get(nodeId);
+      if (bound !== undefined) {
+        assert.equal(boundId, bound,
+          `identity broke${context}: node ${nodeId} was ${bound}, now claimed as ${boundId}`);
+        return;
+      }
+      const previous = reverse.get(boundId);
+      assert.equal(previous, undefined,
+        `identity stolen${context}: ${boundId} already belongs to node ${previous}`);
+      forward.set(nodeId, boundId);
+      reverse.set(boundId, nodeId);
+    },
+
+    /** The bound identity for a node (undefined if never observed) — lets
+     * the judge translate model uuids in derived payloads (container
+     * membership) into the bound side's uuids. */
+    boundOf: (nodeId) => forward.get(nodeId),
+
+    /** The node a bound identity answers for (undefined if unbound) — how
+     * the judge tells a record the model knows from one born of finer
+     * observation than the model's settle points. */
+    nodeOfBound: (boundId) => reverse.get(boundId),
+  };
+}
+
+/** Channel claims (detector fileId → model entity), many-to-one by law. */
+function createChannelBinder() {
+  const claims = new Map(); // fileId -> nodeId
+  const retired = new Set();
+
+  return {
+    /** A channel observed standing for an entity's ground. */
+    observe(nodeId, fileId, context = '') {
+      assert.ok(!retired.has(fileId),
+        `a tombstoned identity rose again${context}: ${fileId}`);
+      const prior = claims.get(fileId);
+      if (prior !== undefined) {
+        assert.equal(nodeId, prior,
+          `identity broke${context}: channel ${fileId} claimed ${prior}, detector now says ${nodeId}`);
+        return;
+      }
+      claims.set(fileId, nodeId);
+    },
+
+    /** Every live claim, for the judge's per-point accounting. */
+    claims: () => [...claims],
+
+    /** The judge proved this channel closed: it must never rise again. */
+    retire(fileId) {
+      claims.delete(fileId);
+      retired.add(fileId);
+    },
+
+    /** Which entity this channel claims (undefined if never claimed). */
+    nodeOf: (fileId) => claims.get(fileId),
+
+    retiredIds: () => new Set(retired),
+  };
+}
+
+module.exports = { createBinder, createChannelBinder };