amalgm 0.1.245 → 0.1.246

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

@@ -0,0 +1,200 @@
+'use strict';
+
+/**
+ * The referee for the INCREMENTAL detector: re-read enrolled ground
+ * from scratch and report every divergence from what the store
+ * believes. It shares no part of the path it judges — no stats
+ * shortcut, no doorbells, no dirty sets, no compare functions, no
+ * applier — so a belief the scan reached by shortcut is never
+ * confirmed by that same shortcut.
+ *
+ * It does share detection's PRIMITIVES: the same enrollment policy,
+ * the same walk, the same truth adapter. That is deliberate — one
+ * definition of each, none left to drift — and it bounds the verdict
+ * exactly: this referee grades the machinery, never the primitives it
+ * asks. Grading those belongs to the oracle
+ * (tests/entity-oracle/referee.js), which enumerates and hashes with
+ * its own code and none of this layer's, driven by the storms.
+ *
+ * Read-only: no events, no store writes. An empty result means no
+ * belief diverged from the ground the primitives reported. Ground
+ * that could not be read reports as an `unsettled:` entry —
+ * inconclusive there, never clean and never a divergence.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { censusBoundaries, gitDirTruth, walkRoot } = require('./scan');
+const { adapterFor } = require('../adapters');
+const { lookFailed } = require('../adapters/truth');
+
+// The same socket the observer reads: one three-state answer.
+const fileTruth = adapterFor('file.binary').rails.detect.truth;
+
+const UNSETTLED = 'unsettled: the ground could not be read — verification is inconclusive here';
+
+function createVerify({ store, shouldEnroll }) {
+  return function verify(rootId) {
+    const mismatches = [];
+    for (const root of store.listRoots()) {
+      if (rootId && root.rootId !== rootId) continue;
+      if (root.kind === 'repo') {
+        // Equality both ways: a registered territory whose .git left disk
+        // is as much a divergence as an unregistered one on disk — and a
+        // territory that could not be inspected is neither.
+        const territory = gitDirTruth(root.path);
+        if (territory === 'unsettled') {
+          mismatches.push({ rootId: root.rootId, path: '.', problem: UNSETTLED });
+          continue;
+        }
+        if (territory === 'absent') {
+          mismatches.push({ rootId: root.rootId, path: '.', problem: 'ghost territory: the observer believes in a repository disk no longer has' });
+          continue;
+        }
+        // The census referee: every `.git` boundary on disk must have a
+        // registered claimant. Grandchildren are checked when their own
+        // parent root comes through this loop. Ground the census could
+        // not list is inconclusive — it may hide a boundary.
+        const census = censusBoundaries(root.path, shouldEnroll);
+        for (const relDir of census.unsettled) {
+          mismatches.push({ rootId: root.rootId, path: relDir || '.', problem: UNSETTLED });
+        }
+        for (const relDir of census.boundaries) {
+          const claimant = store.rootByPath(path.join(root.path, relDir));
+          if (!claimant || claimant.kind !== 'repo') {
+            mismatches.push({ rootId: root.rootId, path: relDir, problem: 'unclaimed territory: disk has a repository the observer never registered' });
+          }
+        }
+        continue;
+      }
+      if (root.kind === 'file') {
+        // The referee for the smallest ground: one path, one truth —
+        // and disk decides the truth's kind, exactly like the scan.
+        const row = store.fileByPath(root.rootId, '');
+        const linkRow = store.linksForRoot(root.rootId)[0] ?? null;
+        let stat = null;
+        try {
+          stat = fs.lstatSync(root.path);
+        } catch (error) {
+          if (lookFailed(error).truth === 'unsettled') {
+            mismatches.push({ rootId: root.rootId, path: '.', problem: UNSETTLED });
+            continue;
+          }
+          stat = null;
+        }
+        if (stat && stat.isFile()) {
+          const read = fileTruth(root.path);
+          if (read.truth === 'unsettled') {
+            mismatches.push({ rootId: root.rootId, path: '.', problem: UNSETTLED });
+          } else if (read.truth === 'present' && read.state.kind === 'file') {
+            if (!row) {
+              mismatches.push({ rootId: root.rootId, path: '.', problem: 'unknown: disk has a file the observer never saw' });
+            } else if (row.contentHash !== read.state.sha256) {
+              mismatches.push({ rootId: root.rootId, path: '.', problem: 'stale: disk moved, the observer did not notice' });
+            }
+          }
+          if (linkRow) {
+            mismatches.push({ rootId: root.rootId, path: '.', problem: 'ghost: the observer believes in a link disk no longer has' });
+          }
+        } else if (stat && stat.isSymbolicLink()) {
+          let target = null;
+          try {
+            target = fs.readlinkSync(root.path);
+          } catch (error) {
+            if (lookFailed(error).truth === 'unsettled') {
+              mismatches.push({ rootId: root.rootId, path: '.', problem: UNSETTLED });
+              continue;
+            }
+            target = null; // vanished mid-verify
+          }
+          if (target !== null) {
+            if (!linkRow) {
+              mismatches.push({ rootId: root.rootId, path: '.', problem: 'unknown: disk has a link the observer never saw' });
+            } else if (linkRow.target !== target) {
+              mismatches.push({ rootId: root.rootId, path: '.', problem: 'stale: the link was retargeted, the observer did not notice' });
+            }
+          }
+          if (row) {
+            mismatches.push({ rootId: root.rootId, path: '.', problem: 'ghost: the observer believes in a file disk no longer has' });
+          }
+        } else {
+          if (row) {
+            mismatches.push({ rootId: root.rootId, path: '.', problem: 'ghost: the observer believes in a file disk no longer has' });
+          }
+          if (linkRow) {
+            mismatches.push({ rootId: root.rootId, path: '.', problem: 'ghost: the observer believes in a link disk no longer has' });
+          }
+        }
+        continue;
+      }
+      if (root.kind !== 'files') continue;
+      const rows = new Map(store.filesForRoot(root.rootId).map((row) => [row.relPath, row]));
+      const { files, dirs, links, repoDirs, unsettled } = walkRoot(root.path, shouldEnroll);
+      // Ground the walk could not read is inconclusive — one entry per
+      // unsettled path, and NO conclusion beneath one: not clean, not
+      // ghost.
+      const underUnsettled = (relPath) =>
+        unsettled.some((dir) => dir === '' || relPath === dir || relPath.startsWith(`${dir}/`));
+      for (const relPath of unsettled) {
+        mismatches.push({ rootId: root.rootId, path: relPath || '.', problem: UNSETTLED });
+      }
+      const linkRows = new Map(store.linksForRoot(root.rootId).map((row) => [row.relPath, row]));
+      for (const entry of links) {
+        const row = linkRows.get(entry.relPath);
+        if (!row) {
+          mismatches.push({ rootId: root.rootId, path: entry.relPath, problem: 'unknown: disk has a link the observer never saw' });
+        } else if (row.target !== entry.target) {
+          mismatches.push({ rootId: root.rootId, path: entry.relPath, problem: 'stale: the link was retargeted, the observer did not notice' });
+        }
+        linkRows.delete(entry.relPath);
+      }
+      for (const relPath of linkRows.keys()) {
+        if (underUnsettled(relPath)) continue;
+        mismatches.push({ rootId: root.rootId, path: relPath, problem: 'ghost: the observer believes in a link disk no longer has' });
+      }
+      const dirRows = new Set(store.dirsForRoot(root.rootId).map((row) => row.relPath));
+      for (const entry of dirs) {
+        if (!dirRows.delete(entry.relPath)) {
+          mismatches.push({ rootId: root.rootId, path: entry.relPath, problem: 'unknown: disk has a directory the observer never saw' });
+        }
+      }
+      for (const relPath of dirRows) {
+        if (underUnsettled(relPath)) continue;
+        mismatches.push({ rootId: root.rootId, path: relPath, problem: 'ghost: the observer believes in a directory disk no longer has' });
+      }
+      for (const relDir of repoDirs) {
+        const claimant = store.rootByPath(relDir ? path.join(root.path, relDir) : root.path);
+        if (!claimant || claimant.kind !== 'repo') {
+          mismatches.push({ rootId: root.rootId, path: relDir || '.', problem: 'unclaimed territory: disk has a repository the observer never registered' });
+        }
+      }
+      for (const entry of files) {
+        const read = fileTruth(path.join(root.path, entry.relPath));
+        if (read.truth === 'unsettled') {
+          mismatches.push({ rootId: root.rootId, path: entry.relPath, problem: UNSETTLED });
+          rows.delete(entry.relPath); // inconclusive, not ghost
+          continue;
+        }
+        if (read.truth !== 'present' || read.state.kind !== 'file') {
+          rows.delete(entry.relPath); // vanished mid-verify: a race, not a conclusion
+          continue;
+        }
+        const row = rows.get(entry.relPath);
+        if (!row) {
+          mismatches.push({ rootId: root.rootId, path: entry.relPath, problem: 'unknown: disk has a file the observer never saw' });
+        } else if (row.contentHash !== read.state.sha256) {
+          mismatches.push({ rootId: root.rootId, path: entry.relPath, problem: 'stale: disk moved, the observer did not notice' });
+        }
+        rows.delete(entry.relPath);
+      }
+      for (const row of rows.values()) {
+        if (underUnsettled(row.relPath)) continue;
+        mismatches.push({ rootId: root.rootId, path: row.relPath, problem: 'ghost: the observer believes in a file disk no longer has' });
+      }
+    }
+    return mismatches;
+  };
+}
+
+module.exports = { createVerify };

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

@@ -0,0 +1,62 @@
+'use strict';
+
+/**
+ * The doorbell half of detection: one recursive OS watcher per root.
+ * macOS = FSEvents, Windows = ReadDirectoryChangesW, Linux = inotify
+ * (recursive support requires Node >= 20, which the engine already requires).
+ *
+ * A watcher is allowed to be lossy and allowed to die — but death is an
+ * event like any other: `onDead` fires exactly once so the owner can
+ * rebuild the doorbell and reconcile the gap. A watcher that cannot even
+ * be born returns already `degraded` and never calls `onDead`. Nothing
+ * here throws past this module.
+ *
+ * A handle is { degraded, close }. The watcher never mutates the ground
+ * it observes: its only job is to carry filesystem doorbells to its owner.
+ */
+
+const fs = require('fs');
+function install(dirPath, recursive, onDirty, onDead) {
+  const handle = { degraded: false, close: () => {} };
+  let watcher = null;
+  try {
+    watcher = fs.watch(dirPath, { recursive, persistent: false }, (_event, filename) => {
+      onDirty(filename ? String(filename).split('\\').join('/') : null);
+    });
+  } catch {
+    handle.degraded = true;
+    return handle;
+  }
+  watcher.on('error', () => {
+    if (handle.degraded) return; // dead is dead: one death, one report
+    handle.degraded = true;
+    try { watcher.close(); } catch { /* already dead */ }
+    if (onDead) onDead();
+  });
+  handle.close = () => {
+    try { watcher.close(); } catch { /* already dead */ }
+  };
+  return handle;
+}
+
+function watchRecursive(rootPath, onDirty, onDead) {
+  return install(rootPath, true, onDirty, onDead);
+}
+
+/**
+ * The non-recursive doorbell: one directory, every event, the raw name
+ * delivered (or null, which could be anything). It hears EVERYTHING —
+ * filtering is the consumer's business, because a delivered name proves
+ * nothing about what it means: a rename of A to B may lawfully deliver
+ * only "B", and a doorbell that filters for "A" has decided the answer
+ * before looking. Two consumers ride it: a single-file root's main
+ * doorbell (the file's own inode goes deaf on atomic saves; the parent
+ * directory does not) and every top-level root's address doorbell (the
+ * parent observes address changes; the entity observes content
+ * changes). Same death contract as watchRecursive.
+ */
+function watchDir(dirPath, onDirty, onDead) {
+  return install(dirPath, false, onDirty, onDead);
+}
+
+module.exports = { watchDir, watchRecursive };

package/runtime/scripts/amalgm-mcp/project-context/store.js

@@ -16,9 +16,9 @@
  *   system-instructions.md    global user-authored instructions under AMALGM_DIR
  *
  * Direct disk edits (editors, agents with their own file tools) are picked up
- * by the per-project fs watcher, a bounded verifier for notifications the OS
- * may drop, and the fs REST hooks. All three funnel into the same reconcile
- * path. Reconcile is idempotent: unchanged revisions emit no events.
+ * by the per-project fs watcher and the fs REST hooks, which funnel into the
+ * same reconcile path. Reconcile is idempotent: unchanged revisions emit no
+ * events.
  *
  * Everything that emits events runs in the amalgm-mcp process — Local Live
  * only streams events appended in-process. chat-core (chat-server process)
@@ -56,13 +56,11 @@ const {
 
 const RESOURCE = 'project_context';
 const WATCH_DEBOUNCE_MS = 200;
-const WATCH_VERIFY_MS = 5_000;
 // The system scope carries user-authored instructions that apply to every
 // session on this computer. It has no change log or project state.
 const SYSTEM_CONTEXT_ID = 'system';
 
-const watchers = new Map(); // projectId -> { watcher, timer, project, projectPath }
-let watchVerificationTimer = null;
+const watchers = new Map(); // projectId -> { watcher, timer, projectPath }
 
 function systemProject() {
   return { id: SYSTEM_CONTEXT_ID, path: path.resolve(AMALGM_DIR), name: 'Amalgm System' };
@@ -685,50 +683,12 @@ function closeWatcher(projectId) {
   const entry = watchers.get(projectId);
   if (!entry) return;
   if (entry.timer) clearTimeout(entry.timer);
-  if (entry.watcher) {
-    try {
-      entry.watcher.close();
-    } catch {
-      // Already closed.
-    }
+  try {
+    entry.watcher.close();
+  } catch {
+    // Already closed.
   }
   watchers.delete(projectId);
-  if (watchers.size === 0 && watchVerificationTimer) {
-    clearInterval(watchVerificationTimer);
-    watchVerificationTimer = null;
-  }
-}
-
-/**
- * `fs.watch` is a latency hint, not durable evidence: kernels may coalesce or
- * drop notifications. This bounded pass owns that wait and makes every
- * watched context converge even when no callback arrives.
- */
-function verifyProjectContextWatchers() {
-  for (const entry of watchers.values()) {
-    try {
-      reconcileProjectContext(entry.project, { source: 'project-context:verify' });
-      if (!entry.watcher) {
-        entry.watcher = openProjectContextWatcher(entry.project);
-      }
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      console.warn(
-        `[ProjectContext] Bounded verify failed for ${entry.projectPath}: ${message}`,
-      );
-    }
-  }
-}
-
-function ensureWatchVerification() {
-  if (watchVerificationTimer || watchers.size === 0) return;
-  watchVerificationTimer = setInterval(
-    verifyProjectContextWatchers,
-    WATCH_VERIFY_MS,
-  );
-  if (typeof watchVerificationTimer.unref === 'function') {
-    watchVerificationTimer.unref();
-  }
 }
 
 /**
@@ -737,7 +697,13 @@ function ensureWatchVerification() {
  * harmless: by the time the debounce fires, disk matches the row and no event
  * is emitted.
  */
-function openProjectContextWatcher(project) {
+function watchProjectContext(input) {
+  const project = projectFromInput(input);
+  if (!project?.id || !project?.path) return;
+  const existing = watchers.get(project.id);
+  if (existing?.projectPath === project.path) return;
+  if (existing) closeWatcher(project.id);
+
   const root = contextPathsFor(project).root;
   let watcher;
   try {
@@ -757,46 +723,12 @@ function openProjectContextWatcher(project) {
       if (typeof entry.timer.unref === 'function') entry.timer.unref();
     });
   } catch {
-    // The bounded verifier remains the durable fallback and retries this hint.
-    return null;
-  }
-  watcher.on('error', () => {
-    const entry = watchers.get(project.id);
-    if (!entry || entry.watcher !== watcher) return;
-    try {
-      watcher.close();
-    } catch {
-      // Already closed.
-    }
-    entry.watcher = null;
-  });
-  if (typeof watcher.unref === 'function') watcher.unref();
-  return watcher;
-}
-
-function watchProjectContext(input) {
-  const project = projectFromInput(input);
-  if (!project?.id || !project?.path) return;
-  const existing = watchers.get(project.id);
-  if (existing?.projectPath === project.path) {
-    existing.project = project;
-    if (!existing.watcher) {
-      existing.watcher = openProjectContextWatcher(project);
-    }
-    ensureWatchVerification();
+    // Context dir missing or unwatchable — best effort; REST hooks still cover writes.
     return;
   }
-  if (existing) closeWatcher(project.id);
-
-  const entry = {
-    watcher: null,
-    timer: null,
-    project,
-    projectPath: project.path,
-  };
-  watchers.set(project.id, entry);
-  entry.watcher = openProjectContextWatcher(project);
-  ensureWatchVerification();
+  watcher.on('error', () => closeWatcher(project.id));
+  if (typeof watcher.unref === 'function') watcher.unref();
+  watchers.set(project.id, { watcher, timer: null, projectPath: project.path });
 }
 
 /** fs REST hook: reconcile when a context doc is touched outside the store. */

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

@@ -0,0 +1,33 @@
+'use strict';
+
+/**
+ * Amalgm's file-type policy: which physical type a piece of file ground
+ * takes. Classification is an INJECTED policy everywhere it is used
+ * (registration and its lenses refuse to construct without one), so it
+ * lives in its own file with no other job — one definition, replaceable
+ * whole.
+ *
+ * The rule is the oldest one there is: bytes holding a NUL are not text.
+ * What matters is WHERE that fact comes from. It is not read here.
+ * Detect's single read of a file produces its fingerprint and this
+ * report together (adapters/filesystem.js), and this policy only names
+ * the type that report implies.
+ *
+ * That is the whole law: A FILE'S HASH AND ITS TYPE DESCRIBE THE SAME
+ * OBSERVED BYTES. A policy that opened the ground itself would be a
+ * second look — and a second look can meet different bytes, or none at
+ * all, leaving a record whose type contradicts the payload beside it.
+ * So this function takes evidence, never a path; it is total, and it
+ * cannot fail.
+ *
+ * Both types travel as exact versions today; the distinction reserves
+ * `file.text` for the richer merge behavior it earns when Send exists
+ * (docs/realtime-rails.md §1).
+ */
+
+/** @param {{ binary: boolean }} evidence — Detect's report on the bytes it hashed. */
+function classifyFile({ binary }) {
+  return binary ? 'file.binary' : 'file.text';
+}
+
+module.exports = { classifyFile };