amalgm 0.1.245 → 0.1.246

package/runtime/scripts/amalgm-mcp/observer/edges.js

@@ -0,0 +1,111 @@
+'use strict';
+
+/**
+ * Enrollment follows symlink edges (ratified 2026-08-01): adding a
+ * workspace authorizes every reachable real target. The observer itself
+ * NEVER follows a pointer — walks record edges and stop — so this
+ * operation is where the ratified policy acts: it reads every enrolled
+ * root's edges (`observer.linkEdges` — files ground from detected truth,
+ * repo ground from a fresh worktree census, a single-ground pointer root
+ * from its own one edge), resolves each to real ground, and enrolls what
+ * is not yet covered. Every reachable real entity ends up registered
+ * exactly once: enrollment is idempotent by real path, so shared targets
+ * deduplicate and cycles terminate on their own.
+ *
+ * What gets enrolled is EXACTLY the target the link names — never more
+ * (amended 2026-08-01, replacing the vetoed snap-to-enclosing-repo
+ * default): a link authorizes the ground it points at, not an enclosing
+ * boundary the user never named. A directory target that is itself a
+ * repository root enrolls as the repo; a plain directory enrolls as
+ * files ground; a file enrolls as a single-ground root — never its
+ * parent, which would share siblings the edge never named. A target
+ * already inside enrolled ground reuses that owner and enrolls nothing.
+ *
+ * The rules, in the order they decide:
+ *  - a broken pointer enrolls nothing — there is no target to enroll
+ *    until it becomes available;
+ *  - ground already inside enrolled ground is already watched;
+ *  - ground amalgm's enrollment policy excludes is refused and reported:
+ *    EVERY route that expands coverage asks the same policy about the
+ *    COMPLETE candidate path — a benign name inside excluded ground is
+ *    still excluded — and following an edge is never a way around it
+ *    (an explicit override is a future deliberate operation, never a
+ *    default);
+ *  - ground that CONTAINS enrolled ground is refused and reported:
+ *    every path has exactly one owner, and overlapping roots would give
+ *    it two — swallowing an enrolled root is a bigger act than following
+ *    an edge;
+ *  - anything else enrolls — repo, files, or single ground as disk
+ *    decides — and its own edges are followed in turn (the loop runs to
+ *    a fixpoint).
+ *
+ * Following adds, only: a retargeted link enrolls its new target and the
+ * old one stays enrolled — removing coverage is an explicit act, never a
+ * side effect of detection.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/** The directory an edge's relative target resolves against: the link's
+ * own parent. A single-ground pointer root records its edge at relPath
+ * '', so its base is the root path's parent, not the root path itself. */
+function edgeBase(root, relPath) {
+  if (root.kind === 'file') return path.dirname(root.path);
+  return path.resolve(root.path, path.dirname(relPath));
+}
+
+function followEdges(observer) {
+  const enrolled = [];
+  const reported = [];
+  const seen = new Set(); // real grounds judged this call, whatever the verdict
+  let settled = true; // every edge surface answered completely
+  let grew = true;
+  while (grew) {
+    grew = false;
+    for (const root of observer.listRoots()) {
+      const surface = observer.linkEdges(root.rootId);
+      // Unreadable ground may hide an edge: what WAS readable still
+      // enrolls (adding is idempotent), but the pass never claims
+      // completeness — the boundary stays dirty and the retry decides.
+      if (surface.unsettled.length > 0) settled = false;
+      for (const link of surface.edges) {
+        const abs = path.resolve(edgeBase(root, link.relPath), link.target);
+        let real;
+        try {
+          real = fs.realpathSync(abs);
+        } catch {
+          continue; // broken: no target to enroll until it becomes available
+        }
+        if (seen.has(real)) continue;
+        seen.add(real);
+        const roots = observer.listRoots();
+        if (roots.some((other) => real === other.path || real.startsWith(`${other.path}/`))) {
+          continue; // already enrolled ground, already watched
+        }
+        // The policy judges the COMPLETE candidate path: it excludes by
+        // path segment (.ssh, node_modules, ...), so a benign final name
+        // inside excluded ground is still refused.
+        if (!observer.shouldEnroll(real)) {
+          reported.push({ path: real, via: link.relPath, reason: 'excluded by amalgm\'s enrollment policy — an edge is never a way around it; an explicit override is a future deliberate operation' });
+          continue;
+        }
+        if (roots.some((other) => other.path.startsWith(`${real}/`))) {
+          reported.push({ path: real, via: link.relPath, reason: 'target ground contains enrolled ground — one owner per path, so enrolling it would overlap' });
+          continue;
+        }
+        // An enrollment failure is never silence: it propagates, the
+        // boundary above stays dirty, and the retry decides — a target
+        // that vanished between judgment and enrollment is simply broken
+        // ground on the next pass, while a real identity failure stays
+        // loud instead of masquerading as a clean registration.
+        observer.enrollRoot(real);
+        enrolled.push(real);
+        grew = true; // the new ground's own edges get their turn
+      }
+    }
+  }
+  return { enrolled, reported, settled };
+}
+
+module.exports = { followEdges };