amalgm 0.1.245 → 0.1.246

package/runtime/scripts/amalgm-mcp/registration/index.js

@@ -0,0 +1,752 @@
+'use strict';
+
+/**
+ * The shared registration operation — the `amalgm register` boundary
+ * (docs/realtime-rails.md §3.1). One call turns a path into registered,
+ * watched ground: inspect the address (a symlink registers AS the link
+ * before anything resolves it), enroll exactly that ground with the
+ * observer, register it in the ONE identity registry, then follow every
+ * symlink edge to a fixpoint so each reachable real target is registered
+ * exactly once. The CLI and SDK both call this; neither reimplements it.
+ *
+ * The model, in five sentences. ONE identity database holds every
+ * registered entity on this installation; a TREE is one active
+ * parentless record with its descendants beneath it — a sync boundary
+ * (its own future head and rail), never an identity boundary. Every
+ * top-level enrolled ground — a workspace, a repository, a single file,
+ * or an explicitly added link — is such a tree, with one evidence LENS
+ * over its observer root (nested repo territories live INSIDE their
+ * tree as repo.git records; they are never trees of their own). A
+ * TREE'S IDENTITY IS ITS UUID, PERMANENT; its root path is only the
+ * current local address — lenses are keyed by the observer's rootId
+ * (the witness), the observer rescues moved ground by physical
+ * continuity, and an orphaned tree arriving inside another tree is
+ * ADOPTED there: one lawful parent update on its parentless record,
+ * after which this boundary retires the orphan's observer roots and
+ * evidence scope (the ground is covered by its new tree). "Watched"
+ * and "registered" are the same act here: an observer root this
+ * boundary enrolls always gets its lens and record, so nothing is ever
+ * ground without identity. What a pointer REACHES is derived at this
+ * layer and only here — resolution needs eyes on every tree, so
+ * `linkTargets` lives on the boundary, not inside any single lens.
+ *
+ * THE LOSS LAW (evidence.js assertWitnessed): 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, and this boundary
+ * convicts that loudly before any lens reconciles — a lost store is
+ * never a fresh start, and no replacement identities mint over
+ * surviving records. Re-enrollment after loss is an explicit act.
+ *
+ * Registration is add-only and policy-gated: following edges and adding
+ * ground never remove coverage; amalgm's enrollment policy is asked on
+ * EVERY route (an edge is refused and reported, an explicit add refuses
+ * loudly — the deliberate override is future work); and a target ground
+ * that would swallow an enrolled root is refused (`reported()`) — one
+ * owner per path. Removing coverage is a future explicit operation
+ * (`amalgm remove`), never a side effect. (Retiring an adopted tree's
+ * observer roots is not removal: the same ground stays covered, by its
+ * new tree.)
+ *
+ * Storage policy is injected (the Axiom-2 pattern): `openIdentity()` is
+ * called ONCE and returns `{ db, sentinelPath }` for the durable
+ * installation registry or `{ db, ephemeral: true }` for a real
+ * in-memory one. One database, one sentinel, one epoch — identity is
+ * never partitioned by tree, which is exactly what makes a cross-tree
+ * move one transaction instead of an export between databases.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { followEdges } = require('../observer/edges');
+const { createRegistry } = require('../registry');
+const { assertWitnessed, createEvidence, createEvidenceMemory } = require('../registry/evidence');
+const { capture } = require('../repocard');
+const { refusal } = require('./refusal');
+const { createRepoFollowers } = require('./repo-followers');
+const { createRepoStates } = require('./repo-states');
+const { registerTree } = require('./tree');
+
+// Events that can change what the recorded edges reach: a new or
+// retargeted pointer, repo ground moving under its card (a worktree
+// change may be a symlink change — the census reads fresh), or a whole
+// root at a new address (its relative out-edges resolve from there now).
+const EDGE_EVENTS = new Set(['link.created', 'link.changed', 'repo.changed', 'repo.discovered', 'root.moved']);
+
+function createRegistration(options) {
+  const { observer, openIdentity, classify, emit = () => {} } = options;
+  if (!observer) throw new Error('createRegistration requires { observer }');
+  if (typeof openIdentity !== 'function') {
+    throw new Error('createRegistration requires { openIdentity }: () => ({ db, sentinelPath }) or ({ db, ephemeral: true }) — ONE identity database holds every registered tree, opened once');
+  }
+  if (typeof classify !== 'function') {
+    throw new Error('createRegistration 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');
+  }
+
+  const opened = openIdentity();
+  const registry = createRegistry({
+    db: opened.db,
+    sentinelPath: opened.sentinelPath,
+    ephemeral: opened.ephemeral,
+    emit,
+    journal: opened.journal ?? null,
+  });
+  const memory = createEvidenceMemory(opened.db);
+  const repoStates = createRepoStates(opened.db);
+  const lenses = new Map(); // rootId (permanent witness) -> evidence lens
+  let reported = []; // the latest edge pass's refusals
+  let edgesDirty = false;
+  let scheduled = false;
+  let stopped = false;
+  const repoFollowers = createRepoFollowers({
+    observer,
+    registry,
+    repoStates,
+    recordForRoot: repoRecordForRoot,
+    onSettled: reconcileSettledRepo,
+  });
+
+  /** Tree roots are the non-enclosed observer roots: a nested repo
+   * territory belongs to the tree that encloses it. */
+  function treeRoots() {
+    const roots = observer.listRoots();
+    return roots.filter((root) => !roots.some((other) =>
+      other.rootId !== root.rootId && root.path.startsWith(`${other.path}/`)));
+  }
+
+  function treeRootCovering(absPath) {
+    return treeRoots()
+      .filter((root) => absPath === root.path || absPath.startsWith(`${root.path}/`))
+      .sort((a, b) => b.path.length - a.path.length)[0] ?? null;
+  }
+
+  /** The tree's top record, found the only honest way: by its witness. */
+  function rootRecordOf(rootId) {
+    const uuid = memory.boundTo(rootId);
+    return uuid === undefined ? null : registry.record(uuid);
+  }
+
+  /** Watched implies registered: every tree root gets its lens, born
+   * with one reconciliation (events are hints; birth reads store truth).
+   * A lens whose witness record gained a parent was ADOPTED into another
+   * tree — its ground is covered there now, so its observer family and
+   * evidence scope retire. Idempotent; convicts loss first (the loss
+   * law, evidence.js `assertWitnessed`). */
+  function ensureTrees() {
+    assertWitnessed({ observer, registry, memory });
+    // Retirement residue: a scope whose witness root no longer lives is a
+    // finished retirement's leftovers. The loss law above already vouched
+    // for every living tree — a dead-witness binding on a PARENTLESS
+    // record convicted there — so dropping the rest can never erase a
+    // claim, and a retirement torn at any point completes right here.
+    const liveIds = new Set(observer.listRoots().map((row) => row.rootId));
+    for (const { scopeId } of memory.allBindings()) {
+      if (!liveIds.has(scopeId)) memory.dropScope(scopeId);
+    }
+    for (const [rootId] of [...lenses]) {
+      const row = observer.listRoots().find((member) => member.rootId === rootId);
+      if (!row) {
+        lenses.delete(rootId);
+        continue;
+      }
+      const record = rootRecordOf(rootId);
+      const nestedRepoScope = row.kind === 'repo' && record?.type === 'repo.git'
+        && observer.listRoots().some((other) => other.rootId !== row.rootId
+          && row.path.startsWith(`${other.path}/`));
+      if (record && record.parentUUID !== null && !nestedRepoScope) {
+        // Retirement is EVIDENCE FIRST, IDENTITY LAST: observer rows go
+        // before the witness binding (descendants before the root), so a
+        // crash anywhere leaves either a living root whose binding still
+        // proves the adoption — retried here — or dead-scope residue the
+        // sweep above collects. The reverse order once minted a duplicate
+        // tree: an unbound living root looks like fresh ground.
+        const family = observer.listRoots()
+          .filter((member) => member.rootId === rootId || member.path.startsWith(`${row.path}/`));
+        for (const member of family) {
+          if (member.rootId !== rootId) observer.removeRoot(member.rootId);
+        }
+        observer.removeRoot(rootId);
+        memory.dropScope(rootId);
+        lenses.delete(rootId);
+      }
+    }
+    for (const root of treeRoots()) {
+      if (lenses.has(root.rootId)) continue;
+      const lens = createEvidence({ observer, registry, memory, rootId: root.rootId, classify });
+      lenses.set(root.rootId, lens);
+      lens.reconcile();
+    }
+    // A nested repository is one semantic root inside its enclosing tree.
+    // It therefore gets its own evidence scope (for its child channels),
+    // while retaining its existing parent UUID. The top-level tree lens
+    // never walks through this boundary.
+    for (const root of observer.listRoots().filter((row) => row.kind === 'repo')) {
+      const record = repoRecordForRoot(root);
+      if (!record) continue;
+      if (memory.boundTo(root.rootId) !== record.uuid) {
+        memory.bind(root.rootId, root.rootId, record.uuid);
+      }
+      if (lenses.has(root.rootId)) continue;
+      const lens = createEvidence({ observer, registry, memory, rootId: root.rootId, classify });
+      lenses.set(root.rootId, lens);
+      lens.reconcile();
+    }
+  }
+
+  function follow() {
+    edgesDirty = false;
+    try {
+      const result = followEdges(observer);
+      registerFollowedTrees();
+      // An unsettled edge surface concludes nothing about completeness:
+      // the boundary stays dirty, and the observer's own backed-off
+      // rescan of that ground rings `repo.changed` when it settles —
+      // which re-marks the edges dirty here and retries the follow.
+      if (!result.settled) edgesDirty = true;
+      reported = result.reported;
+      ensureTrees();
+      return result;
+    } catch (error) {
+      edgesDirty = true;
+      throw error;
+    }
+  }
+
+  /**
+   * `followEdges` is deliberately identity-free: it establishes what real
+   * ground is reachable and asks the observer to cover it. Identity must be
+   * born here, at the registration boundary, before a lens can reconcile the
+   * new root. That makes an edge-reached repository the same thing as a
+   * directly added repository: a complete structural tree plus one initial
+   * Card + Checkpoint document, all before Watch + Detect can describe it.
+   *
+   * Only non-enclosed roots are enrolled here. Nested repositories belong to
+   * their enclosing structural walk, which creates their `repo.git` records
+   * and baselines in the same transaction as their parent tree.
+   */
+  function registerFollowedTrees() {
+    const unregistered = treeRoots()
+      .filter((root) => memory.boundTo(root.rootId) === undefined)
+      .sort((left, right) => left.path.localeCompare(right.path));
+
+    for (const root of unregistered) {
+      try {
+        assertWitnessed({ observer, registry, memory });
+        registerTree({
+          root,
+          registry,
+          memory,
+          shouldEnroll: observer.shouldEnroll,
+          captureRepo: (repoPath) => capture(repoPath, { withBundle: false }),
+          repoStates,
+        });
+      } catch (error) {
+        // An observer root is only coverage until its one structural
+        // registration transaction commits. Leave no watched-but-unregistered
+        // family behind: the still-present link will attempt this same add on
+        // the next edge pass, while a successful sibling stays intact.
+        const family = observer.listRoots()
+          .filter((member) => member.path === root.path || member.path.startsWith(`${root.path}/`))
+          .sort((left, right) => right.path.length - left.path.length);
+        for (const member of family) observer.removeRoot(member.rootId);
+        throw error;
+      }
+    }
+  }
+
+  function tryFollow() {
+    try {
+      follow();
+    } catch (error) {
+      console.warn('[Registration] edge follow failed (stays dirty):', error?.message || error);
+    }
+  }
+
+  /**
+   * The entity that OWNS a derived address inside one tree, walked slot
+   * by slot — '' is the tree's root record. Repository boundaries select
+   * Card + Checkpoint realtime semantics, but their allowed descendants
+   * still have records; this walk therefore always reaches the exact
+   * registered entity at the address.
+   */
+  function owningRecordAt(rootRecord, relPath) {
+    if (!rootRecord) return null;
+    if (relPath === '') return rootRecord;
+    let cursor = rootRecord.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]);
+  }
+
+  /** The `repo.git` entity an observer repo root represents. A directly
+   * registered repo owns itself; a nested repo owns its own boundary
+   * record, even though its worktree leaves are structurally registered
+   * below that record. */
+  function repoRecordForRoot(repoRoot) {
+    const home = treeRootCovering(repoRoot.path);
+    if (!home) return null;
+    const tree = rootRecordOf(home.rootId);
+    if (!tree) return null;
+    const rel = repoRoot.path === home.path ? '' : repoRoot.path.slice(home.path.length + 1);
+    const record = owningRecordAt(tree, rel);
+    return record?.type === 'repo.git' ? record : null;
+  }
+
+  /**
+   * Card + Checkpoint is the filter for repo children. This is the only
+   * place ordinary worktree channels are refreshed for a repo root: raw
+   * filesystem doorbells wake the follower, and a settled follower calls
+   * here exactly once for the resulting state.
+   */
+  function reconcileSettledRepo({ root }) {
+    observer.reconcileRepoWorktree(root.rootId);
+    ensureTrees();
+    lenses.get(root.rootId)?.flushIfDirty();
+  }
+
+  /** Establish every repo's initial child-channel baseline after its
+   * structural tree and persisted Card + Checkpoint already exist. Nested
+   * repos appear while their parent is scanned, so loop to the fixed point. */
+  function reconcileInitialRepoWorktrees(rootPath) {
+    const seen = new Set();
+    while (true) {
+      const pending = observer.listRoots().filter((root) => root.kind === 'repo'
+        && (root.path === rootPath || root.path.startsWith(`${rootPath}/`))
+        && !seen.has(root.rootId));
+      if (pending.length === 0) return;
+      for (const root of pending) {
+        seen.add(root.rootId);
+        observer.reconcileRepoWorktree(root.rootId);
+      }
+      ensureTrees();
+      for (const root of pending) lenses.get(root.rootId)?.flushIfDirty();
+    }
+  }
+
+  /**
+   * One observer event wakes one Record owner. An observer root with its own
+   * lens (every repo.git boundary, including a nested one) owns the event it
+   * emitted. Only events from ground without a lens fall back to the
+   * enclosing tree. Containment and event ownership are different questions:
+   * the former finds a parent tree; the latter must preserve the semantic
+   * boundary that detected the change.
+   */
+  function notifyEventOwner(event) {
+    const direct = event.rootId ? lenses.get(event.rootId) : null;
+    if (direct) {
+      direct.onEvent();
+      return;
+    }
+    const row = observer.listRoots().find((root) => root.rootId === event.rootId);
+    const home = row ? treeRootCovering(row.path)
+      : (typeof event.path === 'string' && path.isAbsolute(event.path) ? treeRootCovering(event.path) : null);
+    if (home) lenses.get(home.rootId)?.onEvent();
+    else for (const lens of lenses.values()) lens.onEvent();
+  }
+
+  /** `add` may only claim success when every watcher it established is
+   * genuinely live. A filesystem watcher that could not open is not a
+   * warning; it means the requested Register → Watch operation is incomplete
+   * and the caller must hear that. */
+  function requireLiveWatchers(rootPath) {
+    const belongs = (root) => root.path === rootPath || root.path.startsWith(`${rootPath}/`);
+    let unavailable = observer.status().filter((root) => belongs(root)
+      && (!root.watching || root.degraded || (root.addressRequired
+        && (!root.addressWatching || root.addressDegraded))));
+    // A normal successful start is left alone. Only a failed watcher birth
+    // is retried, so registration has one deliberate Watch transition.
+    for (const failed of unavailable) observer.start(failed.rootId);
+    unavailable = observer.status().filter((root) => (root.path === rootPath
+      || root.path.startsWith(`${rootPath}/`))
+      && (!root.watching || root.degraded || (root.addressRequired
+        && (!root.addressWatching || root.addressDegraded))));
+    if (unavailable.length > 0) {
+      throw new Error(`registered ${rootPath}, but could not start required watcher(s): ${unavailable.map((root) => root.path).join(', ')}`);
+    }
+  }
+
+  /** Real ground -> the UUID of the entity that owns it, across trees. */
+  function resolveGround(real) {
+    const home = treeRootCovering(real);
+    if (!home) return null;
+    const rel = real === home.path ? '' : real.slice(home.path.length + 1);
+    return owningRecordAt(rootRecordOf(home.rootId), rel)?.uuid ?? null;
+  }
+
+  /** The directory an edge's relative target resolves against — a
+   * single-ground pointer root's base is its parent directory. */
+  function edgeBase(root, relPath) {
+    if (root.kind === 'file') return path.dirname(root.path);
+    return path.resolve(root.path, path.dirname(relPath));
+  }
+
+  function treeAt(rootPath) {
+    const root = observer.listRoots().find((row) => row.path === rootPath);
+    const lens = root && lenses.get(root.rootId);
+    if (!lens) return null;
+    return {
+      registry,
+      evidence: lens,
+      root: () => rootRecordOf(root.rootId),
+    };
+  }
+
+  /** An entity's CURRENT local address, derived from its record chain and
+   * its tree's observer address — never stored. null when its tree is not
+   * locally bound. */
+  function addressOf(uuid) {
+    const names = [];
+    let record = registry.record(uuid);
+    while (record.parentUUID !== null) {
+      names.unshift(record.name);
+      record = registry.record(record.parentUUID);
+    }
+    const home = treeRoots().find((row) => memory.boundTo(row.rootId) === record.uuid);
+    if (!home) return null;
+    return names.length === 0 ? home.path : path.join(home.path, ...names);
+  }
+
+  /**
+   * A managed reference is CANONICAL REGISTRY TRUTH with an idempotent
+   * local projection, and this is the projector: each reference's
+   * rendering must be a symlink at the reference's derived address,
+   * pointing at its target's current address. A missing rendering is
+   * recreated; a drifted one is rewritten. The rewrite is
+   * remove-then-render, deliberately not a temp-and-rename: a crash
+   * between the two acts leaves a missing rendering — exactly what the
+   * next pass recreates — while a stray temp name inside user ground
+   * would be scanned as new ground and mint an entity. Convergence is
+   * the atomicity. Real ground occupying the slot is NEVER overwritten
+   * (the lens reports that divergence); a target with no local address
+   * leaves the rendering as it stands — dangling is honest — repaired
+   * the moment the target is rescued or reattached. This is the one
+   * place the detection side writes disk, and it writes only Amalgm's
+   * own artifact — never user data. A write echoes back as a link
+   * channel fact; the entity stays silent because a reference's payload
+   * is identity, which no ground can attest.
+   */
+  function maintainReferences() {
+    for (const { record, targetUUID } of registry.references()) {
+      const rendered = addressOf(record.uuid);
+      if (rendered === null) continue; // the reference's own tree is not locally bound
+      let target;
+      try {
+        target = addressOf(targetUUID);
+      } catch {
+        continue; // the target record is gone from this registry: nothing to aim at
+      }
+      if (target === null) continue; // target unavailable: dangling (or missing) until rescue repairs it
+      let current = null; // null = no rendering holds the slot
+      try {
+        const stat = fs.lstatSync(rendered);
+        if (!stat.isSymbolicLink()) continue; // real ground on the slot: divergence (the lens reports it), never overwritten
+        current = fs.readlinkSync(rendered);
+      } catch {
+        current = null; // missing, or raced away mid-look: recreated below
+      }
+      if (current === target) continue; // the projection already holds
+      if (current !== null) fs.unlinkSync(rendered);
+      fs.symlinkSync(target, rendered);
+      const home = treeRootCovering(rendered);
+      if (home) {
+        observer.scanNow(home.rootId);
+        // The write's echo may fire where no boundary listens yet (the
+        // startup pass runs during construction), so the projector hands
+        // the fact over itself: the next pass always binds the
+        // rendering's channel.
+        lenses.get(home.rootId)?.onEvent();
+      }
+    }
+  }
+
+  /**
+   * `amalgm register <path>` has two deliberately ordered acts:
+   *
+   *   1. Register the complete entity tree from its structural shape.
+   *   2. Start Watch and let Detect describe the ground from then on.
+   *
+   * The address is inspected first: a symlink at it registers as the link
+   * entity itself (its target then follows after detection), and only real
+   * ground is resolved. Exactly the named ground enrolls — a file or link
+   * as a tree of one, a repo only when the named path IS the repo root.
+   * Changes while the registration walk runs are outside this operation's
+   * contract; no readiness protocol or user-ground mutation is involved.
+   */
+  function add(targetPath, options = {}) {
+    const identityAt = options.identityAt ?? null;
+    if (identityAt !== null && typeof identityAt !== 'function') {
+      throw new Error('add identityAt must be a function when supplied');
+    }
+    let address;
+    let ground;
+    try {
+      const parent = fs.realpathSync(path.dirname(targetPath));
+      address = path.join(parent, path.basename(targetPath));
+      ground = fs.lstatSync(address).isSymbolicLink() ? address : fs.realpathSync(address);
+    } catch (error) {
+      // Ground that is not there is a REFUSAL of this request, not a
+      // fault: nothing is wrong with the installation, the address is
+      // simply not ground. (An address that exists but cannot be read
+      // is not this: it falls through as the fault it is.)
+      if (error.code !== 'ENOENT' && error.code !== 'ENOTDIR') throw error;
+      throw refusal(`refusing to add ${targetPath}: there is no ground at that address`);
+    }
+    const covering = treeRootCovering(ground);
+    if (covering) {
+      ensureTrees();
+      tryFollow();
+      requireLiveWatchers(covering.path);
+      return { rootPath: covering.path, record: rootRecordOf(covering.rootId) };
+    }
+    // The policy judges the COMPLETE address — a benign final name
+    // inside excluded ground (.ssh/config) is still excluded.
+    if (!observer.shouldEnroll(ground)) {
+      throw refusal(`refusing to add ${ground}: amalgm's enrollment policy excludes it — the explicit override is a future deliberate operation, never a default`);
+    }
+    const swallowed = observer.listRoots().filter((root) => root.path.startsWith(`${ground}/`));
+    if (swallowed.length > 0) {
+      throw refusal(`refusing to add ${ground}: it contains already-registered ground (${swallowed.map((root) => root.path).join(', ')}) — one owner per path; remove the inner registration first, explicitly`);
+    }
+    const root = observer.enrollRoot(ground, { scan: false, watch: false });
+    try {
+      assertWitnessed({ observer, registry, memory });
+      registerTree({
+        root,
+        registry,
+        memory,
+        shouldEnroll: observer.shouldEnroll,
+        captureRepo: (repoPath) => capture(repoPath, { withBundle: false }),
+        repoStates,
+        identityAt,
+      });
+    } catch (error) {
+      // The observer root is only an address until structural registration
+      // commits. Do not leave an unregistered address behind after a refused
+      // or failed walk; a committed tree, by contrast, is durable truth and
+      // is never rolled back by a later Watch/Detect fault.
+      observer.removeRoot(root.rootId);
+      throw error;
+    }
+    // Registration committed the complete structural tree before Watch.
+    // Start's first census must run before a parent lens is allowed to
+    // conclude that a pre-registered nested repo is absent: unobserved is
+    // not absent. Only then do evidence lenses reconcile that census.
+    observer.start(root.rootId);
+    ensureTrees();
+    reconcileInitialRepoWorktrees(root.path);
+    flushIfDirty();
+    requireLiveWatchers(root.path);
+    return { rootPath: root.path, record: rootRecordOf(root.rootId) };
+  }
+
+  /**
+   * Many explicit paths, one registration primitive. A batch does not invent
+   * a second transaction model: every selected root follows the exact same
+   * Register → Watch transition as a one-path `add`, in caller order. Input
+   * shape is validated before the first registration; thereafter each result
+   * is durable before its watcher begins, so a later watcher fault cannot
+   * falsely report an all-or-nothing batch after earlier identity committed.
+   *
+   * The object form is internal-only bootstrap support for remote-first UUID
+   * binding. The public CLI/API supplies strings and can never choose UUIDs.
+   */
+  function addMany(entries) {
+    if (!Array.isArray(entries) || entries.length === 0) {
+      throw new Error('addMany requires one or more target paths');
+    }
+    const normalized = entries.map((entry) => {
+      if (typeof entry === 'string') return { targetPath: entry, identityAt: null };
+      if (!entry || typeof entry !== 'object' || typeof entry.targetPath !== 'string') {
+        throw new Error('addMany entries must be paths or { targetPath, identityAt }');
+      }
+      if (entry.identityAt !== undefined && entry.identityAt !== null && typeof entry.identityAt !== 'function') {
+        throw new Error('addMany identityAt must be a function when supplied');
+      }
+      return { targetPath: entry.targetPath, identityAt: entry.identityAt ?? null };
+    });
+    return normalized.map(({ targetPath, identityAt }) => add(targetPath, { identityAt }));
+  }
+
+  /** The boundary's whole convergence pass, one act: loss convicted
+   * first (loudly — a conviction is never a retry), edges followed,
+   * lenses reconciled, renderings projected. Startup, the explicit
+   * call, and the event-scheduled one all run this same code. */
+  function flushIfDirty() {
+    ensureTrees();
+    if (edgesDirty) tryFollow();
+    let clean = !edgesDirty;
+    for (const lens of lenses.values()) clean = lens.flushIfDirty() && clean;
+    maintainReferences(); // renderings follow their targets' current addresses
+    // The filesystem lens owns ordinary ground. A repo's detector is its
+    // Repocard follower: raw repo doorbells become settled Card + Checkpoint
+    // state, then authorize one reconciliation of registered worktree leaves.
+    repoFollowers.sync();
+    return clean;
+  }
+
+  // Startup is the same act as running — the one convergence pass,
+  // nothing less. The projection must not wait for an event: a
+  // rendering whose deletion was detected before a crash is equal
+  // truth at the catch-up scan — silence — and silence never heals.
+  edgesDirty = true;
+  flushIfDirty();
+
+  return {
+    // The service-level cloud boundary consumes the logical registry only;
+    // observer bindings remain private to this registration composition.
+    registry,
+    add,
+    addMany,
+
+    /**
+     * `amalgm register <existing-path> --as <address>` — the managed
+     * reference, the OTHER link kind (never conflated with a filesystem
+     * symlink): created only by this deliberate act, its payload is the
+     * TARGET ENTITY'S UUID, and its local rendering as an ordinary
+     * symlink at `atPath` is derived state this boundary maintains. The
+     * target registers first through the same `add` operation; the
+     * reference then lives inside already-registered ground (the Amalgm
+     * home), so an observed target move rewrites the rendering while
+     * the reference and target UUIDs never change. An unavailable
+     * target leaves the rendering dangling — honest — until rescue or
+     * reattachment repairs it.
+     */
+    addReference(targetPath, atPath) {
+      const target = add(targetPath);
+      const real = fs.lstatSync(targetPath).isSymbolicLink() ? targetPath : fs.realpathSync(targetPath);
+      const targetUuid = resolveGround(real) ?? target.record.uuid;
+      const parent = fs.realpathSync(path.dirname(atPath));
+      const address = path.join(parent, path.basename(atPath));
+      const home = treeRootCovering(parent);
+      if (!home || home.kind !== 'files') {
+        throw refusal(`a reference lives inside registered workspace ground: ${address} is not covered by one — add its workspace first`);
+      }
+      const parentRel = parent === home.path ? '' : parent.slice(home.path.length + 1);
+      const owner = owningRecordAt(rootRecordOf(home.rootId), parentRel);
+      if (!owner) {
+        throw new Error(`no registered entity owns ${parent} yet — flush the boundary before placing a reference there`);
+      }
+      // The deliberate act is IDEMPOTENT: asking for a reference that
+      // already exists converges its rendering below instead of refusing
+      // — a failed first attempt is retried by repeating it. Any OTHER
+      // occupant, record or ground, refuses: one owner per path.
+      const existing = registry.activeAt(owner.uuid, path.basename(atPath));
+      if (existing && registry.references()
+        .find((ref) => ref.record.uuid === existing.uuid)?.targetUUID !== targetUuid) {
+        throw refusal(`refusing to render a reference over existing ground at ${address} — one owner per path`);
+      }
+      if (!existing) {
+        let occupied = true;
+        try {
+          fs.lstatSync(address);
+        } catch {
+          occupied = false;
+        }
+        if (occupied) {
+          throw refusal(`refusing to render a reference over existing ground at ${address} — one owner per path`);
+        }
+      }
+      const record = existing ?? registry.create({
+        type: 'reference', parentUUID: owner.uuid, name: path.basename(atPath),
+        payloadVersion: targetUuid,
+      });
+      // The record is canonical; the rendering is the same idempotent
+      // projection every flush performs — projected first so the full
+      // pass that follows binds the rendering's channel to the record
+      // (attesting nothing).
+      maintainReferences();
+      flushIfDirty();
+      return { record, targetUUID: targetUuid };
+    },
+
+    /** INFALLIBLE by construction: route the hint, mark edge news dirty,
+     * schedule, return. Wire the observer's emit here. The scheduled
+     * pass is the FULL flush — reference maintenance included, so
+     * renderings converge after events, never only on an explicit ask —
+     * with failures warned and left dirty for the next pass. */
+    onEvent(event) {
+      if (stopped) return;
+      repoFollowers.onObserverEvent(event);
+      if (EDGE_EVENTS.has(event.type)) edgesDirty = true;
+      notifyEventOwner(event);
+      if (scheduled) return;
+      scheduled = true;
+      const immediate = setImmediate(() => {
+        scheduled = false;
+        if (stopped) return; // the world closed under an already-queued pass
+        try {
+          flushIfDirty();
+        } catch (error) {
+          console.warn('[Registration] scheduled flush failed (stays dirty):', error?.message || error);
+        }
+      });
+      immediate.unref?.();
+    },
+
+    /**
+     * Shut down: schedule no more work, and honor no more hints —
+     * EVERY lens included. The boundary owns no handles (its stores
+     * belong to whoever opened them) but it and its lenses each own a
+     * pending pass, and a pass that lands after those databases close
+     * would warn about a shutdown that went exactly right. One stop
+     * reaches all of them, because the boundary is what created them.
+     * Dirty state stays dirty on purpose: the next boundary over this
+     * ground reconciles it at birth, which is the same act.
+     */
+    stop() {
+      stopped = true;
+      repoFollowers.stop();
+      for (const lens of lenses.values()) lens.stop();
+    },
+
+    flushIfDirty,
+
+    /**
+     * Derived, never stored: what each link's written address currently
+     * reaches in entity space (link uuid → owning uuid, or null), across
+     * EVERY registered tree. Resolution is the OS's own — realpath,
+     * chains and all — then the real ground's tree answers for the
+     * address with the entity that OWNS it: the exact record at the address.
+     * A repository boundary changes its realtime semantics, not the child
+     * identity map. It dies honestly when
+     * the target moves out from under the text: amalgm remembers the
+     * pointer, never what it used to reach. null = broken or
+     * unregistered ground.
+     */
+    linkTargets() {
+      const out = new Map();
+      for (const root of observer.listRoots()) {
+        const home = treeRootCovering(root.path);
+        const lens = home ? lenses.get(home.rootId) : null;
+        if (!lens) continue;
+        for (const row of observer.linksForRoot(root.rootId)) {
+          const uuid = lens.boundUuid(row.linkId);
+          if (uuid === undefined) continue;
+          let real;
+          try {
+            real = fs.realpathSync(path.resolve(edgeBase(root, row.relPath), row.target));
+          } catch {
+            out.set(uuid, null); // broken: the derived resolution is dead, the record is not
+            continue;
+          }
+          out.set(uuid, resolveGround(real));
+        }
+      }
+      return out;
+    },
+
+    /** The latest edge pass's refusals — visible, never silent. */
+    reported: () => [...reported],
+    repoState: (uuid) => repoStates.get(uuid),
+    tree: treeAt,
+    trees: () => new Map(treeRoots()
+      .filter((root) => lenses.has(root.rootId))
+      .map((root) => [root.path, treeAt(root.path)])),
+  };
+}
+
+module.exports = { createRegistration };