amalgm 0.1.175 → 0.1.176

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

@@ -1,452 +0,0 @@
-'use strict';
-
-/**
- * Workspace reconciliation: reconcile this machine's checkouts toward
- * what peer machines published — cards for where the repo stands (B),
- * checkpoints for the uncommitted content (D).
- *
- * The workspace rule this implements: every writer — human, agent, or
- * remote machine — writes into the same working tree, and no writer's
- * work is ever silently lost. A peer's edits land here the way a local
- * agent's would: non-overlapping changes coexist, overlapping changes
- * preserve both versions and surface a named per-file conflict, git
- * history moves (commit, branch) travel as card-controlled transitions,
- * and ignored files never participate.
- *
- * Reconciliation is automatic for every eligible checkout. There is no
- * per-machine enable flag and no directional relationship between
- * machines. Authorization belongs at the user-level workspace membership
- * boundary (owner, editor, viewer); this layer acts only on state admitted
- * by that boundary. There is one movement verb — advance the peer's
- * contribution in this tree from what we hold to what they published
- * (merge.js) — and it subsumes apply, re-apply, and restore: a peer going
- * clean is just an advance toward their bare base tree, removing exactly
- * their content and nothing else. Because folding an already-present
- * change is a no-op by content, echoed and replayed patches converge
- * instead of looping.
- *
- * Frozen boundaries: only closed-list operations execute (fetch an exact
- * branch from the approved remote, fast-forward, merged file writes via
- * the journaled transition layer), local work is never overwritten, and
- * every hold is a named, queryable state — never a silent skip. Each
- * reconcile pass executes at most one movement per repo and re-observes;
- * convergence happens across passes, on freshly verified state.
- */
-
-const fs = require('fs');
-const path = require('path');
-const { AMALGM_DIR } = require('../config');
-const { subscribeStateEvents } = require('../state/events');
-const { machineId } = require('./identity');
-const { listRepoCards, refreshRepoCard, refreshRepoCards } = require('./cards');
-const { readWall } = require('./wall');
-const {
-  captureWorktreeDiff,
-  hasCommit,
-  headAndDirty,
-  isAncestor,
-  operationState,
-} = require('./git');
-const {
-  checkpointFile,
-  checkpointResourceId,
-  readCheckpoint,
-  repoKeyOfCard,
-  revisionOf,
-} = require('./checkpoint');
-const { ensureDocBound } = require('./binding');
-const { pairDigest, readPairState, saveRollback, writePairState } = require('./ledger');
-const merge = require('./merge');
-const transition = require('./transition');
-
-const RECONCILE_QUIET_MS = 25;
-const RECONCILE_INTERVAL_MS = 30_000;
-const WALL_FILE = path.join(AMALGM_DIR, 'state', 'machine-cards-v4.jsonl');
-
-const service = {
-  started: false,
-  reconcileTimer: null,
-  intervalTimer: null,
-  unsubscribe: null,
-  watchedDocs: new Set([WALL_FILE]),
-  pairs: new Map(), // digest → last outcome, for stats
-  counters: { passes: 0, movements: 0, failures: 0 },
-  lastPass: null,
-};
-
-function fileMtime(file) {
-  try {
-    return fs.statSync(file).mtime.toISOString();
-  } catch {
-    return null;
-  }
-}
-
-// --- same base: advance the peer's contribution ------------------------------
-
-function conflictSummary(conflicts) {
-  return conflicts.map((c) => `${c.kind}:${c.path}`).join(', ').slice(0, 300);
-}
-
-/**
- * Cards are last-writer-wins for committed repo position. positionAt
- * changes only when branch/OID changes; machine id breaks the
- * vanishingly rare exact timestamp tie so every peer makes one decision.
- */
-function compareCardFreshness(left, right) {
-  const leftAt = Date.parse(left?.positionAt || left?.observedAt || left?.updatedAt || '');
-  const rightAt = Date.parse(right?.positionAt || right?.observedAt || right?.updatedAt || '');
-  if (!Number.isFinite(leftAt) || !Number.isFinite(rightAt)) return 0;
-  if (leftAt !== rightAt) return leftAt < rightAt ? -1 : 1;
-  return String(left?.machine || '').localeCompare(String(right?.machine || ''));
-}
-
-async function advanceSameBase(localCard, digest, entry, captured, localRevision) {
-  const root = localCard.path;
-  const pairState = readPairState(digest);
-  const baseTree = await merge.treeOf(root, captured.baseOid);
-  const held = (
-    pairState.baseOid === captured.baseOid
-    && pairState.heldTree
-    && await merge.hasTree(root, pairState.heldTree)
-  ) ? pairState.heldTree : baseTree;
-  const target = await merge.treeOfPatch(root, captured.baseOid, entry.diff || '');
-  const ownWork = localRevision !== null && localRevision !== (pairState.settledLocalRevision ?? null);
-
-  if (held === target) {
-    if (target === baseTree) {
-      return localRevision === null
-        ? { state: 'in-sync', reason: null }
-        : { state: 'local-work', reason: 'peer-clean' };
-    }
-    return { state: 'applied', reason: ownWork ? 'with-local-work' : null };
-  }
-
-  // A conflicted attempt is only repeated when something changed: the
-  // peer published anew, or the local files moved. Otherwise report the
-  // standing conflict without touching anything.
-  if (
-    pairState.peerRevision === entry.revision
-    && pairState.heldTree === held
-    && pairState.conflicts?.length
-    && pairState.settledLocalRevision === localRevision
-  ) {
-    return { state: 'conflict', reason: conflictSummary(pairState.conflicts), conflicts: pairState.conflicts };
-  }
-
-  saveRollback(digest, captured.diff);
-  const result = await merge.advance(root, held, target, { label: entry.revision || 'peer-clean' });
-  const recaptured = await captureWorktreeDiff(root);
-  writePairState(digest, {
-    peerMachine: entry.machine,
-    repoKey: entry.repoKey,
-    baseOid: captured.baseOid,
-    heldTree: result.heldTree,
-    holdsContent: result.heldTree !== baseTree,
-    peerRevision: entry.revision,
-    conflicts: result.conflicts,
-    settledLocalRevision: recaptured.diff ? revisionOf(recaptured.baseOid, recaptured.diff) : null,
-  });
-
-  const moved = result.applied.length > 0;
-  if (result.conflicts.length) {
-    return { state: 'conflict', reason: conflictSummary(result.conflicts), conflicts: result.conflicts, moved };
-  }
-  if (target === baseTree) {
-    return recaptured.diff === ''
-      ? { state: 'in-sync', reason: 'restored-peer-went-clean', moved }
-      : { state: 'local-work', reason: 'peer-clean', moved };
-  }
-  return { state: 'applied', reason: ownWork ? 'coexisting-with-local-work' : null, moved };
-}
-
-// --- one repo, one pass -----------------------------------------------------
-
-/**
- * Reconcile one local checkout toward one peer's published state.
- * Executes at most one movement, returns { state, reason } — every branch
- * of the decision has a name that survives into stats.
- */
-async function reconcilePair(localCard, peerCard, entry, digest) {
-  if (!entry) return { state: 'waiting', reason: 'no-peer-checkpoint-yet' };
-  if (!entry.baseOid) return { state: 'waiting', reason: 'peer-unborn' };
-
-  if (entry.payload?.kind === 'pending') {
-    return { state: 'waiting', reason: 'checkpoint-uploading' };
-  }
-  if (entry.payload) {
-    const payload = require('./objects').readPayload(entry.payload);
-    if (payload.state !== 'ready') {
-      return { state: 'waiting', reason: `checkpoint-${payload.state}` };
-    }
-    const diff = payload.bytes.toString('utf8');
-    if (revisionOf(entry.baseOid, diff) !== entry.revision) {
-      return { state: 'blocked', reason: 'checkpoint-revision-mismatch' };
-    }
-    entry = { ...entry, diff };
-  }
-
-  const captured = await captureWorktreeDiff(localCard.path);
-  if (captured.diff === null) return { state: 'blocked', reason: `local-capture-${captured.reason}` };
-  const current = await headAndDirty(localCard.path);
-  const operation = await operationState(localCard.path);
-  if (operation !== 'none') return { state: 'waiting', reason: 'local-operation-in-flight' };
-  if (captured.baseOid !== current.head.oid) return { state: 'waiting', reason: 'local-state-moving' };
-
-  const targetBranch = entry.branch || peerCard.head?.branch;
-  if (
-    peerCard.head?.oid !== entry.baseOid
-    || peerCard.head?.branch !== targetBranch
-  ) {
-    return { state: 'waiting', reason: 'peer-card-checkpoint-mismatch' };
-  }
-  if (
-    (entry.baseOid !== current.head.oid || targetBranch !== current.head.branch)
-    && compareCardFreshness(localCard, peerCard) > 0
-  ) {
-    return { state: 'local-newer', reason: null };
-  }
-  const localRevision = captured.diff === '' ? null : revisionOf(captured.baseOid, captured.diff);
-
-  if (entry.baseOid === captured.baseOid && targetBranch === current.head.branch) {
-    // A peer whose dirty state couldn't travel is a hold, not a signal to
-    // move — what we already folded in stays exactly where it is.
-    if (entry.skipped) return { state: 'waiting', reason: `peer-skipped-${entry.skipped}` };
-    return advanceSameBase(localCard, digest, entry, captured, localRevision);
-  }
-
-  // The peer's base commit differs from ours.
-  if (
-    current.head.branch === targetBranch
-    && await isAncestor(localCard.path, entry.baseOid, captured.baseOid)
-  ) {
-    return { state: 'peer-behind', reason: null };
-  }
-  if (!(await hasCommit(localCard.path, entry.baseOid))) {
-    if (peerCard.objects?.kind === 'bundle') {
-      const imported = await require('./objects').importFromLocator(localCard.path, peerCard.objects);
-      if (imported.state !== 'imported') {
-        return { state: 'waiting', reason: `objects-${imported.state}` };
-      }
-    } else if (peerCard.objects?.kind === 'pending') {
-      return { state: 'waiting', reason: 'objects-uploading' };
-    } else {
-      const approvedSource = localCard.repo.remote && localCard.repo.remote === peerCard.repo?.remote;
-      if (!approvedSource || !targetBranch) {
-        return { state: 'blocked', reason: 'missing-objects-no-approved-source' };
-      }
-      await transition.fetchBranch(localCard.path, 'origin', targetBranch);
-    }
-    if (!(await hasCommit(localCard.path, entry.baseOid))) {
-      return { state: 'blocked', reason: 'missing-objects-after-fetch' };
-    }
-  }
-  if (
-    current.head.branch === targetBranch
-    && !(await isAncestor(localCard.path, captured.baseOid, entry.baseOid))
-  ) {
-    return { state: 'diverged', reason: 'histories-diverged' };
-  }
-
-  // Fast-forward. Held peer content the peer has since committed is
-  // absorbed by the checkout (content-equal files simply become clean);
-  // unrelated local work rides along untouched. If git refuses because
-  // real local work overlaps the update, first unwind what we ourselves
-  // hold and retry next pass — our own applied content is always ours to
-  // remove, other work never is.
-  try {
-    await transition.moveToCard(localCard.path, {
-      expectedBranch: current.head.branch,
-      expectedOid: current.head.oid,
-      targetBranch,
-      targetOid: entry.baseOid,
-    });
-  } catch (error) {
-    const pairState = readPairState(digest);
-    if (pairState.holdsContent && pairState.baseOid === captured.baseOid && pairState.heldTree) {
-      const baseTree = await merge.treeOf(localCard.path, captured.baseOid);
-      saveRollback(digest, captured.diff);
-      const result = await merge.advance(localCard.path, pairState.heldTree, baseTree, { label: 'unwind-before-forward' });
-      writePairState(digest, {
-        heldTree: result.heldTree,
-        holdsContent: result.heldTree !== baseTree,
-        conflicts: result.conflicts,
-      });
-      return { state: 'restoring', reason: 'unwound-before-forward', moved: result.applied.length > 0 };
-    }
-    return { state: 'blocked', reason: 'local-work-overlaps-forward' };
-  }
-  writePairState(digest, {
-    peerMachine: entry.machine,
-    repoKey: entry.repoKey,
-    baseOid: entry.baseOid,
-    heldTree: null,
-    holdsContent: false,
-    peerRevision: null,
-    conflicts: [],
-    settledLocalRevision: null,
-  });
-  return {
-    state: current.head.branch === targetBranch ? 'forwarded' : 'switched',
-    reason: null,
-    moved: true,
-  };
-}
-
-// --- the sweep --------------------------------------------------------------
-
-async function runReconcile() {
-  service.counters.passes += 1;
-  const startedAt = Date.now();
-  const self = machineId();
-  let moved = false;
-
-  const locals = new Map();
-  for (const card of listRepoCards()) {
-    if (card.health !== 'healthy' || card.kind !== 'primary') continue;
-    const key = repoKeyOfCard(card);
-    if (key && !locals.has(key)) locals.set(key, card);
-  }
-
-  for (const wallEntry of readWall()) {
-    if (wallEntry.machine === self) continue;
-    for (const peerCard of wallEntry.cards || []) {
-      if (peerCard.kind !== 'primary' || (peerCard.health && peerCard.health !== 'healthy')) continue;
-      const repoKey = repoKeyOfCard(peerCard);
-      const localCard = repoKey && locals.get(repoKey);
-      if (!localCard) continue;
-      const currentLocalCard = await refreshRepoCard(localCard.replica) || localCard;
-
-      const digest = pairDigest(wallEntry.machine, repoKey);
-      const record = (outcome) => {
-        const completedAt = new Date().toISOString();
-        service.pairs.set(digest, {
-          peerMachine: wallEntry.machine,
-          repoKey,
-          path: currentLocalCard.path,
-          ...outcome,
-          timing: {
-            cardObservedAt: peerCard.observedAt || null,
-            cardPublishedAt: wallEntry.publishedAt || null,
-            cardReceivedAt: fileMtime(WALL_FILE),
-            checkpointCapturedAt: outcome.checkpointCapturedAt || null,
-            checkpointPublishedAt: outcome.checkpointPublishedAt || null,
-            checkpointReceivedAt: outcome.checkpointReceivedAt || null,
-            reconcileStartedAt: outcome.reconcileStartedAt || null,
-            completedAt,
-            reconcileDurationMs: outcome.reconcileStartedAt
-              ? Date.now() - Date.parse(outcome.reconcileStartedAt)
-              : null,
-          },
-          at: completedAt,
-        });
-      };
-      try {
-        const file = checkpointFile(wallEntry.machine, repoKey);
-        const binding = await ensureDocBound({
-          resourceId: checkpointResourceId(wallEntry.machine, repoKey),
-          filePath: file,
-          create: false,
-        });
-        service.watchedDocs.add(file);
-        if (!binding.bound) {
-          record({ state: 'waiting', reason: `checkpoint-${binding.state}` });
-          continue;
-        }
-        const entry = readCheckpoint(wallEntry.machine, repoKey);
-        const reconcileStartedAt = new Date().toISOString();
-        const outcome = await reconcilePair(currentLocalCard, peerCard, entry, digest);
-        if (outcome.moved) {
-          moved = true;
-          service.counters.movements += 1;
-        }
-        record({
-          ...outcome,
-          checkpointCapturedAt: entry?.capturedAt || null,
-          checkpointPublishedAt: entry?.publishedAt || null,
-          checkpointReceivedAt: fileMtime(file),
-          reconcileStartedAt,
-        });
-      } catch (error) {
-        service.counters.failures += 1;
-        record({ state: 'error', reason: error.message });
-        console.warn(`[WorkspaceReconcile] ${currentLocalCard.path}:`, error.message);
-      }
-    }
-  }
-
-  service.lastPass = { at: new Date().toISOString(), durationMs: Date.now() - startedAt, moved };
-  if (moved) {
-    // A movement changed real repo state: re-card promptly so our own
-    // published truth (and any follow-up movement) doesn't wait a cycle.
-    refreshRepoCards().catch(() => {});
-    scheduleReconcile();
-  }
-}
-
-let running = null;
-let queuedRun = null;
-
-function reconcileNow() {
-  if (running) {
-    queuedRun ??= running.catch(() => {}).then(() => reconcileNow());
-    return queuedRun;
-  }
-  queuedRun = null;
-  running = runReconcile().finally(() => {
-    running = null;
-  });
-  return running;
-}
-
-function scheduleReconcile() {
-  if (!service.started || service.reconcileTimer) return;
-  service.reconcileTimer = setTimeout(() => {
-    service.reconcileTimer = null;
-    reconcileNow().catch((error) => console.warn('[WorkspaceReconcile] reconcile failed:', error.message));
-  }, RECONCILE_QUIET_MS);
-  service.reconcileTimer.unref?.();
-}
-
-function startWorkspaceReconciler() {
-  if (service.started) return;
-  service.started = true;
-  service.unsubscribe = subscribeStateEvents((event) => {
-    const docChanged = typeof event.resource === 'string'
-      && event.resource.startsWith('doc:')
-      && service.watchedDocs.has(event.id);
-    if (docChanged || event.resource === 'repo-cards') scheduleReconcile();
-  });
-  service.intervalTimer = setInterval(scheduleReconcile, RECONCILE_INTERVAL_MS);
-  service.intervalTimer.unref?.();
-  scheduleReconcile();
-}
-
-function stopWorkspaceReconciler() {
-  if (!service.started) return;
-  service.started = false;
-  service.unsubscribe?.();
-  service.unsubscribe = null;
-  if (service.reconcileTimer) clearTimeout(service.reconcileTimer);
-  service.reconcileTimer = null;
-  if (service.intervalTimer) clearInterval(service.intervalTimer);
-  service.intervalTimer = null;
-}
-
-function reconciliationStats() {
-  return {
-    started: service.started,
-    ...service.counters,
-    lastPass: service.lastPass,
-    pairs: [...service.pairs.values()],
-  };
-}
-
-module.exports = {
-  compareCardFreshness,
-  reconciliationStats,
-  reconcileNow,
-  reconcilePair,
-  startWorkspaceReconciler,
-  stopWorkspaceReconciler,
-};