@ecoma-io/archkeep 0.13.0 → 0.15.0

package/src/commands/delta.mjs

@@ -0,0 +1,606 @@
+/**
+ * The `delta` command: two evidence sets — a captured baseline and the current
+ * tree — re-judged under ONE boundary config and ONE shared reference instant,
+ * then classified `introduced` | `resolved` | `unchanged` | `unknown`.
+ *
+ * Two modes, one module:
+ *
+ * - **capture** (`captureDelta`) — run at a base checkout, writes the evidence
+ *   snapshot `./delta-snapshot.mjs` defines: raw import-site records, the
+ *   graph they were collected against, coverage, provenance, and the policy
+ *   fingerprint. Evidence, never verdicts — the header of that module owns
+ *   the argument.
+ * - **compare** (`deltaCommand`) — run at head, loads the baseline and
+ *   re-judges BOTH sides through `../rules/index.mjs`'s engine under the
+ *   CURRENT config, so a policy edit between capture and now cannot fabricate
+ *   an introduced/resolved pair; only the code can move a classification
+ *   (`./delta-classify.mjs`).
+ *
+ * Unlike `diff` — which compares two GRAPH snapshots edge by edge and never
+ * exits 1 — `delta` is a gate: a non-waived introduced violation is a finding
+ * (exit 1), which is the whole point of carrying re-judgeable evidence rather
+ * than a graph. That made `delta` the third verb whose verdict carries
+ * exit 1, beside `check` and `fitness`; `./change.mjs` later became the
+ * fourth, over a different question — declared intent versus observed delta.
+ *
+ * Refusals (each a throw, exit 3 upstream — a delta that could not honestly
+ * classify must never read as "no change"):
+ * - a baseline that cannot be read, parsed, or holds a foreign schemaVersion
+ *   (`./delta-snapshot.mjs`'s loader owns those);
+ * - a provider mismatch between baseline and this run (`providerMismatch`) —
+ *   a THROW here where `diff` settles for a note, because violation IDENTITY
+ *   across two different project models is not trustworthy: the same tree
+ *   attributed to different projects would classify a rename as an
+ *   introduced/resolved pair the code does not contain;
+ * - incomplete CURRENT coverage — a delta over a half-analyzed head is not a
+ *   verdict, the same posture `check` takes on `unchecked` files;
+ * - an Nx workspace with polyglot manifests but no plugin registration — the
+ *   same silently-under-representing graph `graph`/`diff` refuse.
+ *
+ * What is deliberately NOT a refusal: a policy-fingerprint mismatch between
+ * baseline and current. Both sides are re-judged under the current law — that
+ * is the design's point — so the mismatch becomes a loud coverage note
+ * instead. Dirty base provenance and a dirty head are notes too: weaker
+ * evidence, not unreadable evidence.
+ *
+ * This module computes and returns; `../../cli.mjs`'s `runDelta` owns argv,
+ * output destination and the process exit code (`./README.md`).
+ */
+import { createRequire } from "node:module";
+
+import { isWholeFileFailure } from "../analysis/source-util.mjs";
+import { stripTrailingSlashes } from "../path-util.mjs";
+import { referenceTime } from "../governance/clock.mjs";
+import { jsonEnvelope, renderJson } from "../report/json.mjs";
+import { buildDecision } from "../report/evidence.mjs";
+import { formatDeltaReport } from "../report/delta-text.mjs";
+import { formatDeltaSarif } from "../report/sarif.mjs";
+import { evaluateRun } from "../rules/index.mjs";
+import { customRulesForDelta, declaresCustomRules } from "./custom-rules.mjs";
+import { classifyCustomFindings, classifyDelta } from "./delta-classify.mjs";
+import {
+  buildEvidenceSnapshot,
+  providerMismatch,
+  readEvidenceSnapshot,
+  serializeEvidenceSnapshot,
+} from "./delta-snapshot.mjs";
+import { computePolicyFingerprint } from "./graph.mjs";
+import { resolveProvenance } from "./provenance.mjs";
+import { compareSnapshotMetadata } from "./snapshot-meta.mjs";
+
+const require = createRequire(import.meta.url);
+/** @type {{name: string, version: string}} */
+const { name: TOOL_NAME, version: TOOL_VERSION } = require("../../package.json");
+
+/**
+ * Refuses the two head states no delta side may be built over, shared by both
+ * modes: the unregistered-plugin graph and incomplete analysis coverage.
+ *
+ * Exported since `change` arrived because that command builds its comparison
+ * over the same two head states — a graph that under-represents the tree and
+ * an analysis with holes would reconcile a declaration against architecture
+ * nobody observed — and a second copy of the refusal is where the two
+ * commands would drift into answering "may this head be judged?" differently.
+ *
+ * @param {object} commandContext From `resolveCommandContext`.
+ * @param {string} activity Which mode is refusing, for the message.
+ * @throws {Error} on either condition.
+ */
+export function refuseUnjudgeableHead(commandContext, activity) {
+  const { provider, pluginGap } = commandContext;
+  if (provider === "nx" && !pluginGap.registered && pluginGap.manifests.length > 0) {
+    throw new Error(
+      `archkeep: refusing to ${activity} for an Nx workspace where this plugin is not ` +
+        `registered but polyglot manifests exist under project roots ` +
+        `(${pluginGap.manifests.join(", ")}). The graph would carry no polyglot edges, so the ` +
+        `evidence would silently under-represent the real architecture. Register the plugin in ` +
+        `nx.json: "plugins": [{ "plugin": "@ecoma-io/archkeep/nx" }], or remove the polyglot ` +
+        `manifests if they are not in use.`,
+    );
+  }
+  const notAnalyzed = commandContext.analysis.failures.filter(isWholeFileFailure);
+  if (notAnalyzed.length > 0) {
+    throw new Error(
+      `archkeep: cannot ${activity} — ${notAnalyzed.length} file` +
+        `${notAnalyzed.length === 1 ? "" : "s"} could not be analyzed, so the evidence would ` +
+        `miss violations living there and a later classification would misread the gap as a ` +
+        `code change. Fix the unanalyzed files and re-run.`,
+    );
+  }
+}
+
+/**
+ * Captures the current tree as a delta baseline: the evidence snapshot
+ * serialized, ready for a future `delta <base.json>` run to consume.
+ *
+ * @param {object} commandContext From `resolveCommandContext`.
+ * @param {{config: object|null}} io The resolved boundary config — required,
+ *   because the snapshot's policy fingerprint is what lets a later run say
+ *   loudly that the law moved.
+ * @returns {{snapshot: object, text: string}}
+ * @throws {Error} on an unjudgeable head (above) or a run with no boundary
+ *   law — a baseline with no policy identity could never disclose a law
+ *   change, which is the silent direction.
+ */
+export function captureDelta(commandContext, { config }) {
+  refuseUnjudgeableHead(commandContext, "capture a delta baseline");
+  if (!config) {
+    throw new Error(
+      "archkeep: cannot capture a delta baseline without a boundary config — the snapshot " +
+        "records the policy fingerprint so a later delta run can say loudly when the law moved, " +
+        "and a workspace that resolves no law leaves that claim unmakeable.",
+    );
+  }
+  const { root, provider, graph, analysis } = commandContext;
+  const snapshot = buildEvidenceSnapshot({
+    // The two optional custom-rule blocks, stored exactly when the capturing
+    // policy declares rules — an undeclaring workspace's snapshot stays
+    // byte-identical (`./delta-snapshot.mjs`, the optional-blocks section).
+    ...(declaresCustomRules(config)
+      ? { customRules: config.customRules, owned: commandContext.owned }
+      : {}),
+    tool: { name: TOOL_NAME, version: TOOL_VERSION },
+    provenance: resolveProvenance(root),
+    provider,
+    policyFingerprint: computePolicyFingerprint(config),
+    coverage: {
+      // `refuseUnjudgeableHead` already threw on any whole-file failure, so
+      // the capture-side claim is honestly complete.
+      complete: true,
+      analyzedFiles: analysis.analyzed,
+      notAnalyzed: [],
+      blindSpots: analysis.failures
+        .filter((failure) => !isWholeFileFailure(failure))
+        .map(({ sourceFile, line, column, reason }) => ({
+          file: sourceFile,
+          line,
+          column,
+          reason,
+        })),
+    },
+    graph,
+    records: analysis.imports,
+  });
+  return { snapshot, text: serializeEvidenceSnapshot(snapshot) };
+}
+
+/**
+ * Rebuilds an engine-consumable `ProjectGraph` from a snapshot's stored graph.
+ *
+ * The snapshot stores what `graph --format json` publishes — a `projects`
+ * ARRAY and a flat `dependencies` array — while `../rules/index.mjs`'s
+ * `evaluate()` consumes Nx's shape: a `nodes` MAP keyed by name (each with
+ * `type` and `data.{root, tags, targets?}`) plus a source-keyed `dependencies`
+ * map. The conversion is exact where the snapshot kept the fact:
+ *
+ * - `name`/`root`/`type`/`tags` map straight back onto `data`;
+ * - the three rule-relevant extras the snapshot re-attached (`mfeRemote`,
+ *   `entryPoints`, `declaredPackages`) go back onto `data` only when present —
+ *   absence stays absence, because `evaluate()` treats an absent field as
+ *   "declares none" and inventing an empty value would be a second copy of
+ *   that answer (`./delta-snapshot.mjs`);
+ * - `targets` was stored as the NAMES alone, so each becomes `{}` in the
+ *   rebuilt `data.targets` map. That preserves both reads the engine makes of
+ *   it — `Object.keys` in the buildTargets guard, and
+ *   `../rules/topology.mjs`'s `hasBuildExecutor`, whose
+ *   `targets[t].executor !== ""` is true for `{}` — so a declared target
+ *   stays a declared target; the executor STRING itself is the one fact the
+ *   snapshot never held;
+ * - `workspaceLayout` and `exemptedFiles` ride the graph object exactly as
+ *   the provider carried them, because `createContext` reads both off it.
+ *
+ * Every project name gets a `dependencies` entry — an empty array for a
+ * project with no outgoing edge — matching the shape every provider emits.
+ *
+ * A mis-shaped rebuild here is the silent direction in miniature: a base
+ * graph the engine reads as empty yields zero base violations, which
+ * classifies every standing violation as freshly introduced (loud but wrong)
+ * or — with the sides swapped — masks base violations entirely. The test
+ * beside this module holds the non-empty base-side re-judgment.
+ *
+ * @param {{projects: object[], dependencies: {source: string, target: string,
+ *   type: string}[], workspaceLayout?: object, exemptedFiles?: string[]}} storedGraph
+ *   A validated snapshot's `graph` section (`parseEvidenceSnapshot`).
+ * @returns {object} A graph `evaluate()` consumes.
+ */
+export function evidenceGraphToProjectGraph(storedGraph) {
+  /** @type {Record<string, object>} */
+  const nodes = {};
+  /** @type {Record<string, object[]>} */
+  const dependencies = {};
+  for (const project of storedGraph.projects) {
+    /** @type {Record<string, unknown>} */
+    const data = { root: project.root, tags: project.tags ?? [] };
+    if (Array.isArray(project.targets)) {
+      data.targets = Object.fromEntries(project.targets.map((target) => [target, {}]));
+    }
+    if (project.mfeRemote !== undefined) data.mfeRemote = project.mfeRemote;
+    if (Array.isArray(project.entryPoints)) data.entryPoints = project.entryPoints;
+    if (Array.isArray(project.declaredPackages)) data.declaredPackages = project.declaredPackages;
+    nodes[project.name] = { name: project.name, type: project.type, data };
+    dependencies[project.name] = [];
+  }
+  for (const edge of storedGraph.dependencies) {
+    if (!Array.isArray(dependencies[edge.source])) dependencies[edge.source] = [];
+    dependencies[edge.source].push({ source: edge.source, target: edge.target, type: edge.type });
+  }
+  /** @type {Record<string, unknown>} */
+  const graph = { nodes, dependencies };
+  if (storedGraph.workspaceLayout !== undefined)
+    graph.workspaceLayout = storedGraph.workspaceLayout;
+  if (Array.isArray(storedGraph.exemptedFiles)) graph.exemptedFiles = storedGraph.exemptedFiles;
+  return graph;
+}
+
+/**
+ * A longest-root-prefix attributor for `classifyUnresolvableRecords`: the
+ * record's file is matched against project roots, head's first (the current
+ * model is the one both sides are judged under), then any baseline root the
+ * head does not already claim — so a base-side record living in a directory
+ * the head no longer has still attributes to the project that owned it.
+ *
+ * Exported for `./change.mjs`, which classifies the same two evidence sets
+ * through `./delta-classify.mjs` and must attribute unresolvable records the
+ * same way a delta does — a second attribution rule beside this one is how
+ * the two commands would disagree about which project carried a site.
+ *
+ * @param {object} headGraph The current run's graph (`nodes` map).
+ * @param {object[]} baselineProjects The snapshot's stored project rows.
+ * @returns {(record: object) => string|null}
+ */
+export function sourceProjectAttributor(headGraph, baselineProjects) {
+  /** @type {Map<string, string>} root → project name, head winning ties. */
+  const byRoot = new Map();
+  for (const node of Object.values(headGraph.nodes ?? {})) {
+    const root = typeof node?.data?.root === "string" ? node.data.root : null;
+    if (root !== null && !byRoot.has(root)) byRoot.set(root, node.name);
+  }
+  for (const project of baselineProjects) {
+    if (typeof project.root === "string" && !byRoot.has(project.root)) {
+      byRoot.set(project.root, project.name);
+    }
+  }
+  const entries = [...byRoot.entries()]
+    .map(([root, name]) => [stripTrailingSlashes(root), name])
+    .sort((a, b) => b[0].length - a[0].length);
+  return (record) => {
+    const file = record?.sourceFile;
+    if (typeof file !== "string") return null;
+    for (const [root, name] of entries) {
+      if (root === "" || root === "." || file === root || file.startsWith(`${root}/`)) {
+        return /** @type {string} */ (name);
+      }
+    }
+    return null;
+  };
+}
+
+/** First eight hex characters of a fingerprint, for prose that names one. */
+const short = (fingerprint) =>
+  typeof fingerprint === "string" ? fingerprint.slice(0, 8) : String(fingerprint);
+
+/**
+ * Runs the `delta` compare mode: loads the baseline, re-judges both sides
+ * under the current law and one shared instant, classifies, and folds the
+ * classification into the verdict.
+ *
+ * The exit fold — the whole point of the command:
+ * - any `introduced` violation NOT covered by the current waiver table →
+ *   `findings` (exit 1);
+ * - else any `unknown` entry, in either the violations or the unresolvable
+ *   buckets → `no-verdict` (exit 3): an item the classifier could not place
+ *   is a question this run could not answer, never a clean delta;
+ * - else `ok` (exit 0). Waived-introduced entries are REPORTED — waiving is
+ *   a tracked acceptance, not a fix — but do not fail the gate, which is what
+ *   a waiver is for.
+ *
+ * Custom-rule (wasm) findings join the classification when either side
+ * declares them: `./custom-rules.mjs`'s `customRulesForDelta` judges every
+ * head-declared rule over both evidence sets, `./delta-classify.mjs`'s
+ * `classifyCustomFindings` buckets the findings, and the result rides the
+ * envelope as `result.customRules` — a block that is ABSENT (never `null`)
+ * when neither side declares any, so an undeclaring workspace's envelope
+ * stays byte-identical. An introduced custom finding gates exactly as an
+ * introduced violation does, with no waiver lane by construction
+ * (suppressions key on a `messageId` custom findings do not have); an
+ * unclassifiable one is a no-verdict. This is also why the function is async:
+ * the wasm host is.
+ *
+ * @param {string} baselinePath Absolute path to the evidence snapshot.
+ * @param {object} commandContext From `resolveCommandContext`.
+ * @param {{config: object|null, readBaseline?: (path: string) => object,
+ *   now?: string, readArtifact?: (artifact: string) => Uint8Array|null,
+ *   timeoutMs?: number}} io The resolved boundary config (required
+ *   — both sides are re-judged under it), an injectable baseline reader, the
+ *   one shared reference instant (defaults to the shared governance clock),
+ *   and the custom-rule host's two injectable seams, passed through to
+ *   `customRulesForDelta`.
+ * @returns {Promise<{status: "ok"|"findings"|"no-verdict", delta: object,
+ *   coverage: object, report: {text: string, json: string, sarif: string}}>}
+ * @throws {Error} on every refusal the module header lists, and on a
+ *   custom-rule LOAD failure (`./custom-rules.mjs` argues the split).
+ */
+export async function deltaCommand(
+  baselinePath,
+  commandContext,
+  { config, readBaseline = readEvidenceSnapshot, now = referenceTime(), ...customRuleIo },
+) {
+  const { root, provider, marker, graph, analysis } = commandContext;
+
+  refuseUnjudgeableHead(commandContext, "compute a delta");
+  if (!config) {
+    throw new Error(
+      "archkeep: cannot compute a delta without a boundary config — both sides are re-judged " +
+        "under the current law, and a run that resolves no law has nothing to judge either side " +
+        "against.",
+    );
+  }
+
+  const baseline = readBaseline(baselinePath);
+
+  // Provider mismatch is a REFUSAL here, deliberately stricter than `diff`'s
+  // note: `diff` describes structural difference, where a provider artefact is
+  // a caveat; `delta` asserts violation identity across the two sides, and an
+  // identity computed over two different project models is not evidence.
+  const mismatch = providerMismatch(baseline.provider, provider);
+  if (mismatch !== null) {
+    throw new Error(
+      `archkeep: refusing to compute a delta — ${mismatch}. Re-capture the baseline under ` +
+        `this run's provider.`,
+    );
+  }
+
+  const baseGraph = evidenceGraphToProjectGraph(baseline.graph);
+  const configWithNow = { ...config, now };
+  // Both sides RAW (pre-suppression), through the same walk `waivers` reads:
+  // suppression must annotate the classification, never shrink either side —
+  // a suppressed-then-regressed violation has to stay visible
+  // (`./delta-classify.mjs`).
+  const baseViolations = evaluateRun(baseline.records, baseGraph, configWithNow).rawViolations;
+  const headViolations = evaluateRun(analysis.imports, graph, configWithNow).rawViolations;
+
+  const classification = classifyDelta({
+    baseViolations,
+    headViolations,
+    baseRecords: baseline.records,
+    headRecords: analysis.imports,
+    suppressions: config.suppressions ?? [],
+    now,
+    sourceProjectOf: sourceProjectAttributor(graph, baseline.graph.projects),
+  });
+
+  const headProvenance = resolveProvenance(root);
+  const headFingerprint = computePolicyFingerprint(config);
+  const meta = compareSnapshotMetadata({
+    baselineProvider: baseline.provider,
+    headProvider: provider,
+    baselineProvenance: baseline.provenance,
+    headProvenance,
+    baselineFingerprint: baseline.policyFingerprint,
+    headFingerprint,
+  });
+
+  const notes = [];
+  if (meta.policyChanged === true) {
+    notes.push(
+      `the boundary law changed since capture (baseline ${short(baseline.policyFingerprint)}…, ` +
+        `current ${short(headFingerprint)}…) — classifications reflect the current law applied ` +
+        `to both sides, so a violation a policy edit created or retired classifies as unchanged, ` +
+        `not as introduced or resolved`,
+    );
+  }
+  if (meta.crossRepo) {
+    notes.push(
+      `baseline provenance remote (${baseline.provenance.remote}) differs from head provenance ` +
+        `remote (${headProvenance?.remote}) — the delta may be across unrelated repositories ` +
+        `rather than two revisions of the same one`,
+    );
+  } else if (meta.provenanceOneSided) {
+    const side = baseline.provenance ? "head" : "baseline";
+    notes.push(
+      `the ${side} carries no provenance — the delta cannot verify it compares two revisions ` +
+        `of the same repository`,
+    );
+  }
+  if (meta.dirtyBaseline) {
+    notes.push(
+      "the baseline was captured from a dirty working tree — its evidence is not a reproducible " +
+        "claim about the commit it names",
+    );
+  }
+  if (meta.dirtyHead) {
+    notes.push(
+      "this run's working tree is dirty — the head side describes uncommitted state, not the " +
+        "commit HEAD names",
+    );
+  }
+
+  // The custom-rule half, present exactly when a side declares rules: judged
+  // two-sided where the law is identical, `unknown` with a mandatory reason
+  // everywhere else (`./custom-rules.mjs`'s `customRulesForDelta` owns the
+  // routes). `null` when NEITHER side declares any — the envelope block and
+  // the summary key are then absent, and an undeclaring workspace's envelope
+  // stays byte-identical (`../../../../AGENTS.md`, "a change to what is
+  // reported on an unchanged workspace is a breaking change").
+  /** @type {{judged: object[], skipped: object[], removed: string[],
+   *   findings: {introduced: object[], resolved: object[], unchanged: object[],
+   *   unknown: object[]}}|null} */
+  let custom = null;
+  // The head-declared finding catalogue, held for the SARIF face alone: the
+  // envelope deliberately does not carry it (the JSON contract predates the
+  // SARIF face and must stay byte-identical), while `sarifRules` needs it so
+  // an introduced custom finding's `ruleId` resolves to a descriptor.
+  /** @type {{ruleId: string, rule: string, findingId: string, message: string}[]} */
+  let customCatalogue = [];
+  if (declaresCustomRules(config)) {
+    const twoSided = await customRulesForDelta(commandContext, {
+      rows: config.customRules,
+      policy: config,
+      baseline,
+      ...customRuleIo,
+    });
+    customCatalogue = twoSided.catalogue;
+    custom = {
+      judged: twoSided.judged.map(({ name, sha256, notes: ruleNotes }) => ({
+        name,
+        sha256,
+        ...(ruleNotes === undefined ? {} : { notes: ruleNotes }),
+      })),
+      skipped: twoSided.unknownRules,
+      removed: twoSided.removedRules,
+      findings: classifyCustomFindings({
+        judged: twoSided.judged,
+        unknownRules: twoSided.unknownRules,
+      }),
+    };
+  } else if (baseline.customRules !== undefined) {
+    // The head declares nothing, so there is no law to judge either side
+    // under — every baseline rule is a removal, disclosed rather than judged.
+    custom = {
+      judged: [],
+      skipped: [],
+      removed: baseline.customRules.map((row) => row.name),
+      findings: { introduced: [], resolved: [], unchanged: [], unknown: [] },
+    };
+  }
+  if (custom !== null) {
+    for (const skipped of custom.skipped) {
+      notes.push(`custom rule "${skipped.name}" was not classified — ${skipped.reason}`);
+    }
+    for (const name of custom.removed) {
+      notes.push(
+        `custom rule "${name}" is declared in the baseline but not by the current policy — ` +
+          `nothing was judged for it, so its base-side findings are not classified as resolved`,
+      );
+    }
+    for (const rule of custom.judged) {
+      for (const note of rule.notes ?? []) {
+        notes.push(`custom rule "${rule.name}": ${note}`);
+      }
+    }
+  }
+
+  const { violations, unresolvable } = classification;
+  const introducedWaived = violations.introduced.filter((entry) => entry.waived === true).length;
+  const introducedNotWaived = violations.introduced.length - introducedWaived;
+  // Custom findings have no waiver lane (`./delta-classify.mjs`'s
+  // `classifyCustomFindings` argues the by-construction absence), so every
+  // introduced one gates.
+  const customIntroduced = custom === null ? 0 : custom.findings.introduced.length;
+  const customUnknown = custom === null ? 0 : custom.findings.unknown.length;
+  const unknownCount = violations.unknown.length + unresolvable.unknown.length + customUnknown;
+
+  /** @type {"ok"|"findings"|"no-verdict"} */
+  let status;
+  /** @type {0|1|3} */
+  let exitCode;
+  let decision;
+  if (introducedNotWaived + customIntroduced > 0) {
+    status = "findings";
+    exitCode = 1;
+    decision = buildDecision({
+      status,
+      coverageComplete: true,
+      findings: introducedNotWaived + customIntroduced,
+    });
+  } else if (unknownCount > 0) {
+    status = "no-verdict";
+    exitCode = 3;
+    decision = buildDecision({
+      status,
+      coverageComplete: true,
+      findings: 0,
+      reason:
+        `${unknownCount} delta item${unknownCount === 1 ? "" : "s"} could not be classified — ` +
+        (customUnknown > 0
+          ? `${customUnknown} of them custom-rule item${customUnknown === 1 ? "" : "s"} — `
+          : "") +
+        `an item whose identity cannot be stated is never guessed into a bucket`,
+    });
+  } else {
+    status = "ok";
+    exitCode = 0;
+    decision = buildDecision({ status, coverageComplete: true, findings: 0 });
+  }
+
+  const coverage = {
+    complete: true,
+    projects: Object.keys(graph.nodes).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 })),
+    notes,
+  };
+
+  const result = {
+    baseline: {
+      path: baselinePath,
+      tool: baseline.tool,
+      provider: baseline.provider,
+      provenance: baseline.provenance,
+      policyFingerprint: baseline.policyFingerprint,
+      records: baseline.records.length,
+      projects: baseline.graph.projects.length,
+    },
+    head: {
+      provenance: headProvenance,
+      policyFingerprint: headFingerprint,
+      records: analysis.imports.length,
+      projects: Object.keys(graph.nodes).length,
+    },
+    policyChanged: meta.policyChanged,
+    summary: {
+      introduced: violations.introduced.length,
+      introducedWaived,
+      resolved: violations.resolved.length,
+      unchanged: violations.unchanged.length,
+      unknown: violations.unknown.length,
+      unresolvable: {
+        introduced: unresolvable.introduced.length,
+        resolved: unresolvable.resolved.length,
+        unchanged: unresolvable.unchanged.length,
+        unknown: unresolvable.unknown.length,
+      },
+      ...(custom === null
+        ? {}
+        : {
+            customFindings: {
+              introduced: custom.findings.introduced.length,
+              resolved: custom.findings.resolved.length,
+              unchanged: custom.findings.unchanged.length,
+              unknown: custom.findings.unknown.length,
+            },
+          }),
+    },
+    violations,
+    unresolvable,
+    ...(custom === null ? {} : { customRules: custom }),
+  };
+
+  const envelope = jsonEnvelope({
+    command: "delta",
+    context: { root, provider, marker, provenance: headProvenance },
+    status,
+    exitCode,
+    coverage,
+    result,
+    decision,
+  });
+
+  return {
+    status,
+    delta: result,
+    coverage,
+    report: {
+      text: formatDeltaReport({ delta: result, coverage }),
+      json: renderJson(envelope),
+      // Eager beside the other two faces: the render is pure and cheap, and a
+      // lazy face is one a caller can forget to build — the SARIF is the same
+      // verdict, ready whichever face `--format` selects.
+      sarif: formatDeltaSarif({ delta: result, coverage, customCatalogue }),
+    },
+  };
+}

package/src/commands/diff.mjs

@@ -216,13 +216,29 @@ function buildHeadSnapshot(commandContext) {
   };
 }
 
+/**
+ * The identity key of one dependency record: the `(source, target, type)`
+ * triple joined with `\0`. Extracted from `computeDiff`'s index maps so a
+ * second consumer (`./trajectory.mjs`'s persistence sets) keys edges the SAME
+ * way the diff does — a second spelling of this string would be a second
+ * definition of "same edge", and two definitions drift.
+ *
+ * A `static` edge becoming `dynamic` is therefore a removed edge under the
+ * old type and an added edge under the new one, which is exactly what a
+ * consumer wants to see: it is a real architectural event, not an
+ * implementation detail.
+ *
+ * @param {{source: string, target: string, type: string}} edge
+ * @returns {string}
+ */
+export function edgeIdentityKey({ source, target, type }) {
+  return `${source}\0${target}\0${type}`;
+}
+
 /**
  * Computes the diff between two graph snapshots.
  *
- * Edge identity is `(source, target, type)` — a `static` edge becoming
- * `dynamic` is an added edge under the new type and a removed edge under the
- * old one, which is exactly what a consumer wants to see: it is a real
- * architectural event, not an implementation detail.
+ * Edge identity is `(source, target, type)` — see `edgeIdentityKey` above.
  *
  * @param {{projects: object[], dependencies: object[]}} baseline
  * @param {{projects: object[], dependencies: object[]}} head
@@ -282,13 +298,9 @@ export function computeDiff(baseline, head) {
   removedProjects.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
   changedProjects.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
 
-  // Index edges by the (source, target, type) triple — the identity key.
-  const baselineEdges = new Map(
-    baseline.dependencies.map((e) => [`${e.source}\0${e.target}\0${e.type}`, e]),
-  );
-  const headEdges = new Map(
-    head.dependencies.map((e) => [`${e.source}\0${e.target}\0${e.type}`, e]),
-  );
+  // Index edges by the identity key — `edgeIdentityKey` above owns the triple.
+  const baselineEdges = new Map(baseline.dependencies.map((e) => [edgeIdentityKey(e), e]));
+  const headEdges = new Map(head.dependencies.map((e) => [edgeIdentityKey(e), e]));
 
   const addedEdges = [];
   const removedEdges = [];
@@ -410,8 +422,11 @@ export function diffCommand(
   // classifies as changes, compared here through the shared
   // `./snapshot-meta.mjs` so the two commands cannot disagree about them.
   // Each mismatch becomes a `coverage.notes` warning rather than a refusal:
-  // a provider migration, a cross-repository diff, or a policy change between
-  // baseline and head are all legitimate states a consumer must be told about.
+  // a provider migration, a cross-repository diff, a dirty-tree side, or a
+  // policy change between baseline and head are all legitimate states a
+  // consumer must be told about. The dirty-tree wording is the one `delta` and
+  // `change` emit over the same metadata — three commands, one sentence each,
+  // so a consumer reading any report reads the same caveat.
   const headProvenance = resolveProvenance(root);
   const headFingerprint = config ? computePolicyFingerprint(config) : null;
   const meta = compareSnapshotMetadata({
@@ -445,6 +460,19 @@ export function diffCommand(
     );
   }
 
+  if (meta.dirtyBaseline) {
+    coverage.notes.push(
+      "the baseline was captured from a dirty working tree — its evidence is not a reproducible " +
+        "claim about the commit it names",
+    );
+  }
+  if (meta.dirtyHead) {
+    coverage.notes.push(
+      "this run's working tree is dirty — the head side describes uncommitted state, not the " +
+        "commit HEAD names",
+    );
+  }
+
   if (meta.policyChanged === true) {
     // A policy change between baseline and head means every "introduced" or
     // "resolved" violation in the rule-impact analysis may be an artefact of