amalgm 0.1.161 → 0.1.162

package/runtime/scripts/amalgm-mcp/workspace/checkpoint.js

@@ -0,0 +1,237 @@
+'use strict';
+
+/**
+ * Repo checkpoints: each machine's uncommitted work as one recoverable
+ * fact on the rail.
+ *
+ * The two-value repo sync model: the card carries B — where the repo
+ * stands (commit, branch, dirty counts) — and the checkpoint carries D —
+ * the exact uncommitted content as one patch against B. A checkpoint
+ * lives in a document only this machine ever writes: one derived-id
+ * resource per (machine, repository identity), so machines never share a
+ * writer and the doc rail's merge question never arises. Ignored files
+ * never travel by construction — git does not list them.
+ *
+ * Checkpoints are captured only from settled repos (no operation in
+ * flight) and only for primary checkouts with a transportable repo
+ * identity. A clean repo publishes { revision: null } — "nothing dirty"
+ * is a fact peers act on, not an absence. Dirty state over the byte
+ * budget publishes { revision: null, skipped: 'too-large' } — visible,
+ * never silent.
+ */
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+const { AMALGM_DIR } = require('../config');
+const { subscribeStateEvents } = require('../state/events');
+const { machineId, userId } = require('./identity');
+const { listRepoCards } = require('./cards');
+const { captureWorktreeDiff } = require('./git');
+const { ensureDocBound } = require('./binding');
+const { listPairStates } = require('./ledger');
+
+const CHECKPOINT_CONTRACT = 'repo-checkpoint@1';
+const MAX_DIFF_BYTES = 1_000_000;
+const PUBLISH_QUIET_MS = 500;
+const RECONCILE_INTERVAL_MS = 30_000;
+
+const service = {
+  started: false,
+  publishTimer: null,
+  reconcileTimer: null,
+  unsubscribe: null,
+  counters: { published: 0, skips: 0, unbound: 0, failures: 0 },
+  lastRun: null,
+};
+
+function sha256(text) {
+  return crypto.createHash('sha256').update(text, 'utf8').digest('hex');
+}
+
+/** The transportable identity of a card's repository, or null. */
+function repoKeyOfCard(card) {
+  if (card?.repo?.remote) return card.repo.remote;
+  return card?.repo?.rootCommit ? `root:${card.repo.rootCommit}` : null;
+}
+
+/** One resource per (machine, repo) per account — same id on every machine. */
+function checkpointResourceId(machine, repoKey, forUserId = userId()) {
+  if (!forUserId || !machine || !repoKey) return null;
+  const digest = crypto.createHash('sha256')
+    .update(`amalgm-repo-checkpoint@1|${forUserId}|${machine}|${repoKey}`)
+    .digest('base64url');
+  return `shr_rc1${digest.slice(0, 40)}`;
+}
+
+/** The local file backing a checkpoint doc — own or an attached peer's. */
+function checkpointFile(machine, repoKey) {
+  const digest = crypto.createHash('sha256').update(`${machine}|${repoKey}`).digest('hex').slice(0, 24);
+  return path.join(AMALGM_DIR, 'state', 'repo-checkpoints', `${digest}.json`);
+}
+
+/** The content identity of a dirty state: same base, same patch → same revision. */
+function revisionOf(baseOid, diff) {
+  return crypto.createHash('sha256').update(`${baseOid}\n${diff}`, 'utf8').digest('hex');
+}
+
+function parseCheckpoint(text) {
+  try {
+    const entry = JSON.parse(text);
+    if (entry?.checkpoint !== CHECKPOINT_CONTRACT || !entry.machine || !entry.repoKey) return null;
+    return entry;
+  } catch {
+    return null;
+  }
+}
+
+/** A machine's published checkpoint for a repo, as this machine sees it. */
+function readCheckpoint(machine, repoKey) {
+  const file = checkpointFile(machine, repoKey);
+  if (!fs.existsSync(file)) return null;
+  return parseCheckpoint(require('../state/docs').getDocText(file));
+}
+
+/**
+ * Whose work this machine's tree already holds for a repo, from the
+ * reconciliation ledger. Stamped onto outgoing checkpoints so "this diff
+ * incorporates peer X's revision R" is an explicit fact on the wire —
+ * a receiver can tell its own echoed work from new content.
+ */
+function incorporatesFor(repoKey) {
+  const map = {};
+  for (const state of listPairStates()) {
+    if (state.repoKey === repoKey && state.holdsContent && state.peerRevision) {
+      map[state.peerMachine] = state.peerRevision;
+    }
+  }
+  return Object.keys(map).length ? map : undefined;
+}
+
+async function buildEnvelope(card, machine, repoKey) {
+  if (!card.head.oid) return null;
+  const base = {
+    checkpoint: CHECKPOINT_CONTRACT,
+    machine,
+    repoKey,
+    branch: card.head.branch,
+    baseOid: card.head.oid,
+    capturedAt: new Date().toISOString(),
+  };
+  const dirtyTotal = card.dirty.staged + card.dirty.unstaged + card.dirty.untracked + card.dirty.conflicted;
+  if (dirtyTotal === 0) return { ...base, revision: null, diff: '' };
+
+  const captured = await captureWorktreeDiff(card.path, { maxBytes: MAX_DIFF_BYTES });
+  if (captured.diff === null) return { ...base, revision: null, diff: '', skipped: captured.reason };
+  // The repo may have moved between the card and this capture; the next
+  // doorbell pass re-cards and re-captures a coherent pair.
+  if (captured.baseOid !== card.head.oid) return null;
+  const incorporates = incorporatesFor(repoKey);
+  return {
+    ...base,
+    baseOid: captured.baseOid,
+    revision: revisionOf(captured.baseOid, captured.diff),
+    diff: captured.diff,
+    ...(incorporates ? { incorporates } : {}),
+  };
+}
+
+/** Publish this machine's checkpoint docs — one per eligible checkout. */
+async function publishCheckpoints() {
+  const machine = machineId();
+  const run = { published: 0, skips: 0, unbound: 0, failures: 0 };
+  for (const card of listRepoCards()) {
+    if (card.health !== 'healthy' || card.kind !== 'primary' || card.operation !== 'none') continue;
+    const repoKey = repoKeyOfCard(card);
+    const resourceId = checkpointResourceId(machine, repoKey);
+    if (!resourceId) continue;
+    try {
+      const file = checkpointFile(machine, repoKey);
+      const binding = await ensureDocBound({ resourceId, filePath: file, create: true });
+      if (!binding.bound) {
+        run.unbound += 1;
+        continue;
+      }
+      const envelope = await buildEnvelope(card, machine, repoKey);
+      if (!envelope) continue;
+      const docs = require('../state/docs');
+      const current = docs.getDocText(file);
+      const existing = parseCheckpoint(current);
+      const unchanged = existing
+        && existing.baseOid === envelope.baseOid
+        && existing.revision === envelope.revision
+        && (existing.skipped || null) === (envelope.skipped || null)
+        && JSON.stringify(existing.incorporates ?? null) === JSON.stringify(envelope.incorporates ?? null);
+      if (unchanged) {
+        run.skips += 1;
+        continue;
+      }
+      docs.writeDocText(file, `${JSON.stringify(envelope)}\n`, { baseHash: sha256(current) });
+      run.published += 1;
+    } catch (error) {
+      run.failures += 1;
+      console.warn(`[RepoCheckpoint] publish failed for ${card.path}:`, error.message);
+    }
+  }
+  service.counters.published += run.published;
+  service.counters.skips += run.skips;
+  service.counters.unbound += run.unbound;
+  service.counters.failures += run.failures;
+  service.lastRun = { ...run, at: new Date().toISOString() };
+  return run;
+}
+
+function schedulePublish() {
+  if (!service.started || service.publishTimer) return;
+  service.publishTimer = setTimeout(() => {
+    service.publishTimer = null;
+    publishCheckpoints().catch((error) => console.warn('[RepoCheckpoint] publish pass failed:', error.message));
+  }, PUBLISH_QUIET_MS);
+  service.publishTimer.unref?.();
+}
+
+function startCheckpointService() {
+  if (service.started) return;
+  service.started = true;
+  service.unsubscribe = subscribeStateEvents((event) => {
+    if (event.resource === 'repo-cards') schedulePublish();
+  });
+  service.reconcileTimer = setInterval(schedulePublish, RECONCILE_INTERVAL_MS);
+  service.reconcileTimer.unref?.();
+  schedulePublish();
+}
+
+function stopCheckpointService() {
+  if (!service.started) return;
+  service.started = false;
+  service.unsubscribe?.();
+  service.unsubscribe = null;
+  if (service.publishTimer) clearTimeout(service.publishTimer);
+  service.publishTimer = null;
+  if (service.reconcileTimer) clearInterval(service.reconcileTimer);
+  service.reconcileTimer = null;
+}
+
+function checkpointStats() {
+  return {
+    contract: CHECKPOINT_CONTRACT,
+    started: service.started,
+    ...service.counters,
+    lastRun: service.lastRun,
+  };
+}
+
+module.exports = {
+  CHECKPOINT_CONTRACT,
+  MAX_DIFF_BYTES,
+  checkpointFile,
+  checkpointResourceId,
+  checkpointStats,
+  parseCheckpoint,
+  publishCheckpoints,
+  readCheckpoint,
+  repoKeyOfCard,
+  revisionOf,
+  startCheckpointService,
+  stopCheckpointService,
+};

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

@@ -256,29 +256,80 @@ async function rootCommit(worktreeRoot) {
   return stdout.trim().split('\n').sort()[0];
 }
 
+/** Does this checkout's object store already contain the commit? */
+async function hasCommit(worktreeRoot, oid) {
+  const result = await git(['-C', worktreeRoot, 'cat-file', '-e', `${oid}^{commit}`], worktreeRoot, {
+    okCodes: [0, 1, 128],
+  });
+  return result.exitCode === 0;
+}
+
 /**
- * Does git own this file? A file is git-owned when the worktree around it
- * tracks it (`ls-files --error-unmatch`). Untracked files inside a repo
- * and files outside any repo have no git owner.
- * Returns { toplevel } for a git-owned file, null otherwise.
+ * Is `ancestorOid` an ancestor of (or equal to) `descendantOid`, as far
+ * as this checkout can tell? A commit this repo has never fetched (exit
+ * 128) is simply not a known ancestor.
  */
-async function gitOwnerOf(filePath) {
-  const classified = await classifyDirectory(path.dirname(filePath));
-  if (classified.kind !== 'worktree') return null;
+async function isAncestor(worktreeRoot, ancestorOid, descendantOid) {
+  const result = await git(
+    ['-C', worktreeRoot, 'merge-base', '--is-ancestor', ancestorOid, descendantOid],
+    worktreeRoot,
+    { okCodes: [0, 1, 128] },
+  );
+  return result.exitCode === 0;
+}
+
+// Diff output is hashed and applied verbatim, so its bytes must be exact
+// and stable: no quoted path mangling, no abbreviated blob ids.
+const PATCH_ARGS = ['-c', 'core.quotepath=false'];
+
+/**
+ * The complete uncommitted content of a worktree as one applyable patch
+ * against HEAD: staged and unstaged edits together (`git diff HEAD`),
+ * plus every untracked file as a creation diff. Ignored files are
+ * excluded by construction — git never lists them. Binary content rides
+ * `--binary` literals.
+ *
+ * Returns { baseOid, diff, bytes } — diff is '' for a clean tree — or
+ * { baseOid, diff: null, reason } when the state cannot be captured as a
+ * patch (an unborn HEAD, or dirty content over the byte budget).
+ */
+async function captureWorktreeDiff(worktreeRoot, { maxBytes = 1_000_000 } = {}) {
+  const baseOid = await headOid(worktreeRoot);
+  if (!baseOid) return { baseOid: null, diff: null, reason: 'unborn' };
+
   const tracked = await git(
-    ['ls-files', '--error-unmatch', '--', path.basename(filePath)],
-    path.dirname(filePath),
-    { okCodes: [0, 1] },
+    ['-C', worktreeRoot, ...PATCH_ARGS, 'diff', 'HEAD', '--binary', '--full-index'],
+    worktreeRoot,
   );
-  return tracked.exitCode === 0 ? { toplevel: classified.toplevel } : null;
+  const parts = [tracked.stdout];
+  let bytes = Buffer.byteLength(tracked.stdout);
+
+  const untracked = await git(
+    ['-C', worktreeRoot, 'ls-files', '--others', '--exclude-standard', '-z'],
+    worktreeRoot,
+  );
+  for (const file of untracked.stdout.split('\0').filter(Boolean).sort()) {
+    if (bytes > maxBytes) break;
+    const creation = await git(
+      ['-C', worktreeRoot, ...PATCH_ARGS, 'diff', '--no-index', '--binary', '--full-index', '--', '/dev/null', file],
+      worktreeRoot,
+      { okCodes: [0, 1] },
+    );
+    parts.push(creation.stdout);
+    bytes += Buffer.byteLength(creation.stdout);
+  }
+  if (bytes > maxBytes) return { baseOid, diff: null, reason: 'too-large', bytes };
+  return { baseOid, diff: parts.join(''), bytes };
 }
 
 module.exports = {
   GitError,
+  captureWorktreeDiff,
   classifyDirectory,
-  gitOwnerOf,
+  hasCommit,
   headAndDirty,
   headOid,
+  isAncestor,
   listWorktrees,
   operationState,
   originUrl,

package/runtime/scripts/amalgm-mcp/workspace/ledger.js

@@ -0,0 +1,96 @@
+'use strict';
+
+/**
+ * The reconciliation ledger: one durable record per (peer machine,
+ * repository) pair, remembering which part of this machine's working tree
+ * is a peer's contribution.
+ *
+ * The record's heart is `heldTree` — a git tree oid describing "base
+ * commit plus exactly the peer content this machine has folded in". The
+ * working tree is never assumed to equal it; local work is expected to
+ * coexist around it. `holdsContent` (heldTree differs from the bare base
+ * tree) is what lets the checkpoint publisher stamp outgoing diffs with
+ * whose work they incorporate.
+ *
+ * Split out of reconcile.js so the checkpoint layer can read holdings
+ * without importing the reconciler.
+ */
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+const { AMALGM_DIR } = require('../config');
+
+const STATE_DIR = path.join(AMALGM_DIR, 'state', 'workspace-reconciliation');
+const LEGACY_STATE_DIR = path.join(AMALGM_DIR, 'state', 'workspace-follow');
+let stateDirReady = false;
+
+/** Preserve existing pair ownership while retiring the old service name. */
+function ensureStateDir() {
+  if (stateDirReady) return;
+  stateDirReady = true;
+  if (fs.existsSync(STATE_DIR) || !fs.existsSync(LEGACY_STATE_DIR)) return;
+  fs.renameSync(LEGACY_STATE_DIR, STATE_DIR);
+}
+
+function pairDigest(peerMachine, repoKey) {
+  return crypto.createHash('sha256').update(`${peerMachine}|${repoKey}`).digest('hex').slice(0, 24);
+}
+
+function pairStateFile(digest) {
+  ensureStateDir();
+  return path.join(STATE_DIR, `${digest}.json`);
+}
+
+function readPairState(digest) {
+  try {
+    return JSON.parse(fs.readFileSync(pairStateFile(digest), 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function writePairState(digest, patch) {
+  ensureStateDir();
+  fs.mkdirSync(STATE_DIR, { recursive: true });
+  const next = { ...readPairState(digest), ...patch, updatedAt: new Date().toISOString() };
+  fs.writeFileSync(pairStateFile(digest), `${JSON.stringify(next, null, 2)}\n`);
+  return next;
+}
+
+/** Every pair record on this machine — for stats and incorporates stamps. */
+function listPairStates() {
+  ensureStateDir();
+  let names;
+  try {
+    names = fs.readdirSync(STATE_DIR);
+  } catch {
+    return [];
+  }
+  const states = [];
+  for (const name of names) {
+    if (!/^[0-9a-f]{24}\.json$/.test(name)) continue;
+    try {
+      states.push(JSON.parse(fs.readFileSync(path.join(STATE_DIR, name), 'utf8')));
+    } catch { /* an unreadable record is not a pair */ }
+  }
+  return states;
+}
+
+/** Boundary: no movement without a durable copy of what the tree held. */
+function saveRollback(digest, diff) {
+  ensureStateDir();
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const file = path.join(STATE_DIR, `rollback-${digest}-${stamp}.patch`);
+  fs.mkdirSync(STATE_DIR, { recursive: true });
+  fs.writeFileSync(file, diff);
+  return file;
+}
+
+module.exports = {
+  listPairStates,
+  pairDigest,
+  readPairState,
+  saveRollback,
+  writePairState,
+};