@ecoma-io/archkeep 0.21.0 → 0.22.1

package/src/commands/impact.mjs

@@ -35,9 +35,9 @@
  * under project roots, `impact` refuses loudly rather than returning a result
  * whose dependents silently under-represent the real architecture.
  */
-import { isWholeFileFailure } from "../analysis/source-util.mjs";
 import { UsageError } from "../errors.mjs";
 import { computeImpactConstraints } from "./edge-constraints.mjs";
+import { coverageRefusal, coverageVerdict } from "./coverage-verdict.mjs";
 import { jsonEnvelope, renderJson } from "../report/json.mjs";
 import { formatImpactReport } from "../report/impact-text.mjs";
 import { resolveProvenance } from "./provenance.mjs";
@@ -123,11 +123,14 @@ export function computeImpact(projectName, graph) {
  * @param {object} commandContext From `resolveCommandContext`.
  * @param {object} [config] The loaded boundary config. When provided,
  *   constraint context and violations for each dependent edge are computed.
- * @returns {{status: "ok"|"no-verdict", impact: object, coverage: object,
+ * @returns {{status: "ok"|"no-verdict", impact?: object, coverage: object,
  *   report: {text: string, json: string}}}
+ *   `status: "no-verdict"` carries no `impact` payload — the verdict was
+ *   withheld, and the envelope's `coverage` block is the whole answer (#608).
  * @throws {Error} when an Nx workspace has polyglot manifests but the plugin
- *   is not registered, or when the named project does not exist in the graph,
- *   or when the graph has incomplete coverage.
+ *   is not registered, or when the named project does not exist in the graph.
+ *   Incomplete coverage returns the structured no-verdict envelope instead of
+ *   throwing (#608).
  */
 export function impactCommand(projectName, commandContext, config = null) {
   const { root, provider, marker, graph, pluginGap } = commandContext;
@@ -150,22 +153,18 @@ export function impactCommand(projectName, commandContext, config = null) {
   // project before the run invests in anything else.
   const impact = computeImpact(projectName, graph);
 
-  const notAnalyzed = commandContext.analysis.failures
-    .filter(isWholeFileFailure)
-    .map(({ sourceFile, reason }) => ({ file: sourceFile, reason }));
-
-  if (notAnalyzed.length > 0) {
-    throw new Error(
-      `archkeep: the graph has incomplete coverage — ${notAnalyzed.length} file` +
-        `${notAnalyzed.length === 1 ? "" : "s"} could not be analyzed, so the impact set may ` +
-        `under-represent the real architecture. Fix the unanalyzed files and re-run.`,
-    );
+  // The impact set is a claim about the tree the run read, refused through the
+  // one structured contract `./coverage-verdict.mjs` builds (#608): the
+  // verdict is withheld in-band — status "no-verdict", exit 3, a `coverage`
+  // block naming every file and site the run could not judge — where a parser
+  // and `--output` can read it, not on stderr where only a human can.
+  const completeness = coverageVerdict(commandContext);
+  if (!completeness.complete) {
+    return coverageRefusal({ command: "impact", commandContext, what: "computing impact" });
   }
-  const blindSpots = commandContext.analysis.failures
-    .filter((f) => !isWholeFileFailure(f))
-    .map(({ sourceFile, line, column, reason }) => ({ file: sourceFile, line, column, reason }));
+  const blindSpots = completeness.blindSpots;
 
-  const complete = true; // whole-file failures already threw above
+  const complete = true; // the incompleteness cases all returned above
   const status = "ok";
   const exitCode = 0;
 

package/src/commands/plan-context-command.mjs

@@ -64,7 +64,11 @@ import { statSync } from "node:fs";
 import { join } from "node:path";
 
 import { INTENT_FILE, loadIntent } from "../architecture-intent/model.mjs";
-import { isWholeFileFailure } from "../analysis/source-util.mjs";
+import {
+  blindSpotRows,
+  isWholeFileFailure,
+  unresolvableLiteralCount,
+} from "../analysis/source-util.mjs";
 import { tsconfigPathsFacts } from "../analysis/typescript.mjs";
 import { compareGoWork, parseGoWorkUse } from "../go-work.mjs";
 import { judgeTsconfigPaths } from "../tsconfig-paths.mjs";
@@ -497,7 +501,10 @@ export async function planContextCommand(
         (a.messageId < b.messageId ? -1 : a.messageId > b.messageId ? 1 : 0),
     );
 
-  const complete = notAnalyzed.length === 0;
+  // An unresolvable literal site is work the run saw but never judged
+  // (#595, narrowed): a plan over it would present edges the run does not
+  // hold, so it defeats completeness the way a whole-file failure does.
+  const complete = notAnalyzed.length === 0 && unresolvableLiteralCount(failures) === 0;
   const status = complete ? "ok" : "no-verdict";
   const exitCode = complete ? 0 : 3;
 
@@ -525,9 +532,7 @@ export async function planContextCommand(
     analyzedFiles: wholeTree.analyzed,
     imports: wholeTree.imports.length,
     notAnalyzed,
-    blindSpots: failures
-      .filter((failure) => !isWholeFileFailure(failure))
-      .map(({ sourceFile, line, column, reason }) => ({ file: sourceFile, line, column, reason })),
+    blindSpots: blindSpotRows(failures),
     // Intent's own coverage notes ride the same seam `check` threads them on
     // (today only an `"optional": true` allowed row whose statement is absent),
     // so the plan's text and JSON reports read the same notes `check` does.

package/src/commands/reconcile.mjs

@@ -43,9 +43,10 @@
  * comparison (never `localeCompare`), so two runs over an unchanged tree and
  * intent produce byte-identical text and JSON.
  */
-import { isWholeFileFailure } from "../analysis/source-util.mjs";
+import { blindSpotRows } from "../analysis/source-util.mjs";
 import { jsonEnvelope, renderJson } from "../report/json.mjs";
 import { resolveProvenance } from "./provenance.mjs";
+import { coverageRefusal, coverageVerdict } from "./coverage-verdict.mjs";
 import { judgeIntent } from "../architecture-intent/judge.mjs";
 import { computeIntentFingerprint } from "../architecture-intent/intent-fingerprint.mjs";
 import { INTENT_FILE, loadIntent } from "../architecture-intent/model.mjs";
@@ -84,9 +85,12 @@ function intentRows(intent) {
  * @param {{loadIntentOverride?: (root: string) => Promise<object>}} [io]
  *   Injectable intent loader for tests.
  * @param {{propose?: boolean}} [options] `--propose` adds the ranked candidate list.
- * @returns {Promise<{status: "ok", reconcile: object, coverage: object,
+ * @returns {Promise<{status: "ok"|"no-verdict", reconcile?: object, coverage: object,
  *   report: {text: string, json: string}}>}
- * @throws {Error} on every condition the header lists, all exit-3 class.
+ *   `status: "no-verdict"` carries no `reconcile` payload — the verdict was
+ *   withheld, and the envelope's `coverage` block is the whole answer (#608).
+ * @throws {Error} on every condition the header lists except the coverage one,
+ *   which returns instead of throwing.
  */
 export async function reconcileCommand(commandContext, io = {}, options = {}) {
   const { root, provider, marker, analysis } = commandContext;
@@ -94,17 +98,12 @@ export async function reconcileCommand(commandContext, io = {}, options = {}) {
   refuseIncompleteGraph(commandContext);
 
   // A reconcile verdict cannot be established over a tree it could not fully
-  // read — the same fail-closed condition `drift` enforces.
-  const notAnalyzed = analysis.failures
-    .filter(isWholeFileFailure)
-    .map(({ sourceFile, reason }) => ({ file: sourceFile, reason }));
-
-  if (notAnalyzed.length > 0) {
-    throw new Error(
-      `archkeep: reconcile has incomplete coverage — ${notAnalyzed.length} file` +
-        `${notAnalyzed.length === 1 ? "" : "s"} could not be analyzed, so every "absent" score ` +
-        `would be ambiguous between "gone" and "never seen". Fix the unanalyzed files and re-run.`,
-    );
+  // read — the same fail-closed condition `drift` enforces, refused through
+  // the same structured envelope `./coverage-verdict.mjs` builds (#608): the
+  // verdict is withheld in-band, where a parser and `--output` can read it.
+  const completeness = coverageVerdict(commandContext);
+  if (!completeness.complete) {
+    return coverageRefusal({ command: "reconcile", commandContext, what: "reconciling" });
   }
 
   const intent = await (io.loadIntentOverride ?? loadIntent)(root, {
@@ -146,9 +145,7 @@ export async function reconcileCommand(commandContext, io = {}, options = {}) {
     // Reconcile reads only the graph — provider failures are the same blind
     // spots every other command reports, and a blind spot never prevents a
     // verdict.
-    blindSpots: analysis.failures
-      .filter((failure) => !isWholeFileFailure(failure))
-      .map(({ sourceFile, line, column, reason }) => ({ file: sourceFile, line, column, reason })),
+    blindSpots: blindSpotRows(analysis.failures),
     // Coverage notes (e.g. an `optional: true` allowed row the team has not
     // built yet) ride here so "optional and absent" never reads as "never
     // checked".

package/src/commands/scenario-evaluation.mjs

@@ -33,12 +33,21 @@
  */
 import { computeImpact } from "./impact.mjs";
 import { computeImpactConstraints } from "./edge-constraints.mjs";
-import { buildDecisionImpact, buildEvolutionAlignment } from "./evaluation-primitives.mjs";
+import {
+  buildDecisionImpact,
+  buildEvolutionAlignment,
+  decisionProvenanceCoverage,
+} from "./evaluation-primitives.mjs";
 import { resolveProvenance } from "./provenance.mjs";
 import {
-  buildScenarioCompleteness,
   buildGovernanceCompleteness,
+  buildScenarioCompleteness,
+  buildEvidenceComplete,
+  createDomain,
+  EVALUATED,
+  NOT_EVALUATED,
   evaluationStatus,
+  EVALUATION_CONTRACT_TYPES,
 } from "./completeness.mjs";
 
 // ---------------------------------------------------------------------------
@@ -105,8 +114,8 @@ 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.
@@ -587,17 +596,19 @@ export function evaluateScenario(
   // 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 findingsReEvaluated = availableFindings !== null;
-  const debtReEvaluated = availableDebt !== null;
+  const findingsFiltered = availableFindings !== null;
+  const debtFiltered = availableDebt !== null;
 
-  // Mark governance as NOT_EVALUATED when not truly re-evaluated
+  // 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, // filtering is NOT evaluation
-    notEvaluated: !findingsReEvaluated,
+    evaluated: false,
+    notEvaluated: true,
   });
   const debtStatus = evaluationStatus({
-    evaluated: false, // filtering is NOT evaluation
-    notEvaluated: !debtReEvaluated,
+    evaluated: false,
+    notEvaluated: true,
   });
 
   // Build governance completeness
@@ -614,12 +625,78 @@ export function evaluateScenario(
   const refusedCount = refused.length;
   const mutationCoverageComplete = totalChanges === appliedCount && refusedCount === 0;
 
-  // Build overall scenario completeness
+  // 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 {
@@ -655,9 +732,9 @@ export function evaluateScenario(
       ...(scenarioDebt !== null ? { debt: scenarioDebt } : {}),
     },
     governanceImpact: {
-      findingsReEvaluated,
-      debtReEvaluated,
-      governanceComplete: false, // filtering is NOT evaluation
+      findingsFiltered,
+      debtFiltered,
+      governanceComplete: false,
       scenarioFindingsCount: scenarioFindings?.length ?? 0,
       scenarioDebtCount: scenarioDebt?.length ?? 0,
       findingsStatus,
@@ -665,7 +742,7 @@ export function evaluateScenario(
     },
     delta,
     completeness: scenarioCompleteness,
-    complete: mutationCoverageComplete,
+    complete: scenarioCompleteness.overallComplete,
     notes,
   };
 }

package/src/commands/scenario.mjs

@@ -11,7 +11,7 @@
  */
 import { resolveProvenance } from "./provenance.mjs";
 import { jsonEnvelope, renderJson } from "../report/json.mjs";
-import { isWholeFileFailure } from "../analysis/source-util.mjs";
+import { coverageRefusal, coverageVerdict } from "./coverage-verdict.mjs";
 import { evaluateScenario, parseScenarioInput } from "./scenario-evaluation.mjs";
 export { parseScenarioInput } from "./scenario-evaluation.mjs";
 
@@ -23,7 +23,10 @@ export { parseScenarioInput } from "./scenario-evaluation.mjs";
  * @param {string} scenarioJson The scenario description as JSON.
  * @param {object} commandContext From `resolveCommandContext`.
  * @param {object} [config] The loaded boundary config.
- * @returns {{status: string, scenario: object, coverage: object, report: {text: string, json: string}}}
+ * @returns {{status: "ok"|"no-verdict", scenario?: object, coverage: object,
+ *   report: {text: string, json: string}}} `scenario` is absent under
+ *   `status: "no-verdict"` — the coverage refusal (#608) withholds the
+ *   evaluation, and the envelope's `coverage` block is the whole answer.
  */
 export function scenarioCommand(projectName, scenarioJson, commandContext, config = null) {
   const { root, provider, marker, graph, pluginGap } = commandContext;
@@ -44,17 +47,12 @@ export function scenarioCommand(projectName, scenarioJson, commandContext, confi
   // Parse the scenario input
   const scenarioInput = parseScenarioInput(scenarioJson);
 
-  // Check coverage
-  const notAnalyzed = commandContext.analysis.failures
-    .filter(isWholeFileFailure)
-    .map(({ sourceFile, reason }) => ({ file: sourceFile, reason }));
-
-  if (notAnalyzed.length > 0) {
-    throw new Error(
-      `archkeep: the graph has incomplete coverage — ${notAnalyzed.length} file` +
-        `${notAnalyzed.length === 1 ? "" : "s"} could not be analyzed, so the scenario may ` +
-        `under-represent the real architecture. Fix the unanalyzed files and re-run.`,
-    );
+  // Check coverage — refused through the one structured contract
+  // `./coverage-verdict.mjs` builds (#608): the evaluation is withheld
+  // in-band, where a parser and `--output` can read it.
+  const completeness = coverageVerdict(commandContext);
+  if (!completeness.complete) {
+    return coverageRefusal({ command: "scenario", commandContext, what: "evaluating a scenario" });
   }
 
   // Evaluate
@@ -66,9 +64,7 @@ export function scenarioCommand(projectName, scenarioJson, commandContext, confi
     analyzedFiles: commandContext.analysis.analyzed,
     imports: commandContext.analysis.imports.length,
     notAnalyzed: [],
-    blindSpots: commandContext.analysis.failures
-      .filter((f) => !isWholeFileFailure(f))
-      .map(({ sourceFile, line, column, reason }) => ({ file: sourceFile, line, column, reason })),
+    blindSpots: completeness.blindSpots,
     notes: [
       "scenario evaluation is virtual and not authoritative — run `check` for the real verdict",
       "per-edge verdicts cover only depConstraints (3 of 15 violation types)",
@@ -103,7 +99,7 @@ export function scenarioCommand(projectName, scenarioJson, commandContext, confi
     result,
   });
 
-  const text = formatScenarioReport(scenario);
+  const text = formatScenarioReport(scenario, coverage);
 
   return {
     status: "ok",
@@ -119,15 +115,29 @@ export function scenarioCommand(projectName, scenarioJson, commandContext, confi
 /**
  * Formats a scenario evaluation as terminal text.
  *
+ * The coverage line rides the same `coverageIncompleteReasons` clauses every
+ * other text face uses (`../verdict.mjs`), so a terminal reader is told how
+ * much of the tree the comparison inspected, in the one wording the JSON
+ * envelope's status also speaks (#609).
+ *
  * @param {object} scenario The scenario evaluation result.
+ * @param {object} coverage The run's coverage block.
  * @returns {string}
  */
-function formatScenarioReport(scenario) {
+function formatScenarioReport(scenario, coverage) {
   const lines = [];
 
   lines.push(`Scenario evaluation for "${scenario.project}"`);
   lines.push(`${"=".repeat(50)}`);
   lines.push(`Virtual: ${scenario.virtual}  |  Not authoritative: ${scenario.notAuthoritative}`);
+  // The "how much was inspected" line, derived from the same coverage block
+  // the envelope carries — never re-counted here.
+  lines.push(
+    `Coverage: ${coverage.imports} import${coverage.imports === 1 ? "" : "s"} in ` +
+      `${coverage.analyzedFiles} file${coverage.analyzedFiles === 1 ? "" : "s"} across ` +
+      `${coverage.projects} project${coverage.projects === 1 ? "" : "s"}` +
+      (coverage.complete ? "" : " — coverage incomplete"),
+  );
   lines.push("");
 
   if (scenario.changes.length > 0) {

package/src/commands/waivers.mjs

@@ -37,10 +37,11 @@
  * `now` and the output is reproducible byte-for-byte. Defaults to the wall
  * clock, the same injection `evaluate` uses for waiver expiry.
  */
-import { isWholeFileFailure } from "../analysis/source-util.mjs";
+import { blindSpotRows } from "../analysis/source-util.mjs";
 import { suppressionCovers } from "../config.mjs";
 import { referenceTime } from "../governance/clock.mjs";
 import { isWaiver, remainingMs, waiverStatus } from "../governance/waiver.mjs";
+import { coverageRefusal, coverageVerdict } from "./coverage-verdict.mjs";
 import { jsonEnvelope, renderJson } from "../report/json.mjs";
 import { formatWaiversReport } from "../report/waivers-text.mjs";
 import { partitionUnownedCoverage } from "./coverage-acceptance.mjs";
@@ -150,10 +151,13 @@ export function computeWaivers(suppressions, rawViolations, now = referenceTime(
  *   clock, and — from `cli.mjs`'s `runWaivers` — the workspace-relative path
  *   the run's law actually resolved from, so the `coverage.unowned` matching
  *   below subtracts the same configuration files `check` subtracts.
- * @returns {Promise<{status: "ok", waivers: object, report: {text: string, json: string}}>}
- * @throws {Error} whenever the run's law is malformed, or the tree has
- *   whole-file analysis failures — exit-3 class, the same posture `check` takes
- *   on a malformed config and `impact`/`drift` take on incomplete coverage.
+ * @returns {Promise<{status: "ok"|"no-verdict", waivers?: object, coverage: object,
+ *   report: {text: string, json: string}}>}
+ *   `status: "no-verdict"` carries no `waivers` payload — the verdict was
+ *   withheld, and the envelope's `coverage` block is the whole answer (#608).
+ * @throws {Error} whenever the run's law is malformed — exit-3 class, the same
+ *   posture `check` takes on a malformed config. Incomplete coverage returns
+ *   the structured no-verdict envelope instead of throwing (#608).
  */
 export async function waiversCommand(commandContext, boundaryConfig, io = {}) {
   const { root, provider, marker, analysis, graph } = commandContext;
@@ -180,25 +184,23 @@ export async function waiversCommand(commandContext, boundaryConfig, io = {}) {
   // A waiver surface over a tree it could not fully read is a lottery ticket,
   // not a surface: a file the analyzer never judged contributes no raw
   // violation, so every waiver that names it reads as stale and the report
-  // says "covers nothing" about a finding the run never looked at. Refuse
-  // loudly on whole-file failures, the same posture `impact`, `drift`, and
-  // `history` take — "could not look" must never read as "looked and found
-  // nothing" (`./impact.mjs`'s refusal names the same silence). A whole-file
-  // failure whose file a `coverage.unowned` row accepts is withdrawn first,
-  // exactly as `check` withdraws it (`./check.mjs`'s `acceptedUnclaimed`):
-  // its state is a recorded acceptance this very report is about to name,
-  // not a hole the run failed to look at.
-  const notAnalyzed = analysis.failures
-    .filter(isWholeFileFailure)
-    .filter(({ sourceFile }) => !unownedCoverage.acceptedFiles.has(sourceFile))
-    .map(({ sourceFile, reason }) => ({ file: sourceFile, reason }));
-
-  if (notAnalyzed.length > 0) {
-    throw new Error(
-      `archkeep: waivers has incomplete coverage — ${notAnalyzed.length} file` +
-        `${notAnalyzed.length === 1 ? "" : "s"} could not be analyzed, so every waiver naming one ` +
-        `would read as covering nothing it never saw. Fix the unanalyzed files and re-run.`,
-    );
+  // says "covers nothing" about a finding the run never looked at. Refused
+  // through the one structured contract `./coverage-verdict.mjs` builds
+  // (#608) — "could not look" must never read as "looked and found nothing".
+  // A whole-file failure whose file a `coverage.unowned` row accepts is
+  // withdrawn first, exactly as `check` withdraws it (`./check.mjs`'s
+  // `acceptedUnclaimed`): its state is a recorded acceptance this very report
+  // is about to name, not a hole the run failed to look at.
+  const completeness = coverageVerdict(commandContext, {
+    acceptedFiles: unownedCoverage.acceptedFiles,
+  });
+  if (!completeness.complete) {
+    return coverageRefusal({
+      command: "waivers",
+      commandContext,
+      what: "measuring the waiver surface",
+      acceptedFiles: unownedCoverage.acceptedFiles,
+    });
   }
 
   // F07: a waiver surface measured against a graph that cannot see the
@@ -226,10 +228,13 @@ export async function waiversCommand(commandContext, boundaryConfig, io = {}) {
     projects: Object.keys(graph.nodes).length,
     analyzedFiles: analysis.analyzed,
     imports: analysis.imports.length,
-    notAnalyzed,
-    blindSpots: analysis.failures
-      .filter((failure) => !isWholeFileFailure(failure))
-      .map(({ sourceFile, line, column, reason }) => ({ file: sourceFile, line, column, reason })),
+    // The withdrawn list — whole-file failures a `coverage.unowned` row
+    // accepts are already named in `result.unownedAcceptances` below, so
+    // repeating them here would double-count the same acceptance. On this
+    // path the list is empty by construction: anything unwithdrawn refused
+    // above.
+    notAnalyzed: completeness.notAnalyzed,
+    blindSpots: blindSpotRows(analysis.failures),
     // `remainingMs` reflects the wall clock at the moment of THIS run, not the
     // workspace — it is expected to differ between two runs of an unchanged
     // tree, by design (`../governance/clock.mjs`). Disclosed here, in-band,
@@ -282,6 +287,9 @@ export async function waiversCommand(commandContext, boundaryConfig, io = {}) {
   return {
     status: "ok",
     waivers: result,
+    // The same `coverage` block the envelope carries, so both return shapes —
+    // this one and the no-verdict refusal's (#608) — expose it under one key.
+    coverage,
     report: {
       text: formatWaiversReport(result),
       json: renderJson(envelope),