amalgm 0.1.245 → 0.1.246

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

@@ -0,0 +1,1031 @@
+'use strict';
+
+/**
+ * The operation model — one of the oracle's two independent truths
+ * (docs/entity-model.md; the other is the disk referee in referee.js).
+ *
+ * The test performs a real filesystem operation and records it here. The
+ * model keeps its own simulated disk (paths → content hash + a physical
+ * continuity tag standing in for device:inode, for directories too) and, at
+ * each settle point, applies the written identity axioms to the NET state —
+ * never per-op, because identity is only ever resolved at proven quiet
+ * points:
+ *
+ *   1. Address and physical continuity are the two identity witnesses, and
+ *      KIND decides which testifies first. For files, path claims the
+ *      channel — an atomic save replaces the physical file under a
+ *      standing address, so the address must absorb that churn — and
+ *      exactly-one physical continuity rescues path-orphans. For
+ *      directories the same rules run in the OPPOSITE order: nothing
+ *      replaces a directory's inode in place, so physical continuity
+ *      claims first (two directories exchanging names cross by inode,
+ *      exactly like the files inside them) and the address claims only
+ *      recreation — a never-seen inode at a known address is the same
+ *      channel wearing a new tag.
+ *   2. Continuity moves a record — exactly one candidate on each side, or
+ *      nothing is guessed — and only onto UNOWNED ground.
+ *      Continuity arriving on a parked ACTIVE owner's slot is CONTESTED
+ *      GROUND: two established identity claims on one address, and the
+ *      model picks no winner — neither record moves, the ground is
+ *      reported divergence, carried by ADDRESS continuity within the
+ *      ground's kind (an atomic replace keeps it, exactly like path
+ *      claims; a file replaced by a directory has left) until the ground
+ *      leaves the address or an explicit identity-carrying action
+ *      resolves it. Reappearance at the claimant's old address resolves
+ *      nothing — presence proves nothing about identity — and losing
+ *      evidence never resolves a contest. Folder ground carries a channel
+ *      now, so the folder half of this rule is LIVE — and an address that
+ *      runs through contested ground is itself contested for whatever
+ *      claimant sits there: a moved subtree's children cannot be lawfully
+ *      addressed while their parent's ground is undecided.
+ *   3. Leftover appearances are births. A leftover disappearance is
+ *      EVIDENCE, never lifecycle: the channel closes, the entity leaves
+ *      local ground, and its record does not move. Status (active |
+ *      trashed | deleted) is registry law, changed only by explicit owner
+ *      actions — trash, restore, empty-trash — which detection may never
+ *      infer from disk. No explicit action exists in these tests, so every
+ *      record here stays `active` forever.
+ *   4. An ACTIVE entity owns its (parent, name) slot, present or absent —
+ *      one parent has at most one active child with a given name. Ground
+ *      reappearing at the slot reconnects to the same uuid — WHATEVER kind
+ *      it returns as: ownership is identity, not kind, so folder ground at
+ *      a file-owned slot (or the reverse) is a type transition on the same
+ *      uuid, even when the swap happens inside a single interval. New bytes
+ *      are absorbed as the owner's edit (production accepts them or resets
+ *      from canonical). Only an explicit trash/delete vacates a slot for a
+ *      new entity — and no explicit action exists in these tests, so
+ *      reappearance here always reconnects. Restoration from trash stays
+ *      explicit, never inferred.
+ *   5. Git is a LENS, not a lifecycle boundary: a .git appearing flips the
+ *      folder's type to repo.git on the SAME uuid — including at the
+ *      enrolled root, where the record flips workspace ↔ repo.git — and
+ *      every entity under it keeps existing with its identity. Exactly one
+ *      adapter owns detection at a time: under the lens the repo adapter
+ *      owns the subtree; lift the lens and file detection returns. Covered
+ *      ground is therefore UNWITNESSED by leaf detection — no leaf entity
+ *      is born under the lens, and physical continuity never crosses the
+ *      boundary. Entities whose ground the lens covers park with their
+ *      records untouched; the slot law reconnects them when the lens
+ *      lifts, and ground first written under the lens surfaces as a NEW
+ *      entity at the lift. (Today's detector re-mints its low-level
+ *      channels at these boundaries; channels are evidence, and the judge
+ *      absorbs that at the binder, never in the model.)
+ *   6. Only CONTAINERS — workspace, folder, repo.git — hold active
+ *      children. Identity survives every VALID type transition; a folder
+ *      that still has stored-active children may not become a file, because
+ *      accepting that flip would canonicalize the subtree destruction that
+ *      axiom 3 already refused to infer. File ground landing on such a slot
+ *      is DIVERGENCE: reported honestly (the channel and its events are
+ *      real), claimed by no entity, canonical records unmoved, pending
+ *      explicit resolution — amalgm resets local from canonical, or the
+ *      owner moves/trashes the children first.
+ *   7. A LINK is leaf ground whose whole payload is its target exactly as
+ *      written — never what it reaches. Its identity follows the FILE
+ *      rules for the file reason: a symlink cannot be retargeted in place
+ *      (retarget is unlink + recreate), so the address absorbs that churn
+ *      and claims first, and exactly-one physical continuity rescues
+ *      path-orphans (`mv` preserves a symlink's inode). Links are a THIRD
+ *      ground kind: continuity never crosses kinds, a contest carries by
+ *      address continuity within link kind, and slot ownership stays
+ *      identity-not-kind — ground of any kind returning at an owned slot
+ *      is a type transition on the same uuid, container guard included.
+ *
+ * Every settled entity is EXACTLY the six-field universal record —
+ * { uuid, type, parentUUID, name, version, status } — with folders resolved
+ * first so files derive real parent UUIDs. Payloads (content hash,
+ * membership, the repo card) are adapter EVIDENCE, returned in a separate
+ * map keyed by uuid, never stored inside the record. Versions follow the
+ * ratified formula hash(type, parentUUID, name, status, payloadVersion); a
+ * container's payload is its sorted STORED-active direct membership as
+ * (childUUID, name) pairs. A locally-absent entity is still an active
+ * child — its restore is the registry's business — which is why a
+ * disappearance changes NO record at all. repo.git payload is null until
+ * the card/checkpoint evidence is adapted (a documented gate, not a
+ * formula).
+ *
+ * File type (file.text | file.binary) comes from the INJECTED classify
+ * policy, exactly like enrollment comes from the injected shouldEnroll:
+ * explicit policy decides, the model never owns a heuristic. A classify
+ * flip is a type transition on the same uuid.
+ *
+ * Truth is tracked per address between settles and absorbed into the owning
+ * entity at each settle; the just-closed interval stays queryable per
+ * address, so even a channel born and dead between settles is judged at the
+ * address it claimed — no global pool.
+ *
+ * KNOWN GATE: enrollment inside repo ground uses the root-relative policy
+ * while the boundary census re-scopes per boundary — settles with the
+ * registry.
+ *
+ * Deliberately shares no code with the detector: this file must not require
+ * anything from observer/ or repocard/ (enforced by a meta-test).
+ */
+
+const crypto = require('crypto');
+
+function sha256(bytes) {
+  return crypto.createHash('sha256').update(bytes).digest('hex');
+}
+
+function createModel({ shouldEnroll, classify }) {
+  if (typeof shouldEnroll !== 'function' || typeof classify !== 'function') {
+    throw new Error('createModel requires the injected enrollment and classification policies');
+  }
+
+  let nextNode = 1;
+  let nextTag = 1;
+
+  // Simulated disk.
+  const diskFiles = new Map(); // relPath -> { hash, tag, type }
+  const diskLinks = new Map(); // relPath -> { target, tag }
+  const diskDirs = new Map(); // relDir -> { tag } ('' is the workspace, never listed)
+  const gitDirs = new Set(); // dirs holding a .git ('' = the root itself)
+
+  // Settled entities. Nodes that leave the live maps stay forever; frozen
+  // holds the record fields as of the settle that parked them.
+  const workspace = { uuid: `w${nextNode++}` };
+  const fileNodes = new Map(); // uuid -> { uuid, relPath, hash, tag, type, status, history:Set, frozen? }
+  const fileByPath = new Map(); // relPath -> uuid, on-disk only
+  const linkNodes = new Map(); // uuid -> { uuid, relPath, target, tag, type: 'link', status, history:Set, frozen? }
+  const linkByPath = new Map(); // relPath -> uuid, on-disk only
+  const folderNodes = new Map(); // uuid -> { uuid, relDir, tag, type, status, frozen? }
+  const folderByPath = new Map(); // relDir -> uuid, on-disk only
+
+  // Truth: per-address for the open interval, absorbed per-entity at
+  // settle; the just-closed interval stays queryable for channels that
+  // never lived long enough to settle. Link ground keeps its own truth
+  // space — a pointer's payload is an address, never a content hash.
+  let pathTruth = new Map(); // relPath -> Set(hash)
+  let lastTruth = new Map();
+  let linkTruth = new Map(); // relPath -> Set(target)
+  let lastLinkTruth = new Map();
+
+  // Leaf addresses that held visible same-kind ground as of the last
+  // settle — entity ground, divergence, and contested ground alike. The
+  // address absorbs replacement at the CHANNEL layer: ground arriving
+  // where same-kind ground already stood is absorbed by whatever channel
+  // stands there, so the arriving file's own channel dies — physical
+  // continuity cannot rescue a node ONTO standing ground.
+  let leafGroundAtOpen = { file: new Set(), link: new Set() };
+
+  // Contested ground: two identity claims on one address (axiom 2 meeting
+  // axiom 4). Keyed by address, valued with the claimant, the ground's
+  // physical tag — bookkeeping for the claimant's still-open channel,
+  // refreshed while the contest stands — and the ground's KIND, because a
+  // contest carries by address continuity within its kind only.
+  const contestedGround = new Map(); // relPath -> { uuid, tag, kind: 'file' | 'dir' }
+  let contestedAtOpen = new Map(); // relPath -> claimant uuid, as the interval opened
+
+  /** Does this address run through contested ground (itself included)? */
+  function underContest(relPath) {
+    const parts = relPath.split('/');
+    for (let i = 1; i <= parts.length; i++) {
+      if (contestedGround.has(parts.slice(0, i).join('/'))) return true;
+    }
+    return false;
+  }
+
+  /** Policy prunes at directories: every ancestor must enroll. */
+  function enrolledRel(relPath) {
+    const parts = relPath.split('/');
+    for (let i = 1; i <= parts.length; i++) {
+      if (!shouldEnroll(parts.slice(0, i).join('/'))) return false;
+    }
+    return true;
+  }
+
+  function noteTruth(relPath, hash) {
+    if (!enrolledRel(relPath)) return;
+    if (!pathTruth.has(relPath)) pathTruth.set(relPath, new Set());
+    pathTruth.get(relPath).add(hash);
+  }
+
+  function noteLinkTruth(relPath, target) {
+    if (!enrolledRel(relPath)) return;
+    if (!linkTruth.has(relPath)) linkTruth.set(relPath, new Set());
+    linkTruth.get(relPath).add(target);
+  }
+
+  const nameOf = (relPath) => relPath.slice(relPath.lastIndexOf('/') + 1);
+  const parentDirOf = (relPath) => {
+    const cut = relPath.lastIndexOf('/');
+    return cut === -1 ? null : relPath.slice(0, cut);
+  };
+
+  /** mkdir -p semantics: every missing strict ancestor gets a dir entry. */
+  function ensureAncestors(relPath) {
+    const parts = relPath.split('/');
+    for (let i = 1; i < parts.length; i++) {
+      const dir = parts.slice(0, i).join('/');
+      if (!diskDirs.has(dir)) diskDirs.set(dir, { tag: nextTag++ });
+    }
+  }
+
+  /**
+   * Every repo boundary visible to detection, at any depth. Within each
+   * base (the root, or an enclosing boundary), only minimal boundaries are
+   * its own; deeper ones belong to the child's census, with the enrollment
+   * policy re-applied relative to the child — the root-relative contract
+   * each root's census obeys.
+   */
+  function territoriesUnder(baseDir) {
+    const relTo = (dir) => (baseDir === '' ? dir : dir.slice(baseDir.length + 1));
+    const under = [...gitDirs].filter(
+      (dir) => dir !== baseDir && (baseDir === '' || dir.startsWith(`${baseDir}/`)),
+    );
+    const minimal = under
+      .filter((dir) => !under.some((other) => other !== dir && dir.startsWith(`${other}/`)))
+      .filter((dir) => enrolledScoped(relTo(dir)));
+    const all = [];
+    for (const dir of minimal) all.push(dir, ...territoriesUnder(dir));
+    return all;
+
+    function enrolledScoped(rel) {
+      const parts = rel.split('/');
+      for (let i = 1; i <= parts.length; i++) {
+        if (!shouldEnroll(parts.slice(0, i).join('/'))) return false;
+      }
+      return true;
+    }
+  }
+
+  function visibleTerritories() {
+    return gitDirs.has('')
+      ? new Set(['', ...territoriesUnder('')])
+      : new Set(territoriesUnder(''));
+  }
+
+  return {
+    // --- op recorders: call each one AFTER performing the real fs op ------
+
+    /** In-place write: the physical file (its tag) survives. */
+    write(relPath, bytes) {
+      ensureAncestors(relPath);
+      const hash = sha256(bytes);
+      const type = classify(bytes);
+      const existing = diskFiles.get(relPath);
+      if (existing) {
+        existing.hash = hash;
+        existing.type = type;
+      } else {
+        diskFiles.set(relPath, { hash, tag: nextTag++, type });
+      }
+      noteTruth(relPath, hash);
+    },
+
+    /** Atomic replacement: a new physical file lands on the address. */
+    replace(relPath, bytes) {
+      ensureAncestors(relPath);
+      const hash = sha256(bytes);
+      diskFiles.set(relPath, { hash, tag: nextTag++, type: classify(bytes) });
+      noteTruth(relPath, hash);
+    },
+
+    /** mtime moved, bytes did not: nothing to record. */
+    touch() {},
+
+    mkdir(relDir) {
+      ensureAncestors(`${relDir}/.`);
+      if (!diskDirs.has(relDir)) diskDirs.set(relDir, { tag: nextTag++ });
+    },
+
+    rename(from, to) {
+      const entry = diskFiles.get(from);
+      if (!entry) throw new Error(`model: rename of unknown path ${from}`);
+      ensureAncestors(to);
+      diskFiles.delete(from);
+      diskFiles.set(to, entry);
+      noteTruth(to, entry.hash);
+    },
+
+    renameDir(from, to) {
+      if (!diskDirs.has(from)) throw new Error(`model: renameDir of unknown dir ${from}`);
+      ensureAncestors(`${to}/.`);
+      const moveKey = (key) => `${to}${key.slice(from.length)}`;
+      for (const [relDir, entry] of [...diskDirs]) {
+        if (relDir !== from && !relDir.startsWith(`${from}/`)) continue;
+        diskDirs.delete(relDir);
+        diskDirs.set(moveKey(relDir), entry);
+      }
+      for (const [relPath, entry] of [...diskFiles]) {
+        if (!relPath.startsWith(`${from}/`)) continue;
+        diskFiles.delete(relPath);
+        const movedPath = moveKey(relPath);
+        diskFiles.set(movedPath, entry);
+        noteTruth(movedPath, entry.hash);
+      }
+      for (const [relPath, entry] of [...diskLinks]) {
+        if (!relPath.startsWith(`${from}/`)) continue;
+        diskLinks.delete(relPath);
+        const movedPath = moveKey(relPath);
+        diskLinks.set(movedPath, entry);
+        noteLinkTruth(movedPath, entry.target);
+      }
+      for (const dir of [...gitDirs]) {
+        if (dir !== from && !dir.startsWith(`${from}/`)) continue;
+        gitDirs.delete(dir);
+        gitDirs.add(moveKey(dir));
+      }
+    },
+
+    remove(relPath) {
+      if (!diskFiles.delete(relPath)) throw new Error(`model: remove of unknown path ${relPath}`);
+    },
+
+    /**
+     * Link ground. A written pointer always lands on a fresh inode —
+     * creation and retarget alike (retarget IS unlink + recreate) — so
+     * every write wears a new tag; only `mv` preserves one.
+     */
+    writeLink(relPath, target) {
+      ensureAncestors(relPath);
+      diskLinks.set(relPath, { target, tag: nextTag++ });
+      noteLinkTruth(relPath, target);
+    },
+
+    renameLink(from, to) {
+      const entry = diskLinks.get(from);
+      if (!entry) throw new Error(`model: renameLink of unknown path ${from}`);
+      ensureAncestors(to);
+      diskLinks.delete(from);
+      diskLinks.set(to, entry);
+      noteLinkTruth(to, entry.target);
+    },
+
+    removeLink(relPath) {
+      if (!diskLinks.delete(relPath)) throw new Error(`model: removeLink of unknown path ${relPath}`);
+    },
+
+    removeDir(relDir) {
+      for (const relPath of [...diskFiles.keys()]) {
+        if (relPath.startsWith(`${relDir}/`)) diskFiles.delete(relPath);
+      }
+      for (const relPath of [...diskLinks.keys()]) {
+        if (relPath.startsWith(`${relDir}/`)) diskLinks.delete(relPath);
+      }
+      for (const dir of [...diskDirs.keys()]) {
+        if (dir === relDir || dir.startsWith(`${relDir}/`)) diskDirs.delete(dir);
+      }
+      for (const dir of [...gitDirs]) {
+        if (dir === relDir || dir.startsWith(`${relDir}/`)) gitDirs.delete(dir);
+      }
+    },
+
+    gitInit(relDir) {
+      if (relDir !== '' && !diskDirs.has(relDir)) diskDirs.set(relDir, { tag: nextTag++ });
+      gitDirs.add(relDir);
+    },
+
+    gitRemove(relDir) {
+      gitDirs.delete(relDir);
+    },
+
+    // --- settle: apply the axioms to the net state ------------------------
+
+    /**
+     * Resolve identity for everything that happened since the last settle
+     * and return the expected snapshot: six-field records for every entity
+     * ever settled, the payload evidence map, the local-presence evidence,
+     * the exposed (non-repo-ground) file slice the adapter compares, and
+     * the territory census. Git never partitions lifecycle here — every
+     * enrolled path resolves under one set of rules, and the lens only
+     * decides types and exposure. Mirrors nothing: this is the axioms
+     * applied a second time, independently.
+     */
+    settle() {
+      // The contest attributions as the interval OPENED, kept beside the
+      // closing state below: events are judged after the settle, but a
+      // contest moves with its ground mid-interval, so an honest event at
+      // the old address must answer with the boundary it fired under.
+      contestedAtOpen = new Map([...contestedGround].map(([relPath, mark]) => [relPath, mark.uuid]));
+
+      // Directory addressing as the interval OPENED. A departing record
+      // moves not one field, so its frozen parent is the entity that
+      // held its parent address at the LAST settle — never the closing
+      // state, where that dir may have moved away (or another moved in).
+      const dirsAtOpen = new Map(folderByPath);
+
+      const territories = visibleTerritories();
+
+      // Covered ground is unwitnessed: leaf detection cannot see under the
+      // lens, so covered addresses take no part in any identity phase —
+      // their owners park at the drop, reconnect by slot at the lift, and
+      // ground first written under the lens is nobody until it surfaces.
+      // (A territory's own dir stays visible: it IS the repo's ground.)
+      const covered = (relPath) => {
+        for (const dir of territories) {
+          if (dir === '' || relPath.startsWith(`${dir}/`)) return true;
+        }
+        return false;
+      };
+      const visibleFiles = new Map();
+      for (const [relPath, entry] of diskFiles) {
+        if (enrolledRel(relPath) && !covered(relPath)) visibleFiles.set(relPath, entry);
+      }
+      const visibleLinks = new Map();
+      for (const [relPath, entry] of diskLinks) {
+        if (enrolledRel(relPath) && !covered(relPath)) visibleLinks.set(relPath, entry);
+      }
+      const visibleDirs = new Map();
+      for (const [relDir, entry] of diskDirs) {
+        if (enrolledRel(relDir) && !covered(relDir)) visibleDirs.set(relDir, entry);
+      }
+
+      const folderType = (relDir) => (territories.has(relDir) ? 'repo.git' : 'folder');
+
+      // Contested ground carries by ADDRESS continuity within its KIND,
+      // before anything else is judged: ground of the mark's kind still at
+      // a marked address stays contested (an atomic replace only refreshes
+      // the tag its open channel now wears; ground swapping kind has
+      // left). Ground gone from a marked address ends that contest — and
+      // the claimant's channel never closed, so its continuity may resume:
+      // a still-parked claimant rejoins this settle's rescue pool of its
+      // kind, while a re-grounded claimant's SURPLUS channel drags the
+      // contest along to wherever its physical tag landed (exactly one,
+      // or nothing).
+      const rescueEligible = [];
+      const linkRescueEligible = [];
+      const folderRescueEligible = [];
+      const KIND = {
+        file: { ground: visibleFiles, nodes: fileNodes, byPath: fileByPath, rescue: rescueEligible },
+        link: { ground: visibleLinks, nodes: linkNodes, byPath: linkByPath, rescue: linkRescueEligible },
+        dir: { ground: visibleDirs, nodes: folderNodes, byPath: folderByPath, rescue: folderRescueEligible },
+      };
+      for (const [relPath, mark] of [...contestedGround]) {
+        const kind = KIND[mark.kind];
+        const entry = kind.ground.get(relPath);
+        const node = kind.nodes.get(mark.uuid);
+        if (entry) {
+          mark.tag = entry.tag;
+          if (node?.frozen) node.tag = entry.tag;
+          continue;
+        }
+        contestedGround.delete(relPath);
+        if (!node) continue;
+        if (node.frozen) {
+          kind.rescue.push(node);
+          continue;
+        }
+        const landed = [...kind.ground]
+          .filter(([p, e]) => e.tag === mark.tag && !kind.byPath.has(p)
+            && !(mark.kind !== 'dir' && leafGroundAtOpen[mark.kind].has(p)));
+        if (landed.length === 1) {
+          contestedGround.set(landed[0][0], { uuid: mark.uuid, tag: mark.tag, kind: mark.kind });
+        }
+      }
+
+      const absorb = (node, relPath) => {
+        const truths = pathTruth.get(relPath);
+        if (truths) for (const hash of truths) node.history.add(hash);
+      };
+      const absorbLink = (node, relPath) => {
+        const truths = linkTruth.get(relPath);
+        if (truths) for (const target of truths) node.history.add(target);
+      };
+
+      // The occupant law, consulted by every rescue guard (phase 1) and
+      // the slot phase (phase 3), kind-blind: who owns this (parent, name)
+      // SLOT? An active record owns its slot wherever its ground stands —
+      // still on it, gone this very interval (the record has not moved),
+      // or parked settles ago. A node's slot is its RECORD's slot: the
+      // frozen fields once parked; the settled folder graph once this
+      // settle resolved it; the OPENING state while it is still pending —
+      // because records move only when continuity moves them, never by an
+      // address string drifting underneath. The asked address is spelled
+      // through the settled folder graph, so a parent renamed this very
+      // interval still spells the same slot on both sides.
+      const settledNodes = new Set();
+      const slotOfNode = (node) => {
+        if (node.frozen) return [node.frozen.parentUUID, node.frozen.name];
+        const rel = node.relDir ?? node.relPath;
+        const parent = parentDirOf(rel);
+        if (parent === null) return [workspace.uuid, nameOf(rel)];
+        return [(settledNodes.has(node) ? folderByPath : dirsAtOpen).get(parent), nameOf(rel)];
+      };
+      const occupantAt = (relPath) => {
+        const parent = parentDirOf(relPath);
+        const destParent = parent === null ? workspace.uuid : folderByPath.get(parent);
+        if (destParent === undefined) return undefined;
+        const destName = nameOf(relPath);
+        for (const node of [...folderNodes.values(), ...fileNodes.values(), ...linkNodes.values()]) {
+          const [slotParent, slotName] = slotOfNode(node);
+          if (slotParent === destParent && slotName === destName) return node;
+        }
+        return undefined;
+      };
+
+      // --- phase 1: match what continued. For FILES, path claims first —
+      // an atomic save replaces the physical file under a standing address,
+      // so the address absorbs that churn — then exactly-one tag rescues
+      // path-orphans, never across kinds (ground kind is a disk fact).
+      // DIRECTORIES apply the same two rules in the OPPOSITE order, for the
+      // mirror reason: nothing replaces a directory's inode in place, so
+      // physical continuity claims first — a known tag at a new address IS
+      // the directory, moved, even when its old address was reoccupied in
+      // the same interval (two directories exchanging names cross by tag,
+      // exactly like the files inside them) — and the address claims only
+      // what no tag claims: recreation under an old name, the same channel
+      // wearing a new tag. What neither rule matched falls through:
+      // unmatched ground to the slot phase, unmatched nodes to departure.
+      // No move lands on another's slot: a parked ACTIVE owner there —
+      // parked in an earlier settle or departing in this very one — is a
+      // CONTEST, the ground divergence, the claimant parked, nobody
+      // winning by address. Directory movers may hold each other's
+      // addresses, so they resolve in rounds: whoever's ground is free
+      // moves, and when nobody's is, the waiters cross — vacate all, land
+      // all.
+      const folderAppearances = []; // parents first, so children derive live ground
+      const departingFolders = [];
+      {
+        const liveNodes = [...folderByPath.values()].map((uuid) => folderNodes.get(uuid));
+        const nodesByTag = new Map();
+        // A territory's dir carries NO dir channel — its physical tag is
+        // unwitnessed, so it cannot rescue onto a new address (it still
+        // continues IN PLACE: the address-claim step below owns that).
+        for (const node of [...liveNodes, ...folderRescueEligible]) {
+          if (node.type === 'repo.git') continue;
+          nodesByTag.set(node.tag, nodesByTag.has(node.tag) ? 'many' : node);
+        }
+        const dirsByTag = new Map();
+        // Territory ground is just as unwitnessed on the entry side: a dir
+        // that became (or stayed) a boundary offers no dir channel, so its
+        // tag can testify for nobody — the address-claim step and the slot
+        // phase own whatever stands there.
+        for (const [relDir, entry] of visibleDirs) {
+          if (territories.has(relDir)) continue;
+          dirsByTag.set(entry.tag, dirsByTag.has(entry.tag) ? 'many' : { relDir, entry });
+        }
+        const consumedNodes = new Set();
+        const consumedDirs = new Set();
+        const candidates = [];
+        for (const [tag, found] of dirsByTag) {
+          const node = nodesByTag.get(tag);
+          if (found === 'many' || !node || node === 'many') continue;
+          consumedNodes.add(node);
+          consumedDirs.add(found.relDir);
+          if (!node.frozen && node.relDir === found.relDir) {
+            node.type = folderType(found.relDir); // continued in place
+            settledNodes.add(node);
+          } else {
+            candidates.push({ node, found });
+          }
+        }
+        // The address claims what no tag claims: recreation, silently.
+        for (const [relDir, entry] of visibleDirs) {
+          if (consumedDirs.has(relDir)) continue;
+          const node = folderNodes.get(folderByPath.get(relDir));
+          if (node && !consumedNodes.has(node)) {
+            node.tag = entry.tag;
+            node.type = folderType(relDir);
+            consumedNodes.add(node);
+            consumedDirs.add(relDir);
+            settledNodes.add(node);
+          }
+        }
+        const departing = new Set(liveNodes.filter((node) => !consumedNodes.has(node)));
+        departingFolders.push(...departing);
+        const land = (batch) => {
+          for (const { node } of batch) {
+            if (node.frozen) delete node.frozen; // an ex-contest claimant resuming: it left the path maps when it parked
+            else folderByPath.delete(node.relDir);
+          }
+          for (const { node, found } of batch) {
+            node.relDir = found.relDir;
+            node.type = folderType(found.relDir);
+            node.tag = found.entry.tag;
+            folderByPath.set(node.relDir, node.uuid);
+            settledNodes.add(node);
+          }
+        };
+        let pending = candidates;
+        while (pending.length > 0) {
+          const moving = new Set(pending.map((candidate) => candidate.node));
+          const wins = [];
+          const again = [];
+          for (const candidate of pending) {
+            const { node, found } = candidate;
+            const contest = () => {
+              // Two established identity claims on one address (or ground
+              // arriving under an undecided one): the model picks no
+              // winner — the claimant parks, the entry stays divergence.
+              contestedGround.set(found.relDir, { uuid: node.uuid, tag: found.entry.tag, kind: 'dir' });
+              consumedDirs.delete(found.relDir);
+              departing.add(node);
+              if (!node.frozen) departingFolders.push(node);
+            };
+            if (underContest(found.relDir)) {
+              contest();
+              continue;
+            }
+            const occupant = occupantAt(found.relDir);
+            if (occupant && occupant !== node && moving.has(occupant)) {
+              again.push(candidate); // its slot's owner is itself mid-move
+              continue;
+            }
+            // An occupant that IS the moving node is no contest: its own
+            // channel came home (a parent's move can respell home
+            // mid-flight). Anyone else — parked settles ago or departing
+            // in this very interval, whatever its kind — owns the slot.
+            if (occupant && occupant !== node) {
+              contest();
+              continue;
+            }
+            wins.push(candidate);
+          }
+          land(wins);
+          if (wins.length === 0 && again.length === pending.length) {
+            land(again); // the waiters hold each other's addresses: they cross
+            pending = [];
+          } else {
+            pending = again;
+          }
+        }
+        for (const [relDir, entry] of [...visibleDirs]
+          .sort((a, b) => a[0].split('/').length - b[0].split('/').length)) {
+          if (!consumedDirs.has(relDir)) folderAppearances.push([relDir, entry]);
+        }
+      }
+      // Leaf ground — files and links — shares one phase-1 shape: the path
+      // claims the channel first (the address absorbs replace/retarget
+      // churn), then exactly-one physical continuity rescues path-orphans,
+      // never across kinds. `land` is the kind's whole difference: which
+      // payload the entry carries into the node.
+      const settleLeaves = (kindName, land) => {
+        const { ground: visible, byPath, rescue } = KIND[kindName];
+        const appearances = [];
+        const departing = [];
+        const claimed = new Set();
+        const orphanNodes = [];
+        for (const [relPath, uuid] of [...byPath]) {
+          const node = KIND[kindName].nodes.get(uuid);
+          const entry = visible.get(relPath);
+          if (entry) {
+            land(node, relPath, entry);
+            claimed.add(relPath);
+            settledNodes.add(node);
+          } else {
+            orphanNodes.push(node);
+          }
+        }
+        const orphanEntries = [...visible].filter(([relPath]) => !claimed.has(relPath));
+        // Ex-contest claimants whose ground just left the marked address
+        // rejoin the pool: their channel never closed, so exactly-one
+        // physical continuity may still resume for them.
+        const nodesByTag = new Map();
+        for (const node of [...orphanNodes, ...rescue]) {
+          nodesByTag.set(node.tag, nodesByTag.has(node.tag) ? 'many' : node);
+        }
+        const entriesByTag = new Map();
+        for (const [relPath, entry] of orphanEntries) {
+          entriesByTag.set(entry.tag, entriesByTag.has(entry.tag) ? 'many' : { relPath, entry });
+        }
+        const movedNodes = new Set();
+        const movedPaths = new Set();
+        const landCandidate = ({ node, found }) => {
+          if (node.frozen) delete node.frozen; // an ex-contest claimant resuming: it left the path maps when it parked
+          else byPath.delete(node.relPath);
+          land(node, found.relPath, found.entry);
+          byPath.set(node.relPath, node.uuid);
+          settledNodes.add(node);
+          movedNodes.add(node.uuid);
+          movedPaths.add(found.relPath);
+        };
+        let pending = [];
+        for (const [tag, found] of entriesByTag) {
+          const node = nodesByTag.get(tag);
+          if (found === 'many' || !node || node === 'many') continue;
+          pending.push({ node, found });
+        }
+        while (pending.length > 0) {
+          const moving = new Set(pending.map((candidate) => candidate.node));
+          const wins = [];
+          const again = [];
+          for (const candidate of pending) {
+            const { node, found } = candidate;
+            // Standing same-kind ground absorbed the arrival at the
+            // channel layer: the mover's channel died there, no continuity
+            // claim was ever witnessed, and its record simply parks — no
+            // rescue, no contest.
+            if (leafGroundAtOpen[kindName].has(found.relPath)) continue;
+            // A parked owner that IS the rescuing node is no contest: its
+            // own channel came home (a parent's move can respell home
+            // mid-flight). Anyone else standing on the slot — parked in an
+            // earlier settle or departing in this very one — is a CONTEST:
+            // two established identity claims on one address, and the
+            // model picks no winner — the claimant stays (or goes) parked
+            // with its record unmoved, the owner stays with its record
+            // unmoved, and the ground is divergence.
+            const occupant = occupantAt(found.relPath);
+            if (occupant && occupant !== node && moving.has(occupant)) {
+              again.push(candidate); // its slot's owner is itself mid-move
+              continue;
+            }
+            if ((occupant && occupant !== node) || underContest(found.relPath)) {
+              contestedGround.set(found.relPath, { uuid: node.uuid, tag: found.entry.tag, kind: kindName });
+              continue;
+            }
+            wins.push(candidate);
+          }
+          for (const candidate of wins) landCandidate(candidate);
+          if (wins.length === 0 && again.length === pending.length) {
+            for (const candidate of again) landCandidate(candidate); // the waiters hold each other's addresses: they cross
+            pending = [];
+          } else {
+            pending = again;
+          }
+        }
+        for (const pair of orphanEntries) {
+          if (!movedPaths.has(pair[0])) appearances.push(pair);
+        }
+        departing.push(...orphanNodes.filter((node) => !movedNodes.has(node.uuid)));
+        return { appearances, departing };
+      };
+      const { appearances: fileAppearances, departing: departingFiles } = settleLeaves(
+        'file', (node, relPath, entry) => {
+          node.relPath = relPath;
+          node.hash = entry.hash;
+          node.tag = entry.tag;
+          node.type = entry.type;
+          node.history.add(entry.hash);
+          absorb(node, relPath);
+        });
+      const { appearances: linkAppearances, departing: departingLinks } = settleLeaves(
+        'link', (node, relPath, entry) => {
+          node.relPath = relPath;
+          node.target = entry.target;
+          node.tag = entry.tag;
+          node.history.add(entry.target);
+          absorbLink(node, relPath);
+        });
+
+      // --- phase 2: park what departed, BOTH kinds, before any appearance
+      // resolves. Absence is evidence — not one record field moves — and
+      // the owner must already be parked when its slot's returning ground
+      // (possibly of the other kind, inside this very interval) is judged.
+      const parentAtOpen = (rel) => {
+        const parent = parentDirOf(rel);
+        return parent === null ? workspace.uuid : dirsAtOpen.get(parent);
+      };
+      for (const node of departingFolders) {
+        folderByPath.delete(node.relDir);
+      }
+      for (const node of departingFolders) {
+        // A lifted lens is a type transition even on a parked record: the
+        // registry's lift pass flips every uncovered repo.git to folder,
+        // ground present or not.
+        node.type = folderType(node.relDir);
+        node.frozen = { parentUUID: parentAtOpen(node.relDir), name: nameOf(node.relDir) };
+      }
+      for (const node of departingFiles) {
+        node.frozen = { parentUUID: parentAtOpen(node.relPath), name: nameOf(node.relPath) };
+        fileByPath.delete(node.relPath);
+      }
+      for (const node of departingLinks) {
+        node.frozen = { parentUUID: parentAtOpen(node.relPath), name: nameOf(node.relPath) };
+        linkByPath.delete(node.relPath);
+      }
+
+      // --- phase 3: the slot phase (axiom 4). Each remaining appearance
+      // belongs to the parked ACTIVE owner of its (parent, name) slot —
+      // searched across ALL entities, because ownership is identity, not
+      // kind. Only an unowned slot births a new entity. Folders resolve
+      // first, parents before children, so children derive live ground.
+      // Waking an owner: same node, frozen shed. When the returning ground
+      // is the other kind, the node crosses the kind maps — a type
+      // transition on the same uuid — shedding only the old kind's ground
+      // evidence; uuid, status, and content history persist.
+      const wake = (owner, kindNodes) => {
+        delete owner.frozen;
+        if (!kindNodes.has(owner.uuid)) {
+          for (const other of [fileNodes, linkNodes, folderNodes]) {
+            if (other !== kindNodes) other.delete(owner.uuid);
+          }
+          delete owner.relPath;
+          delete owner.relDir;
+          delete owner.hash;
+          delete owner.target;
+          kindNodes.set(owner.uuid, owner);
+        }
+        return owner;
+      };
+      const divergent = new Map(); // relPath -> hash (null for dir ground), entity-less
+      for (const [relDir, entry] of folderAppearances) {
+        if (underContest(relDir)) {
+          divergent.set(relDir, null);
+          continue; // contested ground (or under it): reported, claimed by no entity
+        }
+        const occupant = occupantAt(relDir);
+        const owner = occupant?.frozen ? occupant : undefined;
+        const node = owner
+          ? wake(owner, folderNodes)
+          : { uuid: `d${nextNode++}`, status: 'active' };
+        node.relDir = relDir;
+        node.tag = entry.tag;
+        node.type = folderType(relDir);
+        folderNodes.set(node.uuid, node);
+        folderByPath.set(relDir, node.uuid);
+        settledNodes.add(node);
+      }
+      // Axiom 6's guard: file ground on a slot whose owner is a folder
+      // that still HAS stored-active children is a swap the canonical
+      // graph refuses — the ground is divergence, not a transition. (A
+      // parked folder's subtree parked with it, so its stored-active
+      // children are found among the frozen nodes.)
+      const hasActiveChildren = (uuid) => [...folderNodes.values(), ...fileNodes.values(), ...linkNodes.values()]
+        .some((node) => node.status === 'active' && node.frozen?.parentUUID === uuid);
+      for (const [relPath, entry] of fileAppearances) {
+        if (underContest(relPath)) {
+          divergent.set(relPath, entry.hash);
+          continue; // contested ground (or under it): reported, claimed by no entity, resolved by nothing here
+        }
+        const occupant = occupantAt(relPath);
+        const owner = occupant?.frozen ? occupant : undefined;
+        if (owner && folderNodes.has(owner.uuid) && hasActiveChildren(owner.uuid)) {
+          divergent.set(relPath, entry.hash);
+          continue;
+        }
+        const node = owner
+          ? wake(owner, fileNodes)
+          : { uuid: `n${nextNode++}`, status: 'active' };
+        node.relPath = relPath;
+        node.hash = entry.hash;
+        node.tag = entry.tag;
+        node.type = entry.type;
+        (node.history ??= new Set()).add(entry.hash);
+        absorb(node, relPath);
+        fileNodes.set(node.uuid, node);
+        fileByPath.set(relPath, node.uuid);
+        settledNodes.add(node);
+      }
+      // Link arrivals: the same slot law, third kind — ownership is
+      // identity, not kind, and the container guard is kind-blind: link
+      // ground on an occupied folder's slot is the same refused swap.
+      for (const [relPath, entry] of linkAppearances) {
+        if (underContest(relPath)) {
+          divergent.set(relPath, entry.target);
+          continue; // contested ground (or under it): reported, claimed by no entity
+        }
+        const occupant = occupantAt(relPath);
+        const owner = occupant?.frozen ? occupant : undefined;
+        if (owner && folderNodes.has(owner.uuid) && hasActiveChildren(owner.uuid)) {
+          divergent.set(relPath, entry.target);
+          continue;
+        }
+        const node = owner
+          ? wake(owner, linkNodes)
+          : { uuid: `l${nextNode++}`, status: 'active' };
+        node.relPath = relPath;
+        node.target = entry.target;
+        node.tag = entry.tag;
+        node.type = 'link';
+        (node.history ??= new Set()).add(entry.target);
+        absorbLink(node, relPath);
+        linkNodes.set(node.uuid, node);
+        linkByPath.set(relPath, node.uuid);
+        settledNodes.add(node);
+      }
+
+      lastTruth = pathTruth;
+      pathTruth = new Map();
+      lastLinkTruth = linkTruth;
+      linkTruth = new Map();
+      leafGroundAtOpen = {
+        file: new Set(visibleFiles.keys()),
+        link: new Set(visibleLinks.keys()),
+      };
+
+      // Six-field records + the payload evidence map. Live parents derive
+      // through the settled folder graph; parked nodes carry the fields
+      // frozen when they left the maps.
+      const liveParent = (relPath) => {
+        const parent = parentDirOf(relPath);
+        return parent === null ? workspace.uuid : folderByPath.get(parent);
+      };
+      const records = [];
+      const payloads = new Map(); // uuid -> payload evidence (feeds the version hash)
+      const children = new Map(); // parentUUID -> [childUUID, name] pairs, STORED-active only
+      const note = (record, payload) => {
+        records.push(record);
+        payloads.set(record.uuid, payload);
+        if (record.status !== 'active' || record.parentUUID === null) return;
+        if (!children.has(record.parentUUID)) children.set(record.parentUUID, []);
+        children.get(record.parentUUID).push([record.uuid, record.name]);
+      };
+      for (const node of folderNodes.values()) {
+        note({
+          uuid: node.uuid,
+          type: node.type,
+          parentUUID: node.frozen ? node.frozen.parentUUID : liveParent(node.relDir),
+          name: node.frozen ? node.frozen.name : nameOf(node.relDir),
+          version: null,
+          status: node.status,
+        }, null);
+      }
+      for (const node of fileNodes.values()) {
+        note({
+          uuid: node.uuid,
+          type: node.type,
+          parentUUID: node.frozen ? node.frozen.parentUUID : liveParent(node.relPath),
+          name: node.frozen ? node.frozen.name : nameOf(node.relPath),
+          version: null,
+          status: node.status,
+        }, node.hash);
+      }
+      for (const node of linkNodes.values()) {
+        note({
+          uuid: node.uuid,
+          type: node.type,
+          parentUUID: node.frozen ? node.frozen.parentUUID : liveParent(node.relPath),
+          name: node.frozen ? node.frozen.name : nameOf(node.relPath),
+          version: null,
+          status: node.status,
+        }, node.target);
+      }
+      // The root record: the workspace — or, when a .git sits at the
+      // enrolled root, the repo the lens makes of it. Same uuid both ways.
+      note({
+        uuid: workspace.uuid,
+        type: territories.has('') ? 'repo.git' : 'workspace',
+        parentUUID: null,
+        name: '', version: null, status: 'active',
+      }, null);
+
+      // The ratified version formula, both halves: containers hash their
+      // sorted stored-active membership; repo.git evidence is null-gated
+      // until the card/checkpoint payload is adapted; every record's
+      // version is the canonical envelope over its fields + payload.
+      const membership = (uuid) => sha256(JSON.stringify((children.get(uuid) ?? []).sort()));
+      for (const record of records) {
+        if (record.type === 'folder' || record.type === 'workspace') {
+          payloads.set(record.uuid, membership(record.uuid));
+        }
+        record.version = sha256(JSON.stringify(
+          [record.type, record.parentUUID, record.name, record.status, payloads.get(record.uuid)]));
+      }
+
+      // The exposed slice: what the observer is answerable for — exactly
+      // the live maps, because covered ground never enters a phase (a
+      // territory's own dir is repo ground, never a dir channel).
+      const files = new Map();
+      for (const [relPath, uuid] of fileByPath) {
+        files.set(relPath, { uuid, hash: fileNodes.get(uuid).hash });
+      }
+      const links = new Map();
+      for (const [relPath, uuid] of linkByPath) {
+        links.set(relPath, { uuid, target: linkNodes.get(uuid).target });
+      }
+      const dirs = new Map();
+      for (const [relDir, uuid] of folderByPath) {
+        if (!territories.has(relDir)) dirs.set(relDir, { uuid });
+      }
+
+      // Local presence is EVIDENCE, judged beside the records — never a
+      // record field: which entities local ground currently holds.
+      const present = new Set([
+        workspace.uuid, ...folderByPath.values(), ...fileByPath.values(), ...linkByPath.values(),
+      ]);
+
+      return {
+        records, payloads, files, links, dirs, territories, present, divergent,
+        contested: new Map([...contestedGround].map(([relPath, mark]) => [relPath, mark.uuid])),
+      };
+    },
+
+    /** Was this version ever true for THIS entity? (per-entity emitted-truth;
+     * one history space per entity, so a leaf that crossed kinds still
+     * answers for everything it ever was) */
+    nodeEverTrue(uuid, value) {
+      return (fileNodes.get(uuid) ?? linkNodes.get(uuid))?.history.has(value) === true;
+    },
+
+    /**
+     * Was this version ever true at this address during the just-closed
+     * interval? The floor for a channel born and dead between settles: it
+     * never gained an entity history, but it DID claim an address, and the
+     * address remembers.
+     */
+    addressEverTrue(relPath, hash) {
+      return lastTruth.get(relPath)?.has(hash) === true;
+    },
+
+    /** The link-kind floor: was this target ever written at this address
+     * during the just-closed interval? */
+    addressLinkEverTrue(relPath, target) {
+      return lastLinkTruth.get(relPath)?.has(target) === true;
+    },
+
+    /**
+     * Was this address contested FOR this claimant at either boundary of
+     * the just-closed interval? A contest moves with its ground
+     * mid-interval, so an honest event at the old address answers with the
+     * opening state, while an event at the new address answers with the
+     * closing one — the same interval scope `addressEverTrue` uses.
+     */
+    addressContestedFor(relPath, uuid) {
+      return contestedGround.get(relPath)?.uuid === uuid
+        || contestedAtOpen.get(relPath) === uuid;
+    },
+  };
+}
+
+module.exports = { createModel, sha256 };