@chllming/wave-orchestration 0.7.3 → 0.8.0

package/scripts/wave-orchestrator/agent-state.mjs

@@ -1182,13 +1182,93 @@ export function validateContQaSummary(agent, summary, options = {}) {
 }
 
 // ---------------------------------------------------------------------------
-// Agent Result Envelope — Wave 3
+// Agent Result Envelope — P1-6 End-State (schemaVersion 2)
 // ---------------------------------------------------------------------------
 
 import { toIsoTimestamp } from "./shared.mjs";
 
 /**
- * Path to the envelope file derived from the status path.
+ * Valid roles for the agent result envelope.
+ */
+export const ENVELOPE_VALID_ROLES = [
+  "implementation",
+  "integration",
+  "documentation",
+  "cont-qa",
+  "cont-eval",
+  "security",
+  "deploy",
+];
+
+function inferEnvelopeRole(agent, summary) {
+  const candidate = String(agent?.role || summary?.role || "").trim().toLowerCase();
+  if (candidate && ENVELOPE_VALID_ROLES.includes(candidate)) {
+    return candidate;
+  }
+  if (summary?.integration) {
+    return "integration";
+  }
+  if (summary?.docClosure) {
+    return "documentation";
+  }
+  if (summary?.eval) {
+    return "cont-eval";
+  }
+  if (summary?.security) {
+    return "security";
+  }
+  if (summary?.gate || summary?.verdict) {
+    return "cont-qa";
+  }
+  if (summary?.deploy) {
+    return "deploy";
+  }
+  if (summary?.proof || summary?.docDelta || Array.isArray(summary?.components)) {
+    return "implementation";
+  }
+  return null;
+}
+
+function toSummaryRelativePath(filePath) {
+  const normalized = String(filePath || "").trim();
+  if (!normalized) {
+    return null;
+  }
+  return path.isAbsolute(normalized) ? path.relative(REPO_ROOT, normalized) : normalized;
+}
+
+function toLegacyProofState(state) {
+  if (state === "satisfied") {
+    return "met";
+  }
+  if (state === "partial") {
+    return "gap";
+  }
+  if (state === "failed") {
+    return "failed";
+  }
+  return "not_applicable";
+}
+
+/**
+ * Compute the attempt-scoped canonical envelope path.
+ *
+ * End-state path: .tmp/<lane>/results/wave-<N>/attempt-<A>/<agentId>.json
+ *
+ * @param {object} options - { lane, waveNumber, attempt, agentId }
+ * @returns {string} The envelope file path
+ */
+export function agentEnvelopePath({ lane, waveNumber, attempt, agentId }) {
+  const safeLane = lane || "main";
+  const safeWave = waveNumber ?? 0;
+  const safeAttempt = attempt ?? 1;
+  const safeAgent = agentId || "unknown";
+  return `.tmp/${safeLane}-wave-launcher/results/wave-${safeWave}/attempt-${safeAttempt}/${safeAgent}.json`;
+}
+
+/**
+ * Legacy path derivation from status path.
+ * Retained for backward compatibility during migration.
  *
  * @param {string} statusPath - Path to the .status or .summary file
  * @returns {string} The envelope file path
@@ -1207,129 +1287,365 @@ export function agentEnvelopePathFromStatusPath(statusPath) {
  * Build a structured result envelope from an already-parsed execution summary.
  * Pure function — the envelope is a normalized projection of the summary.
  *
- * @param {object} agent - Agent definition from wave
+ * End-state P1-6: common header + role-specific typed optional payloads.
+ * Absent role sections are NOT included (not null, not empty object).
+ *
+ * @param {object} agent - Agent definition from wave (must include .role)
  * @param {object} summary - Execution summary from buildAgentExecutionSummary
- * @returns {object} AgentResultEnvelope
+ * @param {object} [options] - { waveNumber, attempt, exitCode }
+ * @returns {object} AgentResultEnvelope (schemaVersion 2)
  */
-export function buildAgentResultEnvelope(agent, summary) {
+export function buildAgentResultEnvelope(agent, summary, options = {}) {
   const safeAgent = agent || {};
   const safeSummary = summary || {};
+  const safeOptions = options || {};
 
-  // Exit contract from proof dimensions + doc delta
+  const agentId = safeAgent.agentId || safeSummary.agentId || null;
+  const role = inferEnvelopeRole(safeAgent, safeSummary);
+
+  // --- Common header ---
   const proof = safeSummary.proof || {};
-  const docDelta = safeSummary.docDelta || {};
-  const exitContract = {
+  const proofSection = {
+    state: proof.state === "met" ? "satisfied"
+      : proof.state === "gap" ? "partial"
+      : proof.state === "failed" ? "failed"
+      : "not_applicable",
     completion: proof.completion || null,
     durability: proof.durability || null,
-    proof: proof.proof || null,
-    docImpact: docDelta.state || null,
+    proofLevel: proof.proof || null,
+    detail: proof.detail || null,
   };
 
-  // Proof artifacts
+  // Deliverables — with sha256
+  const deliverables = Array.isArray(safeSummary.deliverables)
+    ? safeSummary.deliverables.map((d) => ({
+        path: d.path || null,
+        exists: d.exists === true,
+        sha256: d.sha256 || null,
+      }))
+    : [];
+
+  // Proof artifacts — with sha256 and requiredFor
   const proofArtifacts = Array.isArray(safeSummary.proofArtifacts)
     ? safeSummary.proofArtifacts.map((artifact) => ({
         path: artifact.path || null,
         kind: artifact.kind || null,
-        sha256: artifact.sha256 || null,
         exists: artifact.exists === true,
+        sha256: artifact.sha256 || null,
+        requiredFor: artifact.requiredFor || null,
       }))
     : [];
 
-  // Deliverables
-  const deliverables = Array.isArray(safeSummary.deliverables)
-    ? safeSummary.deliverables.map((d) => ({
-        path: d.path || null,
-        exists: d.exists === true,
+  // Gaps
+  const gaps = Array.isArray(safeSummary.gaps)
+    ? safeSummary.gaps.map((g) => ({
+        kind: g.kind || null,
+        detail: g.detail || null,
       }))
     : [];
 
-  // Components
-  const components = Array.isArray(safeSummary.components)
-    ? safeSummary.components.map((c) => ({
-        componentId: c.componentId || null,
-        level: c.level || null,
-        state: c.state || null,
+  // Unresolved blockers
+  const unresolvedBlockers = Array.isArray(safeSummary.unresolvedBlockers)
+    ? safeSummary.unresolvedBlockers.map((b) =>
+        typeof b === "object" ? { kind: b.kind || null, detail: b.detail || null, blocking: b.blocking || null } : { kind: null, detail: String(b), blocking: null },
+      )
+    : [];
+
+  // Risk notes
+  const riskNotes = Array.isArray(safeSummary.riskNotes) ? safeSummary.riskNotes : [];
+
+  // Facts
+  const facts = Array.isArray(safeSummary.facts)
+    ? safeSummary.facts.map((f) => ({
+        factId: f.factId || null,
+        kind: f.kind || null,
+        content: f.content || null,
       }))
     : [];
 
-  // Gate claims from the gate marker
-  const gateClaims = [];
-  if (safeSummary.gate) {
-    const gateKeys = ["architecture", "integration", "durability", "live", "docs"];
-    for (const key of gateKeys) {
-      if (safeSummary.gate[key]) {
-        gateClaims.push({
-          gateId: key,
-          claim: safeSummary.gate[key],
-          detail: safeSummary.gate.detail || null,
-        });
-      }
-    }
+  const envelope = {
+    schemaVersion: 2,
+    agentId,
+    waveNumber: safeOptions.waveNumber ?? safeSummary.waveNumber ?? null,
+    attempt: safeOptions.attempt ?? safeSummary.attempt ?? null,
+    completedAt: safeOptions.completedAt || toIsoTimestamp(),
+    exitCode: typeof safeOptions.exitCode === "number" ? safeOptions.exitCode : (typeof safeSummary.exitCode === "number" ? safeSummary.exitCode : 0),
+    role,
+    proof: proofSection,
+    deliverables,
+    proofArtifacts,
+    gaps,
+    unresolvedBlockers,
+    riskNotes,
+    facts,
+  };
+
+  // --- Role-specific typed payloads (absent when not applicable) ---
+
+  if (role === "implementation") {
+    const docDelta = safeSummary.docDelta || {};
+    const components = Array.isArray(safeSummary.components)
+      ? safeSummary.components.map((c) => ({
+          componentId: c.componentId || null,
+          level: c.level || null,
+          state: c.state || null,
+          detail: c.detail || null,
+        }))
+      : [];
+    envelope.implementation = {
+      docDelta: {
+        state: docDelta.state || "none",
+        paths: Array.isArray(docDelta.paths) ? docDelta.paths : [],
+        detail: docDelta.detail || null,
+      },
+      components,
+    };
   }
 
-  // Validation outputs from proof state
-  const validationOutputs = {
-    testsPassed: proof.state === "met" && proof.proof != null,
-    buildPassed: proof.state === "met",
-  };
+  if (role === "integration") {
+    const integ = safeSummary.integration || {};
+    envelope.integration = {
+      state: integ.state || null,
+      claims: integ.claims || 0,
+      conflicts: integ.conflicts || 0,
+      blockers: integ.blockers || 0,
+      detail: integ.detail || null,
+    };
+  }
 
-  // Risk notes
-  const riskNotes = Array.isArray(safeSummary.riskNotes) ? safeSummary.riskNotes : [];
+  if (role === "documentation") {
+    const docDelta = safeSummary.docDelta || safeSummary.docClosure || {};
+    envelope.documentation = {
+      docClosure: {
+        state: docDelta.state || "no-change",
+        paths: Array.isArray(docDelta.paths) ? docDelta.paths : [],
+        detail: docDelta.detail || null,
+      },
+    };
+  }
 
-  // Unresolved blockers
-  const unresolvedBlockers = Array.isArray(safeSummary.unresolvedBlockers)
-    ? safeSummary.unresolvedBlockers
-    : [];
+  if (role === "cont-qa") {
+    const verdict = safeSummary.verdict || {};
+    const gate = safeSummary.gate || {};
+    envelope.contQa = {
+      verdict: {
+        verdict: verdict.verdict || null,
+        detail: verdict.detail || null,
+      },
+      gateClaims: {
+        architecture: gate.architecture || null,
+        integration: gate.integration || null,
+        durability: gate.durability || null,
+        live: gate.live || null,
+        docs: gate.docs || null,
+      },
+    };
+  }
 
-  // Docs deltas
-  const docsDeltas = [];
-  if (docDelta.state) {
-    docsDeltas.push({
-      state: docDelta.state,
-      paths: Array.isArray(docDelta.paths) ? docDelta.paths : [],
-      detail: docDelta.detail || null,
-    });
+  if (role === "cont-eval") {
+    const evalSection = safeSummary.eval || {};
+    envelope.contEval = {
+      state: evalSection.state || null,
+      targets: evalSection.targets || 0,
+      benchmarks: evalSection.benchmarks || 0,
+      regressions: evalSection.regressions || 0,
+      targetIds: Array.isArray(evalSection.targetIds) ? evalSection.targetIds : [],
+      benchmarkIds: Array.isArray(evalSection.benchmarkIds) ? evalSection.benchmarkIds : [],
+      detail: evalSection.detail || null,
+    };
   }
 
-  // Security findings
-  const securityFindings = [];
-  if (safeSummary.security) {
-    securityFindings.push({
-      state: safeSummary.security.state || null,
-      findings: safeSummary.security.findings || 0,
-      approvals: safeSummary.security.approvals || 0,
-      detail: safeSummary.security.detail || null,
-    });
+  if (role === "security") {
+    const sec = safeSummary.security || {};
+    envelope.security = {
+      state: sec.state || null,
+      findings: sec.findings || 0,
+      approvals: sec.approvals || 0,
+      detail: sec.detail || null,
+    };
   }
 
-  // Integration claims
-  const integrationClaims = [];
-  if (safeSummary.integration) {
-    integrationClaims.push({
-      state: safeSummary.integration.state || null,
-      claims: safeSummary.integration.claims || 0,
-      conflicts: safeSummary.integration.conflicts || 0,
-      blockers: safeSummary.integration.blockers || 0,
-      detail: safeSummary.integration.detail || null,
-    });
+  if (role === "deploy") {
+    const dep = safeSummary.deploy || {};
+    envelope.deploy = {
+      state: dep.state || "not_applicable",
+      environment: dep.environment || null,
+      healthCheck: dep.healthCheck || null,
+      rolloutArtifact: dep.rolloutArtifact || null,
+      detail: dep.detail || null,
+    };
   }
 
-  return {
-    envelopeVersion: 1,
-    agentId: safeAgent.agentId || safeSummary.agentId || null,
-    exitContract,
-    proofArtifacts,
-    deliverables,
-    components,
-    gateClaims,
-    validationOutputs,
-    riskNotes,
-    unresolvedBlockers,
-    docsDeltas,
-    securityFindings,
-    integrationClaims,
-    createdAt: toIsoTimestamp(),
+  return envelope;
+}
+
+/**
+ * Build a v2 envelope from legacy parsed log markers.
+ * Migration adapter: synthesizes the end-state envelope shape from the
+ * output of buildAgentExecutionSummary (which parses log markers).
+ *
+ * This exists so the gate engine always sees a consistent v2 shape,
+ * even when the agent emitted legacy log markers rather than a structured envelope.
+ *
+ * @param {object} agent - Agent definition (must include .agentId, .role)
+ * @param {object} legacySummary - Result from buildAgentExecutionSummary
+ * @param {object} [options] - { waveNumber, attempt, exitCode }
+ * @returns {object} AgentResultEnvelope (schemaVersion 2)
+ */
+export function buildEnvelopeFromLegacySignals(agent, legacySummary, options = {}) {
+  const envelope = buildAgentResultEnvelope(agent, legacySummary, options);
+  envelope._synthesizedFromLegacy = true;
+  return envelope;
+}
+
+export function buildExecutionSummaryFromEnvelope(envelope, options = {}) {
+  if (!envelope || typeof envelope !== "object" || Array.isArray(envelope)) {
+    return null;
+  }
+  const role = inferEnvelopeRole(options.agent || {}, envelope);
+  const proof = envelope.proof && typeof envelope.proof === "object"
+    ? {
+        state: toLegacyProofState(envelope.proof.state),
+        completion: envelope.proof.completion || null,
+        durability: envelope.proof.durability || null,
+        proof: envelope.proof.proofLevel || null,
+        detail: envelope.proof.detail || null,
+      }
+    : null;
+  const summary = {
+    agentId: envelope.agentId || options.agent?.agentId || null,
+    role,
+    waveNumber: envelope.waveNumber ?? options.waveNumber ?? null,
+    attempt: envelope.attempt ?? options.attempt ?? null,
+    completedAt: envelope.completedAt || null,
+    exitCode: typeof envelope.exitCode === "number" ? envelope.exitCode : 0,
+    logPath: toSummaryRelativePath(options.logPath),
+    reportPath: toSummaryRelativePath(options.reportPath),
+    proof,
+    deliverables: Array.isArray(envelope.deliverables)
+      ? envelope.deliverables.map((deliverable) => ({
+          path: deliverable.path || null,
+          exists: deliverable.exists === true,
+          sha256: deliverable.sha256 || null,
+        }))
+      : [],
+    proofArtifacts: Array.isArray(envelope.proofArtifacts)
+      ? envelope.proofArtifacts.map((artifact) => ({
+          path: artifact.path || null,
+          kind: artifact.kind || null,
+          exists: artifact.exists === true,
+          sha256: artifact.sha256 || null,
+          requiredFor: artifact.requiredFor || null,
+        }))
+      : [],
+    gaps: Array.isArray(envelope.gaps)
+      ? envelope.gaps.map((gap) => ({
+          kind: gap.kind || null,
+          detail: gap.detail || null,
+        }))
+      : [],
+    unresolvedBlockers: Array.isArray(envelope.unresolvedBlockers)
+      ? envelope.unresolvedBlockers.map((blocker) => ({
+          kind: blocker.kind || null,
+          detail: blocker.detail || null,
+          blocking: blocker.blocking ?? null,
+        }))
+      : [],
+    riskNotes: Array.isArray(envelope.riskNotes) ? envelope.riskNotes.slice() : [],
+    facts: Array.isArray(envelope.facts)
+      ? envelope.facts.map((fact) => ({
+          factId: fact.factId || null,
+          kind: fact.kind || null,
+          content: fact.content || null,
+        }))
+      : [],
   };
+
+  if (envelope.implementation) {
+    summary.docDelta = {
+      state: envelope.implementation.docDelta?.state || "none",
+      paths: Array.isArray(envelope.implementation.docDelta?.paths)
+        ? envelope.implementation.docDelta.paths
+        : [],
+      detail: envelope.implementation.docDelta?.detail || null,
+    };
+    summary.components = Array.isArray(envelope.implementation.components)
+      ? envelope.implementation.components.map((component) => ({
+          componentId: component.componentId || null,
+          level: component.level || null,
+          state: component.state || null,
+          detail: component.detail || null,
+        }))
+      : [];
+  }
+
+  if (envelope.documentation?.docClosure) {
+    summary.docClosure = {
+      state: envelope.documentation.docClosure.state || "no-change",
+      paths: Array.isArray(envelope.documentation.docClosure.paths)
+        ? envelope.documentation.docClosure.paths
+        : [],
+      detail: envelope.documentation.docClosure.detail || null,
+    };
+  }
+
+  if (envelope.integration) {
+    summary.integration = {
+      state: envelope.integration.state || null,
+      claims: envelope.integration.claims || 0,
+      conflicts: envelope.integration.conflicts || 0,
+      blockers: envelope.integration.blockers || 0,
+      detail: envelope.integration.detail || null,
+    };
+  }
+
+  if (envelope.contEval) {
+    summary.eval = {
+      state: envelope.contEval.state || null,
+      targets: envelope.contEval.targets || 0,
+      benchmarks: envelope.contEval.benchmarks || 0,
+      regressions: envelope.contEval.regressions || 0,
+      targetIds: Array.isArray(envelope.contEval.targetIds) ? envelope.contEval.targetIds : [],
+      benchmarkIds: Array.isArray(envelope.contEval.benchmarkIds) ? envelope.contEval.benchmarkIds : [],
+      detail: envelope.contEval.detail || null,
+    };
+  }
+
+  if (envelope.contQa) {
+    summary.gate = {
+      architecture: envelope.contQa.gateClaims?.architecture || null,
+      integration: envelope.contQa.gateClaims?.integration || null,
+      durability: envelope.contQa.gateClaims?.durability || null,
+      live: envelope.contQa.gateClaims?.live || null,
+      docs: envelope.contQa.gateClaims?.docs || null,
+      detail: envelope.contQa.gateClaims?.detail || null,
+    };
+    summary.verdict = {
+      verdict: envelope.contQa.verdict?.verdict || null,
+      detail: envelope.contQa.verdict?.detail || null,
+    };
+  }
+
+  if (envelope.security) {
+    summary.security = {
+      state: envelope.security.state || null,
+      findings: envelope.security.findings || 0,
+      approvals: envelope.security.approvals || 0,
+      detail: envelope.security.detail || null,
+    };
+  }
+
+  if (envelope.deploy) {
+    summary.deploy = {
+      state: envelope.deploy.state || "not_applicable",
+      environment: envelope.deploy.environment || null,
+      healthCheck: envelope.deploy.healthCheck || null,
+      rolloutArtifact: envelope.deploy.rolloutArtifact || null,
+      detail: envelope.deploy.detail || null,
+    };
+  }
+
+  return summary;
 }
 
 /**