@ecoma-io/archkeep 0.24.1 → 0.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecoma-io/archkeep",
-  "version": "0.24.1",
+  "version": "0.25.0",
   "description": "Architecture authority for human and agentic software development — deterministic, evidence-backed enforcement of declared architecture.",
   "keywords": [
     "architecture",

package/src/commands/change.mjs

@@ -103,12 +103,14 @@ import { providerMismatch, readEvidenceSnapshot } from "./delta-snapshot.mjs";
 import { coverageRefusal, coverageVerdict } from "./coverage-verdict.mjs";
 import { blindSpotRows } from "../analysis/source-util.mjs";
 import { cyclicProjects } from "../governance/fitness-rules.mjs";
-import { fitnessVerdict } from "../governance/verdict.mjs";
+import { eventSnapshotSide } from "./history.mjs";
+import { VERDICTS, fitnessVerdict, isVerdict } from "../governance/verdict.mjs";
+import { describe } from "../values.mjs";
 import { buildDecision } from "../report/evidence.mjs";
 import { jsonEnvelope, renderJson } from "../report/json.mjs";
 import { formatChangeReport } from "../report/change-text.mjs";
 import { evaluateRun } from "../rules/index.mjs";
-import { compareSnapshotMetadata } from "./snapshot-meta.mjs";
+import { compareSnapshotMetadata, dirtyBaselineNote, dirtyHeadNote } from "./snapshot-meta.mjs";
 import { resolveProvenance } from "./provenance.mjs";
 import { referenceTime } from "../governance/clock.mjs";
 import {
@@ -368,6 +370,9 @@ function reconciliationVerdict(lists, unprovenReasons) {
   return "matched";
 }
 
+/** The verdict axis `reconcileDisposition` maps — the four `reconciliationVerdict` answers. */
+const RECONCILE_VERDICTS = Object.freeze(["matched", "undeclared", "unfulfilled", "unproven"]);
+
 /**
  * The reconcile DISPOSITION mapping (wave 3, design §5) — the verdict axis
  * first, then the declared constraints' verdicts. Pure and exported so the
@@ -390,8 +395,33 @@ function reconciliationVerdict(lists, unprovenReasons) {
  *   this run — empty when none were declared or when the base identity was
  *   unproven (constraints are left unevaluated then).
  * @returns {"accepted"|"rejected"|"no-verdict"}
+ * @throws {Error} on an axis value outside the four, or a constraint row
+ *   whose verdict is outside the canonical vocabulary — a stranger would fold
+ *   to `accepted`, and a fabricated acceptance is the one answer this mapping
+ *   never hands out.
  */
 export function reconcileDisposition(verdict, constraints = []) {
+  // The mapping owns its input latch — it is exported and pure, the one place
+  // the precedence is stated, and a stranger axis value would match no named
+  // arm and land on `accepted`: a fabricated acceptance, the one answer this
+  // function must never hand out over input it did not understand.
+  if (!RECONCILE_VERDICTS.includes(verdict)) {
+    throw new Error(
+      `archkeep: refusing to map a reconcile verdict ${describe(verdict)} — ` +
+        `expected one of ${RECONCILE_VERDICTS.join(", ")}. This is a bug in the ` +
+        `reconciliation that produced it.`,
+    );
+  }
+  // Same latch one axis down: a constraint row verdict outside the four states
+  // matches neither `unknown` nor `fail`, and the mapping reads it as consent.
+  for (const row of constraints) {
+    if (!isVerdict(row.verdict)) {
+      throw new Error(
+        `archkeep: refusing to map a constraint row whose verdict is ${describe(row.verdict)} — ` +
+          `expected one of ${VERDICTS.join(", ")}. This is a bug in the judge that built the row.`,
+      );
+    }
+  }
   // used by its own test
   if (verdict === "unproven") return "no-verdict";
   if (verdict === "undeclared" || verdict === "unfulfilled") return "rejected";
@@ -648,6 +678,28 @@ export async function changeCommand(
     dependencies: buildDependencies(graph.dependencies),
   };
   const structural = computeDiff(baseGraphForDiff, headGraphForDiff);
+  // The event's identity sides are frozen HERE — at the same instant the diff
+  // above was computed from these same graph objects — so the identity always
+  // describes the graph the diff actually compared. Everything between this
+  // line and the event assembly (constraint re-judgement, custom rules,
+  // classification, debt) reads the graphs too; the engine's purity is what
+  // keeps them honest today, but the WS-I adversarial audit named the seam:
+  // identity and diff agreeing must not rest on purity conventions alone when
+  // one structural line closes it.
+  const baseCommit = baseline.provenance?.commit;
+  const headCommit = headProvenance?.commit;
+  const eventBase = eventSnapshotSide({
+    revision: baseCommit,
+    projects: baseGraphForDiff.projects,
+    dependencies: baseGraphForDiff.dependencies,
+    policyFingerprint: baseline.policyFingerprint,
+  });
+  const eventHead = eventSnapshotSide({
+    revision: headCommit,
+    projects: headGraphForDiff.projects,
+    dependencies: headGraphForDiff.dependencies,
+    policyFingerprint: headFingerprint,
+  });
   const reconciliation = reconcileMaterialDelta(intent, structural);
 
   // Constraints and the law axis are computed over both sides re-judged under
@@ -736,16 +788,10 @@ export async function changeCommand(
     );
   }
   if (meta.dirtyBaseline) {
-    notes.push(
-      "the baseline was captured from a dirty working tree — its evidence is not a reproducible " +
-        "claim about the commit the contract pins",
-    );
+    notes.push(dirtyBaselineNote(true));
   }
   if (meta.dirtyHead) {
-    notes.push(
-      "this run's working tree is dirty — the head side describes uncommitted state, not the " +
-        "commit HEAD names",
-    );
+    notes.push(dirtyHeadNote());
   }
   if (meta.provenanceOneSided) {
     notes.push(
@@ -855,23 +901,24 @@ export async function changeCommand(
     }
   }
 
-  const baseCommit = baseline.provenance?.commit;
-  const headCommit = headProvenance?.commit;
   /** @type {object} */
   const event = {
     schemaVersion: EVOLUTION_EVENT_SCHEMA_VERSION,
     kind: "reconcile",
     source: "change",
-    base: {
-      ...(typeof baseCommit === "string" ? { revision: baseCommit } : {}),
-      // The caller's own evidence ref — the baseline file this run consumed,
-      // spelled as the run received it (the same convention `declaration.file`
-      // uses for the intent path).
-      evidence: baselinePath,
-    },
-    head: {
-      ...(typeof headCommit === "string" ? { revision: headCommit } : {}),
-    },
+    // Both sides were frozen through the ONE identity spelling
+    // (`eventSnapshotSide`, ./history.mjs) at the diff site above: a revision
+    // when one is known, plus the snapshot identity of the graph the diff
+    // compared — never the baseline's storage path, which is machine-local
+    // and must not make the identity a per-machine property.
+    base: eventBase,
+    head: eventHead,
+    // The caller's own evidence ref — the baseline file this run consumed,
+    // spelled as the run received it (the same convention `declaration.file`
+    // uses for the intent path). Disclosed OUTSIDE the identity: the tuple
+    // above names the state itself, so a relocated baseline is still the
+    // same event.
+    evidence: baselinePath,
     declaration: { file: intentPath, digest: declarationDigest(intent) },
     observed,
     affected: evolution.affected,

package/src/commands/delta-snapshot.mjs

@@ -274,7 +274,9 @@ export function buildEvidenceSnapshot({
  * order is the only order the format keeps, and `buildEvidenceSnapshot` sorts
  * every array whose source does not guarantee it. Two captures over one
  * unchanged tree produce byte-identical files, which is what makes a plain
- * `diff` of two baselines meaningful.
+ * `diff` of two baselines meaningful. That determinism is also why this
+ * family carries no identity field, by decision: the bytes are the identity
+ * (`../../../../docs/adr/0008-snapshot-identity-per-family.md`).
  *
  * @param {object} snapshot From `buildEvidenceSnapshot`.
  * @returns {string} The JSON text, newline-terminated.
@@ -330,7 +332,11 @@ export function readEvidenceSnapshot(path, io = {}) {
  * What is deliberately NOT a refusal: dirty base provenance. A baseline from
  * an uncommitted tree is weaker evidence, not unreadable evidence — the parsed
  * snapshot exposes `provenance.dirty` so the renderer can say so loudly, and
- * classification itself proceeds.
+ * classification itself proceeds. A dirty BIT that is not a boolean is a
+ * different thing — malformed, not weaker: the gates read `dirty === true`
+ * while the renderers interpolate truthiness, so any other type would read
+ * clean to some consumers and dirty to others. The provenance block below
+ * refuses it by name.
  *
  * @param {string} text The file contents.
  * @param {string} path The path the text came from, for error messages.
@@ -392,8 +398,23 @@ export function parseEvidenceSnapshot(text, path) {
 
   if (parsed.provenance !== null && !isPlainObject(parsed.provenance)) {
     problems.push("provenance: must be an object ({commit, remote, dirty}) or null");
-  } else if (isPlainObject(parsed.provenance) && typeof parsed.provenance.commit !== "string") {
-    problems.push("provenance.commit: must be a string when provenance is present");
+  } else if (isPlainObject(parsed.provenance)) {
+    if (typeof parsed.provenance.commit !== "string") {
+      problems.push("provenance.commit: must be a string when provenance is present");
+    }
+    if (parsed.provenance.remote !== null && typeof parsed.provenance.remote !== "string") {
+      problems.push("provenance.remote: must be a string or null when provenance is present");
+    }
+    if (typeof parsed.provenance.dirty !== "boolean") {
+      // Malformed, not weaker: the gates read `dirty === true` while the
+      // renderers interpolate truthiness, so a value of any other type reads
+      // clean to some consumers and dirty to others — the one disagreement
+      // this record must never carry.
+      problems.push(
+        "provenance.dirty: must be a boolean when provenance is present — the gates decide " +
+          "between committed and uncommitted evidence on this bit",
+      );
+    }
   }
 
   if (typeof parsed.policyFingerprint !== "string" || parsed.policyFingerprint === "") {

package/src/commands/delta.mjs

@@ -106,9 +106,10 @@ import {
 } from "./delta-snapshot.mjs";
 import { computeDiff } from "./diff.mjs";
 import { buildDependencies, buildProjects, computePolicyFingerprint } from "./graph.mjs";
+import { eventSnapshotSide } from "./history.mjs";
 import { coverageRefusal, coverageVerdict } from "./coverage-verdict.mjs";
 import { resolveProvenance } from "./provenance.mjs";
-import { compareSnapshotMetadata } from "./snapshot-meta.mjs";
+import { compareSnapshotMetadata, dirtyBaselineNote, dirtyHeadNote } from "./snapshot-meta.mjs";
 
 const require = createRequire(import.meta.url);
 /** @type {{name: string, version: string}} */
@@ -569,16 +570,10 @@ export async function deltaCommand(
     );
   }
   if (meta.dirtyBaseline) {
-    notes.push(
-      "the baseline was captured from a dirty working tree — its evidence is not a reproducible " +
-        "claim about the commit it names",
-    );
+    notes.push(dirtyBaselineNote(false));
   }
   if (meta.dirtyHead) {
-    notes.push(
-      "this run's working tree is dirty — the head side describes uncommitted state, not the " +
-        "commit HEAD names",
-    );
+    notes.push(dirtyHeadNote());
   }
 
   // The event's structural signal: what moved between the two graphs the
@@ -588,10 +583,11 @@ export async function deltaCommand(
   // a second spelling of "changed". The head side is rebuilt by the same
   // `buildProjects`/`buildDependencies` the snapshot stores
   // (`./delta-snapshot.mjs`), which is what makes the two sides comparable.
-  const structuralDiff = computeDiff(baseline.graph, {
+  const headGraph = {
     projects: buildProjects(graph.nodes),
     dependencies: buildDependencies(graph.dependencies),
-  });
+  };
+  const structuralDiff = computeDiff(baseline.graph, headGraph);
   const structural = {
     projects: {
       added: structuralDiff.addedProjects.map((project) => project.name),
@@ -618,6 +614,25 @@ export async function deltaCommand(
   // same", and a policy change is disclosed, not folded into drift.
   const baseCommit = baseline.provenance?.commit;
   const headCommit = headProvenance?.commit;
+  // The event's identity sides are frozen HERE — at the same instant the diff
+  // above was computed from these same graph objects — so the identity always
+  // describes the graph the diff actually compared. Everything below this line
+  // (custom rules, classification, intent, debt) reads the graphs too; the
+  // engine's purity is what keeps them honest today, but the WS-I adversarial
+  // audit named the seam: identity and diff agreeing must not rest on purity
+  // conventions alone when one structural line closes it.
+  const eventBase = eventSnapshotSide({
+    revision: baseCommit,
+    projects: baseline.graph.projects,
+    dependencies: baseline.graph.dependencies,
+    policyFingerprint: baseline.policyFingerprint,
+  });
+  const eventHead = eventSnapshotSide({
+    revision: headCommit,
+    projects: headGraph.projects,
+    dependencies: headGraph.dependencies,
+    policyFingerprint: headFingerprint,
+  });
   const provenanceAdvanced =
     typeof baseCommit === "string" &&
     typeof headCommit === "string" &&
@@ -878,13 +893,18 @@ export async function deltaCommand(
       schemaVersion: EVOLUTION_EVENT_SCHEMA_VERSION,
       kind: "transition",
       source: "delta",
-      base: {
-        ...(typeof baseCommit === "string" ? { revision: baseCommit } : {}),
-        // The evidence ref is the baseline file this run actually compared
-        // against — a pointer into the evidence, never a graph.
-        evidence: baselinePath,
-      },
-      head: typeof headCommit === "string" ? { revision: headCommit } : {},
+      // Both sides were frozen through the ONE identity spelling
+      // (`eventSnapshotSide`, ./history.mjs) at the diff site above: a
+      // revision when one is known, plus the snapshot identity of the graph
+      // the diff compared — never the baseline's storage path, which is
+      // machine-local and must not make the identity a per-machine property.
+      base: eventBase,
+      head: eventHead,
+      // The evidence ref is the baseline file this run actually compared
+      // against — a pointer into the evidence, never a graph, and disclosed
+      // OUTSIDE the identity: the tuple above names the state itself, so a
+      // relocated baseline is still the same event.
+      evidence: baselinePath,
       recordedAt: recordOrigin({
         by: "cli",
         tool: `archkeep:v${TOOL_VERSION}`,

package/src/commands/diff.mjs

@@ -46,7 +46,7 @@ import { coverageRefusal, coverageVerdict } from "./coverage-verdict.mjs";
 import { SCHEMA_VERSION } from "../report/json.mjs";
 import { jsonEnvelope, renderJson } from "../report/json.mjs";
 import { formatDiffReport } from "../report/diff-text.mjs";
-import { compareSnapshotMetadata } from "./snapshot-meta.mjs";
+import { compareSnapshotMetadata, dirtyBaselineNote, dirtyHeadNote } from "./snapshot-meta.mjs";
 import { resolveProvenance } from "./provenance.mjs";
 
 /**
@@ -475,16 +475,10 @@ export function diffCommand(
   }
 
   if (meta.dirtyBaseline) {
-    coverage.notes.push(
-      "the baseline was captured from a dirty working tree — its evidence is not a reproducible " +
-        "claim about the commit it names",
-    );
+    coverage.notes.push(dirtyBaselineNote(false));
   }
   if (meta.dirtyHead) {
-    coverage.notes.push(
-      "this run's working tree is dirty — the head side describes uncommitted state, not the " +
-        "commit HEAD names",
-    );
+    coverage.notes.push(dirtyHeadNote());
   }
 
   if (meta.policyChanged === true) {

package/src/commands/history.mjs

@@ -112,6 +112,12 @@ import { compareSnapshotMetadata } from "./snapshot-meta.mjs";
  * Provider and provenance changes surface through the transition
  * classification instead.
  *
+ * This function is the graph-snapshot family's ONE identity — evolution event
+ * sides consume its output through `eventSnapshotSide` below, never a second
+ * derivation (`../../../../docs/adr/0008-snapshot-identity-per-family.md`
+ * records the one-identity-per-family decision, including why the evidence
+ * snapshot family deliberately carries no id at all).
+ *
  * @param {{projects: object[], dependencies: object[], policy?: {fingerprint: string}|null}} snapshot
  * @returns {string} A hex-encoded SHA-256.
  */
@@ -136,6 +142,34 @@ export function snapshotIdentity({ projects, dependencies, policy }) {
   return createHash("sha256").update(canonical).digest("hex");
 }
 
+/**
+ * An evolution event's identity side: the reference to ONE state — a revision
+ * when one is known, plus the snapshot identity of the graph that side was
+ * judged over. `delta` and `change` build every side through this one
+ * function so the identity spelling cannot drift between them, and a storage
+ * path can never re-enter the tuple a committed event store dedupes on
+ * (`docs/concepts/evolution.md`'s "Nor does a storage path"). `history` and
+ * `evolution` spell the same `{revision, snapshot}` shape directly, from a
+ * snapshot whose identity is already computed.
+ *
+ * @param {{revision?: string|null, projects: object[], dependencies: object[],
+ *   policyFingerprint?: string|null}} side
+ * @returns {{revision?: string, snapshot: string}} The identity side.
+ */
+export function eventSnapshotSide({ revision, projects, dependencies, policyFingerprint }) {
+  return {
+    ...(typeof revision === "string" ? { revision } : {}),
+    snapshot: snapshotIdentity({
+      projects,
+      dependencies,
+      policy:
+        policyFingerprint === undefined || policyFingerprint === null
+          ? null
+          : { fingerprint: policyFingerprint },
+    }),
+  };
+}
+
 /**
  * Reads and validates every snapshot in the history directory.
  *

package/src/commands/snapshot-meta.mjs

@@ -23,6 +23,39 @@
  * `null` before treating either as a boolean.
  */
 
+/**
+ * The one wording for the dirty-baseline disclosure, shared by every command
+ * that compares a snapshot pair (`diff`, `delta`, `change`). Three copies of
+ * one disclosure spell drift three ways, so the wording lives beside the fact
+ * it translates. A consumer that pins the baseline by its own contract names
+ * that pin (`pinned`) — `change`'s contract carries `base.commit`; a diff or
+ * delta pair has no such pin, so its note names the commit the snapshot
+ * itself claims.
+ *
+ * @param {boolean} pinned Whether the consumer's contract pins the base commit.
+ * @returns {string} The disclosure note.
+ */
+export function dirtyBaselineNote(pinned) {
+  return pinned
+    ? "the baseline was captured from a dirty working tree — its evidence is not a reproducible " +
+        "claim about the commit the contract pins"
+    : "the baseline was captured from a dirty working tree — its evidence is not a reproducible " +
+        "claim about the commit it names";
+}
+
+/**
+ * The one wording for the dirty-head disclosure — byte-identical in every
+ * consumer, so it is stated exactly once.
+ *
+ * @returns {string} The disclosure note.
+ */
+export function dirtyHeadNote() {
+  return (
+    "this run's working tree is dirty — the head side describes uncommitted state, not the " +
+    "commit HEAD names"
+  );
+}
+
 /**
  * Compares the provider, provenance, and policy fingerprint of two graph
  * envelopes.

package/src/custom-rules/values.mjs

@@ -25,10 +25,7 @@
  * to reach it.
  */
 
-export { isPlainObject } from "../values.mjs";
-
-/** @type {(value: unknown) => boolean} */
-export const isNonEmptyString = (value) => typeof value === "string" && value.trim() !== "";
+export { isPlainObject, isNonEmptyString } from "../values.mjs";
 
 /**
  * A value's type, for a refusal that shows what was actually there.

package/src/governance/fitness-registry.mjs

@@ -52,7 +52,7 @@ import { languageOf } from "../analysis/registry.mjs";
 import { canonicalizeJson } from "../canonical.mjs";
 import { describe, isPlainObject } from "../values.mjs";
 import { GOVERNANCE_ROW_KEYS, rowSchemaViolations } from "./row-schema.mjs";
-import { fitnessVerdict, isVerdict } from "./verdict.mjs";
+import { VERDICTS, fitnessVerdict, isVerdict } from "./verdict.mjs";
 import {
   coverageMinimum,
   cycleFree,
@@ -481,6 +481,19 @@ export function evaluateFitness(rows, snapshot) {
  * @returns {{verdict: "pass"|"fail"|"unknown"|"not_applicable", decisions: object[]}}
  */
 export function fitnessVerdictFor(decisions) {
+  // The fold is an overall-verdict constructor, so it owns the same vocabulary
+  // latch `buildDecision` does rather than trusting every caller to have
+  // latched its rows first: a stranger verdict matches none of the checks
+  // below and falls through to `pass` — the loudest clean state a governance
+  // run can emit, fabricated from a row nobody judged.
+  for (const decision of decisions) {
+    if (!isVerdict(decision.verdict)) {
+      throw new Error(
+        `archkeep: refusing to fold a fitness row whose verdict is ${describe(decision.verdict)} — ` +
+          `expected one of ${VERDICTS.join(", ")}. This is a bug in the rule that judged the row.`,
+      );
+    }
+  }
   if (decisions.some((d) => d.verdict === "fail")) return { verdict: "fail", decisions };
   if (decisions.some((d) => d.verdict === "unknown")) return { verdict: "unknown", decisions };
   if (decisions.length === 0 || decisions.every((d) => d.verdict === "not_applicable")) {

package/src/governance/verdict.mjs

@@ -43,6 +43,8 @@
  * path — a path, never a second implementation.
  */
 
+import { describe, isNonEmptyString } from "../values.mjs";
+
 /** The four canonical verdict values. */
 export const VERDICTS = Object.freeze(["pass", "fail", "unknown", "not_applicable"]);
 
@@ -113,7 +115,7 @@ export function fitnessVerdict({ verdict, name, evidence, message, rows, notAppl
         `expected one of ${VERDICTS.join(", ")}.`,
     );
   }
-  if (verdict === "not_applicable" && notApplicableReason === undefined) {
+  if (verdict === "not_applicable" && !isNonEmptyString(notApplicableReason)) {
     throw new Error(
       `archkeep: fitness function "${name}" returned "not_applicable" without ` +
         `notApplicableReason — invariant I4: the reader must be told why the ` +
@@ -206,6 +208,21 @@ export function buildDecision(run) {
     throw new Error("archkeep: buildDecision needs either a status or an explicit verdict");
   }
   const verdict = run.verdict ?? verdictForStatus(run.status);
+  // The vocabulary latch. `verdictForStatus` cannot produce a stranger, so
+  // this refuses exactly the explicitly-passed verdicts — and it must run
+  // BEFORE the status-conflict check below, so a malformed verdict reports
+  // the vocabulary it violated rather than a conflict it never had. Without
+  // this latch, "perhaps", "PASS", `42` and `{}` fell through the
+  // pass/fail/unknown arms into the not_applicable one and SHIPPED whenever
+  // `notApplicableReason` happened to be truthy — a byte-legal decision
+  // about a workspace nobody judged.
+  if (!isVerdict(verdict)) {
+    throw new Error(
+      `archkeep: refusing to build a decision with verdict ${describe(run.verdict)} — ` +
+        `expected one of ${VERDICTS.join(", ")}. This is a bug in the command that ` +
+        `built the decision.`,
+    );
+  }
   if (
     run.verdict !== undefined &&
     run.status !== undefined &&
@@ -260,17 +277,32 @@ export function buildDecision(run) {
   }
 
   if (verdict === "unknown") {
+    // An absent reason (undefined/null) still defaults to the generic one —
+    // absence is not emptiness. A SUPPLIED reason must actually say
+    // something: "" and "   " are byte-present but semantically absent, and
+    // a non-string reason would ship a `typeof` artifact where the reader
+    // was promised a sentence (I3).
     const reason =
       run.reason ??
       (run.coverageComplete === true ? "no verdict was reached" : "coverage was incomplete");
+    if (!isNonEmptyString(reason)) {
+      throw new Error(
+        `archkeep: refusing to emit an "unknown" decision with a ${describe(run.reason)} reason — ` +
+          `I3 requires a non-empty reason naming why no verdict was reached. ` +
+          `This is a bug in the command that built the decision.`,
+      );
+    }
     return withSampleTime({ verdict, reason }, run.sampleTime);
   }
 
-  // verdict === "not_applicable" (I4).
-  if (!run.notApplicableReason) {
+  // verdict === "not_applicable" (I4). The reason must be a string a reader
+  // could act on — the falsy check this replaces refused "" but SHIPPED
+  // "   " and non-strings, the same byte-present-semantically-absent hole.
+  if (!isNonEmptyString(run.notApplicableReason)) {
     throw new Error(
       `archkeep: refusing to emit a "not_applicable" decision without notApplicableReason — ` +
-        `"did not apply" and "did not run" must never be indistinguishable. ` +
+        `"did not apply" and "did not run" must never be indistinguishable, and a reason of ` +
+        `${describe(run.notApplicableReason)} tells the reader nothing. ` +
         `This is a bug in the command that built the decision.`,
     );
   }

package/src/intent/intent-manifest.json

@@ -25,7 +25,7 @@
         {
           "type": "source-evidence",
           "path": "src/commands/context.mjs",
-          "assertion": "Only commands/context.mjs imports providers — the designated orchestration layer",
+          "assertion": "commands/context.mjs imports providers — the designated orchestration path",
           "sha256": "b505e3a7476c64af4b2daeb106e2f9cb05be82e314604229d508dda04b629a98"
         }
       ],
@@ -40,7 +40,7 @@
           "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",
-          "sha256": "a371d36b89b10c5a4bda4d9e9a2e3bde114256c1377eb95699c9f0f195aabc4a"
+          "sha256": "8f587d3bd3f06519b90f760e7eafc091ca4e4cf26b67929ab180abe35c36c8f0"
         },
         {
           "type": "source-evidence",
@@ -66,13 +66,13 @@
           "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 (three workspaces differing only in project tag fields compared byte-for-byte)",
-          "sha256": "adb25388f17c97577e97e6b65bd3dacc5811710fe3bb60a409a51ff4abcd945e"
+          "sha256": "85b98de1f9268c94020b8b728a3ebbf1e8b50f8c70731c5460c788ea00be3198"
         },
         {
           "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": "adb25388f17c97577e97e6b65bd3dacc5811710fe3bb60a409a51ff4abcd945e"
+          "sha256": "85b98de1f9268c94020b8b728a3ebbf1e8b50f8c70731c5460c788ea00be3198"
         },
         {
           "type": "source-evidence",
@@ -103,9 +103,15 @@
         {
           "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",
           "sha256": "436902ab3ca994c233318437a896630f969a2c8a22b0f93e598d309faed39d49"
         },
+        {
+          "type": "source-evidence",
+          "path": "src/report/json.mjs",
+          "assertion": "SCHEMA_VERSION = 2 — the envelope's schemaVersion constant",
+          "sha256": "090418f6f60dec51638976dff658c55f8a932012bfc7c8bc59952b0f03543340"
+        },
         {
           "type": "source-evidence",
           "path": "src/commands/graph.mjs",
@@ -130,7 +136,7 @@
           "type": "source-evidence",
           "path": "src/commands/diff.mjs",
           "assertion": "parseBaseline validates schemaVersion; refuses unknown versions",
-          "sha256": "85e6400006a7e93c66e64547162c854320fa69d833a11cec42773703f522a163"
+          "sha256": "e28620e288b58e35916e8cd41de446b999bdc2c4e5fcb5f3a617ab0ee449b0fd"
         }
       ],
       "status": "proven"
@@ -150,7 +156,7 @@
           "type": "source-evidence",
           "path": "src/commands/diff.mjs",
           "assertion": "computeDiff returns structural diff; policyMismatch detected via fingerprint; computeRuleImpact for depConstraints-only context",
-          "sha256": "85e6400006a7e93c66e64547162c854320fa69d833a11cec42773703f522a163"
+          "sha256": "e28620e288b58e35916e8cd41de446b999bdc2c4e5fcb5f3a617ab0ee449b0fd"
         }
       ],
       "status": "proven"
@@ -230,7 +236,7 @@
           "type": "behavioral-test",
           "path": "src/intent/intent.test.mjs",
           "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": "adb25388f17c97577e97e6b65bd3dacc5811710fe3bb60a409a51ff4abcd945e"
+          "sha256": "85b98de1f9268c94020b8b728a3ebbf1e8b50f8c70731c5460c788ea00be3198"
         },
         {
           "type": "behavioral-test",
@@ -260,7 +266,7 @@
           "type": "source-evidence",
           "path": "src/commands/diff.mjs",
           "assertion": "coverage.notes warns when ruleImpact is computed (depConstraints only, 3 of 15)",
-          "sha256": "85e6400006a7e93c66e64547162c854320fa69d833a11cec42773703f522a163"
+          "sha256": "e28620e288b58e35916e8cd41de446b999bdc2c4e5fcb5f3a617ab0ee449b0fd"
         },
         {
           "type": "documentation",

package/src/report/json.mjs

@@ -39,6 +39,7 @@
  */
 import { EXIT_FOR_STATUS } from "../verdict.mjs";
 import { verdictForStatus } from "../governance/verdict.mjs";
+import { describe, isNonEmptyString } from "../values.mjs";
 import { createRequire } from "node:module";
 
 const require = createRequire(import.meta.url);
@@ -163,10 +164,11 @@ export function jsonEnvelope({ command, context, status, exitCode, coverage, res
     // `result`. A hand-built "fail" with no findings is still a loud lie
     // (status "findings", exitCode 1, verdict "fail"), never the silent
     // direction.
-    if (decision.verdict === "unknown" && decision.reason === undefined) {
+    if (decision.verdict === "unknown" && !isNonEmptyString(decision.reason)) {
       throw new Error(
         `archkeep: refusing to build a JSON envelope where an "unknown" decision has no reason — ` +
-          `I3: an unknown verdict must say why no verdict was reached, or it reads as a shrug. ` +
+          `I3: an unknown verdict must say why no verdict was reached, or it reads as a shrug ` +
+          `(a reason of ${describe(decision.reason)} is not a reason). ` +
           `This is a bug in the command that built the envelope.`,
       );
     }

package/src/values.mjs

@@ -36,6 +36,17 @@ export const isPlainObject = (value) =>
 export const isStringArray = (value) =>
   Array.isArray(value) && value.every((item) => typeof item === "string");
 
+/**
+ * Whether a value is a string a reader could actually act on — non-empty
+ * after trimming. The verdict contract's reason fields (I3/I4) refuse
+ * everything else: `""` and `"   "` are byte-present but semantically
+ * absent, and a non-string reason would ship a `typeof` artifact where the
+ * reader was promised a sentence.
+ *
+ * @type {(value: unknown) => value is string}
+ */
+export const isNonEmptyString = (value) => typeof value === "string" && value.trim() !== "";
+
 /**
  * A value's type, for an error message that shows what was actually there.
  *