@intentius/chant 0.46.0 → 0.50.0

package/src/fold/subset.test.ts

@@ -74,10 +74,12 @@ const SUPPORTED_CASES: SubsetCase[] = [
 
 const UNSUPPORTED_CASES: SubsetCase[] = [
   { name: "function call as a value", expr: `getName()` },
-  { name: "method call as a value", expr: `config.getName()` },
-  // chant #1082 — a registered helper NAME reached through a namespace is
-  // still a method call, and still rejected by both sides.
-  { name: "registered helper name reached as a method", expr: `helpers.phase("Apply", [])` },
+  // chant #1966 moved "method call as a value" and "registered helper name
+  // reached as a method" out of this strict-parity list and into "documented
+  // divergences" below — a method call now folds when its receiver resolves,
+  // which is exactly the identifier-resolution asymmetry every other
+  // divergence there already documents.
+  //
   // ...and a registered helper with an unfoldable argument is rejected on the
   // argument, by both sides, at the argument's own position.
   { name: "registered helper with an unfoldable argument", expr: `phase("Apply", [getName()])` },
@@ -258,6 +260,89 @@ describe("documented divergences — NOT unified by design (see subset.ts module
     expect(evl001NonLiteralExpressionRule.check(context)).toHaveLength(0);
   });
 
+  test("method call on an unresolved receiver: fold rejects; EVL001 accepts the shape (chant #1966, resolution-dependent)", () => {
+    // `config.getName()` — chant #1966 widened `findSubsetViolation` to
+    // accept a method call unconditionally (mirroring `.step` and a nested
+    // `new` before it), because whether the receiver resolves to a value
+    // with that method is resolution-dependent (module doc, point 1) and out
+    // of reach for a syntax-only classifier. fold() still rejects it here on
+    // the receiver: `config` isn't a `const` this file has.
+    const source = `const bad = new Thing({ x: config.getName() });`;
+    const sourceFile = ts.createSourceFile("t.ts", source, ts.ScriptTarget.Latest, true);
+    const consts = collectConsts(sourceFile);
+    const badInit = consts.get("bad") as ts.NewExpression;
+
+    expect(() => foldResource(badInit, consts, [])).toThrow(FoldError);
+
+    const context: LintContext = { sourceFile, entities: [], filePath: "t.ts", lexicon: undefined };
+    expect(evl001NonLiteralExpressionRule.check(context)).toHaveLength(0);
+  });
+
+  test("registered helper name reached as a method: not the registered call, on either side — rejected for a different reason since #1966", () => {
+    // chant #1082 — a registered helper NAME reached through a namespace is
+    // still a method call, never the bare registered call: `fold()`'s
+    // `{__helper}` shape only ever matches a BARE identifier callee, so
+    // `helpers.phase(...)` never gets that treatment, before or after #1966.
+    // What changed is WHY it's rejected — `helpers` is an unresolved
+    // identifier now reached through the general method-call case, not "no
+    // case for a property-access callee" — same divergence direction as the
+    // test above.
+    const source = `const bad = new Thing({ x: helpers.phase("Apply", []) });`;
+    const sourceFile = ts.createSourceFile("t.ts", source, ts.ScriptTarget.Latest, true);
+    const consts = collectConsts(sourceFile);
+    const badInit = consts.get("bad") as ts.NewExpression;
+
+    let error: unknown;
+    try {
+      foldResource(badInit, consts, []);
+    } catch (e) {
+      error = e;
+    }
+    expect(error).toBeInstanceOf(FoldError);
+    expect((error as FoldError).message).toContain("unresolved identifier: helpers");
+
+    const context: LintContext = { sourceFile, entities: [], filePath: "t.ts", lexicon: undefined };
+    expect(evl001NonLiteralExpressionRule.check(context)).toHaveLength(0);
+  });
+
+  test("composite step access: NO LONGER a divergence (chant #1174) — both fold and EVL001 accept it", () => {
+    // `Checkout({...}).step` — the single-action Composite() wrapper idiom
+    // every lexicon's own docs/examples embed inline inside a Job's
+    // `steps:` array. This was a documented, EVL-only-permissive divergence
+    // from chant #1544 until #1174: `fold()` had no way to invoke an
+    // arbitrary composite factory, so it fell the file back to run
+    // (correct, not an error) while EVL001 already opted into treating the
+    // shape as valid via a since-removed `allowCompositeStepAccess` flag.
+    //
+    // fold() now folds this to a `{__compositeStep, args}` envelope
+    // (../fold/fold.ts) that ../discovery/fold-import.ts's bridge resolves
+    // through the folding file's own imports — interpreted when the callee
+    // is a project-file registered Composite (chant #1023), invoked for
+    // real otherwise (every lexicon-package composite, which is what
+    // `Checkout` is) — and reads `.step` off the REAL result. Kept as a
+    // test rather than deleted: the assertion that the divergence stays
+    // closed.
+    const source = `const bad = new Thing({ x: Checkout({}).step });`;
+    const sourceFile = ts.createSourceFile("t.ts", source, ts.ScriptTarget.Latest, true);
+    const consts = collectConsts(sourceFile);
+    const badInit = consts.get("bad") as ts.NewExpression;
+
+    expect(foldResource(badInit, consts, [])).toEqual({
+      __resource: "Thing",
+      props: { x: { __compositeStep: "Checkout", args: [{}] } },
+    });
+
+    // findSubsetViolation (fold()'s own shared predicate, no opt-in needed
+    // anymore) agrees the shape is admissible.
+    const stepAccessExpr = (
+      (badInit.arguments![0] as ts.ObjectLiteralExpression).properties[0] as ts.PropertyAssignment
+    ).initializer;
+    expect(findSubsetViolation(stepAccessExpr)).toBeUndefined();
+
+    const context: LintContext = { sourceFile, entities: [], filePath: "t.ts", lexicon: undefined };
+    expect(evl001NonLiteralExpressionRule.check(context)).toHaveLength(0);
+  });
+
   test("nested resource construction: NO LONGER a divergence (chant #1169) — both fold and EVL001 accept it", () => {
     // This was the largest divergence in the table until #1169: a nested
     // `new Type()` as a property value could only fold to a {__resource, props}
@@ -352,10 +437,14 @@ describe("findSubsetViolation — optional intrinsic registry (#1044)", () => {
     expect(v?.message).toContain("function call as a value is not foldable: Ref(...)");
   });
 
-  test("the registry doesn't widen anything else: a name in it without the opt-in, a method call, and .map all stay violations", () => {
+  test("the registry doesn't widen anything else: a name in it without the opt-in, a closure-taking method, and a plain call stay violations", () => {
     const notOptedIn: IntrinsicDef[] = [{ name: "Reference", isTag: false }];
     expect(findSubsetViolation(propValue(`Reference("db")`), notOptedIn)).toBeDefined();
-    expect(findSubsetViolation(propValue(`aws.Ref("db")`), REF)).toBeDefined();
+    // chant #1966 — `aws.Ref("db")` is a method call (`Ref` reached through a
+    // namespace, not a bare identifier), so it's no longer here: shape-wise
+    // it's now the same resolution-dependent divergence
+    // "method call on an unresolved receiver" documents above, unrelated to
+    // whether `Ref` itself is opted into `foldsAsCall`.
     expect(findSubsetViolation(propValue(`cidrs.map((c) => c)`, `const cidrs = [];`), REF)).toBeDefined();
     expect(findSubsetViolation(propValue(`makeName("a")`), REF)).toBeDefined();
   });

package/src/fold/subset.ts

@@ -1,6 +1,6 @@
 import * as ts from "typescript";
 import { isFoldableHelperName } from "./foldable-helpers";
-import { intrinsicCallFolds, type IntrinsicDef } from "../lexicon";
+import { intrinsicCallFolds, intrinsicCallFoldsEagerly, type IntrinsicDef } from "../lexicon";
 
 /**
  * subset — the single canonical definition of chant's statically-foldable
@@ -265,6 +265,26 @@ function checkArrayElement(
  * environment-dependent exceptions). Returns the first (deepest,
  * `fold()`-evaluation-order) unsupported node, or `undefined` when `node`'s
  * whole shape is foldable.
+ *
+ * The `<call>(...).step` composite-consumer idiom (`Checkout({...}).step`,
+ * every lexicon's single-action `Composite()` wrapper embedded inline in a
+ * `Job`'s `steps` array — see composites.mdx) used to be an EVL-only,
+ * MORE-permissive divergence here (chant #1544's `allowCompositeStepAccess`
+ * opt-in parameter, since removed): `fold()` had no way to invoke an
+ * arbitrary composite factory, so it fell the file back to run for this
+ * shape (documented, correct behavior, never an error) while this shared
+ * predicate had to be told to stop treating that fallback as a lint error.
+ * chant #1174 closed the divergence — `fold()` now folds exactly this shape
+ * (narrowed to the literal member name `"step"`, the one idiom actually in
+ * use) — so this classifier accepts it unconditionally, the same way it
+ * already accepts a nested `new Type(...)` unconditionally since #1169.
+ *
+ * chant #1966 adds a CallExpression whose callee is a property access —
+ * `github.actor.toString()`, `matrix("os").toString()`, `[...].join(",")` —
+ * to the same unconditional-acceptance set: whether the receiver actually
+ * folds to a value with a callable method of that name is resolution-
+ * dependent (module doc, point 1), so this classifier stays permissive and
+ * only recurses into shape.
  */
 export function findSubsetViolation(
   node: ts.Node,
@@ -334,6 +354,13 @@ export function findSubsetViolation(
   }
 
   if (ts.isPropertyAccessExpression(node)) {
+    // chant #1174 — see this function's doc comment. `<call>(...).step`
+    // (any callee, any argument shape) is the composite-consumer idiom, and
+    // `fold()` now folds it too (narrowed to the literal member `"step"` —
+    // see fold.ts's PropertyAccessExpression branch).
+    if (node.name.text === "step" && ts.isCallExpression(node.expression)) {
+      return undefined;
+    }
     return findSubsetViolation(node.expression, intrinsics);
   }
 
@@ -358,7 +385,10 @@ export function findSubsetViolation(
     }
     // Flow-insensitive — see module doc: fold() short-circuits &&/||/?? and
     // only evaluates the taken side; EVL requires both sides shape-valid.
-    return findSubsetViolation(node.left, intrinsics) ?? findSubsetViolation(node.right, intrinsics);
+    return (
+      findSubsetViolation(node.left, intrinsics) ??
+      findSubsetViolation(node.right, intrinsics)
+    );
   }
 
   if (ts.isConditionalExpression(node)) {
@@ -426,6 +456,40 @@ export function findSubsetViolation(
       return undefined;
     }
 
+    // chant #1966 — the eager counterpart of the #1044 case above: a lexicon
+    // intrinsic registered with `foldsEagerly` instead of `foldsAsCall`
+    // ({@link intrinsicCallFoldsEagerly}, ../lexicon.ts). Same registry-gated
+    // shape, same reasoning.
+    if (
+      intrinsics &&
+      ts.isIdentifier(node.expression) &&
+      intrinsics.some((i) => i.name === (node.expression as ts.Identifier).text && intrinsicCallFoldsEagerly(i))
+    ) {
+      for (const arg of node.arguments) {
+        const v = findSubsetViolation(arg, intrinsics);
+        if (v) return v;
+      }
+      return undefined;
+    }
+
+    // chant #1966 — a method call (`github.actor.toString()`, `[...].join(",")`,
+    // `matrix("os").toString()`): `fold()` now folds this shape unconditionally
+    // — the receiver must fold to a real value with the named method, which is
+    // resolution-dependent (module doc, point 1) and so out of reach for a
+    // syntax-only classifier, exactly the same asymmetry as `.step` above and
+    // a same-file `new` used as a value (#1169). Accepted here regardless of
+    // the intrinsics registry, unlike the two cases just above: nothing about
+    // whether a method call folds depends on a lexicon's registration.
+    if (ts.isPropertyAccessExpression(node.expression)) {
+      const v = findSubsetViolation(node.expression.expression, intrinsics);
+      if (v) return v;
+      for (const arg of node.arguments) {
+        const argViolation = findSubsetViolation(arg, intrinsics);
+        if (argViolation) return argViolation;
+      }
+      return undefined;
+    }
+
     return violation(node, callExpressionMessage(node));
   }
 

package/src/index.ts

@@ -7,6 +7,9 @@
 export * from "./declarable";
 export * from "./composite";
 export * from "./provenance";
+export * from "./secret-provenance";
+export * from "./secret-materialization";
+export * from "./effect-receipt";
 export * from "./build-params";
 export * from "./intrinsic";
 export * from "./types";
@@ -43,6 +46,7 @@ export * from "./lint/selectors";
 export * from "./lint/named-checks";
 export * from "./lint/post-synth";
 export * from "./lint/policy";
+export * from "./lint/pipeline-change-gate";
 export * from "./lint/rule-loader";
 export * from "./lint/discover";
 export * from "./import/parser";

package/src/lexicon-schema.ts

@@ -21,6 +21,9 @@ export const IntrinsicDefSchema = z.object({
   // registration written before #1044 means. Only an explicit `true` opts a
   // call into folding. See IntrinsicDef.foldsAsCall in ../lexicon.ts.
   foldsAsCall: z.boolean().optional(),
+  // chant #1966 — same default-off shape as foldsAsCall, for the EAGER
+  // call-form opt-in. See IntrinsicDef.foldsEagerly in ../lexicon.ts.
+  foldsEagerly: z.boolean().optional(),
 });
 
 // ---------------------------------------------------------------------------

package/src/lexicon.ts

@@ -226,6 +226,29 @@ export interface IntrinsicDef {
    * run path would have called, from the module the source itself named.
    */
   readonly foldsAsCall?: boolean;
+  /**
+   * chant #1966 — opt this intrinsic's PLAIN-CALL form into EAGER folding:
+   * unlike {@link foldsAsCall}, which defers to a `{__intrinsic}` envelope
+   * revived later, `fold()` (../fold/fold.ts) calls the real function
+   * immediately, with the folded arguments, and its real return value IS the
+   * folded value.
+   *
+   * Exists for a lexicon helper whose result is commonly embedded directly in
+   * a template literal (`` `${matrix("os")}` ``, github's
+   * `matrix`/`inputs`/…) — an envelope is still a plain `{__intrinsic, args}`
+   * object when the enclosing template folds, so `String()` coercion at fold
+   * time would stringify it as `"[object Object]"` instead of the real value.
+   * Eager evaluation produces the real, already-live result instead.
+   *
+   * Same admission bar as {@link foldsAsCall} (a pure function of its
+   * arguments — no I/O, no mutable state, no dependency on anything but its
+   * arguments) and mutually exclusive with both {@link isTag} and
+   * `foldsAsCall`: a plain call folds exactly one way.
+   * `../discovery/fold-import.ts`'s `resolveActiveLexiconExport` checks this
+   * to admit the function export into `externals` at all — a lexicon
+   * package's function export is excluded there otherwise.
+   */
+  readonly foldsEagerly?: boolean;
 }
 
 /**
@@ -257,8 +280,8 @@ export interface IntrinsicDef {
  * `dist/manifest.json`) that may predate either field. `undefined` there
  * means what it always did — not a tag, not opted in.
  */
-export function intrinsicFolds(def: { isTag?: boolean; foldsAsCall?: boolean }): boolean {
-  return intrinsicTagFolds(def) || intrinsicCallFolds(def);
+export function intrinsicFolds(def: { isTag?: boolean; foldsAsCall?: boolean; foldsEagerly?: boolean }): boolean {
+  return intrinsicTagFolds(def) || intrinsicCallFolds(def) || intrinsicCallFoldsEagerly(def);
 }
 
 /** True when this intrinsic's TAGGED-TEMPLATE form folds (`Sub\`...\``) — see {@link intrinsicFolds}. */
@@ -280,6 +303,15 @@ export function intrinsicCallFolds(def: { isTag?: boolean; foldsAsCall?: boolean
   return def.isTag !== true && def.foldsAsCall === true;
 }
 
+/**
+ * True when this intrinsic's PLAIN-CALL form folds EAGERLY (chant #1966) —
+ * i.e. the lexicon opted it in via {@link IntrinsicDef.foldsEagerly}.
+ * `isTag: true` disqualifies, same as {@link intrinsicCallFolds}.
+ */
+export function intrinsicCallFoldsEagerly(def: { isTag?: boolean; foldsEagerly?: boolean }): boolean {
+  return def.isTag !== true && def.foldsEagerly === true;
+}
+
 /**
  * Options passed to a MigrationSource by `chant migrate`.
  */
@@ -406,6 +438,61 @@ export interface ComponentPipelineResult {
   jobs: ComponentPipelineJob[];
 }
 
+/**
+ * Finding-mode a scheduled Op surfaces on drift — the vocabulary the
+ * temporal-lexicon composites (`WorkflowAuditOp`/`PipelineAuditOp`/
+ * `ReconcileOp`) already declare on the Op itself (#927). The mode is baked
+ * into the Op's own activity args at build time and is never re-passed on the
+ * generated CI invocation; here it decides only what token/permission wiring
+ * the generated job needs to act on a finding — elevated write access for
+ * `issue`/`pull-request`/`merge-request`, none for `report`.
+ */
+export type OpFindingMode = "report" | "issue" | "pull-request" | "merge-request";
+
+/** One scheduled Op to generate CI for — the cron-triggered counterpart to a component (generate mode). */
+export interface ScheduledOpSpec {
+  /** Op name (`*.op.ts`'s `Op({ name })`) — what `chant run <name>` targets. */
+  name: string;
+  /** Cron expression driving the CI-native trigger — the CI-only alternative to a Temporal `TemporalSchedule`. */
+  schedule: string;
+  /** This Op's finding-mode, for permission/token wiring only (see {@link OpFindingMode}). Default: "report" — no elevated permissions. */
+  findingMode?: OpFindingMode;
+}
+
+/** One CI job generated for a scheduled Op. */
+export interface OpPipelineJob {
+  /** CI job name (safe as a YAML key). */
+  jobName: string;
+  /** The Op this job runs. */
+  op: string;
+  /** Cron expression this job's workflow is scheduled on. */
+  schedule: string;
+  /** The finding-mode wired for this job. */
+  findingMode: OpFindingMode;
+}
+
+/**
+ * One generated CI file for a scheduled Op. Unlike a component pipeline —
+ * one combined document for the whole graph — a cron trigger is
+ * workflow-scoped in every CI provider chant targets (GitHub Actions'
+ * `on.schedule`, a GitLab pipeline schedule bound to one `.gitlab-ci.yml`), so
+ * each scheduled Op gets its own file.
+ */
+export interface OpPipelineFile {
+  /** Suggested file name (e.g. `<op-name>.yml`), relative to the provider's workflow directory. */
+  name: string;
+  /** The synthesized CI YAML for this Op. */
+  yaml: string;
+}
+
+/** The synthesized CI pipeline for a set of scheduled Ops (generate mode's Op counterpart, #927). */
+export interface OpPipelineResult {
+  /** One file per scheduled Op. */
+  files: OpPipelineFile[];
+  /** Every generated job, in emit order — one per Op. */
+  jobs: OpPipelineJob[];
+}
+
 /**
  * Live status of a single deploy unit (a CloudFormation stack, a K8s release, …)
  * addressed by its deployed name — the per-component presence signal
@@ -439,6 +526,24 @@ export interface BuildRootContext {
   projectRoot: string;
   /** The resolved project configuration, for the lexicon's own namespace. */
   config: Record<string, unknown>;
+  /**
+   * The discovered entities, read-only (#1828 / SOPS provenance). A
+   * contributor that reacts to what the project DECLARED — rather than to
+   * what its config listed — reads them here: the committed-encrypted
+   * `declareSecret()` hook resolves each declaration's `file` into a sidecar
+   * entity, and any future declaration-driven contributor needs the same.
+   *
+   * Read-only on purpose. The merge that follows is the only thing that adds
+   * to the entity set, and it refuses a name collision rather than
+   * overwriting; a contributor mutating the map directly would slip past
+   * that. Contributors run in order, so a contributor also sees entities
+   * earlier contributors added.
+   *
+   * Optional: a caller that has no entity set (a plugin hook invoked
+   * directly, a graph mode that never discovered) omits it, and a hook must
+   * treat an absent map as an empty one.
+   */
+  entities?: ReadonlyMap<string, Declarable>;
 }
 
 /**
@@ -450,6 +555,17 @@ export interface BuildRootContribution {
   warnings?: string[];
 }
 
+/**
+ * A plugin's `buildRoots` hook, already bound to this invocation's project
+ * root and config (`collectBuildRootContributors`, ./cli/plugins.ts). What is
+ * NOT bindable that early is the entity set — discovery has not run yet — so
+ * the merge supplies it when it calls the closure. A contributor that ignores
+ * the argument is still assignable, which is what every pre-#1828 hook does.
+ */
+export type BuildRootContributor = (
+  ctx: Pick<BuildRootContext, "entities">,
+) => Promise<BuildRootContribution>;
+
 export interface LexiconPlugin {
   // ── Required ──────────────────────────────────────────────
   /** Human-readable name (e.g. "aws", "gcp") */
@@ -540,6 +656,17 @@ export interface LexiconPlugin {
    */
   auditCatalog?(): Record<string, RuleMeta>;
 
+  /**
+   * Parse standalone template content (a file audit discovery classified for
+   * this lexicon) into the lexicon's entity graph, keyed the way `ctx.entities`
+   * is during a build. Lets entity-reading post-synth checks fire on
+   * `chant audit` of hand-written manifests — parse-to-graph rather than
+   * output-reading rule variants (#1567). Implementations must tolerate
+   * arbitrary external content: a malformed document yields no entities, never
+   * a throw. Omit for lexicons whose audit checks read `ctx.outputs`.
+   */
+  auditEntities?(content: string): Map<string, Declarable>;
+
   /**
    * Machine-readable spec-coverage accounting for `check-lexicon` (#1330).
    *
@@ -600,6 +727,20 @@ export interface LexiconPlugin {
     options?: ComponentPipelineOptions,
   ): ComponentPipelineResult;
 
+  /**
+   * Generate CI for a set of scheduled, stateless Ops — the cron-triggered
+   * sibling of {@link generateComponentPipeline} (#927). Each
+   * `ScheduledOpSpec` becomes its own CI file (cron triggers are
+   * workflow-scoped in every CI provider chant targets), invoking `chant run
+   * <name>` on the local executor — the same one-shot invocation `chant run
+   * <op>` runs by hand. Only CI-provider lexicons (gitlab, github, forgejo)
+   * implement this; omit for lexicons that are not CI providers.
+   */
+  generateOpPipeline?(
+    ops: ScheduledOpSpec[],
+    options?: ComponentPipelineOptions,
+  ): OpPipelineResult;
+
   /**
    * Render this lexicon's config-declared build roots into entities (#1548
    * piece 3) — the seam for a build root that is NOT typed chant source. The
@@ -1115,10 +1256,15 @@ export interface TeardownOutcome {
   /**
    * - `deleted` — gone, including already-gone (deletion is idempotent);
    * - `failed` — the delete errored (core retries these once);
-   * - `not-prunable` — deliberately not deleted; `detail` says why.
+   * - `not-prunable` — deliberately not deleted; `detail` says why;
+   * - `retained` — owned and no longer declared, but deliberately kept
+   *   (#1365 decision 5): a `generated-once` secret never enters the prunable
+   *   set, because deleting it would destroy the only copy of material chant
+   *   never held. Reported loudly, never deleted; deletion is an explicit act
+   *   (`kubectl delete`, or a future gated op), never a sweep's.
    */
-  outcome: "deleted" | "failed" | "not-prunable";
-  /** The error for `failed`, the reason for `not-prunable`. */
+  outcome: "deleted" | "failed" | "not-prunable" | "retained";
+  /** The error for `failed`, the reason for `not-prunable`/`retained`. */
   detail?: string;
 }
 

package/src/lifecycle/change-set.ts

@@ -31,11 +31,30 @@ import { unobservedReasonText, type UnobservedReason } from "../observation";
  *   not drift, just the runtime doing its job. `runtimeOwner` names the
  *   declared entity it belongs to.
  * - `noop` — declared and live with no drift, or already reconciled.
+ * - `effect` — a declared effect receipt (#1832) whose live value is absent or
+ *   differs from the resolved expectation: the effect step will fire. Never a
+ *   `create` or `update` — the generic apply path is observe-only to receipts,
+ *   and the `effect()` step is the sole writer (epic #1703, decision 3). Read
+ *   `effect` for the effect's identity and `effectReason` for why it fires.
  * - `unobserved` — declared, and the lexicon could not look (#1089). Not a
  *   proposal at all: it is the plan admitting a hole. Never a create, never a
  *   delete. Read `unobservedReason` for which hole.
  */
-export type ChangeAction = "create" | "update" | "delete" | "adopt" | "runtime" | "noop" | "unobserved";
+export type ChangeAction = "create" | "update" | "delete" | "adopt" | "runtime" | "noop" | "effect" | "unobserved";
+
+/**
+ * Why an `effect` entry proposes a fire (#1832).
+ *
+ * - `receipt-absent` — the provider confirmed the receipt absent: the effect
+ *   has never recorded a run (or the run crashed before the write — the
+ *   at-least-once case this classification exists to preserve).
+ * - `receipt-stale` — the receipt is live but its value differs from the
+ *   resolved expectation: the effect's inputs changed since the last run.
+ * - `unresolved-input` — a reference input could not resolve at plan time, so
+ *   the expectation cannot be computed. The fire is proposed rather than
+ *   guessed away; the effect step resolves again at run.
+ */
+export type EffectFireReason = "receipt-absent" | "receipt-stale" | "unresolved-input";
 
 /**
  * Who answers "is this resource chant's?". `unknown` until a live ownership
@@ -100,6 +119,16 @@ export interface ChangeSetEntry {
   queried?: string;
   /** The declared entity this resource's owner chain resolves to, for `action: "runtime"` (#1077). */
   runtimeOwner?: string;
+  /**
+   * The effect a receipt witnesses (#1832), for entries derived from an effect
+   * receipt. On `action: "effect"` it names what will fire; on a receipt's
+   * `noop`/`unobserved` rows it keeps the attribution.
+   */
+  effect?: string;
+  /** Why the effect fires, for `action: "effect"` (#1832). */
+  effectReason?: EffectFireReason;
+  /** Human-readable backing for `effectReason` (the digests that differ, the unresolved path). */
+  effectDetail?: string;
 }
 
 export interface ChangeSet {
@@ -234,13 +263,14 @@ export function buildChangeSet(env: string, input: DiffLiveInput, options?: Chan
   return { env, entries };
 }
 
-const ACTION_ORDER: ChangeAction[] = ["create", "update", "delete", "adopt", "runtime", "noop", "unobserved"];
+const ACTION_ORDER: ChangeAction[] = ["create", "update", "effect", "delete", "adopt", "runtime", "noop", "unobserved"];
 
 /** Count entries per action. */
 export function summarize(cs: ChangeSet): Record<ChangeAction, number> {
   const counts: Record<ChangeAction, number> = {
     create: 0,
     update: 0,
+    effect: 0,
     delete: 0,
     adopt: 0,
     runtime: 0,
@@ -257,10 +287,10 @@ export function summarize(cs: ChangeSet): Record<ChangeAction, number> {
  * GitLab renders an `artifacts:reports:terraform` artifact in the merge-request
  * UI as "N to add, M to change, K to delete". The format is generic — any tool
  * that emits this JSON gets the widget — and the chant plan maps onto it
- * directly. Only the mutating actions count: `adopt`, `runtime`, `noop` and
- * `unobserved` are excluded, since the widget has no column for "live but
- * undeclared", "expected runtime child" (#1077), "no change", or "could not
- * look" (#1089). The widget is therefore a floor, not a complete plan: read
+ * directly. Only the mutating actions count: `adopt`, `runtime`, `noop`,
+ * `effect` and `unobserved` are excluded, since the widget has no column for
+ * "live but undeclared", "expected runtime child" (#1077), "no change", "an
+ * effect will fire" (#1832), or "could not look" (#1089). The widget is therefore a floor, not a complete plan: read
  * the full change set when entities are unobserved or classified runtime.
  *
  * The widget label reads "Terraform" regardless of producer; that is GitLab's
@@ -292,9 +322,18 @@ export function renderChangeSet(cs: ChangeSet): string {
         ? "\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):"
-          : `\n${action.toUpperCase()}:`,
+          : action === "effect"
+            ? "\nEFFECT (receipt absent or stale; the effect step fires — the generic apply never writes a receipt):"
+            : `\n${action.toUpperCase()}:`,
     );
     for (const e of group) {
+      if (e.action === "effect") {
+        lines.push(
+          `  effect will fire: ${e.effect ?? e.name} — receipt ${e.name}${e.type ? ` (${e.type})` : ""}` +
+            `${e.effectDetail ? ` — ${e.effectDetail}` : ""}`,
+        );
+        continue;
+      }
       const own = e.ownership === "unknown" ? "" : ` [${e.ownership}]`;
       const why = e.unobservedReason
         ? ` — ${unobservedReasonText(e.unobservedReason)}${e.unobservedDetail ? `: ${e.unobservedDetail}` : ""}`