@intentius/chant 0.49.0 → 0.51.0

package/src/lifecycle/assert-live.test.ts

@@ -0,0 +1,125 @@
+import { describe, test, expect } from "vitest";
+import { createMockPlugin, staticObservation } from "@intentius/chant-test-utils";
+import { observation } from "../observation";
+import { assertLiveEntity, LiveAssertionError, UnobservedAssertionError } from "./assert-live";
+import type { ResourceMetadata } from "../lexicon";
+
+const MARKER = { stack: "shop", env: "test-suite-abc123" };
+
+const meta = (overrides: Partial<ResourceMetadata> = {}): ResourceMetadata => ({
+  type: "Mock::Queue",
+  status: "READY",
+  marker: MARKER,
+  ownership: "owned",
+  ...overrides,
+});
+
+const call = (opts: Partial<Parameters<typeof assertLiveEntity>[0]> = {}) =>
+  assertLiveEntity({
+    plugin: createMockPlugin(),
+    name: "taskQueue",
+    entityType: "Mock::Queue",
+    props: {},
+    buildOutput: "",
+    environment: MARKER.env,
+    marker: MARKER,
+    ...opts,
+  });
+
+describe("assertLiveEntity", () => {
+  test("resolves the metadata for an observed, marker-matched entity", async () => {
+    const plugin = createMockPlugin({ describeResources: staticObservation({ taskQueue: meta() }) });
+    await expect(call({ plugin })).resolves.toEqual(meta());
+  });
+
+  test("checks status when given, passes when it matches", async () => {
+    const plugin = createMockPlugin({ describeResources: staticObservation({ taskQueue: meta({ status: "READY" }) }) });
+    await expect(call({ plugin, status: "READY" })).resolves.toEqual(meta());
+  });
+
+  test("throws naming the entity when observed absent", async () => {
+    const plugin = createMockPlugin({ describeResources: staticObservation({}) });
+    await expect(call({ plugin })).rejects.toThrow(LiveAssertionError);
+    await expect(call({ plugin })).rejects.toThrow(/taskQueue.*observed absent/s);
+  });
+
+  test("throws UnobservedAssertionError, not a plain failure, when NOT-OBSERVED", async () => {
+    const plugin = createMockPlugin({
+      describeResources: staticObservation({}, { taskQueue: { reason: "no-credentials", type: "Mock::Queue" } }),
+    });
+    const err = await call({ plugin }).then(
+      () => undefined,
+      (e: unknown) => e,
+    );
+    expect(err).toBeInstanceOf(UnobservedAssertionError);
+    expect(err).not.toBeInstanceOf(LiveAssertionError);
+    expect((err as UnobservedAssertionError).reason).toBe("no-credentials");
+  });
+
+  test("a thrown describeResources degrades to NOT-OBSERVED read-failed, never a silent absence", async () => {
+    const plugin = createMockPlugin({
+      describeResources: async () => {
+        throw new Error("ECONNREFUSED");
+      },
+    });
+    const err = await call({ plugin }).then(
+      () => undefined,
+      (e: unknown) => e,
+    );
+    expect(err).toBeInstanceOf(UnobservedAssertionError);
+    expect((err as UnobservedAssertionError).reason).toBe("read-failed");
+    expect((err as UnobservedAssertionError).detail).toContain("ECONNREFUSED");
+  });
+
+  test("a lexicon with no describeResources is NOT-OBSERVED, unsupported-kind", async () => {
+    const plugin = createMockPlugin();
+    const err = await call({ plugin }).then(
+      () => undefined,
+      (e: unknown) => e,
+    );
+    expect(err).toBeInstanceOf(UnobservedAssertionError);
+    expect((err as UnobservedAssertionError).reason).toBe("unsupported-kind");
+  });
+
+  test("throws when the observed marker names a foreign stack", async () => {
+    const plugin = createMockPlugin({
+      describeResources: staticObservation({ taskQueue: meta({ marker: { stack: "other-stack", env: MARKER.env } }) }),
+    });
+    await expect(call({ plugin })).rejects.toThrow(/not this deploy's/);
+  });
+
+  test("throws when the observed marker names a foreign env — a same-named leftover from another run", async () => {
+    const plugin = createMockPlugin({
+      describeResources: staticObservation({ taskQueue: meta({ marker: { stack: MARKER.stack, env: "test-other-999999" } }) }),
+    });
+    await expect(call({ plugin })).rejects.toThrow(LiveAssertionError);
+  });
+
+  test("throws when the entity is confirmed foreign (no marker, ownership foreign)", async () => {
+    const plugin = createMockPlugin({
+      describeResources: staticObservation({
+        taskQueue: meta({ marker: undefined, ownership: "foreign" }),
+      }),
+    });
+    await expect(call({ plugin })).rejects.toThrow(/not this deploy's/);
+  });
+
+  test("passes through an entity whose lexicon has no marker channel (ownership unknown, no marker) rather than always failing", async () => {
+    const plugin = createMockPlugin({
+      describeResources: staticObservation({
+        taskQueue: meta({ marker: undefined, ownership: "unknown" }),
+      }),
+    });
+    await expect(call({ plugin })).resolves.toEqual(meta({ marker: undefined, ownership: "unknown" }));
+  });
+
+  test("throws a status mismatch after identity is confirmed", async () => {
+    const plugin = createMockPlugin({ describeResources: staticObservation({ taskQueue: meta({ status: "PENDING" }) }) });
+    await expect(call({ plugin, status: "READY" })).rejects.toThrow(/status "PENDING"/);
+  });
+
+  test("uses the observation() envelope form identically to the bare-map form", async () => {
+    const plugin = createMockPlugin({ describeResources: async () => observation({ taskQueue: meta() }) });
+    await expect(call({ plugin })).resolves.toEqual(meta());
+  });
+});

package/src/lifecycle/assert-live.ts

@@ -0,0 +1,154 @@
+/**
+ * assertLive (#1857) — the read half of the test harness (#1224):
+ * observation-backed assertions against a live deploy, for exactly one
+ * declared entity at a time. Same primitive teardown.ts's fallback path
+ * uses — `describeResources` — turned into a pass/throw instead of a
+ * would-delete set.
+ *
+ * The observation contract (#1089) draws a hard line between OBSERVED-ABSENT
+ * and NOT-OBSERVED: a declared entity the read could not cover is never the
+ * same as one confirmed missing. `assertLiveEntity` preserves that line by
+ * construction — NOT-OBSERVED throws {@link UnobservedAssertionError}, a type
+ * distinct from the {@link LiveAssertionError} an observed-absent, foreign,
+ * or status-mismatched verdict throws, so a caller can tell "could not tell"
+ * from "confirmed wrong" without parsing a message.
+ *
+ * Marker verification is best-effort by the same logic {@link
+ * ResourceMetadata.marker}'s own contract states: a lexicon with no marker
+ * channel on this read path (aws's thin `describeResources`, `ownership:
+ * "unknown"`) reports no marker at all, which is not the same claim as
+ * "foreign". Enforcing a match whenever the channel exists — a present
+ * mismatch, or `ownership: "foreign"` with no marker to show — catches the
+ * case the harness cares about (a same-named leftover from another env);
+ * an absent channel is passed through unverified rather than making every
+ * lexicon without one unusable.
+ */
+
+import { normalizeObservation, unobservedAll, unobservedReasonText, type UnobservedReason } from "../observation";
+import type { ObservationLexicon, ResourceMetadata } from "../lexicon";
+import type { OwnershipMarker } from "../ownership";
+
+/**
+ * Thrown by {@link assertLiveEntity} for a confirmed failure: observed
+ * absent, a marker that names another stack/env, a resource confirmed
+ * foreign, or a status mismatch. Never thrown for NOT-OBSERVED — see {@link
+ * UnobservedAssertionError}.
+ */
+export class LiveAssertionError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "LiveAssertionError";
+  }
+}
+
+/**
+ * Thrown when the entity is NOT-OBSERVED (#1089) rather than confirmed
+ * present or absent. Kept as its own type, not a flag on {@link
+ * LiveAssertionError}: a suite (or a CI policy) that wants to fail loudly on
+ * "could not tell" but treat it differently from a confirmed miss can catch
+ * this one specifically.
+ */
+export class UnobservedAssertionError extends Error {
+  constructor(
+    public readonly entity: string,
+    public readonly reason: UnobservedReason,
+    public readonly detail?: string,
+  ) {
+    super(
+      `assertLive("${entity}") is NOT-OBSERVED — ${unobservedReasonText(reason)}` +
+        `${detail ? `: ${detail}` : ""}. An entity chant could not read is never the same as one confirmed absent.`,
+    );
+    this.name = "UnobservedAssertionError";
+  }
+}
+
+export interface AssertLiveOptions {
+  /** Expected `ResourceMetadata.status`, where the lexicon reports one. Skipped when omitted. */
+  status?: string;
+}
+
+export interface AssertLiveEntityOptions extends AssertLiveOptions {
+  plugin: ObservationLexicon;
+  /** chant entity name — the key to assert on. */
+  name: string;
+  entityType: string;
+  props: Record<string, unknown>;
+  /** This lexicon's own built output for the deploy, or `""` when none was built. */
+  buildOutput: string;
+  environment: string;
+  /** This deploy's identity — the marker an observed resource is checked against. */
+  marker: OwnershipMarker;
+}
+
+/** True when `meta` names a different stack/env than `marker`, on whichever signal it carries. */
+function isConfirmedForeign(meta: ResourceMetadata, marker: OwnershipMarker): boolean {
+  if (meta.marker) return meta.marker.stack !== marker.stack || meta.marker.env !== marker.env;
+  return meta.ownership === "foreign";
+}
+
+/**
+ * Assert one declared entity is live: observed present in `environment`, not
+ * a confirmed-foreign resource, and — when `status` is given — reporting
+ * that status. Resolves to the entity's {@link ResourceMetadata} on success.
+ *
+ * Throws {@link UnobservedAssertionError} for NOT-OBSERVED. Throws {@link
+ * LiveAssertionError} for observed-absent, a confirmed-foreign identity, or a
+ * status mismatch.
+ */
+export async function assertLiveEntity(opts: AssertLiveEntityOptions): Promise<ResourceMetadata> {
+  const { plugin, name, entityType, props, buildOutput, environment, marker, status } = opts;
+
+  if (!plugin.describeResources) {
+    throw new UnobservedAssertionError(
+      name,
+      "unsupported-kind",
+      `the "${plugin.name}" lexicon implements no describeResources`,
+    );
+  }
+
+  let observed;
+  try {
+    observed = normalizeObservation(
+      await plugin.describeResources({
+        environment,
+        buildOutput,
+        entityNames: [name],
+        entities: new Map([[name, { entityType, props }]]),
+      }),
+    );
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    observed = {
+      resources: {},
+      unobserved: unobservedAll([name], "read-failed", detail, { [name]: entityType }),
+      queried: {},
+      notes: [],
+    };
+  }
+
+  const unobserved = observed.unobserved[name];
+  if (unobserved) throw new UnobservedAssertionError(name, unobserved.reason, unobserved.detail);
+
+  const meta = observed.resources[name];
+  if (!meta) {
+    throw new LiveAssertionError(
+      `assertLive("${name}"): observed absent — chant looked and "${environment}" reported no such resource.`,
+    );
+  }
+
+  if (isConfirmedForeign(meta, marker)) {
+    const found = meta.marker ? `{ stack: "${meta.marker.stack}", env: "${meta.marker.env ?? ""}" }` : "no chant marker";
+    throw new LiveAssertionError(
+      `assertLive("${name}"): observed, but it is not this deploy's — carries ${found}, not ` +
+        `{ stack: "${marker.stack}", env: "${marker.env ?? ""}" }. A same-named resource from another stack or env cannot satisfy this assertion.`,
+    );
+  }
+
+  if (status !== undefined && meta.status !== status) {
+    throw new LiveAssertionError(
+      `assertLive("${name}", { status: "${status}" }): observed with status "${meta.status}".`,
+    );
+  }
+
+  return meta;
+}

package/src/lifecycle/change-set.ts

@@ -14,6 +14,7 @@
  */
 import { diffLive, type AttributeChange, type DiffLiveInput } from "./live-diff";
 import { unobservedReasonText, type UnobservedReason } from "../observation";
+import { renderDisruption, summarizeDisruption, type Disruption } from "./disruption";
 
 /**
  * What the projection proposes for a single resource.
@@ -129,6 +130,22 @@ export interface ChangeSetEntry {
   effectReason?: EffectFireReason;
   /** Human-readable backing for `effectReason` (the digests that differ, the unresolved path). */
   effectDetail?: string;
+  /**
+   * How much applying this change hurts (#1665) — in-place / rolling / replace
+   * / destroy / unknown. Set on `update` entries only: every other action
+   * carries its blast radius in the action itself.
+   *
+   * The verdict comes from the lexicon that owns the spec
+   * ({@link LexiconPlugin.classifyDisruption}), never from core, which has no
+   * per-provider replacement rules and must not grow any. `unknown` is the
+   * default and the only fallback — read it as "nobody could say", never as
+   * "probably in place".
+   */
+  disruption?: Disruption;
+  /** The attribute paths that forced `disruption` (#1665). */
+  disruptionBecause?: string[];
+  /** Human-readable backing for `disruption` — the spec knowledge behind the call, or why there is none. */
+  disruptionDetail?: string;
 }
 
 export interface ChangeSet {
@@ -314,6 +331,16 @@ export function renderChangeSet(cs: ChangeSet): string {
   const header = ACTION_ORDER.map((a) => `${counts[a]} ${a}`).join(", ");
   const lines: string[] = [`Plan for ${cs.env}: ${header}`];
 
+  // Disruption (#1665) rides the header too, so the one number that says how
+  // much this plan hurts is visible without reading every row.
+  const disruption = summarizeDisruption(cs);
+  const disruptionParts = (Object.entries(disruption) as Array<[Disruption, number]>)
+    .filter(([, n]) => n > 0)
+    .map(([level, n]) => `${n} ${level}`);
+  if (disruptionParts.length > 0) {
+    lines.push(`Disruption: ${disruptionParts.join(", ")}`);
+  }
+
   for (const action of ACTION_ORDER) {
     const group = cs.entries.filter((e) => e.action === action);
     if (group.length === 0) continue;
@@ -324,7 +351,9 @@ export function renderChangeSet(cs: ChangeSet): string {
           ? "\nRUNTIME (owned by a declared resource; not drift, never a delete/adopt candidate):"
           : action === "effect"
             ? "\nEFFECT (receipt absent or stale; the effect step fires — the generic apply never writes a receipt):"
-            : `\n${action.toUpperCase()}:`,
+            : action === "update" && disruptionParts.length > 0
+              ? "\nUPDATE (disruption from the lexicon that owns the spec; unknown means nobody could say, not that it is safe):"
+              : `\n${action.toUpperCase()}:`,
     );
     for (const e of group) {
       if (e.action === "effect") {
@@ -339,9 +368,12 @@ export function renderChangeSet(cs: ChangeSet): string {
         ? ` — ${unobservedReasonText(e.unobservedReason)}${e.unobservedDetail ? `: ${e.unobservedDetail}` : ""}`
         : "";
       const owner = e.runtimeOwner ? ` — owned by ${e.runtimeOwner}` : "";
-      lines.push(`  ${e.name}${e.type ? ` (${e.type})` : ""}${own}${why}${owner}`);
+      lines.push(`  ${e.name}${e.type ? ` (${e.type})` : ""}${own}${why}${owner}${renderDisruption(e)}`);
+      const forced = new Set(e.disruptionBecause ?? []);
       for (const d of e.deltas ?? []) {
-        lines.push(`      ${d.path}: ${fmt(d.oldValue)} → ${fmt(d.newValue)}`);
+        // A path the verdict rests on is marked, so a `replace` row says which
+        // of five changed properties caused it.
+        lines.push(`      ${forced.has(d.path) ? "! " : ""}${d.path}: ${fmt(d.oldValue)} → ${fmt(d.newValue)}`);
       }
     }
   }

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

@@ -0,0 +1,199 @@
+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 {
+  appendConvergeRecord,
+  readConvergeLedger,
+  consecutiveRuleFires,
+  type ConvergeTickRecordInput,
+  type ConvergeTickRecord,
+} from "./converge-ledger";
+
+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);
+}
+
+function makeInput(overrides?: Partial<ConvergeTickRecordInput>): ConvergeTickRecordInput {
+  return {
+    op: "fountain-converge",
+    env: "staging",
+    timestamp: "2026-01-01T00:00:00.000Z",
+    firedRuleIds: [],
+    outcomes: [],
+    summary: { drifted: 0, remediated: 0, reported: 0, skippedBudget: 0, skippedFlap: 0, unobserved: 0, adopted: 0 },
+    log: "converge(staging): drifted=0 remediated=0 reported=0 skipped-budget=0 skipped-flap=0 unobserved=0 adopted=0",
+    ...overrides,
+  };
+}
+
+describe("converge-ledger", () => {
+  describe("appendConvergeRecord / readConvergeLedger", () => {
+    test("round-trips a single record", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        const { record } = await appendConvergeRecord(makeInput(), { cwd: dir });
+        expect(record.version).toBe(1);
+
+        const { records, malformed } = await readConvergeLedger("staging", { cwd: dir });
+        expect(malformed).toBe(0);
+        expect(records).toEqual([record]);
+      });
+    });
+
+    test("appends without clobbering prior records", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        await appendConvergeRecord(makeInput({ timestamp: "2026-01-01T00:00:00.000Z" }), { cwd: dir });
+        await appendConvergeRecord(makeInput({ timestamp: "2026-01-01T00:10:00.000Z" }), { cwd: dir });
+        await appendConvergeRecord(makeInput({ timestamp: "2026-01-01T00:20:00.000Z" }), { cwd: dir });
+
+        const { records } = await readConvergeLedger("staging", { cwd: dir });
+        expect(records).toHaveLength(3);
+        expect(records.map((r) => r.timestamp)).toEqual([
+          "2026-01-01T00:00:00.000Z",
+          "2026-01-01T00:10:00.000Z",
+          "2026-01-01T00:20:00.000Z",
+        ]);
+      });
+    });
+
+    test("empty ledger for an environment with no records — never throws", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        const { records, malformed } = await readConvergeLedger("nowhere", { cwd: dir });
+        expect(records).toEqual([]);
+        expect(malformed).toBe(0);
+      });
+    });
+
+    test("skips malformed lines but reports the count", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        await appendConvergeRecord(makeInput(), { cwd: dir });
+        // Directly corrupt the ledger by writing a second, non-JSON line via a
+        // second append whose "record" is actually malformed content — simulate
+        // by reading, then re-appending raw garbage through the same git path
+        // a hand-edited ledger would produce. We reuse appendConvergeRecord's
+        // underlying git plumbing indirectly by writing a second valid record,
+        // then asserting the reader tolerates an out-of-schema line mixed in
+        // at read time isn't directly expressible via the public API, so this
+        // test instead exercises the schema-validation branch: a record
+        // missing `firedRuleIds` is treated as malformed.
+        const { readBlobFromPath, writeBlobToPath } = await import("./git");
+        const existing = await readBlobFromPath("staging", "converge.jsonl", { cwd: dir });
+        const corrupted = `${existing}\n${JSON.stringify({ version: 1, op: "x", env: "staging" })}`;
+        await writeBlobToPath("staging", "converge.jsonl", corrupted, "corrupt", { cwd: dir });
+
+        const { records, malformed } = await readConvergeLedger("staging", { cwd: dir });
+        expect(records).toHaveLength(1);
+        expect(malformed).toBe(1);
+      });
+    });
+  });
+
+  describe("consecutiveRuleFires", () => {
+    function rec(firedRuleIds: string[]): ConvergeTickRecord {
+      return { ...makeInput({ firedRuleIds }), version: 1 };
+    }
+
+    test("0 for an empty ledger", () => {
+      expect(consecutiveRuleFires([], "r1")).toBe(0);
+    });
+
+    test("0 when the newest tick didn't fire it", () => {
+      const records = [rec(["r1"]), rec(["r1"]), rec([])];
+      expect(consecutiveRuleFires(records, "r1")).toBe(0);
+    });
+
+    test("counts consecutive fires from the newest tick backward", () => {
+      const records = [rec([]), rec(["r1"]), rec(["r1"]), rec(["r1"])];
+      expect(consecutiveRuleFires(records, "r1")).toBe(3);
+    });
+
+    test("stops counting at the first non-firing tick, scanning backward", () => {
+      const records = [rec(["r1"]), rec([]), rec(["r1"]), rec(["r1"])];
+      expect(consecutiveRuleFires(records, "r1")).toBe(2);
+    });
+
+    test("only counts the named rule, ignoring others", () => {
+      const records = [rec(["r2"]), rec(["r1", "r2"])];
+      expect(consecutiveRuleFires(records, "r1")).toBe(1);
+      expect(consecutiveRuleFires(records, "r2")).toBe(2);
+    });
+  });
+
+  // ── Gate-as-fact (#1485) ───────────────────────────────────────────────────
+
+  describe("gated outcome", () => {
+    test("round-trips a 'gated' outcome with its gateName, and a gated count in the summary", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        const { record } = await appendConvergeRecord(
+          makeInput({
+            firedRuleIds: ["drift-apply"],
+            outcomes: [
+              {
+                ruleId: "drift-apply",
+                action: "gated",
+                op: "fountain-apply",
+                gateName: "rollout-gate",
+                reason: 'dispatch of "fountain-apply" hit gate "rollout-gate"',
+              },
+            ],
+            summary: { drifted: 1, remediated: 0, reported: 0, skippedBudget: 0, skippedFlap: 0, unobserved: 0, adopted: 0, gated: 1 },
+          }),
+          { cwd: dir },
+        );
+        expect(record.outcomes[0]).toEqual({
+          ruleId: "drift-apply",
+          action: "gated",
+          op: "fountain-apply",
+          gateName: "rollout-gate",
+          reason: 'dispatch of "fountain-apply" hit gate "rollout-gate"',
+        });
+        expect(record.summary.gated).toBe(1);
+
+        const { records } = await readConvergeLedger("staging", { cwd: dir });
+        expect(records).toEqual([record]);
+      });
+    });
+  });
+
+  // ── Concurrent local writers (#1485) ────────────────────────────────────────
+
+  describe("appendConvergeRecord retries on RefCASConflictError", () => {
+    test("a concurrent writer to a different env's file on the same orphan branch doesn't lose either write", async () => {
+      await withTestDir(async (dir) => {
+        await initRepo(dir);
+        // Two "operators" appending to two different environments' ledgers on
+        // the same orphan branch, interleaved so their internal git-plumbing
+        // reads race — this is exactly the scenario `writeBlobToPath`'s CAS
+        // guard (chant #1485) now protects against, and `appendConvergeRecord`
+        // retries through rather than surfacing to the caller.
+        const [a, b] = await Promise.all([
+          appendConvergeRecord(makeInput({ env: "staging", op: "staging-converge" }), { cwd: dir }),
+          appendConvergeRecord(makeInput({ env: "prod", op: "prod-converge" }), { cwd: dir }),
+        ]);
+        expect(a.record.env).toBe("staging");
+        expect(b.record.env).toBe("prod");
+
+        const staging = await readConvergeLedger("staging", { cwd: dir });
+        const prod = await readConvergeLedger("prod", { cwd: dir });
+        expect(staging.records).toHaveLength(1);
+        expect(prod.records).toHaveLength(1);
+      });
+    });
+  });
+});