@intentius/chant 0.49.0 → 0.51.0

package/src/lifecycle/disruption.ts

@@ -0,0 +1,224 @@
+/**
+ * Per-change disruption classification (#1665).
+ *
+ * The change set says WHAT a pending change is (`create`/`update`/`delete`/…).
+ * It says nothing about what applying it costs. An `update` that flips a tag
+ * and an `update` that rebuilds a database read identically, and the second one
+ * is the one that wakes somebody up.
+ *
+ * The knowledge that separates them is spec knowledge. CloudFormation's
+ * registry schema declares `createOnlyProperties` per type; Kubernetes' SSA
+ * schema knows which field changes roll a workload. Core owns neither, and
+ * hardcoding either here would put per-provider replacement rules in the tool
+ * — the same mistake `postSynthChecks` exists to avoid. So core defines the
+ * contract and the reporting, and the lexicon that compiled the spec supplies
+ * the answer, via {@link LexiconPlugin.classifyDisruption}.
+ *
+ * The invariant that makes the field trustworthy is that `unknown` is the
+ * default and the only fallback. No classifier, a classifier that says nothing
+ * about an entry, a classifier that throws, a classifier that returns a level
+ * outside the vocabulary — all of them land on `unknown`, never on `in-place`.
+ * A confident "this mutates in place" is only ever a lexicon's own claim.
+ */
+import type { AttributeChange } from "./live-diff";
+import type { ChangeSet, ChangeSetEntry } from "./change-set";
+
+/**
+ * How much applying one pending change hurts.
+ *
+ * - `in-place` — the provider mutates the existing resource. No new identity,
+ *   no window where it is absent.
+ * - `rolling` — the resource survives, but its workload is replaced
+ *   incrementally (a Deployment's pod template changing). Disruptive to what
+ *   is running, not to the resource.
+ * - `replace` — a new resource is created and the old one removed. The
+ *   physical id changes; anything holding the old one has to be updated.
+ * - `destroy` — replacement that removes the old resource FIRST. There is a
+ *   window with nothing there, and whatever the old one held is gone.
+ * - `unknown` — nobody could say. The honest value, and the default: it is
+ *   what a change gets when no lexicon classifies it, and it must never be
+ *   read as "probably fine".
+ */
+export type Disruption = "in-place" | "rolling" | "replace" | "destroy" | "unknown";
+
+/** Every level, most disruptive last — also the guard core validates a lexicon's answer against. */
+export const DISRUPTION_LEVELS: readonly Disruption[] = [
+  "in-place",
+  "rolling",
+  "replace",
+  "destroy",
+  "unknown",
+];
+
+/** Ordering for "the worst thing in this plan", with `unknown` above every confident verdict. */
+const DISRUPTION_RANK: Record<Disruption, number> = {
+  "in-place": 0,
+  rolling: 1,
+  replace: 2,
+  destroy: 3,
+  unknown: 4,
+};
+
+/** One pending change put to a lexicon for classification. */
+export interface DisruptionQuery {
+  /** The change set entry's `name` — the key a verdict comes back under. */
+  name: string;
+  /** Resource type, when the observation reported one. */
+  type?: string;
+  /** The attribute-level changes the entry carries. */
+  deltas: AttributeChange[];
+}
+
+/** A lexicon's answer for one query. */
+export interface DisruptionVerdict {
+  disruption: Disruption;
+  /** The attribute paths that forced the verdict — empty or absent when none did. */
+  because?: string[];
+  /** One line of human-readable backing, naming the spec knowledge behind the call. */
+  detail?: string;
+}
+
+/**
+ * The shape of {@link LexiconPlugin.classifyDisruption}. Keyed by query `name`;
+ * a name the lexicon says nothing about degrades to `unknown`, so a partial
+ * answer is a valid answer.
+ */
+export type DisruptionClassifier = (options: {
+  environment: string;
+  changes: DisruptionQuery[];
+}) => Record<string, DisruptionVerdict> | Promise<Record<string, DisruptionVerdict>>;
+
+/** The verdict every fallback path produces. */
+export function unknownDisruption(detail: string): DisruptionVerdict {
+  return { disruption: "unknown", detail };
+}
+
+/**
+ * Annotate one lexicon's change set with a disruption verdict per `update`.
+ *
+ * Only `update` entries are asked about: every other action already carries its
+ * blast radius in the action itself. Called once per lexicon, before the plan
+ * merges the change sets, so `classify` is always the lexicon that produced the
+ * entries — the only party that can map its own observation's attribute paths
+ * back onto spec properties.
+ *
+ * Returns a new change set; the input is not mutated.
+ */
+export async function annotateDisruption(
+  cs: ChangeSet,
+  environment: string,
+  classify?: DisruptionClassifier,
+): Promise<ChangeSet> {
+  const updates = cs.entries.filter((e) => e.action === "update");
+  if (updates.length === 0) return cs;
+
+  const who = updates[0].lexicon ? `the ${updates[0].lexicon} lexicon` : "this lexicon";
+
+  let verdicts: Record<string, DisruptionVerdict> = {};
+  let fallback: string | undefined;
+
+  if (!classify) {
+    fallback = `${who} does not classify disruption — replacement semantics are spec knowledge it has not published`;
+  } else {
+    try {
+      verdicts = (await classify({
+        environment,
+        changes: updates.map((e) => ({
+          name: e.name,
+          ...(e.type ? { type: e.type } : {}),
+          deltas: e.deltas ?? [],
+        })),
+      })) ?? {};
+    } catch (err) {
+      // A broken classifier is not evidence of anything. It must not be able to
+      // leave a confident verdict behind, and it must not fail the plan either.
+      verdicts = {};
+      fallback = `${who}'s disruption classifier failed: ${err instanceof Error ? err.message : String(err)}`;
+    }
+  }
+
+  const entries = cs.entries.map((e) => {
+    if (e.action !== "update") return e;
+    const verdict = resolveVerdict(verdicts[e.name], fallback, who);
+    const annotated: ChangeSetEntry = {
+      ...e,
+      disruption: verdict.disruption,
+      ...(verdict.because && verdict.because.length > 0 ? { disruptionBecause: verdict.because } : {}),
+      ...(verdict.detail ? { disruptionDetail: verdict.detail } : {}),
+    };
+    return annotated;
+  });
+
+  return { ...cs, entries };
+}
+
+function resolveVerdict(
+  verdict: DisruptionVerdict | undefined,
+  fallback: string | undefined,
+  who: string,
+): DisruptionVerdict {
+  if (fallback) return unknownDisruption(fallback);
+  if (!verdict) return unknownDisruption(`${who} returned no verdict for this change`);
+  if (!DISRUPTION_LEVELS.includes(verdict.disruption)) {
+    return unknownDisruption(
+      `${who} returned "${String(verdict.disruption)}", which is not a disruption level`,
+    );
+  }
+  return verdict;
+}
+
+/** Count `update` entries per level. Entries with no verdict at all are not counted. */
+export function summarizeDisruption(cs: ChangeSet): Record<Disruption, number> {
+  const counts: Record<Disruption, number> = {
+    "in-place": 0,
+    rolling: 0,
+    replace: 0,
+    destroy: 0,
+    unknown: 0,
+  };
+  for (const e of cs.entries) {
+    if (e.action === "update" && e.disruption) counts[e.disruption]++;
+  }
+  return counts;
+}
+
+/** The most disruptive verdict in the set, or undefined when nothing was classified. */
+export function worstDisruption(cs: ChangeSet): Disruption | undefined {
+  let worst: Disruption | undefined;
+  for (const e of cs.entries) {
+    if (e.action !== "update" || !e.disruption) continue;
+    if (!worst || DISRUPTION_RANK[e.disruption] > DISRUPTION_RANK[worst]) worst = e.disruption;
+  }
+  return worst;
+}
+
+/**
+ * Warnings a plan should print on stderr — so a `--json` or `--report gitlab-mr`
+ * consumer, whose shape has no column for disruption, still hears about the
+ * expensive rows. Same discipline as the unobserved warning (#1089).
+ */
+export function disruptionNotices(cs: ChangeSet): string[] {
+  const counts = summarizeDisruption(cs);
+  const notices: string[] = [];
+  const replacing = counts.replace + counts.destroy;
+  if (replacing > 0) {
+    notices.push(
+      `${replacing} update(s) replace the resource rather than mutating it in place` +
+        (counts.destroy > 0
+          ? `, ${counts.destroy} of them by deleting it first — that window has nothing in it.`
+          : "."),
+    );
+  }
+  if (counts.unknown > 0) {
+    notices.push(
+      `${counts.unknown} update(s) could not be classified — no lexicon could say whether applying them replaces the resource. Unknown is not "in place".`,
+    );
+  }
+  return notices;
+}
+
+/** Render one entry's verdict for the human plan, or "" when there is none. */
+export function renderDisruption(entry: ChangeSetEntry): string {
+  if (!entry.disruption) return "";
+  return ` — ${entry.disruption}${entry.disruptionDetail ? `: ${entry.disruptionDetail}` : ""}`;
+}

package/src/lifecycle/gate-ledger.test.ts

@@ -0,0 +1,103 @@
+import { describe, test, expect } from "vitest";
+import { withTestDir } from "@intentius/chant-test-utils";
+import { spawnSync } from "node:child_process";
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { appendGateResolution, readGateResolutions, latestResolutionSince } from "./gate-ledger";
+import { readBlobFromPath } from "./git";
+
+function git(args: string[], cwd: string): { stdout: string; exitCode: number } {
+  const r = spawnSync("git", args, { cwd, encoding: "utf-8" });
+  return { stdout: r.stdout ?? "", exitCode: r.status ?? -1 };
+}
+
+async function initRepo(dir: string): Promise<void> {
+  git(["init", "-q", "-b", "main"], dir);
+  git(["config", "user.email", "test@chant.dev"], dir);
+  git(["config", "user.name", "Test"], dir);
+  writeFileSync(join(dir, "README.md"), "fixture\n");
+  git(["add", "README.md"], dir);
+  git(["commit", "-q", "-m", "init"], dir);
+}
+
+describe("lifecycle/gate-ledger", () => {
+  test("appendGateResolution + readGateResolutions round-trip", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      const { record } = await appendGateResolution(
+        { op: "fountain-apply", gate: "rollout-gate", resolvedBy: "alex", timestamp: "2026-01-01T00:00:00.000Z" },
+        { cwd: dir },
+      );
+      expect(record.version).toBe(1);
+
+      const { records, malformed } = await readGateResolutions("fountain-apply", { cwd: dir });
+      expect(malformed).toBe(0);
+      expect(records).toEqual([record]);
+    });
+  });
+
+  test("stores under a global _gates namespace, keyed by op — not per-environment", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      await appendGateResolution(
+        { op: "fountain-apply", gate: "rollout-gate", resolvedBy: "alex", timestamp: "2026-01-01T00:00:00.000Z" },
+        { cwd: dir },
+      );
+      const raw = await readBlobFromPath("_gates", "fountain-apply.jsonl", { cwd: dir });
+      expect(raw).toContain("rollout-gate");
+    });
+  });
+
+  test("readGateResolutions returns [] for an op with no resolutions yet", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      expect(await readGateResolutions("no-such-op", { cwd: dir })).toEqual({ records: [], malformed: 0 });
+    });
+  });
+
+  test("appends without clobbering — multiple gates/resolutions on the same op accumulate", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      await appendGateResolution(
+        { op: "fountain-apply", gate: "rollout-gate", resolvedBy: "alex", timestamp: "2026-01-01T00:00:00.000Z" },
+        { cwd: dir },
+      );
+      await appendGateResolution(
+        { op: "fountain-apply", gate: "prod-gate", resolvedBy: "sam", timestamp: "2026-01-02T00:00:00.000Z", note: "https://github.com/x/y/pull/1" },
+        { cwd: dir },
+      );
+      const { records } = await readGateResolutions("fountain-apply", { cwd: dir });
+      expect(records.map((r) => r.gate)).toEqual(["rollout-gate", "prod-gate"]);
+      expect(records[1].note).toBe("https://github.com/x/y/pull/1");
+    });
+  });
+
+  describe("latestResolutionSince", () => {
+    test("finds a resolution recorded after the gated tick's own timestamp", () => {
+      const records = [
+        { version: 1 as const, op: "x", gate: "g1", resolvedBy: "a", timestamp: "2026-01-01T00:00:00.000Z" },
+        { version: 1 as const, op: "x", gate: "g1", resolvedBy: "b", timestamp: "2026-01-03T00:00:00.000Z" },
+      ];
+      const found = latestResolutionSince(records, "g1", "2026-01-02T00:00:00.000Z");
+      expect(found?.resolvedBy).toBe("b");
+    });
+
+    test("returns undefined when the only resolution predates the gated tick (a stale, superseded approval)", () => {
+      const records = [
+        { version: 1 as const, op: "x", gate: "g1", resolvedBy: "a", timestamp: "2026-01-01T00:00:00.000Z" },
+      ];
+      expect(latestResolutionSince(records, "g1", "2026-01-02T00:00:00.000Z")).toBeUndefined();
+    });
+
+    test("ignores resolutions for a different gate", () => {
+      const records = [
+        { version: 1 as const, op: "x", gate: "other-gate", resolvedBy: "a", timestamp: "2026-01-05T00:00:00.000Z" },
+      ];
+      expect(latestResolutionSince(records, "g1", "2026-01-01T00:00:00.000Z")).toBeUndefined();
+    });
+
+    test("undefined when there are no resolutions at all", () => {
+      expect(latestResolutionSince([], "g1", "2026-01-01T00:00:00.000Z")).toBeUndefined();
+    });
+  });
+});

package/src/lifecycle/gate-ledger.ts

@@ -0,0 +1,140 @@
+/**
+ * Gate resolution ledger (#1485, epic #1487) — the durable counterpart to a
+ * converge tick's gate-as-fact outcome (`./converge-ledger.ts`'s
+ * `ConvergeRuleOutcome.action === "gated"`). Same append-only, content-
+ * addressed shape as the converge/release ledgers, reusing
+ * `writeBlobToPath`/`readBlobFromPath` (./git.ts) directly — one line per
+ * resolution at `_gates/<op>.jsonl` on the `chant/lifecycle` orphan branch.
+ *
+ * Keyed by op name rather than environment (`_gates`, not `<env>/gates...`)
+ * because a gate belongs to the *dispatched* op — the thing a converge
+ * rule's `run()` action names — and that op's own env, if it declares one at
+ * all, isn't always the calling `ConvergeOp`'s env. `writeBlobToPath`'s own
+ * doc already establishes this generic-namespace pattern
+ * (`./build-ledger-store.ts`'s `_builds`); this is the same move for a
+ * second non-env top-level directory.
+ *
+ * `chant approve <op> <gate>` (`../cli/handlers/operator.ts`) is what
+ * appends here — issue #1485's "resolution is an out-of-band act that
+ * writes the counterpart fact". Per the issue's own leaning on open
+ * question 3 ("local trust in v1, signature as an additive follow-up"),
+ * this record is *not* itself an authorization check — anyone who can run
+ * `chant approve` locally can write one, the same trust boundary a local
+ * `git commit` already has. What it changes: `chant operator status` (and
+ * any future gate-aware dispatch retry) can tell a resolved gate from a
+ * still-pending one by finding a resolution newer than the tick that
+ * recorded it. It does **not** (v1) retroactively make a gated op's local
+ * dispatch succeed — the local executor still refuses any op containing a
+ * gate outright (`../op/local-executor.ts`'s `LocalGateUnsupportedError`),
+ * unconditionally, gate resolution or not. Wiring an approved gate back
+ * into the local executor's dispatch path is the GateStep semantic change
+ * issue #1485 itself flags as open question 1 ("suspension → fact... does
+ * it land as its own issue first? Leaning: yes, split it out") — deferred
+ * here for the same reason the issue defers it: it touches both the local
+ * executor and the generated Temporal workflow, and has migration impact on
+ * shipped ops. `chant approve` in v1 is the durable, queryable record of
+ * "this gate is cleared" that a human (or a future auto-resume path) reads;
+ * it is not itself the unblock.
+ */
+import { sortedJsonReplacer } from "../utils";
+import { readBlobFromPath, readPathSha, readBlobBySha, writeBlobToPath, RefCASConflictError } from "./git";
+
+const DIR = "_gates";
+const APPEND_RETRY_ATTEMPTS = 5;
+
+/** One immutable gate-resolution record. */
+export interface GateResolutionRecord {
+  /** Schema version, so an incompatible future shape is detected before being misread. */
+  version: 1;
+  /** The dispatched op the gate belongs to. */
+  op: string;
+  /** The gate's signal name (matches `ConvergeRuleOutcome.gateName`). */
+  gate: string;
+  /** Who resolved it — an actor name, the same convention `components release --actor` and `run signal --approver` use. */
+  resolvedBy: string;
+  /** ISO-8601 timestamp, caller-supplied (library code never calls `Date.now()` internally). */
+  timestamp: string;
+  /** Optional free-text context (e.g. a PR URL — "or a merged PR" is the issue's other resolution path; recording its link here keeps both paths visible from one ledger). */
+  note?: string;
+}
+
+export type GateResolutionInput = Omit<GateResolutionRecord, "version">;
+
+function filename(op: string): string {
+  return `${op}.jsonl`;
+}
+
+/** Append one immutable gate-resolution record. Does not push to the remote — call `pushLifecycle` (./git.ts) afterward, same two-step shape every other ledger write here uses. Retries on `RefCASConflictError` the same way `appendConvergeRecord` does (./converge-ledger.ts) — a concurrent writer to a different op's/env's file on the same orphan branch is the ordinary case, not an edge case. The baseline read must be `readPathSha` + `readBlobBySha` rather than `readBlobFromPath`, so the exact sha `existing` came from can be passed as `expectPriorPathSha` — see `writeBlobToPath` (./git.ts) for the race that closes. */
+export async function appendGateResolution(
+  input: GateResolutionInput,
+  opts?: { cwd?: string },
+): Promise<{ commit: string; record: GateResolutionRecord }> {
+  const record: GateResolutionRecord = { version: 1, ...input };
+  const json = JSON.stringify(record, sortedJsonReplacer);
+
+  let lastErr: unknown;
+  for (let attempt = 1; attempt <= APPEND_RETRY_ATTEMPTS; attempt++) {
+    try {
+      const priorSha = await readPathSha(DIR, filename(record.op), opts);
+      const existing = priorSha ? await readBlobBySha(priorSha, opts) : null;
+      const content = existing ? `${existing.replace(/\n$/, "")}\n${json}` : json;
+      const commit = await writeBlobToPath(DIR, filename(record.op), content, "Gate resolution record", {
+        ...opts,
+        expectPriorPathSha: priorSha,
+      });
+      return { commit, record };
+    } catch (err) {
+      if (!(err instanceof RefCASConflictError)) throw err;
+      lastErr = err;
+    }
+  }
+  throw lastErr;
+}
+
+/** Read every gate-resolution record for `op`, oldest first. Malformed lines are skipped, not thrown on, the same graceful-degradation stance `readConvergeLedger` takes. Returns `[]` (never throws) when `op` has no resolutions recorded yet. */
+export async function readGateResolutions(
+  op: string,
+  opts?: { cwd?: string },
+): Promise<{ records: GateResolutionRecord[]; malformed: number }> {
+  const content = await readBlobFromPath(DIR, filename(op), opts);
+  if (!content) return { records: [], malformed: 0 };
+
+  const lines = content.split("\n").map((l) => l.trim()).filter(Boolean);
+  const records: GateResolutionRecord[] = [];
+  let malformed = 0;
+  for (const line of lines) {
+    try {
+      const parsed = JSON.parse(line) as Partial<GateResolutionRecord>;
+      if (
+        parsed.version !== 1 ||
+        typeof parsed.op !== "string" ||
+        typeof parsed.gate !== "string" ||
+        typeof parsed.resolvedBy !== "string" ||
+        typeof parsed.timestamp !== "string"
+      ) {
+        malformed++;
+        continue;
+      }
+      records.push(parsed as GateResolutionRecord);
+    } catch {
+      malformed++;
+    }
+  }
+  return { records, malformed };
+}
+
+/** The most recent resolution for `gate` recorded after `sinceIso` (a gated tick's own timestamp) — what `chant operator status` uses to tell a resolved gate from a still-pending one. `undefined` when no such resolution exists. */
+export function latestResolutionSince(
+  records: GateResolutionRecord[],
+  gate: string,
+  sinceIso: string,
+): GateResolutionRecord | undefined {
+  const since = new Date(sinceIso).getTime();
+  let latest: GateResolutionRecord | undefined;
+  for (const r of records) {
+    if (r.gate !== gate) continue;
+    if (new Date(r.timestamp).getTime() < since) continue;
+    if (!latest || new Date(r.timestamp).getTime() >= new Date(latest.timestamp).getTime()) latest = r;
+  }
+  return latest;
+}