agentxchain 2.14.0 → 2.15.0

package/src/lib/coordinator-acceptance.js

@@ -17,6 +17,11 @@ import { readFileSync, writeFileSync, existsSync, mkdirSync, appendFileSync } fr
 import { isAbsolute, join, dirname, relative, resolve } from 'node:path';
 import { randomBytes } from 'node:crypto';
 import { readBarriers, readCoordinatorHistory, saveCoordinatorState } from './coordinator-state.js';
+import {
+  computeBarrierStatus as computeCoordinatorBarrierStatus,
+  getAcceptedReposForWorkstream,
+  getAlignedReposForBarrier,
+} from './coordinator-barriers.js';
 
 // ── Paths ───────────────────────────────────────────────────────────────────
 
@@ -238,100 +243,8 @@ export function recordBarrierTransition(workspacePath, barrierId, previousStatus
   });
 }
 
-// ── Internal barrier logic ──────────────────────────────────────────────────
-
-function getAcceptedReposForWorkstream(history, workstreamId, requiredRepos) {
-  const accepted = new Set();
-  for (const entry of history) {
-    if (entry?.type === 'acceptance_projection' && entry.workstream_id === workstreamId) {
-      if (requiredRepos.includes(entry.repo_id)) {
-        accepted.add(entry.repo_id);
-      }
-    }
-  }
-  return [...accepted];
-}
-
 function computeBarrierStatus(barrier, history, config) {
-  switch (barrier.type) {
-    case 'all_repos_accepted':
-      return computeAllReposAccepted(barrier, history);
-
-    case 'ordered_repo_sequence':
-      return computeOrderedRepoSequence(barrier, history, config);
-
-    case 'interface_alignment':
-      return computeInterfaceAlignment(barrier, history);
-
-    case 'shared_human_gate':
-      // Never auto-satisfied — requires explicit human approval
-      return barrier.status;
-
-    default:
-      return barrier.status;
-  }
-}
-
-function computeAllReposAccepted(barrier, history) {
-  const required = new Set(barrier.required_repos);
-  const satisfied = new Set();
-
-  for (const entry of history) {
-    if (entry?.type === 'acceptance_projection' && entry.workstream_id === barrier.workstream_id) {
-      if (required.has(entry.repo_id)) {
-        satisfied.add(entry.repo_id);
-      }
-    }
-  }
-
-  if (satisfied.size === required.size) return 'satisfied';
-  if (satisfied.size > 0) return 'partially_satisfied';
-  return 'pending';
-}
-
-function computeOrderedRepoSequence(barrier, history, config) {
-  const workstream = config.workstreams?.[barrier.workstream_id];
-  if (!workstream) return barrier.status;
-
-  // Upstream is entry_repo. The barrier is satisfied when entry_repo has an accepted turn.
-  const entryRepo = workstream.entry_repo;
-  const hasUpstreamAcceptance = history.some(
-    entry => entry?.type === 'acceptance_projection'
-      && entry.workstream_id === barrier.workstream_id
-      && entry.repo_id === entryRepo
-  );
-
-  if (hasUpstreamAcceptance) return 'satisfied';
-
-  // Check if any non-entry repos have been accepted (partial)
-  const anyDownstreamAccepted = history.some(
-    entry => entry?.type === 'acceptance_projection'
-      && entry.workstream_id === barrier.workstream_id
-      && entry.repo_id !== entryRepo
-  );
-
-  if (anyDownstreamAccepted) return 'partially_satisfied';
-  return 'pending';
-}
-
-function computeInterfaceAlignment(barrier, history) {
-  const required = new Set(barrier.required_repos);
-  const repoDecisions = {};
-
-  for (const entry of history) {
-    if (entry?.type === 'acceptance_projection' && entry.workstream_id === barrier.workstream_id) {
-      if (required.has(entry.repo_id)) {
-        repoDecisions[entry.repo_id] = entry.decisions ?? [];
-      }
-    }
-  }
-
-  const acceptedRepos = Object.keys(repoDecisions);
-  if (acceptedRepos.length === 0) return 'pending';
-  if (acceptedRepos.length < required.size) return 'partially_satisfied';
-
-  // All repos accepted — check for DEC-* alignment (heuristic)
-  return 'satisfied';
+  return computeCoordinatorBarrierStatus(barrier, history, config);
 }
 
 // ── Barrier effects from a single acceptance ────────────────────────────────
@@ -340,19 +253,32 @@ function evaluateBarrierEffects(workspacePath, state, config, repoId, workstream
   const barriers = readBarriers(workspacePath);
   const history = readCoordinatorHistory(workspacePath);
   const effects = [];
+  let snapshotChanged = false;
 
   for (const [barrierId, barrier] of Object.entries(barriers)) {
     if (barrier.status === 'satisfied') continue;
     if (barrier.workstream_id !== workstreamId) continue;
 
     const newStatus = computeBarrierStatus(barrier, history, config);
+    if (barrier.type === 'all_repos_accepted') {
+      const satisfiedRepos = getAcceptedReposForWorkstream(history, workstreamId, barrier.required_repos);
+      if (JSON.stringify(barrier.satisfied_repos || []) !== JSON.stringify(satisfiedRepos)) {
+        barrier.satisfied_repos = satisfiedRepos;
+        snapshotChanged = true;
+      }
+    }
+    if (barrier.type === 'interface_alignment') {
+      const satisfiedRepos = getAlignedReposForBarrier(barrier, history);
+      if (JSON.stringify(barrier.satisfied_repos || []) !== JSON.stringify(satisfiedRepos)) {
+        barrier.satisfied_repos = satisfiedRepos;
+        snapshotChanged = true;
+      }
+    }
+
     if (newStatus !== barrier.status) {
       const previousStatus = barrier.status;
       barrier.status = newStatus;
-
-      if (barrier.type === 'all_repos_accepted') {
-        barrier.satisfied_repos = getAcceptedReposForWorkstream(history, workstreamId, barrier.required_repos);
-      }
+      snapshotChanged = true;
 
       effects.push({
         barrier_id: barrierId,
@@ -370,7 +296,7 @@ function evaluateBarrierEffects(workspacePath, state, config, repoId, workstream
   }
 
   // Persist updated barrier snapshot
-  if (effects.length > 0) {
+  if (snapshotChanged) {
     writeFileSync(barriersPath(workspacePath), JSON.stringify(barriers, null, 2) + '\n');
   }
 

package/src/lib/coordinator-barriers.js

@@ -0,0 +1,116 @@
+function isProjectionEntry(entry, workstreamId) {
+  return entry?.type === 'acceptance_projection' && entry.workstream_id === workstreamId;
+}
+
+function normalizeDecisionId(decision) {
+  if (typeof decision === 'string') return decision;
+  if (decision && typeof decision === 'object' && typeof decision.id === 'string') return decision.id;
+  return null;
+}
+
+function collectAcceptedDecisionIds(history, workstreamId, requiredRepos = []) {
+  const required = new Set(requiredRepos);
+  const repoDecisionIds = {};
+  const acceptedRepos = new Set();
+
+  for (const entry of history) {
+    if (!isProjectionEntry(entry, workstreamId)) continue;
+    if (required.size > 0 && !required.has(entry.repo_id)) continue;
+
+    acceptedRepos.add(entry.repo_id);
+    if (!repoDecisionIds[entry.repo_id]) {
+      repoDecisionIds[entry.repo_id] = new Set();
+    }
+
+    for (const decision of Array.isArray(entry.decisions) ? entry.decisions : []) {
+      const id = normalizeDecisionId(decision);
+      if (id) {
+        repoDecisionIds[entry.repo_id].add(id);
+      }
+    }
+  }
+
+  return { acceptedRepos, repoDecisionIds };
+}
+
+export function getAcceptedReposForWorkstream(history, workstreamId, requiredRepos = []) {
+  return [
+    ...collectAcceptedDecisionIds(history, workstreamId, requiredRepos).acceptedRepos,
+  ];
+}
+
+export function getAlignedReposForBarrier(barrier, history) {
+  const requiredRepos = Array.isArray(barrier.required_repos) ? barrier.required_repos : [];
+  const alignmentDecisionIds = barrier.alignment_decision_ids || {};
+  const { repoDecisionIds } = collectAcceptedDecisionIds(history, barrier.workstream_id, requiredRepos);
+  const alignedRepos = [];
+
+  for (const repoId of requiredRepos) {
+    const requiredIds = Array.isArray(alignmentDecisionIds[repoId]) ? alignmentDecisionIds[repoId] : [];
+    if (requiredIds.length === 0) continue;
+
+    const acceptedIds = repoDecisionIds[repoId] || new Set();
+    if (requiredIds.every((decisionId) => acceptedIds.has(decisionId))) {
+      alignedRepos.push(repoId);
+    }
+  }
+
+  return alignedRepos;
+}
+
+export function computeAllReposAcceptedStatus(barrier, history) {
+  const requiredRepos = Array.isArray(barrier.required_repos) ? barrier.required_repos : [];
+  const acceptedRepos = getAcceptedReposForWorkstream(history, barrier.workstream_id, requiredRepos);
+
+  if (acceptedRepos.length === requiredRepos.length && requiredRepos.length > 0) return 'satisfied';
+  if (acceptedRepos.length > 0) return 'partially_satisfied';
+  return 'pending';
+}
+
+export function computeOrderedRepoSequenceStatus(barrier, history, config) {
+  const workstream = config.workstreams?.[barrier.workstream_id];
+  if (!workstream) return barrier.status;
+
+  const entryRepo = workstream.entry_repo;
+  const hasUpstreamAcceptance = history.some(
+    (entry) => isProjectionEntry(entry, barrier.workstream_id) && entry.repo_id === entryRepo,
+  );
+
+  if (hasUpstreamAcceptance) return 'satisfied';
+
+  const anyDownstreamAccepted = history.some(
+    (entry) => isProjectionEntry(entry, barrier.workstream_id) && entry.repo_id !== entryRepo,
+  );
+
+  if (anyDownstreamAccepted) return 'partially_satisfied';
+  return 'pending';
+}
+
+export function computeInterfaceAlignmentStatus(barrier, history) {
+  const requiredRepos = Array.isArray(barrier.required_repos) ? barrier.required_repos : [];
+  const alignedRepos = getAlignedReposForBarrier(barrier, history);
+  const acceptedRepos = getAcceptedReposForWorkstream(history, barrier.workstream_id, requiredRepos);
+
+  if (alignedRepos.length === requiredRepos.length && requiredRepos.length > 0) return 'satisfied';
+  if (acceptedRepos.length > 0) return 'partially_satisfied';
+  return 'pending';
+}
+
+export function computeBarrierStatus(barrier, history, config) {
+  switch (barrier.type) {
+    case 'all_repos_accepted':
+      return computeAllReposAcceptedStatus(barrier, history);
+
+    case 'ordered_repo_sequence':
+      return computeOrderedRepoSequenceStatus(barrier, history, config);
+
+    case 'interface_alignment':
+      return computeInterfaceAlignmentStatus(barrier, history);
+
+    case 'shared_human_gate':
+      return barrier.status;
+
+    default:
+      return barrier.status;
+  }
+}

package/src/lib/coordinator-config.js

@@ -146,12 +146,95 @@ function validateWorkstreams(raw, repoIds, errors) {
         `workstream "${workstreamId}" completion_barrier must be one of: ${Array.from(VALID_BARRIER_TYPES).join(', ')}`,
       );
     }
+
+    validateInterfaceAlignment(workstreamId, workstream, errors);
   }
 
   detectWorkstreamCycles(raw.workstreams, errors);
   return workstreamIds;
 }
 
+function validateInterfaceAlignment(workstreamId, workstream, errors) {
+  if (workstream.completion_barrier !== 'interface_alignment') {
+    return;
+  }
+
+  const alignment = workstream.interface_alignment;
+  if (!alignment || typeof alignment !== 'object' || Array.isArray(alignment)) {
+    pushError(
+      errors,
+      'workstream_interface_alignment_invalid',
+      `workstream "${workstreamId}" with completion_barrier "interface_alignment" must declare interface_alignment.decision_ids_by_repo`,
+    );
+    return;
+  }
+
+  const byRepo = alignment.decision_ids_by_repo;
+  if (!byRepo || typeof byRepo !== 'object' || Array.isArray(byRepo)) {
+    pushError(
+      errors,
+      'workstream_interface_alignment_decisions_invalid',
+      `workstream "${workstreamId}" interface_alignment.decision_ids_by_repo must be an object`,
+    );
+    return;
+  }
+
+  const repoIds = Array.isArray(workstream.repos) ? workstream.repos : [];
+  const repoIdSet = new Set(repoIds);
+
+  for (const repoId of repoIds) {
+    if (!(repoId in byRepo)) {
+      pushError(
+        errors,
+        'workstream_interface_alignment_repo_missing',
+        `workstream "${workstreamId}" must declare interface_alignment.decision_ids_by_repo["${repoId}"]`,
+      );
+      continue;
+    }
+
+    const decisionIds = byRepo[repoId];
+    if (!Array.isArray(decisionIds) || decisionIds.length === 0) {
+      pushError(
+        errors,
+        'workstream_interface_alignment_repo_invalid',
+        `workstream "${workstreamId}" interface_alignment.decision_ids_by_repo["${repoId}"] must be a non-empty array`,
+      );
+      continue;
+    }
+
+    const seen = new Set();
+    for (const decisionId of decisionIds) {
+      if (typeof decisionId !== 'string' || !/^DEC-\d+$/.test(decisionId)) {
+        pushError(
+          errors,
+          'workstream_interface_alignment_decision_invalid',
+          `workstream "${workstreamId}" interface_alignment decision "${decisionId}" for repo "${repoId}" must match DEC-NNN`,
+        );
+        continue;
+      }
+      if (seen.has(decisionId)) {
+        pushError(
+          errors,
+          'workstream_interface_alignment_decision_duplicate',
+          `workstream "${workstreamId}" interface_alignment decision "${decisionId}" is duplicated for repo "${repoId}"`,
+        );
+        continue;
+      }
+      seen.add(decisionId);
+    }
+  }
+
+  for (const repoId of Object.keys(byRepo)) {
+    if (!repoIdSet.has(repoId)) {
+      pushError(
+        errors,
+        'workstream_interface_alignment_repo_unknown',
+        `workstream "${workstreamId}" interface_alignment references undeclared repo "${repoId}"`,
+      );
+    }
+  }
+}
+
 function detectWorkstreamCycles(workstreams, errors) {
   const visiting = new Set();
   const visited = new Set();
@@ -344,6 +427,16 @@ export function normalizeCoordinatorConfig(raw) {
           entry_repo: workstream.entry_repo,
           depends_on: Array.isArray(workstream.depends_on) ? [...new Set(workstream.depends_on)] : [],
           completion_barrier: workstream.completion_barrier,
+          interface_alignment: workstream.interface_alignment?.decision_ids_by_repo
+            ? {
+                decision_ids_by_repo: Object.fromEntries(
+                  Object.entries(workstream.interface_alignment.decision_ids_by_repo).map(([repoId, decisionIds]) => [
+                    repoId,
+                    Array.isArray(decisionIds) ? [...new Set(decisionIds)] : [],
+                  ]),
+                ),
+              }
+            : null,
         },
       ]),
     ),

package/src/lib/coordinator-recovery.js

@@ -21,6 +21,11 @@ import {
   readBarriers,
 } from './coordinator-state.js';
 import { safeWriteJson } from './safe-write.js';
+import {
+  computeBarrierStatus as computeCoordinatorBarrierStatus,
+  getAcceptedReposForWorkstream,
+  getAlignedReposForBarrier,
+} from './coordinator-barriers.js';
 
 // ── Paths ───────────────────────────────────────────────────────────────────
 
@@ -335,6 +340,23 @@ export function resyncFromRepoAuthority(workspacePath, state, config) {
     if (barrier.type === 'shared_human_gate') continue; // Never auto-transition
 
     const newStatus = recomputeBarrierStatus(barrier, fullHistory, config);
+    if (barrier.type === 'all_repos_accepted') {
+      const satisfiedRepos = getAcceptedReposForWorkstream(
+        fullHistory, barrier.workstream_id, barrier.required_repos
+      );
+      if (JSON.stringify(barrier.satisfied_repos || []) !== JSON.stringify(satisfiedRepos)) {
+        barrier.satisfied_repos = satisfiedRepos;
+        barriersChanged = true;
+      }
+    }
+    if (barrier.type === 'interface_alignment') {
+      const satisfiedRepos = getAlignedReposForBarrier(barrier, fullHistory);
+      if (JSON.stringify(barrier.satisfied_repos || []) !== JSON.stringify(satisfiedRepos)) {
+        barrier.satisfied_repos = satisfiedRepos;
+        barriersChanged = true;
+      }
+    }
+
     if (newStatus !== barrier.status) {
       const previousStatus = barrier.status;
       barrierChanges.push({
@@ -347,13 +369,6 @@ export function resyncFromRepoAuthority(workspacePath, state, config) {
 
       barrier.status = newStatus;
 
-      // Update satisfied_repos for tracking
-      if (barrier.type === 'all_repos_accepted') {
-        barrier.satisfied_repos = getAcceptedReposForWorkstream(
-          fullHistory, barrier.workstream_id, barrier.required_repos
-        );
-      }
-
       barriersChanged = true;
 
       appendJsonl(barrierLedgerPath(workspacePath), {
@@ -421,75 +436,115 @@ export function resyncFromRepoAuthority(workspacePath, state, config) {
   };
 }
 
-// ── Internal helpers ────────────────────────────────────────────────────────
+/**
+ * Clear a coordinator blocked state after the operator resolves the cause.
+ *
+ * Recovery always begins with repo-authority resync, then restores the
+ * coordinator to `active` or `paused` based on whether a pending gate still
+ * exists. It never mutates repo-local governed state.
+ *
+ * @param {string} workspacePath
+ * @param {object} state
+ * @param {object} config
+ * @returns {{ ok: boolean, state?: object, resumed_status?: string, blocked_reason?: string, blocked_repos?: string[], resync?: object, error?: string }}
+ */
+export function resumeCoordinatorFromBlockedState(workspacePath, state, config) {
+  if (!state || state.status !== 'blocked') {
+    return {
+      ok: false,
+      error: `Cannot resume coordinator: status is "${state?.status || 'missing'}", expected "blocked"`,
+    };
+  }
 
-function getAcceptedReposForWorkstream(history, workstreamId, requiredRepos) {
-  const accepted = new Set();
-  for (const entry of history) {
-    if (entry?.type === 'acceptance_projection' && entry.workstream_id === workstreamId) {
-      if (requiredRepos.includes(entry.repo_id)) {
-        accepted.add(entry.repo_id);
-      }
-    }
+  const previousBlockedReason = state.blocked_reason || 'unknown blocked reason';
+  const expectedSuperRunId = state.super_run_id;
+  const resync = resyncFromRepoAuthority(workspacePath, state, config);
+  const refreshedState = loadCoordinatorState(workspacePath);
+
+  if (!refreshedState) {
+    return {
+      ok: false,
+      error: 'Coordinator state could not be reloaded after resync',
+      blocked_reason: previousBlockedReason,
+      resync,
+    };
   }
-  return [...accepted];
-}
 
-function recomputeBarrierStatus(barrier, history, config) {
-  switch (barrier.type) {
-    case 'all_repos_accepted': {
-      const required = new Set(barrier.required_repos);
-      const satisfied = new Set();
-      for (const entry of history) {
-        if (entry?.type === 'acceptance_projection' && entry.workstream_id === barrier.workstream_id) {
-          if (required.has(entry.repo_id)) {
-            satisfied.add(entry.repo_id);
-          }
-        }
-      }
-      if (satisfied.size === required.size) return 'satisfied';
-      if (satisfied.size > 0) return 'partially_satisfied';
-      return 'pending';
-    }
+  if (refreshedState.super_run_id !== expectedSuperRunId) {
+    return {
+      ok: false,
+      error: `Cannot resume coordinator: super_run_id changed from "${expectedSuperRunId}" to "${refreshedState.super_run_id}"`,
+      blocked_reason: previousBlockedReason,
+      resync,
+    };
+  }
 
-    case 'ordered_repo_sequence': {
-      const workstream = config.workstreams?.[barrier.workstream_id];
-      if (!workstream) return barrier.status;
-      const entryRepo = workstream.entry_repo;
-      const hasUpstream = history.some(
-        e => e?.type === 'acceptance_projection'
-          && e.workstream_id === barrier.workstream_id
-          && e.repo_id === entryRepo
-      );
-      if (hasUpstream) return 'satisfied';
-      const anyDownstream = history.some(
-        e => e?.type === 'acceptance_projection'
-          && e.workstream_id === barrier.workstream_id
-          && e.repo_id !== entryRepo
-      );
-      if (anyDownstream) return 'partially_satisfied';
-      return 'pending';
-    }
+  if (!resync.ok) {
+    return {
+      ok: false,
+      error: `Coordinator remains blocked: ${resync.blocked_reason || refreshedState.blocked_reason || previousBlockedReason}`,
+      blocked_reason: resync.blocked_reason || refreshedState.blocked_reason || previousBlockedReason,
+      resync,
+      state: refreshedState,
+    };
+  }
+
+  const blockedRepos = Object.entries(refreshedState.repo_runs || {})
+    .filter(([, repoRun]) => repoRun?.status === 'blocked')
+    .map(([repoId]) => repoId);
+
+  if (blockedRepos.length > 0) {
+    const blockedReason = `child repos remain blocked: ${blockedRepos.join(', ')}`;
+    const blockedState = {
+      ...refreshedState,
+      status: 'blocked',
+      blocked_reason: blockedReason,
+    };
+    saveCoordinatorState(workspacePath, blockedState);
+    return {
+      ok: false,
+      error: `Cannot resume coordinator: ${blockedReason}`,
+      blocked_reason: blockedReason,
+      blocked_repos: blockedRepos,
+      resync,
+      state: blockedState,
+    };
+  }
+
+  const resumedStatus = refreshedState.pending_gate ? 'paused' : 'active';
+  const resumedState = {
+    ...refreshedState,
+    status: resumedStatus,
+  };
+  delete resumedState.blocked_reason;
 
-    case 'interface_alignment': {
-      const required = new Set(barrier.required_repos);
-      const acceptedRepos = new Set();
-      for (const entry of history) {
-        if (entry?.type === 'acceptance_projection' && entry.workstream_id === barrier.workstream_id) {
-          if (required.has(entry.repo_id)) acceptedRepos.add(entry.repo_id);
-        }
+  saveCoordinatorState(workspacePath, resumedState);
+  appendJsonl(historyPath(workspacePath), {
+    type: 'blocked_resolved',
+    timestamp: new Date().toISOString(),
+    super_run_id: refreshedState.super_run_id,
+    from: 'blocked',
+    to: resumedStatus,
+    blocked_reason: previousBlockedReason,
+    pending_gate: refreshedState.pending_gate
+      ? {
+        gate: refreshedState.pending_gate.gate,
+        gate_type: refreshedState.pending_gate.gate_type,
       }
-      if (acceptedRepos.size === 0) return 'pending';
-      if (acceptedRepos.size < required.size) return 'partially_satisfied';
-      return 'satisfied';
-    }
+      : null,
+  });
 
-    case 'shared_human_gate':
-      return barrier.status; // Never auto-transition
+  return {
+    ok: true,
+    state: resumedState,
+    resumed_status: resumedStatus,
+    blocked_reason: previousBlockedReason,
+    resync,
+  };
+}
 
-    default:
-      return barrier.status;
-  }
+function recomputeBarrierStatus(barrier, history, config) {
+  return computeCoordinatorBarrierStatus(barrier, history, config);
 }
 
 /**

package/src/lib/coordinator-state.js

@@ -97,6 +97,7 @@ function bootstrapBarriers(config) {
       status: 'pending',
       required_repos: [...workstream.repos],
       satisfied_repos: [],
+      alignment_decision_ids: workstream.interface_alignment?.decision_ids_by_repo || null,
       created_at: new Date().toISOString(),
     };
   }