@chllming/wave-orchestration 0.6.3 → 0.7.0

package/scripts/wave-orchestrator/proof-cli.mjs

@@ -0,0 +1,195 @@
+import path from "node:path";
+import { appendCoordinationRecord } from "./coordination-store.mjs";
+import { parseWaveFiles } from "./wave-files.mjs";
+import {
+  buildLanePaths,
+  parseNonNegativeInt,
+  readJsonOrNull,
+  REPO_ROOT,
+  sanitizeAdhocRunId,
+  sanitizeLaneName,
+} from "./shared.mjs";
+import {
+  readWaveProofRegistry,
+  registerWaveProofBundle,
+} from "./proof-registry.mjs";
+
+function printUsage() {
+  console.log(`Usage:
+  pnpm exec wave proof show --lane <lane> --wave <n> [--agent <id>] [--json]
+  pnpm exec wave proof register --lane <lane> --wave <n> --agent <id> --artifact <path> [--artifact <path> ...] [--component <id[:level]> ...] [--authoritative] [--satisfy-owned-components] [--completion <level>] [--durability <level>] [--proof-level <level>] [--doc-delta <state>] [--operator <name>] [--detail <text>] [--json]
+  pnpm exec wave proof <subcommand> --run <id> [--wave 0] ...
+`);
+}
+
+function parseArgs(argv) {
+  const args = argv[0] === "--" ? argv.slice(1) : argv;
+  const subcommand = String(args[0] || "").trim().toLowerCase();
+  const options = {
+    lane: "main",
+    wave: null,
+    runId: "",
+    agentId: "",
+    artifactPaths: [],
+    components: [],
+    authoritative: false,
+    satisfyOwnedComponents: false,
+    completion: "",
+    durability: "",
+    proofLevel: "",
+    docDeltaState: "",
+    operator: "human-operator",
+    detail: "",
+    json: false,
+  };
+  for (let i = 1; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === "--lane") {
+      options.lane = sanitizeLaneName(args[++i]);
+    } else if (arg === "--run") {
+      options.runId = sanitizeAdhocRunId(args[++i]);
+    } else if (arg === "--wave") {
+      options.wave = parseNonNegativeInt(args[++i], "--wave");
+    } else if (arg === "--agent") {
+      options.agentId = String(args[++i] || "").trim();
+    } else if (arg === "--artifact") {
+      options.artifactPaths.push(String(args[++i] || "").trim());
+    } else if (arg === "--component") {
+      options.components.push(String(args[++i] || "").trim());
+    } else if (arg === "--authoritative") {
+      options.authoritative = true;
+    } else if (arg === "--satisfy-owned-components") {
+      options.satisfyOwnedComponents = true;
+    } else if (arg === "--completion") {
+      options.completion = String(args[++i] || "").trim();
+    } else if (arg === "--durability") {
+      options.durability = String(args[++i] || "").trim();
+    } else if (arg === "--proof-level") {
+      options.proofLevel = String(args[++i] || "").trim();
+    } else if (arg === "--doc-delta") {
+      options.docDeltaState = String(args[++i] || "").trim();
+    } else if (arg === "--operator") {
+      options.operator = String(args[++i] || "").trim() || "human-operator";
+    } else if (arg === "--detail") {
+      options.detail = String(args[++i] || "").trim();
+    } else if (arg === "--json") {
+      options.json = true;
+    } else if (arg === "--help" || arg === "-h") {
+      return { help: true, subcommand, options };
+    } else {
+      throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+  return { help: false, subcommand, options };
+}
+
+function loadWave(lanePaths, waveNumber) {
+  const waves = parseWaveFiles(lanePaths.wavesDir, { laneProfile: lanePaths.laneProfile });
+  const wave = waves.find((entry) => entry.wave === waveNumber);
+  if (!wave) {
+    throw new Error(`Wave ${waveNumber} not found in ${lanePaths.wavesDir}`);
+  }
+  return wave;
+}
+
+function resolveLaneForRun(runId, fallbackLane) {
+  return (
+    readJsonOrNull(path.join(REPO_ROOT, ".wave", "adhoc", "runs", runId, "result.json"))?.lane ||
+    fallbackLane
+  );
+}
+
+function coordinationLogPath(lanePaths, waveNumber) {
+  return path.join(lanePaths.coordinationDir, `wave-${waveNumber}.jsonl`);
+}
+
+export async function runProofCli(argv) {
+  const { help, subcommand, options } = parseArgs(argv);
+  if (help || !subcommand) {
+    printUsage();
+    return;
+  }
+  if (!["show", "register"].includes(subcommand)) {
+    throw new Error("Expected subcommand: show | register");
+  }
+  if (options.runId) {
+    options.lane = resolveLaneForRun(options.runId, options.lane);
+  }
+  const lanePaths = buildLanePaths(options.lane, {
+    adhocRunId: options.runId || null,
+  });
+  if (options.wave === null && options.runId) {
+    options.wave = 0;
+  }
+  if (options.wave === null) {
+    throw new Error("--wave is required");
+  }
+  const wave = loadWave(lanePaths, options.wave);
+  if (subcommand === "show") {
+    const registry = readWaveProofRegistry(lanePaths, wave.wave);
+    const entries = options.agentId
+      ? (registry?.entries || []).filter((entry) => entry.agentId === options.agentId)
+      : (registry?.entries || []);
+    const payload = {
+      lane: lanePaths.lane,
+      wave: wave.wave,
+      entries,
+    };
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+  if (!options.agentId) {
+    throw new Error("register requires --agent");
+  }
+  if (options.artifactPaths.length === 0) {
+    throw new Error("register requires at least one --artifact");
+  }
+  const agent = (wave.agents || []).find((entry) => entry.agentId === options.agentId);
+  if (!agent) {
+    throw new Error(`Unknown wave agent id: ${options.agentId}`);
+  }
+  const { entry, registry } = registerWaveProofBundle({
+    lanePaths,
+    wave,
+    agent,
+    artifactPaths: options.artifactPaths,
+    componentIds: options.components,
+    authoritative: options.authoritative,
+    satisfyOwnedComponents: options.satisfyOwnedComponents,
+    completion: options.completion || null,
+    durability: options.durability || null,
+    proofLevel: options.proofLevel || null,
+    docDeltaState: options.docDeltaState || null,
+    detail: options.detail || "",
+    recordedBy: options.operator || "human-operator",
+  });
+  appendCoordinationRecord(coordinationLogPath(lanePaths, wave.wave), {
+    id: entry.id,
+    lane: lanePaths.lane,
+    wave: wave.wave,
+    agentId: options.operator || "human-operator",
+    kind: "evidence",
+    targets: [
+      `agent:${agent.agentId}`,
+      `agent:${wave.integrationAgentId || lanePaths.integrationAgentId || "A8"}`,
+      `agent:${wave.contQaAgentId || lanePaths.contQaAgentId || "A0"}`,
+    ],
+    priority: options.authoritative ? "high" : "normal",
+    artifactRefs: entry.artifacts.map((artifact) => artifact.path),
+    summary:
+      entry.summary ||
+      `${entry.authoritative ? "Authoritative" : "Registered"} proof bundle for ${agent.agentId}`,
+    detail:
+      entry.detail ||
+      `Proof bundle recorded for ${agent.agentId} by ${options.operator || "human-operator"}.`,
+    status: "resolved",
+    source: "operator",
+  });
+  const payload = {
+    lane: lanePaths.lane,
+    wave: wave.wave,
+    entry,
+    registry,
+  };
+  console.log(JSON.stringify(payload, null, 2));
+}

package/scripts/wave-orchestrator/proof-registry.mjs

@@ -0,0 +1,317 @@
+import fs from "node:fs";
+import path from "node:path";
+import {
+  readProofRegistry,
+  writeProofRegistry,
+} from "./artifact-schemas.mjs";
+import {
+  appendWaveControlEvent,
+  readWaveControlPlaneState,
+  syncWaveControlPlaneProjections,
+} from "./control-plane.mjs";
+import { REPO_ROOT, ensureDirectory, hashText, toIsoTimestamp } from "./shared.mjs";
+
+function cloneJson(value) {
+  return value === undefined ? undefined : JSON.parse(JSON.stringify(value));
+}
+
+function safeArray(values) {
+  return Array.isArray(values) ? values : [];
+}
+
+function matchingDeclaredProofArtifact(agent, artifactPath) {
+  return safeArray(agent?.proofArtifacts).find((artifact) => artifact?.path === artifactPath) || null;
+}
+
+function absoluteArtifactPath(repoRelativePath) {
+  return path.resolve(REPO_ROOT, String(repoRelativePath || ""));
+}
+
+function buildProofArtifactRecord(agent, artifactPath) {
+  const declared = matchingDeclaredProofArtifact(agent, artifactPath);
+  const absolutePath = absoluteArtifactPath(artifactPath);
+  const exists = fs.existsSync(absolutePath);
+  return {
+    path: artifactPath,
+    kind: declared?.kind || null,
+    requiredFor: safeArray(declared?.requiredFor),
+    exists,
+    sha256: exists ? hashText(fs.readFileSync(absolutePath, "utf8")) : null,
+  };
+}
+
+function normalizeRegisteredComponent(agent, componentInput, detail = null) {
+  const normalized = String(componentInput || "").trim();
+  if (!normalized) {
+    return null;
+  }
+  const [componentId, explicitLevel = ""] = normalized.split(":", 2);
+  const cleanComponentId = String(componentId || "").trim();
+  if (!cleanComponentId) {
+    return null;
+  }
+  return {
+    componentId: cleanComponentId,
+    level: String(explicitLevel || "").trim() || agent?.componentTargets?.[cleanComponentId] || null,
+    state: "met",
+    detail: String(detail || "").trim() || null,
+  };
+}
+
+function ensureDeliverableState(agent, summary) {
+  const deliverables = safeArray(agent?.deliverables);
+  if (deliverables.length === 0) {
+    return summary;
+  }
+  const current = new Map(
+    safeArray(summary.deliverables).map((item) => [item.path, item]),
+  );
+  for (const deliverablePath of deliverables) {
+    const existing = current.get(deliverablePath);
+    if (existing?.exists === true) {
+      continue;
+    }
+    current.set(deliverablePath, {
+      path: deliverablePath,
+      exists: fs.existsSync(absoluteArtifactPath(deliverablePath)),
+    });
+  }
+  summary.deliverables = Array.from(current.values());
+  return summary;
+}
+
+function mergeComponents(summary, components) {
+  const current = new Map(
+    safeArray(summary.components).map((item) => [item.componentId, item]),
+  );
+  for (const component of components) {
+    if (!component?.componentId) {
+      continue;
+    }
+    const existing = current.get(component.componentId) || {};
+    current.set(component.componentId, {
+      componentId: component.componentId,
+      level: component.level || existing.level || null,
+      state: component.state || existing.state || "met",
+      detail: component.detail || existing.detail || "",
+    });
+  }
+  summary.components = Array.from(current.values());
+  return summary;
+}
+
+function mergeProofArtifacts(summary, artifacts) {
+  const current = new Map(
+    safeArray(summary.proofArtifacts).map((item) => [item.path, item]),
+  );
+  for (const artifact of artifacts) {
+    if (!artifact?.path) {
+      continue;
+    }
+    const existing = current.get(artifact.path) || {};
+    current.set(artifact.path, {
+      path: artifact.path,
+      kind: artifact.kind || existing.kind || null,
+      exists: artifact.exists === true || existing.exists === true,
+      requiredFor: safeArray(artifact.requiredFor).length > 0
+        ? safeArray(artifact.requiredFor)
+        : safeArray(existing.requiredFor),
+      sha256: artifact.sha256 || existing.sha256 || null,
+    });
+  }
+  summary.proofArtifacts = Array.from(current.values());
+  return summary;
+}
+
+function latestAuthoritativeEntry(proofRegistry, agentId) {
+  return safeArray(proofRegistry?.entries)
+    .filter(
+      (entry) =>
+        entry?.authoritative === true &&
+        entry?.agentId === agentId &&
+        !["revoked", "superseded"].includes(String(entry?.state || "").trim().toLowerCase()),
+    )
+    .sort((left, right) => Date.parse(left.recordedAt || "") - Date.parse(right.recordedAt || ""))
+    .at(-1) || null;
+}
+
+export function waveProofRegistryPath(lanePaths, waveNumber) {
+  return path.join(lanePaths.proofDir, `wave-${waveNumber}.json`);
+}
+
+export function readWaveProofRegistry(lanePaths, waveNumber) {
+  const controlState = readWaveControlPlaneState(lanePaths, waveNumber);
+  if (controlState.proofBundles.length === 0) {
+    return readProofRegistry(waveProofRegistryPath(lanePaths, waveNumber), {
+      lane: lanePaths?.lane || null,
+      wave: waveNumber,
+    });
+  }
+  const registry = syncWaveControlPlaneProjections(
+    lanePaths,
+    waveNumber,
+    controlState,
+  ).proofRegistry;
+  return registry || readProofRegistry(waveProofRegistryPath(lanePaths, waveNumber), {
+    lane: lanePaths?.lane || null,
+    wave: waveNumber,
+  });
+}
+
+export function writeWaveProofRegistry(lanePaths, waveNumber, payload) {
+  const filePath = waveProofRegistryPath(lanePaths, waveNumber);
+  ensureDirectory(path.dirname(filePath));
+  return writeProofRegistry(filePath, payload, {
+    lane: lanePaths?.lane || null,
+    wave: waveNumber,
+  });
+}
+
+export function registerWaveProofBundle({
+  lanePaths,
+  wave,
+  agent,
+  artifactPaths = [],
+  componentIds = [],
+  authoritative = false,
+  satisfyOwnedComponents = false,
+  completion = null,
+  durability = null,
+  proofLevel = null,
+  docDeltaState = null,
+  detail = "",
+  recordedBy = "human-operator",
+}) {
+  const recordedAt = toIsoTimestamp();
+  const normalizedArtifacts = Array.from(
+    new Set(safeArray(artifactPaths).map((value) => String(value || "").trim()).filter(Boolean)),
+  ).map((artifactPath) => buildProofArtifactRecord(agent, artifactPath));
+  const normalizedComponents = [
+    ...safeArray(componentIds).map((componentId) =>
+      normalizeRegisteredComponent(agent, componentId, detail),
+    ),
+    ...(satisfyOwnedComponents
+      ? safeArray(agent?.components).map((componentId) =>
+          normalizeRegisteredComponent(agent, componentId, detail),
+        )
+      : []),
+  ].filter((component, index, values) =>
+    component && values.findIndex((other) => other?.componentId === component.componentId) === index,
+  );
+  const entry = {
+    id: `proof-${agent.agentId}-${recordedAt.replace(/[-:.TZ]/g, "").slice(0, 14)}`,
+    agentId: agent.agentId,
+    authoritative,
+    recordedAt,
+    recordedBy,
+    detail: String(detail || "").trim() || null,
+    summary: authoritative
+      ? `Authoritative proof bundle registered for ${agent.agentId}`
+      : `Proof bundle registered for ${agent.agentId}`,
+    satisfyOwnedComponents,
+    proof:
+      completion || durability || proofLevel || authoritative
+        ? {
+            state: "met",
+            completion: completion || agent?.exitContract?.completion || null,
+            durability: durability || agent?.exitContract?.durability || null,
+            proof: proofLevel || agent?.exitContract?.proof || null,
+            detail: String(detail || "").trim() || null,
+          }
+        : null,
+    docDelta: docDeltaState
+      ? {
+          state: docDeltaState,
+          detail: String(detail || "").trim() || null,
+        }
+      : null,
+    components: normalizedComponents,
+    artifacts: normalizedArtifacts,
+  };
+  appendWaveControlEvent(lanePaths, wave.wave, {
+    entityType: "proof_bundle",
+    entityId: entry.id,
+    action: "registered",
+    source: "operator",
+    actor: recordedBy,
+    data: {
+      proofBundleId: entry.id,
+      agentId: entry.agentId,
+      state: "active",
+      authoritative: entry.authoritative,
+      recordedAt: entry.recordedAt,
+      recordedBy: entry.recordedBy,
+      detail: entry.detail,
+      summary: entry.summary,
+      satisfyOwnedComponents: entry.satisfyOwnedComponents,
+      proof: entry.proof,
+      docDelta: entry.docDelta,
+      components: entry.components,
+      artifacts: entry.artifacts,
+      scope: "wave",
+      satisfies: normalizedComponents.map((component) => component.componentId),
+    },
+  });
+  const normalized = syncWaveControlPlaneProjections(
+    lanePaths,
+    wave.wave,
+    readWaveControlPlaneState(lanePaths, wave.wave),
+  ).proofRegistry;
+  return {
+    registry: normalized,
+    entry: cloneJson(entry),
+  };
+}
+
+export function augmentSummaryWithProofRegistry(agent, summary, proofRegistry) {
+  const authoritativeEntry = latestAuthoritativeEntry(proofRegistry, agent?.agentId);
+  if (!authoritativeEntry) {
+    return summary;
+  }
+  const next = cloneJson(summary) || {
+    agentId: agent?.agentId || null,
+  };
+  if (authoritativeEntry.proof?.state === "met") {
+    next.proof = {
+      completion:
+        authoritativeEntry.proof.completion ||
+        next.proof?.completion ||
+        agent?.exitContract?.completion ||
+        null,
+      durability:
+        authoritativeEntry.proof.durability ||
+        next.proof?.durability ||
+        agent?.exitContract?.durability ||
+        null,
+      proof:
+        authoritativeEntry.proof.proof ||
+        next.proof?.proof ||
+        agent?.exitContract?.proof ||
+        null,
+      state: "met",
+      detail:
+        authoritativeEntry.proof.detail ||
+        next.proof?.detail ||
+        "Satisfied by authoritative proof registry.",
+    };
+  }
+  if (authoritativeEntry.docDelta) {
+    next.docDelta = cloneJson(authoritativeEntry.docDelta);
+  }
+  mergeProofArtifacts(next, authoritativeEntry.artifacts);
+  if (authoritativeEntry.satisfyOwnedComponents || safeArray(authoritativeEntry.components).length > 0) {
+    mergeComponents(
+      next,
+      safeArray(authoritativeEntry.components).length > 0
+        ? authoritativeEntry.components
+        : safeArray(agent?.components).map((componentId) => ({
+            componentId,
+            level: agent?.componentTargets?.[componentId] || null,
+            state: "met",
+            detail: authoritativeEntry.detail || "",
+          })),
+    );
+  }
+  ensureDeliverableState(agent, next);
+  return next;
+}

package/scripts/wave-orchestrator/replay.mjs

@@ -1,4 +1,5 @@
 import path from "node:path";
+import { augmentSummaryWithProofRegistry } from "./proof-registry.mjs";
 import { readJsonOrNull } from "./shared.mjs";
 import { buildGateSnapshot } from "./launcher.mjs";
 import {
@@ -59,7 +60,7 @@ function buildReplayLanePaths(metadata) {
   };
 }
 
-function buildReplayAgentRuns(dir, wave, metadata) {
+function buildReplayAgentRuns(dir, wave, metadata, proofRegistry = null) {
   const isHermeticTrace = Number(metadata?.traceVersion) >= 2;
   return (metadata?.agents || []).map((agentMetadata) => {
     const waveAgent =
@@ -69,6 +70,11 @@ function buildReplayAgentRuns(dir, wave, metadata) {
       };
     const summaryPath = absoluteBundlePath(dir, agentMetadata.summaryPath);
     const summaryPayload = summaryPath ? readJsonOrNull(summaryPath) : null;
+    const augmentedSummary = augmentSummaryWithProofRegistry(
+      waveAgent,
+      summaryPayload && typeof summaryPayload === "object" ? summaryPayload : null,
+      proofRegistry,
+    );
     return {
       agent: {
         ...waveAgent,
@@ -86,8 +92,8 @@ function buildReplayAgentRuns(dir, wave, metadata) {
       statusPath: absoluteBundlePath(dir, agentMetadata.statusPath),
       summaryPath,
       summary:
-        summaryPayload && typeof summaryPayload === "object"
-          ? summaryPayload
+        augmentedSummary
+          ? augmentedSummary
           : !isHermeticTrace
             ? agentMetadata.summary || null
             : null,
@@ -174,7 +180,7 @@ export function replayTraceBundle(dir) {
     };
   }
   const lanePaths = buildReplayLanePaths(bundle.metadata);
-  const agentRuns = buildReplayAgentRuns(dir, wave, bundle.metadata);
+  const agentRuns = buildReplayAgentRuns(dir, wave, bundle.metadata, bundle.proofRegistry || null);
   const derivedState = {
     coordinationState: bundle.coordinationState,
     ledger: bundle.ledger,