amalgm 0.1.245 → 0.1.246

package/runtime/scripts/amalgm-mcp/registry/evidence.js

@@ -0,0 +1,826 @@
+'use strict';
+
+/**
+ * The evidence intake: observer truth flows onto registry records here, and
+ * nowhere else. The registry stays the sole owner of identity and lifecycle;
+ * this layer only PROPOSES through the registry's public verbs — it holds no
+ * private handle to the record store and can do nothing detection may not.
+ *
+ * The inbound doorbell contract (docs/entity-model.md):
+ *   1. an observer event arrives;
+ *   2. `onEvent` marks intake dirty and returns — it is INFALLIBLE, so a
+ *      throwing consumer can never swallow an observer event;
+ *   3. fallible reconciliation happens afterward by reading OBSERVER-STORE
+ *      truth — events are hints, never the data;
+ *   4. a failed reconciliation leaves dirty set; the next event or
+ *      `flushIfDirty()` reattempts it;
+ *   5. startup performs the identical reconciliation.
+ * At-most-once event delivery is never load-bearing.
+ *
+ * The channel law, four sentences — KIND-BLIND, now that directories are
+ * channels too: one channel claims at most one entity. An entity may
+ * temporarily hold several evidence channels. Only the channel on the
+ * record's own address is canonical ground. Every other bound channel's
+ * ground is CONTESTED — reported as divergence, moving nothing — so a
+ * bound channel moves its record only onto unowned ground, and only while
+ * its entity has no canonical ground elsewhere.
+ *
+ * A contest is two established identity claims on one address (a bound
+ * channel's continuity against another active record's slot), and Amalgm
+ * never picks the winner: it resolves only when the contested ground
+ * actually leaves the address — ground of the mark's own kind; a file
+ * replaced by a directory has left — or by an explicit identity-carrying
+ * action. Ground reappearing at the claimant's old address resolves
+ * NOTHING — it could be a copy; presence proves nothing about identity.
+ * 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. That
+ * coverage is ARITHMETIC, never storage — a contest writes one durable
+ * marker at its root, and the subtree beneath it derives by prefix,
+ * however large it is.
+ *
+ * Evidence has a DURABLE memory (`createEvidenceMemory`, two tables beside
+ * the records under the same sentinel): channel bindings (channelId →
+ * entityUUID — the schema itself enforces one claim per channel, and each
+ * binding carries its SCOPE, the observer rootId whose lens owns it) and
+ * contested-ground markers. Bindings make the contest DERIVED state at any
+ * moment — startup, flush, mid-session — instead of state anyone repairs;
+ * without them, a restart would silently hand contested ground to the
+ * slot's owner. The observer root is itself a bound channel — the
+ * WITNESS, and the witness binding is how a lens finds its tree's record:
+ * identity is looked up, never guessed from a name or an address. The
+ * loss law lives on the boundary above now that ONE registry holds every
+ * tree: any active parentless record no live witness claims convicts
+ * loudly before a single lens reconciles (registration/index.js) — a
+ * lost observer store is never a fresh start, and no replacement mints
+ * over surviving records. Markers survive the same loss: forgetting the
+ * evidence cannot authorize assigning contested ground to anyone. Both
+ * are internal evidence — never a seventh public record field. The
+ * registry schema creates both tables so its inspect convicts their loss
+ * like any other registry loss, and every durable write lands BEFORE the
+ * in-memory cache, so a failed write is retried by the next
+ * reconciliation, never believed.
+ *
+ * What reconcile maps (the claimed slice today):
+ *   - the root record (workspace ↔ repo.git under the root lens; a
+ *     single-ground root's record IS the file or link entity — bytes
+ *     attested like any file, a pointer attested exactly as written —
+ *     and disk deciding the ground's kind is a type transition on the
+ *     same UUID);
+ *   - file, folder, AND link records under one law: birth, payload
+ *     attestation (files attest content, links attest the pointer exactly
+ *     as written — a container's payload is derived membership; what a
+ *     pointer currently REACHES is derived resolution, owned by the
+ *     registration boundary that can see every tree, recomputed on
+ *     demand and never stored),
+ *     classification flips, moves per the channel law above, slot
+ *     reconnection (a fresh channel landing on an absent active owner's
+ *     unmarked slot rebinds — whatever kind it returns as — never a second
+ *     entity). Folder identity rides the directory channel: one move on
+ *     the folder record and every descendant's derived address follows,
+ *     which is why folders reconcile before files, parents before
+ *     children;
+ *   - repo territories as repo.git type transitions on the slot's record;
+ *   - ADOPTION, the channel law completing across trees: unclaimed
+ *     ground wearing the physical identity of an orphaned top-level tree
+ *     is that tree's arrival — one lawful parent update on its
+ *     parentless record, never a birth (dir ground adopts a files tree,
+ *     territory news adopts a repo tree; single-ground trees reattach
+ *     explicitly — a cross-tree file claim has no parent census to
+ *     bound its ambiguity, so the deliberate act decides);
+ *   - divergence, from two sources in one report: contested ground (null
+ *     bytes when the ground is a directory), and the container refusal
+ *     (file ground on a folder that still has active children) — ground
+ *     detection cannot lawfully assign to any entity.
+ *
+ * Classification is an INJECTED policy (the Axiom-2 pattern) asked about
+ * the observed bytes' own report; the model owns no such rule. And ONE
+ * OBSERVATION IS ONE TRANSITION: a look's payload and the type it implies
+ * reach the registry in a single call (`registry.attest`), so a record can
+ * never durably wear a type from one read beside a payload from another.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const FILE_TYPES = new Set(['file.text', 'file.binary']);
+const LEAF_TYPES = new Set(['file.text', 'file.binary', 'link']);
+// Adoption candidates by ground shape: a dir channel can be an arrived
+// files tree; a territory can be an arrived repo tree. Single-ground
+// (file/link) trees stay outside adoption — a file's inode is weak
+// identity (atomic saves churn it), so their return is reattachment.
+const FILES_TREE = new Set(['files']);
+const REPO_TREE = new Set(['repo']);
+
+const MEMORY_TABLES = ['registry_meta', 'channel_bindings', 'contested_ground'];
+
+/**
+ * The evidence layer's durable memory, living in the ONE identity
+ * database so one sentinel guards records and evidence together — but
+ * owned here: the registry never reads these tables, and evidence never
+ * touches its. The registry SCHEMA is what creates them (all four tables
+ * are born together), so this factory only verifies and reads: a table
+ * gone from an established database is loss, and forgetting evidence
+ * must fail loudly — a silently recreated empty table would resolve
+ * every open contest.
+ *
+ * Every binding and contest marker carries a SCOPE — the observer rootId
+ * whose evidence namespace owns it. Lenses over different trees share
+ * this memory without ever touching each other's channels; channel ids
+ * themselves stay globally unique, so `boundTo` answers across scopes
+ * (adoption asks whose record an orphaned tree's witness claims).
+ * Retiring a tree drops its whole scope — bindings and markers together.
+ */
+function createEvidenceMemory(db) {
+  const present = db.prepare(
+    `SELECT name FROM sqlite_master WHERE type = 'table' AND name IN (${MEMORY_TABLES.map(() => '?').join(', ')})`,
+  ).all(...MEMORY_TABLES).map((row) => row.name);
+  const missing = MEMORY_TABLES.filter((name) => !present.includes(name));
+  if (missing.length > 0) {
+    throw new Error(`evidence memory lost: ${missing.join(', ')} missing from this database — the registry schema creates these tables, and a gap in an established database is loss, never a fresh start`);
+  }
+  const meta = db.prepare('SELECT epoch_uuid FROM registry_meta WHERE singleton = 1').get();
+  if (!meta) {
+    throw new Error('evidence memory requires an initialized registry: registry_meta holds no epoch row — create the registry before its evidence memory');
+  }
+  return {
+    epoch: () => meta.epoch_uuid,
+    bindings: (scopeId) => db.prepare('SELECT channel_id, entity_uuid FROM channel_bindings WHERE scope_id = ?')
+      .all(scopeId).map((row) => ({ channelId: row.channel_id, uuid: row.entity_uuid })),
+    bind: (scopeId, channelId, uuid) => db.prepare(
+      'INSERT INTO channel_bindings (channel_id, scope_id, entity_uuid) VALUES (?, ?, ?)'
+      + ' ON CONFLICT(channel_id) DO UPDATE SET scope_id = excluded.scope_id, entity_uuid = excluded.entity_uuid',
+    ).run(channelId, scopeId, uuid),
+    unbind: (channelId) => db.prepare('DELETE FROM channel_bindings WHERE channel_id = ?').run(channelId),
+    /** Across scopes — channel ids are globally unique. */
+    boundTo: (channelId) => db.prepare('SELECT entity_uuid FROM channel_bindings WHERE channel_id = ?')
+      .get(channelId)?.entity_uuid,
+    allBindings: () => db.prepare('SELECT channel_id, scope_id, entity_uuid FROM channel_bindings').all()
+      .map((row) => ({ channelId: row.channel_id, scopeId: row.scope_id, uuid: row.entity_uuid })),
+    /** A retired tree's whole evidence namespace, gone as one act. */
+    dropScope: (scopeId) => {
+      db.prepare('DELETE FROM channel_bindings WHERE scope_id = ?').run(scopeId);
+      db.prepare('DELETE FROM contested_ground WHERE scope_id = ?').run(scopeId);
+    },
+    contests: (scopeId) => db.prepare('SELECT rel_path, claimant_uuid, kind FROM contested_ground WHERE scope_id = ?')
+      .all(scopeId).map((row) => ({ relPath: row.rel_path, uuid: row.claimant_uuid, kind: row.kind })),
+    contest: (scopeId, relPath, uuid, kind) => db.prepare(
+      'INSERT INTO contested_ground (scope_id, rel_path, claimant_uuid, kind) VALUES (?, ?, ?, ?)'
+      + ' ON CONFLICT(scope_id, rel_path) DO UPDATE SET claimant_uuid = excluded.claimant_uuid, kind = excluded.kind',
+    ).run(scopeId, relPath, uuid, kind),
+    clearContest: (scopeId, relPath) => db.prepare('DELETE FROM contested_ground WHERE scope_id = ? AND rel_path = ?')
+      .run(scopeId, relPath),
+  };
+}
+
+/**
+ * THE LOSS LAW, one function, asked at the only dangerous moments: every
+ * active parentless record must be claimed by a LIVE observer root's
+ * witness binding. A lost or torn observer store leaves registered trees
+ * unclaimed — the evidence behind every binding is gone — and that
+ * convicts loudly. A lens asks before minting any new tree record; the
+ * registration boundary asks before any lens reconciles. A lost store is
+ * never a fresh start, no replacement identity ever mints over surviving
+ * records, and re-enrollment after loss is an explicit act.
+ */
+function assertWitnessed({ observer, registry, memory }) {
+  const liveIds = new Set(observer.listRoots().map((row) => row.rootId));
+  const claimed = new Set(memory.allBindings()
+    .filter((row) => liveIds.has(row.channelId))
+    .map((row) => row.uuid));
+  const unclaimed = registry.roots().filter((record) => !claimed.has(record.uuid));
+  if (unclaimed.length > 0) {
+    throw new Error(`identity evidence lost: registered tree(s) ${unclaimed.map((record) => record.uuid).join(', ')} have no living witness — a lost observer store cannot re-earn its claims, and re-enrollment must be explicit`);
+  }
+}
+
+function createEvidence(options) {
+  const { observer, registry, memory, rootId, classify } = options;
+  if (!observer || !registry) throw new Error('createEvidence requires { observer, registry }');
+  if (!memory) {
+    throw new Error('createEvidence requires { memory }: channel bindings and contested ground must survive a restart — in-memory evidence is the silent-handoff hole');
+  }
+  if (typeof rootId !== 'string') {
+    throw new Error('createEvidence requires { rootId }: a lens is keyed by the tree\'s permanent identity, never its address — the address is derived fresh each reconcile');
+  }
+  if (typeof classify !== 'function') {
+    throw new Error('createEvidence requires { classify }: ({ binary }) => file type — an injected policy over the OBSERVED BYTES\' own report, never a built-in rule and never a fresh read of the ground');
+  }
+  if (memory.epoch() !== registry.epoch()) {
+    throw new Error(`evidence memory epoch ${memory.epoch()} is not this registry's ${registry.epoch()} — bindings from another registry's database cannot claim these records`);
+  }
+
+  let dirty = false;
+  let scheduled = false;
+  let stopped = false;
+  let groundPath = null; // the tree's CURRENT address, read from the observer at each reconcile
+  const channelToUuid = new Map(memory.bindings(rootId).map((row) => [row.channelId, row.uuid]));
+  const contested = new Map(memory.contests(rootId).map((row) => [row.relPath, { uuid: row.uuid, kind: row.kind }]));
+  let divergent = new Map(); // relPath -> hash (null for dir ground), ground no entity may claim
+
+  // Durable truth first, cache second — here and in the marker sync below.
+  // A failed database write leaves the cache unset, so the retrying
+  // reconciliation re-derives and re-attempts it; cache-first would believe
+  // a write that never happened and skip it forever.
+  function bind(channelId, uuid) {
+    memory.bind(rootId, channelId, uuid);
+    channelToUuid.set(channelId, uuid);
+  }
+
+  function release(channelId) {
+    if (!channelToUuid.has(channelId)) return;
+    memory.unbind(channelId);
+    channelToUuid.delete(channelId);
+  }
+
+  /** Derived, never stored: the record's current address, via the chain. */
+  function pathOf(uuid) {
+    const names = [];
+    let record = registry.record(uuid);
+    while (record.parentUUID !== null) {
+      names.unshift(record.name);
+      record = registry.record(record.parentUUID);
+    }
+    return names.join('/');
+  }
+
+  /** Walk an address slot by slot WITHOUT materializing anything. */
+  function activeAtPath(relPath, root) {
+    let cursor = root.uuid;
+    const parts = relPath.split('/');
+    for (let i = 0; i < parts.length - 1; i++) {
+      const at = registry.activeAt(cursor, parts[i]);
+      if (!at) return null;
+      cursor = at.uuid;
+    }
+    return registry.activeAt(cursor, parts[parts.length - 1]);
+  }
+
+  /** Every active record under the root, with its derived address. */
+  function walkActive(uuid, prefix, out) {
+    for (const child of registry.children(uuid)) {
+      if (child.status !== 'active') continue;
+      const rel = prefix === '' ? child.name : `${prefix}/${child.name}`;
+      out.push({ record: child, rel });
+      walkActive(child.uuid, rel, out);
+    }
+    return out;
+  }
+
+  /** Materialize the folder chain for a path; file → folder is always valid. */
+  function ensureDir(relDir, root) {
+    let cursor = root.uuid;
+    if (relDir === '' || relDir === '.') return cursor;
+    for (const segment of relDir.split('/')) {
+      const at = registry.activeAt(cursor, segment);
+      if (!at) {
+        cursor = registry.create({ type: 'folder', parentUUID: cursor, name: segment }).uuid;
+      } else if (FILE_TYPES.has(at.type)) {
+        cursor = registry.changeType(at.uuid, 'folder').uuid;
+      } else {
+        cursor = at.uuid;
+      }
+    }
+    return cursor;
+  }
+
+  /**
+   * Leaf payload attestation — ONE OBSERVATION, ONE TRANSITION. The
+   * payload and the type reach the registry in a single call because
+   * they describe a single look: bytes carry the policy's answer about
+   * the OBSERVED BYTES' own report (produced by the very read that
+   * produced this hash — this layer never opens the ground), and a
+   * pointer carries `link`, which is disk's decision and not a policy's.
+   * A look that finds the other kind on the slot is that same one
+   * transition, not a type flip followed by an attestation.
+   *
+   * Only leaf ground attests: a container's payload is its derived
+   * membership, and a reference's payload is the target's IDENTITY,
+   * written by the deliberate act that created it — no ground speaks
+   * for either, so both are silence here.
+   */
+  function attestPayload(kind, uuid, evidence) {
+    if (!LEAF_TYPES.has(registry.record(uuid).type)) return;
+    if (kind === 'file') {
+      registry.attest(uuid, { payloadVersion: evidence.hash, type: classify(evidence) });
+    } else if (kind === 'link') {
+      registry.attest(uuid, { payloadVersion: evidence.hash, type: 'link' });
+    }
+  }
+
+  /** Orphaned: the tree's recorded address no longer holds its ground. */
+  function addressGone(row) {
+    try {
+      const stat = fs.lstatSync(row.path);
+      return stat.dev !== row.device || stat.ino !== row.inode;
+    } catch {
+      return true;
+    }
+  }
+
+  /**
+   * ADOPTION — the channel law completing across trees: unclaimed ground
+   * wearing the physical identity of an orphaned top-level tree is that
+   * tree's ARRIVAL, never a birth. A tree boundary is not an identity
+   * boundary, so the whole tree joins this one as one lawful parent
+   * update on its parentless record; every descendant record rides
+   * along, and their channels reconnect slot by slot under the ordinary
+   * arrival law. The claim rules are every continuity rescue's: exactly
+   * one candidate, only for a tree whose own address no longer holds its
+   * ground, and only a tree that was actually registered — ground that
+   * never earned a record has nothing to preserve, so a birth is honest.
+   */
+  function arrivedTree(device, inode, kinds) {
+    if (device == null) return null;
+    const roots = observer.listRoots();
+    const hasShape = (row) => {
+      if (kinds.has(row.kind)) return true;
+      // A repo moved across parent directories can be noticed first at its
+      // old address. The observer honestly demotes that absent address to
+      // files before the enclosing tree sees the arriving `.git`; its
+      // durable witness still names repo.git, so the arriving territory
+      // must use the registered shape rather than scan order to preserve
+      // one identity.
+      if (kinds !== REPO_TREE) return false;
+      const uuid = memory.boundTo(row.rootId);
+      return uuid !== undefined && registry.record(uuid).type === 'repo.git';
+    };
+    const matches = roots.filter((row) => row.rootId !== rootId && hasShape(row)
+      && row.device === device && row.inode === inode
+      && !roots.some((other) => other.rootId !== row.rootId && row.path.startsWith(`${other.path}/`))
+      && addressGone(row));
+    if (matches.length !== 1) return null;
+    const uuid = memory.boundTo(matches[0].rootId);
+    if (uuid === undefined) return null;
+    const record = registry.record(uuid);
+    return record.parentUUID === null && record.status === 'active' ? record : null;
+  }
+
+  function reconcile() {
+    dirty = false; // an event landing mid-reconcile re-dirties honestly
+    try {
+      const rootRow = observer.listRoots().find((row) => row.rootId === rootId);
+      if (!rootRow) return; // not enrolled yet — nothing is claimed
+      groundPath = rootRow.path; // the address is derived, never the lens's identity
+
+      // The root record: enrollment is its birth; a .git at the enrolled
+      // root is a type transition on the same uuid, never a second root.
+      // The observer root is itself a channel claiming that record — the
+      // WITNESS, and the witness binding IS the lookup: this lens's tree
+      // is whatever record its observer root claims, so the record store
+      // is never asked to guess by name or address. The loss law lives
+      // one level up now that the registry holds every tree: the
+      // boundary convicts any active parentless record no live witness
+      // claims (registration/index.js) before any lens reconciles —
+      // identity evidence is durable, or its loss is explicit, and a
+      // fresh observer store can never silently mint over surviving
+      // records. A witness claiming a record that now has a PARENT means
+      // this tree was ADOPTED into another: the lens's work is done, and
+      // the boundary retires it.
+      const fileRow = rootRow.kind === 'file'
+        ? (observer.filesForRoot(rootRow.rootId)[0] ?? null)
+        : null;
+      const linkRow = rootRow.kind === 'file'
+        ? (observer.linksForRoot(rootRow.rootId)[0] ?? null)
+        : null;
+      const rootType = rootRow.kind === 'repo' ? 'repo.git'
+        : rootRow.kind === 'file' ? null // the ground's own attestation owns its type
+          : 'workspace';
+      const witnessed = channelToUuid.get(rootRow.rootId);
+      let root = witnessed === undefined ? null : registry.record(witnessed);
+      // An adopted ordinary tree retires its lens: its enclosing tree now
+      // owns the ground. An adopted repo.git is different: it is a semantic
+      // Card + Checkpoint boundary inside that tree, so its own child
+      // channels retain a lens keyed by its observer root.
+      if (root && root.parentUUID !== null && !(rootRow.kind === 'repo' && root.type === 'repo.git')) return;
+      if (root) {
+        if (rootType !== null && root.type !== rootType) root = registry.changeType(root.uuid, rootType);
+      } else {
+        if (rootRow.kind === 'file' && !fileRow && !linkRow) return; // no ground yet: nothing to enroll
+        assertWitnessed({ observer, registry, memory }); // minting is the dangerous moment
+        // The birth is ONE transition: the record and its witness binding
+        // land together or not at all — a tear between them would leave a
+        // parentless record no witness claims, which IS the loss shape.
+        // The registry's primitive also holds the bell: entity.committed
+        // rings only after this commits, never for a birth that rolled back.
+        root = registry.transaction(() => {
+          const minted = registry.enrollRoot(rootRow.kind !== 'file'
+            ? { type: rootType, name: path.basename(groundPath) }
+            : fileRow
+              ? { type: classify(fileRow), name: path.basename(groundPath), payloadVersion: fileRow.contentHash }
+              : { type: 'link', name: path.basename(groundPath), payloadVersion: linkRow.target });
+          memory.bind(rootId, rootRow.rootId, minted.uuid);
+          return minted;
+        });
+        channelToUuid.set(rootRow.rootId, root.uuid); // cache after the commit, never inside it
+      }
+
+      // A single-ground tree: the root record IS the file or link entity
+      // — one channel of ground, disk deciding its kind, attested under
+      // the same law as anywhere else (files re-ask classification only
+      // when content changed; a pointer's payload is its written text),
+      // behind the same witness gate above. Ground returning as the
+      // other kind is a type transition on the same UUID. Absent ground
+      // releases the channel and moves nothing: the entity lives, its
+      // record stays.
+      if (rootRow.kind === 'file') {
+        if (fileRow) {
+          if (channelToUuid.get(fileRow.fileId) !== root.uuid) bind(fileRow.fileId, root.uuid);
+          attestPayload('file', root.uuid, { hash: fileRow.contentHash, binary: fileRow.binary });
+        } else if (linkRow) {
+          if (channelToUuid.get(linkRow.linkId) !== root.uuid) bind(linkRow.linkId, root.uuid);
+          attestPayload('link', root.uuid, { hash: linkRow.target });
+        }
+        for (const channelId of [...channelToUuid.keys()]) {
+          if (channelId !== rootRow.rootId && channelId !== fileRow?.fileId && channelId !== linkRow?.linkId) {
+            release(channelId);
+          }
+        }
+        divergent = new Map();
+        return;
+      }
+
+      // Observer-store truth, never event payloads (events are hints).
+      // Both maps arrive sorted by path, so folders reconcile parents
+      // before children.
+      const desiredDirs = new Map(); // relPath -> { channelId }
+      const desiredFiles = new Map(); // relPath -> { channelId, hash, binary } — one read's whole report
+      const desiredLinks = new Map(); // relPath -> { channelId, hash: the pointer as written }
+      // A Git root keeps ordinary child channels too, but they are only
+      // refreshed after its Repocard follower settles a new state. The
+      // observer never lets raw worktree doorbells reach this branch.
+      if (rootRow.kind === 'files' || rootRow.kind === 'repo') {
+        for (const row of observer.dirsForRoot(rootRow.rootId)) {
+          desiredDirs.set(row.relPath, { channelId: row.dirId, device: row.device, inode: row.inode });
+        }
+        for (const row of observer.filesForRoot(rootRow.rootId)) {
+          desiredFiles.set(row.relPath, { channelId: row.fileId, hash: row.contentHash, binary: row.binary });
+        }
+        for (const row of observer.linksForRoot(rootRow.rootId)) {
+          desiredLinks.set(row.relPath, { channelId: row.linkId, hash: row.target });
+        }
+      }
+      const territories = new Set(observer.listRoots()
+        .filter((row) => row.kind === 'repo' && row.path.startsWith(`${groundPath}/`))
+        .map((row) => row.path.slice(groundPath.length + 1)));
+
+      // Continuity pass — the channel law applied, kind-blind. Folders
+      // move FIRST (before territories and files), because one folder move
+      // carries every descendant's derived address with it — including a
+      // territory's — and files judged after it see live truth. "No
+      // canonical ground elsewhere" is asked live for the same reason.
+      //
+      // A contest is recorded at its ROOT only: everything beneath a
+      // contested address is contested by arithmetic (`ancestorContested`),
+      // reported as divergence each reconcile, never stored per descendant
+      // — one contest, one durable marker, however large the subtree.
+      const contestedNow = new Map(); // relPath -> { uuid, kind } — roots only
+      const nowDivergent = new Map(); // relPath -> hash (null for dir ground)
+      const ancestorContested = (relPath) => {
+        const parts = relPath.split('/');
+        for (let i = 1; i < parts.length; i++) {
+          const prefix = parts.slice(0, i).join('/');
+          if (contested.has(prefix) || contestedNow.has(prefix)) return true;
+        }
+        return false;
+      };
+      const underContest = (relPath) => contested.has(relPath) || contestedNow.has(relPath)
+        || ancestorContested(relPath);
+      const channelPaths = new Map(); // uuid -> [relPath] of its live channels
+      for (const desired of [desiredDirs, desiredFiles, desiredLinks]) {
+        for (const [relPath, { channelId }] of desired) {
+          const uuid = channelToUuid.get(channelId);
+          if (uuid === undefined) continue;
+          if (!channelPaths.has(uuid)) channelPaths.set(uuid, []);
+          channelPaths.get(uuid).push(relPath);
+        }
+      }
+      const groundedElsewhere = (uuid) => {
+        const home = pathOf(uuid);
+        return (channelPaths.get(uuid) ?? []).some((rel) => rel === home);
+      };
+      // Each channel whose record must move is settled in rounds, because
+      // directories cross by inode: a claim whose slot is held by another
+      // waiting mover waits with it, and when no one can move, the waiters
+      // hold each other's addresses — one permutation, one transition
+      // (registry.moveMany). Everything else is the channel law verbatim:
+      // a parked or immovable occupant, ground under an undecided
+      // ancestor, or an entity already grounded at home is a contest —
+      // move neither, write nothing.
+      const claimsOf = (desired, kind) => {
+        const claims = [];
+        for (const [relPath, entry] of desired) {
+          const uuid = channelToUuid.get(entry.channelId);
+          if (uuid === undefined) continue;
+          if (pathOf(uuid) === relPath) {
+            attestPayload(kind, uuid, entry);
+            continue;
+          }
+          claims.push({ relPath, uuid, entry });
+        }
+        return claims;
+      };
+      const parentOf = (relPath) => (path.dirname(relPath) === '.' ? '' : path.dirname(relPath));
+      const settleClaims = (claims, kind) => {
+        let waiting = claims;
+        while (waiting.length > 0) {
+          const moving = new Set(waiting.map((claim) => claim.uuid));
+          const again = [];
+          for (const claim of waiting) {
+            const { relPath, uuid, entry } = claim;
+            if (pathOf(uuid) === relPath) {
+              // a parent's move respelled home mid-flight: recorded once,
+              // descendants silent
+              attestPayload(kind, uuid, entry);
+              continue;
+            }
+            if (contested.has(relPath) || contestedNow.has(relPath)) {
+              contestedNow.set(relPath, { uuid, kind });
+              continue;
+            }
+            if (ancestorContested(relPath)) {
+              nowDivergent.set(relPath, kind === 'file' ? entry.hash : null);
+              continue;
+            }
+            const occupant = activeAtPath(relPath, root);
+            if (occupant) {
+              if (moving.has(occupant.uuid)) again.push(claim);
+              else contestedNow.set(relPath, { uuid, kind });
+              continue;
+            }
+            if (groundedElsewhere(uuid)) {
+              contestedNow.set(relPath, { uuid, kind });
+              continue;
+            }
+            const parentUuid = ensureDir(parentOf(relPath), root);
+            registry.move(uuid, { parentUUID: parentUuid, name: path.basename(relPath) });
+            attestPayload(kind, uuid, entry);
+          }
+          if (again.length < waiting.length) {
+            waiting = again;
+            continue;
+          }
+          // Every waiter's slot is held by another waiter: an address
+          // permutation among their own records. Target parents resolve in
+          // POST state — a parent address about to be owned by a fellow
+          // mover already names its record.
+          const landing = new Map(waiting.map((claim) => [claim.relPath, claim.uuid]));
+          registry.moveMany(waiting.map(({ relPath, uuid }) => {
+            const parentRel = parentOf(relPath);
+            const parentUUID = parentRel === ''
+              ? root.uuid
+              : landing.get(parentRel) ?? activeAtPath(parentRel, root).uuid;
+            return { uuid, parentUUID, name: path.basename(relPath) };
+          }));
+          for (const { uuid, entry } of waiting) {
+            attestPayload(kind, uuid, entry);
+          }
+          waiting = [];
+        }
+      };
+      settleClaims(claimsOf(desiredDirs, 'dir'), 'dir');
+
+      // Territories after folder continuity, before file ground: a
+      // boundary is a repo.git type transition on the slot's record, and
+      // the slot must already be where its folder channel says it is.
+      for (const territory of [...territories].sort()) {
+        const parentUuid = ensureDir(path.dirname(territory) === '.' ? '' : path.dirname(territory), root);
+        const name = path.basename(territory);
+        const at = registry.activeAt(parentUuid, name);
+        if (!at) {
+          // Adoption before birth here too: a registered top-level repo
+          // TREE that moved in arrives as its own record, never a fresh
+          // territory record. The enclosed observer root's identity is
+          // the evidence — the same physical dir the orphaned tree owns.
+          const enclosed = observer.listRoots().find((row) => row.path === path.join(groundPath, territory));
+          const arrivedRecord = enclosed ? arrivedTree(enclosed.device, enclosed.inode, REPO_TREE) : null;
+          if (arrivedRecord) registry.move(arrivedRecord.uuid, { parentUUID: parentUuid, name });
+          else registry.create({ type: 'repo.git', parentUUID: parentUuid, name });
+        } else if (at.type !== 'repo.git') registry.changeType(at.uuid, 'repo.git');
+      }
+      // A lifted lens is the reverse transition on the same record.
+      for (const { record, rel } of walkActive(root.uuid, '', [])) {
+        if (record.type === 'repo.git' && !territories.has(rel)) {
+          registry.changeType(record.uuid, 'folder');
+        }
+      }
+
+      settleClaims(claimsOf(desiredFiles, 'file'), 'file');
+      settleClaims(claimsOf(desiredLinks, 'link'), 'link');
+
+      // Marker sync — the durable half of the contest. Forgetting cannot
+      // authorize assignment: a marked address stays contested while ground
+      // of the mark's own kind remains there, even when the evidence that
+      // raised the contest is gone (an observer store lost mid-contest).
+      // The ground leaving the address is the one detection-visible
+      // resolution.
+      for (const [relPath, mark] of [...contested]) {
+        const present = mark.kind === 'file' ? desiredFiles.has(relPath)
+          : mark.kind === 'link' ? desiredLinks.has(relPath)
+            : desiredDirs.has(relPath);
+        if (!present) {
+          memory.clearContest(rootId, relPath);
+          contested.delete(relPath);
+        }
+      }
+      for (const [relPath, mark] of contestedNow) {
+        const held = contested.get(relPath);
+        if (held?.uuid !== mark.uuid || held?.kind !== mark.kind) {
+          memory.contest(rootId, relPath, mark.uuid, mark.kind);
+          contested.set(relPath, mark);
+        }
+      }
+
+      // Arrival pass: an unbound channel reconnects to its slot's absent
+      // active owner — whatever kind it returns as; ownership is identity,
+      // not kind — or is a birth. Ground on or under a contested address
+      // gets no assignment and no birth; file ground on a folder that
+      // still has active children is the container refusal. Folders
+      // arrive first, parents before children, so files land under real
+      // records, never fresh scaffolding.
+      for (const [relPath, { channelId, device, inode }] of desiredDirs) {
+        if (channelToUuid.has(channelId)) continue;
+        if (underContest(relPath)) {
+          if (!contested.has(relPath)) nowDivergent.set(relPath, null);
+          continue; // reported, assigned to nobody, resolved by nothing here
+        }
+        // Adoption before birth: this directory may BE an orphaned
+        // registered tree, arrived here whole.
+        const arrivedRecord = arrivedTree(device, inode, FILES_TREE);
+        if (arrivedRecord) {
+          const parentUuid = ensureDir(path.dirname(relPath) === '.' ? '' : path.dirname(relPath), root);
+          const name = path.basename(relPath);
+          if (registry.activeAt(parentUuid, name)) {
+            nowDivergent.set(relPath, null); // two identity claims on one address: assign nothing
+            continue;
+          }
+          registry.move(arrivedRecord.uuid, { parentUUID: parentUuid, name });
+          bind(channelId, arrivedRecord.uuid);
+          continue;
+        }
+        const parentUuid = ensureDir(path.dirname(relPath) === '.' ? '' : path.dirname(relPath), root);
+        const name = path.basename(relPath);
+        const at = registry.activeAt(parentUuid, name);
+        if (at && at.type === 'folder') {
+          bind(channelId, at.uuid);
+        } else if (at && LEAF_TYPES.has(at.type)) {
+          bind(channelId, registry.changeType(at.uuid, 'folder').uuid);
+        } else if (at && at.type === 'reference') {
+          // Real ground on a rendering's slot: the projection never
+          // overwrites it, and detection assigns it to nobody — divergence.
+          nowDivergent.set(relPath, null);
+        } else if (at) {
+          continue; // a repo.git slot never transitions on ground: territory news owns it
+        } else {
+          bind(channelId, registry.create({ type: 'folder', parentUUID: parentUuid, name }).uuid);
+        }
+      }
+      for (const [relPath, entry] of desiredFiles) {
+        const { channelId, hash } = entry;
+        if (channelToUuid.has(channelId)) continue;
+        if (underContest(relPath)) {
+          if (!contested.has(relPath)) nowDivergent.set(relPath, hash);
+          continue; // reported, assigned to nobody, resolved by nothing here
+        }
+        const parentUuid = ensureDir(path.dirname(relPath) === '.' ? '' : path.dirname(relPath), root);
+        const name = path.basename(relPath);
+        const at = registry.activeAt(parentUuid, name);
+        if (at && at.type === 'folder') {
+          if (registry.children(at.uuid).some((child) => child.status === 'active')) {
+            nowDivergent.set(relPath, hash);
+            continue;
+          }
+          const asFile = registry.changeType(at.uuid, classify(entry), { payloadVersion: hash });
+          bind(channelId, asFile.uuid);
+        } else if (at && LEAF_TYPES.has(at.type)) {
+          // Slot reconnection is identity, not kind: the absent owner
+          // returns as file ground, and the record transitions with it —
+          // one attestation, whichever leaf kind it was wearing.
+          bind(channelId, at.uuid);
+          attestPayload('file', at.uuid, entry);
+        } else if (at && at.type === 'reference') {
+          // Real ground on a rendering's slot: the projection never
+          // overwrites it, and detection assigns it to nobody — divergence.
+          nowDivergent.set(relPath, hash);
+        } else if (at) {
+          continue; // a repo.git slot never transitions on ground: territory news owns it
+        } else {
+          const born = registry.create({
+            type: classify(entry),
+            parentUUID: parentUuid, name, payloadVersion: hash,
+          });
+          bind(channelId, born.uuid);
+        }
+      }
+      // Link arrivals: same law, third kind — the payload is the pointer
+      // exactly as disk wrote it, and no classification is asked (linkness
+      // is decided by disk, not by policy).
+      for (const [relPath, { channelId, hash: target }] of desiredLinks) {
+        if (channelToUuid.has(channelId)) continue;
+        if (underContest(relPath)) {
+          if (!contested.has(relPath)) nowDivergent.set(relPath, target);
+          continue; // reported, assigned to nobody, resolved by nothing here
+        }
+        const parentUuid = ensureDir(path.dirname(relPath) === '.' ? '' : path.dirname(relPath), root);
+        const name = path.basename(relPath);
+        const at = registry.activeAt(parentUuid, name);
+        if (at && at.type === 'reference') {
+          // The rendered symlink IS the reference's local ground: its
+          // channel binds, but its target text never attests — the
+          // reference's payload is the target's IDENTITY, written by the
+          // deliberate act that created it, and the rendered address is
+          // derived state the boundary maintains.
+          bind(channelId, at.uuid);
+        } else if (at && LEAF_TYPES.has(at.type)) {
+          // The same reconnection law, third kind: the owner returns as a
+          // pointer, and one attestation carries the record across.
+          bind(channelId, at.uuid);
+          attestPayload('link', at.uuid, { hash: target });
+        } else if (at && at.type === 'folder') {
+          if (registry.children(at.uuid).some((child) => child.status === 'active')) {
+            nowDivergent.set(relPath, target); // the container refusal, kind-blind
+            continue;
+          }
+          bind(channelId, registry.changeType(at.uuid, 'link', { payloadVersion: target }).uuid);
+        } else if (at) {
+          continue; // a repo.git slot never carries a link channel; territory news owns it
+        } else {
+          bind(channelId, registry.create({ type: 'link', parentUUID: parentUuid, name, payloadVersion: target }).uuid);
+        }
+      }
+
+      // Departure pass: a channel gone from truth closed; the entity LIVES,
+      // its record unmoved — releasing the binding is all that happens.
+      const liveIds = new Set([
+        rootRow.rootId, // the witness: live for as long as the root is enrolled
+        ...[...desiredDirs.values()].map((entry) => entry.channelId),
+        ...[...desiredFiles.values()].map((entry) => entry.channelId),
+        ...[...desiredLinks.values()].map((entry) => entry.channelId),
+      ]);
+      for (const channelId of [...channelToUuid.keys()]) {
+        if (!liveIds.has(channelId)) release(channelId);
+      }
+
+      // One divergence report, two sources: contested ground (marked, with
+      // its current bytes — null when the ground is a directory) and the
+      // container refusal.
+      divergent = new Map();
+      for (const [relPath, mark] of contested) {
+        divergent.set(relPath, mark.kind === 'file' ? desiredFiles.get(relPath).hash
+          : mark.kind === 'link' ? desiredLinks.get(relPath).hash
+            : null);
+      }
+      for (const [relPath, hash] of nowDivergent) divergent.set(relPath, hash);
+    } catch (error) {
+      dirty = true;
+      throw error;
+    }
+  }
+
+  function tryReconcile() {
+    try {
+      reconcile();
+    } catch (error) {
+      console.warn('[Evidence] reconcile failed (intake stays dirty):', error?.message || error);
+    }
+  }
+
+  return {
+    /** INFALLIBLE by construction: mark dirty, schedule, return. */
+    onEvent() {
+      if (stopped) return;
+      dirty = true;
+      if (scheduled) return;
+      scheduled = true;
+      const immediate = setImmediate(() => {
+        scheduled = false;
+        if (stopped) return; // the world closed under an already-queued pass
+        if (dirty) tryReconcile();
+      });
+      immediate.unref?.();
+    },
+
+    /**
+     * Shut down: honor no more hints, and let no queued pass run. A lens
+     * owns no handles — its stores belong to whoever opened them — but it
+     * DOES own a scheduled reconciliation, and one that lands after those
+     * stores close would warn about a shutdown that went exactly right.
+     * Dirty state stays dirty on purpose: the next lens over this tree
+     * reconciles at birth, which is the same act.
+     */
+    stop() {
+      stopped = true;
+    },
+
+    reconcile,
+    flushIfDirty() {
+      if (dirty) tryReconcile();
+      return !dirty;
+    },
+    dirty: () => dirty,
+    divergence: () => new Map(divergent),
+    boundUuid: (channelId) => channelToUuid.get(channelId),
+  };
+}
+
+module.exports = { assertWitnessed, createEvidence, createEvidenceMemory };