@intentius/chant 0.50.0 → 0.51.0

package/dist/lifecycle/disruption.d.ts

@@ -0,0 +1,96 @@
+/**
+ * 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.js";
+import type { ChangeSet, ChangeSetEntry } from "./change-set.js";
+/**
+ * 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 declare const DISRUPTION_LEVELS: readonly Disruption[];
+/** 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 declare function unknownDisruption(detail: string): DisruptionVerdict;
+/**
+ * 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 declare function annotateDisruption(cs: ChangeSet, environment: string, classify?: DisruptionClassifier): Promise<ChangeSet>;
+/** Count `update` entries per level. Entries with no verdict at all are not counted. */
+export declare function summarizeDisruption(cs: ChangeSet): Record<Disruption, number>;
+/** The most disruptive verdict in the set, or undefined when nothing was classified. */
+export declare function worstDisruption(cs: ChangeSet): Disruption | undefined;
+/**
+ * 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 declare function disruptionNotices(cs: ChangeSet): string[];
+/** Render one entry's verdict for the human plan, or "" when there is none. */
+export declare function renderDisruption(entry: ChangeSetEntry): string;
+//# sourceMappingURL=disruption.d.ts.map

package/dist/lifecycle/disruption.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"disruption.d.ts","sourceRoot":"","sources":["../../src/lifecycle/disruption.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9D;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;AAEpF,oGAAoG;AACpG,eAAO,MAAM,iBAAiB,EAAE,SAAS,UAAU,EAMlD,CAAC;AAWF,8DAA8D;AAC9D,MAAM,WAAW,eAAe;IAC9B,0EAA0E;IAC1E,IAAI,EAAE,MAAM,CAAC;IACb,wDAAwD;IACxD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qDAAqD;IACrD,MAAM,EAAE,eAAe,EAAE,CAAC;CAC3B;AAED,wCAAwC;AACxC,MAAM,WAAW,iBAAiB;IAChC,UAAU,EAAE,UAAU,CAAC;IACvB,mFAAmF;IACnF,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,qFAAqF;IACrF,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,EAAE;IAC3C,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,eAAe,EAAE,CAAC;CAC5B,KAAK,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC,CAAC;AAErF,gDAAgD;AAChD,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,iBAAiB,CAEnE;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,kBAAkB,CACtC,EAAE,EAAE,SAAS,EACb,WAAW,EAAE,MAAM,EACnB,QAAQ,CAAC,EAAE,oBAAoB,GAC9B,OAAO,CAAC,SAAS,CAAC,CA0CpB;AAiBD,wFAAwF;AACxF,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,SAAS,GAAG,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,CAY7E;AAED,wFAAwF;AACxF,wBAAgB,eAAe,CAAC,EAAE,EAAE,SAAS,GAAG,UAAU,GAAG,SAAS,CAOrE;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,SAAS,GAAG,MAAM,EAAE,CAkBzD;AAED,+EAA+E;AAC/E,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,cAAc,GAAG,MAAM,CAG9D"}

package/dist/lifecycle/index.d.ts

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

package/dist/lifecycle/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/lifecycle/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,OAAO,CAAC;AACtB,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,wBAAwB,CAAC;AACvC,cAAc,cAAc,CAAC;AAC7B,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,mBAAmB,CAAC;AAClC,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/lifecycle/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,OAAO,CAAC;AACtB,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,wBAAwB,CAAC;AACvC,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC;AAC7B,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,YAAY,CAAC;AAC3B,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,mBAAmB,CAAC;AAClC,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC"}

package/dist/lifecycle/replay.d.ts

@@ -14,6 +14,7 @@
  * answer most questions but never all of them.
  */
 import type { LiveObservation } from "../graph-ir.js";
+import type { ObservationDepth } from "./types.js";
 /**
  * Rebuild observations from a recorded snapshot (#1266).
  *
@@ -40,6 +41,7 @@ export declare function replaySnapshots(environment: string, ref: string, scoped
     observations: LiveObservation[];
     commit: string;
     timestamp: string;
+    depth: ObservationDepth;
 } | {
     error: string;
     hint?: string;

package/dist/lifecycle/replay.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"replay.d.ts","sourceRoot":"","sources":["../../src/lifecycle/replay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAGnD;;;;;;;;;;;;GAYG;AACH;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAMvE;AAED,wBAAsB,eAAe,CACnC,WAAW,EAAE,MAAM,EACnB,GAAG,EAAE,MAAM,EACX,YAAY,EAAE,GAAG,CAAC,MAAM,CAAC,GACxB,OAAO,CAAC;IAAE,YAAY,EAAE,eAAe,EAAE,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAyIpH"}
+{"version":3,"file":"replay.d.ts","sourceRoot":"","sources":["../../src/lifecycle/replay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,KAAK,EAAqB,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAEnE;;;;;;;;;;;;GAYG;AACH;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAMvE;AAED,wBAAsB,eAAe,CACnC,WAAW,EAAE,MAAM,EACnB,GAAG,EAAE,MAAM,EACX,YAAY,EAAE,GAAG,CAAC,MAAM,CAAC,GACxB,OAAO,CACN;IAAE,YAAY,EAAE,eAAe,EAAE,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,gBAAgB,CAAA;CAAE,GAC/F;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,CACnC,CA8IA"}

package/dist/op/local-executor.d.ts

@@ -15,7 +15,13 @@ import { type ActivityFn, type ActivityProfile } from "./activity-registry.js";
 export interface StepRecord {
     phase: string;
     fn: string;
-    args: Record<string, unknown>;
+    /**
+     * Present for a local-executor record. Absent for one reconstructed from
+     * Temporal workflow history (op-progress.ts) — an activity's scheduled
+     * input isn't decoded there, so the field is simply omitted rather than
+     * populated with a guess.
+     */
+    args?: Record<string, unknown>;
     status: "ok" | "fail" | "skipped";
     durationMs: number;
     outcome?: {

package/dist/op/local-executor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"local-executor.d.ts","sourceRoot":"","sources":["../../src/op/local-executor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAiC,QAAQ,EAA8B,MAAM,SAAS,CAAC;AAC7G,OAAO,EAAmB,KAAK,UAAU,EAAE,KAAK,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAM7F,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,MAAM,EAAE,IAAI,GAAG,MAAM,GAAG,SAAS,CAAC;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC;IAC3C,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,EAAE,OAAO,CAAC;CACb;AAID,kFAAkF;AAClF,qBAAa,yBAA0B,SAAQ,KAAK;aACtB,UAAU,EAAE,MAAM;gBAAlB,UAAU,EAAE,MAAM;CAO/C;AAED,mFAAmF;AACnF,qBAAa,YAAa,SAAQ,KAAK;aACT,MAAM,EAAE,WAAW;gBAAnB,MAAM,EAAE,WAAW;CAIhD;AAmBD,8EAA8E;AAC9E,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAU/C;AA8BD;gDACgD;AAChD,wBAAgB,QAAQ,CAAC,MAAM,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAY/D;AAiSD;;;;;GAKG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,QAAQ,EAChB,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,EACnC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,EACzC,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,WAAW,CAAC,CAgDtB"}
+{"version":3,"file":"local-executor.d.ts","sourceRoot":"","sources":["../../src/op/local-executor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAiC,QAAQ,EAA8B,MAAM,SAAS,CAAC;AAC7G,OAAO,EAAmB,KAAK,UAAU,EAAE,KAAK,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAM7F,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,EAAE,EAAE,MAAM,CAAC;IACX;;;;;OAKG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,MAAM,EAAE,IAAI,GAAG,MAAM,GAAG,SAAS,CAAC;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC;IAC3C,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,EAAE,OAAO,CAAC;CACb;AAID,kFAAkF;AAClF,qBAAa,yBAA0B,SAAQ,KAAK;aACtB,UAAU,EAAE,MAAM;gBAAlB,UAAU,EAAE,MAAM;CAO/C;AAED,mFAAmF;AACnF,qBAAa,YAAa,SAAQ,KAAK;aACT,MAAM,EAAE,WAAW;gBAAnB,MAAM,EAAE,WAAW;CAIhD;AAmBD,8EAA8E;AAC9E,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAU/C;AA8BD;gDACgD;AAChD,wBAAgB,QAAQ,CAAC,MAAM,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAY/D;AAiSD;;;;;GAKG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,QAAQ,EAChB,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,EACnC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,EACzC,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,WAAW,CAAC,CAgDtB"}

package/dist/testing.d.ts

@@ -15,6 +15,12 @@
  *   in-process for exactly this suite's environment. Stateless by design:
  *   a crashed suite's environment is recovered by calling destroy again (or
  *   `chant lifecycle teardown <env> --yes`).
+ * - **assertLive** (#1857) — `describeResources()` against exactly one
+ *   declared entity, turned into a pass or a thrown failure. Preserves
+ *   #1089's tri-state rather than collapsing it: NOT-OBSERVED throws {@link
+ *   UnobservedAssertionError}, never a silent pass and never an ordinary
+ *   failure, because chant could not read the entity is not the same claim
+ *   as chant read it and it is gone.
  *
  * ## Isolation
  *
@@ -39,12 +45,14 @@
  * exported, and a CI job pointing the identical suite at a real account just
  * leaves both unset.
  */
-import type { Declarable } from "./declarable.js";
+import { type Declarable } from "./declarable.js";
 import type { SerializerResult } from "./serializer.js";
 import { type BuildParamValue } from "./build-params.js";
-import type { LexiconPlugin } from "./lexicon.js";
+import type { LexiconPlugin, ResourceMetadata } from "./lexicon.js";
 import { type ActivityFn, type ActivityProfile } from "./op/activity-registry.js";
 import { type TeardownReport } from "./lifecycle/teardown.js";
+import { LiveAssertionError, UnobservedAssertionError, type AssertLiveOptions } from "./lifecycle/assert-live.js";
+export { LiveAssertionError, UnobservedAssertionError, type AssertLiveOptions };
 export interface DeployStackOptions {
     /** The chant project directory (where the infra source lives). */
     dir: string;
@@ -86,6 +94,19 @@ export interface DeployedStack {
     entities: Map<string, Declarable>;
     /** The environment this deploy targeted — the teardown key. */
     env: string;
+    /**
+     * Assert that a declared entity is live: observed present in this
+     * deploy's environment, not confirmed as another stack/env's resource,
+     * and — when `status` is given — reporting that status.
+     *
+     * Rides the observation contract (#1089): an entity `describeResources`
+     * could not cover throws {@link UnobservedAssertionError}, never a pass
+     * and never a plain failure — NOT-OBSERVED is not the same claim as
+     * absent. Observed-absent, a confirmed-foreign identity, or a status
+     * mismatch throws {@link LiveAssertionError}. Resolves to the entity's
+     * `ResourceMetadata` on success.
+     */
+    assertLive(name: string, options?: AssertLiveOptions): Promise<ResourceMetadata>;
     /**
      * Tear down everything carrying this suite's marker `{ stack, env }`.
      * Throws {@link TeardownIncompleteError} when any candidate failed to

package/dist/testing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAMH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAMrD,OAAO,EAAsB,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAI1E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAG/C,OAAO,EAAgC,KAAK,UAAU,EAAE,KAAK,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAE7G,OAAO,EAAmB,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAgB5E,MAAM,WAAW,kBAAkB;IACjC,kEAAkE;IAClE,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;OAKG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iFAAiF;IACjF,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IACzC;;;OAGG;IACH,OAAO,CAAC,EAAE,aAAa,EAAE,CAAC;IAC1B,6EAA6E;IAC7E,UAAU,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACrC,oFAAoF;IACpF,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAC3C;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACvC;AAED,mEAAmE;AACnE,MAAM,WAAW,aAAa;IAC5B,+DAA+D;IAC/D,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,gBAAgB,CAAC,CAAC;IAChD,8CAA8C;IAC9C,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IAClC,+DAA+D;IAC/D,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;;OAOG;IACH,OAAO,IAAI,OAAO,CAAC,cAAc,CAAC,CAAC;CACpC;AAED;;;;;;GAMG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;aACpB,MAAM,EAAE,cAAc;gBAAtB,MAAM,EAAE,cAAc;CAkBnD;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAUjD;AA8BD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,aAAa,CAAC,CAkHrF"}
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAMH,OAAO,EAAwB,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AACrE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAMrD,OAAO,EAAsB,KAAK,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAI1E,OAAO,KAAK,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAGjE,OAAO,EAAgC,KAAK,UAAU,EAAE,KAAK,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAE7G,OAAO,EAAmB,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC5E,OAAO,EAEL,kBAAkB,EAClB,wBAAwB,EACxB,KAAK,iBAAiB,EACvB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAE,kBAAkB,EAAE,wBAAwB,EAAE,KAAK,iBAAiB,EAAE,CAAC;AAgBhF,MAAM,WAAW,kBAAkB;IACjC,kEAAkE;IAClE,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;OAKG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iFAAiF;IACjF,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IACzC;;;OAGG;IACH,OAAO,CAAC,EAAE,aAAa,EAAE,CAAC;IAC1B,6EAA6E;IAC7E,UAAU,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACrC,oFAAoF;IACpF,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAC3C;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACvC;AAED,mEAAmE;AACnE,MAAM,WAAW,aAAa;IAC5B,+DAA+D;IAC/D,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,gBAAgB,CAAC,CAAC;IAChD,8CAA8C;IAC9C,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IAClC,+DAA+D;IAC/D,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;;;;;;OAWG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IACjF;;;;;;;OAOG;IACH,OAAO,IAAI,OAAO,CAAC,cAAc,CAAC,CAAC;CACpC;AAED;;;;;;GAMG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;aACpB,MAAM,EAAE,cAAc;gBAAtB,MAAM,EAAE,cAAc;CAkBnD;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAUjD;AA8BD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,aAAa,CAAC,CAmJrF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant",
-  "version": "0.50.0",
+  "version": "0.51.0",
   "description": "Declarative infrastructure-as-code toolkit — TypeScript on Node.js",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",

package/src/cli/handlers/lifecycle.test.ts

@@ -821,6 +821,96 @@ describe("runLifecyclePlan", () => {
     expect(byName["sg-0abc123"].name).toBe("sg-0abc123");
   });
 
+  // #1665 — per-change disruption. Core defines the contract and reports it;
+  // the lexicon that owns the spec answers, and every degradation is `unknown`.
+  describe("disruption classification (#1665)", () => {
+    const drifted = (lexicon: string, type: string) => {
+      readSnapshotMock.mockResolvedValue(JSON.stringify({
+        lexicon,
+        environment: "prod",
+        commit: "abc",
+        timestamp: "2026-04-01T00:00:00Z",
+        resources: { db: meta({ type, attributes: { Engine: "postgres" } }) },
+      }));
+      return staticDescribeResources({ db: meta({ type, attributes: { Engine: "mysql" } }) });
+    };
+
+    test("a lexicon's verdict reaches --json and the stderr warning", async () => {
+      buildMock.mockResolvedValue(makeBuildResult({ aws: ["db"] }));
+      const plugins: LexiconPlugin[] = [
+        createMockPlugin({
+          name: "aws",
+          emulator: awsEmulatorStub,
+          describeResources: drifted("aws", "AWS::RDS::DBInstance"),
+          classifyDisruption: ({ changes }) =>
+            Object.fromEntries(
+              changes.map((c) => [
+                c.name,
+                { disruption: "destroy" as const, because: c.deltas.map((d) => d.path), detail: "Engine is create-only" },
+              ]),
+            ),
+        }),
+      ];
+      const exit = await runLifecyclePlan({
+        args: makeArgs({ path: "plan", extraPositional: "prod", json: true }),
+        plugins,
+        serializers: plugins.map((p) => p.serializer),
+      });
+      expect(exit).toBe(0);
+      const plan = JSON.parse(stdoutBuf.join("\n"));
+      const db = plan.entries.find((e: { name: string }) => e.name === "db");
+      expect(db).toMatchObject({
+        action: "update",
+        disruption: "destroy",
+        disruptionDetail: "Engine is create-only",
+      });
+      expect(db.disruptionBecause).toContain("attributes.Engine");
+      // The --json shape has no column for it, so the warning is what a CI
+      // consumer hears.
+      expect(stderrBuf.join("\n")).toContain("replace the resource rather than mutating it in place");
+    });
+
+    test("a lexicon with no classifier leaves every update unknown, never in-place", async () => {
+      buildMock.mockResolvedValue(makeBuildResult({ k8s: ["db"] }));
+      const plugins: LexiconPlugin[] = [
+        createMockPlugin({ name: "k8s", describeResources: drifted("k8s", "K8s::Apps::Deployment") }),
+      ];
+      const exit = await runLifecyclePlan({
+        args: makeArgs({ path: "plan", extraPositional: "prod", json: true }),
+        plugins,
+        serializers: plugins.map((p) => p.serializer),
+      });
+      expect(exit).toBe(0);
+      const plan = JSON.parse(stdoutBuf.join("\n"));
+      const db = plan.entries.find((e: { name: string }) => e.name === "db");
+      expect(db.disruption).toBe("unknown");
+      expect(db.disruptionDetail).toContain("k8s lexicon does not classify disruption");
+      expect(stderrBuf.join("\n")).toContain("could not be classified");
+    });
+
+    test("the human render carries the verdict", async () => {
+      buildMock.mockResolvedValue(makeBuildResult({ aws: ["db"] }));
+      const plugins: LexiconPlugin[] = [
+        createMockPlugin({
+          name: "aws",
+          emulator: awsEmulatorStub,
+          describeResources: drifted("aws", "AWS::RDS::DBInstance"),
+          classifyDisruption: () => ({ db: { disruption: "in-place" as const, detail: "no create-only property changed" } }),
+        }),
+      ];
+      const exit = await runLifecyclePlan({
+        args: makeArgs({ path: "plan", extraPositional: "prod" }),
+        plugins,
+        serializers: plugins.map((p) => p.serializer),
+      });
+      expect(exit).toBe(0);
+      const out = stdoutBuf.join("\n");
+      expect(out).toContain("Disruption: 1 in-place");
+      expect(out).toContain("— in-place: no create-only property changed");
+      expect(stderrBuf.join("\n")).not.toContain("could not be classified");
+    });
+  });
+
   // #1832 — effect receipts are declared, diffed, and observed like any
   // resource, but observe-only to the generic apply path: the plan compares
   // live value to resolved expectation and proposes the fire, never a create.

package/src/cli/handlers/lifecycle.ts

@@ -20,6 +20,7 @@ import { computeBuildDigest, diffDigests } from "../../lifecycle/digest";
 import { diffLive, diffLiveArtifacts, diffSnapshots, type LiveDiffResult, type LiveArtifactDiffResult, type SnapshotDiffResult } from "../../lifecycle/live-diff";
 import { buildChangeSet, renderChangeSet, gitlabMrReport, summarize, type ChangeSet } from "../../lifecycle/change-set";
 import { mergeReceiptEntries, observedValueResolver, planReceipts, readReceiptValue, type ReceiptReading } from "../../lifecycle/receipt-plan";
+import { annotateDisruption, disruptionNotices } from "../../lifecycle/disruption";
 import { collectEffectReceipts, isEffectReceipt } from "../../effect-receipt";
 import {
   formatUnobserved,
@@ -1264,7 +1265,17 @@ export async function runLifecyclePlan(ctx: CommandContext): Promise<number> {
         // Attribution survives the flat merge below (#1674).
         lexicon: lexiconName,
       });
-      merged.entries.push(...cs.entries);
+
+      // Disruption (#1665) is asked of THIS lexicon, before the merge: the
+      // deltas are paths into its own observation shape, and the replacement
+      // rules are in the spec it compiled. A lexicon that answers nothing
+      // leaves every update `unknown` — never `in-place`.
+      const classified = await annotateDisruption(
+        cs,
+        environment,
+        plugin.classifyDisruption ? (o) => plugin.classifyDisruption!(o) : undefined,
+      );
+      merged.entries.push(...classified.entries);
       checked++;
     }
   } finally {
@@ -1299,6 +1310,12 @@ export async function runLifecyclePlan(ctx: CommandContext): Promise<number> {
     }));
   }
 
+  // Same reason as above (#1665): the `--json` and `--report gitlab-mr` shapes
+  // have no column for how much an update hurts.
+  for (const notice of disruptionNotices(merged)) {
+    console.error(formatWarning({ message: notice }));
+  }
+
   // `--report gitlab-mr` emits the GitLab MR plan-widget artifact instead of the
   // human render. Write it to a file (`tfplan.json`) in CI and declare it as
   // `artifacts:reports:terraform` to light up the merge-request widget.

package/src/cli/handlers/op-progress.test.ts

@@ -0,0 +1,202 @@
+import { describe, test, expect } from "vitest";
+import { extractStepRecords, countActivities, queryGateState } from "./op-progress";
+import type { OpConfig } from "../../op/types";
+import type { EffectReceiptRef } from "../../op/receipt-store";
+import type { WorkflowHistoryRaw, HistoryEvent } from "./run-client";
+
+// Minimal history-event builders. Field shapes match what `fetchNormalizedHistory`
+// produces: short PascalCase `eventType`, decimal-string `eventId`/`scheduledEventId`.
+function scheduled(eventId: string, fn: string, at: Date): HistoryEvent {
+  return {
+    eventId,
+    eventType: "ActivityTaskScheduled",
+    eventTime: at,
+    activityTaskScheduledEventAttributes: { activityId: eventId, activityType: { name: fn } },
+  };
+}
+function completed(scheduledEventId: string, at: Date): HistoryEvent {
+  return {
+    eventType: "ActivityTaskCompleted",
+    eventTime: at,
+    activityTaskCompletedEventAttributes: { scheduledEventId },
+  };
+}
+function failed(scheduledEventId: string, at: Date, message = "boom"): HistoryEvent {
+  return {
+    eventType: "ActivityTaskFailed",
+    eventTime: at,
+    activityTaskFailedEventAttributes: { scheduledEventId, failure: { message } },
+  };
+}
+
+const T0 = new Date("2026-05-01T00:00:00Z");
+const sec = (n: number) => new Date(T0.getTime() + n * 1000);
+
+describe("extractStepRecords", () => {
+  test("joins two phases' activities to their declared phase, in order", () => {
+    const config: OpConfig = {
+      name: "op", overview: "o",
+      phases: [
+        { name: "Build", steps: [{ kind: "activity", fn: "build" }] },
+        { name: "Deploy", steps: [{ kind: "activity", fn: "deploy" }] },
+      ],
+    };
+    const history: WorkflowHistoryRaw = {
+      events: [
+        scheduled("1", "build", sec(0)),
+        completed("1", sec(1)),
+        scheduled("2", "deploy", sec(2)),
+        completed("2", sec(4)),
+      ],
+    };
+    const records = extractStepRecords(config, history);
+    expect(records).toEqual([
+      { phase: "Build", fn: "build", status: "ok", durationMs: 1000 },
+      { phase: "Deploy", fn: "deploy", status: "ok", durationMs: 2000 },
+    ]);
+  });
+
+  test("two steps calling the same activity each get their own scheduled event (no last-wins collision)", () => {
+    const config: OpConfig = {
+      name: "op", overview: "o",
+      phases: [{ name: "P1", steps: [{ kind: "activity", fn: "dup" }, { kind: "activity", fn: "dup" }] }],
+    };
+    const history: WorkflowHistoryRaw = {
+      events: [
+        scheduled("1", "dup", sec(0)),
+        completed("1", sec(1)), // first "dup": 1000ms, ok
+        scheduled("2", "dup", sec(1)),
+        failed("2", sec(1.5), "second dup failed"), // second "dup": fails
+      ],
+    };
+    const records = extractStepRecords(config, history);
+    expect(records).toEqual([
+      { phase: "P1", fn: "dup", status: "ok", durationMs: 1000 },
+      { phase: "P1", fn: "dup", status: "fail", durationMs: 500, error: "second dup failed" },
+    ]);
+  });
+
+  test("a step not yet scheduled produces no record unless final", () => {
+    const config: OpConfig = {
+      name: "op", overview: "o",
+      phases: [
+        { name: "P1", steps: [{ kind: "activity", fn: "a" }] },
+        { name: "P2", steps: [{ kind: "activity", fn: "b" }] },
+      ],
+    };
+    const history: WorkflowHistoryRaw = { events: [scheduled("1", "a", sec(0)), completed("1", sec(1))] };
+
+    expect(extractStepRecords(config, history)).toEqual([
+      { phase: "P1", fn: "a", status: "ok", durationMs: 1000 },
+    ]);
+    expect(extractStepRecords(config, history, { final: true })).toEqual([
+      { phase: "P1", fn: "a", status: "ok", durationMs: 1000 },
+      { phase: "P2", fn: "b", status: "skipped", durationMs: 0 },
+    ]);
+  });
+
+  test("a scheduled-but-not-yet-settled step produces no record", () => {
+    const config: OpConfig = {
+      name: "op", overview: "o",
+      phases: [{ name: "P1", steps: [{ kind: "activity", fn: "a" }] }],
+    };
+    const history: WorkflowHistoryRaw = { events: [scheduled("1", "a", sec(0))] };
+    expect(extractStepRecords(config, history)).toEqual([]);
+  });
+
+  test("a retried activity resolves to its last outcome (Failed attempt then eventual Completed)", () => {
+    const config: OpConfig = {
+      name: "op", overview: "o",
+      phases: [{ name: "P1", steps: [{ kind: "activity", fn: "flaky" }] }],
+    };
+    const history: WorkflowHistoryRaw = {
+      events: [
+        scheduled("1", "flaky", sec(0)),
+        failed("1", sec(1), "attempt 1 failed"),
+        completed("1", sec(3)), // eventual success
+      ],
+    };
+    expect(extractStepRecords(config, history)).toEqual([
+      { phase: "P1", fn: "flaky", status: "ok", durationMs: 3000 },
+    ]);
+  });
+
+  test("effect step: matched receipt — only receiptRead settles; nested + receiptWrite are skipped only when final", () => {
+    const receipt: EffectReceiptRef = { name: "r", effect: "e", flavor: "existence", inputs: {} };
+    const config: OpConfig = {
+      name: "op", overview: "o",
+      phases: [{
+        name: "Effect",
+        steps: [{ kind: "effect", receipt, steps: [{ kind: "activity", fn: "applyIt" }] }],
+      }],
+    };
+    const history: WorkflowHistoryRaw = {
+      events: [scheduled("1", "receiptRead", sec(0)), completed("1", sec(1))],
+    };
+    expect(extractStepRecords(config, history)).toEqual([
+      { phase: "Effect", fn: "receiptRead", status: "ok", durationMs: 1000 },
+    ]);
+    expect(extractStepRecords(config, history, { final: true })).toEqual([
+      { phase: "Effect", fn: "receiptRead", status: "ok", durationMs: 1000 },
+      { phase: "Effect", fn: "applyIt", status: "skipped", durationMs: 0 },
+      { phase: "Effect", fn: "receiptWrite", status: "skipped", durationMs: 0 },
+    ]);
+  });
+
+  test("onFailure phases are matched in reverse declared order, matching how the workflow actually runs them", () => {
+    const config: OpConfig = {
+      name: "op", overview: "o",
+      phases: [{ name: "Main", steps: [{ kind: "activity", fn: "boom" }] }],
+      onFailure: [
+        { name: "C1", steps: [{ kind: "activity", fn: "comp1" }] },
+        { name: "C2", steps: [{ kind: "activity", fn: "comp2" }] },
+      ],
+    };
+    const history: WorkflowHistoryRaw = {
+      events: [
+        scheduled("1", "boom", sec(0)),
+        failed("1", sec(1), "boom"),
+        // Compensation runs C2 then C1 (reverse of declared order).
+        scheduled("2", "comp2", sec(2)),
+        completed("2", sec(3)),
+        scheduled("3", "comp1", sec(3)),
+        completed("3", sec(4)),
+      ],
+    };
+    expect(extractStepRecords(config, history)).toEqual([
+      { phase: "Main", fn: "boom", status: "fail", durationMs: 1000, error: "boom" },
+      { phase: "C2", fn: "comp2", status: "ok", durationMs: 1000 },
+      { phase: "C1", fn: "comp1", status: "ok", durationMs: 1000 },
+    ]);
+  });
+});
+
+describe("countActivities", () => {
+  test("counts scheduled and completed events", () => {
+    const history: WorkflowHistoryRaw = {
+      events: [scheduled("1", "a", sec(0)), scheduled("2", "b", sec(0)), completed("1", sec(1))],
+    };
+    expect(countActivities(history)).toEqual({ completed: 1, scheduled: 2 });
+  });
+
+  test("empty history", () => {
+    expect(countActivities({})).toEqual({ completed: 0, scheduled: 0 });
+  });
+});
+
+describe("queryGateState", () => {
+  test("returns the query result when the handle supports it", async () => {
+    const handle = { query: async () => ({ signalName: "g", since: "t" }) } as unknown as Parameters<typeof queryGateState>[0];
+    expect(await queryGateState(handle)).toEqual({ signalName: "g", since: "t" });
+  });
+
+  test("returns null when the workflow reports no pending gate", async () => {
+    const handle = { query: async () => null } as unknown as Parameters<typeof queryGateState>[0];
+    expect(await queryGateState(handle)).toBeNull();
+  });
+
+  test("returns undefined (not an error) when the query isn't registered — e.g. an Op with no gates", async () => {
+    const handle = { query: async () => { throw new Error("unregistered query"); } } as unknown as Parameters<typeof queryGateState>[0];
+    expect(await queryGateState(handle)).toBeUndefined();
+  });
+});