@ecoma-io/archkeep 0.13.0

package/src/report/health-text.mjs

@@ -0,0 +1,123 @@
+/**
+ * The terminal report for the `health` command: per-metric verdicts with the
+ * number each was decided over, and the trend when a snapshot directory was
+ * given.
+ *
+ * Each metric renders as a verdict word (`ok` / `findings` /
+ * `not_applicable` / `unknown`) and — exactly when the metric MEASURED
+ * something — the number behind it. A metric whose verdict is
+ * `not_applicable` or `unknown` carries no number, because a number with no
+ * evidence would read as a measured zero (`../../../../AGENTS.md`: an empty
+ * result is a claim, not a shrug). The report states what each
+ * `not_applicable` and each `unknown` could not measure, so nothing reads as a
+ * silent gap.
+ *
+ * Determinism: the metric order is fixed, and the trend rows are the snapshots
+ * in byte-sort order (`../commands/history.mjs` orders them). This module
+ * decides nothing — a formatter that filtered would be a rule wearing a
+ * formatter's name (`../README.md`).
+ *
+ * Three pieces below are exported rather than private, because `report`
+ * renders the same metrics inside a larger document (`./report-text.mjs`) and
+ * a second copy of "how a metric renders" is how the two faces would come to
+ * disagree about the same verdict — the rule against stating a rule twice
+ * (`../../../../AGENTS.md`), applied to a format. The metric ORDER travels
+ * with them for the same reason: the order is part of the determinism claim,
+ * not a per-renderer taste.
+ */
+
+/**
+ * The metric line: the verdict word aligned to a column, the number exactly
+ * when the metric measured one, and the note that says what an unmeasured
+ * metric could not look at.
+ *
+ * `metric.value` is present ONLY for `ok`/`findings`
+ * (`../governance/metrics.mjs` fixes that), so this function never has to
+ * decide whether a number may be shown — it shows whatever the metric
+ * carries, and a `not_applicable`/`unknown` metric carries none.
+ *
+ * @param {string} label The metric's display name.
+ * @param {{verdict: string, value?: number, note?: string}} metric
+ * @returns {string}
+ */
+export function formatMetricLine(label, metric) {
+  const value = metric.value === undefined ? "" : `  ${metric.value}`;
+  const note = metric.note ? `  (${metric.note})` : "";
+  return `  ${metric.verdict.padEnd(16)}${label}${value}${note}`;
+}
+
+/**
+ * The fixed metric order: which key of the metrics object each line renders,
+ * and under what label. Fixed is the point — two runs over an unchanged tree
+ * produce byte-identical reports only if nothing decides this order at render
+ * time.
+ *
+ * @type {readonly {readonly key: string, readonly label: string}[]}
+ */
+export const HEALTH_METRIC_ORDER = Object.freeze([
+  Object.freeze({ key: "projects", label: "projects" }),
+  Object.freeze({ key: "edges", label: "edges" }),
+  Object.freeze({ key: "coverage", label: "coverage" }),
+  Object.freeze({ key: "violations", label: "violations" }),
+  Object.freeze({ key: "waiverSurface", label: "waiver surface" }),
+  Object.freeze({ key: "cycles", label: "cycles" }),
+  Object.freeze({ key: "edgeDensity", label: "edge density" }),
+  Object.freeze({ key: "debt", label: "debt rows" }),
+  Object.freeze({ key: "fitness", label: "intent fitness" }),
+]);
+
+/**
+ * The coverage headline: what the run inspected, and — when it could not
+ * inspect everything — that the metrics which needed the missing evidence read
+ * `unknown` rather than zero.
+ *
+ * `subject` names the command the headline belongs to, so `report` states its
+ * own coverage in the same words `health` does without a second copy of them.
+ *
+ * @param {{complete: boolean, imports: number, analyzedFiles: number,
+ *   projects: number, notAnalyzed: object[]}} coverage
+ * @param {string} [subject]
+ * @returns {string}
+ */
+export function formatCoverageHeadline(coverage, subject = "health") {
+  const inspected =
+    `${coverage.imports} import${coverage.imports === 1 ? "" : "s"} in ` +
+    `${coverage.analyzedFiles} file${coverage.analyzedFiles === 1 ? "" : "s"} across ` +
+    `${coverage.projects} project${coverage.projects === 1 ? "" : "s"}`;
+
+  if (coverage.complete) return `✔ ${subject} over complete coverage (${inspected})`;
+
+  const notAnalyzedCount = coverage.notAnalyzed.length;
+  return (
+    `✖ ${subject} over incomplete coverage — ${notAnalyzedCount} file${notAnalyzedCount === 1 ? "" : "s"} ` +
+    `could not be analyzed, so the metrics that needed them read unknown (${inspected})`
+  );
+}
+
+/**
+ * The whole health report.
+ *
+ * @param {{metrics: object, trends: object|null, coverage: object}} input
+ * @returns {string}
+ */
+export function formatHealthReport({ metrics, trends, coverage }) {
+  const sections = [formatCoverageHeadline(coverage, "health")];
+
+  for (const { key, label } of HEALTH_METRIC_ORDER) {
+    sections.push(formatMetricLine(label, metrics[key]));
+  }
+
+  if (trends) {
+    sections.push(
+      `trends  ${trends.snapshots.length} snapshot${trends.snapshots.length === 1 ? "" : "s"}`,
+    );
+    for (const snapshot of trends.snapshots) {
+      sections.push(
+        `  ${snapshot.name}  ${snapshot.projects} projects, ${snapshot.dependencies} edges`,
+      );
+    }
+    for (const note of trends.notes) sections.push(`  ${note}`);
+  }
+
+  return sections.join("\n");
+}

package/src/report/history-text.mjs

@@ -0,0 +1,204 @@
+/**
+ * The terminal report for the `history` command: snapshots in history order,
+ * each transition classified, and what the whole record can and cannot say.
+ *
+ * The summary line states what the record is a claim about — how many
+ * snapshots, how many transitions, and the shape of the history the directory
+ * actually holds. Counts end every section, so a reader is never left deciding
+ * whether an omission is content or silence.
+ *
+ * This module decides nothing. A formatter that filtered would be a rule
+ * wearing a formatter's name (`../README.md`).
+ */
+
+/**
+ * Neutralises control and terminal-escape sequences in a name or value before
+ * it is printed, so a crafted project/tag/edge name cannot inject escape
+ * sequences into a consumer's terminal (`SECURITY.md`). Real project names are
+ * ordinary characters and pass through untouched; only C0 control characters
+ * (which includes the ESC byte) and DEL become visible escapes.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+function sanitize(text) {
+  // eslint-disable-next-line no-control-regex
+  return String(text).replace(/[\x00-\x1F\x7F]/g, (c) => {
+    if (c === "\n") return "\\n";
+    if (c === "\t") return "\\t";
+    if (c === "\r") return "\\r";
+    return `\\x${c.charCodeAt(0).toString(16).padStart(2, "0")}`;
+  });
+}
+
+/**
+ * One project as a line, same shape as `graph-text.mjs`.
+ *
+ * @param {{name: string, root: string, tags: string[]}} project
+ * @returns {string}
+ */
+function formatProject(project) {
+  const tags =
+    project.tags.length > 0 ? ` [${project.tags.map((t) => sanitize(t)).join(", ")}]` : "";
+  return `  ${sanitize(project.name)}  ${sanitize(project.root)}${tags}`;
+}
+
+/**
+ * One edge as a line, same shape as `graph-text.mjs`.
+ *
+ * @param {{source: string, target: string, type: string}} edge
+ * @returns {string}
+ */
+function formatEdge(edge) {
+  return `  ${sanitize(edge.source)} → ${sanitize(edge.target)} (${sanitize(edge.type)})`;
+}
+
+/**
+ * One metadata change as a line, same shape as `diff-text.mjs`.
+ *
+ * @param {{field: string, baseline: *, head: *}} change
+ * @returns {string}
+ */
+function formatChange(change) {
+  const formatValue = (v) => {
+    if (Array.isArray(v)) return v.length > 0 ? v.map((x) => sanitize(x)).join(", ") : "(none)";
+    if (v === null || v === undefined) return "(none)";
+    return sanitize(String(v));
+  };
+  return `  ${change.field}  ${formatValue(change.baseline)} → ${formatValue(change.head)}`;
+}
+
+/**
+ * How the architecture actually changed between two snapshots: the added and
+ * removed projects and edges rendered as one line each. Changed projects
+ * render their changed fields beneath the project line, like `diff`.
+ *
+ * @param {object} changes The `computeDiff` payload.
+ * @returns {string[]}
+ */
+function formatChanges(changes) {
+  const lines = [];
+  if (changes.addedProjects.length > 0) {
+    const word = changes.addedProjects.length === 1 ? "project" : "projects";
+    lines.push(`+ ${changes.addedProjects.length} added ${word}`);
+    for (const project of changes.addedProjects) lines.push(formatProject(project));
+  }
+  if (changes.removedProjects.length > 0) {
+    const word = changes.removedProjects.length === 1 ? "project" : "projects";
+    lines.push(`- ${changes.removedProjects.length} removed ${word}`);
+    for (const project of changes.removedProjects) lines.push(formatProject(project));
+  }
+  if (changes.changedProjects.length > 0) {
+    const word = changes.changedProjects.length === 1 ? "project" : "projects";
+    lines.push(`~ ${changes.changedProjects.length} changed ${word}`);
+    for (const project of changes.changedProjects) {
+      lines.push(`  ${project.name}`);
+      for (const change of project.changes) lines.push(formatChange(change));
+    }
+  }
+  if (changes.addedEdges.length > 0) {
+    const word = changes.addedEdges.length === 1 ? "edge" : "edges";
+    lines.push(`+ ${changes.addedEdges.length} added ${word}`);
+    for (const edge of changes.addedEdges) lines.push(formatEdge(edge));
+  }
+  if (changes.removedEdges.length > 0) {
+    const word = changes.removedEdges.length === 1 ? "edge" : "edges";
+    lines.push(`- ${changes.removedEdges.length} removed ${word}`);
+    for (const edge of changes.removedEdges) lines.push(formatEdge(edge));
+  }
+  return lines;
+}
+
+/**
+ * Classifies one transition into the short "kind" a reader skims for.
+ *
+ * @param {{architectureChanged: boolean, codeDrift: boolean, policyChanged: boolean|null,
+ *   providerChanged: boolean}} transition
+ * @returns {string}
+ */
+function transitionKind(transition) {
+  if (transition.architectureChanged) return "architecture";
+  if (transition.providerChanged) return "provider";
+  if (transition.policyChanged === true) return "policy";
+  if (transition.codeDrift) return "code drift";
+  return "unchanged";
+}
+
+/**
+ * The whole history report.
+ *
+ * @param {{evolution: {dir: string, captured: object|null,
+ *   snapshots: {name: string, id: string}[],
+ *   transitions: {from: string, to: string, architectureChanged: boolean,
+ *     changes: object|null, policyChanged: boolean|null, providerChanged: boolean,
+ *     codeDrift: boolean, notes: string[]}[]}, coverage: object}} input
+ * @returns {string}
+ */
+export function formatHistoryReport({ evolution, coverage }) {
+  const sections = [];
+
+  const transitionWord = evolution.transitions.length === 1 ? "transition" : "transitions";
+  const snapshotWord = evolution.snapshots.length === 1 ? "snapshot" : "snapshots";
+  const inspected = `${coverage.imports} import${
+    coverage.imports === 1 ? "" : "s"
+  } in ${coverage.analyzedFiles} file${
+    coverage.analyzedFiles === 1 ? "" : "s"
+  } across ${coverage.projects} project${coverage.projects === 1 ? "" : "s"}`;
+
+  sections.push(`history  ${evolution.dir}`);
+  sections.push(
+    `${evolution.snapshots.length} ${snapshotWord}, ${evolution.transitions.length} ${transitionWord} (${inspected})`,
+  );
+
+  if (evolution.captured) {
+    sections.push(
+      evolution.captured.duplicate
+        ? `capture  ${evolution.captured.name} — already the last snapshot, no new file written`
+        : `capture  ${evolution.captured.name} written`,
+    );
+  }
+
+  for (const [i, snapshot] of evolution.snapshots.entries()) {
+    sections.push(`${i}  ${snapshot.name}  ${snapshot.id.slice(0, 8)}`);
+  }
+
+  // The footer counts true architectural change only — a transition classified
+  // as policy or provider is a change to the record's interpretation, not to
+  // the architecture, so a policy-only history must not read as "N transitions
+  // recorded an architectural change".
+  let changed = 0;
+  for (const transition of evolution.transitions) {
+    if (transition.architectureChanged) changed += 1;
+    const kind = transitionKind(transition);
+    sections.push(`~ ${transition.from} → ${transition.to}  (${kind})`);
+    if (transition.changes) {
+      for (const line of formatChanges(transition.changes)) sections.push(`  ${line}`);
+    }
+    for (const note of transition.notes) {
+      sections.push(`  ${note}`);
+    }
+  }
+
+  if (evolution.transitions.length === 0) {
+    // A single snapshot is a claim about a history of length one — it says so
+    // rather than reporting "no changes", which would be ambiguous.
+    sections.push(
+      "✔ one snapshot, no transitions yet — capture again after an architectural change",
+    );
+  } else if (changed === 0) {
+    const anySignal = evolution.transitions.some(
+      (t) => t.policyChanged === true || t.providerChanged || t.codeDrift,
+    );
+    sections.push(
+      anySignal
+        ? "✔ no architectural change recorded across the snapshots (only policy, provider, or drift signals)"
+        : "✔ no architectural change recorded across the snapshots",
+    );
+  } else {
+    sections.push(
+      `${changed} transition${changed === 1 ? "" : "s"} recorded an architectural change`,
+    );
+  }
+
+  return sections.join("\n");
+}

package/src/report/impact-text.mjs

@@ -0,0 +1,128 @@
+/**
+ * The terminal report for the `impact` command: reverse reachability from the
+ * project graph.
+ *
+ * Each dependent project is listed as a single line, grouped under the target
+ * project. A project with no dependents renders the header and a "0" count
+ * rather than an omitted section, because "nothing depends on this" and "the
+ * renderer forgot" look identical otherwise — the same reasoning as
+ * `./graph-text.mjs`'s `(no dependencies)` line.
+ *
+ * When the impact carries a `constraintImpact` field (computed when a boundary
+ * config was provided), a constraint-context section follows the dependent
+ * listing: each dependent is shown with a ✔ or ✖ marker, the constraint rows
+ * that govern its edge, and any violations. When there are no dependents, the
+ * section states that explicitly. This section is absent when no config was
+ * given, so an impact without `--config` is unchanged from its prior output.
+ *
+ * The coverage claim sits ABOVE the listing, not below it, so the reader knows
+ * whether the result is complete before reading any entry — an incomplete
+ * impact set printed in full would have the "this may under-represent" warning
+ * buried at the bottom.
+ *
+ * This module decides nothing. A formatter that filtered would be a rule
+ * wearing a formatter's name (`../README.md`).
+ */
+
+/**
+ * The constraint context for one dependent, as text.
+ *
+ * @param {{project: string, edges: object[], constraintRows: object[], violations: object[]}} entry
+ * @returns {string}
+ */
+function formatConstraintEntry(entry) {
+  const lines = [];
+
+  if (entry.constraintRows.length === 0) {
+    lines.push(`    (no matching constraint rows — untagged or unmatched tags)`);
+  } else {
+    for (const row of entry.constraintRows) {
+      const tag = row.sourceTag ?? row.allSourceTags?.join("+") ?? "?";
+      const parts = [];
+      if (row.onlyDependOnLibsWithTags)
+        parts.push(`only [${row.onlyDependOnLibsWithTags.join(", ")}]`);
+      if (row.notDependOnLibsWithTags)
+        parts.push(`not [${row.notDependOnLibsWithTags.join(", ")}]`);
+      lines.push(`    [${tag}] ${parts.join(", ")}`);
+      if (row.description) lines.push(`      description  ${row.description}`);
+      if (row.remediation) lines.push(`      remediation   ${row.remediation}`);
+    }
+  }
+
+  for (const v of entry.violations) {
+    lines.push(`    ✖ ${v.source} → ${v.target}  ${v.messageId}`);
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * The whole impact report.
+ *
+ * @param {{impact: {project: string, direct: string[], transitive: string[],
+ *   dependents: string[], constraintImpact?: object[]}, coverage: object}} input
+ * @returns {string}
+ */
+export function formatImpactReport({ impact, coverage }) {
+  const sections = [];
+
+  // Coverage claim goes FIRST — above the listing — so the reader knows
+  // whether the impact set is complete before reading any entry.
+  const inspected =
+    `${coverage.imports} import${coverage.imports === 1 ? "" : "s"} in ` +
+    `${coverage.analyzedFiles} file${coverage.analyzedFiles === 1 ? "" : "s"} across ` +
+    `${coverage.projects} project${coverage.projects === 1 ? "" : "s"}`;
+
+  if (coverage.complete) {
+    sections.push(`✔ impact complete (${inspected})`);
+  } else {
+    const notAnalyzedCount = coverage.notAnalyzed.length;
+    sections.push(
+      `✖ impact incomplete — ${notAnalyzedCount} file${notAnalyzedCount === 1 ? "" : "s"} ` +
+        `could not be analyzed, so this impact set may under-represent the real architecture (${inspected})`,
+    );
+  }
+
+  // Header names the target project
+  sections.push(`Impact of ${impact.project}`);
+
+  // List dependents — each on its own line
+  if (impact.dependents.length > 0) {
+    for (const name of impact.dependents) {
+      sections.push(`  ${name}`);
+    }
+  }
+
+  // Constraint-impact section: when the boundary config was provided, show
+  // which constraint rows govern each dependent's edge and whether it violates.
+  // The section appears whenever `constraintImpact` is present — even when
+  // empty (no dependents) — so a reader can always tell "config provided, no
+  // dependents to judge" from "no config".
+  if (impact.constraintImpact) {
+    sections.push("Constraint context");
+    if (impact.constraintImpact.length === 0) {
+      sections.push("  (no dependents to judge against constraint table)");
+    }
+    for (const entry of impact.constraintImpact) {
+      const hasViolations = entry.violations.length > 0;
+      const marker = hasViolations ? "✖" : "✔";
+      sections.push(`  ${marker} ${entry.project}`);
+      sections.push(formatConstraintEntry(entry));
+    }
+  }
+
+  // Summary line: total, with direct and transitive broken out.
+  // A project with 0 dependents states "0 project(s) depend on" — an
+  // explicit claim, never silence.
+  const total = impact.dependents.length;
+  const directCount = impact.direct.length;
+  const transitiveCount = impact.transitive.length;
+
+  const projectWord = total === 1 ? "project" : "projects";
+  const verbWord = total === 1 ? "depends" : "depend";
+  sections.push(
+    `${total} ${projectWord} ${verbWord} on ${impact.project} (direct: ${directCount}, transitive: ${transitiveCount})`,
+  );
+
+  return sections.join("\n");
+}

package/src/report/json.mjs

@@ -0,0 +1,173 @@
+/**
+ * The versioned JSON envelope every command's `--format json` wraps its
+ * result in — one wrapper, six commands, so a consumer writes one parser
+ * rather than one per command. `../../../../docs/reference/json-output.md` is the
+ * published contract this module builds; this file is where the contract's
+ * three consistency rules are enforced in code rather than left to a
+ * docs page a later command author might not read.
+ *
+ * **This module knows no command's payload.** `jsonEnvelope` takes `result` as
+ * an opaque object and writes it through unchanged — `../../cli.mjs`'s `check`
+ * builds its own `result.violations`/`result.goWork`/`result.tsconfigPaths`,
+ * and a later command builds its own. Payload shape lives with the command
+ * that produces it, which is what keeps this file untouched by every command
+ * after the first (`../commands/README.md` states the same split one layer
+ * down).
+ *
+ * The three assertions below are the empty-result invariant
+ * (`../../../../AGENTS.md`) in executable form, not merely documented: a caller
+ * that got one of them wrong would otherwise ship a JSON file claiming a clean
+ * run over a tree this tool never finished reading, and nothing downstream
+ * would ever see the mistake. They throw rather than degrade on purpose — a
+ * mismatch here is a bug in the command that built the envelope, not a fact
+ * about the workspace being judged, so it gets a programming error rather than
+ * a diagnostic.
+ *
+ * The optional `decision` field rides the same posture. It carries the
+ * canonical 4-state verdict (`../governance/verdict.mjs`) that every
+ * governance capability emits and consumes, and its `verdict` must agree
+ * with the envelope's `status` the same way `status` and `exitCode` must:
+ * `"ok"` implies `"pass"`, `"findings"` implies `"fail"`, `"no-verdict"`
+ * implies `"unknown"`. A decision that contradicts its status would make one
+ * of them a lie — the exact class of disagreement this module refuses to
+ * ship. The same refusal covers the invariant the uncertain verdict carries:
+ * an `"unknown"` decision must name the reason no verdict was reached, so a
+ * hand-built decision cannot slip a reason-less "no verdict" past the last
+ * boundary it crosses. The field is OPTIONAL (absent on every envelope that
+ * does not opt in), which is what keeps SCHEMA_VERSION at 2: additive,
+ * byte-compatible with every consumer that reads the envelope today.
+ */
+import { verdictForStatus } from "../governance/verdict.mjs";
+import { createRequire } from "node:module";
+
+const require = createRequire(import.meta.url);
+/** @type {{name: string, version: string}} */
+const { name: TOOL_NAME, version: TOOL_VERSION } = require("../../package.json");
+
+/**
+ * The schema version this build writes. An integer, per
+ * `docs/reference/json-output.md`'s stability promise: it only moves for a
+ * breaking change to the envelope, and a consumer that reads a
+ * `schemaVersion` it does not recognise should refuse to parse the rest of
+ * the envelope rather than guess — an unrecognised version is a caller
+ * reading a contract from the future, not a workspace fact. Nothing in this
+ * package reads its own envelope back, so that refusal is advice to the
+ * consumer, not a mechanism enforced here.
+ */
+export const SCHEMA_VERSION = 2;
+
+/** The one `status`↔`exitCode` mapping every command's envelope must agree with. */
+const EXIT_CODE_FOR_STATUS = Object.freeze({ ok: 0, findings: 1, "no-verdict": 3 });
+
+/**
+ * Builds the envelope, asserting the three invariants that keep it from ever
+ * claiming more than a run actually established.
+ *
+ * @param {{command: string, context: {root: string, provider: "nx"|"native"|"moon", marker: string,
+ *   provenance?: {commit: string, remote: string|null, dirty: boolean}|null},
+ *   status: "ok"|"findings"|"no-verdict", exitCode: 0|1|3,
+ *   coverage: {complete: boolean, projects: number, analyzedFiles: number, imports: number,
+ *     notAnalyzed: object[], blindSpots: object[], notes: string[], coverageGaps?: object[]},
+ *   result: object,
+ *   decision?: {verdict: string, reason?: string, notApplicableReason?: string,
+ *     sampleTime?: string}}} run
+ * @returns {object} The envelope `docs/reference/json-output.md` documents.
+ * @throws {Error} when `status` claims `"ok"` over incomplete coverage, when
+ *   `status` and `exitCode` disagree, when `coverage.complete` disagrees
+ *   with whether `coverage.notAnalyzed` is empty, or when the optional
+ *   `decision.verdict` contradicts the envelope's `status`.
+ */
+export function jsonEnvelope({ command, context, status, exitCode, coverage, result, decision }) {
+  if (status === "ok" && coverage.complete !== true) {
+    throw new Error(
+      `archkeep: refusing to build a JSON envelope claiming status "ok" over incomplete coverage ` +
+        `(coverage.complete: false) — a caller cannot report a clean run over a tree it could not ` +
+        `fully read. This is a bug in the command that built this envelope, not a fact about the ` +
+        `workspace being judged.`,
+    );
+  }
+  if (EXIT_CODE_FOR_STATUS[status] !== exitCode) {
+    throw new Error(
+      `archkeep: refusing to build a JSON envelope where status "${status}" and exitCode ${exitCode} ` +
+        `disagree — status "${status}" must carry exitCode ${EXIT_CODE_FOR_STATUS[status]}. A ` +
+        `consumer reading a file written by --output has only these two fields to trust; letting ` +
+        `them disagree would make one of them a lie.`,
+    );
+  }
+  if (coverage.complete !== (coverage.notAnalyzed.length === 0)) {
+    throw new Error(
+      `archkeep: refusing to build a JSON envelope where coverage.complete (${coverage.complete}) ` +
+        `disagrees with coverage.notAnalyzed (${coverage.notAnalyzed.length} entr${coverage.notAnalyzed.length === 1 ? "y" : "ies"}) ` +
+        `— the two must always agree, or a reader checking only one of them could mistake a partial ` +
+        `run for a complete one.`,
+    );
+  }
+  // A bare `null` decision is the same programming error as a hand-built
+  // decision that contradicts its status: refuse it with the named message
+  // rather than crash on `decision.verdict` with a raw TypeError.
+  if (decision !== undefined && (decision === null || typeof decision !== "object")) {
+    throw new Error(
+      `archkeep: refusing to build a JSON envelope where decision is ${decision === null ? "null" : `a ${typeof decision}`} ` +
+        `rather than an object — a decision must carry a verdict that agrees with its status. ` +
+        `This is a bug in the command that built the envelope.`,
+    );
+  }
+  if (decision != null) {
+    const implied = verdictForStatus(status);
+    if (decision.verdict !== implied) {
+      throw new Error(
+        `archkeep: refusing to build a JSON envelope where decision.verdict "${decision.verdict}" ` +
+          `contradicts status "${status}" — status implies ${implied}, and a ` +
+          `decision that disagrees with its own status would make one of the two a lie. ` +
+          `This is a bug in the command that built the envelope.`,
+      );
+    }
+    // I3, enforced again at this boundary — `src/governance/evidence.mjs`
+    // already guarantees it for the engine path, but a hand-built decision
+    // would otherwise ship an "unknown" without the reason I3 requires and
+    // only this boundary would ever see the mistake. I2 (findings on "fail")
+    // gets no latch here for the same reason I4 gets none: the other
+    // invariants already pin every route a "fail" can take — `verdictForStatus`
+    // only returns "fail" for a "findings" status, and this module knows no
+    // command's payload, so counting findings would mean reaching into
+    // `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) {
+      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. ` +
+          `This is a bug in the command that built the envelope.`,
+      );
+    }
+  }
+
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    tool: { name: TOOL_NAME, version: TOOL_VERSION },
+    command,
+    workspace: {
+      root: context.root,
+      provider: context.provider,
+      marker: context.marker,
+      provenance: context.provenance ?? null,
+    },
+    status,
+    exitCode,
+    coverage,
+    result,
+    ...(decision == null ? {} : { decision }),
+  };
+}
+
+/**
+ * The envelope as bytes: two-space indent and a trailing newline, so a file
+ * written by `--output` reads the same as every other file this tool writes
+ * and diffs cleanly in a pull request.
+ *
+ * @param {object} envelope From `jsonEnvelope`.
+ * @returns {string}
+ */
+export function renderJson(envelope) {
+  return `${JSON.stringify(envelope, null, 2)}\n`;
+}