@ecoma-io/archkeep 0.17.0 → 0.18.0

package/src/commands/change.mjs

@@ -53,6 +53,24 @@
  * passing is ok (exit 0). The workspace-law axis rides the envelope as
  * evidence only.
  *
+ * ## Wave 3: classification and events (additive)
+ *
+ * Every result carries the evolution classification (`classifications`,
+ * `affected`, `debt` — added fields; nothing existing moved) computed by the
+ * one home the predicates live in, `../governance/evolution-event.mjs`'s
+ * `classifyEvolution`, from the reconciliation output this command already
+ * produced. With `--event-out <dir>` (owned by `../../cli.mjs`), the same
+ * facts are persisted as the canonical reconcile EvolutionEvent
+ * (`kind: "reconcile"`, `source: "change"`, declaration digest over the
+ * intent's declarative rows, disposition by §5's mapping: matched with every
+ * constraint passing ⇒ accepted, undeclared/unfulfilled or a failed
+ * constraint ⇒ rejected, unproven or an undeterminable constraint ⇒
+ * no-verdict). A write failure throws → exit 3; the flag absent means no
+ * file is written and the run is byte-identical to a pre-wave-3 one. The
+ * breadth guard that refuses an empty-rows intent whose summary asserts a
+ * change lives in `./change-intent.mjs`'s validation (`parseChangeIntent`),
+ * the same loud lane as every other malformed declaration.
+ *
  * Refusals (each a throw → exit 3 upstream): a manifest that fails shape or
  * reference validation, an unreadable/malformed/foreign-schema baseline,
  * incomplete baseline coverage, a provider mismatch, incomplete head
@@ -85,6 +103,18 @@ import { formatChangeReport } from "../report/change-text.mjs";
 import { evaluateRun } from "../rules/index.mjs";
 import { compareSnapshotMetadata } from "./snapshot-meta.mjs";
 import { resolveProvenance } from "./provenance.mjs";
+import { referenceTime } from "../governance/clock.mjs";
+import {
+  classifyEvolution,
+  declarationDigest,
+  eventDedupeKey,
+  eventId,
+  EVOLUTION_EVENT_SCHEMA_VERSION,
+} from "../governance/evolution-event.mjs";
+import { writeEvent } from "../governance/evolution-store.mjs";
+import { judgeIntent } from "../architecture-intent/judge.mjs";
+import { INTENT_FILE, loadIntent } from "../architecture-intent/model.mjs";
+import { debtChangeDiff } from "../governance/debt-ledger.mjs";
 
 /**
  * One expected-fact row as the report and JSON carry it. Kept in one builder
@@ -111,6 +141,81 @@ function cmpFacts(a, b) {
   );
 }
 
+/**
+ * The identity string a delta-classified violation entry carries into the
+ * event's `findings` — the same identity fields the delta classification
+ * emits (`messageId`, `sourceProject`, `target`), serialized deterministically
+ * so the ref is stable across runs over the same transition.
+ *
+ * @param {{messageId: string, sourceProject: string|null, target: string}} entry
+ * @returns {string}
+ */
+function violationFindingId(entry) {
+  return `${entry.messageId}:${entry.sourceProject ?? "-"}:${entry.target}`;
+}
+
+/**
+ * The identity string an observed edge carries into the event's `observed`
+ * and `affected` — `(source, target, type)`, the triple `./diff.mjs`'s
+ * `edgeIdentityKey` owns, spelled for a human reader (`>` separator, optional
+ * type suffix). Two spellings of one triple never diverge because the triple
+ * itself is the input.
+ *
+ * @param {{source: string, target: string, type?: string}} edge
+ * @returns {string}
+ */
+function edgeIdentityString(edge) {
+  return `${edge.source}>${edge.target}${edge.type === undefined || edge.type === "" ? "" : `:${edge.type}`}`;
+}
+
+/**
+ * The structural-diff facts in the event's `observed` shape (design §1),
+ * mapped from `computeDiff`'s output and the metadata comparison — the same
+ * lists the reconciliation already consumed, never recomputed.
+ *
+ * @param {{addedProjects: object[], removedProjects: object[],
+ *   changedProjects: object[], addedEdges: object[], removedEdges: object[]}} structural
+ * @param {{policyChanged: boolean|null, policyOneSided: boolean,
+ *   provenanceChanged: boolean|null}} meta From `compareSnapshotMetadata`.
+ * @returns {{architectureChanged: boolean, projects: {added: string[],
+ *   removed: string[], changed: string[]}, edges: {added: string[],
+ *   removed: string[]}, policyChanged: boolean|null, policyOneSided: boolean,
+ *   provenanceChanged: boolean|null, providerChanged: boolean}}
+ */
+function observedFrom(structural, meta) {
+  const projects = {
+    added: structural.addedProjects.map((project) => project.name),
+    removed: structural.removedProjects.map((project) => project.name),
+    changed: structural.changedProjects.map((project) => project.name),
+  };
+  const edges = {
+    added: structural.addedEdges.map(edgeIdentityString),
+    removed: structural.removedEdges.map(edgeIdentityString),
+  };
+  return {
+    architectureChanged:
+      projects.added.length +
+        projects.removed.length +
+        projects.changed.length +
+        edges.added.length +
+        edges.removed.length >
+      0,
+    projects,
+    edges,
+    // `null` is "could not be compared": exactly one side records the law
+    // (`policyOneSided`) or neither does — passed through so classifyEvolution
+    // discloses rather than reading it as "the same", and the advanced
+    // both-absent pair never classifies as unchanged
+    // (`../governance/evolution-event.mjs`).
+    policyChanged: meta.policyChanged,
+    policyOneSided: meta.policyOneSided,
+    provenanceChanged: meta.provenanceChanged,
+    // The provider mismatch refuses before reconciliation ever runs, so a
+    // reconciliable pair is by construction same-provider.
+    providerChanged: false,
+  };
+}
+
 /**
  * Reconciles a normalized change-intent contract against the structural diff
  * of the two graphs. Pure — the heart of the command, and the function a
@@ -244,6 +349,37 @@ export function reconciliationVerdict(lists, unprovenReasons) {
   return "matched";
 }
 
+/**
+ * The reconcile DISPOSITION mapping (wave 3, design §5) — the verdict axis
+ * first, then the declared constraints' verdicts. Pure and exported so the
+ * mapping is a fact a test can pin:
+ *
+ * | verdict | disposition |
+ * |---|---|
+ * | `matched`, every declared constraint passing | `accepted` |
+ * | `matched`, a declared constraint failing | `rejected` — the change's own
+ *   promise was broken, the same lane design §2 gives a constraint `fail` |
+ * | `undeclared` / `unfulfilled` | `rejected` |
+ * | `unproven`, or any declared constraint `unknown` | `no-verdict` — an
+ *   undetermined axis never reads as an acceptance |
+ *
+ * `no-verdict` is never a degraded `accepted`: the mapping refuses to
+ * fabricate either direction when the run could not determine it.
+ *
+ * @param {"matched"|"undeclared"|"unfulfilled"|"unproven"} verdict
+ * @param {{verdict: string}[]} [constraints] The judged constraint rows from
+ *   this run — empty when none were declared or when the base identity was
+ *   unproven (constraints are left unevaluated then).
+ * @returns {"accepted"|"rejected"|"no-verdict"}
+ */
+export function reconcileDisposition(verdict, constraints = []) {
+  if (verdict === "unproven") return "no-verdict";
+  if (verdict === "undeclared" || verdict === "unfulfilled") return "rejected";
+  if (constraints.some((row) => row.verdict === "unknown")) return "no-verdict";
+  if (constraints.some((row) => row.verdict === "fail")) return "rejected";
+  return "accepted";
+}
+
 /**
  * Judges the constraints the contract declares, through the shared engine —
  * both sides re-judged under the CURRENT law and one shared instant, exactly
@@ -335,14 +471,24 @@ function judgeDeclaredConstraints(intent, io) {
  * @param {string} intentPath Absolute path to the change-intent manifest.
  * @param {object} commandContext From `resolveCommandContext`.
  * @param {{config?: object|null, readBaseline?: (path: string) => object,
- *   readIntent?: (path: string) => Promise<object>, now?: string}} [io]
+ *   readIntent?: (path: string) => Promise<object>, now?: string,
+ *   loadIntentOverride?: (root: string, opts?: object) => Promise<object|undefined>,
+ *   eventOut?: string, writeEvent?: (dir: string, event: object,
+ *   io?: object) => {id: string, duplicate: boolean}}} [io]
  *   The resolved boundary config (required — constraints are judged under it
  *   and the fingerprint identifies the law), injectable readers so tests drive
- *   the command without disk, and the shared reference instant. Both readers
- *   return VALIDATED domain objects — `readEvidenceSnapshot`'s parse and
- *   `parseChangeIntent`'s normalized contract respectively — the same seam
- *   contract `deltaCommand`'s `readBaseline` states; an injector handing back
- *   raw file contents skips the grammar this command trusts.
+ *   the command without disk, the shared reference instant, and the wave-3
+ *   event surface: `eventOut` names the directory the reconcile EvolutionEvent
+ *   is written to (absent ⇒ no event file, byte-identical run), and
+ *   `writeEvent` is the store seam defaulting to the canonical append-only
+ *   store. Both readers return VALIDATED domain objects —
+ *   `readEvidenceSnapshot`'s parse and `parseChangeIntent`'s normalized
+ *   contract respectively — the same seam contract `deltaCommand`'s
+ *   `readBaseline` states; an injector handing back raw file contents skips
+ *   the grammar this command trusts. `loadIntentOverride` is the same
+ *   architecture-intent seam `drift` uses (defaults to `loadIntent`); the
+ *   change event's `debt` diff judges the intent over this run's base and
+ *   head graphs and would be untestable without it.
  * @returns {Promise<{status: "ok"|"findings"|"no-verdict",
  *   changeIntent: object, coverage: object, report: {text: string, json: string}}>}
  * @throws {Error} on every refusal the module header lists.
@@ -351,9 +497,27 @@ export async function changeCommand(
   baselinePath,
   intentPath,
   commandContext,
-  { config, readBaseline = readEvidenceSnapshot, readIntent, now } = {},
+  {
+    config,
+    readBaseline = readEvidenceSnapshot,
+    readIntent,
+    now,
+    // Wave 3 (design §4): the directory the reconcile EvolutionEvent is
+    // written to. Absent ⇒ no event file is written and the run is
+    // byte-identical to a pre-wave-3 run; the classification still rides the
+    // envelope result either way.
+    eventOut,
+    // The architecture-intent reader seam (design §8): the change event's
+    // `debt` diff judges the SAME intent file `drift`/`debt` judge over this
+    // run's base and head graphs. Injectable so tests drive it without disk;
+    // defaults to the canonical loader. Absent intent ⇒ no ids are emitted.
+    loadIntentOverride,
+    // The store seam, injectable so tests drive the write without disk and
+    // embedders can route it; defaults to the canonical append-only store.
+    writeEvent: writeEventSeam = writeEvent,
+  } = {},
 ) {
-  const { root, provider, marker, graph, analysis } = commandContext;
+  const { root, provider, marker, graph, analysis, tracked } = commandContext;
 
   // The one required member of `io`: constraints are judged under the current
   // law and the envelope records which law that was, so an undefined config
@@ -452,12 +616,23 @@ export async function changeCommand(
   /** @type {object[]} */
   let constraints = [];
   let liveViolations = null;
+  // The classification is a wave-3 event signal too, so it is held at
+  // function scope: `null` when the base identity is unproven (nothing was
+  // evaluated, and the event must not fabricate violation facts).
+  /** @type {ReturnType<typeof classifyDelta>|null} */
+  let classification = null;
+  // The base engine graph is hoisted (not block-scoped) because the change
+  // event's `debt` diff below re-judges the architecture intent over BOTH
+  // sides. It exists only when the base identity is provable; `null` here is
+  // the F-CHG-1 signal that no debt diff is trustworthy and none will be
+  // emitted (an unproven base must never fabricate ledger ids).
+  const baseEngineGraph =
+    unprovenReasons.length === 0 ? evidenceGraphToProjectGraph(baseline.graph) : null;
   if (unprovenReasons.length === 0) {
     const configWithNow = now === undefined ? config : { ...config, now };
-    const baseEngineGraph = evidenceGraphToProjectGraph(baseline.graph);
     const baseRaw = evaluateRun(baseline.records, baseEngineGraph, configWithNow).rawViolations;
     const headEval = evaluateRun(analysis.imports, graph, configWithNow);
-    const classification = classifyDelta({
+    classification = classifyDelta({
       baseViolations: baseRaw,
       headViolations: headEval.rawViolations,
       baseRecords: baseline.records,
@@ -547,6 +722,140 @@ export async function changeCommand(
     notes,
   };
 
+  // Wave 3 (design §1, §2, §5): the evolution classification and the reconcile
+  // event. The classification is ALWAYS computed — it rides the envelope
+  // result in memory even when no event is written (design §4) — and the
+  // event is persisted only when `eventOut` names a directory. The signals
+  // are mapped from the reconciliation output already computed above; nothing
+  // here re-derives what `diff`, `classifyDelta` or `classifyEvolution`
+  // answered (`../governance/evolution-event.mjs` is the predicates' one
+  // home). When the base identity is unproven the constraints were left
+  // unevaluated, so no violation signal exists — the classification then
+  // answers `no-verdict` from the declared-intent row alone, never a
+  // fabricated acceptance.
+  const observed = observedFrom(structural, meta);
+  /** @type {{id: string, waived: boolean}[]} */
+  const introducedViolations = (classification?.violations.introduced ?? []).map((entry) => ({
+    id: violationFindingId(entry),
+    waived: entry.waived === true,
+  }));
+  const resolvedViolations = (classification?.violations.resolved ?? []).map(violationFindingId);
+  const unknownViolations = (classification?.violations.unknown ?? []).map((entry) => ({
+    id: `unidentified:${entry.reason}`,
+    reason: entry.reason,
+  }));
+  const evolution = classifyEvolution({
+    observed,
+    ...(classification === null
+      ? {}
+      : {
+          violations: {
+            introduced: introducedViolations,
+            resolved: resolvedViolations,
+            unknown: unknownViolations,
+          },
+        }),
+    declaredConstraints: constraints.map((row) => ({ id: row.name, verdict: row.verdict })),
+    declaredIntentRows: [{ id: "intent", verdict }],
+  });
+
+  // Debt impact: the architecture-lifecycle debt THIS change opened or closed,
+  // as stable ids the W5 ledger derives for the same intent facts (design §8)
+  // — the SAME fact → the SAME id, so an event's `debt.introduced` links the
+  // ledger's `introducedBy`. The ids come from a `judgeIntent` diff over the
+  // run's base and head graphs under ONE current intent: a drift finding (or
+  // unbuilt aspirational gap) present at head but not base is introduced; one
+  // gone at head is resolved. Constraint-fail rows carry no source/target/rule
+  // — because they are not drift, they stay in `affected.constraints` and
+  // `findings`, never in `debt`. An unproven base (F-CHG-1) or an unjudgeable
+  // intent is a no-verdict: no ids are emitted, an in-band note says so, and a
+  // change run never fabricates ledger ids over evidence it cannot vouch for.
+  /** @type {{introduced: string[], resolved: string[], note?: string}} */
+  let debt;
+  if (baseEngineGraph === null) {
+    debt = {
+      introduced: [],
+      resolved: [],
+      note: "base identity unproven — no architecture debt diff can be trusted",
+    };
+  } else {
+    try {
+      const archIntent = await (loadIntentOverride ?? loadIntent)(root, { tracked });
+      if (archIntent === undefined || archIntent === null) {
+        debt = {
+          introduced: [],
+          resolved: [],
+          note: `no '${INTENT_FILE}' tracked — the change event carries no architecture debt ids`,
+        };
+      } else {
+        const baseVerdict = judgeIntent(archIntent, baseEngineGraph);
+        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 baseCommit = baseline.provenance?.commit;
+  const headCommit = headProvenance?.commit;
+  /** @type {object} */
+  const event = {
+    schemaVersion: EVOLUTION_EVENT_SCHEMA_VERSION,
+    kind: "reconcile",
+    source: "change",
+    base: {
+      ...(typeof baseCommit === "string" ? { revision: baseCommit } : {}),
+      // The caller's own evidence ref — the baseline file this run consumed,
+      // spelled as the run received it (the same convention `declaration.file`
+      // uses for the intent path).
+      evidence: baselinePath,
+    },
+    head: {
+      ...(typeof headCommit === "string" ? { revision: headCommit } : {}),
+    },
+    declaration: { file: intentPath, digest: declarationDigest(intent) },
+    observed,
+    affected: evolution.affected,
+    findings: {
+      introduced: introducedViolations.map((entry) => entry.id),
+      resolved: resolvedViolations,
+      unknown: unknownViolations.map((entry) => entry.id),
+    },
+    // The verdictDeltas are the DECLARED constraints judged over the delta —
+    // a change run has no separate base-verdict pass, so each row states the
+    // delta verdict itself rather than a pair that does not exist.
+    fitness: {
+      verdictDeltas: constraints.map((row) => ({ id: row.name, verdict: row.verdict })),
+    },
+    debt,
+    classifications: evolution.classifications,
+    disposition: evolution.disposition,
+    notes: evolution.notes,
+    provenance: typeof headCommit === "string" ? [{ kind: "git-commit", ref: headCommit }] : [],
+    // The governance clock — the same injected `now` seam the rest of the run
+    // uses, the wall clock only when nothing was injected. It is EXCLUDED
+    // from the identity by `evolution-event.mjs` by construction.
+    recordedAt: { by: "change", tool: "archkeep:v1", on: now ?? referenceTime() },
+  };
+  event.dedupeKey = eventDedupeKey(event);
+  event.id = eventId(event);
+
+  /** @type {{dir: string, id: string, duplicate: boolean}|null} */
+  let eventWritten = null;
+  if (eventOut !== undefined && eventOut !== null && eventOut !== "") {
+    // The store's io.root is the workspace root: the write must be provable
+    // to stay inside the workspace (the same containment `--output` obeys).
+    // A write failure throws — exit 3 upstream, the could-not-look lane —
+    // never a silent "event recorded" that wrote nothing.
+    const write = writeEventSeam(eventOut, event, { root });
+    eventWritten = { dir: eventOut, ...write };
+  }
+
   const result = {
     intent: {
       file: intentPath,
@@ -588,6 +897,12 @@ export async function changeCommand(
       changedSinceBase: meta.policyChanged === true,
       liveViolations,
     },
+    // Wave 3 additive result fields (design §5): the evolution classification
+    // and the debt impact. Present on every run, `--event-out` or not — the
+    // event's classification rides the envelope in memory (design §4).
+    classifications: evolution.classifications,
+    affected: evolution.affected,
+    debt,
   };
 
   const envelope = jsonEnvelope({
@@ -605,7 +920,13 @@ export async function changeCommand(
     changeIntent: result,
     coverage,
     report: {
-      text: formatChangeReport({ change: result, coverage }),
+      text: formatChangeReport({
+        change: result,
+        coverage,
+        // Present only when an event was written — the text report stays
+        // byte-identical when `--event-out` is absent.
+        ...(eventWritten === null ? {} : { eventWritten }),
+      }),
       json: renderJson(envelope),
     },
   };

package/src/commands/debt.mjs

@@ -49,6 +49,7 @@ 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 { readEvents } from "../governance/evolution-store.mjs";
 import { formatDebtReport } from "../report/debt-text.mjs";
 import { jsonEnvelope, renderJson } from "../report/json.mjs";
 import { resolveProvenance } from "./provenance.mjs";
@@ -68,9 +69,12 @@ import { readSnapshots } from "./history.mjs";
  * @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.
+ *   events?: string|null, io?: {readSnapshots?: Function,
+ *   loadIntentOverride?: Function, resolveProvenance?: Function,
+ *   readEvents?: Function}}} [options] Injectable seams for tests, mirroring
+ *   the `history`/`drift` pattern. `events` is the event-store directory the
+ *   `--events <dir>` CLI flag resolves; absent ⇒ no lifecycle refs (the
+ *   ledger says so in `lifecycle.note`), never guessed.
  * @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.
@@ -140,14 +144,26 @@ export async function debtCommand(dir, commandContext, options = {}) {
     );
   }
 
+  // The optional event linkage (design §4): `--events <dir>` reads the
+  // evolution store so active debt can carry `introducedBy` and closed debt
+  // can appear on the `resolved` list. Absent ⇒ nothing is loaded and the
+  // ledger records no refs ("no event store linked" note); refs are never
+  // guessed.
+  const loadStoreEvents = io.readEvents ?? readEvents;
+  const events = options.events ? loadStoreEvents(options.events) : null;
+
   const ledger = computeDebtLedger(
     {
       suppressions: config.suppressions,
       intentNotes: verdict.notes,
+      gaps: verdict.gaps,
       findings: verdict.findings,
     },
     read,
-    { referenceTime: options.referenceTime },
+    {
+      referenceTime: options.referenceTime,
+      events,
+    },
   );
 
   const observed = buildObserved(commandContext);
@@ -168,7 +184,9 @@ export async function debtCommand(dir, commandContext, options = {}) {
     // 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.
+    // directory and tree. The lifecycle note (when the store is not linked)
+    // states the same posture for refs: they are absent, disclosed, never
+    // fabricated.
     notes: [
       `ledger ages are snapshot-relative; ${ledger.entries.length} entr` +
         `${ledger.entries.length === 1 ? "y" : "ies"} derived across ${read.files.length} snapshot` +
@@ -177,6 +195,7 @@ export async function debtCommand(dir, commandContext, options = {}) {
         "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.",
+      ...(ledger.lifecycle.note ? [ledger.lifecycle.note] : []),
     ],
   };
 
@@ -192,9 +211,11 @@ export async function debtCommand(dir, commandContext, options = {}) {
     agings: ledger.agings,
     sampleTime: ledger.sampleTime,
     entries: ledger.entries,
+    resolved: ledger.resolved,
     total: ledger.total,
     byKind: ledger.byKind,
     bySeverity: ledger.bySeverity,
+    lifecycle: ledger.lifecycle,
   };
 
   const envelope = jsonEnvelope({