@ecoma-io/archkeep 0.21.0 → 0.22.1

package/src/governance/evolution-event.mjs

@@ -107,15 +107,102 @@ export function declarationDigest(intent) {
   });
 }
 
+/**
+ * The escape character every identity spelling below uses, and the one
+ * function that applies it. A field that carries none of `\`, `>` or `:` and
+ * is not exactly `-` is returned byte-identical — the overwhelmingly common
+ * case, which is what keeps this escaping from rewriting the stored events of
+ * workspaces whose names never carried a delimiter (#627's fix is
+ * conditional by design; a wholesale re-encode on the `boundaryKey`
+ * pattern would change the persisted bytes of every workspace). A field that
+ * does carry one is escaped, so the delimiters that remain unescaped in an
+ * identity string are exactly the separators, and distinct field tuples can
+ * no longer join to the same string (#627). The sentinel `-` (`#628` writes
+ * it for an absent source project) escapes to `\-`, so a field that literally
+ * is `-` can no longer read as "absent" — `\-` in an identity string can only
+ * ever have come from field data.
+ *
+ * @param {string} value One field of an identity string.
+ * @returns {string} The field, escaped iff escaping is needed.
+ */
+export function escapeIdentityField(value) {
+  if (!value.includes("\\") && !value.includes(">") && !value.includes(":") && value !== "-") {
+    return value;
+  }
+  // Backslash first, so it never escapes an escape this pass itself wrote.
+  return value
+    .replaceAll("\\", "\\\\")
+    .replaceAll(">", "\\>")
+    .replaceAll(":", "\\:")
+    .replace(/^-$/u, "\\-");
+}
+
+/**
+ * The identity string of one graph edge, in the canonical spelling
+ * `source>target:type` — the `(source, target, type)` identity design §1
+ * names. The ONE spelling the evolution events' `observed.edges` and
+ * `affected.boundaries` use: this module owns it, and `classifyEvolution`
+ * maps every edge it is handed through this function, so there is exactly
+ * one definition of "same edge" and no second spelling to drift. Fields are
+ * escaped through `escapeIdentityField`, so the unescaped `>` and `:` in the
+ * result are the separators and two distinct triples never join to one
+ * string (#627) — while a triple with no delimiter in any field spells
+ * exactly what earlier versions spelled, byte for byte.
+ *
+ * @param {{source: string, target: string, type: string}} edge
+ * @returns {string}
+ */
+export function edgeEvolutionIdentity({ source, target, type }) {
+  return `${escapeIdentityField(source)}>${escapeIdentityField(target)}:${escapeIdentityField(type)}`;
+}
+
+/**
+ * The one accepted input shape for an `observed.edges` entry: the raw
+ * `{source, target, type}` triple. A caller handing over a ready-made string
+ * would be choosing a second spelling of "same edge", so a string is refused
+ * loudly rather than accepted as one shape more — the identity string is this
+ * module's output, never its input.
+ *
+ * @param {unknown} entry
+ * @returns {string}
+ */
+function evolutionBoundary(entry) {
+  if (
+    typeof entry !== "object" ||
+    entry === null ||
+    !("source" in entry) ||
+    typeof entry.source !== "string" ||
+    entry.source === "" ||
+    !("target" in entry) ||
+    typeof entry.target !== "string" ||
+    entry.target === "" ||
+    !("type" in entry) ||
+    typeof entry.type !== "string"
+  ) {
+    throw new TypeError(
+      "classifyEvolution: observed.edges entries must be {source, target, type} triples — " +
+        "the identity string is classifyEvolution's own output spelling, never an input",
+    );
+  }
+  // The guard above has verified every property; the annotation only states
+  // what it proved.
+  return edgeEvolutionIdentity(
+    /** @type {{source: string, target: string, type: string}} */ (entry),
+  );
+}
+
 /**
  * @typedef {object} EvolutionEvidence
  * @property {{projects?: {added: string[], removed: string[], changed: string[]},
- *   edges?: {added: string[], removed: string[]},
+ *   edges?: {added: {source: string, target: string, type: string}[],
+ *   removed: {source: string, target: string, type: string}[]},
  *   policyChanged?: boolean|null, policyOneSided?: boolean,
  *   provenanceChanged?: boolean|null}} [observed]
- *   The structural diff between base and head: project names and edge identity
- *   strings (source,target,type) that were added, removed, or changed. Empty
- *   by default. `policyChanged` — whether the policy fingerprint changed
+ *   The structural diff between base and head: project names and raw edge
+ *   triples that were added, removed, or changed. The triples are mapped
+ *   through `edgeEvolutionIdentity` here — the identity spelling is this
+ *   module's own, so `affected.boundaries` comes out as identity strings
+ *   whichever shape the caller held. Empty by default. `policyChanged` — whether the policy fingerprint changed
  *   between base and head; `null` is "could not be compared": exactly one side
  *   records the policy (`policyOneSided: true`) or neither does
  *   (both-absent). `true` is a disclosure, never a refusal. `policyOneSided`
@@ -197,9 +284,9 @@ export function declarationDigest(intent) {
  *   absent (`null`) ⇒ NOT asserted, note added |
  *
  * The `affected` identities are derived from the same signals, never from a
- * second opinion: changed project names, changed edge identity strings, the
- * constraint/intent rows whose verdict was not `pass`/`matched`, and the ADR
- * ids whose lineage moved.
+ * second opinion: changed project names, the changed edges under the one
+ * identity spelling (`edgeEvolutionIdentity`), the constraint/intent rows
+ * whose verdict was not `pass`/`matched`, and the ADR ids whose lineage moved.
  *
  * @param {EvolutionEvidence} [input]
  * @returns {EvolutionClassification}
@@ -211,8 +298,8 @@ export function classifyEvolution(input = {}) {
   const addedProjects = projects.added ?? [];
   const removedProjects = projects.removed ?? [];
   const changedProjects = projects.changed ?? [];
-  const addedEdges = edges.added ?? [];
-  const removedEdges = edges.removed ?? [];
+  const addedEdges = (edges.added ?? []).map(evolutionBoundary);
+  const removedEdges = (edges.removed ?? []).map(evolutionBoundary);
   const structureChanged =
     addedProjects.length +
       removedProjects.length +

package/src/intent/intent-manifest.json

@@ -1,7 +1,7 @@
 {
   "version": 2,
   "generatedAt": "v1.0.0-hardening",
-  "description": "Machine-readable manifest declaring every v1.0 intent and the evidence that supports it. A contract is 'proven' only when at least one evidence entry is an executable proof (behavioral-test, e2e-test, or architecture-test). Source-evidence and documentation support the claim but cannot prove it alone.",
+  "description": "Machine-readable manifest declaring every v1.0 intent and the evidence that supports it. A contract is 'proven' only when at least one evidence entry is an executable proof (behavioral-test, e2e-test, or architecture-test). Source-evidence and documentation support the claim but cannot prove it alone. Every evidence entry carries the sha256 of the artifact it names, and the gate recomputes each digest, so evidence is content-addressed: an artifact that changed after its claim was certified is a loud mismatch, not a silent swap.",
   "evidenceTaxonomy": {
     "behavioral-test": "A unit or integration test that imports and calls the code, asserting on runtime behavior (not source text). Proves the intent is regression-protected.",
     "e2e-test": "A CLI subprocess test that exercises the real binary against a consumer workspace. Proves the intent holds end-to-end.",
@@ -19,12 +19,14 @@
         {
           "type": "architecture-test",
           "path": "src/conformance/boundary.test.mjs",
-          "assertion": "SHIPPED_PACKAGES allow-list prevents unapproved dependencies; specifiersIn() walk catches all imports including createRequire; no provider import found in core layers"
+          "assertion": "SHIPPED_PACKAGES allow-list prevents unapproved dependencies; specifiersIn() walk catches all imports including createRequire; no provider import found in core layers",
+          "sha256": "12d4e179f88de2622a41e56f42b2bab1c88a677ec2232430752138c57ba5fb18"
         },
         {
           "type": "source-evidence",
           "path": "src/commands/context.mjs",
-          "assertion": "Only commands/context.mjs imports providers — the designated orchestration layer"
+          "assertion": "Only commands/context.mjs imports providers — the designated orchestration layer",
+          "sha256": "7f566c06afbb175337529bd9bdc42465f8849498b932abf6a77fe0290a0cd13c"
         }
       ],
       "status": "proven"
@@ -37,17 +39,20 @@
         {
           "type": "behavioral-test",
           "path": "src/report/json.test.mjs",
-          "assertion": "JSON envelope throws on status=ok + incomplete coverage, status/exitCode disagreement, coverage.complete/notAnalyzed disagreement"
+          "assertion": "JSON envelope throws on status=ok + incomplete coverage, status/exitCode disagreement, coverage.complete/notAnalyzed disagreement",
+          "sha256": "a371d36b89b10c5a4bda4d9e9a2e3bde114256c1377eb95699c9f0f195aabc4a"
         },
         {
           "type": "source-evidence",
           "path": "src/lsp/diagnose.mjs",
-          "assertion": "analyzed:false on every non-verdict path; empty diagnostic list only from two named places"
+          "assertion": "analyzed:false on every non-verdict path; empty diagnostic list only from two named places — plus a document whose only positioned failure is an external disclosure, which was judged and so is not published (#603)",
+          "sha256": "72196def14055475ccb23284a3c5d34167535a506985b26fb95af097545cc740"
         },
         {
           "type": "source-evidence",
           "path": "cli.mjs",
-          "assertion": "Exit codes 0/1/3 distinguish clean/findings/cannot-look"
+          "assertion": "Exit codes 0/1/3 distinguish clean/findings/cannot-look",
+          "sha256": "81abe8243660b3cca913ee903c1fc0bfcdb6a240640c5302f18848e6a9473fe6"
         }
       ],
       "status": "proven"
@@ -60,17 +65,26 @@
         {
           "type": "behavioral-test",
           "path": "src/intent/intent.test.mjs",
-          "assertion": "analysis output conforms to the frozen contract schema (no extra verdict/policy fields); analysis output is invariant under project tag changes; analysis source contains no judging vocabulary"
+          "assertion": "analysis output conforms to the frozen contract schema (no extra verdict/policy fields); analysis output is invariant under project tag changes (three workspaces differing only in project tag fields compared byte-for-byte)",
+          "sha256": "6ed86cb5e7af94b56fa2af3d2da5d45d58937fbbf316105da0224d0060e88582"
+        },
+        {
+          "type": "architecture-test",
+          "path": "src/intent/intent.test.mjs",
+          "assertion": "the gate walks every production analysis module and fails when judging vocabulary (judge/forbid/permit/allow/ban) appears in code",
+          "sha256": "6ed86cb5e7af94b56fa2af3d2da5d45d58937fbbf316105da0224d0060e88582"
         },
         {
           "type": "source-evidence",
           "path": "src/analysis/contract.md",
-          "assertion": "Analysis record is a superset of a graph edge — 5 of 15 violations decided on raw specifier"
+          "assertion": "Analysis record is a superset of a graph edge — 5 of 15 violations decided on raw specifier",
+          "sha256": "56d2db7816ba5ffc5fbe9e299f7d5e270a857b42eb54bd3bea7c05da17be595b"
         },
         {
           "type": "source-evidence",
           "path": "AGENTS.md",
-          "assertion": "src/graph/ is a lossy view of analysis, on purpose; src/analysis/ never judges"
+          "assertion": "src/graph/ is a lossy view of analysis, on purpose; src/analysis/ never judges",
+          "sha256": "3209154935cc1463127721203da74dc8bf8ba40258b182c5faa7345946611e38"
         }
       ],
       "status": "proven"
@@ -83,17 +97,20 @@
         {
           "type": "e2e-test",
           "path": "e2e/determinism.e2e.mjs",
-          "assertion": "Graph, check, impact run twice — byte-identical JSON output"
+          "assertion": "Graph, check, impact run twice — byte-identical JSON output",
+          "sha256": "90c0f2a62a111013990ff96ec07042e961c1aae50710c597192657cc270df5ec"
         },
         {
           "type": "source-evidence",
           "path": "src/commands/graph.mjs",
-          "assertion": "Plain string comparison, never localeCompare; INTERNAL_DATA_FIELDS stripped; SCHEMA_VERSION = 2"
+          "assertion": "Plain string comparison, never localeCompare; INTERNAL_DATA_FIELDS stripped; SCHEMA_VERSION = 2",
+          "sha256": "25ece527ff5ea847f5863314a12c50c95a80f995d36d3aeb756ca022dd72f283"
         },
         {
           "type": "source-evidence",
           "path": "src/commands/graph.mjs",
-          "assertion": "computePolicyFingerprint produces SHA-256 of canonicalized policy"
+          "assertion": "computePolicyFingerprint produces SHA-256 of canonicalized policy",
+          "sha256": "25ece527ff5ea847f5863314a12c50c95a80f995d36d3aeb756ca022dd72f283"
         }
       ],
       "status": "proven"
@@ -106,12 +123,14 @@
         {
           "type": "e2e-test",
           "path": "e2e/diff.e2e.mjs",
-          "assertion": "Invalid baseline schemaVersion exits 3; incompatible version exits 3"
+          "assertion": "Invalid baseline schemaVersion exits 3; incompatible version exits 3",
+          "sha256": "7892a6dc56f5e1ec725fd6d029bba76bc493d8c34790f346e15af0d7d0dbbdc1"
         },
         {
           "type": "source-evidence",
           "path": "src/commands/diff.mjs",
-          "assertion": "parseBaseline validates schemaVersion; refuses unknown versions"
+          "assertion": "parseBaseline validates schemaVersion; refuses unknown versions",
+          "sha256": "6190013ec55eeb7f1a9e4cdd910c7be73bfb1fa87051bdeace7c9581c6a18426"
         }
       ],
       "status": "proven"
@@ -124,12 +143,14 @@
         {
           "type": "e2e-test",
           "path": "e2e/diff.e2e.mjs",
-          "assertion": "Self-baseline exits 0; added/removed edges reported; policy mismatch warned; rule-impact with config"
+          "assertion": "Self-baseline exits 0; added/removed edges reported; policy mismatch warned; rule-impact with config",
+          "sha256": "7892a6dc56f5e1ec725fd6d029bba76bc493d8c34790f346e15af0d7d0dbbdc1"
         },
         {
           "type": "source-evidence",
           "path": "src/commands/diff.mjs",
-          "assertion": "computeDiff returns structural diff; policyMismatch detected via fingerprint; computeRuleImpact for depConstraints-only context"
+          "assertion": "computeDiff returns structural diff; policyMismatch detected via fingerprint; computeRuleImpact for depConstraints-only context",
+          "sha256": "6190013ec55eeb7f1a9e4cdd910c7be73bfb1fa87051bdeace7c9581c6a18426"
         }
       ],
       "status": "proven"
@@ -142,12 +163,14 @@
         {
           "type": "e2e-test",
           "path": "e2e/determinism.e2e.mjs",
-          "assertion": "Impact --format json produces identical output on two runs"
+          "assertion": "Impact --format json produces identical output on two runs",
+          "sha256": "90c0f2a62a111013990ff96ec07042e961c1aae50710c597192657cc270df5ec"
         },
         {
           "type": "behavioral-test",
           "path": "src/commands/impact.test.mjs",
-          "assertion": "Sorts results using plain string comparison (never localeCompare)"
+          "assertion": "Sorts results using plain string comparison (never localeCompare)",
+          "sha256": "b188d7001d146c203be490727414f0c585d8e589f10e3a9add40a34b5aedd532"
         }
       ],
       "status": "proven"
@@ -160,17 +183,20 @@
         {
           "type": "behavioral-test",
           "path": "src/commands/context-command.test.mjs",
-          "assertion": "Returns tags, matched constraints, per-edge violations; coverage.notes warns about depConstraints-only scope"
+          "assertion": "Returns tags, matched constraints, per-edge violations; coverage.notes warns about depConstraints-only scope",
+          "sha256": "eccd31e3057bbb0cb45785e0047e0d71e83dbbc00703ee231f085cf52fb76db8"
         },
         {
           "type": "e2e-test",
           "path": "e2e/context.e2e.mjs",
-          "assertion": "Native consumer: tags, constraints, coverage.notes verified; Moon consumer: context E2E"
+          "assertion": "Native consumer: tags, constraints, coverage.notes verified; Moon consumer: context E2E",
+          "sha256": "336994ea66e2b7b7ff1d374e3127b478d530508b8c8e5ef927805c5aa11b6cb8"
         },
         {
           "type": "documentation",
           "path": "../../docs/concepts/agentic-development.md",
-          "assertion": "Section 'What context and impact do not check' warns agents about the semantic gap"
+          "assertion": "Section 'What context and impact do not check' warns agents about the semantic gap",
+          "sha256": "a42bca1e927a59d28160eb947a285c20d1a6cc9633a69c91a45e9d46bbe1686b"
         }
       ],
       "status": "proven"
@@ -183,12 +209,14 @@
         {
           "type": "behavioral-test",
           "path": "src/commands/explain.test.mjs",
-          "assertion": "Returns all violations at a site; unresolvable site returns unresolvable:true with reason"
+          "assertion": "Returns all violations at a site; unresolvable site returns unresolvable:true with reason",
+          "sha256": "017581d978f277fadecedd6a4a0a4befca3743dbf2b084e1192792a1891466ad"
         },
         {
           "type": "e2e-test",
           "path": "e2e/explain.e2e.mjs",
-          "assertion": "Native and Moon consumers: specifier, sourceProject, targetProject, violations verified"
+          "assertion": "Native and Moon consumers: specifier, sourceProject, targetProject, violations verified",
+          "sha256": "857e198249c0614af643f784d985ae782ab8dfa9906f92f44193e2570ee0c343"
         }
       ],
       "status": "proven"
@@ -201,37 +229,44 @@
         {
           "type": "behavioral-test",
           "path": "src/intent/intent.test.mjs",
-          "assertion": "depConstraints verdicts from judgeEdge agree with evaluate; explain includes the same violations as evaluate at a given site; diff warns in coverage.notes when ruleImpact is computed"
+          "assertion": "depConstraints verdicts from judgeEdge agree with evaluate in both directions (violating edge found by both, legal edge reported by neither); explain includes the same violations as evaluate at a given site",
+          "sha256": "6ed86cb5e7af94b56fa2af3d2da5d45d58937fbbf316105da0224d0060e88582"
         },
         {
           "type": "behavioral-test",
           "path": "src/commands/context-command.test.mjs",
-          "assertion": "Test verifies coverage.notes contains depConstraints warning"
+          "assertion": "Test verifies coverage.notes contains depConstraints warning",
+          "sha256": "eccd31e3057bbb0cb45785e0047e0d71e83dbbc00703ee231f085cf52fb76db8"
         },
         {
           "type": "e2e-test",
           "path": "e2e/context.e2e.mjs",
-          "assertion": "E2E verifies coverage.notes in JSON envelope"
+          "assertion": "E2E verifies coverage.notes in JSON envelope",
+          "sha256": "336994ea66e2b7b7ff1d374e3127b478d530508b8c8e5ef927805c5aa11b6cb8"
         },
         {
           "type": "source-evidence",
           "path": "src/commands/context-command.mjs",
-          "assertion": "coverage.notes warns that per-edge violations cover only depConstraints (3 of 15 violation types)"
+          "assertion": "coverage.notes warns that per-edge violations cover only depConstraints (3 of 15 violation types)",
+          "sha256": "72526cdaf038da4d9a50b33ab3cb30828713e62bbb891f4e2e51e008a403338e"
         },
         {
           "type": "source-evidence",
           "path": "src/commands/impact.mjs",
-          "assertion": "coverage.notes warns that per-edge violations cover only depConstraints (3 of 15 violation types)"
+          "assertion": "coverage.notes warns that per-edge violations cover only depConstraints (3 of 15 violation types)",
+          "sha256": "38cff166a8944860c51a73316447ce789898751489d783e75fd6befbfd30be3c"
         },
         {
           "type": "source-evidence",
           "path": "src/commands/diff.mjs",
-          "assertion": "coverage.notes warns when ruleImpact is computed (depConstraints only, 3 of 15)"
+          "assertion": "coverage.notes warns when ruleImpact is computed (depConstraints only, 3 of 15)",
+          "sha256": "6190013ec55eeb7f1a9e4cdd910c7be73bfb1fa87051bdeace7c9581c6a18426"
         },
         {
           "type": "documentation",
           "path": "../../docs/concepts/agentic-development.md",
-          "assertion": "Section warns agents: violations:[] means allowed by constraint table, not free of all boundary violations"
+          "assertion": "Section warns agents: violations:[] means allowed by constraint table, not free of all boundary violations",
+          "sha256": "a42bca1e927a59d28160eb947a285c20d1a6cc9633a69c91a45e9d46bbe1686b"
         }
       ],
       "status": "proven"
@@ -244,12 +279,14 @@
         {
           "type": "e2e-test",
           "path": "e2e/determinism.e2e.mjs",
-          "assertion": "Graph, check, impact: two runs produce byte-identical JSON"
+          "assertion": "Graph, check, impact: two runs produce byte-identical JSON",
+          "sha256": "90c0f2a62a111013990ff96ec07042e961c1aae50710c597192657cc270df5ec"
         },
         {
           "type": "source-evidence",
           "path": "src/commands/graph.mjs",
-          "assertion": "Plain string comparison throughout; never localeCompare"
+          "assertion": "Plain string comparison throughout; never localeCompare",
+          "sha256": "25ece527ff5ea847f5863314a12c50c95a80f995d36d3aeb756ca022dd72f283"
         }
       ],
       "status": "proven"
@@ -262,22 +299,26 @@
         {
           "type": "e2e-test",
           "path": "e2e/parity.e2e.mjs",
-          "assertion": "Nx vs Native: project names, edge source/target/type, violation rule IDs, envelope structure"
+          "assertion": "Nx vs Native: project names, edge source/target/type, violation rule IDs, envelope structure",
+          "sha256": "106f59315e4661ae67f5c1e44895d56f7f7562eacd4c44101a9ed4b0e56f774e"
         },
         {
           "type": "e2e-test",
           "path": "e2e/moon.e2e.mjs",
-          "assertion": "Moon: check, graph, diff, impact, explain, context verified against Moon provider (conditional on moon CLI availability)"
+          "assertion": "Moon: check, graph, diff, impact, explain, context verified against Moon provider (conditional on moon CLI availability)",
+          "sha256": "8293a65ff407ea43a3985c742ae6333970ec3b0400f3df46189793a3dc87af6b"
         },
         {
           "type": "source-evidence",
           "path": "src/providers/moon.mjs",
-          "assertion": "inferWorkspaceLayout returns null for partial layouts — same all-or-nothing contract as Nx and Native"
+          "assertion": "inferWorkspaceLayout returns null for partial layouts — same all-or-nothing contract as Nx and Native",
+          "sha256": "232dd8e2cbe70c9149ba3a75a03dcebe0db355894c280964ebbf6a5a536b5567"
         },
         {
           "type": "behavioral-test",
           "path": "src/providers/moon.test.mjs",
-          "assertion": "Partial layout (apps-only, libs-only) returns undefined workspaceLayout"
+          "assertion": "Partial layout (apps-only, libs-only) returns undefined workspaceLayout",
+          "sha256": "084a0061b3236e680274d837fb2f12d27dd4b5a379040157f7afe2be5088e8ac"
         }
       ],
       "status": "proven"
@@ -290,17 +331,20 @@
         {
           "type": "behavioral-test",
           "path": "src/commands/drift.test.mjs",
-          "assertion": "driftCommand returns status ok with observed facts and findings; refuses incomplete coverage, absent intent, and unregistered-plugin incomplete graph; buildObserved counts implicit edges separately"
+          "assertion": "driftCommand returns status ok with observed facts and findings; refuses incomplete coverage, absent intent, and unregistered-plugin incomplete graph; buildObserved counts implicit edges separately",
+          "sha256": "dbb0dfa1ecce9123ad0a38cdd6bc97e6645a47cba78496357318375db952e43a"
         },
         {
           "type": "behavioral-test",
           "path": "src/report/drift-text.test.mjs",
-          "assertion": "formatDriftReport states comparison facts even when clean (no-drift is a claim about coverage); groups findings by rule in taxonomy order; byte-identical determinism"
+          "assertion": "formatDriftReport states comparison facts even when clean (no-drift is a claim about coverage); groups findings by rule in taxonomy order; byte-identical determinism",
+          "sha256": "767d395c40cb0fa61f19ec06d587708e4ba065323bb1ee170254365847b49cc5"
         },
         {
           "type": "e2e-test",
           "path": "e2e/drift.e2e.mjs",
-          "assertion": "Through the installed CLI: drift exits 0 on a matching tree and names fingerprint/rows; reports dependencyForbidden and projectMissing; JSON envelope carries findings; malformed intent exits 3 for both drift and check"
+          "assertion": "Through the installed CLI: drift exits 0 on a matching tree and names fingerprint/rows; reports dependencyForbidden and projectMissing; JSON envelope carries findings; malformed intent exits 3 for both drift and check",
+          "sha256": "1e060ba0f02497259fdde2481dc59bd74bf6658f2fc354100de4f89ff6ffb926"
         }
       ],
       "status": "proven"

package/src/lsp/diagnose.mjs

@@ -42,7 +42,7 @@
  * places outside the boundary system entirely.
  */
 import { analyzeFile } from "../analysis/analyze.mjs";
-import { projectOwning } from "../analysis/source-util.mjs";
+import { isExternalSiteFailure, projectOwning } from "../analysis/source-util.mjs";
 import { declaredEdgeViolationsForCheck } from "../commands/edge-constraints.mjs";
 import { evaluate } from "../rules/index.mjs";
 
@@ -97,10 +97,19 @@ export function diagnoseDocument({ sourceFile, text, index, config }) {
 
   // Recorded failures come next, and they are published whether or not the
   // rule pass below succeeds: they are the part of the file that was NOT
-  // judged, and a reader needs that before they read what was.
+  // judged, and a reader needs that before they read what was. The external
+  // class is not that part (`isExternalSiteFailure`): a bare coordinate that
+  // resolves to the dependency universe was judged — resolved external,
+  // disclosed in the run's blind-spot rows, excluded from the withholding
+  // count — so a warning on it would say "not checked" about a site the
+  // verdict below covers, and one per third-party import would be a wall of
+  // warnings a reader rightly learns to ignore (#603). The workspace-surface
+  // and whole-file classes keep publishing.
   const diagnostics = [
     ...prelude,
-    ...analysis.failures.map((failure) => failureDiagnostic(failure, lines)),
+    ...analysis.failures
+      .filter((failure) => !isExternalSiteFailure(failure))
+      .map((failure) => failureDiagnostic(failure, lines)),
   ];
 
   // The engine derives its evidence index from exactly the records it is

package/src/report/discover-text.mjs

@@ -4,15 +4,27 @@
  *
  * The coverage claim sits ABOVE everything — the reader knows whether the
  * observations are complete before reading any entry, exactly like
- * `./graph-text.mjs`'s report. The proposal, when present, is rendered below
- * the observations with the proposal-only banner (`proposed`, `not
- * authoritative`) repeated on every line of every candidate, so a reader who
- * scans the report cannot mistake a candidate for a decision.
+ * `./graph-text.mjs`'s report. Under an incomplete claim sit the reason
+ * clauses the run withheld the verdict over, worded by
+ * `../verdict.mjs`'s `coverageIncompleteReasons` and rendered through
+ * `./text.mjs`'s `formatCoverageIncomplete` — the same clauses, in the
+ * same `⚠` rendering, `check`'s text report prints, so a terminal reader is
+ * told why the verdict is withheld whichever face ran. A zero-analysis run
+ * is the case that needs this: its `notAnalyzed` list is empty, so a
+ * count-bearing headline would blame zero failures for an incomplete
+ * discovery (#619).
+ *
+ * The proposal, when present, is rendered below the observations with the
+ * proposal-only banner (`proposed`, `not authoritative`) repeated on every
+ * line of every candidate, so a reader who scans the report cannot mistake a
+ * candidate for a decision.
  *
  * This module decides nothing. A formatter that filtered would be a rule
  * wearing a formatter's name (`../README.md`).
  */
 
+import { formatCoverageIncomplete } from "./text.mjs";
+
 /** The three confidence markers, in the order the legend prints them. */
 const CONFIDENCE_ORDER = ["high", "medium", "low"];
 
@@ -96,10 +108,16 @@ function formatRule(item) {
  *
  * @param {{discovery: {projects: object[], edges: object[], tags: string[]},
  *   proposal: object|null,
- *   coverage: object}} input
+ *   coverage: object,
+ *   coverageIncomplete?: string[]}} input
+ *   `coverageIncomplete` is the withheld-verdict clause list
+ *   (`../verdict.mjs`'s `coverageIncompleteReasons`, handed through
+ *   `../commands/discover.mjs`) — rendered below the incomplete headline,
+ *   empty exactly when the discovery is complete, and optional because a
+ *   complete discovery carries no clauses to render.
  * @returns {string}
  */
-export function formatDiscoverReport({ discovery, proposal, coverage }) {
+export function formatDiscoverReport({ discovery, proposal, coverage, coverageIncomplete }) {
   const sections = [];
 
   const inspected =
@@ -110,11 +128,15 @@ export function formatDiscoverReport({ discovery, proposal, coverage }) {
   if (coverage.complete) {
     sections.push(`✔ discovery complete (${inspected})`);
   } else {
-    const notAnalyzedCount = coverage.notAnalyzed.length;
+    // The headline states the incompleteness and its consequence; the clauses
+    // below state WHY, one per failed coverage axis. Blaming the whole-file
+    // count in the headline alone would read "0 files could not be analyzed"
+    // over a zero-analysis run (#619) — incomplete, with a reason of nothing.
     sections.push(
-      `✖ discovery incomplete — ${notAnalyzedCount} file${notAnalyzedCount === 1 ? "" : "s"} ` +
-        `could not be analyzed, so these observations may under-represent the workspace (${inspected})`,
+      `✖ discovery incomplete — these observations may under-represent the workspace (${inspected})`,
     );
+    const clauses = formatCoverageIncomplete(coverageIncomplete ?? []);
+    if (clauses !== "") sections.push(clauses);
   }
 
   const projectWord = discovery.projects.length === 1 ? "project" : "projects";

package/src/report/graph-text.mjs

@@ -12,12 +12,21 @@
  * The coverage claim sits ABOVE the listing, not below it, so the reader knows
  * whether the snapshot is complete before reading any entry — an incomplete
  * snapshot printed in full would have the "this may under-represent" warning
- * buried at the bottom.
+ * buried at the bottom. Under an incomplete claim sit the reason clauses the
+ * run withheld the verdict over, worded by `../verdict.mjs`'s
+ * `coverageIncompleteReasons` and rendered through `./text.mjs`'s
+ * `formatCoverageIncomplete` — the same clauses, in the same `⚠` rendering,
+ * `check`'s text report prints, so a terminal reader is told why the verdict
+ * is withheld whichever face ran. A zero-analysis run is the case that needs
+ * this: its `notAnalyzed` list is empty, so a count-bearing headline would
+ * blame zero failures for an incomplete snapshot.
  *
  * This module decides nothing. A formatter that filtered would be a rule
  * wearing a formatter's name (`../README.md`).
  */
 
+import { formatCoverageIncomplete } from "./text.mjs";
+
 /**
  * One project as a line: name, root, type, and tags.
  *
@@ -44,7 +53,13 @@ function formatEdge(edge) {
  * The whole graph report.
  *
  * @param {{projects: object[], dependencies: object[], workspaceLayout: object,
- *   workspaceLayoutSource: string, coverage: object}} input
+ *   workspaceLayoutSource: string, coverage: object,
+ *   coverageIncomplete?: string[]}} input
+ *   `coverageIncomplete` is the withheld-verdict clause list
+ *   (`../verdict.mjs`'s `coverageIncompleteReasons`, handed through
+ *   `../../commands/graph.mjs`) — rendered below the incomplete headline,
+ *   empty exactly when the snapshot is complete, and optional because a
+ *   complete snapshot carries no clauses to render.
  * @returns {string}
  */
 export function formatGraphReport({
@@ -53,6 +68,7 @@ export function formatGraphReport({
   workspaceLayout,
   workspaceLayoutSource,
   coverage,
+  coverageIncomplete,
 }) {
   const sections = [];
 
@@ -66,11 +82,15 @@ export function formatGraphReport({
   if (coverage.complete) {
     sections.push(`✔ graph snapshot complete (${inspected})`);
   } else {
-    const notAnalyzedCount = coverage.notAnalyzed.length;
+    // The headline states the incompleteness and its consequence; the clauses
+    // below state WHY, one per failed coverage axis. Blaming the whole-file
+    // count in the headline alone would read "0 files could not be analyzed"
+    // over a zero-analysis run (#612) — incomplete, with a reason of nothing.
     sections.push(
-      `✖ graph snapshot incomplete — ${notAnalyzedCount} file${notAnalyzedCount === 1 ? "" : "s"} ` +
-        `could not be analyzed, so this snapshot may under-represent the architecture (${inspected})`,
+      `✖ graph snapshot incomplete — this snapshot may under-represent the architecture (${inspected})`,
     );
+    const clauses = formatCoverageIncomplete(coverageIncomplete ?? []);
+    if (clauses !== "") sections.push(clauses);
   }
 
   // Layout line