@ecoma-io/archkeep 0.17.0 → 0.18.1

package/src/fixtures/evolution-lifecycle/workspace.mjs

@@ -0,0 +1,242 @@
+/**
+ * Fixture scaffolding for the Wave 3 W8 evolution-lifecycle conformance suite
+ * (`../evolution-lifecycle.integration.test.mjs`). This module is the ONE home
+ * for the real-git workspace builders that suite uses — a throwaway native Go
+ * workspace per case, materialized through real `git`, driven through the real
+ * `archkeep evolution` entry point.
+ *
+ * It deliberately reuses the native-workspace recipe already proven by
+ * `../commands/evolution.cli.integration.test.mjs` (an `archkeep.json` model,
+ * a `module-boundaries.config.mjs` law, and Go sources) rather than inventing
+ * a second convention, and threads the same environment guard (`../process.mjs`).
+ *
+ * Nothing here decides a verdict. It builds trees and drives the CLI; the
+ * assertions live in the suite. Keeping the builders here (and only here) is
+ * what the W8 task boundary requires: fixture scaffolding lives in
+ * `./fixtures/evolution-lifecycle/`, nowhere else.
+ */
+
+import { execFileSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { EXIT, runCli } from "../../../cli.mjs";
+import { SPAWN_BUDGET_MS, SPAWN_TEST_BUDGET_MS } from "../../../spawn-budget.mjs";
+import { environmentForTree } from "../../workspace.mjs";
+
+export { SPAWN_TEST_BUDGET_MS, EXIT };
+
+/** Identity flags keeping every fixture commit independent of the machine. */
+const IDENTITY = ["-c", "user.name=t", "-c", "user.email=t@t", "-c", "commit.gpgsign=false"];
+
+/**
+ * Runs git in `cwd` through the same environment guard production uses, with
+ * the single-spawn budget on every child so a wedged git fails the test rather
+ * than blocking the worker thread forever.
+ */
+export function git(cwd, ...args) {
+  return execFileSync("git", args, {
+    cwd,
+    env: environmentForTree(),
+    encoding: "utf8",
+    timeout: SPAWN_BUDGET_MS,
+    killSignal: "SIGKILL",
+  });
+}
+
+/** Writes `text` to `root/relativePath`, creating parent directories. */
+export function writeIn(root, relativePath, text) {
+  mkdirSync(join(root, relativePath, ".."), { recursive: true });
+  writeFileSync(join(root, relativePath), text);
+}
+
+/** Stages every change and commits with the fixture identity; returns the SHA. */
+export function commit(root, message) {
+  git(root, ...IDENTITY, "add", "-A");
+  git(root, ...IDENTITY, "commit", "-q", "-m", message);
+  return git(root, "rev-parse", "HEAD").trim();
+}
+
+/** Resolves the current HEAD of the fixture. */
+export function headOf(root) {
+  return git(root, "rev-parse", "HEAD").trim();
+}
+
+/**
+ * Opens a brand-new throwaway native git workspace (never the repository's own
+ * tree). `archkeep.json` declares two Go projects on two layers, exactly the
+ * MODEL `../commands/evolution.cli.integration.test.mjs` uses, so a case can
+ * lay an edge between them and the native provider draws it.
+ *
+ * @returns {{root: string}}
+ */
+export function createWorkspace() {
+  const root = mkdtempSync(join(tmpdir(), "archkeep-lifecycle-"));
+  git(root, "init", "-q", "-b", "main");
+  writeIn(root, "archkeep.json", `${MODEL()}\n`);
+  writeIn(root, "libs/alpha/go.mod", "module example.com/alpha\n\ngo 1.22\n");
+  writeIn(root, "libs/beta/go.mod", "module example.com/beta\n\ngo 1.22\n");
+  return { root };
+}
+
+/**
+ * The native workspace model: two Go projects on two layers (alpha is
+ * `layer:a`, beta is `layer:b`), the law file exempted from coverage.
+ */
+const MODEL = () =>
+  JSON.stringify(
+    {
+      projects: {
+        declared: [
+          { root: "libs/alpha", name: "alpha", tags: ["layer:a"] },
+          { root: "libs/beta", name: "beta", tags: ["layer:b"] },
+        ],
+      },
+      coverage: {
+        exempt: [{ path: "module-boundaries.config.mjs", reason: "the workspace's own law" }],
+      },
+    },
+    null,
+    2,
+  );
+
+/** The eight options a valid boundary law must carry, per `policyFrom`. */
+const OPTIONS = `export const moduleBoundaryOptions = {
+  allow: [],
+  buildTargets: ["build"],
+  enforceBuildableLibDependency: false,
+  allowCircularSelfDependency: false,
+  checkDynamicDependenciesExceptions: [],
+  ignoredCircularDependencies: [],
+  banTransitiveDependencies: false,
+  checkNestedExternalImports: false,
+};
+`;
+
+export const ALPHA_CLEAN = `package alpha
+
+func Name() string { return "alpha" }
+`;
+
+export const ALPHA_REACHING = `package alpha
+
+import (
+	"example.com/beta"
+)
+
+func Name() string { return "alpha" + beta.Suffix() }
+`;
+
+export const BETA = `package beta
+
+func Suffix() string { return "-beta" }
+`;
+
+/**
+ * Writes a `module-boundaries.config.mjs` law at `root` with the given
+ * `depConstraints` rows and optional `fitness` array.
+ *
+ * @param {string} root
+ * @param {{rows?: string, fitness?: string}} [law]
+ */
+export function writeLaw(root, { rows = "", fitness } = {}) {
+  writeIn(
+    root,
+    "module-boundaries.config.mjs",
+    `export const depConstraints = [\n${rows}\n];\n${OPTIONS}` +
+      (fitness === undefined ? "" : `\nexport const fitness = ${fitness};\n`),
+  );
+}
+
+/**
+ * A single permitted layer rule (a may reach b). The same ONE_ROW the
+ * evolution CLI integration fixtures use, so an allowed alpha→beta edge never
+ * trips a boundary rule.
+ */
+export const ALLOW_A_TO_B = `  { sourceTag: "layer:a", onlyDependOnLibsWithTags: ["layer:b"] },`;
+
+/**
+ * Writes `architecture-intent.json` at `root`. `sections` carries the top-level
+ * keys directly (`version`, `boundaries`, `allowed`, `forbidden`,
+ * `dependencies`, …); `version` defaults to "1".
+ */
+export function writeIntent(root, sections) {
+  writeIn(root, "architecture-intent.json", `${JSON.stringify(sections, null, 2)}\n`);
+}
+
+/**
+ * Writes one ADR record under `docs/adr/`, the shape `adr-registry.mjs` reads.
+ * `record` is the frontmatter map (`{id, status, supersedes?, bindings?}`).
+ */
+export function writeAdr(root, filename, record) {
+  const lines = ["---", `id: ${record.id}`, `status: ${record.status}`];
+  if (record.supersedes?.length) {
+    lines.push("supersedes:");
+    for (const target of record.supersedes) lines.push(`  - ${target}`);
+  }
+  if (record.bindings?.length) {
+    lines.push("bindings:");
+    for (const binding of record.bindings) lines.push(`  - ${binding}`);
+  }
+  lines.push("---", "", `# ${record.id}`, "");
+  writeIn(root, join("docs/adr", filename), `${lines.join("\n")}\n`);
+}
+
+/**
+ * Drives the CLI in-process over `cwd`, capturing streams. Returns the exit
+ * code and joined `out`/`err`. `runCli` is the real entry point
+ * (`../cli.mjs`), never a shell-out to a binary named `archkeep`.
+ */
+export async function runEvolution(cwd, argv) {
+  const out = [];
+  const err = [];
+  const exitCode = await runCli(argv, {
+    out: (text) => out.push(text),
+    err: (text) => err.push(text),
+    cwd,
+  });
+  return { exitCode, out: out.join("\n"), err: err.join("\n") };
+}
+
+/**
+ * Invokes `evolution --base <base> [--head <head>] [--event-out <dir>] [--format json]`.
+ *
+ * @param {string} base The base revision (full SHA).
+ * @param {{head?: string, eventOut?: string, format?: string}} [options]
+ */
+export function evolutionArgs(base, { head, eventOut, format = "json" } = {}) {
+  const args = ["evolution", "--base", base];
+  if (head) args.push("--head", head);
+  if (eventOut) args.push("--event-out", eventOut);
+  if (format) args.push("--format", format);
+  return args;
+}
+
+/**
+ * Parses the `--format json` envelope out of a successful evolution run.
+ */
+export function parseEnvelope(run) {
+  if (run.exitCode !== EXIT.ok) throw new Error(`evolution exited ${run.exitCode}: ${run.err}`);
+  return JSON.parse(run.out);
+}
+
+/** The parsed event files in `dir`, in filename order. */
+export function readEvents(dir) {
+  return readdirSync(dir)
+    .filter((name) => name.endsWith(".json") && !name.endsWith(".json.tmp"))
+    .sort()
+    .map((name) => JSON.parse(readFileSync(join(dir, name), "utf8")));
+}
+
+/** The event store's file names in `dir`, in filename order. */
+export function eventFiles(dir) {
+  return readdirSync(dir)
+    .filter((name) => name.endsWith(".json") && !name.endsWith(".json.tmp"))
+    .sort();
+}
+
+/** Removes a throwaway workspace. */
+export function dispose(root) {
+  rmSync(root, { recursive: true, force: true });
+}

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,
+  };
 }