@ecoma-io/archkeep 0.13.0

package/src/commands/custom-rules.mjs

@@ -0,0 +1,428 @@
+/**
+ * The custom-rules fold: every rule the workspace's policy declares, loaded
+ * from its artifact and judged over the evidence this run already computed.
+ *
+ * A custom rule is a pure function from evidence to verdict
+ * (`../../../../docs/adr/0002-custom-rules-one-contract.md`). Two modules
+ * already own the halves of that sentence — `../custom-rules/evidence.mjs`
+ * builds the "in" side and `../custom-rules/host.mjs` runs the artifact and
+ * holds it to the contract — and neither reads a file, because the commands
+ * layer owns files (`./README.md`, and the same split `../rules/README.md`
+ * states: "reads records, never files"). This module is the third piece: it
+ * turns a declared row into bytes, drives those two, and hands back the same
+ * verdict records `check` already folds into its exit machinery for fitness.
+ *
+ * ## By presence, and once
+ *
+ * There is no `--custom-rules` flag, for the reason there is no `--fitness`
+ * one (`./fitness.mjs`'s header): an opt-in flag makes a forgotten flag
+ * byte-identical to "no custom rules checked", which is the silent direction
+ * this tool exists to end. A policy that declares `customRules` gets them
+ * judged, once per run, over the facts the run already holds.
+ *
+ * ## The two failure classes are not interchangeable
+ *
+ * `../custom-rules/host.mjs` separates them and this module routes them:
+ *
+ * - **LOAD** — the declared law could not be loaded (unreadable artifact,
+ *   hash mismatch, bytes that are not wasm, a module that asks for an import,
+ *   a missing export, a self-description that will not read). This module
+ *   THROWS, which reaches a reader the way a malformed boundary config does:
+ *   `../../cli.mjs`'s `runCheck` prints the message and exits 3. Judging a
+ *   tree against a law that was never read would be a verdict about nothing —
+ *   and reporting the rule as `unknown` instead would let a workspace ship a
+ *   permanently unloadable rule and still see a green-ish table row for it.
+ *   Every rule is loaded BEFORE any is evaluated, so a run either judges the
+ *   whole declared law or refuses it; half a law, half-applied, is a verdict
+ *   nobody declared.
+ * - **EVALUATE** — the law loaded and this rule could not reach a verdict (a
+ *   trap, a timeout, an unreadable verdict, an evidence kind this contract
+ *   does not carry). The RULE's verdict becomes `unknown` with the host's own
+ *   self-standing reason carried through unedited, and the run's exit follows
+ *   the same lane a `unknown` fitness function takes (exit 3).
+ *
+ * ## A path-scoped run answers `not_applicable`, before anything is read
+ *
+ * `check <path>` analyzes a subset of the tree, so the `imports` kind is a
+ * subset and the evidence bundle would describe a workspace that does not
+ * exist. A rule judged over it would answer about a tree nobody has —
+ * `not_applicable` is the posture `coverage-minimum` already takes for the
+ * identical reason (`../governance/fitness-rules.mjs`'s `coverageMinimum`):
+ * loud, reason named, and — unlike `unknown` — not by itself a failed run, so
+ * a scoped run over a clean subtree does not exit 3 for a question it was
+ * never in a position to ask.
+ *
+ * The decision is taken BEFORE any artifact is read, which is the one place
+ * this module deliberately differs from a full run: a scoped run reads no
+ * artifact, hashes nothing, and starts no worker. Loading is not free — it
+ * runs `archkeep_describe` inside a worker — and paying for it to reach a
+ * verdict already known to be `not_applicable` would be work with no judgment
+ * behind it. Nothing is hidden by that: every declared rule still gets its own
+ * row, naming itself and why it did not apply, in all three faces.
+ *
+ * ## Determinism
+ *
+ * Rules are judged in declaration order (row order is semantic for a policy,
+ * the same reason `../canonical.mjs` leaves `depConstraints` order alone), and
+ * a rule's own findings are left in the order it emitted them: a rule holds no
+ * ambient capability, so its output is a function of the evidence bytes, and
+ * re-sorting would destroy an order the rule chose rather than normalize an
+ * accident. The evidence itself is byte-deterministic by construction
+ * (`../custom-rules/evidence.mjs`).
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { containmentViolation } from "../containment.mjs";
+import { buildEvidenceBundle, serializeEvidenceBundle } from "../custom-rules/evidence.mjs";
+import {
+  CUSTOM_RULE_TIMEOUT_MS,
+  evaluateCustomRule,
+  loadCustomRule,
+} from "../custom-rules/host.mjs";
+// The overall-verdict precedence — any `fail`, then any `unknown`, then
+// all-`not_applicable`, else `pass` — is stated once, by the module that
+// already owned it for fitness. A second copy here would be the one that
+// drifted (`../../../../AGENTS.md`, "Never state a rule twice").
+import { fitnessVerdictFor } from "../governance/fitness-registry.mjs";
+import { fitnessVerdict } from "../governance/verdict.mjs";
+
+/**
+ * The namespace every custom finding is reported under, in all three faces:
+ * `custom/<ruleName>/<findingId>`. Built here, once, and carried on the
+ * records this module hands back — so `../report/text.mjs`, `../report/sarif.mjs`
+ * and `../../cli.mjs`'s JSON envelope render an id rather than compose one,
+ * and three faces cannot come to spell the same finding three ways.
+ *
+ * @param {string} ruleName
+ * @param {string} findingId
+ * @returns {string}
+ */
+function namespacedId(ruleName, findingId) {
+  return `custom/${ruleName}/${findingId}`;
+}
+
+/**
+ * Whether a policy declares custom rules at all — the one condition that
+ * separates "this workspace declared no rules of its own" from "the rules
+ * could not be judged". Exported so `../../cli.mjs` and this module cannot
+ * come to disagree about what "declares custom rules" means, the same bargain
+ * `./fitness.mjs`'s `declaresFitness` states.
+ *
+ * @param {{customRules?: unknown}|null|undefined} config The loaded policy.
+ * @returns {boolean}
+ */
+export function declaresCustomRules(config) {
+  return config !== null && config !== undefined && config.customRules !== undefined;
+}
+
+/**
+ * The default artifact reader: a rule's bytes, read from the workspace root.
+ *
+ * Binary, and therefore not `Workspace.readFile` — that reader decodes UTF-8
+ * (`../workspace.mjs`), which would replace every byte a wasm module is made
+ * of. It carries the same containment rule that reader does: a path that
+ * resolves through a symlink out of the tree hands back bytes the workspace
+ * never committed, and running them as the declared law is the whole verdict
+ * built on outside input (`../containment.mjs`, the G-10 closure).
+ *
+ * `null` covers every way the bytes did not arrive — absent, unreadable,
+ * escaping the tree — because the caller reports all three the same way: a
+ * declared law with no bytes behind it is a run that refuses. The artifact is
+ * NOT required to be a tracked file: the `sha256` the row pins is what makes
+ * "the law CI ran is the law review saw" checkable (`../config.mjs`), and a
+ * tracked-ness requirement would refuse a legitimately generated artifact
+ * whose hash a reviewer approved in the policy anyway.
+ *
+ * @param {string} root Absolute workspace root.
+ * @returns {(artifact: string) => Uint8Array|null}
+ */
+export function readArtifactBytes(root) {
+  return (artifact) => {
+    const abs = join(root, artifact);
+    if (containmentViolation(root, abs) !== null) return null;
+    try {
+      return readFileSync(abs);
+    } catch {
+      return null;
+    }
+  };
+}
+
+/**
+ * @param {string} name
+ * @param {string} reason
+ * @returns {never}
+ */
+function refuseLoad(name, reason) {
+  // The `custom rule "<name>": ` prefix is the host's own spelling for a
+  // failure (`../custom-rules/host.mjs`'s `failed`), matched here so a
+  // caller-side load failure and a host-side one read as one class.
+  throw new Error(`archkeep: custom rule "${name}": ${reason}`);
+}
+
+/**
+ * One rule's verdict record — the same envelope every governance consumer
+ * reads (`../governance/verdict.mjs`), plus the two facts a custom rule adds.
+ *
+ * `reason` is the policy row's own declared reason (why the workspace has this
+ * rule at all), which is a different question from a verdict's `message` (what
+ * this run decided) and from `notApplicableReason` (why it did not apply). All
+ * three can be true at once, so all three are carried rather than collapsed.
+ *
+ * @param {{name: string, reason: string}} row The declared policy row.
+ * @param {{verdict: "pass"|"fail"|"unknown"|"not_applicable", evidence: object,
+ *   message: string, findings?: object[], notApplicableReason?: string}} decided
+ * @returns {object}
+ */
+function decisionFor(row, decided) {
+  return {
+    ...fitnessVerdict({
+      verdict: decided.verdict,
+      name: row.name,
+      evidence: decided.evidence,
+      message: decided.message,
+      notApplicableReason: decided.notApplicableReason,
+    }),
+    reason: row.reason,
+    findings: decided.findings ?? [],
+  };
+}
+
+/**
+ * A declared rule's row on a path-scoped run.
+ *
+ * `evidence` names the artifact but NOT its `sha256`: on this path nothing was
+ * read and nothing was hashed, and printing the declared digest beside a rule
+ * that never ran would present an unverified claim in the slot every other row
+ * uses for a verified one.
+ *
+ * @param {{name: string, artifact: string, reason: string}} row
+ * @returns {object}
+ */
+function scopedDecision(row) {
+  return decisionFor(row, {
+    verdict: "not_applicable",
+    evidence: { artifact: row.artifact, scoped: true },
+    notApplicableReason:
+      "this run was scoped to specific paths — a custom rule is judged over whole-tree evidence, " +
+      "and it needs a full, unscoped run",
+    message:
+      "does not apply to a path-scoped run — a custom rule sees the whole tree's evidence or " +
+      "none of it, so it needs a full `check` with no paths",
+  });
+}
+
+/**
+ * The evidence facts every rule in this run is judged over, assembled once.
+ *
+ * Only the `rule` block differs between rules (its `params` ride inside the
+ * bundle), so everything else is collected here and handed to
+ * `buildEvidenceBundle` once per rule. The bundle's own sorting and validation
+ * run per call — that is its contract, and reaching around it to sort here
+ * would put a second opinion about "what the evidence is" beside the one
+ * module that owns the question.
+ *
+ * Attribution for `imports` comes from `commandContext.owned` — the ownership
+ * map `../workspace.mjs` already built — because the workspace layer is the
+ * only one allowed to say which project owns a file, and re-deriving it from a
+ * root prefix here would be a second answer to a question already answered.
+ *
+ * @param {object} commandContext From `./context.mjs`'s `resolveCommandContext`.
+ * @param {object} policy The loaded boundary policy.
+ * @returns {{projects: object[], edges: object[], imports: object[], policy: object}}
+ */
+function observedFacts(commandContext, policy) {
+  const { graph, owned, analysis } = commandContext;
+  const projectOfFile = new Map(owned.map(({ file, project }) => [file, project]));
+  return {
+    // Tags are read off the graph node, which is where a provider puts them —
+    // and a node with no `tags` key IS an untagged project, the same reading
+    // `../rules/` already gives it (`projectWithoutTagsCannotHaveDependencies`
+    // exists precisely because that state is real), never "tags were not read".
+    // `root` is passed through verbatim: a graph that carries none refuses in
+    // `buildEvidenceBundle` by name rather than being defaulted to a path.
+    projects: Object.entries(graph.nodes).map(([key, node]) => ({
+      name: node.name ?? key,
+      root: node.data?.root,
+      tags: Array.isArray(node.data?.tags) ? node.data.tags : [],
+    })),
+    edges: Object.values(graph.dependencies ?? {}).flat(),
+    imports: analysis.imports.map((site) => ({
+      site,
+      // `undefined` here is not papered over: `buildEvidenceBundle` refuses an
+      // unattributed site by name, which is the loud direction for a state
+      // that means the ownership map and the analysis disagree.
+      sourceProject: projectOfFile.get(site.sourceFile),
+    })),
+    policy,
+  };
+}
+
+/**
+ * One rule's verdict, from the verdict document it returned.
+ *
+ * @param {{name: string, artifact: string, sha256: string, reason: string}} row
+ * @param {Record<string, any>} verdict The validated verdict document.
+ * @returns {object}
+ */
+function judgedDecision(row, verdict) {
+  const findings = verdict.findings.map((finding) => ({
+    id: namespacedId(row.name, finding.id),
+    message: finding.message,
+    // Every position field is stated only when the rule stated it: a finding
+    // about a whole workspace has no file, and writing one in would send a
+    // reader to a line the rule never claimed (`../report/sarif.mjs` drops the
+    // location block for the same reason).
+    ...(finding.sourceFile === undefined ? {} : { sourceFile: finding.sourceFile }),
+    ...(finding.line === undefined ? {} : { line: finding.line }),
+    ...(finding.column === undefined ? {} : { column: finding.column }),
+    ...(finding.project === undefined ? {} : { project: finding.project }),
+  }));
+  const evidence = { artifact: row.artifact, sha256: row.sha256, findings: findings.length };
+  if (verdict.verdict === "fail") {
+    return decisionFor(row, {
+      verdict: "fail",
+      evidence,
+      findings,
+      message: `reported ${findings.length} finding${findings.length === 1 ? "" : "s"}`,
+    });
+  }
+  if (verdict.verdict === "unknown") {
+    return decisionFor(row, {
+      verdict: "unknown",
+      evidence,
+      findings,
+      message: `could not judge this workspace — ${verdict.reason}`,
+    });
+  }
+  if (verdict.verdict === "not_applicable") {
+    return decisionFor(row, {
+      verdict: "not_applicable",
+      evidence,
+      findings,
+      notApplicableReason: verdict.notApplicableReason,
+      message: `did not apply to this workspace — ${verdict.notApplicableReason}`,
+    });
+  }
+  return decisionFor(row, {
+    verdict: "pass",
+    evidence,
+    findings,
+    message: "judged this workspace and reported no finding",
+  });
+}
+
+/**
+ * Every declared custom rule, loaded and judged against this run's facts.
+ *
+ * @param {object} commandContext From `./context.mjs`'s `resolveCommandContext`.
+ * @param {{rows: object[], policy: object, scoped?: boolean,
+ *   readArtifact?: (artifact: string) => Uint8Array|null, collectEvidence?: boolean,
+ *   timeoutMs?: number}} run
+ *   `rows` is the validated `customRules` list, `policy` the loaded boundary
+ *   policy the `policy` evidence kind is read from, `scoped` set when `paths`
+ *   narrowed the run. `readArtifact` is the one seam reaching outside this
+ *   process, injectable for the reason every reader in this package is; a
+ *   smaller `timeoutMs` lets a test drive the budget without waiting out the
+ *   real one. `collectEvidence` keeps each rule's serialized bundle for the
+ *   caller — what `../../cli.mjs`'s `--evidence-out` writes out, and off by
+ *   default because the bundle is the largest document a run builds.
+ * @returns {Promise<{decisions: object[], overall: {verdict: string},
+ *   catalogue: {ruleId: string, rule: string, findingId: string, message: string}[],
+ *   evidence: {rule: string, bytes: Uint8Array}[]}>}
+ *   `catalogue` is every finding each loaded rule DECLARES it can report — the
+ *   reportingDescriptor set a SARIF result resolves against — so a rule that
+ *   fired nothing is still described rather than nameless. It is empty on a
+ *   scoped run, where nothing was loaded. `evidence` is empty unless
+ *   `collectEvidence` asked for it, and always empty on a scoped run — the
+ *   two states are told apart by the caller, which knows which it asked for.
+ * @throws {Error} on any load-class failure, naming the rule and the reason.
+ */
+export async function customRulesForCheck(
+  commandContext,
+  {
+    rows,
+    policy,
+    scoped = false,
+    readArtifact,
+    collectEvidence = false,
+    timeoutMs = CUSTOM_RULE_TIMEOUT_MS,
+  },
+) {
+  if (scoped) {
+    const decisions = rows.map(scopedDecision);
+    // No bundle is built on this path and none is returned: a scoped run's
+    // evidence would describe a workspace that does not exist, and handing an
+    // author bytes their rule was never judged over is worse than handing
+    // them none. `../../cli.mjs`'s `--evidence-out` says so out loud rather
+    // than writing an empty directory.
+    return { decisions, overall: fitnessVerdictFor(decisions), catalogue: [], evidence: [] };
+  }
+
+  const read = readArtifact ?? readArtifactBytes(commandContext.root);
+
+  /** @type {{row: object, module: WebAssembly.Module, describe: Record<string, any>}[]} */
+  const loaded = [];
+  for (const row of rows) {
+    const artifactBytes = read(row.artifact);
+    if (artifactBytes === null || artifactBytes === undefined) {
+      refuseLoad(
+        row.name,
+        `the artifact "${row.artifact}" could not be read — a path that does not exist, cannot ` +
+          `be opened, or resolves through a symlink out of the workspace all reach this run as ` +
+          `no bytes at all, and a declared law with no bytes behind it is a run that refuses ` +
+          `rather than a rule that quietly judges nothing`,
+      );
+    }
+    const outcome = await loadCustomRule({
+      name: row.name,
+      artifactBytes,
+      declaredSha256: row.sha256,
+      timeoutMs,
+    });
+    if (!outcome.ok) throw new Error(`archkeep: ${outcome.failure.reason}`);
+    loaded.push({ row, module: outcome.module, describe: outcome.describe });
+  }
+
+  const catalogue = loaded.flatMap(({ row, describe }) =>
+    describe.findings.map((entry) => ({
+      ruleId: namespacedId(row.name, entry.id),
+      rule: row.name,
+      findingId: entry.id,
+      message: entry.message,
+    })),
+  );
+
+  const observed = observedFacts(commandContext, policy);
+  /** @type {{rule: string, bytes: Uint8Array}[]} */
+  const evidence = [];
+  const decisions = [];
+  for (const { row, module, describe } of loaded) {
+    // `row` is handed to the bundle as the declared row itself — read, never
+    // written (`../custom-rules/evidence.mjs`'s `buildEvidenceBundle`), which
+    // is what keeps an absent `params` absent on the policy object every later
+    // reader sees.
+    const evidenceBytes = serializeEvidenceBundle(buildEvidenceBundle({ ...observed, rule: row }));
+    // Collected only when a caller asked for it. The bundle is the largest
+    // document this run builds — every import site in the tree — and keeping
+    // one per rule alive for a run nobody asked to inspect would be memory
+    // spent on a debugging aid that was never requested.
+    if (collectEvidence) evidence.push({ rule: row.name, bytes: evidenceBytes });
+    const outcome = await evaluateCustomRule({ module, describe, evidenceBytes, timeoutMs });
+    decisions.push(
+      outcome.ok
+        ? judgedDecision(row, outcome.verdict)
+        : decisionFor(row, {
+            verdict: "unknown",
+            evidence: { artifact: row.artifact, sha256: row.sha256, findings: 0 },
+            // The host's own words, unedited: the reason is self-standing by
+            // its contract, and a paraphrase here would be a second account of
+            // a failure only the host saw.
+            message: outcome.failure.reason,
+          }),
+    );
+  }
+
+  return { decisions, overall: fitnessVerdictFor(decisions), catalogue, evidence };
+}

package/src/commands/debt.mjs

@@ -0,0 +1,218 @@
+/**
+ * The `debt` command: the architecture-debt ledger — the exemptions, gaps and
+ * violations a workspace is carrying, each aged across the snapshot history.
+ *
+ * Descriptive, read-only: `debt` never changes a verdict and never exits 1.
+ * It computes today's candid facts the same way `check`/`drift` do — the
+ * boundary config's `boundarySuppressions`, and `judgeIntent`'s findings,
+ * notes and unresolved — and ages them across the history directory `graph
+ * --format json` snapshots live in (`../commands/history.mjs`'s
+ * `readSnapshots`).
+ *
+ * It is a report, not a gate: its exit code is 0 on a completed ledger (even a
+ * long one) and 3 when the run cannot complete — no snapshots, a malformed or
+ * inconsistent snapshot directory, incomplete graph coverage, or intent that
+ * cannot be verified.
+ *
+ * ## The snapshot directory
+ *
+ * The ledger ages across the same directory the `history` command reads — a
+ * consumer-managed directory of graph envelopes, the sole source of truth
+ * with no index file (that is `history`'s choice, inherited here). When the
+ * directory holds fewer than two snapshots, `agings: false` states that every
+ * entry is really age-0 because the record cannot establish age — never a
+ * guessed age. A missing directory is a no-verdict (exit 3), never an empty
+ * ledger.
+ *
+ * ## Fail-closed
+ *
+ * Three conditions refuse loudly (exit 3) instead of degrading:
+ *
+ * - the graph coverage is incomplete — every "project missing" would be
+ *   ambiguous between "gone" and "never seen";
+ * - the intent cannot be verified (`judgeIntent`'s `unresolved` non-empty) —
+ *   an intent that cannot be verified is not a clean ledger ("cannot verify"
+ *   must never read as "no debt");
+ * - the snapshot directory cannot be read or parsed — the ledger would either
+ *   be empty (a shrug) or age against a record it could not read.
+ *
+ * An empty entry list must mean exactly "no exemptions, gaps or findings".
+ *
+ * ## Determinism
+ *
+ * The ledger sorts by the evaluator's total key — plain `<` comparison, never
+ * `localeCompare` — and `sampleTime` rides in the result so a reader can see
+ * when the ledger was taken; the aging itself is snapshot-relative
+ * (`../governance/debt-ledger.mjs`).
+ */
+import { isWholeFileFailure } from "../analysis/source-util.mjs";
+import { judgeIntent } from "../architecture-intent/judge.mjs";
+import { INTENT_FILE, loadIntent } from "../architecture-intent/model.mjs";
+import { computeDebtLedger } from "../governance/debt-ledger.mjs";
+import { formatDebtReport } from "../report/debt-text.mjs";
+import { jsonEnvelope, renderJson } from "../report/json.mjs";
+import { resolveProvenance } from "./provenance.mjs";
+import { buildObserved, refuseIncompleteGraph } from "./drift.mjs";
+import { readSnapshots } from "./history.mjs";
+
+/**
+ * Runs the `debt` command: computes the current candid facts, ages them across
+ * the snapshot directory, and returns the ledger report.
+ *
+ * The `config` is resolved by the caller (`cli.mjs`) exactly the way `diff`'s
+ * is — `--config`, the workspace's declared `boundaryConfig`, or the inline
+ * `archkeep.json` policy — so a debt run and a `check` run never disagree about
+ * the current boundary law.
+ *
+ * @param {string} dir Absolute path to the history directory.
+ * @param {object} commandContext From `resolveCommandContext`.
+ * @param {{config?: {depConstraints: object[], options: object,
+ *   suppressions: object[]}|null, referenceTime?: number|string,
+ *   io?: {readSnapshots?: Function, loadIntentOverride?: Function,
+ *   resolveProvenance?: Function}}} [options] Injectable seams for tests,
+ *   mirroring the `history`/`drift` pattern.
+ * @returns {Promise<{status: "ok", ledger: object, coverage: object,
+ *   report: {text: string, json: string}}>}
+ * @throws {Error} on every condition the header lists, all exit-3 class.
+ */
+export async function debtCommand(dir, commandContext, options = {}) {
+  const { root, provider, marker, analysis } = commandContext;
+  const io = options.io ?? {};
+  const config = options.config ?? { depConstraints: [], options: {}, suppressions: [] };
+
+  refuseIncompleteGraph(commandContext);
+
+  const notAnalyzed = analysis.failures
+    .filter(isWholeFileFailure)
+    .map(({ sourceFile, reason }) => ({ file: sourceFile, reason }));
+  if (notAnalyzed.length > 0) {
+    throw new Error(
+      `archkeep: debt has incomplete coverage — ${notAnalyzed.length} file` +
+        `${notAnalyzed.length === 1 ? "" : "s"} could not be analyzed, so every "project missing" ` +
+        `would be ambiguous between "gone" and "never seen". Fix the unanalyzed files and re-run.`,
+    );
+  }
+
+  // The snapshot directory is the sole source of truth for aging; a directory
+  // that cannot be read or parsed throws here (exit 3), never an empty ledger.
+  const read = (io.readSnapshots ?? readSnapshots)(dir, root);
+
+  // A directory that EXISTS but holds no snapshots is the same state
+  // `historyCommand` refuses in `./history.mjs`, and for the same reason: an
+  // empty directory is not an empty history, it is no record at all. The
+  // ledger ages every entry against that record, so with nothing to age
+  // against a "✔ no architecture debt" line would be a claim this run cannot
+  // make — a fresh `.archkeep/history/`, or a CI cache whose capture step never
+  // ran, would silently turn a `archkeep debt` gate into a no-op. This
+  // command's own header says so ("A missing directory is a no-verdict
+  // (exit 3), never an empty ledger"); an unpopulated one is the same
+  // no-verdict wearing a different errno.
+  if (read.files.length === 0) {
+    throw new Error(
+      `archkeep: the history directory '${dir}' contains no snapshots — there is no record to ` +
+        `age the ledger against, so "no architecture debt" would be a claim this run cannot ` +
+        `make. Capture one first with 'archkeep history <dir> --capture' (or point the command ` +
+        `at the directory where you keep graph snapshots).`,
+    );
+  }
+
+  const intent = await (io.loadIntentOverride ?? loadIntent)(root, {
+    tracked: commandContext.tracked,
+  });
+  if (intent === undefined) {
+    throw new Error(
+      `archkeep: debt requires a tracked ${INTENT_FILE} at the workspace root, but none ` +
+        `is present — a ledger of architecture debt needs the declared intent to compare against`,
+    );
+  }
+
+  const verdict = judgeIntent(intent, {
+    nodes: commandContext.graph.nodes,
+    dependencies: commandContext.graph.dependencies,
+  });
+  if (verdict.unresolved.length > 0) {
+    throw new Error(
+      `archkeep: cannot build a debt ledger — ${INTENT_FILE} cannot be verified: ` +
+        verdict.unresolved
+          .map(({ boundary, issue }) => `boundary/row ${boundary}: ${issue}`)
+          .join("; ") +
+        `. An intent that cannot be verified is not a clean ledger; fix the intent or the graph and re-run.`,
+    );
+  }
+
+  const ledger = computeDebtLedger(
+    {
+      suppressions: config.suppressions,
+      intentNotes: verdict.notes,
+      findings: verdict.findings,
+    },
+    read,
+    { referenceTime: options.referenceTime },
+  );
+
+  const observed = buildObserved(commandContext);
+  const coverage = {
+    complete: true,
+    projects: observed.projects.length,
+    analyzedFiles: analysis.analyzed,
+    imports: analysis.imports.length,
+    notAnalyzed: [],
+    blindSpots: analysis.failures
+      .filter((failure) => !isWholeFileFailure(failure))
+      .map(({ sourceFile, line, column, reason }) => ({ file: sourceFile, line, column, reason })),
+    // The ledger names what it could not age — a reader can tell "aged" from
+    // "observed, not yet aged". The second note discloses `sampleTime`'s own
+    // nature: it reflects the wall clock at the moment of THIS run, not the
+    // workspace, so it is expected to differ between two runs of an unchanged
+    // tree, by design (`../governance/clock.mjs`) — disclosed here, in-band,
+    // so a consumer diffing or hashing two envelopes to detect real drift
+    // knows to exclude it rather than read clock drift as architectural
+    // change; every other field is deterministic given the same law, history
+    // directory and tree.
+    notes: [
+      `ledger ages are snapshot-relative; ${ledger.entries.length} entr` +
+        `${ledger.entries.length === 1 ? "y" : "ies"} derived across ${read.files.length} snapshot` +
+        `${read.files.length === 1 ? "" : "s"}`,
+      "sampleTime is the wall clock at the moment of this run, not a fact about the " +
+        "workspace — it is expected to differ between two runs of an unchanged tree and " +
+        "should be excluded from any diff or hash meant to detect real change. Every other " +
+        "field here is deterministic given the same law, history directory and tree.",
+    ],
+  };
+
+  const context = {
+    root,
+    provider,
+    marker,
+    provenance: (io.resolveProvenance ?? resolveProvenance)(root),
+  };
+  const result = {
+    dir,
+    snapshots: read.files.length,
+    agings: ledger.agings,
+    sampleTime: ledger.sampleTime,
+    entries: ledger.entries,
+    total: ledger.total,
+    byKind: ledger.byKind,
+    bySeverity: ledger.bySeverity,
+  };
+
+  const envelope = jsonEnvelope({
+    command: "debt",
+    context,
+    status: "ok",
+    exitCode: 0,
+    coverage,
+    result,
+  });
+
+  return {
+    status: "ok",
+    ledger: result,
+    coverage,
+    report: {
+      text: formatDebtReport({ ledger: result, coverage }),
+      json: renderJson(envelope),
+    },
+  };
+}