@ecoma-io/archkeep 0.17.0 → 0.18.0

package/src/commands/delta-classify.mjs

@@ -65,6 +65,7 @@
 import { canonicalizeJson } from "../canonical.mjs";
 import { suppressionCovers } from "../config.mjs";
 import { referenceTime } from "../governance/clock.mjs";
+import { classifyEvolution } from "../governance/evolution-event.mjs";
 import { suppressionFate } from "../governance/waiver.mjs";
 import { namespacedId } from "./custom-rules.mjs";
 
@@ -491,6 +492,262 @@ export function classifyDelta(input) {
   };
 }
 
+/**
+ * The stable identity string of one classified delta violation entry, for an
+ * evolution event's `findings` (`../governance/evolution-event.mjs`) — the
+ * delta's own identity facts, never a second spelling: `messageId`,
+ * `sourceProject`, the target (project or specifier, with the marker saying
+ * which), and the canonical constraint row that fired. `baseCount`/`headCount`
+ * and the sites are attached evidence, exactly as they are outside identity in
+ * `violationIdentity` — a growth or shrink changes counts, not what the
+ * violation IS.
+ *
+ * @param {object} entry One classified entry from `classifyViolations` or
+ *   `classifyDelta`'s `violations` buckets.
+ * @returns {string} The canonical identity string.
+ */
+function deltaEntryIdentity(entry) {
+  return canonicalizeJson({
+    messageId: entry.messageId,
+    sourceProject: entry.sourceProject ?? null,
+    target: entry.target ?? null,
+    targetIsSpecifier: entry.targetIsSpecifier === true,
+    constraint: entry.constraint ?? null,
+  });
+}
+
+/**
+ * The best name an UNCLASSIFIABLE delta entry can honestly carry into an
+ * event's `unknown` list — the identity it has, or an honest absence. The
+ * reason is the load-bearing half (`classifyEvolution` discloses each with
+ * it); the id exists so the note can name the entry.
+ *
+ * @param {{violation?: object}} entry A violation-classification unknown.
+ * @returns {string}
+ */
+function unknownViolationIdentity(entry) {
+  const violation = entry?.violation;
+  if (violation !== null && typeof violation === "object") {
+    const messageId = typeof violation.messageId === "string" ? violation.messageId : null;
+    const target =
+      typeof violation.targetProject === "string" && violation.targetProject !== ""
+        ? violation.targetProject
+        : typeof violation.specifier === "string" && violation.specifier !== ""
+          ? violation.specifier
+          : null;
+    if (messageId !== null || target !== null) {
+      return `violation ${messageId ?? "?"}${target === null ? "" : ` → ${target}`}`;
+    }
+  }
+  return "unidentifiable violation";
+}
+
+/** The same best-name discipline for an unresolvable-record unknown. */
+function unknownRecordIdentity(entry) {
+  const record = entry?.record;
+  if (
+    record !== null &&
+    typeof record === "object" &&
+    typeof record.specifier === "string" &&
+    record.specifier !== ""
+  ) {
+    return `unresolvable import '${record.specifier}'`;
+  }
+  return "unidentifiable unresolvable import";
+}
+
+/**
+ * The delta event's `findings` (design §1) mapped from a delta capture: the
+ * identity strings of the classified violations, plus every verdict-relevant
+ * unknown the run disclosed — violation unknowns, unresolvable-record
+ * unknowns, and custom-rule unknowns, each with its reason. Unresolvable
+ * introduced/resolved records are NOT findings: the delta carries them but
+ * never counts them as violations (no rule reached a verdict about them), and
+ * the event's findings mirror the delta's gating vocabulary.
+ *
+ * @param {object} delta The `deltaCommand` result payload (`violations`,
+ *   `unresolvable`, optional `customRules`).
+ * @returns {{introduced: string[], resolved: string[], unknown: {id: string,
+ *   reason: string}[]}}
+ */
+export function deltaFindings(delta) {
+  return {
+    introduced: delta.violations.introduced.map(deltaEntryIdentity),
+    resolved: delta.violations.resolved.map(deltaEntryIdentity),
+    unknown: [
+      ...delta.violations.unknown.map((entry) => ({
+        id: unknownViolationIdentity(entry),
+        reason: entry.reason,
+      })),
+      ...delta.unresolvable.unknown.map((entry) => ({
+        id: unknownRecordIdentity(entry),
+        reason: entry.reason,
+      })),
+      ...(delta.customRules === undefined
+        ? []
+        : delta.customRules.findings.unknown.map((entry) => ({
+            id: `custom rule '${entry.rule}'`,
+            reason: entry.reason,
+          }))),
+    ],
+  };
+}
+
+/**
+ * The identity string of one graph edge, in the design's canonical spelling
+ * `source>target:type` (the `(source, target, type)` identity the design
+ * §1 names, printed the way `docs/concepts/evolution.md`'s example shows).
+ * The ONE spelling the delta's event `observed.edges`/`affected.boundaries`
+ * use — a second spelling somewhere would be a second definition of "same
+ * edge", and two definitions drift.
+ *
+ * @param {{source: string, target: string, type: string}} edge
+ * @returns {string}
+ */
+export function edgeEvolutionIdentity({ source, target, type }) {
+  return `${source}>${target}:${type}`;
+}
+
+/**
+ * The delta event's per-constraint verdict deltas (design §1 `fitness`),
+ * derived from the classified entries the capture already carries — never a
+ * re-judgment. A constraint's base/head verdict is judged from the entries
+ * that name it: `fail` when an entry attributes any live site to that side
+ * (`baseCount`/`headCount`), `pass` otherwise. Only rows whose verdict MOVED
+ * are deltas — a constraint failing on both sides moved nothing, and a
+ * half-fixed one is the delta's report of the half it moved. Rows are sorted
+ * by constraint identity, so two runs over the same capture are
+ * byte-identical.
+ *
+ * @param {object} delta The `deltaCommand` result payload.
+ * @returns {{constraint: string, base: "pass"|"fail", head: "pass"|"fail"}[]}
+ */
+export function deltaVerdictDeltas(delta) {
+  const entries = [
+    ...delta.violations.introduced,
+    ...delta.violations.resolved,
+    ...delta.violations.unchanged,
+  ];
+  /** @type {Map<string, {base: number, head: number}>} */
+  const byConstraint = new Map();
+  for (const entry of entries) {
+    if (entry.constraint === undefined || entry.constraint === null) continue;
+    const id = canonicalizeJson(entry.constraint);
+    const row = byConstraint.get(id) ?? { base: 0, head: 0 };
+    if (entry.baseCount > 0) row.base += 1;
+    if (entry.headCount > 0) row.head += 1;
+    byConstraint.set(id, row);
+  }
+  /** @type {{constraint: string, base: "pass"|"fail", head: "pass"|"fail"}[]} */
+  const deltas = [];
+  for (const [constraint, counts] of byConstraint) {
+    /** @type {"pass"|"fail"} */
+    const base = counts.base > 0 ? "fail" : "pass";
+    /** @type {"pass"|"fail"} */
+    const head = counts.head > 0 ? "fail" : "pass";
+    if (base === head) continue;
+    deltas.push({ constraint, base, head });
+  }
+  return deltas;
+}
+
+/**
+ * The §1 mapping for a delta capture: feeds the delta's OWN signals — the
+ * classified violations with their waiver state, the policy-change fact, and
+ * the structural-change/code-drift signals the caller supplies when it
+ * computed them — to `classifyEvolution` (`../governance/evolution-event.mjs`),
+ * the one home of the classification predicates, and returns its verdict.
+ * This module adds no second opinion about what a class means; it maps.
+ *
+ * The delta's verdict-relevant unknowns — violation unknowns, unresolvable-
+ * record unknowns, custom-rule unknowns — are passed through as
+ * `violations.unknown`, so `classifyEvolution`'s fail-closed discipline holds
+ * for every item the delta itself could not place: each raises a `notes[]`
+ * disclosure and forces disposition `no-verdict`; none is ever folded into a
+ * clean class.
+ *
+ * `affected.constraints` is the one delta-specific derivation: the delta's
+ * governed constraints are the `depConstraints` rows its classified
+ * introduced/resolved entries name (the capture output carries each row), and
+ * no reconcile-vocabulary verdict exists for them — so they are mapped from
+ * the entries, never invented. `affected.projects`/`boundaries`/`decisions`
+ * come from `classifyEvolution`'s own mapping of the supplied signals.
+ *
+ * @param {object} delta The `deltaCommand` result payload.
+ * @param {{projects?: {added: string[], removed: string[], changed: string[]},
+ *   edges?: {added: string[], removed: string[]}, codeDrift?: boolean}} [signals]
+ *   The structural-change and drift signals a delta run derives from the two
+ *   graphs it holds (the graph diff is `diff`'s vocabulary, shared here, never
+ *   re-derived) — `projects`/`edges` carry identity strings (`edgeEvolutionIdentity`
+ *   for edges), and `codeDrift` is the delta's computed "provenance advanced,
+ *   no arch/policy change" fact. Absent signals are empty, so a delta that
+ *   computed none reads as a violation-only mapping.
+ * @returns {{classifications: string[], disposition: "accepted"|"rejected"|"no-verdict",
+ *   notes: string[], affected: {projects: string[], boundaries: string[],
+ *   constraints: string[], decisions: string[]}}} The full
+ *   `EvolutionClassification` — `classifications`/`notes` per the wave
+ *   contract, with `disposition`/`affected` riding from the one definition so
+ *   no caller re-derives either.
+ */
+export function classifyDeltaEvolution(delta, signals = {}) {
+  const projects = signals.projects ?? { added: [], removed: [], changed: [] };
+  const edges = signals.edges ?? { added: [], removed: [] };
+  const evolution = classifyEvolution({
+    observed: {
+      projects,
+      edges,
+      // `null` survives: it is the one-sided policy case, and `classifyEvolution`
+      // reads it as "could not be compared" — never as "the same". The
+      // one-sided/advanced facts are input facts the payload carries (F-HIST-1):
+      // both-sides-absent is also `null` but stays comparable.
+      policyChanged: delta.policyChanged,
+      policyOneSided: delta.policyOneSided,
+      provenanceChanged: delta.provenanceChanged,
+    },
+    codeDrift: signals.codeDrift === true,
+    violations: {
+      introduced: delta.violations.introduced.map((entry) => ({
+        id: deltaEntryIdentity(entry),
+        waived: entry.waived === true,
+      })),
+      resolved: delta.violations.resolved.map(deltaEntryIdentity),
+      unknown: [
+        ...delta.violations.unknown.map((entry) => ({
+          id: unknownViolationIdentity(entry),
+          reason: entry.reason,
+        })),
+        ...delta.unresolvable.unknown.map((entry) => ({
+          id: unknownRecordIdentity(entry),
+          reason: entry.reason,
+        })),
+        ...(delta.customRules === undefined
+          ? []
+          : delta.customRules.findings.unknown.map((entry) => ({
+              id: `custom rule '${entry.rule}'`,
+              reason: entry.reason,
+            }))),
+      ],
+    },
+  });
+
+  /** @type {Set<string>} */
+  const constraintIds = new Set();
+  for (const entry of [...delta.violations.introduced, ...delta.violations.resolved]) {
+    if (entry.constraint === undefined || entry.constraint === null) continue;
+    constraintIds.add(canonicalizeJson(entry.constraint));
+  }
+
+  return {
+    classifications: evolution.classifications,
+    disposition: evolution.disposition,
+    notes: evolution.notes,
+    affected: {
+      ...evolution.affected,
+      constraints: [...constraintIds].sort(cmpString),
+    },
+  };
+}
+
 /** Identity-or-reason wrapper applied to every raw violation. */
 function identityOf(violation) {
   const result = violationIdentity(violation);

package/src/commands/delta.mjs

@@ -43,6 +43,20 @@
  * instead. Dirty base provenance and a dirty head are notes too: weaker
  * evidence, not unreadable evidence.
  *
+ * (wave 3, additive) Each compare run maps its own capture output into the
+ * canonical evolution event (`../governance/evolution-event.mjs`, design §1):
+ * a `kind: "transition"`, `source: "delta"` record whose classifications come
+ * from the ONE predicate home `classifyEvolution` (through
+ * `./delta-classify.mjs`'s `classifyDeltaEvolution`), whose observed/findings/
+ * fitness facts are mapped — never re-derived — from the structural signal,
+ * the policy comparison and the violation classification this run already
+ * computed, and whose disposition is a function of the delta's own verb
+ * (`deltaDisposition`). The event rides the result envelope as the additive
+ * `classifications`/`affected` fields, and `--event-out <dir>` (owned by
+ * `../../cli.mjs`) additionally appends the record to the event store
+ * (`../governance/evolution-store.mjs`). Absent the flag, no file is written
+ * and nothing else about the run changes byte-for-byte.
+ *
  * This module computes and returns; `../../cli.mjs`'s `runDelta` owns argv,
  * output destination and the process exit code (`./README.md`).
  */
@@ -51,20 +65,38 @@ 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 {
+  eventDedupeKey,
+  eventId,
+  EVOLUTION_EVENT_SCHEMA_VERSION,
+} from "../governance/evolution-event.mjs";
+import { writeEvent } from "../governance/evolution-store.mjs";
+import { recordOrigin } from "../governance/provenance-record.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 { judgeIntent } from "../architecture-intent/judge.mjs";
+import { INTENT_FILE, loadIntent } from "../architecture-intent/model.mjs";
+import { debtChangeDiff } from "../governance/debt-ledger.mjs";
 import { customRulesForDelta, declaresCustomRules } from "./custom-rules.mjs";
-import { classifyCustomFindings, classifyDelta } from "./delta-classify.mjs";
+import {
+  classifyCustomFindings,
+  classifyDelta,
+  classifyDeltaEvolution,
+  deltaFindings,
+  deltaVerdictDeltas,
+  edgeEvolutionIdentity,
+} from "./delta-classify.mjs";
 import {
   buildEvidenceSnapshot,
   providerMismatch,
   readEvidenceSnapshot,
   serializeEvidenceSnapshot,
 } from "./delta-snapshot.mjs";
-import { computePolicyFingerprint } from "./graph.mjs";
+import { computeDiff } from "./diff.mjs";
+import { buildDependencies, buildProjects, computePolicyFingerprint } from "./graph.mjs";
 import { resolveProvenance } from "./provenance.mjs";
 import { compareSnapshotMetadata } from "./snapshot-meta.mjs";
 
@@ -275,6 +307,40 @@ export function sourceProjectAttributor(headGraph, baselineProjects) {
   };
 }
 
+/**
+ * The delta event's disposition, mapped from the delta's OWN verb contract —
+ * the status `deltaCommand` already folds — so the event's evaluative stance
+ * is a function of the run consumers already know, never a second opinion:
+ *
+ * - `no-verdict` status (any unclassifiable item — violation, unresolvable
+ *   record, or custom finding) ⇒ `no-verdict`, never a fabricated
+ *   accepted/rejected;
+ * - `findings` status ⇒ `rejected`, unconditionally — `findings` means some
+ *   introduced gating finding survived the current waiver table, WHATEVER
+ *   class it carries. The classifications are deliberately NOT consulted:
+ *   a custom-rule-only introduced finding never reaches the VIOLATION
+ *   predicate, so a classifications scan would read "accepted" on an exit-1
+ *   run — the silent direction;
+ * - everything else — a clean comparable capture (`ok`, `[]` classifications),
+ *   an `ok` capture with a fact class (REPAIR, CHANGE, DRIFT,
+ *   DECISION_CHANGE — each accepted by the vocabulary `classification` earns),
+ *   or an `ok` capture holding a WAIVED violation (a waiver is a tracked
+ *   acceptance — which is exactly what kept the gate `ok`) ⇒ `accepted`.
+ *
+ * The two refusals that can never reach this mapping — an unjudgeable head
+ * and a provider mismatch — THROW before any event exists, so a delta that
+ * could not be computed has no record at all, never a record with a guessed
+ * disposition.
+ *
+ * @param {{status: "ok"|"findings"|"no-verdict"}} input
+ * @returns {"accepted"|"rejected"|"no-verdict"}
+ */
+export function deltaDisposition({ status }) {
+  if (status === "no-verdict") return "no-verdict";
+  if (status === "findings") return "rejected";
+  return "accepted";
+}
+
 /** First eight hex characters of a fingerprint, for prose that names one. */
 const short = (fingerprint) =>
   typeof fingerprint === "string" ? fingerprint.slice(0, 8) : String(fingerprint);
@@ -305,27 +371,45 @@ const short = (fingerprint) =>
  * (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,
+ *   now?: string, eventOut?: string|null,
+ *   loadIntentOverride?: (root: string, opts?: object) => Promise<object|undefined>,
+ *   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
+ *   `eventOut` — the directory an evolution event is appended to when given
+ *   (absent or `null` ⇒ no event file, byte-identical behavior),
+ *   `loadIntentOverride` — the architecture-intent reader the event's `debt`
+ *   sub-ledger judges over this run's base and head graphs (defaults to
+ *   `loadIntent`; absent intent ⇒ no ids, an in-band note says so), 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}}>}
+ *   coverage: object,
+ *   eventWrite: {id: string, duplicate: boolean}|null,
+ *   report: {text: string, json: string, sarif: string}}>} `delta` carries
+ *   the additive `classifications`/`affected` fields (design §1); `eventWrite`
+ *   is `null` unless `eventOut` was given, then the store's answer for the
+ *   event that was (or already was) recorded.
  * @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 },
+  {
+    config,
+    readBaseline = readEvidenceSnapshot,
+    now = referenceTime(),
+    eventOut = null,
+    loadIntentOverride,
+    ...customRuleIo
+  },
 ) {
-  const { root, provider, marker, graph, analysis } = commandContext;
+  const { root, provider, marker, graph, analysis, tracked } = commandContext;
 
   refuseUnjudgeableHead(commandContext, "compute a delta");
   if (!config) {
@@ -415,6 +499,53 @@ export async function deltaCommand(
     );
   }
 
+  // The event's structural signal: what moved between the two graphs the
+  // delta already holds, computed through `computeDiff` — the ONE shared
+  // structural vocabulary (`./diff.mjs`, shared with `trajectory`) — so a
+  // project or edge added/removed/changed is a fact about the evidence, never
+  // a second spelling of "changed". The head side is rebuilt by the same
+  // `buildProjects`/`buildDependencies` the snapshot stores
+  // (`./delta-snapshot.mjs`), which is what makes the two sides comparable.
+  const structuralDiff = computeDiff(baseline.graph, {
+    projects: buildProjects(graph.nodes),
+    dependencies: buildDependencies(graph.dependencies),
+  });
+  const structural = {
+    projects: {
+      added: structuralDiff.addedProjects.map((project) => project.name),
+      removed: structuralDiff.removedProjects.map((project) => project.name),
+      changed: structuralDiff.changedProjects.map((project) => project.name),
+    },
+    edges: {
+      added: structuralDiff.addedEdges.map(edgeEvolutionIdentity),
+      removed: structuralDiff.removedEdges.map(edgeEvolutionIdentity),
+    },
+  };
+  const structureChanged =
+    structural.projects.added.length +
+      structural.projects.removed.length +
+      structural.projects.changed.length +
+      structural.edges.added.length +
+      structural.edges.removed.length >
+    0;
+  // The delta's `codeDrift` signal (design §2): provenance advanced — both
+  // sides carry commits, they differ, and neither side was captured dirty (a
+  // dirty tree is weaker evidence, not a claim about the commit it names) —
+  // the architecture did not move, and the policy was comparable AND
+  // unchanged. `policyChanged === null` (one-sided) never reads as "the
+  // same", and a policy change is disclosed, not folded into drift.
+  const baseCommit = baseline.provenance?.commit;
+  const headCommit = headProvenance?.commit;
+  const provenanceAdvanced =
+    typeof baseCommit === "string" &&
+    typeof headCommit === "string" &&
+    baseCommit !== headCommit &&
+    baseline.provenance?.dirty !== true &&
+    headProvenance?.dirty !== true &&
+    meta.crossRepo !== true &&
+    meta.provenanceOneSided !== true;
+  const codeDrift = provenanceAdvanced && !structureChanged && meta.policyChanged === false;
+
   // 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
@@ -480,6 +611,29 @@ export async function deltaCommand(
     }
   }
 
+  // The §1 mapping: the delta's own signals through `classifyEvolution` — one
+  // definition (`./delta-classify.mjs`'s `classifyDeltaEvolution` maps, never
+  // re-decides a class). The result's additive `classifications`/`affected`
+  // ride the envelope, and the same classification feeds the event when
+  // `eventOut` is given.
+  const deltaPayload = {
+    violations: classification.violations,
+    unresolvable: classification.unresolvable,
+    policyChanged: meta.policyChanged,
+    // The one-sided/advanced facts ride the payload (never the event's
+    // `observed`, which is the stored record): classifyEvolution needs them
+    // as input facts — `policyOneSided` is never derived from `policyChanged
+    // === null`, because both-sides-absent is also `null` (F-HIST-1).
+    policyOneSided: meta.policyOneSided,
+    provenanceChanged: meta.provenanceChanged,
+    ...(custom === null ? {} : { customRules: custom }),
+  };
+  const evolution = classifyDeltaEvolution(deltaPayload, {
+    projects: structural.projects,
+    edges: structural.edges,
+    codeDrift,
+  });
+
   const { violations, unresolvable } = classification;
   const introducedWaived = violations.introduced.filter((entry) => entry.waived === true).length;
   const introducedNotWaived = violations.introduced.length - introducedWaived;
@@ -577,9 +731,115 @@ export async function deltaCommand(
     },
     violations,
     unresolvable,
+    classifications: evolution.classifications,
+    affected: evolution.affected,
     ...(custom === null ? {} : { customRules: custom }),
   };
 
+  // The evolution event (design §1), built by mapping — never re-deriving —
+  // the capture output the run already holds: `observed`/`affected`/
+  // `findings`/`fitness` come from the structural signal, the §1 mapping, and
+  // the classification above; `classifications` come from the same mapping;
+  // the disposition is a function of the delta's own verb through
+  // `deltaDisposition`. `recordedAt` carries the SAME injected reference
+  // instant the run judged waivers at — one clock, one transition. Written
+  // only when `eventOut` is given: absent ⇒ no file, byte-identical behavior.
+  /** @type {{id: string, duplicate: boolean}|null} */
+  let eventWrite = null;
+  if (eventOut !== null && eventOut !== undefined) {
+    // F-delta-event-id: an evolution event is only written from a reproducible
+    // identity — a committed, clean head and a clean base. A commitless head
+    // has no revision to name, and a dirty tree names a commit its evidence
+    // does not back; either way TWO distinct evidence states collapse onto ONE
+    // event id, so a later transition is silently lost or aliased (the silent
+    // direction). Refuse loudly instead. The same run without `--event-out`
+    // stays a byte-identical in-memory delta.
+    if (typeof headCommit !== "string") {
+      throw new Error(
+        "archkeep: refusing to write a delta event without a committed head — a commitless " +
+          "head has no reproducible event identity, and every distinct head state would " +
+          "collide on one event id. Commit the head, or capture without --event-out.",
+      );
+    }
+    if (baseline.provenance?.dirty === true || headProvenance?.dirty === true) {
+      throw new Error(
+        "archkeep: refusing to write a delta event from a dirty working tree — the event " +
+          "would name a commit whose evidence is uncommitted, and distinct uncommitted " +
+          "states would collide on one event id. Commit both sides first.",
+      );
+    }
+    // The architecture-debt sub-ledger (design §8): judged by re-running the
+    // current intent over this run's base and head graphs — a drift finding
+    // present at head but not base is introduced; one gone is resolved. Both
+    // ENGINE graphs exist here (the base from the captured snapshot, the head
+    // from the live capture), so unlike `change` there is no unproven-base
+    // gate; the fail-closed branches are an absent intent and an unjudgeable
+    // one, each emitting no ids and an in-band note rather than a fabricated
+    // clean ledger.
+    /** @type {{introduced: string[], resolved: string[], note?: string}} */
+    let debt;
+    try {
+      const archIntent = await (loadIntentOverride ?? loadIntent)(root, { tracked });
+      if (archIntent === undefined || archIntent === null) {
+        debt = {
+          introduced: [],
+          resolved: [],
+          note: `no '${INTENT_FILE}' tracked — the delta event carries no architecture debt ids`,
+        };
+      } else {
+        const baseVerdict = judgeIntent(archIntent, baseGraph);
+        const headVerdict = judgeIntent(archIntent, graph);
+        debt = debtChangeDiff(baseVerdict, headVerdict);
+      }
+    } catch (error) {
+      debt = {
+        introduced: [],
+        resolved: [],
+        note: `architecture intent could not be judged — no debt ids emitted (${error.message})`,
+      };
+    }
+    const event = {
+      schemaVersion: EVOLUTION_EVENT_SCHEMA_VERSION,
+      kind: "transition",
+      source: "delta",
+      base: {
+        ...(typeof baseCommit === "string" ? { revision: baseCommit } : {}),
+        // The evidence ref is the baseline file this run actually compared
+        // against — a pointer into the evidence, never a graph.
+        evidence: baselinePath,
+      },
+      head: typeof headCommit === "string" ? { revision: headCommit } : {},
+      recordedAt: recordOrigin({
+        by: "cli",
+        tool: `archkeep:v${TOOL_VERSION}`,
+        clock: { now: () => now },
+      }),
+      observed: {
+        architectureChanged: structureChanged,
+        projects: structural.projects,
+        edges: structural.edges,
+        policyChanged: meta.policyChanged,
+        // A delta that completed is a delta whose provider matched — the
+        // mismatch refusal above throws before any event could exist.
+        providerChanged: false,
+      },
+      affected: evolution.affected,
+      findings: deltaFindings(deltaPayload),
+      fitness: { verdictDeltas: deltaVerdictDeltas(deltaPayload) },
+      debt,
+      classifications: evolution.classifications,
+      disposition: deltaDisposition({ status }),
+      notes: [...notes, ...evolution.notes],
+      provenance: [
+        ...(typeof baseCommit === "string" ? [{ kind: "git-commit", ref: baseCommit }] : []),
+        ...(typeof headCommit === "string" ? [{ kind: "git-commit", ref: headCommit }] : []),
+      ],
+    };
+    event.dedupeKey = eventDedupeKey(event);
+    event.id = eventId(event);
+    eventWrite = writeEvent(eventOut, event, { root });
+  }
+
   const envelope = jsonEnvelope({
     command: "delta",
     context: { root, provider, marker, provenance: headProvenance },
@@ -592,6 +852,7 @@ export async function deltaCommand(
 
   return {
     status,
+    eventWrite,
     delta: result,
     coverage,
     report: {