@intentius/chant 0.49.0 → 0.51.0

package/src/lifecycle/converge-ledger.ts

@@ -0,0 +1,179 @@
+/**
+ * Converge ledger (#1484) — the append-only record of what a `ConvergeOp`
+ * tick did, one line per tick, at `<env>/converge.jsonl` on the
+ * `chant/lifecycle` orphan branch. Same storage shape as the release ledger
+ * (./release-ledger.ts): immutable, append-only JSONL, reusing
+ * `writeBlobToPath`/`readBlobFromPath` (./git.ts) directly rather than a new
+ * git-plumbing path — the exact reuse `appendReleaseRecordLine` already
+ * demonstrates for a second filename under the same env directory.
+ *
+ * This is also where flap-damping state lives (issue: "consecutive-fire
+ * counts go in the ledger ... not process memory, so damping survives worker
+ * restarts"): each record's `firedRuleIds` names every rule whose predicate
+ * matched this tick, independent of what action was actually taken (run,
+ * report, or skipped for budget/flap reasons) — {@link consecutiveRuleFires}
+ * walks the ledger backward from the newest record and counts how many in a
+ * row include a given rule id, stopping at the first tick where it didn't
+ * fire (the symptom cleared).
+ */
+import { sortedJsonReplacer } from "../utils";
+import { readBlobFromPath, readPathSha, readBlobBySha, writeBlobToPath, RefCASConflictError } from "./git";
+
+const FILENAME = "converge.jsonl";
+
+/**
+ * Read-modify-append retry budget for {@link appendConvergeRecord} (#1485).
+ * `writeBlobToPath`'s ref write is now CAS-guarded (./git.ts) — a conflict
+ * (another writer, e.g. a second operator ticking a different env on the
+ * same orphan branch, updated the branch tip between our read and our
+ * write) throws `RefCASConflictError` instead of silently clobbering. This
+ * many attempts, re-reading the ledger fresh each time, absorbs that race
+ * rather than surfacing it as a tick failure — the whole point of the CAS
+ * guard is correctness, not a new way for a tick to fail.
+ */
+const APPEND_RETRY_ATTEMPTS = 5;
+
+/** One rule's outcome within a tick. */
+export interface ConvergeRuleOutcome {
+  ruleId: string;
+  /**
+   * What actually happened for this fired rule this tick. `"gated"` (#1485)
+   * is gate-as-fact: the dispatched op's own run hit a gate it can't clear
+   * on the local executor, and the tick records that as a terminal, durable
+   * fact — `gateName` names the gate — rather than treating it as a
+   * dispatch failure. Resolution is out-of-band (`chant approve <op>
+   * <gate>`, ./gate-ledger.ts, or a merged PR); the tick itself never
+   * blocks waiting for it.
+   */
+  action: "ran" | "reported" | "skipped-budget" | "skipped-flap" | "gated";
+  /** The dispatched Op name, for `action: "ran"` or `"gated"`. */
+  op?: string;
+  /** The gate's signal name, for `action: "gated"`. */
+  gateName?: string;
+  /** The report reason, for `action: "reported"` (including a flap-damped rule's forced report) — and the human-readable explanation for `action: "gated"`. */
+  reason?: string;
+}
+
+/** One immutable converge-tick record. */
+export interface ConvergeTickRecord {
+  /** Schema version, so an incompatible future shape is detected before being misread. */
+  version: 1;
+  /** The ConvergeOp's name (`OpConfig.name`). */
+  op: string;
+  env: string;
+  /** ISO-8601 timestamp, caller-supplied (same convention as `ReleaseRecord.timestamp` — library code never calls `Date.now()` internally). */
+  timestamp: string;
+  /** Every rule id whose predicate matched this tick, regardless of what action followed — the flap-damping input. */
+  firedRuleIds: string[];
+  /** Per-rule outcome, for every fired rule. */
+  outcomes: ConvergeRuleOutcome[];
+  /** Aggregate counts backing the tick's one log line. */
+  summary: {
+    drifted: number;
+    remediated: number;
+    reported: number;
+    skippedBudget: number;
+    skippedFlap: number;
+    unobserved: number;
+    adopted: number;
+    /** Rules whose dispatch hit a gate this tick (#1485) — a terminal, non-blocking fact; see `ConvergeRuleOutcome.action`'s doc. @default 0, so an older record without this field still reads as zero, not undefined. */
+    gated?: number;
+  };
+  /** The one human-readable log line this tick produced (issue: "one log line and one ledger record per tick"). */
+  log: string;
+}
+
+export type ConvergeTickRecordInput = Omit<ConvergeTickRecord, "version">;
+
+/**
+ * Append one immutable tick record. Does not push to the remote — call
+ * `pushLifecycle` (./git.ts) afterward, same two-step shape every other
+ * ledger write here uses.
+ *
+ * Retries the whole read-modify-write cycle (#1485) on `RefCASConflictError`
+ * — `writeBlobToPath`'s ref write is CAS-guarded, so a concurrent writer to
+ * a *different* env's file on the same orphan branch (two operators ticking
+ * two environments at once is the ordinary case, not an edge case) can lose
+ * the race and needs to re-read the branch tip and retry, not fail the
+ * tick. Each retry re-reads `existing` fresh, so it always appends onto
+ * whatever the other writer just committed rather than reintroducing a stale
+ * read. Exhausting the budget re-throws the conflict — a real, sustained
+ * pile-up of writers is a signal worth surfacing, not silently swallowing.
+ *
+ * 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 appendConvergeRecord(
+  input: ConvergeTickRecordInput,
+  opts?: { cwd?: string },
+): Promise<{ commit: string; record: ConvergeTickRecord }> {
+  const record: ConvergeTickRecord = { 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(record.env, FILENAME, opts);
+      const existing = priorSha ? await readBlobBySha(priorSha, opts) : null;
+      const content = existing ? `${existing.replace(/\n$/, "")}\n${json}` : json;
+      const commit = await writeBlobToPath(record.env, FILENAME, content, "Converge tick record", {
+        ...opts,
+        expectPriorPathSha: priorSha,
+      });
+      return { commit, record };
+    } catch (err) {
+      if (!(err instanceof RefCASConflictError)) throw err;
+      lastErr = err;
+    }
+  }
+  throw lastErr;
+}
+
+/** Read every tick record for `environment`, oldest first. Malformed lines are skipped, not thrown on — a corrupted or hand-edited ledger degrades gracefully, the same stance `readReleaseLedger` takes. */
+export async function readConvergeLedger(
+  environment: string,
+  opts?: { cwd?: string },
+): Promise<{ records: ConvergeTickRecord[]; malformed: number }> {
+  const content = await readBlobFromPath(environment, FILENAME, opts);
+  if (!content) return { records: [], malformed: 0 };
+
+  const lines = content.split("\n").map((l) => l.trim()).filter(Boolean);
+  const records: ConvergeTickRecord[] = [];
+  let malformed = 0;
+  for (const line of lines) {
+    try {
+      const parsed = JSON.parse(line) as Partial<ConvergeTickRecord>;
+      if (
+        parsed.version !== 1 ||
+        typeof parsed.op !== "string" ||
+        typeof parsed.env !== "string" ||
+        typeof parsed.timestamp !== "string" ||
+        !Array.isArray(parsed.firedRuleIds)
+      ) {
+        malformed++;
+        continue;
+      }
+      records.push(parsed as ConvergeTickRecord);
+    } catch {
+      malformed++;
+    }
+  }
+  return { records, malformed };
+}
+
+/**
+ * How many consecutive most-recent ticks (newest first) fired `ruleId`,
+ * stopping at the first tick where it did not — the count a rule's
+ * `flapThreshold` is compared against. `0` when the newest tick didn't fire
+ * it (including an empty ledger).
+ */
+export function consecutiveRuleFires(records: ConvergeTickRecord[], ruleId: string): number {
+  let count = 0;
+  for (let i = records.length - 1; i >= 0; i--) {
+    if (!records[i].firedRuleIds.includes(ruleId)) break;
+    count++;
+  }
+  return count;
+}

package/src/lifecycle/deep-diff.test.ts

@@ -1,5 +1,5 @@
 import { describe, test, expect } from "vitest";
-import { countPropertyDrift, diffDeep } from "./deep-diff";
+import { countPropertyDrift, diffDeep, type DeclaredDeepEntity } from "./deep-diff";
 import { UNRESOLVED, type NormalizedDeepObservation } from "../deep-observation";
 import type { BaselineLexicon } from "./observation-baseline";
 
@@ -202,3 +202,81 @@ describe("diffDeep — owning field manager (#1189)", () => {
     expect(change).not.toHaveProperty("owner");
   });
 });
+
+// #1443 — the declared-side counterpart of `owner`. Both sides of one
+// comparison get precise attribution, which is what makes the report actionable.
+describe("diffDeep — declared-side origin (#1443)", () => {
+  // Annotated, not `as const`: the annotation is what keeps `kind` narrowed to
+  // its literal, and it types the fixture as the production shape rather than
+  // whatever the literal happens to infer to.
+  const declared: Record<string, DeclaredDeepEntity> = {
+    web: {
+      type: "K8s::Apps::Deployment",
+      properties: { spec: { replicas: 2, template: { spec: { containers: [{ name: "app", image: "a:1" }] } } } },
+      pathOrigins: {
+        "": { kind: "composite", composite: "WebService", instance: "web" },
+        "spec.replicas": { kind: "build-param", params: ["tier"] },
+      },
+    },
+  };
+
+  test("reports the origin alongside the live owner", () => {
+    const result = diffDeep({
+      declared,
+      live: live({
+        web: {
+          type: "K8s::Apps::Deployment",
+          properties: { spec: { replicas: 5, template: { spec: { containers: [{ name: "app", image: "a:1" }] } } } },
+          fieldOwners: { "spec.replicas": "hpa-controller" },
+        },
+      }),
+    });
+    expect(result.drifted[0].changes[0]).toMatchObject({
+      path: "spec.replicas",
+      owner: "hpa-controller",
+      origin: { kind: "build-param", params: ["tier"] },
+    });
+  });
+
+  test("a path with no origin of its own inherits the nearest recorded ancestor", () => {
+    const result = diffDeep({
+      declared,
+      live: live({
+        web: {
+          type: "K8s::Apps::Deployment",
+          properties: { spec: { replicas: 2, template: { spec: { containers: [{ name: "app", image: "a:2" }] } } } },
+        },
+      }),
+    });
+    const change = result.drifted[0].changes.find((c) => c.path.includes("image"))!;
+    expect(change.origin).toEqual({ kind: "composite", composite: "WebService", instance: "web" });
+  });
+
+  test("is absent on an undeclared path — nothing in source produced it", () => {
+    const result = diffDeep({
+      declared,
+      live: live({
+        web: {
+          type: "K8s::Apps::Deployment",
+          properties: {
+            spec: { replicas: 2, template: { spec: { containers: [{ name: "app", image: "a:1" }] } } },
+            status: { observed: 1 },
+          },
+        },
+      }),
+    });
+    const change = result.drifted[0].changes.find((c) => c.path === "status.observed")!;
+    expect(change.kind).toBe("undeclared");
+    expect(change).not.toHaveProperty("origin");
+  });
+
+  test("is absent when the build recorded no path origins", () => {
+    // The run path, and a sandboxed child: absent means "could not record",
+    // not "nothing governs this field", so the key must not appear at all.
+    const result = diffDeep({
+      declared: { web: { type: "K8s::Apps::Deployment", properties: { spec: { replicas: 2 } } } },
+      live: live({ web: { type: "K8s::Apps::Deployment", properties: { spec: { replicas: 5 } } } }),
+    });
+    expect(result.drifted[0].changes[0]).not.toHaveProperty("origin");
+  });
+});

package/src/lifecycle/deep-diff.ts

@@ -29,6 +29,7 @@ import {
   type DeepNormalizationHooks,
   type NormalizedDeepObservation,
 } from "../deep-observation";
+import { originOfPath, type PathOrigin } from "../provenance";
 import type { UnobservedResource } from "./live-diff";
 import { acceptedDeviation, type BaselineLexicon } from "./observation-baseline";
 
@@ -70,6 +71,18 @@ export interface PropertyDrift {
    * with no per-field ownership, which is every substrate but k8s.
    */
   owner?: string;
+  /**
+   * What produced this path on the DECLARED side (#1443) — the counterpart of
+   * {@link owner}, and the reason the two are reported together: "owned live by
+   * `hpa-controller`, governed in source by the `tier` parameter" says where
+   * each half of a disagreement has to be fixed, which neither half says alone.
+   *
+   * Resolved by longest prefix from the entity's recorded path origins, so a
+   * field inside a keyed list element inherits the origin recorded for the
+   * list. Absent when the build recorded none — the run path, and a sandboxed
+   * child, have no expression to attribute (see `EntityProvenance.paths`).
+   */
+  origin?: PathOrigin;
 }
 
 /** Property-level drift for one declared entity. */
@@ -100,6 +113,11 @@ export interface DeepDiffResult {
 export interface DeclaredDeepEntity {
   type: string;
   properties: Record<string, unknown>;
+  /**
+   * The entity's recorded path origins (#1443), as `EntityProvenance.paths`.
+   * Omit for a build that recorded none.
+   */
+  pathOrigins?: Record<string, PathOrigin>;
 }
 
 export interface DiffDeepInput {
@@ -188,12 +206,17 @@ export function diffDeep(input: DiffDeepInput): DeepDiffResult {
       // meaningful for a path that exists live — an `absent` drift has no live
       // field for anyone to own.
       const owner = hasLive ? liveEntity.fieldOwners?.[path] : undefined;
+      // The declared-side counterpart (#1443). Only meaningful for a path
+      // source actually declares — an `undeclared` drift has no authored
+      // expression for anything to have produced.
+      const origin = hasDeclared ? originOfPath(declaredEntity.pathOrigins, path) : undefined;
       const drift: PropertyDrift = {
         path,
         kind,
         ...(hasDeclared ? { declared: declaredValue } : {}),
         ...(hasLive ? { live: liveValue } : {}),
         ...(owner ? { owner } : {}),
+        ...(origin ? { origin } : {}),
       };
 
       const acceptedEntry = acceptedDeviation(baseline, name, path);

package/src/lifecycle/deep-observe.ts

@@ -27,11 +27,21 @@ import {
   type NormalizedDeepObservation,
 } from "../deep-observation";
 import { unobservedAll, type UnobservedEntity } from "../observation";
+import type { PathOrigin } from "../provenance";
 import { diffDeep, type DeclaredDeepEntity, type DeepDiffResult } from "./deep-diff";
 import type { BaselineLexicon } from "./observation-baseline";
 
-/** Declared entities for one lexicon, in the shape the observe paths pass around. */
-export type DeclaredEntities = Map<string, { entityType: string; props: Record<string, unknown> }>;
+/**
+ * Declared entities for one lexicon, in the shape the observe paths pass around.
+ *
+ * `pathOrigins` (#1443) rides alongside `props` rather than being read off the
+ * entity, because callers rebuild this map as plain objects and the symbol-keyed
+ * provenance channel does not survive that copy.
+ */
+export type DeclaredEntities = Map<
+  string,
+  { entityType: string; props: Record<string, unknown>; pathOrigins?: Record<string, PathOrigin> }
+>;
 
 export interface DeepObserveOptions {
   environment: string;
@@ -138,6 +148,7 @@ export function diffDeepObservation(
         hooks,
         counterpartPaths: livePaths,
       }),
+      ...(entity.pathOrigins ? { pathOrigins: entity.pathOrigins } : {}),
     };
     if (liveEntity) {
       normalizedLive[name] = {

package/src/lifecycle/disruption.test.ts

@@ -0,0 +1,186 @@
+import { describe, test, expect } from "vitest";
+import {
+  annotateDisruption,
+  disruptionNotices,
+  summarizeDisruption,
+  worstDisruption,
+  type DisruptionClassifier,
+} from "./disruption";
+import { renderChangeSet, type ChangeSet, type ChangeSetEntry } from "./change-set";
+
+function entry(overrides: Partial<ChangeSetEntry> = {}): ChangeSetEntry {
+  return {
+    name: "db",
+    type: "AWS::RDS::DBInstance",
+    lexicon: "aws",
+    action: "update",
+    evidence: { declared: true, inSnapshot: true, live: true, observed: true },
+    deltas: [{ path: "attributes.Engine", oldValue: "postgres", newValue: "mysql" }],
+    ownership: "unknown",
+    ...overrides,
+  };
+}
+
+function set(entries: ChangeSetEntry[]): ChangeSet {
+  return { env: "prod", entries };
+}
+
+describe("annotateDisruption (#1665)", () => {
+  test("no classifier degrades every update to unknown, never in-place", async () => {
+    const out = await annotateDisruption(set([entry()]), "prod", undefined);
+    expect(out.entries[0].disruption).toBe("unknown");
+    expect(out.entries[0].disruptionDetail).toContain("aws lexicon does not classify disruption");
+  });
+
+  test("a lexicon's verdict rides the entry", async () => {
+    const classify: DisruptionClassifier = () => ({
+      db: { disruption: "replace", because: ["attributes.Engine"], detail: "Engine is create-only" },
+    });
+    const out = await annotateDisruption(set([entry()]), "prod", classify);
+    expect(out.entries[0]).toMatchObject({
+      disruption: "replace",
+      disruptionBecause: ["attributes.Engine"],
+      disruptionDetail: "Engine is create-only",
+    });
+  });
+
+  test("a name the classifier said nothing about is unknown", async () => {
+    const classify: DisruptionClassifier = () => ({});
+    const out = await annotateDisruption(set([entry()]), "prod", classify);
+    expect(out.entries[0].disruption).toBe("unknown");
+    expect(out.entries[0].disruptionDetail).toContain("returned no verdict");
+  });
+
+  // The guard that makes `in-place` trustworthy: a lexicon cannot smuggle a
+  // level in that core does not recognise, and a bogus one is never treated as
+  // the safe end of the scale.
+  test("a level outside the vocabulary is rejected into unknown", async () => {
+    const classify = (() => ({
+      db: { disruption: "totally-fine", detail: "trust me" },
+    })) as unknown as DisruptionClassifier;
+    const out = await annotateDisruption(set([entry()]), "prod", classify);
+    expect(out.entries[0].disruption).toBe("unknown");
+    expect(out.entries[0].disruptionDetail).toContain("totally-fine");
+  });
+
+  test("a classifier that throws leaves unknown, and the plan survives", async () => {
+    const classify: DisruptionClassifier = () => {
+      throw new Error("registry missing");
+    };
+    const out = await annotateDisruption(set([entry()]), "prod", classify);
+    expect(out.entries[0].disruption).toBe("unknown");
+    expect(out.entries[0].disruptionDetail).toContain("registry missing");
+  });
+
+  test("an async classifier is awaited", async () => {
+    const classify: DisruptionClassifier = async () => ({
+      db: { disruption: "in-place", detail: "no create-only property changed" },
+    });
+    const out = await annotateDisruption(set([entry()]), "prod", classify);
+    expect(out.entries[0].disruption).toBe("in-place");
+  });
+
+  test("only update entries are classified", async () => {
+    const classify: DisruptionClassifier = ({ changes }) => {
+      expect(changes.map((c) => c.name)).toEqual(["db"]);
+      return { db: { disruption: "destroy" } };
+    };
+    const out = await annotateDisruption(
+      set([
+        entry(),
+        entry({ name: "bucket", action: "create", deltas: undefined }),
+        entry({ name: "queue", action: "delete", deltas: undefined }),
+      ]),
+      "prod",
+      classify,
+    );
+    const byName = Object.fromEntries(out.entries.map((e) => [e.name, e]));
+    expect(byName.db.disruption).toBe("destroy");
+    expect(byName.bucket.disruption).toBeUndefined();
+    expect(byName.queue.disruption).toBeUndefined();
+  });
+
+  test("a set with no updates is returned untouched, and no classifier is called", async () => {
+    let called = false;
+    const cs = set([entry({ action: "noop", deltas: undefined })]);
+    const out = await annotateDisruption(cs, "prod", () => {
+      called = true;
+      return {};
+    });
+    expect(out).toBe(cs);
+    expect(called).toBe(false);
+  });
+
+  test("the input change set is not mutated", async () => {
+    const cs = set([entry()]);
+    await annotateDisruption(cs, "prod", () => ({ db: { disruption: "replace" } }));
+    expect(cs.entries[0].disruption).toBeUndefined();
+  });
+});
+
+describe("summaries and notices", () => {
+  const classified = set([
+    entry({ name: "db", disruption: "destroy" }),
+    entry({ name: "sg", disruption: "replace" }),
+    entry({ name: "tags", disruption: "in-place" }),
+    entry({ name: "mystery", disruption: "unknown" }),
+    entry({ name: "bucket", action: "noop", disruption: undefined, deltas: undefined }),
+  ]);
+
+  test("summarizeDisruption counts update entries only", () => {
+    expect(summarizeDisruption(classified)).toEqual({
+      "in-place": 1,
+      rolling: 0,
+      replace: 1,
+      destroy: 1,
+      unknown: 1,
+    });
+  });
+
+  test("worstDisruption ranks unknown above every confident verdict", () => {
+    expect(worstDisruption(classified)).toBe("unknown");
+    expect(worstDisruption(set([entry({ disruption: "in-place" })]))).toBe("in-place");
+    expect(worstDisruption(set([entry({ action: "noop", disruption: undefined })]))).toBeUndefined();
+  });
+
+  test("notices name the replacing and the unclassified rows", () => {
+    const notices = disruptionNotices(classified);
+    expect(notices[0]).toContain("2 update(s) replace the resource");
+    expect(notices[0]).toContain("1 of them by deleting it first");
+    expect(notices[1]).toContain("1 update(s) could not be classified");
+  });
+
+  test("a clean plan produces no notices", () => {
+    expect(disruptionNotices(set([entry({ disruption: "in-place" })]))).toEqual([]);
+  });
+});
+
+describe("renderChangeSet with disruption", () => {
+  test("the header, the row, and the forcing delta all say it", () => {
+    const out = renderChangeSet(
+      set([
+        entry({
+          disruption: "replace",
+          disruptionBecause: ["attributes.Engine"],
+          disruptionDetail: "Engine is create-only",
+          deltas: [
+            { path: "attributes.Engine", oldValue: "postgres", newValue: "mysql" },
+            { path: "attributes.AllocatedStorage", oldValue: 20, newValue: 40 },
+          ],
+        }),
+      ]),
+    );
+    expect(out).toContain("Disruption: 1 replace");
+    expect(out).toContain("UPDATE (disruption from the lexicon that owns the spec");
+    expect(out).toContain("db (AWS::RDS::DBInstance) — replace: Engine is create-only");
+    expect(out).toContain("! attributes.Engine:");
+    expect(out).toContain("  attributes.AllocatedStorage:");
+    expect(out).not.toContain("! attributes.AllocatedStorage");
+  });
+
+  test("an unclassified plan renders the plain UPDATE header", () => {
+    const out = renderChangeSet(set([entry({ disruption: undefined })]));
+    expect(out).toContain("\nUPDATE:");
+    expect(out).not.toContain("Disruption:");
+  });
+});