@intentius/chant 0.50.0 → 0.52.0

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 {
@@ -308,24 +325,65 @@ export function gitlabMrReport(cs: ChangeSet): GitlabMrReport {
   return { create: counts.create, update: counts.update, delete: counts.delete };
 }
 
+/**
+ * Warning a plan should print when it carries a hole — a declared entity the
+ * lexicon could not observe (#1089). The `--json` and `--report gitlab-mr`
+ * shapes have no column for `unobserved`, so both the CLI (on stderr) and the
+ * `markdown` report (in the body, since a reviewer never sees a job's stderr)
+ * read this same wording rather than drifting apart. Empty when the plan has
+ * no hole. Same discipline as {@link disruptionNotices} in `./disruption`.
+ */
+export function unobservedPlanNotice(cs: ChangeSet): string[] {
+  const count = summarize(cs).unobserved;
+  return count > 0
+    ? [
+        `${count} declared entity(ies) could not be observed — no create/update/delete is proposed for them. This plan is incomplete, not clean.`,
+      ]
+    : [];
+}
+
+/**
+ * Section heading text for one action group — shared between {@link renderChangeSet}
+ * and {@link renderChangeSetMarkdown} so the wording never drifts between the
+ * terminal render and the reviewer-facing one.
+ */
+function actionSectionLabel(action: ChangeAction, hasDisruption: boolean): string {
+  switch (action) {
+    case "unobserved":
+      return "UNOBSERVED (declared; chant could not read live state — no action proposed)";
+    case "runtime":
+      return "RUNTIME (owned by a declared resource; not drift, never a delete/adopt candidate)";
+    case "effect":
+      return "EFFECT (receipt absent or stale; the effect step fires — the generic apply never writes a receipt)";
+    case "update":
+      return hasDisruption
+        ? "UPDATE (disruption from the lexicon that owns the spec; unknown means nobody could say, not that it is safe)"
+        : "UPDATE";
+    default:
+      return action.toUpperCase();
+  }
+}
+
 /** Human-readable render of a change set. Pure — returns a string. */
 export function renderChangeSet(cs: ChangeSet): string {
   const counts = summarize(cs);
   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;
-    lines.push(
-      action === "unobserved"
-        ? "\nUNOBSERVED (declared; chant could not read live state — no action proposed):"
-        : action === "runtime"
-          ? "\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()}:`,
-    );
+    lines.push(`\n${actionSectionLabel(action, disruptionParts.length > 0)}:`);
     for (const e of group) {
       if (e.action === "effect") {
         lines.push(
@@ -339,9 +397,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)}`);
       }
     }
   }
@@ -349,6 +410,99 @@ export function renderChangeSet(cs: ChangeSet): string {
   return lines.join("\n");
 }
 
+/**
+ * Entries beyond this in one action group are collapsed into a `<details>`
+ * block in {@link renderChangeSetMarkdown} — a group's worth of rows is fine
+ * to read inline, a hundred-entry plan is not (#1983).
+ */
+const MARKDOWN_FOLD_THRESHOLD = 20;
+
+/** One entry's markdown, mirroring the rows {@link renderChangeSet} prints. */
+function renderMarkdownEntry(e: ChangeSetEntry): string[] {
+  if (e.action === "effect") {
+    return [
+      `- effect will fire: \`${e.effect ?? e.name}\` — receipt \`${e.name}\`${e.type ? ` (${e.type})` : ""}` +
+        `${e.effectDetail ? ` — ${e.effectDetail}` : ""}`,
+    ];
+  }
+  const lexicon = e.lexicon ? ` \`${e.lexicon}\`` : "";
+  const own = e.ownership === "unknown" ? "" : ` [${e.ownership}]`;
+  const why = e.unobservedReason
+    ? ` — ${unobservedReasonText(e.unobservedReason)}${e.unobservedDetail ? `: ${e.unobservedDetail}` : ""}`
+    : "";
+  const owner = e.runtimeOwner ? ` — owned by \`${e.runtimeOwner}\`` : "";
+  // Bolded rather than the plain-text render's bare " — destroy: ..." — a
+  // reviewer scanning a wall of "update" rows should see disruption without
+  // reading every one (#1665).
+  const disruption = e.disruption
+    ? ` — **${e.disruption}**${e.disruptionDetail ? `: ${e.disruptionDetail}` : ""}`
+    : "";
+  const lines = [`- \`${e.name}\`${e.type ? ` (${e.type})` : ""}${lexicon}${own}${why}${owner}${disruption}`];
+
+  if (e.deltas && e.deltas.length > 0) {
+    const forced = new Set(e.disruptionBecause ?? []);
+    lines.push("  ```");
+    for (const d of e.deltas) {
+      lines.push(`  ${forced.has(d.path) ? "! " : "  "}${d.path}: ${fmt(d.oldValue)} → ${fmt(d.newValue)}`);
+    }
+    lines.push("  ```");
+  }
+  return lines;
+}
+
+/**
+ * Markdown projection of a change set (#1983) — sized for a PR/MR comment
+ * rather than a terminal. A scannable counts header, entries grouped by
+ * action and attributed to their lexicon, deltas in a fenced block, and any
+ * group past {@link MARKDOWN_FOLD_THRESHOLD} folded into a `<details>` so a
+ * large plan doesn't bury the comment. Pure — no ANSI, no I/O — and
+ * deterministic: same entry ordering as {@link renderChangeSet}.
+ *
+ * Both a hole (#1089) and an expensive verdict (#1665) are surfaced IN the
+ * body, not left to stderr the way `--json` and `--report gitlab-mr` leave
+ * them: a reviewer reading a comment never sees the job's log, so a plan
+ * carrying either must not read as clean.
+ */
+export function renderChangeSetMarkdown(cs: ChangeSet): string {
+  const counts = summarize(cs);
+  const lines: string[] = [`## Plan for \`${cs.env}\``, "", ACTION_ORDER.map((a) => `${counts[a]} ${a}`).join(", ")];
+
+  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 notice of unobservedPlanNotice(cs)) {
+    lines.push("", `> **${notice}**`);
+  }
+
+  for (const action of ACTION_ORDER) {
+    const group = cs.entries.filter((e) => e.action === action);
+    if (group.length === 0) continue;
+
+    lines.push("", `### ${actionSectionLabel(action, disruptionParts.length > 0)}`);
+
+    const body = group.flatMap((e) => renderMarkdownEntry(e));
+    if (group.length > MARKDOWN_FOLD_THRESHOLD) {
+      lines.push(
+        "",
+        `<details><summary>${group.length} entries — click to expand</summary>`,
+        "",
+        ...body,
+        "",
+        "</details>",
+      );
+    } else {
+      lines.push("", ...body);
+    }
+  }
+
+  return lines.join("\n").trimEnd() + "\n";
+}
+
 function fmt(v: unknown): string {
   if (v === undefined) return "<unset>";
   if (typeof v === "string") return v.length > 60 ? v.slice(0, 57) + "..." : v;

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:");
+  });
+});

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/index.ts

@@ -7,6 +7,7 @@ export * from "./deep-diff";
 export * from "./deep-observe";
 export * from "./observation-baseline";
 export * from "./change-set";
+export * from "./disruption";
 export * from "./unobserved-gate";
 export * from "./receipt-plan";
 export * from "./affected";
@@ -16,6 +17,7 @@ export * from "./build-ledger-store";
 export * from "./oras-referrer-lookup";
 export * from "./status";
 export * from "./teardown";
+export * from "./assert-live";
 export * from "./symptoms";
 export * from "./converge-ledger";
 export * from "./scenario";

package/src/lifecycle/replay.test.ts

@@ -249,3 +249,28 @@ describe("a resource recorded twice is one node (#1432 follow-up)", () => {
     expect(keys(result.observations)).toEqual(["rtb-default"]);
   });
 });
+
+describe("replaySnapshots — recorded depth (#1268)", () => {
+  it("reports identity when nothing recorded deeper", async () => {
+    stored.set("main__aws", snapshot("main", "us-east-1", { managed: { web: "i-1" } }));
+    const result = await replaySnapshots("prod", "latest", new Set());
+    if ("error" in result) throw new Error(result.error);
+    expect(result.depth).toBe("identity");
+  });
+
+  it("reports deep when any recorded lexicon read that deep", async () => {
+    stored.set("main__aws", JSON.stringify({
+      lexicon: "aws", environment: "prod", stack: "main",
+      commit: "abc", timestamp: "2026-08-03T00:00:00.000Z", depth: "deep",
+      resources: { web: { type: "AWS::EC2::Instance", status: "OBSERVED", physicalId: "i-1" } },
+    }));
+    stored.set("net__aws", JSON.stringify({
+      lexicon: "aws", environment: "prod", stack: "net",
+      commit: "abc", timestamp: "2026-08-03T00:00:00.000Z",
+      resources: { vpc: { type: "AWS::EC2::VPC", status: "OBSERVED", physicalId: "vpc-1" } },
+    }));
+    const result = await replaySnapshots("prod", "latest", new Set());
+    if ("error" in result) throw new Error(result.error);
+    expect(result.depth).toBe("deep");
+  });
+});