amalgm 0.1.245 → 0.1.246

package/runtime/scripts/amalgm-mcp/lib/layout.js

@@ -32,15 +32,40 @@ const path = require('path');
 const ROOT_MANIFEST_NAME = '.amalgm-root.json';
 const USER_MANIFEST_NAME = '.amalgm-user.json';
 const LAYOUT_VERSION = 1;
+const USER_HOME_MANIFEST_NAME = 'home.json';
+const USER_HOME_SCHEMA_VERSION = 1;
 
-// Per-user roots for platform primitives. Everything Amalgm owns for a user
-// lives under one of these; anything else on disk is the user's own project.
+// Stable per-user product namespaces. Their authority is NOT inferred from
+// their path: user content and exact platform-managed targets are declared
+// separately below (docs/user-cloud-bootstrap.md).
 const PRIMITIVE_DIRS = Object.freeze([
   'agents',
   'apps',
   'automations',
   'toolbox',
   'workspaces',
+  'system',
+]);
+
+const USER_HOME_ROOTS = Object.freeze([
+  { key: 'agents', relativePath: 'agents' },
+  { key: 'apps', relativePath: 'apps' },
+  { key: 'automations', relativePath: 'automations' },
+  { key: 'toolbox', relativePath: 'toolbox' },
+  { key: 'workspaces', relativePath: 'workspaces' },
+  { key: 'system', relativePath: 'system' },
+]);
+
+// Platform management is an exact-node fact. It deliberately does not
+// cascade from `system/`: human permissions may still inherit normally, while
+// only these particular entities are product-managed.
+const USER_HOME_EXACT_MANAGED = Object.freeze([
+  ...USER_HOME_ROOTS.map(({ key, relativePath }) => ({
+    key: `${key}-root`, relativePath, rootKey: key,
+  })),
+  { key: 'home-manifest', relativePath: 'system/home.json', rootKey: 'system' },
+  { key: 'defaults', relativePath: 'system/defaults', rootKey: 'system' },
+  { key: 'policy', relativePath: 'system/policy', rootKey: 'system' },
 ]);
 
 function readJson(file, fallback = null) {
@@ -56,6 +81,51 @@ function writeJson(file, data) {
   fs.writeFileSync(file, `${JSON.stringify(data, null, 2)}\n`, { mode: 0o600 });
 }
 
+function declaredUserHome(userDir) {
+  const root = path.resolve(userDir);
+  return {
+    schemaVersion: USER_HOME_SCHEMA_VERSION,
+    userDir: root,
+    roots: USER_HOME_ROOTS.map((entry) => ({
+      ...entry,
+      path: path.join(root, entry.relativePath),
+    })),
+    exactManaged: USER_HOME_EXACT_MANAGED.map((entry) => ({
+      ...entry,
+      path: path.join(root, entry.relativePath),
+      scope: 'exact',
+    })),
+  };
+}
+
+/**
+ * Materialize the fixed, safe bootstrap surface. This does not register or
+ * synchronize anything; runtime bootstrap calls the shared `amalgm register`
+ * boundary for that. Keeping those acts separate prevents login from growing
+ * a second identity registrar or silently enrolling machine-local state.
+ */
+function ensureUserHome(userDir) {
+  const declaration = declaredUserHome(userDir);
+  for (const root of declaration.roots) {
+    fs.mkdirSync(root.path, { recursive: true, mode: 0o700 });
+  }
+  for (const managed of declaration.exactManaged) {
+    if (path.extname(managed.path)) continue;
+    fs.mkdirSync(managed.path, { recursive: true, mode: 0o700 });
+  }
+
+  const manifest = declaration.exactManaged.find((entry) => entry.key === 'home-manifest');
+  if (manifest && !fs.existsSync(manifest.path)) {
+    writeJson(manifest.path, {
+      schemaVersion: USER_HOME_SCHEMA_VERSION,
+      kind: 'amalgm-user-home',
+      roots: declaration.roots.map(({ key, relativePath }) => ({ key, path: relativePath })),
+      exactManaged: declaration.exactManaged.map(({ key, relativePath, scope }) => ({ key, path: relativePath, scope })),
+    });
+  }
+  return declaration;
+}
+
 function lstatOrNull(target) {
   try {
     return fs.lstatSync(target);
@@ -249,17 +319,25 @@ function ensureUserDir(homeDir, { userId, email }) {
   const existing = findUserDirByUserId(homeDir, cleanId);
   if (existing) {
     if (cleanEmail && readUserManifest(existing)?.canonicalEmail !== cleanEmail) {
-      return adoptUserEmail(homeDir, { userId: cleanId, email: cleanEmail }).dir;
+      const adopted = adoptUserEmail(homeDir, { userId: cleanId, email: cleanEmail }).dir;
+      ensureUserHome(adopted);
+      return adopted;
     }
     indexUserFolder(homeDir, path.basename(existing), { userId: cleanId, email: cleanEmail });
+    ensureUserHome(existing);
     return existing;
   }
 
   const legacyDir = path.join(homeDir, 'users', sanitizeFolderSegment(cleanId));
   if (lstatOrNull(legacyDir)?.isDirectory()) {
     writeUserManifest(legacyDir, { userId: cleanId, email: cleanEmail });
-    if (cleanEmail) return adoptUserEmail(homeDir, { userId: cleanId, email: cleanEmail }).dir;
+    if (cleanEmail) {
+      const adopted = adoptUserEmail(homeDir, { userId: cleanId, email: cleanEmail }).dir;
+      ensureUserHome(adopted);
+      return adopted;
+    }
     indexUserFolder(homeDir, path.basename(legacyDir), { userId: cleanId, email: '' });
+    ensureUserHome(legacyDir);
     return legacyDir;
   }
 
@@ -268,6 +346,7 @@ function ensureUserDir(homeDir, { userId, email }) {
   fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
   writeUserManifest(dir, { userId: cleanId, email: cleanEmail });
   indexUserFolder(homeDir, folderName, { userId: cleanId, email: cleanEmail });
+  ensureUserHome(dir);
   return dir;
 }
 
@@ -323,8 +402,14 @@ module.exports = {
   PRIMITIVE_DIRS,
   ROOT_MANIFEST_NAME,
   USER_MANIFEST_NAME,
+  USER_HOME_EXACT_MANAGED,
+  USER_HOME_MANIFEST_NAME,
+  USER_HOME_ROOTS,
+  USER_HOME_SCHEMA_VERSION,
   adoptUserEmail,
+  declaredUserHome,
   emailFolderName,
+  ensureUserHome,
   ensureRootManifest,
   ensureUserDir,
   createCompatLink,

package/runtime/scripts/amalgm-mcp/observer/README.md

@@ -0,0 +1,259 @@
+# Observer — the change-detection layer
+
+## Purpose
+
+Notice that bytes on disk changed, and say so exactly once. The observer is
+the single place in the runtime where a local change is born. It never syncs,
+never merges, never decides truth — it emits facts for the layers above.
+
+## Axioms
+
+1. **Registration is coverage, and every path has exactly one owner —
+   permanently.** One observer root per enrolled workspace, repo, or
+   single ground (the smallest root there is: one channel, relPath `''`,
+   a parent-directory doorbell; a file under the file laws, or an
+   explicitly enrolled pointer under the link laws). No caps, no
+   side-effect watchers, no "watched because open". A root's identity is
+   its rootId and its path is only the current address: each root
+   carries its own physical identity (a dir root its inode, a
+   single-ground root its channel row's), and enrollment rescues moved
+   ground by continuity — unique inode match against a path-orphan
+   rebinds the address (`root.moved`, the whole family in ONE store
+   transaction), every channel intact; a lookalike at the old address
+   is new ground. A scan's evidence horizon is the root's ground, and
+   the root's own address is the horizon's edge: ground missing there —
+   or a directory root's address wearing a different identity — is
+   undecidable (moved? deleted? replaced?), so the scan CONCLUDES
+   NOTHING about identity. IDENTITY PERSISTS; LOCAL PRESENCE IS
+   SEPARATE EVIDENCE: the undecided address flips one durable `present`
+   bit and says so — `root.unavailable` on the way down,
+   `root.available` on the way back, one symmetric pair at one choke
+   point, never a lifecycle verdict and never a grammar of unrelated
+   events. Beliefs freeze, the referee convicts the divergence, and
+   the next enrollment moment decides: naming the new address rescues,
+   re-naming this one adopts the ground, and explicit removal is the
+   only deletion. THE PARENT OBSERVES ADDRESS CHANGES; THE ENTITY
+   OBSERVES CONTENT CHANGES: every top-level root also carries a
+   non-recursive doorbell on its parent directory, and that doorbell
+   HEARS EVERY EVENT THERE — a rename may lawfully deliver only the NEW
+   name, so a name filter would decide the answer before looking; the
+   cheap address check is what decides (an intact, present address
+   returns in one lstat). An undecided address gets ONE DECISION, AT
+   EVERY ENTRANCE: the parent doorbell and the root's own scans (the
+   settle scan racing a slow delivery, the catch-up scan at start) can
+   learn of one rename in either order, and the verdict may never
+   depend on which arrived first — whichever entrance finds the
+   address undecided makes the same directed look before concluding
+   anything, so a followed move has no unavailable moment regardless
+   of arrival order, and a same-parent rename made while nothing ran
+   is followed at start. The rename is followed for EVERY kind when
+   WITNESSED CONTINUITY EVIDENCE claims it — the root's
+   kind-appropriate identity as of the last completed scan: a dir root
+   its own inode, a single ground its channel row's (which absorbs
+   atomic-save churn each time a scan witnesses it) — under the
+   exactly-one rule: one candidate of the root's own shape in the
+   parent, or no conclusion. The path still claims first (file ground
+   is only undecided when nothing file-shaped holds the address),
+   ambiguity — two entries wearing one inode, a hardlink beside a
+   rename — refuses to guess, and so does MISSING evidence: an atomic
+   save renamed away inside its own settle window leaves ground no scan
+   ever witnessed (new inode, new bytes, nothing to tie it to the
+   channel), so the follow refuses and even a later re-add of the new
+   address is honestly a NEW identity — the follow rides evidence,
+   never clairvoyance. A departure beyond the parent is honest absence,
+   LIVE: `root.unavailable` on the same delivery, reattachment the
+   explicit act that names the new address. The remaining honest edge: a
+   move BEYOND THE PARENT made while nothing was running, or to ground
+   nothing watches,
+   stays unavailable until an enrollment moment names it (a move INTO
+   registered ground is adopted by that tree's evidence, one level up). A `.git` claims its
+   subtree, and
+   territory is decided by disk, not by callers: a directory with a `.git`
+   enrolls as repo territory; a `.git` appearing inside a live files root
+   closes the file channels under it and births a repo root
+   (`repo.discovered`); a `.git` vanishing returns the ground to files
+   (`repo.removed`) and the channels are reborn. A repo's changes travel as
+   one card, never as thousands of file events. Enrollment names ground
+   by ADDRESS: the parent chain resolves, the last segment is inspected,
+   never traversed — an explicitly enrolled symlink enrolls as the
+   pointer itself.
+2. **The doorbell is a hint, never a fact — but a hint only ever raises
+   scrutiny.** OS watchers are lossy by contract. Truth is always:
+   settle → walk → compare → hash. Stats may excuse a file from hashing
+   only when all three hold: nothing named it, its stats are identical,
+   and its mtime is strictly older than the moment we last read its bytes
+   (git's racily-clean rule). A file the doorbell named is always hashed —
+   timestamps can be backdated, a delivered event cannot.
+3. **Every scan is the same code, and every scan has an event.** There is no
+   clock. `scanNow` runs at exactly four moments: enrollment (birth), start
+   (catch-up for the window we were dead), watcher death (rebuild the
+   doorbell, reconcile the gap once), and whenever a consumer asks — a sync
+   session opening, a document opening, an app regaining focus are events
+   too, and they belong to the layer above.
+4. **Echo suppression is content, not bookkeeping.** A writer records its own
+   write (`noteWrite`); a scan that finds the recorded hash finds nothing.
+5. **Identity has two axes, never mixed — and KIND decides which axis
+   testifies first.** `fileId → path/inode` answers "which file";
+   `fileId → contentHash` answers "did it change". For files the path
+   claims the channel — an atomic save replaces the inode in place, so
+   the address must absorb that churn — and the inode only rescues
+   path-orphans (renames), exactly-one match both sides. Directories are
+   channels under the same two rules in the OPPOSITE order, minus
+   content: nothing replaces a directory's inode in place, so the inode
+   claims first (two directories exchanging names cross by inode,
+   exactly like the files inside them) and the path claims only
+   recreation — a never-seen inode under an old name is the same
+   channel, silently retagged. Nothing to hash: a directory's meaning
+   (membership) is derived by the layers above, so empty folders exist
+   and folder renames — including exchanges — survive by inode. A
+   symlink is a channel in the FILES' order for the file reason (a
+   retarget is unlink + recreate, so the address absorbs the inode
+   churn; `mv` preserves the inode, so the inode rescues renames) whose
+   whole payload is the written target string, read every scan and NEVER
+   followed — the real target is watched at its real enrolled address,
+   and the edge-following enrollment operation (`edges.js`), not any
+   walk, is what turns unclaimed targets into ground. Every root kind
+   exposes its edges (`linkEdges`): files ground from detected truth,
+   repo ground from a fresh worktree census — a repo's changes travel
+   as one card, but its edges are enrollment-policy inputs like any
+   other root's.
+
+## Shape
+
+- `watch.js` — recursive OS doorbell (macOS FSEvents, Windows RDCW, Linux
+  inotify via Node ≥20), plus `watchDir`: the non-recursive doorbell
+  that hears EVERY event in one directory and delivers the raw name —
+  filtering is the consumer's business, because a rename may deliver
+  only the new name. Two consumers ride it: the single-file root's main
+  doorbell (the file's own inode goes deaf on atomic saves; the parent
+  directory does not — events naming the file ring content, foreign
+  names ring the cheap address check) and every top-level root's
+  ADDRESS doorbell (the parent observes address changes; the entity
+  observes content changes). Allowed to die; death is an event — the
+  owner rebuilds the doorbell and reconciles once.
+- `scan.js` — walk a root, and the pure compare functions: `diffRootState`
+  for files, `diffDirState` for directories (same rules, no content),
+  `diffLinkState` for symlinks (the file rules, target string as payload);
+  `censusLinks` reads a repo worktree's symlink edges fresh (stored
+  nowhere — git owns a repo's memory); `gitDirTruth` is the three-state
+  territory look every consumer asks.
+- `apply.js` — where a compare result becomes truth: events published
+  and store rows landed, deterministic order, one applier per channel
+  kind. The content read is injected, because unsettled suspicion
+  surviving onto the root's retry is the wiring's law.
+- `continuity.js` — a root's WITNESSED physical identity, the
+  moved-root claim, the undecided-address verdict, and the presence
+  bit's only two writers. Questions only: the actions a verdict
+  triggers (rebind, follow) re-aim watchers, so they live in the wiring.
+- `verify.js` — the referee, deliberately built from none of the
+  machinery above (see Verification below).
+- `store.js` — the layer's whole memory: `observer_roots` (with each
+  root's own `device, inode` — identity is permanent, the address is
+  not, and a family of roots changes address as ONE transaction — and
+  its durable `present` bit: presence survives a restart),
+  `observer_files`
+  (`file_id, rel_path, device, inode, size, mtime, content_hash`),
+  `observer_dirs` (`dir_id, rel_path, device, inode`), and
+  `observer_links` (`link_id, rel_path, device, inode, target`), on an
+  injected database handle, stamped with its schema generation (5).
+- `index.js` — the wiring, and only the wiring: enroll, settle, scan,
+  emit. It owns what the pieces above may not — when a look happens
+  (the settle timer and its backoff), what a doorbell means, territory
+  births and burials, and the rescue actions that re-aim watchers.
+- `edges.js` — the ratified enrollment policy acting on every root's
+  edges (`linkEdges` — repo roots via census, single-ground pointer
+  roots via their own one edge): adding a workspace authorizes every
+  reachable real target, so this operation resolves each pointer to
+  real ground and enrolls EXACTLY the target the link names — a repo
+  only when the named target IS the repo root; a file as a
+  single-ground root, never its parent — to a fixpoint, idempotent by
+  real path (shared targets deduplicate, cycles terminate), add-only
+  (a retarget enrolls the new ground and never removes the old). Two
+  refusals, both reported: ground the enrollment policy excludes
+  (`observer.shouldEnroll` — the SAME policy every route asks, about
+  the COMPLETE candidate path, so a benign name inside excluded ground
+  like `.ssh/config` is still refused; an edge is never a way around
+  it) and a target containing enrolled ground. Enrollment FAILURES are
+  never silence: they propagate, the boundary above stays dirty, and
+  the retry decides (a vanished target is broken ground next pass).
+  The registration boundary above (`registration/`) is what makes
+  watched ground REGISTERED ground — a tree per top-level root, keyed
+  by permanent rootId — and owns derived link resolution across trees
+  (answering with the OWNING entity: repo territory resolves to its
+  boundary's record).
+
+The observer imports nothing from the rest of the runtime. Enrollment policy
+(`shouldEnroll`) is injected; the default is the workspace inclusion rules.
+
+## Events
+
+- `file.created { rootId, fileId, path, hash, size }`
+- `file.changed { rootId, fileId, path, hash, previousHash, size }`
+- `file.renamed { rootId, fileId, from, to }`
+- `file.deleted { rootId, fileId, path }`
+- `dir.created { rootId, dirId, path }` / `dir.renamed { rootId, dirId,
+  from, to }` / `dir.deleted { rootId, dirId, path }` — no `dir.changed`:
+  a directory has no bytes of its own, and a recreation under the same
+  name is the same channel wearing a new inode (silent).
+- `link.created { rootId, linkId, path, target }` / `link.changed {
+  rootId, linkId, path, target, previousTarget }` (a retarget — the
+  written address is the payload) / `link.renamed { rootId, linkId,
+  from, to }` / `link.deleted { rootId, linkId, path }` — recreation
+  with the same address is silence, the same pointer wearing a new
+  inode.
+- `repo.discovered { rootId, path }` / `repo.removed { rootId, path }` —
+  territory handoff; the consumer attaches or drops a follower.
+- `root.moved { rootId, from, to }` — continuity rescued a moved root:
+  same identity, new address, channels untouched; the follow-up scan
+  proves silence. Consumers re-aim address-derived state, nothing else.
+- `root.unavailable { rootId, path }` / `root.available { rootId,
+  path }` — the symmetric presence pair: identity persists, local
+  presence is separate evidence. Unavailable is never deleted (no
+  lifecycle is concluded), available is never new (the same channels
+  wake), and a followed move emits neither — continuity never broke.
+- `repo.changed { rootId, areas: ['git'|'worktree'] }` — a raw doorbell,
+  forwarded instantly with no settling: quieting and identity belong to the
+  follower (repocard/follow.js), and a delayed doorbell would blind its
+  torn-read guard. On any catch-up scan a repo root rings unconditionally —
+  the observer cannot know what happened while nobody watched; the
+  follower's ids turn "maybe" into silence.
+
+The store is the identity half of detection's memory: `file_id`/`dir_id`
+are the durable channel identities that survive renames, and the root's own
+id is the store's WITNESS — the registry side binds it, validates it before
+every canonical proposal, and convicts an unknown witness loudly, so a
+lost store is never mistaken for a fresh start. Loss is judged by
+completeness too: an established store either has its whole schema or it
+convicts at open — a silently recreated table would end every channel it
+held behind a witness that still checks out. Bytes are the disposable
+half: re-detection is idempotent because equal hashes are silence.
+Committed store state is always some truth disk actually had: the file loop
+satisfies this per row (file renames never cross — the address claims first,
+so a rename only ever targets a row-free slot), and a directory batch, whose
+movers may cross, lands as ONE transaction with doorbells rung only after
+truth has landed — a crash mid-batch changes nothing, and the next scan
+re-detects the same batch.
+
+## The referee
+
+`verify()` re-reads enrolled ground and reports any divergence between disk
+truth and the observer's beliefs — including unclaimed territory: a `.git`
+on disk with no registered repo root. It is the referee of the INCREMENTAL
+detector, and only that: it shares no part of the path it judges — no stats
+shortcut, no doorbells, no dirty sets, no compare functions, no applier —
+so no belief the scan reached by shortcut is ever 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: `verify()` grades
+the machinery, never the primitives it asks. Grading those is the oracle
+referee's job (`tests/entity-oracle/referee.js`), which enumerates and
+hashes with its own code and none of this layer's.
+
+So the two referees answer different questions and run in different places:
+the storms and the oracle exams end with both, while an audit or shadow
+mode in production has only `verify()` — the oracle is test ground and
+production imports none of it. An empty `verify()` means no change went
+undetected in the ground the primitives reported; that the primitives are
+themselves right is the oracle's proof, not this one's.

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

@@ -0,0 +1,150 @@
+'use strict';
+
+/**
+ * Where a compare result becomes truth: events published, store rows
+ * landed, deterministic order — one applier per channel kind. The
+ * scan compares (scan.js), this file concludes; the wiring (index.js)
+ * decides when. `scanContent` is injected because a file's content read
+ * is the wiring's law (unsettled suspicion survives onto the root's
+ * retry) — the applier only honors its answer. That answer is the WHOLE
+ * content truth, fingerprint and kind together, because one read
+ * produced both; the applier never splits them.
+ */
+
+const crypto = require('crypto');
+
+const byPath = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+
+function createApply({ store, publish, scanContent }) {
+  /**
+   * Directory channels: same shape as files, minus content — a rename is
+   * the whole event, a retag (recreated under its old name) is silence,
+   * and there is nothing to hash. Movers may exchange addresses and land
+   * on freshly-deleted ones (directories cross by inode), so the compare
+   * result is one truth transition in the store too: one transaction, and
+   * the doorbells ring only after truth has landed — a crash mid-batch
+   * changes nothing, and the next scan re-detects the same batch.
+   * Deterministic order.
+   */
+  function applyDirDiff(root, diff) {
+    const deletes = diff.deletes.sort((a, b) => byPath(a.relPath, b.relPath));
+    const renames = diff.renames.sort((a, b) => byPath(a.entry.relPath, b.entry.relPath));
+    const creates = diff.creates.sort((a, b) => byPath(a.relPath, b.relPath))
+      .map((entry) => ({ dirId: crypto.randomUUID(), ...entry }));
+    store.applyDirDiff({
+      deletes: deletes.map((row) => row.dirId),
+      moves: renames.map(({ row, entry }) => ({ dirId: row.dirId, rootId: root.rootId, ...entry })),
+      retags: diff.retags.map(({ row, entry }) => ({ dirId: row.dirId, ...entry })),
+      creates: creates.map((entry) => ({ rootId: root.rootId, ...entry })),
+    });
+    for (const row of deletes) {
+      publish({ type: 'dir.deleted', rootId: root.rootId, dirId: row.dirId, path: row.relPath });
+    }
+    for (const { row, entry } of renames) {
+      publish({ type: 'dir.renamed', rootId: root.rootId, dirId: row.dirId, from: row.relPath, to: entry.relPath });
+    }
+    for (const entry of creates) {
+      publish({ type: 'dir.created', rootId: root.rootId, dirId: entry.dirId, path: entry.relPath });
+    }
+  }
+
+  /**
+   * Link channels: the file shape with the target string as the whole
+   * payload — a rename is the move, a retarget is the change (with the
+   * previous pointer), and a recreation under an old name with an old
+   * target is silence. Renames never cross (the address claims first), so
+   * rows commit per-row like files. Deterministic order.
+   */
+  function applyLinkDiff(root, diff) {
+    for (const { row, entry } of diff.renames.sort((a, b) => byPath(a.entry.relPath, b.entry.relPath))) {
+      publish({ type: 'link.renamed', rootId: root.rootId, linkId: row.linkId, from: row.relPath, to: entry.relPath });
+      if (row.target !== entry.target) {
+        publish({
+          type: 'link.changed', rootId: root.rootId, linkId: row.linkId,
+          path: entry.relPath, target: entry.target, previousTarget: row.target,
+        });
+      }
+      store.updateLink(row.linkId, entry);
+    }
+    for (const { row, entry } of diff.changes.sort((a, b) => byPath(a.entry.relPath, b.entry.relPath))) {
+      publish({
+        type: 'link.changed', rootId: root.rootId, linkId: row.linkId,
+        path: entry.relPath, target: entry.target, previousTarget: row.target,
+      });
+      store.updateLink(row.linkId, entry);
+    }
+    for (const { row, entry } of diff.retags) {
+      store.updateLink(row.linkId, entry); // the same pointer wearing a new inode
+    }
+    for (const entry of diff.creates.sort((a, b) => byPath(a.relPath, b.relPath))) {
+      const linkId = crypto.randomUUID();
+      store.insertLink({ linkId, rootId: root.rootId, ...entry });
+      publish({ type: 'link.created', rootId: root.rootId, linkId, path: entry.relPath, target: entry.target });
+    }
+    for (const row of diff.deletes.sort((a, b) => byPath(a.relPath, b.relPath))) {
+      store.removeLink(row.linkId);
+      publish({ type: 'link.deleted', rootId: root.rootId, linkId: row.linkId, path: row.relPath });
+    }
+  }
+
+  /** Turn one compare result into events + store updates. Deterministic order. */
+  function applyDiff(root, diff) {
+
+    for (const { row, entry } of diff.renames.sort((a, b) => byPath(a.entry.relPath, b.entry.relPath))) {
+      publish({ type: 'file.renamed', rootId: root.rootId, fileId: row.fileId, from: row.relPath, to: entry.relPath });
+      // The move is a fact on its own: record it before content is examined,
+      // so a file that vanishes mid-hash still deletes under its new name.
+      store.updateFile(row.fileId, {
+        ...entry, relPath: entry.relPath,
+        contentHash: row.contentHash, binary: row.binary, hashedAtMs: row.hashedAtMs,
+      });
+      const hashedAtMs = Date.now(); // Stamped BEFORE reading: a write during our read must force a future re-hash.
+      const content = scanContent(root, entry.relPath);
+      if (content === null || content.contentHash === row.contentHash) {
+        if (content !== null) store.updateFile(row.fileId, { ...entry, relPath: entry.relPath, ...content, hashedAtMs });
+        continue;
+      }
+      publish({
+        type: 'file.changed', rootId: root.rootId, fileId: row.fileId,
+        path: entry.relPath, hash: content.contentHash, previousHash: row.contentHash, size: entry.size,
+      });
+      store.updateFile(row.fileId, { ...entry, relPath: entry.relPath, ...content, hashedAtMs });
+    }
+
+    for (const { row, entry } of diff.checks.sort((a, b) => byPath(a.entry.relPath, b.entry.relPath))) {
+      const hashedAtMs = Date.now();
+      const content = scanContent(root, entry.relPath);
+      if (content === null) continue;
+      if (content.contentHash !== row.contentHash) {
+        publish({
+          type: 'file.changed', rootId: root.rootId, fileId: row.fileId,
+          path: entry.relPath, hash: content.contentHash, previousHash: row.contentHash, size: entry.size,
+        });
+      }
+      // Same hash = a touch or our own write echoing back: silence, but the
+      // stat fields advance so the next scan skips it.
+      store.updateFile(row.fileId, { ...entry, relPath: entry.relPath, ...content, hashedAtMs });
+    }
+
+    for (const entry of diff.creates.sort((a, b) => byPath(a.relPath, b.relPath))) {
+      const hashedAtMs = Date.now();
+      const content = scanContent(root, entry.relPath);
+      if (content === null) continue;
+      const fileId = crypto.randomUUID();
+      store.insertFile({ fileId, rootId: root.rootId, ...entry, ...content, hashedAtMs });
+      publish({
+        type: 'file.created', rootId: root.rootId, fileId,
+        path: entry.relPath, hash: content.contentHash, size: entry.size,
+      });
+    }
+
+    for (const row of diff.deletes.sort((a, b) => byPath(a.relPath, b.relPath))) {
+      store.removeFile(row.fileId);
+      publish({ type: 'file.deleted', rootId: root.rootId, fileId: row.fileId, path: row.relPath });
+    }
+  }
+
+  return { applyDiff, applyDirDiff, applyLinkDiff };
+}
+
+module.exports = { createApply };

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

@@ -0,0 +1,111 @@
+'use strict';
+
+/**
+ * Root continuity primitives: what a root's WITNESSED physical identity
+ * is, whether its recorded address still holds its ground, and the one
+ * presence bit. Pure questions plus the two presence transitions — the
+ * ACTIONS a verdict triggers (rebind, the undecided-address decision)
+ * stay in the wiring, because they re-aim watchers and scans.
+ */
+
+const fs = require('fs');
+
+function createContinuity({ store, publish }) {
+  /**
+   * A root's WITNESSED physical identity, for continuity rescue.
+   * Directory roots carry their own device:inode (nothing replaces a
+   * directory's inode in place). A single-ground root's identity lives
+   * in its one channel row — current as of the last completed scan: the
+   * file laws absorb atomic-save and retarget churn each time a scan
+   * witnesses it, and continuity can only ever claim what a scan has
+   * witnessed. Ground that changed inodes inside a still-open settle
+   * window is unwitnessed — no evidence, no claim.
+   */
+  function rootIdentity(root) {
+    if (root.kind !== 'file') {
+      return root.device == null ? null : { device: root.device, inode: root.inode };
+    }
+    const row = store.fileByPath(root.rootId, '') ?? store.linksForRoot(root.rootId)[0];
+    return row ? { device: row.device, inode: row.inode } : null;
+  }
+
+  /** Orphaned means the recorded address no longer holds this ground. */
+  function orphanedAtAddress(root) {
+    const identity = rootIdentity(root);
+    if (!identity) return false;
+    try {
+      const stat = fs.lstatSync(root.path);
+      return stat.dev !== identity.device || stat.ino !== identity.inode;
+    } catch {
+      return true;
+    }
+  }
+
+  /**
+   * Continuity claims a root exactly like it claims the directories
+   * inside one: unique device:inode match, exactly one candidate, and
+   * only for a path-orphan — a root whose recorded address still holds
+   * its ground is never stolen by a lookalike.
+   */
+  function findMovedRoot(stat) {
+    const wantDir = stat.isDirectory();
+    const matches = store.listRoots().filter((root) => {
+      if (wantDir !== (root.kind !== 'file')) return false;
+      const identity = rootIdentity(root);
+      return Boolean(identity) && identity.device === stat.dev && identity.inode === stat.ino;
+    });
+    if (matches.length !== 1) return null;
+    return orphanedAtAddress(matches[0]) ? matches[0] : null;
+  }
+
+  /**
+   * A scan's evidence horizon is the root's ground; the root's own
+   * address is the horizon's edge. Ground missing there — or a directory
+   * root's address wearing a different physical identity — is
+   * UNDECIDABLE from here: moved away, deleted, or replaced by a
+   * lookalike all present the same address, and concluding "deleted"
+   * would end every channel a rescue could have saved. So the scan
+   * concludes nothing: beliefs freeze, the referee convicts the
+   * divergence, and the next enrollment moment decides — naming the new
+   * address rescues, re-naming this one adopts, and explicit removal is
+   * the only deletion (an external filesystem change is never permission
+   * to end identity). A single-ground root's address lawfully churns
+   * inodes (atomic saves, retargets), so only absence — or foreign
+   * directory ground — freezes it; presence is the file laws' business.
+   */
+  function addressUndecided(root) {
+    let stat;
+    try {
+      stat = fs.lstatSync(root.path);
+    } catch {
+      return true;
+    }
+    if (root.kind === 'file') return !stat.isFile() && !stat.isSymbolicLink();
+    if (!stat.isDirectory()) return true;
+    return root.device != null && (stat.dev !== root.device || stat.ino !== root.inode);
+  }
+
+  /**
+   * Identity persists; local presence is separate evidence. These two
+   * transitions are the ONLY writers of `present`, and every scan entry
+   * funnels through them — so consumers track one bit through one
+   * symmetric event pair, never a grammar of unrelated events. Neither
+   * ever concludes lifecycle: unavailable is not deleted, and available
+   * is not new.
+   */
+  function markAbsent(root) {
+    if (!root.present) return;
+    store.setRootPresent(root.rootId, false);
+    publish({ type: 'root.unavailable', rootId: root.rootId, path: root.path });
+  }
+
+  function markPresent(root) {
+    if (root.present) return;
+    store.setRootPresent(root.rootId, true);
+    publish({ type: 'root.available', rootId: root.rootId, path: root.path });
+  }
+
+  return { addressUndecided, findMovedRoot, markAbsent, markPresent, rootIdentity };
+}
+
+module.exports = { createContinuity };