@intentius/chant 0.50.0 → 0.52.0

package/src/components/run-progress.ts

@@ -107,11 +107,15 @@ export type RunProgressSink = (event: RunProgressEvent) => void;
 /**
  * Build a sink that writes `JSON.stringify(event) + "\n"` to `write` (default:
  * `process.stdout.write`), one line per event, as they happen — the
- * `--progress-json` CLI wiring's sink (../cli/handlers/run.ts). Kept separate
- * from `driver-output.ts`'s end-of-run renderers: this emits *during* the
- * run, one line at a time; `renderDriverJson`/`renderDriverHuman` render the
- * completed `DriverRunResult` once, after the run finishes.
+ * `--progress-json` CLI wiring's sink (../cli/handlers/run.ts, for both the
+ * `--components` driver's `RunProgressEvent`s and the Temporal Op path's
+ * `StepRecord`s, chant #1676). Kept separate from `driver-output.ts`'s
+ * end-of-run renderers: this emits *during* the run, one line at a time;
+ * `renderDriverJson`/`renderDriverHuman` render the completed
+ * `DriverRunResult` once, after the run finishes.
  */
-export function ndjsonProgressSink(write: (chunk: string) => void = (s) => void process.stdout.write(s)): RunProgressSink {
+export function ndjsonProgressSink<T = RunProgressEvent>(
+  write: (chunk: string) => void = (s) => void process.stdout.write(s),
+): (event: T) => void {
   return (event) => write(JSON.stringify(event) + "\n");
 }

package/src/lexicon.ts

@@ -18,6 +18,7 @@ import type { ReferenceCatalog } from "./graph-refs";
 import type { IREdge } from "./graph-ir";
 import type { DescribeResourcesResult, UnobservedReason } from "./observation";
 import type { DeepNormalizationHooks, DeepObservationResult } from "./deep-observation";
+import type { DisruptionQuery, DisruptionVerdict } from "./lifecycle/disruption";
 import type { OwnerChainVerdict } from "./owner-chain";
 import type { CommandGroup } from "./cli/command-group";
 
@@ -44,6 +45,16 @@ export type {
   UnobservedReason,
 } from "./observation";
 
+// Disruption classification (#1665), re-exported from the same entry so a
+// lexicon's `classifyDisruption` types itself without a second import path.
+// Runtime helpers live in `@intentius/chant/lifecycle/disruption`.
+export type {
+  Disruption,
+  DisruptionQuery,
+  DisruptionVerdict,
+  DisruptionClassifier,
+} from "./lifecycle/disruption";
+
 // The deep observation contract (#1014), re-exported for the same reason: a
 // lexicon authoring `observeResourcesDeep` + its pruning/ordering hooks types
 // them from the same entry. Runtime helpers live in
@@ -878,6 +889,46 @@ export interface LexiconPlugin {
     namespace?: string;
   }): Promise<DescribeResourcesResult>;
 
+  /**
+   * Classify how much each pending `update` in a plan hurts (#1665) —
+   * in-place / rolling / replace / destroy, or `unknown`.
+   *
+   * `lifecycle plan` reports WHAT changes. What it costs to apply is a
+   * different question, and the answer is spec knowledge: CloudFormation's
+   * registry schema declares `createOnlyProperties` per type, Kubernetes' SSA
+   * schema knows which field changes roll a workload. Core owns neither, so it
+   * defines the vocabulary and does the reporting, and the lexicon that
+   * compiled the spec answers — the same division `postSynthChecks` draws for
+   * validation. A replacement rule hardcoded in core would be a rule the tool
+   * has to keep in step with a provider it does not generate from.
+   *
+   * Only the lexicon can answer, for a second reason: the `deltas` on an entry
+   * are paths into ITS OWN observation shape (`attributes.<key>` off
+   * {@link describeResources}), which core cannot map back onto spec property
+   * names without knowing how the reader named things.
+   *
+   * Called once per lexicon with that lexicon's `update` entries, before the
+   * plan merges the change sets. Expected to be a table lookup over compiled
+   * spec data — no live API call, no mutation. Returning a `Promise` is
+   * allowed, so a lexicon whose answer needs an await is not shut out.
+   *
+   * **Every degradation lands on `unknown`.** Return a partial map: a name
+   * absent from the result is `unknown`, which is the right answer when the
+   * spec does not say (a conditionally-immutable property, a type with no
+   * schema on record). Core also forces `unknown` when this method is absent,
+   * when it throws, and when it returns a level outside the vocabulary. There
+   * is no path by which a lexicon accidentally produces a confident
+   * `in-place` — that claim has to be made deliberately, and a consumer gating
+   * on `replace` can trust it for exactly that reason.
+   *
+   * Omit for lexicons with no replacement semantics to publish.
+   */
+  classifyDisruption?(options: {
+    environment: string;
+    /** This lexicon's `update` entries — name, type, and the attribute deltas. */
+    changes: DisruptionQuery[];
+  }): Record<string, DisruptionVerdict> | Promise<Record<string, DisruptionVerdict>>;
+
   /**
    * Report the undeclared resources this estate *depends on* (#1273), as
    * opposed to the ones it manages.

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

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

package/src/lifecycle/assert-live.ts

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

package/src/lifecycle/change-set.test.ts

@@ -1,5 +1,14 @@
 import { describe, expect, test } from "vitest";
-import { buildChangeSet, renderChangeSet, summarize, gitlabMrReport } from "./change-set";
+import {
+  buildChangeSet,
+  renderChangeSet,
+  renderChangeSetMarkdown,
+  summarize,
+  gitlabMrReport,
+  unobservedPlanNotice,
+  type ChangeSet,
+  type ChangeSetEntry,
+} from "./change-set";
 import type { ResourceMetadata } from "../lexicon";
 
 const meta = (over: Partial<ResourceMetadata> = {}): ResourceMetadata => ({
@@ -446,3 +455,137 @@ describe("buildChangeSet: not-observed is not absent (#1089)", () => {
     expect(gitlabMrReport(cs)).toEqual({ create: 0, update: 0, delete: 0 });
   });
 });
+
+// ── Markdown report (#1983) ──────────────────────────────────────────────
+
+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 },
+    ownership: "unknown",
+    ...overrides,
+  };
+}
+
+function set(entries: ChangeSetEntry[]): ChangeSet {
+  return { env: "prod", entries };
+}
+
+describe("unobservedPlanNotice (#1983)", () => {
+  test("empty when nothing is unobserved", () => {
+    expect(unobservedPlanNotice(set([entry({ action: "noop" })]))).toEqual([]);
+  });
+
+  test("one notice naming the count, matching the CLI's stderr wording", () => {
+    const cs = set([
+      entry({ name: "a", action: "unobserved", unobservedReason: "no-binding" }),
+      entry({ name: "b", action: "unobserved", unobservedReason: "read-failed" }),
+      entry({ name: "c", action: "noop" }),
+    ]);
+    expect(unobservedPlanNotice(cs)).toEqual([
+      "2 declared entity(ies) could not be observed — no create/update/delete is proposed for them. This plan is incomplete, not clean.",
+    ]);
+  });
+});
+
+describe("renderChangeSetMarkdown (#1983)", () => {
+  test("empty plan: header only, no ANSI, deterministic", () => {
+    const out = renderChangeSetMarkdown(set([]));
+    expect(out).toBe(
+      "## Plan for `prod`\n\n0 create, 0 update, 0 effect, 0 delete, 0 adopt, 0 runtime, 0 noop, 0 unobserved\n",
+    );
+    expect(out).not.toMatch(/\x1b\[/);
+  });
+
+  test("counts header and grouped sections, attributed to lexicon", () => {
+    const cs = set([
+      entry({ name: "new-bucket", type: "S3::Bucket", lexicon: "aws", action: "create", evidence: { declared: true, inSnapshot: false, live: false, observed: true } }),
+      entry({ name: "web", type: "K8s::Apps::Deployment", lexicon: "k8s", action: "noop", evidence: { declared: true, inSnapshot: true, live: true, observed: true } }),
+    ]);
+    const out = renderChangeSetMarkdown(cs);
+    expect(out).toContain("## Plan for `prod`");
+    expect(out).toContain("1 create, 0 update, 0 effect, 0 delete, 0 adopt, 0 runtime, 1 noop, 0 unobserved");
+    expect(out).toContain("### CREATE");
+    expect(out).toContain("- `new-bucket` (S3::Bucket) `aws`");
+    expect(out).toContain("### NOOP");
+    expect(out).toContain("- `web` (K8s::Apps::Deployment) `k8s`");
+  });
+
+  test("deltas render in a fenced block, forced path marked", () => {
+    const cs = set([
+      entry({
+        deltas: [
+          { path: "attributes.DBInstanceIdentifier", oldValue: "app-db", newValue: "app-db-2" },
+          { path: "attributes.AllocatedStorage", oldValue: 20, newValue: 40 },
+        ],
+        disruption: "destroy",
+        disruptionBecause: ["attributes.DBInstanceIdentifier"],
+        disruptionDetail: "DBInstanceIdentifier is create-only",
+      }),
+    ]);
+    const out = renderChangeSetMarkdown(cs);
+    expect(out).toContain("**destroy**: DBInstanceIdentifier is create-only");
+    expect(out).toContain("```");
+    expect(out).toContain("! attributes.DBInstanceIdentifier: app-db → app-db-2");
+    expect(out).toContain("attributes.AllocatedStorage: 20 → 40");
+  });
+
+  test("disruption count rides the header, same as the human render", () => {
+    const cs = set([entry({ disruption: "in-place" }), entry({ name: "web", disruption: "destroy" })]);
+    const out = renderChangeSetMarkdown(cs);
+    expect(out).toContain("**Disruption:** 1 in-place, 1 destroy");
+  });
+
+  test("unobserved renders both the prominent notice and its own section, same wording as the human render", () => {
+    const cs = set([
+      entry({ name: "crd-widget", action: "unobserved", unobservedReason: "no-binding", unobservedDetail: "no kubectl context for prod" }),
+    ]);
+    const out = renderChangeSetMarkdown(cs);
+    expect(out).toContain(
+      "> **1 declared entity(ies) could not be observed — no create/update/delete is proposed for them. This plan is incomplete, not clean.**",
+    );
+    expect(out).toContain("### UNOBSERVED (declared; chant could not read live state — no action proposed)");
+    expect(out).toContain("- `crd-widget`");
+    expect(out).toContain("no binding for this environment");
+    expect(out).toContain("no kubectl context for prod");
+  });
+
+  test("a clean plan (no holes) carries no unobserved notice at all", () => {
+    const out = renderChangeSetMarkdown(set([entry({ action: "noop" })]));
+    expect(out).not.toContain("could not be observed");
+    expect(out).not.toContain("UNOBSERVED");
+  });
+
+  test("effect entries render as their own line, no deltas", () => {
+    const cs = set([
+      entry({
+        name: "receipt-x",
+        action: "effect",
+        effect: "seed-admin",
+        effectReason: "receipt-absent",
+        effectDetail: "no receipt recorded yet",
+        deltas: undefined,
+      }),
+    ]);
+    const out = renderChangeSetMarkdown(cs);
+    expect(out).toContain("- effect will fire: `seed-admin` — receipt `receipt-x`");
+    expect(out).toContain("no receipt recorded yet");
+  });
+
+  test("a group past the fold threshold collapses into <details>, a small one does not", () => {
+    const many = Array.from({ length: 25 }, (_, i) =>
+      entry({ name: `bucket-${i}`, action: "create", evidence: { declared: true, inSnapshot: false, live: false, observed: true }, deltas: undefined }),
+    );
+    const out = renderChangeSetMarkdown(set(many));
+    expect(out).toContain("<details><summary>25 entries — click to expand</summary>");
+    expect(out).toContain("</details>");
+    expect(out).toContain("- `bucket-0`");
+    expect(out).toContain("- `bucket-24`");
+
+    const few = renderChangeSetMarkdown(set(many.slice(0, 3)));
+    expect(few).not.toContain("<details>");
+  });
+});