@ecoma-io/archkeep 0.22.0 → 0.22.1

package/gate-attestation.mjs

@@ -0,0 +1,23 @@
+/**
+ * The gate-attestation verifier's public face — what a consumer imports from
+ * this package's `./gate-attestation` subpath to validate an attestation with
+ * the version it actually installed.
+ *
+ * It holds no logic on purpose, the same bargain `./commands` (`commands.mjs`)
+ * and `./nx` (`nx.mjs`) make: a named entry that is a re-export, so the
+ * verifier can grow under `src/` without a second copy of any decision
+ * appearing beside it.
+ *
+ * ```js
+ * import { validateGateAttestation, readGateAttestation }
+ *   from "@ecoma-io/archkeep/gate-attestation";
+ * ```
+ */
+export {
+  ATTESTED_PACKAGE,
+  GATE_ATTESTATION_SCHEMA_VERSION,
+  readGateAttestation,
+  reachesCheckVerdict,
+  validateGateAttestation,
+  verifiedAdopters,
+} from "./src/verify-gate-attestation.mjs";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecoma-io/archkeep",
-  "version": "0.22.0",
+  "version": "0.22.1",
   "description": "Architecture enforcement for polyglot repositories — dependency graphs and module boundaries for Go, Rust, Python, TypeScript, JavaScript, Vue, Java and Kotlin",
   "keywords": [
     "architecture",
@@ -29,6 +29,7 @@
     ".": "./index.mjs",
     "./nx": "./nx.mjs",
     "./commands": "./commands.mjs",
+    "./gate-attestation": "./gate-attestation.mjs",
     "./presets/*.json": "./presets/*.json",
     "./package.json": "./package.json"
   },
@@ -36,6 +37,7 @@
     "index.mjs",
     "nx.mjs",
     "commands.mjs",
+    "gate-attestation.mjs",
     "cli.mjs",
     "lsp.mjs",
     "src/",

package/src/analysis/analyze.mjs

@@ -121,6 +121,12 @@ export { LANGUAGE_BY_EXTENSION, languageOf };
  *   the file as a whole rather than one position.
  * @property {number|null} column 1-based, or `null`.
  * @property {string} reason Human-readable; written to be read in a report.
+ * @property {true} [dynamic] The site's target is computed at runtime — the
+ *   language itself declines a static answer. Disclosed without withholding
+ *   (`isDynamicSiteFailure`).
+ * @property {true} [external] The site names the external dependency universe
+ *   rather than the governed graph. Disclosed without withholding
+ *   (`isExternalSiteFailure`); every analyzer sets it (#603).
  */
 
 /**

package/src/analysis/csharp.mjs

@@ -429,6 +429,24 @@ export function analyzeCSharp({ sourceFile, text, workspace }) {
             external: true,
             packageName: site.importableName,
           };
+          // The bare-coordinate class the contract discloses without
+          // withholding (#603): the namespace names the external dependency
+          // universe, not the governed graph, so the site is DISCLOSED — a
+          // positioned row carrying `external: true`
+          // (`isExternalSiteFailure`), the run's verdict untouched — rather
+          // than swallowed, the same classification the TypeScript analyzer
+          // already emits. A name a tracked namespace claims resolved through
+          // the index above and never reaches this branch; the split-package
+          // branch below keeps withholding. The `importableName === null`
+          // arm above is the extern-alias construct, not an unresolvable
+          // coordinate, and stays unfailed.
+          result.failures.push({
+            sourceFile,
+            line,
+            column,
+            reason: `C# cannot resolve '${site.importableName}' from '${sourceFile}'`,
+            external: true,
+          });
         } else if (resolved.ambiguous) {
           resolution = null;
           result.failures.push({

package/src/analysis/go.mjs

@@ -704,6 +704,24 @@ export function analyzeGo({ sourceFile, text, workspace }) {
           packageName: target === null ? site.specifier : null,
         },
       });
+      // The bare-module class the contract discloses without withholding
+      // (#603): the import names the external dependency universe, not the
+      // governed graph, so the site is DISCLOSED — a positioned row carrying
+      // `external: true` (`isExternalSiteFailure`), the run's verdict
+      // untouched — rather than swallowed. An empty blind-spot list must mean
+      // "nothing to disclose", and a workspace whose imports reach outside it
+      // has things to disclose. An import naming a declared module resolved
+      // above and never reaches this branch; the same classification the
+      // TypeScript analyzer already emits.
+      if (target === null) {
+        result.failures.push({
+          sourceFile,
+          line,
+          column,
+          reason: `Go cannot resolve '${site.specifier}' from '${sourceFile}'`,
+          external: true,
+        });
+      }
     }
   } catch (cause) {
     result.failures.push(fileFailure(sourceFile, `Go analysis failed: ${cause?.message ?? cause}`));

package/src/analysis/java.mjs

@@ -235,6 +235,21 @@ export function analyzeJava({ sourceFile, text, workspace }) {
           external: true,
           packageName: site.importableName,
         };
+        // The bare-coordinate class the contract discloses without withholding
+        // (#603): the dotted name names the external dependency universe, not
+        // the governed graph, so the site is DISCLOSED — a positioned row
+        // carrying `external: true` (`isExternalSiteFailure`), the run's
+        // verdict untouched — rather than swallowed, the same classification
+        // the TypeScript analyzer already emits. A name a tracked package
+        // prefix claims resolved through the index above and never reaches
+        // this branch; the split-package branch below keeps withholding.
+        result.failures.push({
+          sourceFile,
+          line,
+          column,
+          reason: `Java cannot resolve '${site.importableName}' from '${sourceFile}'`,
+          external: true,
+        });
       } else if (resolved.ambiguous) {
         // Split package: unresolvable by static reading, so `resolved` is
         // null WITH a positioned failure naming every claimant — the Python

package/src/analysis/kotlin.mjs

@@ -184,6 +184,21 @@ export function analyzeKotlin({ sourceFile, text, workspace }) {
           external: true,
           packageName: site.importableName,
         };
+        // The bare-coordinate class the contract discloses without withholding
+        // (#603): the dotted name names the external dependency universe, not
+        // the governed graph, so the site is DISCLOSED — a positioned row
+        // carrying `external: true` (`isExternalSiteFailure`), the run's
+        // verdict untouched — rather than swallowed, the same classification
+        // the TypeScript analyzer already emits. A name a tracked package
+        // prefix claims resolved through the index above and never reaches
+        // this branch; the split-package branch below keeps withholding.
+        result.failures.push({
+          sourceFile,
+          line,
+          column,
+          reason: `Kotlin cannot resolve '${site.importableName}' from '${sourceFile}'`,
+          external: true,
+        });
       } else if (resolved.ambiguous) {
         resolution = null;
         result.failures.push({

package/src/analysis/python.mjs

@@ -1243,10 +1243,15 @@ export function analyzePython({ sourceFile, text, workspace }) {
           continue;
         }
         if (!site.literal) {
-          fail(
-            `dynamic import of '${site.specifier}' has a non-literal argument, ` +
+          result.failures.push({
+            sourceFile,
+            line,
+            column,
+            reason:
+              `dynamic import of '${site.specifier}' has a non-literal argument, ` +
               `so its target is not knowable statically`,
-          );
+            dynamic: true,
+          });
           continue;
         }
 
@@ -1293,6 +1298,23 @@ export function analyzePython({ sourceFile, text, workspace }) {
             external: true,
             packageName: absolute.split(".")[0],
           };
+          // The bare-package class the contract discloses without withholding
+          // (#603): every layout is modelled and the name still reaches no
+          // tracked package, so the external answer is the language's, and the
+          // site is DISCLOSED — a positioned row carrying `external: true`
+          // (`isExternalSiteFailure`), the run's verdict untouched — rather
+          // than swallowed, the same classification the TypeScript analyzer
+          // already emits. The unmodelled branch above keeps withholding,
+          // because there the external answer is NOT the language's; the
+          // relative-import and ambiguous branches keep withholding because
+          // those names the workspace's own surface.
+          result.failures.push({
+            sourceFile,
+            line,
+            column,
+            reason: `Python cannot resolve '${site.specifier}' from '${sourceFile}'`,
+            external: true,
+          });
         } else if (resolution.ambiguous) {
           fail(
             `'${site.specifier}' resolves through the namespace package '${resolution.prefix}', which ` +

package/src/analysis/rust.mjs

@@ -804,6 +804,24 @@ export function analyzeRust({ sourceFile, text, workspace }) {
           // so a `bannedExternalImports` glob is written against this form.
           packageName: target === null ? site.root : null,
         };
+        // The bare-crate class the contract discloses without withholding
+        // (#603): the `use` names the external dependency universe, not the
+        // governed graph, so the site is DISCLOSED — a positioned row carrying
+        // `external: true` (`isExternalSiteFailure`), the run's verdict
+        // untouched — rather than swallowed, the same classification the
+        // TypeScript analyzer already emits. A name a workspace crate declares
+        // resolved above and never reaches this branch; the brace-group
+        // malformation above keeps withholding, because there the name itself
+        // was never read.
+        if (target === null) {
+          result.failures.push({
+            sourceFile,
+            line,
+            column,
+            reason: `Rust cannot resolve '${site.specifier}' from '${sourceFile}'`,
+            external: true,
+          });
+        }
       }
       result.imports.push({
         sourceFile,

package/src/analysis/source-util.mjs

@@ -395,11 +395,17 @@ export const isDynamicSiteFailure = (failure) => failure.dynamic === true;
  * question can never masquerade as external), and every verdict lane counts
  * by its absence, the same mechanism the `dynamic` marker uses.
  *
- * Only the TypeScript/Vue analyzer sets the field today. The other analyzers'
- * unresolvable literals keep withholding — including legitimately external
- * coordinates (a JVM package coordinate naming an uninstalled library) —
- * which is the over-loud direction and is tracked as its own issue rather
- * than silently tolerated.
+ * Every analyzer sets the field, and each holds the same class line as the
+ * TypeScript/Vue one: only a bare coordinate that genuinely names the
+ * language's dependency universe gets it (a Go module path outside the
+ * workspace modules, a Rust crate outside the workspace crates, a Python
+ * third-party top-level import outside the unmodelled gate, a JVM/C# dotted
+ * name no tracked package or namespace claims), and a specifier naming a
+ * declared workspace project never does — a workspace-edge question must not
+ * masquerade as external. What still withholds is everything that is NOT this
+ * class: a workspace-surface specifier, a Rust brace group, a Python relative
+ * import past the top-level package, an unmodelled layout, a split package
+ * (#603's per-language pins hold both directions).
  *
  * @param {{ line: number|null, external?: true }} failure
  * @returns {boolean}

package/src/canonical.mjs

@@ -11,11 +11,50 @@
  * correct.
  *
  * Used by `computePolicyFingerprint` (`../commands/graph.mjs`), the intent
- * fingerprint (`./intent-fingerprint.mjs`), and anything else a fingerprint
- * is computed over — one canonicalizer, in one place, so two serializations
- * cannot drift.
+ * fingerprint (`./intent-fingerprint.mjs`), the evidence-snapshot serializer
+ * (`./commands/delta-snapshot.mjs`, through the exported replacer below), and
+ * anything else a fingerprint or a byte-deterministic file is produced from —
+ * one canonicalizer, in one place, so two serializations cannot drift.
  */
 
+/**
+ * The `JSON.stringify` replacer that sorts plain-object keys at every depth.
+ *
+ * Exported beside `canonicalizeJson` so a serializer that needs a different
+ * `JSON.stringify` spacing can run the SAME rule rather than grow a second
+ * copy of it: `canonicalizeJson` passes this replacer at compact spacing, and
+ * `./commands/delta-snapshot.mjs`'s `serializeEvidenceSnapshot` passes it at
+ * two-space spacing, so both spellings sort identically by construction.
+ *
+ * @param {string} _key The key being visited; `JSON.stringify` calls the
+ *   replacer once per key and once for the root with `""`.
+ * @param {*} current The value at that key.
+ * @returns {*} The value to serialize in its place — a key-sorted copy when
+ *   `current` is a plain object, `current` itself otherwise.
+ */
+export function canonicalJsonReplacer(_key, current) {
+  if (current !== null && typeof current === "object" && !Array.isArray(current)) {
+    // A null-prototype accumulator, not `{}`: `JSON.parse('{"__proto__":…}')`
+    // produces an OWN key literally named "__proto__" (JSON has no notion of
+    // prototypes), and `sorted[keyName] = …` on an ordinary object treats
+    // that one key specially — it sets the object's prototype instead of
+    // creating an own property, so the key silently vanishes from
+    // `JSON.stringify`'s output. Two documents that disagree only in a
+    // `__proto__` field would then canonicalize identically, a silent
+    // fingerprint collision (`../../../AGENTS.md`, "An empty result is a claim,
+    // not a shrug" — this is the same failure shape: two different inputs
+    // must never produce one indistinguishable output). `Object.create(null)`
+    // has no `__proto__` accessor to intercept the assignment, so every key
+    // — "__proto__" included — always becomes a real own property.
+    const sorted = Object.create(null);
+    for (const keyName of Object.keys(current).sort()) {
+      sorted[keyName] = current[keyName];
+    }
+    return sorted;
+  }
+  return current;
+}
+
 /**
  * Serialize `value` with keys sorted at every object level.
  *
@@ -23,26 +62,5 @@
  * @returns {string} The canonical serialization.
  */
 export function canonicalizeJson(value) {
-  return JSON.stringify(value, (key, current) => {
-    if (current !== null && typeof current === "object" && !Array.isArray(current)) {
-      // A null-prototype accumulator, not `{}`: `JSON.parse('{"__proto__":…}')`
-      // produces an OWN key literally named "__proto__" (JSON has no notion of
-      // prototypes), and `sorted[keyName] = …` on an ordinary object treats
-      // that one key specially — it sets the object's prototype instead of
-      // creating an own property, so the key silently vanishes from
-      // `JSON.stringify`'s output. Two documents that disagree only in a
-      // `__proto__` field would then canonicalize identically, a silent
-      // fingerprint collision (`../../../AGENTS.md`, "An empty result is a claim,
-      // not a shrug" — this is the same failure shape: two different inputs
-      // must never produce one indistinguishable output). `Object.create(null)`
-      // has no `__proto__` accessor to intercept the assignment, so every key
-      // — "__proto__" included — always becomes a real own property.
-      const sorted = Object.create(null);
-      for (const keyName of Object.keys(current).sort()) {
-        sorted[keyName] = current[keyName];
-      }
-      return sorted;
-    }
-    return current;
-  });
+  return JSON.stringify(value, canonicalJsonReplacer);
 }

package/src/commands/README.md

@@ -22,15 +22,18 @@ the resolution order.
   drift, a failing fitness gate, and a failing custom rule
   (`./custom-rules.mjs`). Exits 1 on any of them, and it is the only
   command holding all four exit codes
-  ([which verbs carry exit 1 is settled in `docs/concepts/architecture.md`](../../../../docs/concepts/architecture.md)
-  — `fitness` and `delta` are the other two).
+  ([which verbs carry exit 1 is settled in `docs/reference/exit-codes.md`](../../../../docs/reference/exit-codes.md)
+  — `fitness`, `delta`, `change` and `rules verify` are the other four).
 
 - **`graph`** (`./graph.mjs`'s `graphCommand`) — the project graph as a
   deterministic, serialisable snapshot: projects (with `targets` and `tags`) and
   dependencies, each as a flat sorted array. Strips internal fields
   (`mfeRemote`, `entryPoints`, `declaredPackages`). Includes
-  `workspaceLayout`/`workspaceLayoutSource`. Refuses an Nx workspace with
-  polyglot manifests but no plugin registration. Descriptive: never exits 1.
+  `workspaceLayout`/`workspaceLayoutSource`. Completeness comes from
+  `./coverage-verdict.mjs`'s shared constructor — a whole-file failure, an
+  unjudged site, or a run that analyzed no file at all (#612) is the
+  no-verdict lane. Refuses an Nx workspace with polyglot manifests but no
+  plugin registration. Descriptive: never exits 1.
 
 - **`diff`** (`./diff.mjs`'s `diffCommand`) — two graph snapshots compared edge
   by edge. Takes a baseline file (not a git ref). When a boundary config is
@@ -56,8 +59,9 @@ the resolution order.
   incomplete head coverage, and an Nx workspace with polyglot manifests but no
   plugin registration; a policy-fingerprint change is a loud coverage note, not
   a refusal. A verdict, not a description: a non-waived introduced violation is
-  a finding (exit 1 — then the third verb beside `check` and `fitness`; `change`
-  and its declared-intent question arrived later as the fourth), an
+  a finding (exit 1 — one of the five verdict verbs
+  [`docs/reference/exit-codes.md`](../../../../docs/reference/exit-codes.md)
+  pins), an
   unclassifiable item is a no-verdict (exit 3), and a waived-introduced entry
   is reported without gating. Capture stays descriptive: never exits 1.
 
@@ -75,8 +79,9 @@ the resolution order.
   verdict, and the workspace-law axis it reports is informational — computed,
   labeled as evidence, never folded into the exit code, because `check`
   remains the authority on the law. Undeclared, unfulfilled, or a failed
-  declared constraint is a finding (exit 1 — the fourth verb beside `check`,
-  `fitness`, `delta`); an unproven base identity or an undeterminable
+  declared constraint is a finding (exit 1 — one of the five verdict verbs
+  [`docs/reference/exit-codes.md`](../../../../docs/reference/exit-codes.md)
+  pins); an unproven base identity or an undeterminable
   constraint is exit 3, and constraints are left unevaluated over a base the
   run cannot vouch for. Refuses a manifest that fails shape or reference
   validation, an unreadable/malformed/incomplete baseline, a provider
@@ -198,10 +203,13 @@ the resolution order.
   `../../src/governance/discovery-proposal.mjs`'s pure evaluator over it.
   Proposal-only: every candidate carries `proposed: true` and
   `notAuthoritative: true`, and the command never writes
-  `architecture-intent.json`. Returns `status: "no-verdict"` (exit 3) over
-  incomplete coverage and refuses `--propose` over it; refuses an Nx workspace
-  with polyglot manifests but no plugin registration; a zero-project workspace
-  is the empty `unknown` proposal, not a refusal. Descriptive: never exits 1.
+  `architecture-intent.json`. Completeness comes from
+  `./coverage-verdict.mjs`'s shared constructor — a whole-file failure, an
+  unjudged site, or a run that analyzed no file at all (#619) is the
+  no-verdict lane. Returns `status: "no-verdict"` (exit 3) over incomplete
+  coverage and refuses `--propose` over it; refuses an Nx workspace with
+  polyglot manifests but no plugin registration; a zero-project workspace is
+  the empty `unknown` proposal, not a refusal. Descriptive: never exits 1.
 
 - **`drift`** (`./drift.mjs`'s `driftCommand`) — the observed architecture
   compared against the declared intended one. The intended side is the one
@@ -307,6 +315,49 @@ the resolution order.
   declaration carries is listed `unknown` — named, never hidden. Descriptive:
   never exits 1.
 
+- **`scenario`** (`./scenario.mjs`'s `scenarioCommand`, with the scenario
+  grammar in `./scenario-evaluation.mjs`'s `parseScenarioInput`/`evaluateScenario`)
+  — a hypothetical change evaluated against the current workspace and compared
+  with its present impact. Virtual and read-only by construction: it never
+  mutates the workspace, never writes canonical history, never emits an
+  `EvolutionEvent`, and every output field carries `virtual: true` /
+  `notAuthoritative` — a what-if projection, never an authoritative verdict.
+  Refuses an Nx workspace with polyglot manifests but no plugin registration;
+  incomplete coverage withholds the evaluation as the structured
+  incomplete-coverage refusal (exit 3, no `result`). Descriptive: never exits 1.
+
+- **`decisions`** (`./decisions.mjs`'s `decisionsCommand`) — the deterministic
+  chain behind one recorded decision: the decision, the governed rows that
+  stand on it (intent, constraint and fitness), the projects they govern, the
+  current evidence and findings, and the decision's verification level. It
+  composes the governance modules without owning any of them —
+  `../governance/decision-graph.mjs`'s `forwardDecision` walk,
+  `../governance/decision-fitness.mjs`'s verification level, and the row walk
+  `./provenance-command.mjs` exports, so it never holds a second copy of which
+  rows exist. A binding naming a declared fitness gate is judged against the
+  same snapshot the `fitness` command builds; one naming no declared gate
+  renders `unverifiable` — the registry alone asserts nothing, never a clean
+  pass. Refuses an unreadable registry; an unresolvable reference — the
+  positional `<id>` or any hop of the walk — is rendered as an unresolved block
+  (exit 3), never as a clean chain. Descriptive: never exits 1.
+
+- **`rules`** (`./rules.mjs`'s `rulesListCommand`, `rulesInfoCommand`,
+  `rulesVerifyCommand` and `rulesAddCommand`) — the CLI face of the official
+  rules catalog (`@ecoma-io/archkeep-rules`): `list`, `info`, `verify` and
+  `add`. The catalog is read from the filesystem at a user-resolvable path
+  (explicit `--catalog`, then
+  `node_modules/@ecoma-io/archkeep-rules/catalog.json`), never by import, and
+  artifact integrity is validated through the engine's real host
+  (`../custom-rules/host.mjs`). `verify` is the one verdict verb: exit 1 when
+  the catalog's recorded digests disagree with the shipped bytes (a digest
+  mismatch, an artifact the host refuses, or one that escaped its directory),
+  exit 3 when the catalog could not be read — the two lanes `check` uses, so
+  "the artifact was modified" never reads as "the catalog could not be looked
+  at". `list` and `info` are always exit 0; `add` exits 0 on success and 3 on
+  any failure. Catalog-derived paths are contained to the catalog's own
+  directory (`../containment.mjs`), so data a consumer vendored cannot name a
+  path outside its tree. `check` never reads the catalog.
+
 ## Shared modules
 
 - **`snapshot-meta.mjs`** — `compareSnapshotMetadata`, shared by `diff` and

package/src/commands/change-intent.mjs

@@ -84,6 +84,30 @@ export const CONSTRAINT_ROW_NAMES = Object.freeze({
   noNewCycles: "no-new-cycles",
 });
 
+/**
+ * The one spelling of a declared edge row's identity: the NUL-separated
+ * `(from, to)` project pair. Two sites must read one edge declaration as one
+ * fact — this module's duplicate rejection (the dedup key
+ * `sectionListViolations` carries rows by) and `./change.mjs`'s
+ * reconciliation (which matches a declared row against the observed graph's
+ * `{source, target}`) — so the string is built here and imported, never
+ * spelled twice. Two private spellings were the live defect this helper
+ * closes (#613): they produced the same bytes until a shape moved, which is
+ * byte-for-byte the silent direction — the reconciliation would stop
+ * recognizing declarations it was handed while every command-local test
+ * stayed green.
+ *
+ * The observed edge's `type` is deliberately not part of the pair: whether
+ * the graph emits a dependency as `static` or `dynamic` is the model's
+ * spelling, not the author's promise (`./change.mjs`, `reconcileMaterialDelta`).
+ *
+ * @param {{from: string, to: string}} row A validated edge row.
+ * @returns {string}
+ */
+export function edgePairKey({ from, to }) {
+  return `${from}\u0000${to}`;
+}
+
 /** A value's type, for an error message that shows what was actually there. */
 function describe(value) {
   if (Array.isArray(value)) return `an array (${JSON.stringify(value)})`;
@@ -280,7 +304,7 @@ export function findChangeIntentViolations(raw) {
       },
       identity: (entry) =>
         isPlainObject(entry) && nonEmptyString(entry.from) && nonEmptyString(entry.to)
-          ? `${entry.from}\u0000${entry.to}`
+          ? edgePairKey(/** @type {{from: string, to: string}} */ (entry))
           : "",
     }),
   );

package/src/commands/change.mjs

@@ -90,6 +90,7 @@ import { buildDependencies, buildProjects, computePolicyFingerprint } from "./gr
 import {
   CONSTRAINT_ORDER,
   CONSTRAINT_ROW_NAMES,
+  edgePairKey,
   findChangeIntentReferenceViolations,
   readChangeIntent,
 } from "./change-intent.mjs";
@@ -113,6 +114,7 @@ import { referenceTime } from "../governance/clock.mjs";
 import {
   classifyEvolution,
   declarationDigest,
+  escapeIdentityField,
   eventDedupeKey,
   eventId,
   EVOLUTION_EVENT_SCHEMA_VERSION,
@@ -151,13 +153,26 @@ function cmpFacts(a, b) {
  * The identity string a delta-classified violation entry carries into the
  * event's `findings` — the same identity fields the delta classification
  * emits (`messageId`, `sourceProject`, `target`), serialized deterministically
- * so the ref is stable across runs over the same transition.
+ * so the ref is stable across runs over the same transition. Fields are
+ * escaped through `escapeIdentityField`, so a `:` inside a project name no
+ * longer reads as the field separator and two distinct entries never share
+ * one id (#628). The sentinel is the ONE literal written unescaped: it is
+ * this function's own spelling for "absent", so a source project literally
+ * named `-` escapes to `\-` instead of merging with it — while an absent
+ * source project still spells exactly what earlier versions spelled, byte
+ * for byte.
+ *
+ * Exported as the ONE spelling of this id — the same arrangement
+ * `edgeEvolutionIdentity` holds for edge identity — so a consumer composing
+ * the command layer cannot grow a second one that drifts.
  *
  * @param {{messageId: string, sourceProject: string|null, target: string}} entry
  * @returns {string}
  */
-function violationFindingId(entry) {
-  return `${entry.messageId}:${entry.sourceProject ?? "-"}:${entry.target}`;
+export function violationFindingId(entry) {
+  const sourceProject =
+    entry.sourceProject == null ? "-" : escapeIdentityField(entry.sourceProject);
+  return `${escapeIdentityField(entry.messageId)}:${sourceProject}:${escapeIdentityField(entry.target)}`;
 }
 
 /**
@@ -237,9 +252,13 @@ function observedFrom(structural, meta) {
 export function reconcileMaterialDelta(intent, delta) {
   const addedProjectNames = new Set(intent.projects.add);
   const removedProjectNames = new Set(intent.projects.remove);
-  const edgeKey = ({ from, to }) => `${from}\u0000${to}`;
-  const addEdgeKeys = new Set(intent.edges.add.map(edgeKey));
-  const removeEdgeKeys = new Set(intent.edges.remove.map(edgeKey));
+  // The declared row's identity is `./change-intent.mjs`'s `edgePairKey` — the
+  // ONE spelling, shared with the grammar's own duplicate detection. A local
+  // spelling here was the live defect (#613): it agreed byte-for-byte until a
+  // shape moved, and the reconciliation would then stop recognizing the
+  // declarations it was handed while every command-local test stayed green.
+  const addEdgeKeys = new Set(intent.edges.add.map(edgePairKey));
+  const removeEdgeKeys = new Set(intent.edges.remove.map(edgePairKey));
 
   /** @type {object[]} */
   const matched = [];
@@ -263,7 +282,7 @@ export function reconcileMaterialDelta(intent, delta) {
       to: edge.target,
       type: edge.type,
     });
-    if (addEdgeKeys.has(edgeKey({ from: edge.source, to: edge.target }))) matched.push(row);
+    if (addEdgeKeys.has(edgePairKey({ from: edge.source, to: edge.target }))) matched.push(row);
     else unexpected.push(row);
   }
   for (const edge of delta.removedEdges) {
@@ -273,7 +292,7 @@ export function reconcileMaterialDelta(intent, delta) {
       to: edge.target,
       type: edge.type,
     });
-    if (removeEdgeKeys.has(edgeKey({ from: edge.source, to: edge.target }))) matched.push(row);
+    if (removeEdgeKeys.has(edgePairKey({ from: edge.source, to: edge.target }))) matched.push(row);
     else unexpected.push(row);
   }
   // No declaration surface in this version: a metadata change to a project
@@ -292,10 +311,10 @@ export function reconcileMaterialDelta(intent, delta) {
   const observedAdded = new Set(delta.addedProjects.map((p) => p.name));
   const observedRemoved = new Set(delta.removedProjects.map((p) => p.name));
   const observedAddEdges = new Set(
-    delta.addedEdges.map((edge) => edgeKey({ from: edge.source, to: edge.target })),
+    delta.addedEdges.map((edge) => edgePairKey({ from: edge.source, to: edge.target })),
   );
   const observedRemoveEdges = new Set(
-    delta.removedEdges.map((edge) => edgeKey({ from: edge.source, to: edge.target })),
+    delta.removedEdges.map((edge) => edgePairKey({ from: edge.source, to: edge.target })),
   );
 
   // Declared but never observed — the unfulfilled half, kept apart from
@@ -313,12 +332,12 @@ export function reconcileMaterialDelta(intent, delta) {
     }
   }
   for (const edge of intent.edges.add) {
-    if (!observedAddEdges.has(edgeKey(edge))) {
+    if (!observedAddEdges.has(edgePairKey(edge))) {
       missingExpected.push(factRow({ kind: "edge-added", from: edge.from, to: edge.to }));
     }
   }
   for (const edge of intent.edges.remove) {
-    if (!observedRemoveEdges.has(edgeKey(edge))) {
+    if (!observedRemoveEdges.has(edgePairKey(edge))) {
       missingExpected.push(factRow({ kind: "edge-removed", from: edge.from, to: edge.to }));
     }
   }

package/src/commands/coverage-verdict.mjs

@@ -13,10 +13,17 @@
  * 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
+ * - `coverageVerdict` computes the one completeness over three axes — no
+ *   whole-file failure, no unjudged blind spot, at least one file analyzed —
+ *   and the status/exit pair that completeness implies. The first two axes
+ *   ride the envelope law (`../report/json.mjs`), and there only in ONE
+ *   direction: the envelope refuses `complete: true` over a non-empty
+ *   `notAnalyzed` list or an unjudged blind-spot row, and deliberately
+ *   allows `complete: false` with both lists empty, so a run that judged
+ *   nothing is able to say so. The third axis — `analyzed > 0` — is the one
+ *   this constructor adds on top (#599, #612, #619): the envelope has no
+ *   zero-analysis refusal by design, which is WHY this constructor exists.
+ *   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