@ecoma-io/archkeep 0.21.0 → 0.22.1

package/src/commands/evaluation-primitives.mjs

@@ -9,6 +9,7 @@
  * @module
  */
 import { readAdrContext } from "./adr.mjs";
+import { edgeEvolutionIdentity } from "../governance/evolution-event.mjs";
 import { hasAuthority, resolveDecisionRef, stripAdrPrefix } from "../governance/adr-registry.mjs";
 import { isComboDepConstraint } from "../rules/tags.mjs";
 import { computeDecisionProvenance } from "../governance/provenance-graph.mjs";
@@ -16,9 +17,13 @@ import { resolveFileAttribution } from "./provenance.mjs";
 
 import {
   buildCompleteness,
+  buildEvidenceComplete,
   buildGovernanceCompleteness,
   evaluationStatus,
   EVALUATION_STATUS,
+  EVALUATION_CONTRACT_TYPES,
+  computeDomainCoverage,
+  REQUIRED_DOMAINS,
 } from "./completeness.mjs";
 import { computeImpact } from "./impact.mjs";
 import { computeImpactConstraints } from "./edge-constraints.mjs";
@@ -284,6 +289,116 @@ export function evaluateBoundaryImpact(graph, constraintImpact, targetProject) {
 // Canonical Architecture Evaluation
 // ---------------------------------------------------------------------------
 
+/**
+ * The provenance coverage of a decision set: the fraction of rows that
+ * resolved to a known record with authority.
+ *
+ * An ADR row counts when its record carries decision authority
+ * (`hasAuthority` — `accepted`/`active`); a fitness row counts when it
+ * resolved to an id the loaded policy binds (`resolution === "known"`).
+ * Refs that resolve to nothing are reported by `unresolvedDecisionRefs`
+ * and never become rows; a record without authority emits a row the gate
+ * fails on loudly rather than counting. One derivation, one home —
+ * `deriveEvidenceGates` and the scenario face both read it, so the two
+ * callers cannot disagree about what a covered decision is.
+ *
+ * @param {object[]|null|undefined} decisions Decision rows from
+ *   `buildDecisionImpact`.
+ * @returns {number} A ratio in [0, 1]; 0 when no decision binds an
+ *   affected row.
+ */
+export function decisionProvenanceCoverage(decisions) {
+  const rows = decisions ?? [];
+  if (rows.length === 0) return 0;
+  const covered = rows.filter((row) =>
+    row.kind === "adr" ? row.hasAuthority === true : row.resolution === "known",
+  ).length;
+  return covered / rows.length;
+}
+
+/**
+ * Derives evidence gates from evaluation outputs for the canonical evaluator.
+ *
+ * Each gate is computed from actual evaluation data rather than being
+ * caller-supplied. Gates not applicable to canonical evaluation
+ * (mutationCoverage, surfaceParity, baseIdentityValid) are set to 0/false
+ * and excluded via EVALUATION_CONTRACT_TYPES.CANONICAL.
+ *
+ * @param {object} evaluation The full evaluation result.
+ * @param {object} evaluation.completeness The completeness result.
+ * @param {object} evaluation.impact The structural impact.
+ * @param {object|null} evaluation.constraintImpact Constraint impact.
+ * @param {object|null} evaluation.decisionImpact Decision impact.
+ * @param {object} evaluation.boundaryImpact Boundary impact.
+ * @param {object} evaluation.findingsImpact Findings impact.
+ * @param {object} evaluation.debtImpact Debt impact.
+ * @param {object} evaluation.evolutionAlignment Evolution alignment.
+ * @returns {object} Evidence gate values for buildEvidenceComplete.
+ */
+export function deriveEvidenceGates(evaluation) {
+  const { completeness, constraintImpact, decisionImpact } = evaluation;
+
+  // domainCoverage: ratio of evaluated required domains
+  /** @type {{ [domain: string]: string }} */
+  const domainStatuses = {};
+  for (const domain of REQUIRED_DOMAINS) {
+    const dom = completeness.domains[domain];
+    domainStatuses[domain] = dom ? dom.status : EVALUATION_STATUS.NOT_EVALUATED;
+  }
+  const dc = computeDomainCoverage(domainStatuses);
+  const domainCoverage = dc.coverage;
+
+  // claimEvidenceCoverage: structural always produces claims with evidence.
+  // Constraint/decision claims exist when config is present.
+  const structuralClaimEvidence = 1; // structural always produces evidence
+  const constraintClaimEvidence = constraintImpact !== null ? 1 : 0;
+  const decisionClaimEvidence = decisionImpact !== null ? 1 : 0;
+  const totalClaims = 3; // structural + constraint + decision
+  const evidencedClaims = structuralClaimEvidence + constraintClaimEvidence + decisionClaimEvidence;
+  const claimEvidenceCoverage = totalClaims > 0 ? evidencedClaims / totalClaims : 0;
+
+  // causalCoverage: constraint consequences with complete causal chains
+  // When constraint impact is present, all constraint edges are traced.
+  // When absent, causal coverage is 0 (no constraints to trace).
+  const causalCoverage = constraintImpact !== null ? 1 : 0;
+
+  // provenanceCoverage: the fraction of decision rows that resolved to a
+  // known record with authority — derived from facts the rows carry, never
+  // from a property the row builder never wrote.
+  const provenanceCoverage = decisionProvenanceCoverage(decisionImpact?.decisions);
+
+  // mutationCoverage: not applicable for canonical evaluation
+  // surfaceParity: not applicable for canonical evaluation
+
+  // hiddenGapCount: NOT_EVALUATED domains without a note
+  let hiddenGapCount = 0;
+  for (const [, domain] of Object.entries(completeness.domains)) {
+    if (domain.status === EVALUATION_STATUS.NOT_EVALUATED && !domain.note) {
+      hiddenGapCount++;
+    }
+  }
+
+  // falseCompleteCount: detect when domains pass but evidence gates fail
+  // This is computed by buildCompleteness from the evidenceComplete contract.
+
+  // baseIdentityValid: not applicable for canonical evaluation
+
+  // deterministic: canonical evaluator is deterministic by construction
+  const deterministic = true;
+
+  return {
+    domainCoverage,
+    claimEvidenceCoverage,
+    causalCoverage,
+    provenanceCoverage,
+    mutationCoverage: 0,
+    surfaceParity: 0,
+    hiddenGapCount,
+    falseCompleteCount: 0,
+    baseIdentityValid: false,
+    deterministic,
+  };
+}
 /**
  * Evaluates the complete architecture state for a target project.
  *
@@ -435,6 +550,76 @@ export function evaluateArchitectureState({
     },
   });
 
+  // Derive evidence gates and build Evidence-Complete contract
+  const evaluationResult = {
+    completeness,
+    impact,
+    constraintImpact,
+    decisionImpact,
+    boundaryImpact,
+    findingsImpact,
+    debtImpact,
+    evolutionAlignment,
+  };
+  const evidenceGates = deriveEvidenceGates(evaluationResult);
+  const evidenceComplete = buildEvidenceComplete({
+    ...evidenceGates,
+    contractType: EVALUATION_CONTRACT_TYPES.CANONICAL,
+  });
+
+  // Rebuild completeness with evidenceComplete contract
+  const completenessWithEC = buildCompleteness({
+    structural: {
+      status: structuralStatus,
+      evaluated: true,
+      partial: false,
+      notEvaluated: false,
+      unsupported: false,
+      refused: false,
+      note: "",
+    },
+    constraint: {
+      status: constraintStatus,
+      evaluated: hasConfig && config.depConstraints !== undefined,
+      partial: false,
+      notEvaluated: !hasConfig || config.depConstraints === undefined,
+      unsupported: false,
+      refused: false,
+      note: "",
+    },
+    boundary: {
+      status: boundaryStatus,
+      evaluated: hasConfig,
+      partial: false,
+      notEvaluated: !hasConfig,
+      unsupported: false,
+      refused: false,
+      note: "",
+    },
+    decision: {
+      status: decisionStatus,
+      evaluated: hasConfig,
+      partial: false,
+      notEvaluated: !hasConfig,
+      unsupported: false,
+      refused: false,
+      note: "",
+    },
+    findings: governanceResult.findings,
+    debt: governanceResult.debt,
+    governance: governanceResult.domain,
+    evidence: {
+      status: evidenceStatus,
+      evaluated: evidenceEvaluated,
+      partial: false,
+      notEvaluated: false,
+      unsupported: false,
+      refused: false,
+      note: "",
+    },
+    evidenceComplete,
+  });
+
   return {
     project: projectName,
     impact,
@@ -444,8 +629,9 @@ export function evaluateArchitectureState({
     boundaryImpact,
     findingsImpact,
     debtImpact,
-    completeness,
+    completeness: completenessWithEC,
     affectedProjects,
+    evidenceComplete,
   };
 }
 
@@ -473,7 +659,13 @@ export function buildEvolutionAlignment(projectName, impact, constraintImpact, r
     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}`;
+        // The canonical spelling — imported, not restated, so this surface
+        // cannot drift from `EvolutionEvent.affected`'s vocabulary.
+        const edgeId = edgeEvolutionIdentity({
+          source: entry.project,
+          target: edge.target,
+          type: edge.type,
+        });
         if (!affectedBoundaries.includes(edgeId)) {
           affectedBoundaries.push(edgeId);
         }

package/src/commands/evolution.mjs

@@ -80,6 +80,7 @@ import { debtChangeDiff, debtFactId, driftFactOf } from "../governance/debt-ledg
 import { computeAffectedDecisions } from "../governance/decision-lineage.mjs";
 import {
   classifyEvolution,
+  edgeEvolutionIdentity,
   eventDedupeKey,
   eventId,
   EVOLUTION_EVENT_SCHEMA_VERSION,
@@ -939,23 +940,24 @@ function buildEvolutionSummary(comparisons) {
         comparisons.flatMap((c) => c.observed.projects.changed.map((p) => p.name ?? p)),
       ),
     },
+    // The identity string is the ONE spelling `edgeEvolutionIdentity` owns —
+    // the same spelling `affected.boundaries` and every stored event carry.
+    // An edge without a complete triple has no identity to name, so it is
+    // dropped from the union and counted into `unnamedEdges` rather than
+    // leaking an object serialization into a field of identity strings.
     edges: {
       added: unique(
         comparisons.flatMap((c) =>
-          c.observed.edges.added.map((e) =>
-            e.source && e.target && e.type
-              ? `${e.source}→${e.target}:${e.type}`
-              : JSON.stringify(e),
-          ),
+          c.observed.edges.added
+            .filter((e) => e.source && e.target && e.type)
+            .map((e) => edgeEvolutionIdentity(e)),
         ),
       ),
       removed: unique(
         comparisons.flatMap((c) =>
-          c.observed.edges.removed.map((e) =>
-            e.source && e.target && e.type
-              ? `${e.source}→${e.target}:${e.type}`
-              : JSON.stringify(e),
-          ),
+          c.observed.edges.removed
+            .filter((e) => e.source && e.target && e.type)
+            .map((e) => edgeEvolutionIdentity(e)),
         ),
       ),
     },
@@ -983,6 +985,21 @@ function buildEvolutionSummary(comparisons) {
   };
 
   const notes = unique(comparisons.flatMap((c) => c.notes ?? []));
+  const unnamedEdges = comparisons.reduce(
+    (count, c) =>
+      count +
+      [...c.observed.edges.added, ...c.observed.edges.removed].filter(
+        (e) => !(e.source && e.target && e.type),
+      ).length,
+    0,
+  );
+  if (unnamedEdges > 0) {
+    // The house shape for "we could not name it": a note naming the gap,
+    // never a silent drop dressed as a clean union.
+    notes.push(
+      `${unnamedEdges} changed edge(s) carry no complete identity and are not named in observed.edges`,
+    );
+  }
   return {
     transitions: comparisons.length,
     disposition,

package/src/commands/explain.mjs

@@ -79,7 +79,11 @@
  * was: the field, and its rendered lines, exist only when the comparison was
  * requested.
  */
-import { isWholeFileFailure } from "../analysis/source-util.mjs";
+import {
+  blindSpotRows,
+  isWholeFileFailure,
+  unresolvableLiteralCount,
+} from "../analysis/source-util.mjs";
 import { UsageError } from "../errors.mjs";
 import { evaluate } from "../rules/index.mjs";
 import { findConstraintsFor } from "../rules/tags.mjs";
@@ -369,7 +373,13 @@ export function explainCommand(site, commandContext, config, options = {}) {
     .filter(isWholeFileFailure)
     .map(({ sourceFile, reason }) => ({ file: sourceFile, reason }));
 
-  const complete = notAnalyzed.length === 0;
+  // An unresolvable site was seen but never judged (#595): the graph is
+  // missing whatever edge that site would have drawn, and rules that judge
+  // the whole graph (circularity, lazy loading) would answer over a gap. The
+  // explanation still reports — status no-verdict — naming the site in
+  // `coverage.blindSpots`, the same contract `graph`/`discover` run.
+  const blindSpotCount = unresolvableLiteralCount(commandContext.analysis.failures);
+  const complete = notAnalyzed.length === 0 && blindSpotCount === 0;
   const status = complete ? "ok" : "no-verdict";
 
   // Find the import record at this site.
@@ -422,14 +432,7 @@ export function explainCommand(site, commandContext, config, options = {}) {
         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: blindSpotRows(commandContext.analysis.failures),
         notes: [],
       };
 
@@ -576,9 +579,7 @@ export function explainCommand(site, commandContext, config, options = {}) {
     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: blindSpotRows(commandContext.analysis.failures),
     notes: [],
   };
 

package/src/commands/fitness.mjs

@@ -45,10 +45,11 @@
  * sorted; JSON rides `canonicalizeJson`. Two runs over an unchanged tree and
  * policy 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 { formatFitnessSection } from "../report/text.mjs";
 import { resolveProvenance } from "./provenance.mjs";
+import { coverageRefusal, coverageVerdict } from "./coverage-verdict.mjs";
 import { driftForCheck } from "./drift.mjs";
 import {
   evaluateFitness,
@@ -114,9 +115,13 @@ export function declaresFitness(config) {
  *
  * @param {object} commandContext From `resolveCommandContext`.
  * @param {{config?: object|null}} [io] The loaded policy, injectable for tests.
- * @returns {Promise<{status: "ok"|"findings"|"no-verdict", fitness: object, coverage: object,
- *   report: {text: string, json: string}}>}
- * @throws {Error} on every condition the header lists, all exit-3 class.
+ * @returns {Promise<{status: "ok"|"findings"|"no-verdict", fitness?: object,
+ *   coverage: object, report: {text: string, json: string}}>}
+ *   `status: "no-verdict"` from the coverage refusal carries no `fitness`
+ *   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 fitnessCommand(commandContext, io = {}) {
   const { root, provider, marker, analysis } = commandContext;
@@ -129,18 +134,16 @@ export async function fitnessCommand(commandContext, io = {}) {
     );
   }
 
-  // A verdict over a tree it could not fully read is a guess. Same refusal
-  // `drift`/`graph`/`diff` make for the same condition.
-  const notAnalyzed = analysis.failures
-    .filter(isWholeFileFailure)
-    .map(({ sourceFile, reason }) => ({ file: sourceFile, reason }));
-  if (notAnalyzed.length > 0) {
-    throw new Error(
-      `archkeep: fitness has incomplete coverage — ${notAnalyzed.length} file` +
-        `${notAnalyzed.length === 1 ? "" : "s"} could not be analyzed, so every coverage ` +
-        `and graph claim would be ambiguous between "clean" and "never seen". Fix the ` +
-        `unanalyzed files and re-run.`,
-    );
+  // A verdict over a tree it could not fully read is a guess. 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. The unified
+  // completeness returns the no-verdict envelope instead, for every axis the
+  // envelope law already withholds over.
+  const completeness = coverageVerdict(commandContext);
+  if (!completeness.complete) {
+    return coverageRefusal({ command: "fitness", commandContext, what: "judging fitness" });
   }
 
   // `drift-free` judges the SAME verdict-shaped intent `check`'s fold builds —
@@ -192,9 +195,7 @@ export async function fitnessCommand(commandContext, io = {}) {
     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/graph.mjs

@@ -10,6 +10,13 @@
  * `entryPoints`, or `declaredPackages`). It is descriptive: it never exits 1,
  * because a snapshot of what is is never a finding.
  *
+ * Its completeness verdict is not computed here: `graphCommand` composes
+ * `./coverage-verdict.mjs`'s `coverageVerdict`, the one constructor every
+ * refusal-contract face reads, so this snapshot's `status`/`exitCode` cannot
+ * drift from the axes `check` judges completeness over. The graph-family
+ * restatement this replaces is how the zero-analysis axis went missing here
+ * while every other face carried it (#612).
+ *
  * What it needs from its caller is a `CommandContext` — the preamble every
  * command shares (`./context.mjs`). What it gives back is a `status`, the
  * payload for both the text and the JSON renderers, and enough coverage
@@ -29,11 +36,12 @@
  */
 import { createHash } from "node:crypto";
 
-import { isWholeFileFailure } from "../analysis/source-util.mjs";
 import { canonicalizeJson } from "../canonical.mjs";
 import { DEFAULT_WORKSPACE_LAYOUT } from "../rules/specifiers.mjs";
 import { jsonEnvelope, renderJson } from "../report/json.mjs";
 import { formatGraphReport } from "../report/graph-text.mjs";
+import { coverageIncompleteReasons } from "../verdict.mjs";
+import { coverageVerdict } from "./coverage-verdict.mjs";
 import { resolveProvenance } from "./provenance.mjs";
 
 /**
@@ -218,13 +226,24 @@ export function graphCommand(commandContext, { config = null } = {}) {
     );
   }
 
-  const notAnalyzed = commandContext.analysis.failures
-    .filter(isWholeFileFailure)
-    .map(({ sourceFile, reason }) => ({ file: sourceFile, reason }));
+  // The completeness verdict is the shared constructor's, not this file's:
+  // restating the axes here is how the `analyzed > 0` term went missing from
+  // this face while `check` carried it (#612 — a run that judged no file at
+  // all used to report `ok` / `complete: true` / exit 0, byte-for-byte the
+  // envelope a clean workspace gets). `coverageVerdict` owns the one law —
+  // no whole-file failure, no unjudged site, at least one file analyzed —
+  // and the same return shape the envelope and the text face both read.
+  const verdict = coverageVerdict(commandContext);
+  const { complete, status, exitCode } = verdict;
 
-  const complete = notAnalyzed.length === 0;
-  const status = complete ? "ok" : "no-verdict";
-  const exitCode = complete ? 0 : 3;
+  // The clauses the text face renders over an incomplete run, worded by the
+  // same function `verdictFor` joins into `decision.reason` — one wording,
+  // two renderings, and neither can drift from the other.
+  const coverageIncomplete = coverageIncompleteReasons({
+    unchecked: verdict.notAnalyzed.length,
+    blindSpots: verdict.blindSpotCount,
+    analyzed: commandContext.analysis.analyzed,
+  });
 
   const projects = buildProjects(graph.nodes);
   const dependencies = buildDependencies(graph.dependencies);
@@ -244,10 +263,8 @@ export function graphCommand(commandContext, { config = null } = {}) {
     projects: projects.length,
     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 })),
+    notAnalyzed: verdict.notAnalyzed,
+    blindSpots: verdict.blindSpots,
     notes: [],
   };
 
@@ -290,6 +307,7 @@ export function graphCommand(commandContext, { config = null } = {}) {
         workspaceLayout,
         workspaceLayoutSource,
         coverage,
+        coverageIncomplete,
       }),
       json: renderJson(envelope),
     },

package/src/commands/health.mjs

@@ -43,7 +43,11 @@
  * It does not print, and it does not decide the process's exit code —
  * `../../cli.mjs` owns those (`./README.md`).
  */
-import { isWholeFileFailure } from "../analysis/source-util.mjs";
+import {
+  blindSpotRows,
+  isWholeFileFailure,
+  unresolvableLiteralCount,
+} from "../analysis/source-util.mjs";
 import { buildDependencies, buildProjects } from "./graph.mjs";
 import { jsonEnvelope, renderJson } from "../report/json.mjs";
 import { formatHealthReport } from "../report/health-text.mjs";
@@ -108,7 +112,12 @@ export function healthCommand(commandContext, io = {}) {
   const edges = buildDependencies(graph.dependencies);
 
   // The run's coverage facts, the same shape every command's envelope carries.
-  const fileComplete = analysis.failures.filter(isWholeFileFailure).length === 0;
+  // An unresolvable site is a fact the run saw but never judged (#595) —
+  // metrics measured over it would read precision the run does not have,
+  // so it defeats file completeness the way a whole-file failure does.
+  const fileComplete =
+    analysis.failures.filter(isWholeFileFailure).length === 0 &&
+    unresolvableLiteralCount(analysis.failures) === 0;
   // The graph is complete only when the files are AND the graph actually sees
   // every polyglot edge — an Nx workspace with an unregistered plugin carries
   // a graph with no Go/Rust/Python edges, which `graph`/`impact` refuse and
@@ -123,9 +132,7 @@ export function healthCommand(commandContext, io = {}) {
     notAnalyzed: analysis.failures
       .filter(isWholeFileFailure)
       .map(({ sourceFile, reason }) => ({ file: sourceFile, reason })),
-    blindSpots: analysis.failures
-      .filter((f) => !isWholeFileFailure(f))
-      .map(({ sourceFile, line, column, reason }) => ({ file: sourceFile, line, column, reason })),
+    blindSpots: blindSpotRows(analysis.failures),
     notes: graphComplete
       ? []
       : [

package/src/commands/history.mjs

@@ -74,12 +74,17 @@ import { createHash } from "node:crypto";
 import { existsSync, readdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { basename, join, resolve } from "node:path";
 
-import { isWholeFileFailure } from "../analysis/source-util.mjs";
+import {
+  blindSpotRows,
+  isWholeFileFailure,
+  unresolvableLiteralCount,
+} from "../analysis/source-util.mjs";
+import { canonicalizeJson } from "../canonical.mjs";
 import { containmentViolation } from "../containment.mjs";
 import { classifyEvolution } from "../governance/evolution-event.mjs";
 import { jsonEnvelope, renderJson } from "../report/json.mjs";
 import { formatHistoryReport } from "../report/history-text.mjs";
-import { computeDiff, edgeIdentityKey, parseBaseline } from "./diff.mjs";
+import { computeDiff, parseBaseline } from "./diff.mjs";
 import { buildDependencies, buildProjects } from "./graph.mjs";
 import { resolveProvenance } from "./provenance.mjs";
 import { compareSnapshotMetadata } from "./snapshot-meta.mjs";
@@ -117,17 +122,17 @@ export function snapshotIdentity({ projects, dependencies, policy }) {
     type,
     tags,
   }));
-  const canonical = JSON.stringify(
-    { projects: identityProjects, dependencies, policy: policy?.fingerprint ?? null },
-    (_, value) =>
-      value !== null && typeof value === "object" && !Array.isArray(value)
-        ? Object.fromEntries(
-            Object.keys(value)
-              .sort()
-              .map((key) => [key, value[key]]),
-          )
-        : value,
-  );
+  // The canonical string comes from `../canonical.mjs` — the one canonicalizer
+  // ("one canonicalizer, in one place, so two serializations cannot drift").
+  // This digest's private inline replacer was the last serialization site
+  // beside it (#613); `history.test.mjs` pins the digest byte-identical to the
+  // retired spelling on every snapshot shape, so composing it moved no byte an
+  // unchanged workspace ever saw.
+  const canonical = canonicalizeJson({
+    projects: identityProjects,
+    dependencies,
+    policy: policy?.fingerprint ?? null,
+  });
   return createHash("sha256").update(canonical).digest("hex");
 }
 
@@ -397,8 +402,12 @@ export function classifyTransition(from, to) {
         changed: diff.changedProjects.map((project) => project.name),
       },
       edges: {
-        added: diff.addedEdges.map(edgeIdentityKey),
-        removed: diff.removedEdges.map(edgeIdentityKey),
+        // The raw triples — `classifyEvolution` maps them through its own
+        // identity spelling (`edgeEvolutionIdentity`), so `affected.boundaries`
+        // carries the canonical strings every other event surface uses, not
+        // this module's diff-internal key spelling.
+        added: diff.addedEdges,
+        removed: diff.removedEdges,
       },
       policyChanged: meta.policyChanged,
       policyOneSided: meta.policyOneSided,
@@ -554,10 +563,23 @@ export function historyCommand(
     const notAnalyzed = commandContext.analysis.failures
       .filter(isWholeFileFailure)
       .map(({ sourceFile, reason }) => ({ file: sourceFile, reason }));
-    if (notAnalyzed.length > 0) {
+
+    const blindSpotCount = unresolvableLiteralCount(commandContext.analysis.failures);
+    if (notAnalyzed.length > 0 || blindSpotCount > 0) {
       throw new Error(
-        `archkeep: the head graph has incomplete coverage — ${notAnalyzed.length} file` +
-          `${notAnalyzed.length === 1 ? "" : "s"} could not be analyzed, so a captured snapshot ` +
+        `archkeep: the head graph has incomplete coverage — ` +
+          [
+            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 
+a captured snapshot ` +
           `would under-represent the real architecture. Fix the unanalyzed files and re-run.`,
       );
     }
@@ -608,14 +630,7 @@ export function historyCommand(
           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: blindSpotRows(commandContext.analysis.failures),
           notes: [],
         },
         result: { ...head, policy: headPolicy ?? undefined },