@ecoma-io/archkeep 0.16.1 → 0.18.0

package/src/governance/debt-ledger.mjs

@@ -77,6 +77,10 @@
  * never as an empty ledger.
  */
 
+import { createHash } from "node:crypto";
+
+import { canonicalizeJson } from "../canonical.mjs";
+
 import { referenceTime as clockReferenceTime } from "./clock.mjs";
 import { EXPIRED_WAIVER_EVIDENCE, suppressionFate } from "./waiver.mjs";
 
@@ -118,9 +122,122 @@ function owningProjectForPath(path, byName) {
       bestRoot = root;
     }
   }
+
   return best;
 }
 
+/**
+ * The stable identity of a debt entry: `sha256` of its canonical `{kind,
+ * source}` — the same mechanism `eventId` uses for evolution events (one
+ * pattern, one canonicalizer), never the wall clock, a sequence or a random.
+ * The same fact must always hash to the same id; any caller that emits these
+ * ids into an evolution event's `debt.introduced`/`debt.resolved` MUST use
+ * this exact identity, or the event-linked lifecycle will never match the
+ * ledger.
+ *
+ * `expired-waiver` maps back to `waiver`: it is the SAME accepted violation,
+ * and its id must not change when its `expiresAt` passes — a fact's identity
+ * cannot depend on a transient state.
+ *
+ * @param {string} kind The entry's `kind`.
+ * @param {string} source The entry's `source` (its keying field).
+ * @returns {string} The stable hex id.
+ */
+export function entryId(kind, source) {
+  const semanticKind = kind === "expired-waiver" ? "waiver" : kind;
+  return createHash("sha256")
+    .update(canonicalizeJson({ kind: semanticKind, source }))
+    .digest("hex");
+}
+
+/**
+ * The stable identity of a structured debt fact: `entryId` over the fact's
+ * canonical JSON. Where `entryId(kind, source)` keys on a single string (a
+ * waiver path, an unresolved boundary), `debtFactId` keys on the full semantic
+ * fact so two distinct facts can never collide on one id.
+ *
+ * This is the ONE identity the event-linked lifecycle links against: a
+ * producer (`change`, `delta`) that emits `debt.introduced`/`debt.resolved`
+ * MUST call this exact function with the same structured fact the ledger
+ * derives its entry from, or the ids will never match (the broken lifecycle
+ * F-DEB-1 exists to close). The fact excludes prose — a reworded message must
+ * not re-key a fact (F-DEB-5 drift, F-DEB-8 aspirational gap).
+ *
+ * @param {string} kind The entry's `kind`.
+ * @param {object} fact The structured semantic fact, e.g. a drift finding
+ *   `{source, target, rule}` or an aspirational gap `{from, to}`.
+ * @returns {string} The stable hex id.
+ */
+export function debtFactId(kind, fact) {
+  return entryId(kind, canonicalizeJson(fact));
+}
+
+/**
+ * The structured drift fact a judge finding keys on: `{source, target, rule}`
+ * over exactly the fields that were judged. Presence findings (projectMissing,
+ * projectPresent, projectTagMissing) carry no `target`; the fact spans only
+ * the present fields — shared by the ledger's drift entry and every producer
+ * that emits `debt.introduced`/`debt.resolved`, so they can never disagree
+ * about which id a finding owns.
+ *
+ * @param {{source?: string, target?: string, rule?: string}} finding A judge
+ *   finding (`judgeIntent`'s `{source, target, rule, …}`).
+ * @returns {{source: string, target?: string, rule?: string}} The drift fact.
+ */
+export function driftFactOf(finding) {
+  return {
+    source: finding.source,
+    ...(finding.target === undefined ? {} : { target: finding.target }),
+    ...(finding.rule === undefined ? {} : { rule: finding.rule }),
+  };
+}
+
+/**
+ * The debt a base→head transition opened and closed, expressed as ledger ids
+ * (design §8: `debt.introduced` names debt created, `debt.resolved` names debt
+ * resolved). Two `judgeIntent` verdicts — one over the base graph, one over
+ * the head graph, both judged under ONE current intent — diff on the STABLE
+ * ids: a finding present at base but gone at head is resolved; present at head
+ * but not base is introduced; a fact that never moved is neither. Identity
+ * never depends on prose (F-DEB-5 drift, F-DEB-8 aspirational gap), so the
+ * ids emitted here are byte-identical to what `computeDebtLedger` derives for
+ * the same fact — the ONE home that makes the event-linked lifecycle fire.
+ *
+ * Aspirational gaps count as debt too: an optional row not built at base but
+ * built at head is resolved debt; one that stops being built is introduced.
+ *
+ * @param {object} baseVerdict A `judgeIntent` result over the base graph.
+ * @param {object} headVerdict A `judgeIntent` result over the head graph.
+ * @returns {{introduced: string[], resolved: string[]}} Stable debt ids.
+ */
+export function debtChangeDiff(baseVerdict, headVerdict) {
+  const driftOf = (v) => (v.findings ?? []).map((f) => debtFactId("drift", driftFactOf(f)));
+  const gapOf = (v) =>
+    (v.gaps ?? []).map((g) => debtFactId("aspirational-gap", { from: g.from, to: g.to }));
+  const baseIds = new Set([...driftOf(baseVerdict), ...gapOf(baseVerdict)]);
+  const headIds = new Set([...driftOf(headVerdict), ...gapOf(headVerdict)]);
+  const introduced = [...headIds].filter((id) => !baseIds.has(id)).sort();
+  const resolved = [...baseIds].filter((id) => !headIds.has(id)).sort();
+  return { introduced, resolved };
+}
+/**
+ * Reduces an `opts.events` value to a loaded event array, or `null` when no
+ * event store is linked. Accepts an already-loaded array or a
+ * `{ getEvents(dir) }`-shaped reader (design §4). `null` means "not linked":
+ * no `introducedBy`/`resolvedBy` is ever guessed.
+ *
+ * @param {{events?: object[]|{getEvents?: (dir?: string) => object[]},
+ *   eventsDir?: string}} opts
+ * @returns {object[]|null}
+ */
+function loadEvents(opts) {
+  if (!opts.events) return null;
+  if (Array.isArray(opts.events)) return opts.events;
+  if (typeof opts.events.getEvents === "function")
+    return opts.events.getEvents(opts.eventsDir) ?? [];
+  return null;
+}
+
 /**
  * The complete ledger over one ordered snapshot set. Deterministic: the same
  * files, the same current facts and the same `referenceTime` produce the same
@@ -131,17 +248,27 @@ function owningProjectForPath(path, byName) {
  * test runs could share. (The ledger's own determinism is about a fixed
  * clock.)
  *
- * @param {{suppressions?: object[], intentNotes?: string[], findings?: object[],
+ * @param {{suppressions?: object[], intentNotes?: string[], gaps?: {from: string,
+ *   to: string, note?: string}[], findings?: object[],
  *   unresolved?: object[]}} current The current run's candid facts: the loaded
- *   boundary config's `suppressions`, `judgeIntent`'s `notes` (aspirational
- *   gaps), `findings` (drift), and `unresolved`.
+ *   boundary config's `suppressions`, `judgeIntent`'s aspirational-gap facts
+ *   (`gaps`, structured `{from, to}` — the identity source) with `intentNotes`
+ *   as their prose display (deprecated dance when `gaps` is absent),
+ *   `findings` (drift), and `unresolved`.
  * @param {{files: {name: string, envelope: object, id: string}[]}} snapshots
  *   From `readSnapshots(dir)`, in history order.
- * @param {{referenceTime?: number|string}} [opts]
+ * @param {{referenceTime?: number|string, events?: object[]|{getEvents?: (dir?: string) => object[]},
+ *   eventsDir?: string}} [opts] `events` links an event store (design §4): an
+ *   already-loaded array of evolution events, or a `{ getEvents(dir) }`-shaped
+ *   reader. Absent ⇒ no `introducedBy`/`resolvedBy` is ever set and a
+ *   `lifecycle.note` states the refs are unavailable — refs are never guessed.
  * @returns {{entries: {source: string, kind: string, severity: string,
- *   age: number, count: number, remediationHint: string}[],
+ *   age: number, count: number, remediationHint: string, id: string,
+ *   status: "active", introducedBy?: string}[],
+ *   resolved: {id: string, status: "resolved", resolvedBy: string}[],
  *   total: number, byKind: object, bySeverity: object, agings: boolean,
- *   sampleTime: string}}
+ *   sampleTime: string,
+ *   lifecycle: {linked: boolean, note: string|null}}}
  */
 export function computeDebtLedger(current, snapshots, opts = {}) {
   const referenceTime = opts.referenceTime ?? clockReferenceTime();
@@ -167,7 +294,7 @@ export function computeDebtLedger(current, snapshots, opts = {}) {
 
   const byName = headProjects(files);
 
-  /** @type {{source: string, kind: string, severity: string, age: number, count: number, remediationHint: string}[]} */
+  /** @type {{source: string, kind: string, severity: string, age: number, count: number, remediationHint: string, id: string, status: "active", introducedBy?: string}[]} */
   const entries = [];
 
   for (const suppression of current.suppressions ?? []) {
@@ -179,28 +306,58 @@ export function computeDebtLedger(current, snapshots, opts = {}) {
     // suppression (no `expiresAt`) is `suppress`: still low and permanent.
     const fate = suppressionFate(suppression, sampleTime);
     const expired = fate === "reassert";
+    const kind = expired ? "expired-waiver" : "waiver";
     entries.push({
       source: suppression.path,
-      kind: expired ? "expired-waiver" : "waiver",
+      kind,
       severity: expired ? "medium" : "low",
       age: project ? ageOf(project) : 0,
       count: 1,
+      id: entryId(kind, suppression.path),
+      status: "active",
       remediationHint: expired
         ? `the waiver at '${suppression.path}' expired — the boundary it accepted is live again (${EXPIRED_WAIVER_EVIDENCE}); renew it or retire it`
         : `the accepted violation at '${suppression.path}' is still suppressed — ` +
           (project ? `owning project '${project}'` : "retire it or confirm the reason"),
     });
   }
-  for (const note of current.intentNotes ?? []) {
-    entries.push({
-      source: note,
-      kind: "aspirational-gap",
-      severity: "low",
-      age: 0,
-      count: 1,
-      remediationHint:
-        "an optional allowed row is not yet built — either build it or remove the row",
-    });
+  // Aspirational-gap entries: an `optional: true` `allowed` row not yet built.
+  // Identity comes from the STRUCTURED `{from, to}` (F-DEB-8) — never from the
+  // prose note, which re-keys every gap when the wording changes. `gaps` is
+  // the structured source when a caller threads it (the producer emits the
+  // same `{from, to}` ids the ledger derives here); the prose `intentNotes`
+  // fallback keys on the note itself only for callers that pass notes with no
+  // structured gaps — a deprecated shape, retained so the identity home stays
+  // single (the `debtFactId` here is the one the producers must match).
+  const gaps = current.gaps ?? [];
+  if (gaps.length > 0) {
+    for (const gap of gaps) {
+      entries.push({
+        source: gap.note ?? `${gap.from} → ${gap.to}`,
+        kind: "aspirational-gap",
+        severity: "low",
+        age: 0,
+        count: 1,
+        id: debtFactId("aspirational-gap", { from: gap.from, to: gap.to }),
+        status: "active",
+        remediationHint:
+          "an optional allowed row is not yet built — either build it or remove the row",
+      });
+    }
+  } else {
+    for (const note of current.intentNotes ?? []) {
+      entries.push({
+        source: note,
+        kind: "aspirational-gap",
+        severity: "low",
+        age: 0,
+        count: 1,
+        id: entryId("aspirational-gap", note),
+        status: "active",
+        remediationHint:
+          "an optional allowed row is not yet built — either build it or remove the row",
+      });
+    }
   }
 
   // Which projects hold an accepted waiver — so a drift finding in the same
@@ -217,12 +374,20 @@ export function computeDebtLedger(current, snapshots, opts = {}) {
   for (const finding of current.findings ?? []) {
     const project = typeof finding.source === "string" ? finding.source : null;
     const waiverFailed = project !== null && waiverProjects.has(project);
+    // The stable fact keys on the full semantic tuple (source, target, rule)
+    // — never on `finding.source` alone, which collides every distinct
+    // same-source finding onto one id (F-DEB-5), and never on the prose
+    // `finding.message`, which re-keys a fact when the wording changes.
+    // `driftFactOf` is the ONE builder both the ledger and the producers use,
+    // so an introduced id can never disagree with the ledger's active id.
     entries.push({
       source: finding.source ?? finding.message,
       kind: "drift",
       severity: waiverFailed ? "high" : "medium",
       age: project ? ageOf(project) : 0,
       count: 1,
+      id: debtFactId("drift", driftFactOf(finding)),
+      status: "active",
       remediationHint: waiverFailed
         ? `this drift finding is in a project with an accepted waiver — the accepted violation is failing again, resolve it or remove the waiver`
         : "a dependency the intent forbids (or allows but is not built) — resolve the contradiction",
@@ -235,6 +400,8 @@ export function computeDebtLedger(current, snapshots, opts = {}) {
       severity: "unknown",
       age: 0,
       count: 1,
+      id: entryId("unresolved", unresolved.boundary),
+      status: "active",
       remediationHint:
         "an intent boundary matched no observed project — the intent cannot be verified",
     });
@@ -270,5 +437,80 @@ export function computeDebtLedger(current, snapshots, opts = {}) {
     if (entry.severity !== "unknown") bySeverity[entry.severity] += 1;
   }
 
-  return { entries, total: entries.length, byKind, bySeverity, agings, sampleTime };
+  // The lifecycle surface (design §6): every active entry carries a stable id
+  // and `status: "active"`. When an event store is linked, REPAIR events name
+  // the debt they closed (`debt.resolved`) and introduction events name what
+  // they opened (`debt.introduced`); the closure is only accepted when the
+  // candidate fact is NOT still active at head (an id that came back is not
+  // resolved). Without a linked store, `resolved` stays empty and no ref is
+  // ever fabricated — the note states the refs are unavailable instead.
+  const events = loadEvents(opts);
+  const activeIds = new Set(entries.map((entry) => entry.id));
+  /** @type {{id: string, status: "resolved", resolvedBy: string}[]} */
+  const resolved = [];
+  const lifecycle = { linked: events !== null, note: null };
+
+  if (events === null) {
+    lifecycle.note = "no event store linked — lifecycle refs unavailable";
+  } else {
+    /** @type {Map<string, string>} id → the first event that introduced it. */
+    const introducedByForId = new Map();
+    /** @type {Set<string>} debt ids already placed on the resolved list. */
+    const resolvedSeen = new Set();
+    for (const event of events) {
+      // The store validates that every event carries a string id, but the
+      // reader shape is loosely typed — coerce so the ref string is always a
+      // real string, never a fabricated one.
+      const eventId = typeof event?.id === "string" ? event.id : "";
+      for (const debtId of event?.debt?.introduced ?? []) {
+        if (typeof debtId === "string" && !introducedByForId.has(debtId)) {
+          introducedByForId.set(debtId, eventId);
+        }
+      }
+      const repairs = Array.isArray(event?.classifications)
+        ? event.classifications.includes("REPAIR")
+        : false;
+      if (!repairs) continue;
+      for (const debtId of event?.debt?.resolved ?? []) {
+        // Closure is only real when the candidate fact is gone at head; a
+        // debt id still active is not resolved (closed then re-opened), and
+        // an id NO event ever introduced was never debt — resolving it would
+        // invent a foreign fact out of nothing (inv. 2/7, F-DEB-2).
+        if (
+          typeof debtId !== "string" ||
+          activeIds.has(debtId) ||
+          resolvedSeen.has(debtId) ||
+          !introducedByForId.has(debtId)
+        )
+          continue;
+        resolvedSeen.add(debtId);
+        // The resolved surface carries ONLY evidence-backed refs. The full
+        // original entry (kind, severity, age, count) is not reconstructed
+        // here — that record lives on in the history snapshots behind the
+        // ledger; `kind:"debt"`, `age:0`, `count:1` would be fabricated
+        // numerics (design §6 retains the record, never a stand-in).
+        resolved.push({ id: debtId, status: "resolved", resolvedBy: eventId });
+      }
+    }
+    if (resolved.length > 0 && lifecycle.note === null) {
+      lifecycle.note =
+        "resolved rows retain only evidence-backed refs — each closed debt's full entry lives in the history snapshots";
+    }
+    for (const entry of entries) {
+      const introducedBy = introducedByForId.get(entry.id);
+      if (introducedBy !== undefined) entry.introducedBy = introducedBy;
+    }
+  }
+  resolved.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+
+  return {
+    entries,
+    resolved,
+    total: entries.length,
+    byKind,
+    bySeverity,
+    agings,
+    sampleTime,
+    lifecycle,
+  };
 }

package/src/governance/decision-fitness.mjs

@@ -0,0 +1,213 @@
+/**
+ * Decision fitness — the "IS IT STILL TRUE" verification level, one per
+ * decision that carries authority.
+ *
+ * This module DERIVES a decision's verification level from its attached
+ * executable constraints and their verdicts. It is a pure, descriptive reader
+ * of the governance state:
+ *
+ *   - it READS the decision's `bindings` (the constraint/fitness ids a record
+ *     makes enforceable) and the fitness-registry's verdicts for those
+ *     constraints;
+ *   - it never judges a constraint itself — the verdict for a bound constraint
+ *     comes in from the caller (a fitness-registry run), and `decisionFitness`
+ *     only folds those verdicts into one per-decision level;
+ *   - it is NOT wired into `check` exit codes this wave — a violated or
+ *     unverifiable decision does not fail `check` (Wave 2 keeps decision
+ *     fitness descriptive; see the Wave 2 design contract's scope section).
+ *
+ * ## The vocabulary (per decision, only for decisions WITH authority)
+ *
+ * A decision with no authority (`proposed` a draft, `superseded` replaced,
+ * `retired` withdrawn) is not measured — its fitness is `not_applicable` with
+ * a reason. A decision with authority is `active` (accepted and currently
+ * governing) or `accepted` (a decision made and recorded, "not yet verified"
+ * is a valid intermediate).
+ *
+ *   - `enforced` — at least one bound executable constraint/fitness resolves
+ *     AND was evaluated AND passed (verified true).
+ *   - `partially-enforced` — some bound constraints evaluated & passed, but
+ *     others are unverified / coverage incomplete.
+ *   - `violated` — at least one bound constraint/fitness FAILED: the decision's
+ *     "what must remain true" is currently false. RED direction.
+ *   - `unverifiable` — the decision has authority but no bound constraint/
+ *     fitness can be resolved/evaluated. RED direction — it is NEVER a pass;
+ *     "no violation" is not healthy.
+ *
+ * "Healthy" is NOT derivable from "no violations": a decision with no
+ * executable constraint is `unverifiable`, never healthy. `violated` and
+ * `unverifiable` are the two red directions; `enforced` is the only fully-green
+ * one.
+ *
+ * ## No `stale`, deliberately
+ *
+ * The contract offers a `stale` level only if the repository already has a
+ * time-based staleness notion. It does not (no decision-verification staleness
+ * exists anywhere in `src/`), so `stale` is folded into `unverifiable`: a
+ * decision whose evidence is out of date is, like one with no reachable
+ * constraint, not verified true — same red meaning, deterministic, no clock.
+ *
+ * ## Determinism
+ *
+ * No wall-clock time enters the model. The `io` argument exists for signature
+ * parity and future dependency injection (e.g. an injected clock), but the
+ * derivation needs none: it reads only the bound verdicts a caller supplies,
+ * so identical inputs yield byte-identical output. A caller that does need a
+ * timestamp (a later wave) injects the clock through `io` rather than reading
+ * the wall clock.
+ */
+
+import { hasAuthority } from "./adr-registry.mjs";
+
+/** The closed set of per-decision fitness levels `computeDecisionFitness` emits. */
+export const DECISION_FITNESS_LEVELS = Object.freeze([
+  "enforced",
+  "partially-enforced",
+  "violated",
+  "unverifiable",
+  "not_applicable",
+]);
+
+/** Whether a level names a red (never-healthy) direction. */
+export function isRedDirection(level) {
+  return level === "violated" || level === "unverifiable";
+}
+
+/**
+ * The resolver that turns a bound constraint id into its verdict record.
+ *
+ * @typedef {(bindingId: string) => (object | undefined)} DecisionRefLookup
+ *   Returns the fitness/constraint verdict for a bound id, or `undefined` when
+ *   no constraint resolves (or no verdict was produced for it) — a binding the
+ *   lookup cannot answer is an UNVERIFIED binding, never a silent pass.
+ */
+
+/**
+ * The per-decision fitness level.
+ *
+ * @typedef {object} DecisionFitness
+ * @property {string} id The record id (`NNN-slug`).
+ * @property {string} status The record's lifecycle status.
+ * @property {string} level One of `DECISION_FITNESS_LEVELS`.
+ * @property {boolean} verified True only for `enforced` — the decision's
+ *   "what must remain true" has a constraint that verifies true.
+ * @property {string} [reason] WHY the level, present on every non-`enforced`
+ *   level (which constraint failed, why "not applicable", why nothing
+ *   verified). Optional: `enforced` needs no reason.
+ */
+/**
+ * Computes the per-decision verification level for every record.
+ *
+ * Deterministic and pure: folds the supplied per-constraint verdicts into one
+ * level per decision, reading only the arguments. Bindings that fail win over
+ * everything (`violated`); when nothing fails and nothing passes, the decision
+ * is `unverifiable` — never healthy, the silent direction this vocabulary
+ * exists to refuse.
+ *
+ * @param {Array<{id: string, status: string, bindings: string[]}>} records
+ *   The ADR registry's parsed records (a `loadAdrRegistry` result or an
+ *   equivalent in tests).
+ * @param {unknown} _fitnessVerdicts
+ *   Reserved for parity with the wave's call shape. `computeDecisionFitness`
+ *   it (the lookup is the single door through which verdicts enter, so the
+ *   derivation stays agnostic to how the caller keys them).
+ * @param {DecisionRefLookup} decisionRefLookup Resolves a bound constraint id
+ *   to its verdict record (or `undefined` when it does not resolve / was not
+ *   evaluated). The only door through which verdicts enter the derivation.
+ * @param {object} [_io] The reserved `io` injection seam the wave's call shape
+ *   coordinates on. This derivation is pure and needs no clock (see the
+ *   no-`stale` note), so it is intentionally unused here; a later timestamp-
+ *   bearing wave injects a clock through this slot.
+ * @returns {DecisionFitness[]} One entry per record, in input order.
+ */
+export function computeDecisionFitness(records, _fitnessVerdicts, decisionRefLookup, _io = {}) {
+  /** @type {DecisionFitness[]} */
+  const out = [];
+
+  for (const record of records) {
+    if (!hasAuthority(record.status)) {
+      out.push({
+        id: record.id,
+        status: record.status,
+        level: "not_applicable",
+        verified: false,
+        reason: `status "${record.status}" carries no authority — only active/accepted decisions are measured`,
+      });
+      continue;
+    }
+
+    const bindings = record.bindings ?? [];
+    const resolved = bindings
+      .map((binding) => ({ binding, verdict: decisionRefLookup(binding) }))
+      .filter((entry) => entry.verdict !== undefined) // an unresolved binding is unverified
+      .map((entry) => entry.verdict);
+
+    const failed = resolved.filter((v) => v.verdict === "fail");
+    const passed = resolved.filter((v) => v.verdict === "pass");
+
+    if (failed.length > 0) {
+      out.push({
+        id: record.id,
+        status: record.status,
+        level: "violated",
+        verified: false,
+        reason: `bound constraint "${failed[0].name}" FAILED — what-must-remain-true is currently false`,
+      });
+      continue;
+    }
+
+    if (passed.length === 0) {
+      // RED: no bound constraint verifies true. Covers "no bindings",
+      // "bindings resolve to nothing", and "bindings evaluate but return
+      // unknown/not_applicable". Never a pass.
+      out.push({
+        id: record.id,
+        status: record.status,
+        level: "unverifiable",
+        verified: false,
+        reason: unverifiableReason(record, bindings, resolved),
+      });
+      continue;
+    }
+
+    if (passed.length === bindings.length && resolved.length === bindings.length) {
+      out.push({
+        id: record.id,
+        status: record.status,
+        level: "enforced",
+        verified: true,
+      });
+    } else {
+      out.push({
+        id: record.id,
+        status: record.status,
+        level: "partially-enforced",
+        verified: false,
+        reason:
+          `${passed.length} of ${bindings.length} bound constraint(s) verified true; ` +
+          `the rest are unverified or unevaluated`,
+      });
+    }
+  }
+
+  return out;
+}
+
+/**
+ * Names WHY a decision with authority verifies nothing true.
+ *
+ * @param {{id: string}} record
+ * @param {string[]} bindings
+ * @param {Array<{name: string, verdict: string}>} resolved
+ * @returns {string}
+ */
+function unverifiableReason(record, bindings, resolved) {
+  if (bindings.length === 0) {
+    return `no executable constraint/fitness is bound to ${record.id} — nothing can be verified`;
+  }
+  if (resolved.length === 0) {
+    return `no bound constraint for ${record.id} resolves or was evaluated — none can be verified`;
+  }
+  const names = resolved.map((v) => v.name ?? "?").join(", ");
+  return `bound constraint(s) ${names} evaluated but none verified true — coverage incomplete, not enforced`;
+}