@ecoma-io/archkeep 0.20.1 → 0.22.0

package/src/commands/scenario-evaluation.mjs

@@ -33,10 +33,22 @@
  */
 import { computeImpact } from "./impact.mjs";
 import { computeImpactConstraints } from "./edge-constraints.mjs";
-import { readAdrContext } from "./adr.mjs";
-import { hasAuthority, resolveDecisionRef, stripAdrPrefix } from "../governance/adr-registry.mjs";
-import { isComboDepConstraint } from "../rules/tags.mjs";
-import { execSync } from "node:child_process";
+import {
+  buildDecisionImpact,
+  buildEvolutionAlignment,
+  decisionProvenanceCoverage,
+} from "./evaluation-primitives.mjs";
+import { resolveProvenance } from "./provenance.mjs";
+import {
+  buildGovernanceCompleteness,
+  buildScenarioCompleteness,
+  buildEvidenceComplete,
+  createDomain,
+  EVALUATED,
+  NOT_EVALUATED,
+  evaluationStatus,
+  EVALUATION_CONTRACT_TYPES,
+} from "./completeness.mjs";
 
 // ---------------------------------------------------------------------------
 // Scenario types
@@ -54,6 +66,9 @@ export const SCENARIO_CHANGE_TYPES = Object.freeze(["dependency_added", "depende
  * @property {"dependency_added"|"dependency_removed"} type
  * @property {string} source The source project of the dependency.
  * @property {string} target The target project of the dependency.
+ * @property {string} [edgeType] The dependency edge type (required for
+ *   dependency_added; used for disambiguation in dependency_removed when
+ *   multiple edges exist between the same source+target with different types).
  */
 
 /**
@@ -63,8 +78,6 @@ export const SCENARIO_CHANGE_TYPES = Object.freeze(["dependency_added", "depende
  * @property {DependencyChange[]} changes The hypothetical changes to evaluate.
  */
 
-// ---------------------------------------------------------------------------
-// Output types
 // ---------------------------------------------------------------------------
 /**
  * @typedef {object} ScenarioEvaluation
@@ -73,13 +86,27 @@ export const SCENARIO_CHANGE_TYPES = Object.freeze(["dependency_added", "depende
  * @property {string} project The target project being evaluated.
  * @property {object} base The base graph information.
  * @property {string} base.revision The git revision or snapshot identity.
- * @property {boolean} base.attributed Whether the base is a real, verifiable revision.
- * @property {string} base.provenance How the base was determined (user-provided, auto-resolved, or unverifiable).
+ * @property {string} base.identity One of: "verified", "unverified", "mismatch", "unattributed".
+ * @property {boolean} base.identityVerified Whether the base revision identity was verified against workspace HEAD.
+ * @property {boolean} base.identityMismatch Whether the base revision does not match workspace HEAD.
+ * @property {string} base.provenance How the base was determined.
  * @property {string[]} changes The change descriptions that were applied.
  * @property {string[]|undefined} refused Changes that could not be applied, if any.
  * @property {object} current The current impact for the target project.
  * @property {object} scenario The would-be impact after applying the changes.
  * @property {object} delta What would change.
+ * @property {string[]} delta.dependentsAdded Dependents added in the scenario (flat access).
+ * @property {string[]} delta.dependentsRemoved Dependents removed in the scenario (flat access).
+ * @property {{status: string}} delta.constraintsChanged Whether constraint impacts changed (structured status).
+ * @property {{status: string}} delta.decisionsChanged Whether decisions changed (structured status).
+ * @property {object} delta.structuralDelta Structured delta for dependency changes.
+ * @property {object} delta.governanceDelta Governance-level delta.
+ * @property {{status: string}} delta.governanceDelta.findingsChanged Status: "changed" | "unchanged" | "not_evaluated".
+ * @property {{status: string}} delta.governanceDelta.debtChanged Status: "changed" | "unchanged" | "not_evaluated".
+ * @property {object} delta.evidenceDelta Evidence-level delta metadata.
+ * @property {string} delta.evidenceDelta.baseRevision The revision used as base.
+ * @property {number} delta.evidenceDelta.changesApplied Number of changes applied.
+ * @property {number} delta.evidenceDelta.changesRefused Number of changes refused.
  * @property {object} [evidenceChain] The provenance chain: base → changes → re-evaluated → delta.
  * @property {string} evidenceChain.baseRevision The revision the scenario started from.
  * @property {string[]} evidenceChain.appliedChanges The changes applied to the base.
@@ -87,12 +114,15 @@ export const SCENARIO_CHANGE_TYPES = Object.freeze(["dependency_added", "depende
  * @property {string} evidenceChain.scenarioState The state after applying changes ("scenario").
  * @property {object} evidenceChain.delta The computed differences.
  * @property {object} [governanceImpact] Governance re-evaluation results.
- * @property {boolean} governanceImpact.findingsReEvaluated Whether findings were re-evaluated.
- * @property {boolean} governanceImpact.debtReEvaluated Whether debt was re-evaluated.
+ * @property {boolean} governanceImpact.findingsFiltered Whether precomputed findings were filtered into the scenario state.
+ * @property {boolean} governanceImpact.debtFiltered Whether precomputed debt was filtered into the scenario state.
  * @property {boolean} governanceImpact.governanceComplete Whether all governance data was provided.
  * @property {number} governanceImpact.scenarioFindingsCount Number of findings in the scenario state.
  * @property {number} governanceImpact.scenarioDebtCount Number of debt entries in the scenario state.
- * @property {boolean} complete Whether the evaluation could be fully completed.
+ * @property {string} governanceImpact.findingsStatus EVALUATION_STATUS for findings.
+ * @property {string} governanceImpact.debtStatus EVALUATION_STATUS for debt.
+ * @property {object} completeness Structured completeness from buildScenarioCompleteness.
+ * @property {boolean} complete Backward-compat shorthand: whether all changes were applied (mutationCoverageComplete).
  * @property {string[]} notes Caveats about the evaluation.
  */
 
@@ -107,17 +137,19 @@ export const SCENARIO_CHANGE_TYPES = Object.freeze(["dependency_added", "depende
  * @returns {{nodes: object, dependencies: object}}
  */
 function cloneGraph(graph) {
-  const nodes = { ...graph.nodes };
-  const dependencies = {};
-  for (const [source, edges] of Object.entries(graph.dependencies)) {
-    dependencies[source] = edges.map((e) => ({ ...e }));
-  }
+  const nodes = structuredClone(graph.nodes);
+  const dependencies = structuredClone(graph.dependencies);
   return { nodes, dependencies };
 }
 
 /**
  * Applies a scenario's changes to a graph, producing a would-be graph.
  *
+ * Each change must identify the edge type explicitly. For dependency_added,
+ * the type field is required. For dependency_removed, identity is resolved
+ * by source + target + type. If type is not provided and multiple edges
+ * exist between the same source+target, the mutation is refused as ambiguous.
+ *
  * @param {object} graph The base graph to apply changes to.
  * @param {DependencyChange[]} changes The hypothetical changes.
  * @returns {{graph: object, applied: string[], refused: string[]}}
@@ -144,231 +176,236 @@ function applyChanges(graph, changes) {
         continue;
       }
 
-      // Check if edge already exists
+      // The edge type must be explicit — do not silently invent "static"
+      if (!change.edgeType || typeof change.edgeType !== "string") {
+        refused.push(
+          `cannot add dependency: edge type is required for ${change.source} → ${change.target}`,
+        );
+        continue;
+      }
+
+      // Check if edge already exists (source+target+type identity)
       const existing = cloned.dependencies[change.source] ?? [];
-      if (existing.some((e) => e.target === change.target)) {
-        applied.push(`dependency already exists: ${change.source} → ${change.target}`);
+      if (existing.some((e) => e.target === change.target && e.type === change.edgeType)) {
+        applied.push(
+          `dependency already exists: ${change.source} → ${change.target} (${change.edgeType})`,
+        );
         continue;
       }
 
-      // Add the edge
+      // Add the edge with explicit type
       if (!cloned.dependencies[change.source]) {
         cloned.dependencies[change.source] = [];
       }
       cloned.dependencies[change.source].push({
         target: change.target,
-        type: "static",
+        type: change.edgeType,
         source: change.source,
       });
-      applied.push(`added dependency: ${change.source} → ${change.target}`);
+      applied.push(`added dependency: ${change.source} → ${change.target} (${change.edgeType})`);
     }
 
     if (change.type === "dependency_removed") {
       const existing = cloned.dependencies[change.source] ?? [];
-      const idx = existing.findIndex((e) => e.target === change.target);
-      if (idx === -1) {
+
+      // Use canonical edge identity: source + target + type
+      const matching = existing.filter((e) => {
+        if (e.target !== change.target) return false;
+        if (change.edgeType && e.type !== change.edgeType) return false;
+        return true;
+      });
+
+      if (matching.length === 0) {
+        const typeInfo = change.edgeType ? ` (${change.edgeType})` : "";
         refused.push(
-          `cannot remove dependency: no edge from "${change.source}" to "${change.target}"`,
+          `cannot remove dependency: no edge from "${change.source}" to "${change.target}"${typeInfo}`,
         );
         continue;
       }
-      existing.splice(idx, 1);
-      applied.push(`removed dependency: ${change.source} → ${change.target}`);
-    }
-  }
-
-  return { graph: cloned, applied, refused };
-}
-
-// ---------------------------------------------------------------------------
-// Decision impact (reuses impact-statement's buildDecisionImpact)
-// ---------------------------------------------------------------------------
-
-/**
- * Builds decision impact for the scenario's would-be state.
- *
- * @param {string} root Workspace root path.
- * @param {object[]} constraintImpact Per-dependent constraint analysis.
- * @param {object} config The loaded boundary config.
- * @returns {{decisions: object[], unresolvedDecisionRefs: string[]}|null}
- */
-function buildScenarioDecisionImpact(root, constraintImpact, config) {
-  if (!constraintImpact || !config?.depConstraints) {
-    return { decisions: [], unresolvedDecisionRefs: [] };
-  }
-
-  // Collect unique decisionRefs ONLY from constraint rows that are actually
-  // AFFECTED by the scenario change — rows that govern edges from impacted
-  // dependents. A decisionRef in the config is not enough.
-  const seenRefs = new Set();
-  const affectedRefs = [];
-
-  // Build a set of all constraint rows that appear in constraintImpact,
-  // using identity matching (the rows are the actual config row objects).
-  const activeRows = new Set(constraintImpact.flatMap((entry) => entry.constraintRows));
-
-  for (const row of config.depConstraints) {
-    if (!row.decisionRef) continue;
-    if (activeRows.has(row) && !seenRefs.has(row.decisionRef)) {
-      seenRefs.add(row.decisionRef);
-      affectedRefs.push(row.decisionRef);
-    }
-  }
 
-  if (affectedRefs.length === 0) {
-    return { decisions: [], unresolvedDecisionRefs: [] };
-  }
-
-  let adrContext;
-  try {
-    adrContext = readAdrContext(root);
-  } catch {
-    return { decisions: [], unresolvedDecisionRefs: [...affectedRefs].sort() };
-  }
-
-  const { byId, knownFitness } = adrContext;
-  const unresolvedDecisionRefs = [];
-  const decisions = [];
-
-  for (const ref of affectedRefs) {
-    const resolution = resolveDecisionRef(byId, knownFitness, ref);
-    if (resolution === "unknown") {
-      unresolvedDecisionRefs.push(ref);
-      continue;
-    }
-    if (resolution === "fitness") {
-      decisions.push({ id: ref, kind: "fitness", resolution: "known" });
-      continue;
+      if (matching.length > 1) {
+        // Ambiguous: multiple edges with same source+target but different types,
+        // and no type was specified to disambiguate
+        const types = matching.map((e) => e.type).join(", ");
+        refused.push(
+          `ambiguous removal: multiple edges from "${change.source}" to "${change.target}" ` +
+            `(${types}). Specify edgeType to disambiguate.`,
+        );
+        continue;
+      }
+      // Remove the single matching edge by identity (matching was already computed)
+      const idx = existing.indexOf(matching[0]);
+      existing.splice(idx, 1);
+      const typeLabel = change.edgeType ? ` (${change.edgeType})` : "";
+      applied.push(`removed dependency: ${change.source} → ${change.target}${typeLabel}`);
     }
-    const record = byId.get(stripAdrPrefix(ref));
-    decisions.push({
-      id: record.id,
-      kind: "adr",
-      status: record.status,
-      hasAuthority: hasAuthority(record.status),
-    });
   }
-
-  return {
-    decisions: decisions.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0)),
-    unresolvedDecisionRefs: [...new Set(unresolvedDecisionRefs)].sort(),
-  };
-}
-
-/**
- * Builds evolution alignment for the scenario.
- *
- * @param {string} projectName The target project.
- *
- * @param {object[]} [constraintImpact]
- * @param {string[]} [resolvedDecisions]
- * @returns {{projects: string[], boundaries: string[], constraints: string[], decisions: string[]}}
- */
-function buildScenarioEvolutionAlignment(projectName, impact, constraintImpact, resolvedDecisions) {
-  const affectedProjects = [projectName, ...impact.dependents];
-  const affectedConstraints = [];
-  const affectedBoundaries = [];
-
-  if (constraintImpact) {
-    for (const entry of constraintImpact) {
-      // Collect edge identities for each affected boundary
-      for (const edge of entry.edges) {
-        const edgeId = `${entry.project}>${edge.target}:${edge.type}`;
-        if (!affectedBoundaries.includes(edgeId)) {
-          affectedBoundaries.push(edgeId);
-        }
-      }
-      // Collect constraint row labels using same format as buildEvolutionAlignment
-      for (const row of entry.constraintRows) {
-        const label = isComboDepConstraint(row)
-          ? `allSourceTags:${row.allSourceTags.join(",")}`
-          : `sourceTag:${row.sourceTag}`;
-        if (!affectedConstraints.includes(label)) {
-          affectedConstraints.push(label);
-        }
-      }
+  // Clean up empty dependency arrays
+  for (const [source, edges] of Object.entries(cloned.dependencies)) {
+    if (edges.length === 0) {
+      delete cloned.dependencies[source];
     }
   }
 
-  return {
-    projects: [...new Set(affectedProjects)].sort(),
-    boundaries: affectedBoundaries.sort(),
-    constraints: affectedConstraints.sort(),
-    decisions: resolvedDecisions ? [...new Set(resolvedDecisions)].sort() : [],
-  };
+  return { graph: cloned, applied, refused };
 }
 
 /**
  * Computes the delta between current and scenario.
  *
+ * All boolean delta fields are replaced with structured status objects
+ * to avoid boolean information loss. Each status is one of:
+ * - "changed": the value differs between current and scenario
+ * - "unchanged": the value is identical
+ * - "not_evaluated": the comparison could not be performed
+ *
  * @param {object} current Current impact.
  * @param {object} scenario Scenario impact.
+ * @param {object} [extra] Additional context for structured delta sections.
+ * @param {string} [extra.baseRevision] The base revision used.
+ * @param {number} [extra.changesApplied] Number of changes applied.
+ * @param {number} [extra.changesRefused] Number of changes refused.
+ * @param {string} [extra.findingsChanged] Status: "changed" | "unchanged" | "not_evaluated".
+ * @param {string} [extra.debtChanged] Status: "changed" | "unchanged" | "not_evaluated".
  * @returns {{dependentsAdded: string[], dependentsRemoved: string[],
- *   constraintsChanged: boolean, decisionsChanged: boolean}}
+ *   constraintsChanged: {status: string}, decisionsChanged: {status: string},
+ *   structuralDelta: {dependentsAdded: string[], dependentsRemoved: string[]},
+ *   governanceDelta: {findingsChanged: {status: string}, debtChanged: {status: string}},
+ *   evidenceDelta: {baseRevision: string, changesApplied: number, changesRefused: number}}}
  */
-function computeDelta(current, scenario) {
+function computeDelta(current, scenario, extra = {}) {
   const currentDeps = new Set(current.impact.dependents ?? []);
   const scenarioDeps = new Set(scenario.impact.dependents ?? []);
 
   const dependentsAdded = [...scenarioDeps].filter((d) => !currentDeps.has(d)).sort();
   const dependentsRemoved = [...currentDeps].filter((d) => !scenarioDeps.has(d)).sort();
 
-  const constraintsChanged =
-    JSON.stringify(current.constraintImpact ?? []) !==
-    JSON.stringify(scenario.constraintImpact ?? []);
+  const constraintsChanged = {
+    status:
+      JSON.stringify(current.constraintImpact ?? []) !==
+      JSON.stringify(scenario.constraintImpact ?? [])
+        ? "changed"
+        : "unchanged",
+  };
 
-  const decisionsChanged =
-    JSON.stringify(current.decisionImpact ?? []) !== JSON.stringify(scenario.decisionImpact ?? []);
+  const decisionsChanged = {
+    status:
+      JSON.stringify(current.decisionImpact ?? []) !== JSON.stringify(scenario.decisionImpact ?? [])
+        ? "changed"
+        : "unchanged",
+  };
+
+  // Use structured status for governance changes
+  const findingsStatus = extra.findingsChanged ?? "not_evaluated";
+  const debtStatus = extra.debtChanged ?? "not_evaluated";
 
   return {
     dependentsAdded,
     dependentsRemoved,
     constraintsChanged,
     decisionsChanged,
+    structuralDelta: {
+      dependentsAdded,
+      dependentsRemoved,
+    },
+    governanceDelta: {
+      findingsChanged: { status: findingsStatus },
+      debtChanged: { status: debtStatus },
+    },
+    evidenceDelta: {
+      baseRevision: extra.baseRevision ?? "(unknown)",
+      changesApplied: extra.changesApplied ?? 0,
+      changesRefused: extra.changesRefused ?? 0,
+    },
   };
 }
+
 /**
- * Resolves the base revision for a scenario evaluation.
+ * Resolves the base revision for a scenario, with explicit identity verification.
  *
- * When the user provides a `base` string, it is used as-is and marked as
- * attributed. When no base is provided, we attempt to resolve from
- * `git rev-parse HEAD`. If that fails, we report the gap rather than
- * fabricating a revision.
+ * The following identity states are represented:
+ * - verified: the base revision matches the verified workspace HEAD
+ * - unverified: the base revision could not be verified against workspace state
+ * - mismatch: the base revision differs from the verified workspace HEAD
+ * - unattributed: no git revision could be resolved
  *
  * @param {string} root The workspace root.
- * @param {string|undefined} userBase The user-provided base (optional).
- * @returns {{revision: string, attributed: boolean, provenance: string}}
+ * @param {string} [userBase] Optional user-provided base revision.
+ * @returns {{revision: string, identity: string, provenance: string,
+ *   identityVerified: boolean, identityMismatch: boolean}}
  */
 function resolveBaseRevision(root, userBase) {
+  let workspaceHead = null;
+  let isDirty = false;
+  try {
+    const provenance = resolveProvenance(root);
+    if (provenance && provenance.commit && provenance.commit.length > 0) {
+      workspaceHead = provenance.commit;
+      isDirty = !!provenance.dirty;
+    }
+  } catch {
+    // Provenance unavailable — will use "(unknown)" below
+  }
+
   if (typeof userBase === "string" && userBase.length > 0) {
+    // User-provided base — verify against workspace HEAD
+    if (workspaceHead) {
+      if (isDirty) {
+        // Dirty tree: cannot verify relationship
+        return {
+          revision: userBase,
+          identity: "unverified",
+          identityVerified: false,
+          identityMismatch: false,
+          provenance: `user-provided (HEAD is ${workspaceHead}, dirty — identity unverifiable)`,
+        };
+      }
+      if (userBase === workspaceHead) {
+        return {
+          revision: userBase,
+          identity: "verified",
+          identityVerified: true,
+          identityMismatch: false,
+          provenance: `user-provided (matches HEAD ${workspaceHead})`,
+        };
+      }
+      // User-provided base does not match HEAD
+      return {
+        revision: userBase,
+        identity: "mismatch",
+        identityVerified: false,
+        identityMismatch: true,
+        provenance: `user-provided (HEAD is ${workspaceHead}, requested ${userBase})`,
+      };
+    }
+
+    // No workspace HEAD to verify against
     return {
       revision: userBase,
-      attributed: true,
-      provenance: "user-provided",
+      identity: "unverified",
+      identityVerified: false,
+      identityMismatch: false,
+      provenance: "user-provided (could not verify — no git HEAD available)",
     };
   }
 
-  // Attempt to resolve from git
-  try {
-    const revision = execSync("git rev-parse HEAD", {
-      cwd: root,
-      encoding: "utf8",
-      timeout: 5000,
-    }).trim();
-    if (revision && revision.length === 40) {
-      return {
-        revision,
-        attributed: true,
-        provenance: "auto-resolved: git rev-parse HEAD",
-      };
-    }
-  } catch {
-    // Fall through to unverifiable
+  // Auto-resolve from git
+  if (workspaceHead) {
+    const suffix = isDirty ? " (dirty)" : "";
+    return {
+      revision: workspaceHead,
+      identity: isDirty ? "unverified" : "verified",
+      identityVerified: !isDirty,
+      identityMismatch: false,
+      provenance: `auto-resolved: git commit ${workspaceHead}${suffix}`,
+    };
   }
 
   return {
     revision: "(unattributed workspace)",
-    attributed: false,
+    identity: "unattributed",
+    identityVerified: false,
+    identityMismatch: false,
     provenance: "unverifiable — git rev-parse HEAD failed or not a git repository",
   };
 }
@@ -432,12 +469,8 @@ export function evaluateScenario(
   }
 
   // Step 5: Build decision impact for both sides
-  const currentDecisionImpact = buildScenarioDecisionImpact(root, currentConstraintImpact, config);
-  const scenarioDecisionImpact = buildScenarioDecisionImpact(
-    root,
-    scenarioConstraintImpact,
-    config,
-  );
+  const currentDecisionImpact = buildDecisionImpact(root, currentConstraintImpact, config);
+  const scenarioDecisionImpact = buildDecisionImpact(root, scenarioConstraintImpact, config);
 
   // Step 6: Build evolution alignment for both sides
   const currentResolved = currentDecisionImpact
@@ -447,13 +480,13 @@ export function evaluateScenario(
     ? scenarioDecisionImpact.decisions.map((d) => d.id)
     : [];
 
-  const currentEvolution = buildScenarioEvolutionAlignment(
+  const currentEvolution = buildEvolutionAlignment(
     projectName,
     currentImpact,
     currentConstraintImpact,
     currentResolved,
   );
-  const scenarioEvolution = buildScenarioEvolutionAlignment(
+  const scenarioEvolution = buildEvolutionAlignment(
     projectName,
     scenarioImpact,
     scenarioConstraintImpact,
@@ -471,9 +504,14 @@ export function evaluateScenario(
     constraintImpact: scenarioConstraintImpact,
     decisionImpact: scenarioDecisionImpact,
   };
-  const delta = computeDelta(currentState, scenarioState);
-
-  // Step 8: Build evidence chain
+  const delta = computeDelta(currentState, scenarioState, {
+    baseRevision: base.revision,
+    changesApplied: applied.length,
+    changesRefused: refused.length,
+    // Governance was NOT re-evaluated — filtering is not evaluation
+    findingsChanged: "not_evaluated",
+    debtChanged: "not_evaluated",
+  });
   const evidenceChain = {
     baseRevision: base.revision,
     appliedChanges: applied,
@@ -484,6 +522,9 @@ export function evaluateScenario(
       dependentsRemoved: delta.dependentsRemoved,
       constraintsChanged: delta.constraintsChanged,
       decisionsChanged: delta.decisionsChanged,
+      structuralDelta: delta.structuralDelta,
+      governanceDelta: delta.governanceDelta,
+      evidenceDelta: delta.evidenceDelta,
     },
   };
 
@@ -492,11 +533,24 @@ export function evaluateScenario(
   let scenarioFindings = null;
   let scenarioDebt = null;
   if (availableFindings) {
-    // Re-filter findings for the hypothetical graph's affected projects
+    // Build set of edges that were removed in this scenario
+    const removedEdges = new Set();
+    for (const change of scenarioInput.changes) {
+      if (change.type === "dependency_removed") {
+        removedEdges.add(`${change.source}|${change.target}`);
+      }
+    }
+
+    // Re-filter findings for the hypothetical graph's affected projects,
+    // excluding findings whose edge was removed
     const affectedSet = new Set(scenarioAffectedProjects);
     scenarioFindings = availableFindings.filter((f) => {
+      // Check if this finding's edge was removed
       const source = f.source ?? f.project ?? "";
       const target = f.target ?? "";
+      if (removedEdges.has(`${source}|${target}`)) {
+        return false; // edge no longer exists in hypothetical graph
+      }
       return affectedSet.has(source) || affectedSet.has(target);
     });
   }
@@ -537,11 +591,113 @@ export function evaluateScenario(
     notes.push(`changes that could not be applied: ${refused.join("; ")}`);
   }
   // Step 11: Assemble — determine provenance and completeness semantics
-  // `complete` reflects whether the core evaluation (graph + constraints)
-  // completed. `governanceComplete` tracks whether governance dimensions
-  // were fully evaluated.
-  const governanceComplete = availableFindings !== null && availableDebt !== null;
-  const isComplete = refused.length === 0;
+  //
+  // Governance filtering (re-applying precomputed findings/debt to the
+  // hypothetical graph) is NOT governance re-evaluation. True re-evaluation
+  // would run the full check pipeline against the hypothetical graph.
+  // When we only filter, governance is NOT_EVALUATED.
+  const findingsFiltered = availableFindings !== null;
+  const debtFiltered = availableDebt !== null;
+
+  // Filtering is NOT re-evaluation (the header above), so the status is
+  // NOT_EVALUATED on both paths — no re-evaluation pipeline exists to pass.
+  // Telling a consumer "evaluated" for a filter is the mislabel this refuses.
+  const findingsStatus = evaluationStatus({
+    evaluated: false,
+    notEvaluated: true,
+  });
+  const debtStatus = evaluationStatus({
+    evaluated: false,
+    notEvaluated: true,
+  });
+
+  // Build governance completeness
+  const governanceCompleteness = buildGovernanceCompleteness({
+    findingsStatus,
+    debtStatus,
+    findingsCount: scenarioFindings?.length ?? 0,
+    debtCount: scenarioDebt?.length ?? 0,
+  });
+
+  // Determine mutation coverage completeness
+  const totalChanges = scenarioInput.changes.length;
+  const appliedCount = applied.length;
+  const refusedCount = refused.length;
+  const mutationCoverageComplete = totalChanges === appliedCount && refusedCount === 0;
+
+  // Build the scenario's domain statuses FIRST — the Evidence-Complete
+  // contract below derives its hidden-gap gate from them, so a domain that
+  // is NOT_EVALUATED without a note flips that gate, and a domain that
+  // skips with a stated reason does not.
+  //   structural — always evaluated (scenario builds a complete graph).
+  //   constraint, boundary, decision — require a boundary config; decision
+  //     follows the config exactly as the canonical face reads it, because
+  //     the scenario runs decision impact (buildDecisionImpact above) when
+  //     one is present. The condition this replaces, `config.decisionRefs`,
+  //     named a field no workspace can declare — it held the decision domain
+  //     at NOT_EVALUATED forever, a permanent hidden gap on every configured
+  //     workspace.
+  //   findings, debt — never re-evaluated in a scenario; the notes say so,
+  //     which is what keeps them disclosed and out of the hidden-gap count.
+  //   evidence — always evaluated (we build the EC contract).
+  const hasConfig = config !== null;
+  const configGapNote =
+    "No boundary config — constraint, boundary and decision rules not evaluated";
+  const configGated = () =>
+    hasConfig ? createDomain(EVALUATED) : createDomain(NOT_EVALUATED, configGapNote);
+  const scenarioDomains = {
+    structural: createDomain(EVALUATED),
+    constraint: configGated(),
+    boundary: configGated(),
+    decision: configGated(),
+    findings:
+      governanceCompleteness.findings.status === NOT_EVALUATED
+        ? createDomain(NOT_EVALUATED, "Findings not re-evaluated in scenario")
+        : governanceCompleteness.findings,
+    debt:
+      governanceCompleteness.debt.status === NOT_EVALUATED
+        ? createDomain(NOT_EVALUATED, "Debt not re-evaluated in scenario")
+        : governanceCompleteness.debt,
+    evidence: createDomain(EVALUATED),
+  };
+
+  // Hidden gaps: NOT_EVALUATED domains without a stated reason — the same
+  // derivation `deriveEvidenceGates` runs for the canonical face, so neither
+  // face can pass the gate on a literal while the other fails on facts.
+  let scenarioHiddenGapCount = 0;
+  for (const domainStatus of Object.values(scenarioDomains)) {
+    if (domainStatus.status === NOT_EVALUATED && !domainStatus.note) {
+      scenarioHiddenGapCount++;
+    }
+  }
+
+  // Derive evidence gates for scenario evaluation and build Evidence-Complete contract.
+  // Scenario mutation is deterministic: same inputs → same outputs (pure graph clone + apply).
+  // surfaceParity: the scenario applied all requested changes (refused===0), so the
+  // hypothetical surface is internally consistent — no surface drift from the plan.
+  const surfaceParity = refusedCount === 0 ? 1 : 0;
+
+  const evidenceComplete = buildEvidenceComplete({
+    domainCoverage: currentDecisionImpact !== null ? 1 : 0,
+    claimEvidenceCoverage: config !== null ? 1 : 0,
+    causalCoverage: currentConstraintImpact !== null ? 1 : 0,
+    provenanceCoverage: decisionProvenanceCoverage(currentDecisionImpact?.decisions),
+    mutationCoverage: mutationCoverageComplete ? 1 : 0,
+    surfaceParity,
+    hiddenGapCount: scenarioHiddenGapCount,
+    falseCompleteCount: 0,
+    baseIdentityValid: base.identityVerified,
+    deterministic: true,
+    contractType: EVALUATION_CONTRACT_TYPES.SCENARIO,
+  });
+  const scenarioCompleteness = buildScenarioCompleteness({
+    changesComplete: mutationCoverageComplete,
+    baseIdentityVerified: base.identityVerified,
+    mutationCoverageComplete,
+    governance: governanceCompleteness,
+    evidenceComplete,
+    domains: scenarioDomains,
+  });
 
   return {
     virtual: true,
@@ -576,14 +732,17 @@ export function evaluateScenario(
       ...(scenarioDebt !== null ? { debt: scenarioDebt } : {}),
     },
     governanceImpact: {
-      findingsReEvaluated: availableFindings !== null,
-      debtReEvaluated: availableDebt !== null,
-      governanceComplete,
+      findingsFiltered,
+      debtFiltered,
+      governanceComplete: false,
       scenarioFindingsCount: scenarioFindings?.length ?? 0,
       scenarioDebtCount: scenarioDebt?.length ?? 0,
+      findingsStatus,
+      debtStatus,
     },
     delta,
-    complete: isComplete,
+    completeness: scenarioCompleteness,
+    complete: scenarioCompleteness.overallComplete,
     notes,
   };
 }
@@ -637,6 +796,12 @@ export function parseScenarioInput(jsonString) {
 
   return {
     base: typeof parsed.base === "string" ? parsed.base : undefined,
-    changes: changes.map((c) => ({ type: c.type, source: c.source, target: c.target })),
+    changes: changes.map((c) => {
+      const change = { type: c.type, source: c.source, target: c.target };
+      if (c.edgeType && typeof c.edgeType === "string") {
+        change.edgeType = c.edgeType;
+      }
+      return change;
+    }),
   };
 }