@ecoma-io/archkeep 0.21.0 → 0.22.0

package/src/commands/coverage-verdict.mjs

@@ -0,0 +1,184 @@
+/**
+ * The ONE incomplete-coverage refusal contract, and the one completeness
+ * every command's verdict is a claim about (#608).
+ *
+ * #602 gave the graph family (`check`, `graph`, `discover`, `explain`,
+ * `context`) a structured refusal: `status: "no-verdict"`, exit 3, a
+ * `coverage` block naming what the run could not read — in the envelope,
+ * where a parser and `--output` can read it. Every command here that refuses
+ * the same condition refused it by throwing: a stderr sentence, an empty
+ * stdout, no envelope, nothing under `--output`. Same refusal class, two
+ * machine contracts — while `docs/reference/exit-codes.md` already documents
+ * the structured one for every descriptive command. The functions here are
+ * the shared construction the throw family now goes through, so the two
+ * families cannot drift again:
+ *
+ * - `coverageVerdict` computes the one completeness the envelope law
+ *   (`../report/json.mjs`) already enforces — no whole-file failure, no
+ *   unjudged blind spot, at least one file analyzed — and the status/exit
+ *   pair that completeness implies. The failure classes are read through
+ *   `../analysis/source-util.mjs`'s classifiers, never an inline filter: the
+ *   class line is theirs alone to own.
+ * - `coverageRefusal` builds the refusal result itself: the envelope through
+ *   `jsonEnvelope` (so the envelope invariants hold by construction, and a
+ *   refusal cannot accidentally claim `complete: true`), and a text face
+ *   whose coverage lines come from `coverageIncompleteReasons` — the same
+ *   clauses `check`'s text report renders — so a terminal reader is told the
+ *   same thing the envelope tells a parser.
+ *
+ * What still throws: the plugin-gap refusal (a graph that under-represents
+ * the workspace is a different refusal, kept loud in every command that has
+ * one — `drift.mjs`'s `refuseIncompleteGraph` and `delta.mjs`'s
+ * `refusePluginGapHead` are the two shared guards), input refusals (a
+ * malformed baseline file, a missing intent), and the capture modes
+ * (`delta --capture`, `history --capture`) whose product is a snapshot file
+ * with no envelope contract to refuse through.
+ *
+ * @module
+ */
+
+import {
+  blindSpotRows,
+  isWholeFileFailure,
+  unresolvableLiteralCount,
+} from "../analysis/source-util.mjs";
+import { EXIT, coverageIncompleteReasons } from "../verdict.mjs";
+import { buildDecision } from "../report/evidence.mjs";
+import { jsonEnvelope, renderJson } from "../report/json.mjs";
+import { formatCoverageIncomplete } from "../report/text.mjs";
+import { resolveProvenance } from "./provenance.mjs";
+
+/**
+ * @typedef {object} CoverageVerdict
+ * @property {{file: string, reason: string}[]} notAnalyzed One row per
+ *   whole-file failure — the files the run never read.
+ * @property {object[]} blindSpots Every positioned failure, all permanent
+ *   classes — the run's disclosure of every site it saw and did not judge.
+ * @property {number} blindSpotCount The count of sites that WITHHOLD the
+ *   verdict (unresolvable literals referencing the workspace; dynamic and
+ *   external sites disclosed but exit-neutral).
+ * @property {boolean} complete Whether the run judged everything in scope.
+ * @property {"ok"|"no-verdict"} status The verdict the completeness implies.
+ * @property {0|3} exitCode The exit code the status implies.
+ */
+
+/**
+ * The one completeness verdict over a command context's analysis.
+ *
+ * The three completeness axes are exactly the envelope law's: a whole-file
+ * failure is a file no verdict was reached on; an unresolvable literal site
+ * is a question the resolver was asked and could not answer; a zero-analyzed
+ * run judged nothing (#599). Dynamic and external sites are declared limits —
+ * disclosed in `blindSpots`, never withholding — because
+ * `unresolvableLiteralCount` draws that class line once, and this function
+ * reads the count rather than re-deriving it.
+ *
+ * @param {object} commandContext From `resolveCommandContext`.
+ * @param {{acceptedFiles?: Set<string>}} [io] `acceptedFiles` names whole-
+ *   file failures a `coverage.unowned` row already accepts (`waivers` and
+ *   `check` withdraw those first): the state is a recorded acceptance the
+ *   report itself names, not a hole the run failed to look at. Absent ⇒ no
+ *   withdrawal, which is every command but `waivers`.
+ * @returns {CoverageVerdict}
+ */
+export function coverageVerdict(commandContext, { acceptedFiles } = {}) {
+  const { analysis } = commandContext;
+  const notAnalyzed = analysis.failures
+    .filter(isWholeFileFailure)
+    .filter(({ sourceFile }) => !(acceptedFiles?.has(sourceFile) ?? false))
+    .map(({ sourceFile, reason }) => ({ file: sourceFile, reason }));
+  const blindSpots = blindSpotRows(analysis.failures);
+  const blindSpotCount = unresolvableLiteralCount(analysis.failures);
+  const complete = notAnalyzed.length === 0 && blindSpotCount === 0 && analysis.analyzed > 0;
+  return {
+    notAnalyzed,
+    blindSpots,
+    blindSpotCount,
+    complete,
+    status: complete ? "ok" : "no-verdict",
+    exitCode: complete ? EXIT.ok : EXIT.error,
+  };
+}
+
+/**
+ * The structured refusal itself: what a command returns over an analysis it
+ * could not fully read, instead of throwing.
+ *
+ * The envelope carries no `result`: the verdict was withheld, so there is no
+ * verdict payload to ride beside the refusal — the `coverage` block IS the
+ * payload, and `jsonEnvelope`'s law would refuse any `ok`-shaped claim this
+ * object might otherwise smuggle through. `decision` is accepted for the two
+ * commands whose envelopes already carry one (`delta`, `change`); an
+ * "unknown" decision must name its reason (I3), so callers pass `true` and
+ * the reason is joined from the same clause list the text face renders.
+ *
+ * @param {{command: string, commandContext: object, what: string,
+ *   acceptedFiles?: Set<string>, decision?: boolean}} input
+ *   `command` is the envelope's command name, `what` names the question the
+ *   command was asking (the text face's one free clause), `acceptedFiles`
+ *   forwards to `coverageVerdict` (see above), and `decision: true` attaches
+ *   the canonical `unknown` decision.
+ * @returns {{status: "no-verdict", coverage: object,
+ *   report: {text: string, json: string}}}
+ */
+export function coverageRefusal({ command, commandContext, what, acceptedFiles, decision }) {
+  const verdict = coverageVerdict(commandContext, { acceptedFiles });
+  // A refusal over a complete coverage would be a `no-verdict` claim about a
+  // run that looked at everything — the silent direction in the other dress.
+  // Every caller gates on `coverageVerdict(...).complete` first; this is the
+  // one place that refuses to build the lie if a caller stops gating.
+  if (verdict.complete) {
+    throw new Error(
+      `coverageRefusal: ${command}'s coverage is complete — there is nothing to refuse`,
+    );
+  }
+  /** @type {"no-verdict"} The completeness is false, so this is the status. */
+  const status = "no-verdict";
+  const reasons = coverageIncompleteReasons({
+    unchecked: verdict.notAnalyzed.length,
+    blindSpots: verdict.blindSpotCount,
+    analyzed: commandContext.analysis.analyzed,
+  });
+  const coverage = {
+    complete: false,
+    projects: Object.keys(commandContext.graph.nodes).length,
+    analyzedFiles: commandContext.analysis.analyzed,
+    imports: commandContext.analysis.imports.length,
+    notAnalyzed: verdict.notAnalyzed,
+    blindSpots: verdict.blindSpots,
+    notes: [],
+  };
+  const envelope = jsonEnvelope({
+    command,
+    context: {
+      root: commandContext.root,
+      provider: commandContext.provider,
+      marker: commandContext.marker,
+      provenance: resolveProvenance(commandContext.root),
+    },
+    status,
+    exitCode: verdict.exitCode,
+    coverage,
+    result: undefined,
+    ...(decision === true
+      ? {
+          decision: buildDecision({
+            status,
+            coverageComplete: false,
+            findings: 0,
+            reason: reasons.join("; "),
+          }),
+        }
+      : {}),
+  });
+  return {
+    status,
+    coverage,
+    report: {
+      text:
+        `${command}: no verdict — ${what} needs a workspace this run could fully read\n` +
+        formatCoverageIncomplete(reasons),
+      json: renderJson(envelope),
+    },
+  };
+}

package/src/commands/debt.mjs

@@ -45,12 +45,13 @@
  * when the ledger was taken; the aging itself is snapshot-relative
  * (`../governance/debt-ledger.mjs`).
  */
-import { isWholeFileFailure } from "../analysis/source-util.mjs";
+import { blindSpotRows } from "../analysis/source-util.mjs";
 import { judgeIntent } from "../architecture-intent/judge.mjs";
 import { INTENT_FILE, loadIntent } from "../architecture-intent/model.mjs";
 import { computeDebtLedger } from "../governance/debt-ledger.mjs";
 import { readEvents } from "../governance/evolution-store.mjs";
 import { formatDebtReport } from "../report/debt-text.mjs";
+import { coverageRefusal, coverageVerdict } from "./coverage-verdict.mjs";
 import { jsonEnvelope, renderJson } from "../report/json.mjs";
 import { resolveProvenance } from "./provenance.mjs";
 import { buildObserved, refuseIncompleteGraph } from "./drift.mjs";
@@ -75,9 +76,12 @@ import { readSnapshots } from "./history.mjs";
  *   the `history`/`drift` pattern. `events` is the event-store directory the
  *   `--events <dir>` CLI flag resolves; absent ⇒ no lifecycle refs (the
  *   ledger says so in `lifecycle.note`), never guessed.
- * @returns {Promise<{status: "ok", ledger: object, coverage: object,
+ * @returns {Promise<{status: "ok"|"no-verdict", ledger?: 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 `ledger` 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 debtCommand(dir, commandContext, options = {}) {
   const { root, provider, marker, analysis } = commandContext;
@@ -86,15 +90,16 @@ export async function debtCommand(dir, commandContext, options = {}) {
 
   refuseIncompleteGraph(commandContext);
 
-  const notAnalyzed = analysis.failures
-    .filter(isWholeFileFailure)
-    .map(({ sourceFile, reason }) => ({ file: sourceFile, reason }));
-  if (notAnalyzed.length > 0) {
-    throw new Error(
-      `archkeep: debt has incomplete coverage — ${notAnalyzed.length} file` +
-        `${notAnalyzed.length === 1 ? "" : "s"} could not be analyzed, so every "project missing" ` +
-        `would be ambiguous between "gone" and "never seen". Fix the unanalyzed files and re-run.`,
-    );
+  // The ledger is a claim about the tree the run read, refused through the one
+  // structured contract `./coverage-verdict.mjs` builds (#608). This gate used
+  // to check whole-file failures only and then claim `coverage.complete: true`
+  // beside `blindSpots` that could carry an unjudged site — which the envelope
+  // law refuses as a programming error, so a blind-spot-only tree crashed
+  // here. The unified completeness refuses it as the verdict-withholding state
+  // it is, before the snapshot directory is read.
+  const completeness = coverageVerdict(commandContext);
+  if (!completeness.complete) {
+    return coverageRefusal({ command: "debt", commandContext, what: "aging the debt ledger" });
   }
 
   // The snapshot directory is the sole source of truth for aging; a directory
@@ -173,9 +178,7 @@ export async function debtCommand(dir, commandContext, options = {}) {
     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 })),
+    blindSpots: blindSpotRows(analysis.failures),
     // The ledger names what it could not age — a reader can tell "aged" from
     // "observed, not yet aged". The second note discloses `sampleTime`'s own
     // nature: it reflects the wall clock at the moment of THIS run, not the

package/src/commands/delta-classify.mjs

@@ -593,20 +593,11 @@ export function deltaFindings(delta) {
   };
 }
 
-/**
- * The identity string of one graph edge, in the design's canonical spelling
- * `source>target:type` (the `(source, target, type)` identity the design
- * §1 names, printed the way `docs/concepts/evolution.md`'s example shows).
- * The ONE spelling the delta's event `observed.edges`/`affected.boundaries`
- * use — a second spelling somewhere would be a second definition of "same
- * edge", and two definitions drift.
- *
- * @param {{source: string, target: string, type: string}} edge
- * @returns {string}
- */
-export function edgeEvolutionIdentity({ source, target, type }) {
-  return `${source}>${target}:${type}`;
-}
+// The identity spelling's ONE home is `../governance/evolution-event.mjs` —
+// `classifyEvolution` owns it and maps every `observed.edges` entry through
+// it. This re-export keeps delta's importers on the same name; it defines
+// nothing.
+export { edgeEvolutionIdentity } from "../governance/evolution-event.mjs";
 
 /**
  * The delta event's per-constraint verdict deltas (design §1 `fitness`),
@@ -675,12 +666,16 @@ export function deltaVerdictDeltas(delta) {
  *
  * @param {object} delta The `deltaCommand` result payload.
  * @param {{projects?: {added: string[], removed: string[], changed: string[]},
- *   edges?: {added: string[], removed: string[]}, codeDrift?: boolean}} [signals]
+ *   edges?: {added: {source: string, target: string, type: string}[],
+ *   removed: {source: string, target: string, type: string}[]},
+ *   codeDrift?: boolean}} [signals]
  *   The structural-change and drift signals a delta run derives from the two
  *   graphs it holds (the graph diff is `diff`'s vocabulary, shared here, never
- *   re-derived) — `projects`/`edges` carry identity strings (`edgeEvolutionIdentity`
- *   for edges), and `codeDrift` is the delta's computed "provenance advanced,
- *   no arch/policy change" fact. Absent signals are empty, so a delta that
+ *   re-derived) — `edges` carries the raw `{source, target, type}` triples,
+ *   which `classifyEvolution` maps through `edgeEvolutionIdentity` itself (the
+ *   identity string is its output spelling, never an input), and `codeDrift`
+ *   is the delta's computed "provenance advanced, no arch/policy change" fact.
+ *   Absent signals are empty, so a delta that
  *   computed none reads as a violation-only mapping.
  * @returns {{classifications: string[], disposition: "accepted"|"rejected"|"no-verdict",
  *   notes: string[], affected: {projects: string[], boundaries: string[],

package/src/commands/delta.mjs

@@ -23,8 +23,12 @@
  * exit 1, beside `check` and `fitness`; `./change.mjs` later became the
  * fourth, over a different question — declared intent versus observed delta.
  *
- * Refusals (each a throw, exit 3 upstream — a delta that could not honestly
- * classify must never read as "no change"):
+ * Refusals — a delta that could not honestly classify must never read as
+ * "no change". Incomplete CURRENT coverage on the compare side returns the
+ * structured no-verdict envelope `./coverage-verdict.mjs` builds (#608) —
+ * 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; the
+ * rest are throws, exit 3 upstream:
  * - a baseline that cannot be read, parsed, or holds a foreign schemaVersion
  *   (`./delta-snapshot.mjs`'s loader owns those);
  * - a provider mismatch between baseline and this run (`providerMismatch`) —
@@ -32,8 +36,8 @@
  *   across two different project models is not trustworthy: the same tree
  *   attributed to different projects would classify a rename as an
  *   introduced/resolved pair the code does not contain;
- * - incomplete CURRENT coverage — a delta over a half-analyzed head is not a
- *   verdict, the same posture `check` takes on `unchecked` files;
+ * - incomplete coverage on the CAPTURE side (`refuseUnjudgeableHead`), where
+ *   there is no envelope to withhold — a baseline write has no verdict;
  * - an Nx workspace with polyglot manifests but no plugin registration — the
  *   same silently-under-representing graph `graph`/`diff` refuse.
  *
@@ -62,7 +66,11 @@
  */
 import { createRequire } from "node:module";
 
-import { isWholeFileFailure } from "../analysis/source-util.mjs";
+import {
+  blindSpotRows,
+  isWholeFileFailure,
+  unresolvableLiteralCount,
+} from "../analysis/source-util.mjs";
 import { stripTrailingSlashes } from "../path-util.mjs";
 import { referenceTime } from "../governance/clock.mjs";
 import {
@@ -97,6 +105,7 @@ import {
 } from "./delta-snapshot.mjs";
 import { computeDiff } from "./diff.mjs";
 import { buildDependencies, buildProjects, computePolicyFingerprint } from "./graph.mjs";
+import { coverageRefusal, coverageVerdict } from "./coverage-verdict.mjs";
 import { resolveProvenance } from "./provenance.mjs";
 import { compareSnapshotMetadata } from "./snapshot-meta.mjs";
 
@@ -105,20 +114,21 @@ const require = createRequire(import.meta.url);
 const { name: TOOL_NAME, version: TOOL_VERSION } = require("../../package.json");
 
 /**
- * Refuses the two head states no delta side may be built over, shared by both
- * modes: the unregistered-plugin graph and incomplete analysis coverage.
+ * Refuses the unregistered-plugin head state no delta side may be built over:
+ * on an Nx workspace whose `nx.json` does not register this plugin but whose
+ * tracked files include polyglot manifests under project roots.
  *
  * Exported since `change` arrived because that command builds its comparison
- * over the same two head states — a graph that under-represents the tree and
- * an analysis with holes would reconcile a declaration against architecture
- * nobody observed — and a second copy of the refusal is where the two
- * commands would drift into answering "may this head be judged?" differently.
+ * over the same head state — a graph that under-represents the tree would
+ * reconcile a declaration against architecture nobody observed — and a second
+ * copy of the refusal is where the two commands would drift into answering
+ * "may this head be judged?" differently.
  *
  * @param {object} commandContext From `resolveCommandContext`.
  * @param {string} activity Which mode is refusing, for the message.
- * @throws {Error} on either condition.
+ * @throws {Error} on the unregistered-plugin graph.
  */
-export function refuseUnjudgeableHead(commandContext, activity) {
+export function refusePluginGapHead(commandContext, activity) {
   const { provider, pluginGap } = commandContext;
   if (provider === "nx" && !pluginGap.registered && pluginGap.manifests.length > 0) {
     throw new Error(
@@ -130,11 +140,45 @@ export function refuseUnjudgeableHead(commandContext, activity) {
         `manifests if they are not in use.`,
     );
   }
+}
+
+/**
+ * Refuses, as a throw, the two head states no delta side may be built over:
+ * the unregistered-plugin graph (`refusePluginGapHead`) and incomplete
+ * analysis coverage.
+ *
+ * The coverage half stayed a throw through #602's unification of the
+ * graph-family refusal, and it stays one here — but only for the CAPTURE
+ * side: `captureDelta` writes a baseline, and a write that cannot be honest
+ * has no verdict to withhold, so stderr is the only face it has. The compare
+ * side (`deltaCommand`, `changeCommand`) refuses coverage through
+ * `./coverage-verdict.mjs`'s structured envelope (#608) instead and calls only
+ * `refusePluginGapHead`, so a withheld verdict reaches a parser and
+ * `--output` in-band.
+ *
+ * @param {object} commandContext From `resolveCommandContext`.
+ * @param {string} activity Which mode is refusing, for the message.
+ * @throws {Error} on either condition.
+ */
+export function refuseUnjudgeableHead(commandContext, activity) {
+  refusePluginGapHead(commandContext, activity);
   const notAnalyzed = commandContext.analysis.failures.filter(isWholeFileFailure);
-  if (notAnalyzed.length > 0) {
+
+  const blindSpotCount = unresolvableLiteralCount(commandContext.analysis.failures);
+  if (notAnalyzed.length > 0 || blindSpotCount > 0) {
     throw new Error(
-      `archkeep: cannot ${activity} — ${notAnalyzed.length} file` +
-        `${notAnalyzed.length === 1 ? "" : "s"} could not be analyzed, so the evidence would ` +
+      `archkeep: cannot ${activity} — ` +
+        [
+          notAnalyzed.length > 0
+            ? `${notAnalyzed.length} file${notAnalyzed.length === 1 ? "" : "s"} could not be analyzed`
+            : null,
+          blindSpotCount > 0
+            ? `${blindSpotCount} import site${blindSpotCount === 1 ? "" : "s"} could not be resolved`
+            : null,
+        ]
+          .filter(Boolean)
+          .join(", ") +
+        `, so the evidence would ` +
         `miss violations living there and a later classification would misread the gap as a ` +
         `code change. Fix the unanalyzed files and re-run.`,
     );
@@ -181,14 +225,7 @@ export function captureDelta(commandContext, { config }) {
       complete: true,
       analyzedFiles: analysis.analyzed,
       notAnalyzed: [],
-      blindSpots: analysis.failures
-        .filter((failure) => !isWholeFileFailure(failure))
-        .map(({ sourceFile, line, column, reason }) => ({
-          file: sourceFile,
-          line,
-          column,
-          reason,
-        })),
+      blindSpots: blindSpotRows(analysis.failures),
     },
     graph,
     records: analysis.imports,
@@ -387,15 +424,21 @@ const short = (fingerprint) =>
  *   `loadIntent`; absent intent ⇒ no ids, an in-band note says so), and the
  *   custom-rule host's two injectable seams, passed through to
  *   `customRulesForDelta`.
- * @returns {Promise<{status: "ok"|"findings"|"no-verdict", delta: object,
+ * @returns {Promise<{status: "ok"|"findings"|"no-verdict", delta?: object,
  *   coverage: object,
- *   eventWrite: {id: string, duplicate: boolean}|null,
- *   report: {text: string, json: string, sarif: string}}>} `delta` carries
+ *   eventWrite?: {id: string, duplicate: boolean}|null,
+ *   report: {text: string, json: string, sarif?: string}}>} `delta` carries
  *   the additive `classifications`/`affected` fields (design §1); `eventWrite`
  *   is `null` unless `eventOut` was given, then the store's answer for the
- *   event that was (or already was) recorded.
+ *   event that was (or already was) recorded. `status: "no-verdict"` from the
+ *   coverage refusal (#608) carries neither `delta` nor `eventWrite` — the
+ *   comparison was withheld before any event work, and the envelope's
+ *   `coverage` block plus its `decision.reason` are the whole answer; the
+ *   report then has no `sarif` face (there are no findings to render).
  * @throws {Error} on every refusal the module header lists, and on a
  *   custom-rule LOAD failure (`./custom-rules.mjs` argues the split).
+ *   Incomplete head coverage returns the structured no-verdict envelope
+ *   instead of throwing (#608); the unregistered-plugin graph keeps its throw.
  */
 export async function deltaCommand(
   baselinePath,
@@ -411,7 +454,22 @@ export async function deltaCommand(
 ) {
   const { root, provider, marker, graph, analysis, tracked } = commandContext;
 
-  refuseUnjudgeableHead(commandContext, "compute a delta");
+  // The plugin-gap refusal stays a throw; the coverage refusal returns the one
+  // structured envelope `./coverage-verdict.mjs` builds (#608): a verdict
+  // withheld because the run could not read the tree belongs in-band, where a
+  // parser and `--output` can read it — the same contract the graph family has
+  // run since #602. The capture side keeps the throw (`refuseUnjudgeableHead`
+  // above), because a baseline write has no envelope to withhold.
+  refusePluginGapHead(commandContext, "compute a delta");
+  const completeness = coverageVerdict(commandContext);
+  if (!completeness.complete) {
+    return coverageRefusal({
+      command: "delta",
+      commandContext,
+      what: "computing a delta",
+      decision: true,
+    });
+  }
   if (!config) {
     throw new Error(
       "archkeep: cannot compute a delta without a boundary config — both sides are re-judged " +
@@ -630,7 +688,13 @@ export async function deltaCommand(
   };
   const evolution = classifyDeltaEvolution(deltaPayload, {
     projects: structural.projects,
-    edges: structural.edges,
+    // The raw triples, not `structural.edges` (the mapped identity strings):
+    // `classifyEvolution` owns the spelling and takes the triples. The
+    // envelope's `structural` and the event's `observed` keep the mapped
+    // strings this run derived above — one mapping per command, and the
+    // classification's `affected.boundaries` comes out under the same
+    // spelling because it is mapped inside `classifyEvolution` itself.
+    edges: { added: structuralDiff.addedEdges, removed: structuralDiff.removedEdges },
     codeDrift,
   });
 
@@ -683,9 +747,7 @@ export async function deltaCommand(
     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 })),
+    blindSpots: blindSpotRows(analysis.failures),
     notes,
   };
 

package/src/commands/diff.mjs

@@ -40,9 +40,9 @@
  */
 import { readFileSync } from "node:fs";
 
-import { isWholeFileFailure } from "../analysis/source-util.mjs";
 import { buildDependencies, buildProjects, computePolicyFingerprint } from "./graph.mjs";
 import { computeRuleImpact } from "./edge-constraints.mjs";
+import { coverageRefusal, coverageVerdict } from "./coverage-verdict.mjs";
 import { SCHEMA_VERSION } from "../report/json.mjs";
 import { jsonEnvelope, renderJson } from "../report/json.mjs";
 import { formatDiffReport } from "../report/diff-text.mjs";
@@ -349,11 +349,14 @@ export function computeDiff(baseline, head) {
  *   When omitted, reads from the real filesystem. `config` is the loaded
  *   boundary config; when provided, rule-impact analysis is computed alongside
  *   the structural diff.
- * @returns {{status: "ok"|"no-verdict", diff: object, coverage: object,
- *   report: {text: string, json: string}}}
- * @throws {Error} when the baseline cannot be read or is incomplete, when
- *   the head is incomplete, or when an Nx workspace has polyglot manifests
- *   but the plugin is not registered.
+ * @returns {{status: "ok"|"no-verdict", diff?: object, coverage: object,
+ *   report: {text: string, json: string}}} `diff` is absent under
+ *   `status: "no-verdict"` — the coverage refusal (#608) withholds the
+ *   comparison, and the envelope's `coverage` block is the whole answer.
+ * @throws {Error} when the baseline cannot be read or is incomplete, or when
+ *   an Nx workspace has polyglot manifests but the plugin is not registered
+ *   (the inline throw in the body). An incomplete head returns the
+ *   structured no-verdict envelope instead of throwing (#608).
  */
 export function diffCommand(
   baselinePath,
@@ -379,19 +382,18 @@ export function diffCommand(
   // is a caller error, not a workspace fact, and it should name the file.
   const baseline = readBaseline(baselinePath);
 
-  // Refuse an incomplete head — same reasoning as the incomplete baseline
-  // refusal: every "added" or "removed" entry would be ambiguous.
-  const notAnalyzed = commandContext.analysis.failures
-    .filter(isWholeFileFailure)
-    .map(({ sourceFile, reason }) => ({ file: sourceFile, reason }));
-
-  if (notAnalyzed.length > 0) {
-    throw new Error(
-      `archkeep: the head graph has incomplete coverage — ${notAnalyzed.length} file` +
-        `${notAnalyzed.length === 1 ? "" : "s"} could not be analyzed, so every "added" or ` +
-        `"removed" entry in the diff would be ambiguous between a real change and a coverage ` +
-        `gap. Fix the unanalyzed files and re-run.`,
-    );
+  // Refuse an incomplete head through the one structured contract
+  // `./coverage-verdict.mjs` builds (#608): the diff 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.
+  // The reasoning is the incomplete-baseline refusal's: every "added" or
+  // "removed" entry would be ambiguous. That baseline refusal stays a throw —
+  // `parseBaseline` above throws it through the default reader — because a
+  // baseline nobody captured correctly is a caller error about a file, not a
+  // coverage fact about THIS tree.
+  const completeness = coverageVerdict(commandContext);
+  if (!completeness.complete) {
+    return coverageRefusal({ command: "diff", commandContext, what: "diffing the head graph" });
   }
 
   const head = buildHeadSnapshot(commandContext);
@@ -404,9 +406,7 @@ export function diffCommand(
     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: [],
   };
 
@@ -417,6 +417,12 @@ export function diffCommand(
       projects: baseline.projects.length,
       edges: baseline.dependencies.length,
       toolVersion: baseline.toolVersion,
+      // The provenance the baseline itself recorded — which commit, remote,
+      // and dirtiness the captured side names (#609). The head side's own
+      // provenance rides the envelope's `workspace.provenance`; without the
+      // baseline's, a consumer could not tell WHICH revision the empty or
+      // non-empty diff is measured against.
+      provenance: baseline.provenance ?? null,
     },
     head: { projects: head.projects.length, edges: head.dependencies.length },
     addedProjects: diff.addedProjects,
@@ -525,8 +531,9 @@ export function diffCommand(
     // no depConstraints violations were introduced or resolved on the changed
     // edges. Run `check` for the complete verdict.
     coverage.notes.push(
-      "per-edge rule-impact covers only depConstraints (3 of 15 violation types). " +
-        "A dependency with no rule-impact may still violate npm-ban, circular-dependency, " +
+      "per-edge rule-impact covers only depConstraints (3 of 15 violation types; standing " +
+        "edges adjacent to a tags-changed project are re-judged under both sides' tags). A " +
+        "dependency with no rule-impact may still violate npm-ban, circular-dependency, " +
         "lazy-load, or other rules that require import-site details. Run check for the " +
         "complete verdict.",
     );