agentxchain 2.96.1 → 2.98.0

package/bin/agentxchain.js

@@ -345,9 +345,10 @@ program
   .action(decisionsCommand);
 
 program
-  .command('diff <left_run_id> <right_run_id>')
-  .description('Compare two recorded governed runs from run-history')
+  .command('diff <left_ref> <right_ref>')
+  .description('Compare two recorded governed runs or two export artifacts')
   .option('-j, --json', 'Output as JSON')
+  .option('--export', 'Compare two export artifacts instead of run-history entries')
   .option('-d, --dir <path>', 'Project directory')
   .action(diffCommand);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentxchain",
-  "version": "2.96.1",
+  "version": "2.98.0",
   "description": "CLI for AgentXchain — governed multi-agent software delivery",
   "type": "module",
   "bin": {

package/src/commands/diff.js

@@ -1,9 +1,41 @@
 import chalk from 'chalk';
 
 import { findProjectRoot } from '../lib/config.js';
+import { buildExportDiff, resolveExportArtifact } from '../lib/export-diff.js';
 import { buildRunDiff, resolveRunHistoryReference } from '../lib/run-diff.js';
 
 export async function diffCommand(leftRef, rightRef, opts) {
+  if (opts.export) {
+    const leftExport = resolveExportArtifact(leftRef);
+    if (!leftExport.ok) {
+      console.error(chalk.red(leftExport.error));
+      process.exit(1);
+    }
+
+    const rightExport = resolveExportArtifact(rightRef);
+    if (!rightExport.ok) {
+      console.error(chalk.red(rightExport.error));
+      process.exit(1);
+    }
+
+    const exportDiff = buildExportDiff(leftExport.artifact, rightExport.artifact, {
+      left_ref: leftExport.resolved_ref,
+      right_ref: rightExport.resolved_ref,
+    });
+    if (!exportDiff.ok) {
+      console.error(chalk.red(exportDiff.error));
+      process.exit(1);
+    }
+
+    if (opts.json) {
+      console.log(JSON.stringify(exportDiff.diff, null, 2));
+      return;
+    }
+
+    console.log(formatExportDiffText(exportDiff.diff));
+    return;
+  }
+
   const root = findProjectRoot(opts.dir || process.cwd());
   if (!root) {
     console.error(chalk.red('No AgentXchain project found. Run this inside a governed project.'));
@@ -53,16 +85,7 @@ function formatRunDiffText(diff) {
 
   appendChangedSection(lines, 'List changes', Object.values(diff.list_changes)
     .filter((entry) => entry.changed)
-    .flatMap((entry) => {
-      const items = [];
-      if (entry.added.length > 0) {
-        items.push(`${entry.label} added: ${entry.added.join(', ')}`);
-      }
-      if (entry.removed.length > 0) {
-        items.push(`${entry.label} removed: ${entry.removed.join(', ')}`);
-      }
-      return items;
-    }));
+    .flatMap((entry) => listChangeItems(entry)));
 
   appendChangedSection(lines, 'Gate changes', diff.gate_changes
     .filter((entry) => entry.changed)
@@ -71,6 +94,47 @@ function formatRunDiffText(diff) {
   return lines.join('\n');
 }
 
+function formatExportDiffText(diff) {
+  const lines = [];
+  lines.push(chalk.bold('Export Diff'));
+  lines.push(`${chalk.dim('Left:')}  ${formatExportHeader(diff.left_ref, diff.left)}`);
+  lines.push(`${chalk.dim('Right:')} ${formatExportHeader(diff.right_ref, diff.right)}`);
+
+  if (!diff.changed) {
+    lines.push('');
+    lines.push(chalk.green('No differences.'));
+    return lines.join('\n');
+  }
+
+  appendChangedSection(lines, 'Changed fields', Object.values(diff.scalar_changes)
+    .filter((entry) => entry.changed)
+    .map((entry) => `${entry.label}: ${formatValue(entry.left, entry.label)} -> ${formatValue(entry.right, entry.label)}`));
+
+  appendChangedSection(lines, 'Numeric deltas', Object.values(diff.numeric_changes)
+    .filter((entry) => entry.changed)
+    .map((entry) => `${entry.label}: ${formatValue(entry.left, entry.label)} -> ${formatValue(entry.right, entry.label)}${formatDelta(entry.delta, entry.label)}`));
+
+  appendChangedSection(lines, 'List changes', Object.values(diff.list_changes)
+    .filter((entry) => entry.changed)
+    .flatMap((entry) => listChangeItems(entry)));
+
+  if (diff.subject_kind === 'coordinator') {
+    appendChangedSection(lines, 'Repo status changes', diff.repo_status_changes
+      .filter((entry) => entry.changed)
+      .map((entry) => `${entry.key}: ${formatValue(entry.left)} -> ${formatValue(entry.right)}`));
+
+    appendChangedSection(lines, 'Repo export changes', diff.repo_export_changes
+      .filter((entry) => entry.changed)
+      .map((entry) => `${entry.key}: ${formatValue(entry.left)} -> ${formatValue(entry.right)}`));
+
+    appendChangedSection(lines, 'Event type deltas', diff.event_type_changes
+      .filter((entry) => entry.changed)
+      .map((entry) => `${entry.key}: ${formatValue(entry.left)} -> ${formatValue(entry.right)}${formatDelta(entry.delta, entry.label)}`));
+  }
+
+  return lines.join('\n');
+}
+
 function appendChangedSection(lines, heading, items) {
   if (items.length === 0) return;
   lines.push('');
@@ -80,6 +144,17 @@ function appendChangedSection(lines, heading, items) {
   }
 }
 
+function listChangeItems(entry) {
+  const items = [];
+  if (entry.added.length > 0) {
+    items.push(`${entry.label} added: ${entry.added.join(', ')}`);
+  }
+  if (entry.removed.length > 0) {
+    items.push(`${entry.label} removed: ${entry.removed.join(', ')}`);
+  }
+  return items;
+}
+
 function formatRunHeader(entry) {
   const status = entry.status || '—';
   const trigger = entry.trigger || 'legacy';
@@ -89,6 +164,15 @@ function formatRunHeader(entry) {
   return `${entry.run_id} (${status}, ${trigger}, ${recordedAt})`;
 }
 
+function formatExportHeader(ref, entry) {
+  const exportKind = entry.export_kind === 'agentxchain_coordinator_export'
+    ? 'coordinator export'
+    : 'run export';
+  const status = entry.status || '—';
+  const identity = entry.run_id || entry.super_run_id || 'unknown run';
+  return `${ref} (${exportKind}, ${status}, ${identity})`;
+}
+
 function formatValue(value, label = '') {
   if (value == null) return '—';
   if (typeof value === 'boolean') return value ? 'yes' : 'no';

package/src/commands/replay-export.js

@@ -17,6 +17,190 @@ import { createBridgeServer } from '../lib/dashboard/bridge-server.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
+function restoreExportFiles(root, files, scopeLabel) {
+  if (!files || typeof files !== 'object') {
+    throw new Error(`${scopeLabel} is missing a valid files object.`);
+  }
+
+  let restored = 0;
+  for (const [relPath, entry] of Object.entries(files)) {
+    const absPath = join(root, relPath);
+    mkdirSync(dirname(absPath), { recursive: true });
+
+    if (typeof entry === 'string') {
+      writeFileSync(absPath, entry);
+      restored++;
+      continue;
+    }
+
+    if (!entry || typeof entry !== 'object' || typeof entry.content_base64 !== 'string') {
+      throw new Error(`${scopeLabel} entry "${relPath}" must provide content_base64.`);
+    }
+
+    writeFileSync(absPath, Buffer.from(entry.content_base64, 'base64'));
+    restored++;
+  }
+
+  return restored;
+}
+
+function restoreCoordinatorRepos(tempRoot, repos) {
+  if (!repos || typeof repos !== 'object') {
+    return 0;
+  }
+
+  let restored = 0;
+  for (const [repoId, repoEntry] of Object.entries(repos)) {
+    if (!repoEntry || repoEntry.ok === false) {
+      continue;
+    }
+
+    if (typeof repoEntry.path !== 'string' || !repoEntry.path.trim()) {
+      throw new Error(`Coordinator repo "${repoId}" is marked ok but has no path.`);
+    }
+
+    const nestedFiles = repoEntry.export?.files;
+    if (!nestedFiles || typeof nestedFiles !== 'object') {
+      throw new Error(`Coordinator repo "${repoId}" is marked ok but has no nested export.files.`);
+    }
+
+    const repoRoot = join(tempRoot, repoEntry.path);
+    mkdirSync(repoRoot, { recursive: true });
+    restored += restoreExportFiles(repoRoot, nestedFiles, `repos.${repoId}.export.files`);
+  }
+
+  return restored;
+}
+
+function readEmbeddedJsonEntry(entry, label) {
+  if (!entry || typeof entry !== 'object') {
+    throw new Error(`${label} is not a valid export file entry.`);
+  }
+
+  if (entry.data && typeof entry.data === 'object') {
+    return entry.data;
+  }
+
+  if (typeof entry.content_base64 !== 'string' || !entry.content_base64) {
+    throw new Error(`${label} must provide content_base64.`);
+  }
+
+  try {
+    return JSON.parse(Buffer.from(entry.content_base64, 'base64').toString('utf8'));
+  } catch (err) {
+    throw new Error(`${label} contains invalid JSON: ${err.message}`);
+  }
+}
+
+function getCoordinatorReplayPhases(exportData) {
+  const coordinatorConfig = exportData?.config
+    || readEmbeddedJsonEntry(exportData?.files?.['agentxchain-multi.json'], 'files["agentxchain-multi.json"]');
+  const routingPhases = Object.keys(coordinatorConfig?.routing || {});
+  if (routingPhases.length > 0) {
+    return routingPhases;
+  }
+
+  const phases = [];
+  for (const workstreamId of Object.keys(coordinatorConfig?.workstreams || {})) {
+    const phase = coordinatorConfig.workstreams?.[workstreamId]?.phase;
+    if (phase && !phases.includes(phase)) {
+      phases.push(phase);
+    }
+  }
+
+  return phases.length > 0 ? phases : ['planning'];
+}
+
+function restoreFailedCoordinatorRepoStubs(tempRoot, exportData) {
+  if (!exportData?.repos || typeof exportData.repos !== 'object') {
+    return 0;
+  }
+
+  const phases = getCoordinatorReplayPhases(exportData);
+  const coordinatorState = exportData?.files?.['.agentxchain/multirepo/state.json']
+    ? readEmbeddedJsonEntry(exportData.files['.agentxchain/multirepo/state.json'], 'files[".agentxchain/multirepo/state.json"]')
+    : null;
+
+  let restored = 0;
+  for (const [repoId, repoEntry] of Object.entries(exportData.repos)) {
+    if (!repoEntry || repoEntry.ok !== false) {
+      continue;
+    }
+
+    if (typeof repoEntry.path !== 'string' || !repoEntry.path.trim()) {
+      throw new Error(`Coordinator repo "${repoId}" failed export but has no path.`);
+    }
+
+    const repoRoot = join(tempRoot, repoEntry.path);
+    const promptPath = '.agentxchain/prompts/replay.md';
+    const repoRun = coordinatorState?.repo_runs?.[repoId] || {};
+    const defaultPhase = repoRun.phase || phases[0] || 'planning';
+    const routing = Object.fromEntries(
+      phases.map((phase) => [
+        phase,
+        {
+          entry_role: 'replay',
+          allowed_next_roles: ['replay', 'human'],
+        },
+      ]),
+    );
+    const config = {
+      schema_version: '1.0',
+      template: 'generic',
+      project: {
+        id: `${repoId}-replay-placeholder`,
+        name: `${repoId} Replay Placeholder`,
+      },
+      roles: {
+        replay: {
+          title: 'Replay Placeholder',
+          mandate: 'Preserve coordinator replay continuity when nested repo export is unavailable.',
+          write_authority: 'review_only',
+          runtime: 'replay-placeholder',
+        },
+      },
+      runtimes: {
+        'replay-placeholder': { type: 'manual' },
+      },
+      routing,
+      gates: {},
+      prompts: {
+        replay: promptPath,
+      },
+      rules: {
+        challenge_required: true,
+        max_turn_retries: 2,
+        max_deadlock_cycles: 2,
+      },
+    };
+    const state = {
+      schema_version: '1.1',
+      run_id: repoRun.run_id || null,
+      status: repoRun.status || 'blocked',
+      phase: defaultPhase,
+      active_turns: {},
+      turn_sequence: 0,
+      retained_turns: {},
+      budget_reservations: {},
+      phase_gate_status: {},
+    };
+
+    mkdirSync(join(repoRoot, '.agentxchain', 'prompts'), { recursive: true });
+    writeFileSync(join(repoRoot, 'agentxchain.json'), `${JSON.stringify(config, null, 2)}\n`);
+    writeFileSync(join(repoRoot, '.agentxchain', 'state.json'), `${JSON.stringify(state, null, 2)}\n`);
+    writeFileSync(join(repoRoot, '.agentxchain', 'history.jsonl'), '');
+    writeFileSync(join(repoRoot, '.agentxchain', 'events.jsonl'), '');
+    writeFileSync(join(repoRoot, '.agentxchain', 'decision-ledger.jsonl'), '');
+    writeFileSync(
+      join(repoRoot, promptPath),
+      '# Replay Placeholder\n\nThis repo export was unavailable in the coordinator artifact. Replay restores a placeholder so coordinator dashboards remain readable.\n',
+    );
+    restored += 6;
+  }
+
+  return restored;
+}
+
 export async function replayExportCommand(exportFile, opts = {}) {
   if (!exportFile) {
     console.error(chalk.red('Usage: agentxchain replay export <export-file>'));
@@ -51,21 +235,22 @@ export async function replayExportCommand(exportFile, opts = {}) {
     mkdirSync(tempRoot, { recursive: true });
     mkdirSync(tempAgentxchainDir, { recursive: true });
 
-    // Write all embedded files from the export
-    let fileCount = 0;
-    for (const [relPath, content] of Object.entries(exportData.files)) {
-      const absPath = join(tempRoot, relPath);
-      mkdirSync(dirname(absPath), { recursive: true });
-      writeFileSync(absPath, typeof content === 'string' ? content : JSON.stringify(content, null, 2));
-      fileCount++;
+    // Restore the real exported bytes for top-level files.
+    let fileCount = restoreExportFiles(tempRoot, exportData.files, 'files');
+
+    // Coordinator exports also need successful nested child repo exports
+    // rehydrated under their declared repo paths for dashboard replay.
+    if (exportData.export_kind === 'agentxchain_coordinator_export') {
+      fileCount += restoreCoordinatorRepos(tempRoot, exportData.repos);
+      fileCount += restoreFailedCoordinatorRepoStubs(tempRoot, exportData);
     }
 
     // Ensure agentxchain.json exists (needed by some dashboard endpoints)
     const configPath = join(tempRoot, 'agentxchain.json');
-    if (!existsSync(configPath)) {
+    if (exportData.export_kind !== 'agentxchain_coordinator_export' && !existsSync(configPath)) {
       // Synthesize a minimal config from export summary
       const minimalConfig = {
-        protocol_version: exportData.summary?.protocol_version || 6,
+        protocol_version: exportData.summary?.protocol_version || null,
         protocol_mode: 'governed',
         version: 4,
         project: { name: exportData.summary?.project_name || 'replay-export' },
@@ -153,6 +338,10 @@ export async function replayExportCommand(exportFile, opts = {}) {
       console.error(chalk.red(`Port ${opts.port || 3847} is already in use. Try --port <number>.`));
       process.exit(1);
     }
+    if (err instanceof Error) {
+      console.error(chalk.red(err.message));
+      process.exit(2);
+    }
     throw err;
   }
 }

package/src/lib/export-diff.js

@@ -0,0 +1,347 @@
+import { existsSync, readFileSync } from 'fs';
+import { resolve } from 'path';
+
+const RUN_EXPORT_SCALAR_FIELDS = [
+  ['run_id', 'Run ID'],
+  ['status', 'Status'],
+  ['phase', 'Phase'],
+  ['project_name', 'Project'],
+  ['project_goal', 'Goal'],
+  ['provenance_trigger', 'Trigger'],
+  ['dashboard_status', 'Dashboard'],
+];
+
+const RUN_EXPORT_NUMERIC_FIELDS = [
+  ['history_entries', 'History entries'],
+  ['decision_entries', 'Decision entries'],
+  ['hook_audit_entries', 'Hook audit entries'],
+  ['notification_audit_entries', 'Notification audit entries'],
+  ['dispatch_artifact_files', 'Dispatch artifacts'],
+  ['staging_artifact_files', 'Staging artifacts'],
+  ['total_delegations_issued', 'Delegations'],
+  ['active_repo_decision_count', 'Active repo decisions'],
+  ['overridden_repo_decision_count', 'Overridden repo decisions'],
+];
+
+const COORDINATOR_EXPORT_SCALAR_FIELDS = [
+  ['super_run_id', 'Super run ID'],
+  ['status', 'Status'],
+  ['phase', 'Phase'],
+  ['project_name', 'Project'],
+];
+
+const COORDINATOR_EXPORT_NUMERIC_FIELDS = [
+  ['barrier_count', 'Barriers'],
+  ['history_entries', 'History entries'],
+  ['decision_entries', 'Decision entries'],
+  ['total_events', 'Aggregated events'],
+];
+
+export function resolveExportArtifact(ref) {
+  const exportPath = resolve(ref);
+  if (!existsSync(exportPath)) {
+    return {
+      ok: false,
+      error: `Export file not found: ${exportPath}`,
+    };
+  }
+
+  let artifact;
+  try {
+    artifact = JSON.parse(readFileSync(exportPath, 'utf8'));
+  } catch (error) {
+    return {
+      ok: false,
+      error: `Failed to parse export file ${exportPath}: ${error.message}`,
+    };
+  }
+
+  if (!artifact || typeof artifact !== 'object' || Array.isArray(artifact)) {
+    return {
+      ok: false,
+      error: `Export file ${exportPath} must contain a JSON object.`,
+    };
+  }
+
+  if (typeof artifact.export_kind !== 'string' || !artifact.export_kind.trim()) {
+    return {
+      ok: false,
+      error: `Export file ${exportPath} is missing export_kind.`,
+    };
+  }
+
+  return {
+    ok: true,
+    artifact,
+    resolved_ref: exportPath,
+  };
+}
+
+export function buildExportDiff(leftArtifact, rightArtifact, refs = {}) {
+  if (leftArtifact.export_kind !== rightArtifact.export_kind) {
+    return {
+      ok: false,
+      error: `Export kinds do not match: ${leftArtifact.export_kind} vs ${rightArtifact.export_kind}`,
+    };
+  }
+
+  if (leftArtifact.export_kind === 'agentxchain_run_export') {
+    return {
+      ok: true,
+      diff: buildRunExportDiff(leftArtifact, rightArtifact, refs),
+    };
+  }
+
+  if (leftArtifact.export_kind === 'agentxchain_coordinator_export') {
+    return {
+      ok: true,
+      diff: buildCoordinatorExportDiff(leftArtifact, rightArtifact, refs),
+    };
+  }
+
+  return {
+    ok: false,
+    error: `Unsupported export kind for diff: ${leftArtifact.export_kind}`,
+  };
+}
+
+function buildRunExportDiff(leftArtifact, rightArtifact, refs) {
+  const left = normalizeRunExport(leftArtifact);
+  const right = normalizeRunExport(rightArtifact);
+
+  const scalar_changes = buildFieldChanges(left, right, RUN_EXPORT_SCALAR_FIELDS);
+  const numeric_changes = buildNumericChanges(left, right, RUN_EXPORT_NUMERIC_FIELDS);
+  const list_changes = {
+    active_turn_ids: buildListChange('Active turns', left.active_turn_ids, right.active_turn_ids),
+    retained_turn_ids: buildListChange('Retained turns', left.retained_turn_ids, right.retained_turn_ids),
+    active_repo_decision_ids: buildListChange('Active repo decisions', left.active_repo_decision_ids, right.active_repo_decision_ids),
+    overridden_repo_decision_ids: buildListChange('Overridden repo decisions', left.overridden_repo_decision_ids, right.overridden_repo_decision_ids),
+  };
+
+  const changed = hasChanged(scalar_changes, numeric_changes, list_changes);
+
+  return {
+    comparison_mode: 'export',
+    subject_kind: 'run',
+    export_kind: leftArtifact.export_kind,
+    left_ref: refs.left_ref || null,
+    right_ref: refs.right_ref || null,
+    changed,
+    left,
+    right,
+    scalar_changes,
+    numeric_changes,
+    list_changes,
+  };
+}
+
+function buildCoordinatorExportDiff(leftArtifact, rightArtifact, refs) {
+  const left = normalizeCoordinatorExport(leftArtifact);
+  const right = normalizeCoordinatorExport(rightArtifact);
+
+  const scalar_changes = buildFieldChanges(left, right, COORDINATOR_EXPORT_SCALAR_FIELDS);
+  const numeric_changes = buildNumericChanges(left, right, COORDINATOR_EXPORT_NUMERIC_FIELDS);
+  const list_changes = {
+    repo_ids: buildListChange('Repos', left.repo_ids, right.repo_ids),
+    repos_with_events: buildListChange('Repos with events', left.repos_with_events, right.repos_with_events),
+  };
+  const repo_status_changes = buildMapChanges('Repo status', left.repo_run_statuses, right.repo_run_statuses);
+  const repo_export_changes = buildBooleanMapChanges('Repo export ok', left.repo_export_status, right.repo_export_status);
+  const event_type_changes = buildNumericMapChanges('Event type', left.event_type_counts, right.event_type_counts);
+
+  const changed = hasChanged(scalar_changes, numeric_changes, list_changes)
+    || repo_status_changes.some((entry) => entry.changed)
+    || repo_export_changes.some((entry) => entry.changed)
+    || event_type_changes.some((entry) => entry.changed);
+
+  return {
+    comparison_mode: 'export',
+    subject_kind: 'coordinator',
+    export_kind: leftArtifact.export_kind,
+    left_ref: refs.left_ref || null,
+    right_ref: refs.right_ref || null,
+    changed,
+    left,
+    right,
+    scalar_changes,
+    numeric_changes,
+    list_changes,
+    repo_status_changes,
+    repo_export_changes,
+    event_type_changes,
+  };
+}
+
+function normalizeRunExport(artifact) {
+  const summary = artifact.summary || {};
+  const repoDecisions = summary.repo_decisions || {};
+  return {
+    export_kind: artifact.export_kind,
+    run_id: summary.run_id || null,
+    status: summary.status || null,
+    phase: summary.phase || null,
+    project_name: artifact.project?.name || null,
+    project_goal: summary.project_goal || artifact.project?.goal || null,
+    provenance_trigger: summary.provenance?.trigger || null,
+    dashboard_status: summary.dashboard_session?.status || null,
+    history_entries: toNumber(summary.history_entries),
+    decision_entries: toNumber(summary.decision_entries),
+    hook_audit_entries: toNumber(summary.hook_audit_entries),
+    notification_audit_entries: toNumber(summary.notification_audit_entries),
+    dispatch_artifact_files: toNumber(summary.dispatch_artifact_files),
+    staging_artifact_files: toNumber(summary.staging_artifact_files),
+    total_delegations_issued: toNumber(summary.delegation_summary?.total_delegations_issued),
+    active_repo_decision_count: toNumber(repoDecisions.active_count),
+    overridden_repo_decision_count: toNumber(repoDecisions.overridden_count),
+    active_turn_ids: normalizeStringArray(summary.active_turn_ids),
+    retained_turn_ids: normalizeStringArray(summary.retained_turn_ids),
+    active_repo_decision_ids: normalizeStringArray((repoDecisions.active || []).map((entry) => entry?.id)),
+    overridden_repo_decision_ids: normalizeStringArray((repoDecisions.overridden || []).map((entry) => entry?.id)),
+  };
+}
+
+function normalizeCoordinatorExport(artifact) {
+  const summary = artifact.summary || {};
+  const aggregatedEvents = summary.aggregated_events || {};
+  const repoRunStatuses = summary.repo_run_statuses || {};
+  const repos = artifact.repos || {};
+
+  return {
+    export_kind: artifact.export_kind,
+    super_run_id: summary.super_run_id || null,
+    status: summary.status || null,
+    phase: summary.phase || null,
+    project_name: artifact.coordinator?.project_name || null,
+    barrier_count: toNumber(summary.barrier_count),
+    history_entries: toNumber(summary.history_entries),
+    decision_entries: toNumber(summary.decision_entries),
+    total_events: toNumber(aggregatedEvents.total_events),
+    repo_ids: normalizeStringArray(Object.keys(repos)),
+    repos_with_events: normalizeStringArray(aggregatedEvents.repos_with_events),
+    repo_run_statuses: normalizeStringMap(repoRunStatuses),
+    repo_export_status: normalizeBooleanMap(Object.fromEntries(
+      Object.entries(repos).map(([repoId, repoEntry]) => [repoId, repoEntry?.ok === true]),
+    )),
+    event_type_counts: normalizeNumericMap(aggregatedEvents.event_type_counts),
+  };
+}
+
+function buildFieldChanges(left, right, fields) {
+  return Object.fromEntries(
+    fields.map(([field, label]) => [field, {
+      label,
+      left: left[field],
+      right: right[field],
+      changed: !isEqual(left[field], right[field]),
+    }]),
+  );
+}
+
+function buildNumericChanges(left, right, fields) {
+  return Object.fromEntries(
+    fields.map(([field, label]) => [field, {
+      label,
+      left: left[field],
+      right: right[field],
+      changed: !isEqual(left[field], right[field]),
+      delta: typeof left[field] === 'number' && typeof right[field] === 'number'
+        ? right[field] - left[field]
+        : null,
+    }]),
+  );
+}
+
+function buildListChange(label, left, right) {
+  const leftSet = new Set(left);
+  const rightSet = new Set(right);
+  return {
+    label,
+    left,
+    right,
+    added: right.filter((value) => !leftSet.has(value)),
+    removed: left.filter((value) => !rightSet.has(value)),
+    changed: left.length !== right.length || left.some((value, index) => value !== right[index]),
+  };
+}
+
+function buildMapChanges(label, leftMap, rightMap) {
+  const keys = normalizeStringArray([...Object.keys(leftMap), ...Object.keys(rightMap)]);
+  return keys.map((key) => ({
+    label,
+    key,
+    left: leftMap[key] ?? null,
+    right: rightMap[key] ?? null,
+    changed: !isEqual(leftMap[key] ?? null, rightMap[key] ?? null),
+  }));
+}
+
+function buildBooleanMapChanges(label, leftMap, rightMap) {
+  return buildMapChanges(label, leftMap, rightMap);
+}
+
+function buildNumericMapChanges(label, leftMap, rightMap) {
+  const keys = normalizeStringArray([...Object.keys(leftMap), ...Object.keys(rightMap)]);
+  return keys.map((key) => {
+    const left = typeof leftMap[key] === 'number' ? leftMap[key] : null;
+    const right = typeof rightMap[key] === 'number' ? rightMap[key] : null;
+    return {
+      label,
+      key,
+      left,
+      right,
+      changed: !isEqual(left, right),
+      delta: typeof left === 'number' && typeof right === 'number' ? right - left : null,
+    };
+  });
+}
+
+function hasChanged(scalarChanges, numericChanges, listChanges) {
+  return [
+    ...Object.values(scalarChanges),
+    ...Object.values(numericChanges),
+  ].some((entry) => entry.changed)
+    || Object.values(listChanges).some((entry) => entry.changed);
+}
+
+function normalizeStringArray(value) {
+  if (!Array.isArray(value)) return [];
+  return [...new Set(value
+    .filter((item) => typeof item === 'string' && item.trim().length > 0)
+    .map((item) => item.trim()))]
+    .sort((a, b) => a.localeCompare(b, 'en'));
+}
+
+function normalizeStringMap(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return {};
+  return Object.fromEntries(
+    Object.entries(value)
+      .filter(([key]) => typeof key === 'string' && key.trim().length > 0)
+      .map(([key, mapValue]) => [key.trim(), typeof mapValue === 'string' && mapValue.trim() ? mapValue.trim() : null]),
+  );
+}
+
+function normalizeBooleanMap(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return {};
+  return Object.fromEntries(
+    Object.entries(value)
+      .filter(([key]) => typeof key === 'string' && key.trim().length > 0)
+      .map(([key, mapValue]) => [key.trim(), mapValue === true]),
+  );
+}
+
+function normalizeNumericMap(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return {};
+  return Object.fromEntries(
+    Object.entries(value)
+      .filter(([key, mapValue]) => typeof key === 'string' && key.trim().length > 0 && typeof mapValue === 'number')
+      .map(([key, mapValue]) => [key.trim(), mapValue]),
+  );
+}
+
+function toNumber(value) {
+  return typeof value === 'number' ? value : null;
+}
+
+function isEqual(left, right) {
+  return JSON.stringify(left) === JSON.stringify(right);
+}