amalgm 0.1.245 → 0.1.246

package/runtime/scripts/amalgm-mcp/repocard/capture.js

@@ -0,0 +1,149 @@
+'use strict';
+
+/**
+ * Repo → { card, checkpoint, cardId, checkpointId, stateId }, or { busy }.
+ * Reads git, writes nothing. Capture is deterministic: the same repo state
+ * always derives the same ids, which is what makes equal ids silence.
+ */
+
+const crypto = require('crypto');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const { runGit, gitText, tryGitText } = require('./git');
+
+/** git's well-known empty tree: the diff base for a repo with no commits. */
+const EMPTY_TREE = '4b825dc642cb6eb9a060e54bf8d69288fbee4904';
+
+/**
+ * Index states no patch can represent (axiom 3). Bisect is deliberately NOT
+ * here: it is a mode, not an unfinished operation — it can last hours, and
+ * every checkout it makes must be captured like any other.
+ */
+const BUSY_MARKERS = [
+  'MERGE_HEAD',
+  'rebase-merge',
+  'rebase-apply',
+  'CHERRY_PICK_HEAD',
+  'REVERT_HEAD',
+];
+
+const sha256 = (bytes) => crypto.createHash('sha256').update(bytes).digest('hex');
+
+/** The actual .git directory, resolved through worktree/submodule pointers. */
+function gitDirPath(repoPath) {
+  return path.resolve(repoPath, gitText(repoPath, ['rev-parse', '--git-dir']));
+}
+
+function busyReason(repoPath) {
+  const gitDir = gitDirPath(repoPath);
+  for (const marker of BUSY_MARKERS) {
+    if (fs.existsSync(path.join(gitDir, marker))) return marker;
+  }
+  return null;
+}
+
+function refList(repoPath, prefix) {
+  const out = tryGitText(repoPath, ['for-each-ref', '--format=%(refname:short) %(objectname)', prefix]);
+  if (!out) return [];
+  return out.split('\n').map((line) => {
+    const at = line.lastIndexOf(' ');
+    return { name: line.slice(0, at), commit: line.slice(at + 1) };
+  }).sort((a, b) => (a.name < b.name ? -1 : 1));
+}
+
+function remoteList(repoPath) {
+  const out = tryGitText(repoPath, ['config', '--get-regexp', '^remote\\..*\\.url$']);
+  if (!out) return [];
+  return out.split('\n').map((line) => {
+    const at = line.indexOf(' ');
+    return { name: line.slice(7, at - 4), url: line.slice(at + 1) };
+  }).sort((a, b) => (a.name < b.name ? -1 : 1));
+}
+
+function untrackedFiles(repoPath) {
+  const out = runGit(repoPath, ['ls-files', '--others', '--exclude-standard', '-z']).toString('utf8');
+  return out.split('\0').filter(Boolean).sort().flatMap((rel) => {
+    // A trailing slash is git marking a repo boundary it will not enter — a
+    // nested repository or linked worktree. That is its own territory with
+    // its own card; the parent's checkpoint must not contain it.
+    if (rel.endsWith('/')) return [];
+    const abs = path.join(repoPath, rel);
+    const stat = fs.lstatSync(abs);
+    if (stat.isSymbolicLink()) {
+      const content = Buffer.from(fs.readlinkSync(abs));
+      return [{ path: rel, mode: '120000', content, sha256: sha256(content) }];
+    }
+    if (stat.isDirectory()) return []; // same boundary, unmarked: never read a directory as a file
+    const content = fs.readFileSync(abs);
+    const mode = stat.mode & 0o111 ? '100755' : '100644';
+    return [{ path: rel, mode, content, sha256: sha256(content) }];
+  });
+}
+
+function makeBundle(repoPath) {
+  const tmp = path.join(os.tmpdir(), `repocard-${process.pid}-${crypto.randomBytes(6).toString('hex')}.bundle`);
+  try {
+    runGit(repoPath, ['bundle', 'create', tmp, '--all', 'HEAD']);
+    const bytes = fs.readFileSync(tmp);
+    return { bytes, sha256: sha256(bytes) };
+  } finally {
+    fs.rmSync(tmp, { force: true });
+  }
+}
+
+function deriveCardId(card) {
+  return sha256(JSON.stringify({
+    version: card.version,
+    head: card.head,
+    branches: card.branches,
+    tags: card.tags,
+    // remotes deliberately absent: seed metadata, not identity (axiom 5).
+    // bundle bytes deliberately absent: packing is not deterministic (axiom 2).
+  }));
+}
+
+function deriveCheckpointId(checkpoint) {
+  return sha256(JSON.stringify({
+    baseCommit: checkpoint.baseCommit,
+    stagedPatch: sha256(checkpoint.stagedPatch),
+    unstagedPatch: sha256(checkpoint.unstagedPatch),
+    untracked: checkpoint.untracked.map((file) => ({
+      path: file.path, mode: file.mode, sha256: file.sha256,
+    })),
+  }));
+}
+
+function capture(repoPath, { withBundle = true } = {}) {
+  const busy = busyReason(repoPath);
+  if (busy) return { busy };
+
+  const branch = tryGitText(repoPath, ['symbolic-ref', '-q', '--short', 'HEAD']); // null = detached
+  const commit = tryGitText(repoPath, ['rev-parse', '-q', '--verify', 'HEAD']);   // null = unborn
+
+  const card = {
+    version: 1,
+    head: { branch, commit, detached: branch === null && commit !== null },
+    branches: refList(repoPath, 'refs/heads'),
+    tags: refList(repoPath, 'refs/tags'),
+    remotes: remoteList(repoPath),
+    bundle: commit && withBundle ? makeBundle(repoPath) : null,
+  };
+
+  const checkpoint = {
+    baseCommit: commit,
+    branch,
+    // Patches stay Buffers: a "text" diff of NUL-free binary content carries
+    // raw non-UTF-8 bytes, and a string conversion would corrupt it silently.
+    stagedPatch: runGit(repoPath, ['diff', '--cached', '--binary', '--full-index', commit ? 'HEAD' : EMPTY_TREE]),
+    unstagedPatch: runGit(repoPath, ['diff', '--binary', '--full-index']),
+    untracked: untrackedFiles(repoPath),
+  };
+
+  const cardId = deriveCardId(card);
+  const checkpointId = deriveCheckpointId(checkpoint);
+  return { card, checkpoint, cardId, checkpointId, stateId: sha256(cardId + checkpointId) };
+}
+
+module.exports = { capture, busyReason, gitDirPath, sha256, EMPTY_TREE };

package/runtime/scripts/amalgm-mcp/repocard/follow.js

@@ -0,0 +1,310 @@
+'use strict';
+
+/**
+ * The follower: raw repo doorbells in, at most one honest semantic event out.
+ *
+ * The axiom: **ids identify settled states — and a settled state is the
+ * only completion git ever announces.** Every change the two documents
+ * describe settles as one of exactly two facts: the committed history
+ * moved (cardId) or the work on top of it moved (checkpointId). History-
+ * moving operations — commit, merge, rebase, checkout — end by moving a
+ * ref atomically; worktree commands — add, restore, clean, an editor
+ * saving — end the way any edit does, leaving files that settle into a
+ * new checkpointId. Ids never claim a *command* finished: an unowned
+ * writer that pauses mid-run yields two true states, not one. Operation
+ * boundaries exist only where someone owns the writer — git's busy
+ * markers for its own operations, `command()` for amalgm's — and no
+ * event-driven observer can invent one for a writer nobody owns. So we
+ * read where both ids are once the ground is still; card + checkpoint is
+ * the whole vocabulary:
+ *
+ *   cardId moved         -> card.changed        (an operation completed)
+ *   only checkpointId    -> checkpoint.changed  (work on top: edits,
+ *                                                staging, untracked, clean)
+ *   neither              -> silence             (churn, touches, echoes)
+ *
+ * Git stores the truth but gives an outside reader no bell, no atomic
+ * glance, and no record of untracked files. Everything else in this module
+ * is the plumbing that makes an outside read safe — never a third document:
+ *
+ *  - **The torn-read guard.** A state travels only when two consecutive
+ *    captures agree on its identity — a torn, id-inconsistent snapshot
+ *    never travels, and ignored churn (which never moves the ids) cannot
+ *    starve detection (`capMs` keeps trying, the pair keeps it honest).
+ *  - **Busy markers.** Git saying "I am between two cards; there is no
+ *    coherent state to photograph yet." Their removal rings. Bisect is NOT
+ *    busy — it is a mode whose checkouts must each be seen.
+ *  - **Locks, with a liveness check.** A lock HELD by a living process is
+ *    git mid-write: wait, and report it (`status().blocked`); the lock's
+ *    deletion rings. An unheld lock is litter from a crash and blocks
+ *    nothing — proven empirically: a stale lock still lets edits, `git
+ *    clean`, even `update-ref` through, so honoring it would be permanent
+ *    blindness. The holder check is a single shot when a capture attempt
+ *    meets a lock — never a poll.
+ *  - **`command(fn)` is an optimization, not an authority.** An amalgm-run
+ *    command batches its noise into one capture at its end. Correctness
+ *    never depends on it — the ids' movement is the completion signal
+ *    for commands amalgm never sees.
+ *
+ * The follower retries itself whenever it holds firsthand evidence of a
+ * miss (a disagreeing pair, a failed capture, a failed emit). It waits on
+ * the doorbell only for endings that are filesystem events, and consumer
+ * moments (`flush()` — a session opening, an app regaining focus) are the
+ * pull valve that turns a lost doorbell's "delayed" into "delivered"
+ * without polling. Named residual: a lock-free writer that stalls across
+ * both reads looks like stillness; the next doorbell or flush corrects the
+ * ids but cannot unsend the event.
+ */
+
+const { execFileSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const { capture, busyReason, gitDirPath } = require('./capture');
+
+const LOCKS = ['index.lock', 'HEAD.lock', 'packed-refs.lock'];
+
+let lsofUnavailable = false;
+
+/**
+ * Does any living process hold this lock file open? Git's lockfile API
+ * keeps the fd open for the lock's whole life, so an unheld lock is litter
+ * from a crash. One subprocess per call, only ever called when a capture
+ * attempt meets a lock — never a poll. If the platform cannot answer,
+ * assume held: we never publish over a maybe-writing git.
+ */
+function lockHeld(lockPath) {
+  if (lsofUnavailable) return true;
+  try {
+    execFileSync('lsof', ['-t', '--', lockPath], { stdio: ['ignore', 'pipe', 'ignore'], timeout: 2_000 });
+    return true;
+  } catch (error) {
+    if (error.status === 1) return false; // lsof's "nobody": the lock is litter
+    lsofUnavailable = true;
+    console.warn('[Follower] lsof unavailable — treating locks as live:', error?.code || error?.message);
+    return true;
+  }
+}
+
+function createFollower(options) {
+  const {
+    repoPath,
+    emit,
+    settleMs = 200, // doorbells quiet this long -> try a capture
+    capMs = 2000,   // churn never quiet -> still try this often
+    last = null,    // resume seed: { cardId, checkpointId }
+    // May return a promise (e.g. a capture worker): the follower awaits it,
+    // and any doorbell that lands mid-pair re-arms a retry (`pendingWake`).
+    captureFn = (repo) => capture(repo, { withBundle: false }),
+  } = options;
+  if (!repoPath) throw new Error('createFollower requires { repoPath }');
+  if (typeof emit !== 'function') throw new Error('createFollower requires { emit }');
+
+  let known = last ? { cardId: last.cardId, checkpointId: last.checkpointId } : null;
+  let owned = 0; // depth of amalgm-owned commands in flight
+  let blocked = null; // lock name while the last capture attempt met a held lock
+  let blockedPath = null;
+  let settleTimer = null;
+  let capTimer = null;
+  let firing = false; // a consumer flushing from inside emit must not recurse
+  let pendingWake = false; // a fire attempt landed while a pair was in flight
+  let closed = false;
+
+  /** The first lock present on disk, or null. Heldness is checked separately. */
+  function presentLock() {
+    let gitDir;
+    try {
+      gitDir = gitDirPath(repoPath);
+    } catch {
+      return null; // not a repo right now; capture will say so
+    }
+    const name = LOCKS.find((lock) => fs.existsSync(path.join(gitDir, lock)));
+    return name ? { name, path: path.join(gitDir, name) } : null;
+  }
+
+  /** Self-armed retry: used only when the follower itself witnessed the miss. */
+  function retry(delayMs) {
+    if (closed) return;
+    if (settleTimer) clearTimeout(settleTimer);
+    settleTimer = setTimeout(() => {
+      settleTimer = null;
+      fire();
+    }, delayMs);
+    settleTimer.unref?.();
+  }
+
+  /** Emit if the ids moved. `known` advances only on successful delivery. */
+  function speak(snap) {
+    if (known && snap.cardId === known.cardId && snap.checkpointId === known.checkpointId) return true;
+    const type = !known || snap.cardId !== known.cardId ? 'card.changed' : 'checkpoint.changed';
+    try {
+      emit({
+        type,
+        path: repoPath,
+        cardId: snap.cardId,
+        checkpointId: snap.checkpointId,
+        stateId: snap.stateId,
+        card: snap.card,
+        checkpoint: snap.checkpoint,
+      });
+    } catch (error) {
+      console.warn(`[Follower] emit failed for "${repoPath}" — state stays undelivered:`, error?.message || error);
+      return false;
+    }
+    known = { cardId: snap.cardId, checkpointId: snap.checkpointId };
+    return true;
+  }
+
+  async function fire() {
+    if (closed || owned > 0) return;
+    if (firing) {
+      // With an async captureFn a doorbell can land while a pair is in
+      // flight; its timer is already consumed and the pair's answer may
+      // predate it. Remember the wake, re-arm when the pair completes.
+      // The completed pair still speaks: it read a true settled state
+      // (ids identify states, not commands). Invalidating in-flight pairs
+      // on every doorbell was considered and rejected — under sustained
+      // churn it silences the follower entirely (every pair dies young),
+      // where this rule delivers rolling true snapshots that converge.
+      pendingWake = true;
+      return;
+    }
+    firing = true;
+    try {
+      await fireInner();
+    } catch (error) {
+      if (closed) return;
+      console.warn(`[Follower] capture cycle failed for "${repoPath}":`, error?.message || error);
+      retry(capMs);
+    } finally {
+      firing = false;
+      if (pendingWake) {
+        pendingWake = false;
+        retry(settleMs);
+      }
+    }
+  }
+
+  async function fireInner() {
+    if (settleTimer) { clearTimeout(settleTimer); settleTimer = null; }
+    if (capTimer) { clearTimeout(capTimer); capTimer = null; }
+
+    // A lock held by a living process is git mid-write: wait, report it;
+    // the lock's deletion rings. An unheld lock is litter from a crash —
+    // it stops neither editors nor `git clean` nor `update-ref`, so
+    // honoring it would be permanent blindness, not safety.
+    const lock = presentLock();
+    if (lock && lockHeld(lock.path)) {
+      blocked = lock.name;
+      blockedPath = lock.path;
+      return;
+    }
+    blocked = null;
+    blockedPath = null;
+
+    try {
+      if (busyReason(repoPath)) return; // the operation's end rings its own doorbell
+    } catch {
+      return; // not a repo right now; territory handling lives in the observer
+    }
+
+    // The torn-read guard: two consecutive reads must agree before a state
+    // may travel — a repo mid-mutation cannot produce the same ids twice.
+    let first;
+    let second;
+    try {
+      first = await captureFn(repoPath);
+      if (closed || owned > 0) return; // the pair is stale before it finished
+      second = first && !first.busy ? await captureFn(repoPath) : null;
+    } catch (error) {
+      if (closed) return;
+      // A read tripping over a mid-flight writer (a file vanishing between
+      // list and read) is evidence of motion, not a reason to go quiet.
+      console.warn(`[Follower] capture failed for "${repoPath}":`, error?.message || error);
+      retry(capMs);
+      return;
+    }
+    // The world may have moved while we awaited: a close() must not be
+    // spoken over, and a command that began mid-pair owns the boundary now.
+    if (closed || owned > 0) return;
+    if (!first || first.busy || !second || second.busy) return;
+    if (first.stateId !== second.stateId) {
+      // The pair disagreeing is firsthand evidence of a writer in flight;
+      // re-arm ourselves rather than hope the write's doorbell was delivered.
+      retry(settleMs);
+      return;
+    }
+    if (!speak(second)) retry(capMs); // consumer failure: patient, loud, never lost
+  }
+
+  function ring() {
+    if (closed || owned > 0) return; // the command's end is the boundary
+    if (settleTimer) clearTimeout(settleTimer);
+    settleTimer = setTimeout(() => {
+      settleTimer = null;
+      fire();
+    }, settleMs);
+    settleTimer.unref?.();
+    if (!capTimer) {
+      // Not restarted by rings: under endless churn this still fires, and
+      // the torn-read guard decides whether anything was actually still.
+      capTimer = setTimeout(() => {
+        capTimer = null;
+        fire();
+      }, capMs);
+      capTimer.unref?.();
+    }
+  }
+
+  function beginCommand() {
+    owned += 1;
+  }
+
+  function endCommand() {
+    owned = Math.max(0, owned - 1);
+    if (owned === 0 && !closed) fire();
+  }
+
+  /** Run an amalgm-owned command: no captures while it runs, one at its end. */
+  function command(fn) {
+    beginCommand();
+    let result;
+    try {
+      result = fn();
+    } catch (error) {
+      endCommand();
+      throw error;
+    }
+    if (result && typeof result.then === 'function') {
+      return Promise.resolve(result).finally(() => endCommand());
+    }
+    endCommand();
+    return result;
+  }
+
+  return {
+    ring,
+    /** Birth: capture once, immediately. With a seeded `last`, an unchanged repo is silence. */
+    start: () => fire(),
+    /** Consumer-requested capture — the "scanNow" of this layer. */
+    flush: () => fire(),
+    beginCommand,
+    endCommand,
+    command,
+    ids: () => (known ? { ...known } : null),
+    /**
+     * `blocked` is the lock that deferred the last capture attempt — checked
+     * against disk so a lock deleted behind our back never reads as blocked.
+     */
+    status: () => ({ blocked: blocked && fs.existsSync(blockedPath) ? blocked : null }),
+    close() {
+      closed = true;
+      for (const timer of [settleTimer, capTimer]) {
+        if (timer) clearTimeout(timer);
+      }
+      settleTimer = capTimer = null;
+    },
+  };
+}
+
+module.exports = { createFollower };

package/runtime/scripts/amalgm-mcp/repocard/git.js

@@ -0,0 +1,48 @@
+'use strict';
+
+/**
+ * The one place this layer talks to git: plain subprocesses, no libraries.
+ * Output is Buffers (git output is not always text); errors carry git's own
+ * stderr. `tryGit` is for probes where failure is an answer, not a problem
+ * (detached HEAD, unborn HEAD, a merge that conflicts).
+ */
+
+const { execFileSync } = require('child_process');
+
+const MAX_BUFFER = 512 * 1024 * 1024;
+
+function runGit(cwd, args, { input } = {}) {
+  try {
+    return execFileSync('git', args, {
+      cwd,
+      input,
+      maxBuffer: MAX_BUFFER,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+    });
+  } catch (error) {
+    const stderr = error.stderr ? error.stderr.toString('utf8').trim() : '';
+    error.message = `git ${args.join(' ')} failed${stderr ? `: ${stderr}` : ''}`;
+    // The mark truth readers classify by: git itself failed on this
+    // ground, distinct from a programming error in the caller.
+    error.gitFailed = `git ${args[0]}`;
+    throw error;
+  }
+}
+
+function tryGit(cwd, args, options) {
+  try {
+    return runGit(cwd, args, options);
+  } catch {
+    return null;
+  }
+}
+
+const gitText = (cwd, args, options) => runGit(cwd, args, options).toString('utf8').trim();
+
+function tryGitText(cwd, args, options) {
+  const out = tryGit(cwd, args, options);
+  return out === null ? null : out.toString('utf8').trim();
+}
+
+module.exports = { runGit, tryGit, gitText, tryGitText };

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

@@ -0,0 +1,48 @@
+'use strict';
+
+/**
+ * The repocard api.
+ *
+ *   capture(repoPath)      → { card, checkpoint, cardId, checkpointId, stateId } | { busy }
+ *   verify(repoPath, ids)  → { ok, problems, cardId, checkpointId }
+ *   apply(dir, state)      → materialize + prove: the ids re-derived from the
+ *                            result must equal the ids that arrived (axiom 4).
+ *                            Throws if reproduction failed; only a return is
+ *                            "I applied this event."
+ *   createFollower(opts)   → repo doorbells in, card.changed /
+ *                            checkpoint.changed / silence out (follow.js).
+ *   createCaptureWorker()  → capture off the event loop: { capture, close }
+ *                            (capture-worker.js); pass its capture as a
+ *                            follower's captureFn.
+ */
+
+const { capture } = require('./capture');
+const { materialize } = require('./apply');
+const { createFollower } = require('./follow');
+const { createCaptureWorker } = require('./capture-worker');
+
+function verify(repoPath, expected) {
+  const derived = capture(repoPath, { withBundle: false });
+  if (derived.busy) {
+    return { ok: false, problems: [`repo is busy: ${derived.busy}`], cardId: null, checkpointId: null };
+  }
+  const problems = [];
+  if (derived.cardId !== expected.cardId) {
+    problems.push(`cardId mismatch: expected ${expected.cardId}, derived ${derived.cardId}`);
+  }
+  if (derived.checkpointId !== expected.checkpointId) {
+    problems.push(`checkpointId mismatch: expected ${expected.checkpointId}, derived ${derived.checkpointId}`);
+  }
+  return { ok: problems.length === 0, problems, cardId: derived.cardId, checkpointId: derived.checkpointId };
+}
+
+function apply(dir, state) {
+  materialize(dir, state.card, state.checkpoint);
+  const proof = verify(dir, state);
+  if (!proof.ok) {
+    throw new Error(`apply did not reproduce the state: ${proof.problems.join('; ')}`);
+  }
+  return { cardId: proof.cardId, checkpointId: proof.checkpointId };
+}
+
+module.exports = { capture, apply, verify, createFollower, createCaptureWorker };

package/runtime/scripts/amalgm-mcp/server/local-service-router.js

@@ -24,6 +24,7 @@ const { handleLocalRoutes } = require('./routes/local');
 const { handleCredentialRoutes } = require('./routes/credentials');
 const { handleInboundRoutes } = require('./routes/inbound');
 const { handleAppRoutes } = require('./routes/apps');
+const { handleEntityRoutes } = require('./routes/entities');
 
 const DEFAULT_ROUTE_GROUPS = [
   handleHealthRoutes,
@@ -42,6 +43,7 @@ const DEFAULT_ROUTE_GROUPS = [
   handleCredentialRoutes,
   handleInboundRoutes,
   handleAppRoutes,
+  handleEntityRoutes,
 ];
 
 function createLocalServiceRouter(routeGroups = DEFAULT_ROUTE_GROUPS) {