@intentius/chant 0.50.0 → 0.51.0

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