@intentius/chant 0.46.0 → 0.49.0

package/src/lexicon.ts

@@ -439,6 +439,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 +468,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 +569,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).
    *
@@ -1115,10 +1155,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}` : ""}`

package/src/lifecycle/index.ts

@@ -7,6 +7,8 @@ export * from "./deep-diff";
 export * from "./deep-observe";
 export * from "./observation-baseline";
 export * from "./change-set";
+export * from "./unobserved-gate";
+export * from "./receipt-plan";
 export * from "./affected";
 export * from "./release-ledger";
 export * from "./build-ledger";

package/src/lifecycle/observation-baseline.test.ts

@@ -97,3 +97,49 @@ describe("acceptDeviations", () => {
     expect(countAccepted(null)).toBe(0);
   });
 });
+
+describe("acceptDeviations refuses effect receipts (#1833)", () => {
+  const now = "2026-08-24T00:00:00.000Z";
+
+  test("refuses a deviation whose type is the core receipt entityType", () => {
+    expect(() =>
+      acceptDeviations(emptyBaseline("prod"), "chant", [
+        { entity: "seededReceipt", type: "Chant::EffectReceipt", path: "value", value: "gone" },
+      ], { now }),
+    ).toThrow(/effect receipt "seededReceipt"/);
+  });
+
+  test("refuses a deviation on an entity the caller recognized as a receipt (materialized row)", () => {
+    expect(() =>
+      acceptDeviations(emptyBaseline("prod"), "aws", [
+        { entity: "migratedReceipt", type: "AWS::SSM::Parameter", path: "Value", value: "stale" },
+      ], { now, receipts: new Set(["migratedReceipt"]) }),
+    ).toThrow(/effect receipt "migratedReceipt"/);
+  });
+
+  test("the refusal names the receipt and the effect step as sole writer, and records nothing", () => {
+    const before = emptyBaseline("prod");
+    let error: Error | undefined;
+    try {
+      acceptDeviations(before, "aws", [
+        { entity: "Role", type: "AWS::IAM::Role", path: "MaxSessionDuration", value: 7200 },
+        { entity: "migratedReceipt", type: "AWS::SSM::Parameter", path: "Value", value: "stale" },
+      ], { now, receipts: new Set(["migratedReceipt"]) });
+    } catch (e) {
+      error = e as Error;
+    }
+    expect(error).toBeDefined();
+    expect(error!.message).toContain('effect receipt "migratedReceipt"');
+    expect(error!.message).toContain("only writer");
+    expect(error!.message).toContain("defuse the effect");
+    // The whole acceptance aborts — the non-receipt row was not recorded either.
+    expect(before.lexicons).toEqual({});
+  });
+
+  test("passes: non-receipt deviations accept as before, receipts set present", () => {
+    const b = acceptDeviations(emptyBaseline("prod"), "aws", [
+      { entity: "Role", type: "AWS::IAM::Role", path: "MaxSessionDuration", value: 7200 },
+    ], { now, receipts: new Set(["migratedReceipt"]) });
+    expect(baselineForLexicon(b, "aws").Role.accepted).toHaveLength(1);
+  });
+});

package/src/lifecycle/observation-baseline.ts

@@ -37,6 +37,7 @@
 
 import { readBlobFromPath, writeBlobToPath } from "./git";
 import { sortedJsonReplacer } from "../utils";
+import { EFFECT_RECEIPT_ENTITY_TYPE } from "../effect-receipt";
 
 /** The file name under `<environment>/` on the orphan branch. */
 export const OBSERVATION_BASELINE_FILE = "observation-baseline.json";
@@ -140,19 +141,50 @@ export interface DeviationToAccept {
   note?: string;
 }
 
+/** Options for {@link acceptDeviations}. */
+export interface AcceptDeviationsOptions {
+  /** ISO timestamp to stamp instead of the wall clock (tests, replays). */
+  now?: string;
+  /**
+   * Entity names the caller recognized as effect receipts (#1833) — the
+   * marker-based read (`collectEffectReceipts`, ../effect-receipt.ts) over
+   * the build's entities, which is how a lexicon-materialized receipt row is
+   * caught even though its `entityType` is the row's own. Core-typed
+   * receipts are refused regardless, via {@link DeviationToAccept.type}.
+   */
+  receipts?: ReadonlySet<string>;
+}
+
 /**
  * Record deviations as accepted, returning a new baseline (the input is not
  * mutated). An existing acceptance for the same entity+path is replaced — that
  * is how re-accepting after a deliberate change works, and it keeps the file
  * from growing a second entry for every value a path has ever held.
+ *
+ * REFUSES a deviation on an effect receipt (#1833, epic #1703), throwing
+ * before anything is recorded: a receipt is the declared witness that its
+ * effect ran, and the `effect()` step is its only writer — baselining a
+ * receipt's live value would accept "the effect never fired" as the new
+ * normal and silently defuse the effect. The whole acceptance aborts, not
+ * just the receipt's row, so a partial baseline never lands.
  */
 export function acceptDeviations(
   baseline: ObservationBaseline,
   lexicon: string,
   deviations: readonly DeviationToAccept[],
-  opts?: { now?: string },
+  opts?: AcceptDeviationsOptions,
 ): ObservationBaseline {
   if (deviations.length === 0) return baseline;
+  for (const dev of deviations) {
+    if (dev.type === EFFECT_RECEIPT_ENTITY_TYPE || opts?.receipts?.has(dev.entity)) {
+      throw new Error(
+        `cannot accept drift on effect receipt "${dev.entity}" (path ${dev.path}): ` +
+          `the effect() step is the receipt's only writer — accepting the live value would ` +
+          `silently defuse the effect. Re-run the effect (or change its inputs) instead of ` +
+          `baselining the receipt.`,
+      );
+    }
+  }
   const now = opts?.now ?? new Date().toISOString();
   const lexicons: Record<string, BaselineLexicon> = { ...baseline.lexicons };
   const entities: BaselineLexicon = { ...(lexicons[lexicon] ?? {}) };

package/src/lifecycle/receipt-plan.test.ts

@@ -0,0 +1,250 @@
+import { describe, it, expect } from "vitest";
+import {
+  planReceipts,
+  mergeReceiptEntries,
+  observedValueResolver,
+  readReceiptValue,
+  type ReceiptReading,
+} from "./receipt-plan";
+import { buildChangeSet, renderChangeSet, summarize, type ChangeSet } from "./change-set";
+import {
+  EffectReceipt,
+  EXISTENCE_EXPECTATION,
+  receiptExpectation,
+  resolveReceiptExpectation,
+  collectEffectReceipts,
+  type EffectReceiptDeclaration,
+} from "../effect-receipt";
+import { AttrRef } from "../attrref";
+import type { ResourceMetadata } from "../lexicon";
+import type { ReceiptInputResolver } from "../effect-receipt";
+
+const noRefs: ReceiptInputResolver = (_ref, path) => {
+  throw new Error(`unexpected reference at ${path}`);
+};
+
+function receiptsOf(...decls: Array<[string, EffectReceiptDeclaration]>): Map<string, EffectReceiptDeclaration> {
+  return new Map(decls);
+}
+
+describe("planReceipts", () => {
+  it("absent receipt proposes the fire", () => {
+    const r = EffectReceipt("dbMigrated", { effect: "db-migrate", flavor: "existence" });
+    const readings = new Map<string, ReceiptReading>([
+      ["dbMigrated", { observed: true, present: false, lexicon: "aws" }],
+    ]);
+
+    const entries = planReceipts(receiptsOf(["dbMigrated", r]), readings, noRefs);
+
+    expect(entries).toHaveLength(1);
+    expect(entries[0].action).toBe("effect");
+    expect(entries[0].effect).toBe("db-migrate");
+    expect(entries[0].effectReason).toBe("receipt-absent");
+    expect(entries[0].evidence).toEqual({ declared: true, inSnapshot: false, live: false, observed: true });
+  });
+
+  it("stale hash proposes the fire, with both values in the detail", () => {
+    const r = EffectReceipt("seeded", { effect: "seed", flavor: "hash", inputs: { rows: 10 } });
+    const expected = receiptExpectation(r);
+    const readings = new Map<string, ReceiptReading>([
+      ["seeded", { observed: true, present: true, value: "sha256:0000", lexicon: "aws" }],
+    ]);
+
+    const entries = planReceipts(receiptsOf(["seeded", r]), readings, noRefs);
+
+    expect(entries[0].action).toBe("effect");
+    expect(entries[0].effectReason).toBe("receipt-stale");
+    expect(entries[0].effectDetail).toContain("sha256:0000");
+    expect(entries[0].effectDetail).toContain(expected);
+  });
+
+  it("matching receipt is a clean noop", () => {
+    const r = EffectReceipt("seeded", { effect: "seed", flavor: "hash", inputs: { rows: 10 } });
+    const readings = new Map<string, ReceiptReading>([
+      ["seeded", { observed: true, present: true, value: receiptExpectation(r), lexicon: "aws" }],
+    ]);
+
+    const entries = planReceipts(receiptsOf(["seeded", r]), readings, noRefs);
+
+    expect(entries[0].action).toBe("noop");
+    expect(entries[0].effect).toBe("seed");
+  });
+
+  it("matching existence receipt is a clean noop", () => {
+    const r = EffectReceipt("bootstrapped", { effect: "bootstrap", flavor: "existence" });
+    const readings = new Map<string, ReceiptReading>([
+      ["bootstrapped", { observed: true, present: true, value: EXISTENCE_EXPECTATION }],
+    ]);
+
+    expect(planReceipts(receiptsOf(["bootstrapped", r]), readings, noRefs)[0].action).toBe("noop");
+  });
+
+  it("a lexicon that could not look yields unobserved with its reason, never a clean row", () => {
+    const r = EffectReceipt("dbMigrated", { effect: "db-migrate", flavor: "existence" });
+    const readings = new Map<string, ReceiptReading>([
+      ["dbMigrated", { observed: false, present: false, unobservedReason: "no-credentials", unobservedDetail: "no AWS credentials" }],
+    ]);
+
+    const entries = planReceipts(receiptsOf(["dbMigrated", r]), readings, noRefs);
+
+    expect(entries[0].action).toBe("unobserved");
+    expect(entries[0].unobservedReason).toBe("no-credentials");
+    expect(entries[0].unobservedDetail).toBe("no AWS credentials");
+  });
+
+  it("a receipt no lexicon observes yields unobserved, loudly, never silently clean", () => {
+    const r = EffectReceipt("dbMigrated", { effect: "db-migrate", flavor: "existence" });
+
+    const entries = planReceipts(receiptsOf(["dbMigrated", r]), new Map(), noRefs);
+
+    expect(entries[0].action).toBe("unobserved");
+    expect(entries[0].unobservedReason).toBe("unsupported-kind");
+    expect(entries[0].unobservedDetail).toContain("db-migrate");
+    expect(entries[0].unobservedDetail).toContain("unknown, not clean");
+  });
+
+  it("a reference that cannot resolve at plan time proposes the fire with an unresolved-input note", () => {
+    const parent = { entityType: "Test::Db" };
+    const ref = new AttrRef(parent, "endpoint");
+    ref._setLogicalName("db");
+    const r = EffectReceipt("seeded", { effect: "seed", flavor: "hash", inputs: { endpoint: ref } });
+    const readings = new Map<string, ReceiptReading>([
+      ["seeded", { observed: true, present: true, value: "sha256:live" }],
+    ]);
+
+    // Resolver over observed values that do NOT include db.endpoint.
+    const entries = planReceipts(receiptsOf(["seeded", r]), readings, observedValueResolver({}));
+
+    expect(entries[0].action).toBe("effect");
+    expect(entries[0].effectReason).toBe("unresolved-input");
+    expect(entries[0].effectDetail).toContain("unresolved input");
+    expect(entries[0].effectDetail).toContain("db.endpoint");
+  });
+
+  it("a reference input resolves against observed values and the comparison uses the resolved digest", () => {
+    const parent = { entityType: "Test::Db" };
+    const ref = new AttrRef(parent, "endpoint");
+    ref._setLogicalName("db");
+    const r = EffectReceipt("seeded", { effect: "seed", flavor: "hash", inputs: { endpoint: ref } });
+
+    const observed: Record<string, ResourceMetadata> = {
+      db: { type: "Test::Db", status: "ok", attributes: { endpoint: "db.example.internal:5432" } },
+    };
+    const resolver = observedValueResolver(observed);
+    const expected = resolveReceiptExpectation(r, resolver);
+    const readings = new Map<string, ReceiptReading>([
+      ["seeded", { observed: true, present: true, value: expected }],
+    ]);
+
+    expect(planReceipts(receiptsOf(["seeded", r]), readings, resolver)[0].action).toBe("noop");
+  });
+
+  it("crash between effect and receipt write: the stale receipt re-proposes the fire on the next plan", () => {
+    // Run 1 wrote the receipt for inputs { schema: 1 }. The effect for
+    // { schema: 2 } ran, then the process died before the receipt write —
+    // the live value still carries run 1's digest.
+    const run1 = EffectReceipt("migrated", { effect: "migrate", flavor: "hash", inputs: { schema: 1 } });
+    const run2 = EffectReceipt("migrated", { effect: "migrate", flavor: "hash", inputs: { schema: 2 } });
+    const readings = new Map<string, ReceiptReading>([
+      ["migrated", { observed: true, present: true, value: receiptExpectation(run1) }],
+    ]);
+
+    const entries = planReceipts(receiptsOf(["migrated", run2]), readings, noRefs);
+
+    expect(entries[0].action).toBe("effect");
+    expect(entries[0].effectReason).toBe("receipt-stale");
+
+    // The first-run variant of the same crash: the effect ran, the write
+    // never happened, the receipt is absent — the fire is proposed again.
+    const absent = new Map<string, ReceiptReading>([["migrated", { observed: true, present: false }]]);
+    expect(planReceipts(receiptsOf(["migrated", run2]), absent, noRefs)[0].effectReason).toBe("receipt-absent");
+  });
+});
+
+describe("mergeReceiptEntries", () => {
+  it("replaces the generic create proposed for an absent receipt with the effect row", () => {
+    const r = EffectReceipt("dbMigrated", { effect: "db-migrate", flavor: "existence" });
+    const receipts = receiptsOf(["dbMigrated", r]);
+
+    // The generic classification knows nothing about receipts: declared and
+    // confirmed absent classifies as create.
+    const cs = buildChangeSet("prod", {
+      declared: new Set(["dbMigrated", "bucket"]),
+      observedNow: { bucket: { type: "Test::Bucket", status: "ok" } },
+      observedThen: undefined,
+    });
+    expect(cs.entries.find((e) => e.name === "dbMigrated")?.action).toBe("create");
+
+    const entries = planReceipts(receipts, new Map([["dbMigrated", { observed: true, present: false } as ReceiptReading]]), noRefs);
+    mergeReceiptEntries(cs, receipts, entries);
+
+    const row = cs.entries.filter((e) => e.name === "dbMigrated");
+    expect(row).toHaveLength(1);
+    expect(row[0].action).toBe("effect");
+    expect(summarize(cs).create).toBe(0);
+  });
+
+  it("a live receipt is never a prune candidate: the generic delete is replaced", () => {
+    const r = EffectReceipt("dbMigrated", { effect: "db-migrate", flavor: "existence" });
+    const receipts = receiptsOf(["dbMigrated", r]);
+
+    // Worst case for the write-exclusion: the receipt is live and owned but
+    // missing from the declared axis the change set saw (exactly what
+    // withholding it from the apply-bound set produces) — the generic
+    // classification proposes delete, the prune candidacy a receipt must
+    // never have.
+    const cs = buildChangeSet("prod", {
+      declared: new Set<string>(),
+      observedNow: {
+        dbMigrated: { type: "AWS::SSM::Parameter", status: "ok", ownership: "owned" },
+      },
+      observedThen: undefined,
+    });
+    expect(cs.entries.find((e) => e.name === "dbMigrated")?.action).toBe("delete");
+
+    const entries = planReceipts(
+      receipts,
+      new Map([["dbMigrated", { observed: true, present: true, value: EXISTENCE_EXPECTATION } as ReceiptReading]]),
+      noRefs,
+    );
+    mergeReceiptEntries(cs, receipts, entries);
+
+    expect(cs.entries.filter((e) => e.action === "delete")).toHaveLength(0);
+    expect(cs.entries.filter((e) => e.action === "adopt")).toHaveLength(0);
+    expect(cs.entries.find((e) => e.name === "dbMigrated")?.action).toBe("noop");
+  });
+});
+
+describe("renderChangeSet with effect entries", () => {
+  it('renders "effect will fire: <effect>"', () => {
+    const r = EffectReceipt("dbMigrated", { effect: "db-migrate", flavor: "existence" });
+    const cs: ChangeSet = { env: "prod", entries: [] };
+    mergeReceiptEntries(
+      cs,
+      receiptsOf(["dbMigrated", r]),
+      planReceipts(receiptsOf(["dbMigrated", r]), new Map([["dbMigrated", { observed: true, present: false } as ReceiptReading]]), noRefs),
+    );
+
+    const rendered = renderChangeSet(cs);
+    expect(rendered).toContain("effect will fire: db-migrate");
+    expect(rendered).toContain("1 effect");
+    expect(rendered).toContain("the generic apply never writes a receipt");
+  });
+});
+
+describe("readReceiptValue", () => {
+  it("reads value, falling back to the provider's Value casing", () => {
+    expect(readReceiptValue({ value: "a" })).toBe("a");
+    expect(readReceiptValue({ Value: "b" })).toBe("b");
+    expect(readReceiptValue({ value: "a", Value: "b" })).toBe("a");
+    expect(readReceiptValue(undefined)).toBeUndefined();
+  });
+});
+
+describe("collectEffectReceipts over a mixed entity map", () => {
+  it("finds only marker-carrying entities", () => {
+    const r = EffectReceipt("dbMigrated", { effect: "db-migrate", flavor: "existence" });
+    const entities = new Map<string, EffectReceiptDeclaration>([["dbMigrated", r]]);
+    expect([...collectEffectReceipts(entities).keys()]).toEqual(["dbMigrated"]);
+  });
+});