@intentius/chant 0.124.24 → 0.124.25

package/src/effect-receipt.ts

@@ -66,6 +66,28 @@ export const EFFECT_RECEIPT_ENTITY_TYPE = "Chant::EffectReceipt";
  */
 export const EXISTENCE_EXPECTATION = "chant.effect-receipt:exists";
 
+const OUTPUTS_SEPARATOR = "+outputs=";
+
+/**
+ * A receipt expectation with the digest of the step outputs its effect read
+ * appended (#3948). The effect step writes this value, so the next run fires
+ * again when one of those outputs changed, though the declared inputs did not.
+ */
+export function withStepOutputs(expectation: string, outputs: string): string {
+  return `${expectation}${OUTPUTS_SEPARATOR}${outputs}`;
+}
+
+/**
+ * The part of a stored receipt value that the declared inputs determine: the
+ * value without any step-output digest {@link withStepOutputs} appended. The
+ * plan and `receiptStaleness` compare this part, since step outputs exist only
+ * while the Op runs.
+ */
+export function declaredExpectation(value: string): string {
+  const at = value.indexOf(OUTPUTS_SEPARATOR);
+  return at < 0 ? value : value.slice(0, at);
+}
+
 /**
  * An effect receipt declaration — a Declarable, so discovery collects it,
  * `chant list` shows it, and (unlike a secret declaration) serialization

package/src/lexicon-module.ts

@@ -176,12 +176,19 @@ export function resetLexiconModules(): void {
  * Import the module a path-declared lexicon names. Returns `undefined` when
  * `name` is package-backed, so a caller falls through to its package import.
  * An import failure is thrown with the declared path in the message.
+ *
+ * `typeScript: false` imports it with plain node, without registering tsx
+ * (#3276): tsx's ESM hooks run on a thread of their own, which costs the
+ * compiled CLI about 200 MB, so a caller whose module is JavaScript says so.
  */
-export async function importLexiconModule(name: string): Promise<Record<string, unknown> | undefined> {
+export async function importLexiconModule(
+  name: string,
+  options: { typeScript?: boolean } = {},
+): Promise<Record<string, unknown> | undefined> {
   const path = modulePaths.get(name);
   if (path === undefined) return undefined;
   try {
-    ensureTypeScriptLoader();
+    if (options.typeScript !== false) ensureTypeScriptLoader();
     return esModuleNamespace((await import(path)) as Record<string, unknown>);
   } catch (err) {
     throw new Error(

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

@@ -12,6 +12,7 @@ import {
   EXISTENCE_EXPECTATION,
   receiptExpectation,
   resolveReceiptExpectation,
+  withStepOutputs,
   collectEffectReceipts,
   type EffectReceiptDeclaration,
 } from "../effect-receipt";
@@ -70,6 +71,14 @@ describe("planReceipts", () => {
     expect(entries[0].effect).toBe("seed");
   });
 
+  it("a value an effect step wrote with step outputs is a noop when its declared part matches (#3948)", () => {
+    const r = EffectReceipt("seeded", { effect: "seed", flavor: "hash", inputs: { rows: 10 } });
+    const readings = new Map<string, ReceiptReading>([
+      ["seeded", { observed: true, present: true, value: withStepOutputs(receiptExpectation(r), "sha256:abc"), lexicon: "aws" }],
+    ]);
+    expect(planReceipts(receiptsOf(["seeded", r]), readings, noRefs)[0].action).toBe("noop");
+  });
+
   it("matching existence receipt is a clean noop", () => {
     const r = EffectReceipt("bootstrapped", { effect: "bootstrap", flavor: "existence" });
     const readings = new Map<string, ReceiptReading>([

package/src/lifecycle/receipt-plan.ts

@@ -34,6 +34,7 @@
 import { AttrRef } from "../attrref";
 import {
   EXISTENCE_EXPECTATION,
+  declaredExpectation,
   resolveReceiptExpectation,
   type EffectReceiptDeclaration,
   type ReceiptInputResolver,
@@ -198,7 +199,9 @@ export function planReceipts(
       continue;
     }
 
-    if (reading.value === expectation) {
+    // A value an effect step wrote with the digest of the step outputs it read
+    // (#3948) is compared on its declared part: outputs exist only at run.
+    if (typeof reading.value === "string" && declaredExpectation(reading.value) === expectation) {
       entries.push({ ...base, action: "noop", evidence });
       continue;
     }

package/src/op/effect-step.test.ts

@@ -12,7 +12,8 @@
  *   differing receipts as findings and never writes.
  */
 import { describe, test, expect, vi } from "vitest";
-import { EffectReceipt, receiptExpectation, EXISTENCE_EXPECTATION } from "../effect-receipt";
+import { EffectReceipt, receiptExpectation, EXISTENCE_EXPECTATION, declaredExpectation, withStepOutputs } from "../effect-receipt";
+import { stepOutput } from "./step-output-ref";
 import { INTRINSIC_MARKER, type Intrinsic } from "../intrinsic";
 import { effect, phase } from "./builders";
 import {
@@ -324,3 +325,96 @@ describe("runOpLocally — effect steps", () => {
     ).rejects.toThrow(/parallel phase/);
   });
 });
+
+// ── Step outputs inside an effect (#3948) ───────────────────────────────────
+
+describe("runOpLocally — an effect's nested steps read step outputs (#3948)", () => {
+  function refOp(): OpConfig {
+    return {
+      name: "seed-op",
+      overview: "",
+      phases: [
+        phase("Pick", [{ kind: "activity", fn: "pick", id: "pick" }]),
+        phase("Seed", [effect(seeded, [step("runSeed", { file: stepOutput("pick", "file") })])]),
+      ],
+    };
+  }
+
+  test("the resolved value reaches the nested step, and the receipt holds its digest", async () => {
+    const { store, values } = memStore();
+    const received: unknown[] = [];
+    let file = "a.sql";
+    const activities = activityMap(store, {
+      pick: async () => ({ file }),
+      runSeed: async (args) => void received.push(args),
+    });
+    const first = await runOpLocally(refOp(), activities, PROFILES);
+    expect(first.status).toBe("ok");
+    expect(received).toEqual([{ file: "a.sql" }]);
+    const written = values.get("seeded")!;
+    expect(written).not.toBe(receiptExpectation(seeded));
+    expect(declaredExpectation(written)).toBe(receiptExpectation(seeded));
+
+    // The same value: the receipt matches and the effect is skipped.
+    const second = await runOpLocally(refOp(), activities, PROFILES);
+    expect(received).toHaveLength(1);
+    expect(second.records.find((r) => r.fn === "receiptRead")?.outcome).toEqual({ name: "EffectApplied", value: true });
+
+    // A changed value fires the effect again, though the declared inputs did not change.
+    file = "b.sql";
+    await runOpLocally(refOp(), activities, PROFILES);
+    expect(received).toEqual([{ file: "a.sql" }, { file: "b.sql" }]);
+    expect(values.get("seeded")).not.toBe(written);
+  });
+
+  test("a receipt written before the effect read outputs re-fires the effect once", async () => {
+    const { store, values } = memStore({ seeded: receiptExpectation(seeded) });
+    const ran = vi.fn();
+    const activities = activityMap(store, { pick: async () => ({ file: "a.sql" }), runSeed: async () => { ran(); } });
+    await runOpLocally(refOp(), activities, PROFILES);
+    expect(ran).toHaveBeenCalledTimes(1);
+    expect(declaredExpectation(values.get("seeded")!)).toBe(receiptExpectation(seeded));
+  });
+
+  test("an existence receipt takes no outputs: it says the effect ran once", async () => {
+    const booted = EffectReceipt("booted", { effect: "bootstrap", flavor: "existence" });
+    const config: OpConfig = {
+      name: "boot-op",
+      overview: "",
+      phases: [
+        phase("Pick", [{ kind: "activity", fn: "pick", id: "pick" }]),
+        phase("Boot", [effect(booted, [step("boot", { file: stepOutput("pick", "file") })])]),
+      ],
+    };
+    const { store, values } = memStore();
+    const activities = activityMap(store, { pick: async () => ({ file: "a.sql" }), boot: async () => {} });
+    await runOpLocally(config, activities, PROFILES);
+    expect(values.get("booted")).toBe(EXISTENCE_EXPECTATION);
+  });
+
+  test("an effect in onFailure whose source step did not complete is skipped whole (A6)", async () => {
+    const config: OpConfig = {
+      name: "seed-op",
+      overview: "",
+      phases: [phase("Pick", [{ kind: "activity", fn: "pick", id: "pick" }])],
+      onFailure: [phase("Undo", [effect(seeded, [step("unseed", { file: stepOutput("pick", "file") })])])],
+    };
+    const { store, writes } = memStore();
+    const ran = vi.fn();
+    const activities = activityMap(store, { pick: async () => { throw new Error("boom"); }, unseed: async () => { ran(); } });
+    const failure = (await runOpLocally(config, activities, PROFILES).catch((e) => e)) as OpRunFailure;
+    expect(failure).toBeInstanceOf(OpRunFailure);
+    expect(ran).not.toHaveBeenCalled();
+    expect(writes).toEqual([]);
+    const skipped = failure.result.records.find((r) => r.fn === "effect:seeded");
+    expect(skipped?.status).toBe("skipped");
+    expect(skipped?.refusal).toMatch(/step "pick" did not complete/);
+  });
+
+  test("receiptStaleness compares the declared part of a value written with outputs", async () => {
+    const expected = receiptExpectation(seeded);
+    const { store } = memStore({ seeded: withStepOutputs(expected, "sha256:abc") });
+    const { receiptStaleness } = receiptActivities(store);
+    expect(await receiptStaleness({ receipts: [receiptCheckInput(seeded)] })).toEqual({ stale: false, findings: [] });
+  });
+});

package/src/op/local-executor.test.ts

@@ -459,6 +459,71 @@ describe("runOpLocally — gate as fact (#2119)", () => {
   });
 });
 
+describe("runOpLocally — step-output references in onFailure (#3948)", () => {
+  const failing: ActivityFn = async () => { throw new Error("boom"); };
+
+  test("a compensation step receives the value a main-phase step returned", async () => {
+    const received: unknown[] = [];
+    const activities = new Map<string, ActivityFn>([
+      ["deploy", async () => ({ previous: "v1" })],
+      ["migrate", failing],
+      ["restore", async (args) => { received.push(args); }],
+    ]);
+    const config = op({
+      phases: [
+        { name: "Deploy", steps: [{ kind: "activity", fn: "deploy", id: "deploy" }] },
+        { name: "Migrate", steps: [{ kind: "activity", fn: "migrate" }] },
+      ],
+      onFailure: [{ name: "Rollback", steps: [{ kind: "activity", fn: "restore", args: { revision: stepOutput("deploy", "previous") } }] }],
+    });
+    const err = await runOpLocally(config, activities, PROFILES).catch((e) => e);
+    expect(err).toBeInstanceOf(OpRunFailure);
+    expect(received).toEqual([{ revision: "v1" }]);
+  });
+
+  test("a compensation step whose source step did not complete is skipped, and the record says why (A6)", async () => {
+    const ran: string[] = [];
+    const activities = new Map<string, ActivityFn>([
+      ["deploy", failing],
+      ["restore", async () => void ran.push("restore")],
+      ["notify", async () => void ran.push("notify")],
+    ]);
+    const config = op({
+      phases: [{ name: "Deploy", steps: [{ kind: "activity", fn: "deploy", id: "deploy" }] }],
+      onFailure: [{ name: "Rollback", steps: [
+        { kind: "activity", fn: "restore", args: { revision: stepOutput("deploy", "previous") } },
+        { kind: "activity", fn: "notify" },
+      ] }],
+    });
+    const err = await runOpLocally(config, activities, PROFILES).catch((e) => e);
+    expect(err).toBeInstanceOf(OpRunFailure);
+    // The skip is not a failure of compensation: the next step still runs.
+    expect(ran).toEqual(["notify"]);
+    const restore = err.result.records.find((r: { fn: string }) => r.fn === "restore");
+    expect(restore.status).toBe("skipped");
+    expect(restore.refusal).toMatch(/step "deploy" did not complete/);
+  });
+
+  test("the skip applies in a parallel compensation phase too", async () => {
+    const ran: string[] = [];
+    const activities = new Map<string, ActivityFn>([
+      ["deploy", failing],
+      ["restore", async () => void ran.push("restore")],
+      ["notify", async () => void ran.push("notify")],
+    ]);
+    const config = op({
+      phases: [{ name: "Deploy", steps: [{ kind: "activity", fn: "deploy", id: "deploy" }] }],
+      onFailure: [{ name: "Rollback", parallel: true, steps: [
+        { kind: "activity", fn: "restore", args: { revision: stepOutput("deploy") } },
+        { kind: "activity", fn: "notify" },
+      ] }],
+    });
+    const err = await runOpLocally(config, activities, PROFILES).catch((e) => e);
+    expect(ran).toEqual(["notify"]);
+    expect(err.result.records.find((r: { fn: string }) => r.fn === "restore").status).toBe("skipped");
+  });
+});
+
 describe("runOpLocally — step-output references (#1290)", () => {
   test("a later step receives the producer's resolved value, not the placeholder", async () => {
     const received: unknown[] = [];

package/src/op/local-executor.ts

@@ -23,7 +23,9 @@ import { outcomeAttributesOf } from "./types";
 import type { OpConfig, PhaseDefinition, ActivityStep, GateStep, EffectStep, StepDefinition } from "./types";
 import { resolveActivity, type ActivityFn, type ActivityProfile } from "./activity-registry";
 import type { ReceiptReadResult } from "./receipt-store";
-import { isStepOutputRef } from "./step-output-ref";
+import { collectStepOutputRefs, isStepOutputRef } from "./step-output-ref";
+import { canonicalJson } from "../effect-receipt";
+import { contentDigest } from "../content-digest";
 import { parseDuration } from "./duration";
 import { stepLabel, withRunConsole, withStepConsole } from "./step-console";
 import { stepTimeoutProblem } from "./activity-profiles";
@@ -278,6 +280,48 @@ function resolveStepOutputRefs(value: unknown, resultsById: ReadonlyMap<string,
   return value;
 }
 
+/** The activity steps a step runs: itself, or an effect's nested ones. */
+function activitiesOf(step: ActivityStep | EffectStep): ActivityStep[] {
+  return isEffect(step) ? step.steps.filter(isActivity) : [step];
+}
+
+/**
+ * The first step a compensation step references that has not completed in
+ * this run (#3948 decision A6), or `undefined` when every one did. A failure
+ * can stop the run before the step that a rollback reads, and calling the
+ * rollback with `undefined` in place of that value would undo the wrong
+ * thing, or nothing, while reporting `ok`.
+ */
+function unfinishedSource(step: ActivityStep | EffectStep, resultsById: ReadonlyMap<string, unknown>): string | undefined {
+  for (const activity of activitiesOf(step)) {
+    const missing = collectStepOutputRefs(activity.args).find((ref) => !resultsById.has(ref.step));
+    if (missing) return missing.step;
+  }
+  return undefined;
+}
+
+/** The skipped record of a compensation step whose source did not complete. */
+function unfinishedSourceRecord(step: ActivityStep | EffectStep, phaseName: string, source: string): StepRecord {
+  const record = isEffect(step) ? skippedRecord(phaseName, `effect:${step.receipt.name}`) : skippedRecord(phaseName, step.fn, step.args);
+  return { ...record, refusal: `step "${source}" did not complete in this run, so this compensation step, which reads its output, was skipped` };
+}
+
+/**
+ * The digest of the step outputs an effect's nested steps read (#3948), or
+ * `undefined` when they read none. The receipt store folds it into the
+ * expectation, so a changed value re-fires the effect instead of the receipt
+ * matching on the declared inputs alone. An existence receipt says only that
+ * the effect ran once, so it takes none.
+ */
+function effectOutputsDigest(step: EffectStep, resultsById: ReadonlyMap<string, unknown>): string | undefined {
+  if (step.receipt.flavor === "existence") return undefined;
+  const read = activitiesOf(step).flatMap((a) =>
+    collectStepOutputRefs(a.args).map((ref) => ({ step: ref.step, path: ref.path ?? "", value: resolveStepOutputRefs(ref, resultsById) })),
+  );
+  if (read.length === 0) return undefined;
+  return contentDigest(canonicalJson(read));
+}
+
 /**
  * Find the first `policyGate` step anywhere in the Op (phases + `onFailure`,
  * including steps nested inside effect steps), if any.
@@ -464,13 +508,14 @@ async function runStep(
 /** The step data the executor synthesizes to read a receipt through the store
  * activities (`receiptRead`/`receiptWrite` — provided by the receipt row's
  * lexicon, #1835, or a mock store in tests via `receiptActivities`). */
-function receiptReadStep(step: EffectStep): ActivityStep {
+function receiptReadStep(step: EffectStep, outputs?: string): ActivityStep {
   return {
     kind: "activity",
     fn: "receiptRead",
     args: {
       receipt: step.receipt,
       ...(step.expectation !== undefined ? { expectation: step.expectation } : {}),
+      ...(outputs !== undefined ? { outputs } : {}),
     },
     profile: "fastIdempotent",
     outcomeAttribute: { name: "EffectApplied", from: "applied" },
@@ -496,6 +541,8 @@ interface GateContext {
   passed?: PassedGate[];
   /** The run's hold on its work item's lease (#2748). Absent in compensation phases, which run whatever the lease did. */
   work?: RunWorkLease;
+  /** Set in `onFailure` phases (#3948): a step whose referenced step did not complete is skipped. */
+  compensating?: boolean;
   /** How a gate that names a decision point asks it (#3170). */
   points?: GatePointAsker;
   /** The environment the run was started for, a point gate's `gate.env` input. */
@@ -790,7 +837,15 @@ async function runEffectStep(
 }> {
   const records: StepRecord[] = [];
 
-  const read = await runStep(receiptReadStep(step), phaseName, activities, profiles, resultsById, signal);
+  let outputs: string | undefined;
+  try {
+    outputs = effectOutputsDigest(step, resultsById);
+  } catch (err) {
+    // A resolved value JSON cannot hold (canonicalJson refuses it) would be a wrong expectation.
+    pushRecord(records, gates, { phase: phaseName, fn: `effect:${step.receipt.name}`, args: {}, status: "fail", durationMs: 0, error: errMessage(err) });
+    return { records, failed: true };
+  }
+  const read = await runStep(receiptReadStep(step, outputs), phaseName, activities, profiles, resultsById, signal);
   pushRecord(records, gates, read.record);
   if (read.record.status === "fail") return { records, failed: true };
 
@@ -950,7 +1005,10 @@ async function runPhase(
       }
     }
     const steps = phase.steps.filter(isActivity);
-    const settled = await Promise.all(steps.map((s) => runStep(s, phase.name, activities, profiles, resultsById, signal)));
+    const settled = await Promise.all(steps.map((s) => {
+      const source = gates.compensating ? unfinishedSource(s, resultsById) : undefined;
+      return source ? { record: unfinishedSourceRecord(s, phase.name, source) } as RanStep : runStep(s, phase.name, activities, profiles, resultsById, signal);
+    }));
     const ran = settled.map((r) => r.record);
     for (const r of ran) gates.onRecord?.(r);
     const records = gateRecords.concat(ran);
@@ -1011,6 +1069,11 @@ async function runPhase(
       }
       continue;
     }
+    const source = gates.compensating ? unfinishedSource(step, resultsById) : undefined;
+    if (source) {
+      pushRecord(records, gates, unfinishedSourceRecord(step, phase.name, source));
+      continue;
+    }
     if (isEffect(step)) {
       const { records: effRecords, failed, pending, pushed, pushWarning, point } = await runEffectStep(
         step, phase.name, activities, profiles, resultsById, gates, signal,
@@ -1444,7 +1507,7 @@ async function runOpInTurn(
     // Compensation: run onFailure phases in reverse order (best-effort). Skipped
     // on abort (Ctrl-C) — the user asked to stop, so don't start new work.
     // It runs whatever the work lease did, so it takes no work boundary.
-    const compensation: GateContext = { ...gates, work: undefined };
+    const compensation: GateContext = { ...gates, work: undefined, compensating: true };
     if (!signal?.aborted) {
       for (const phase of [...(config.onFailure ?? [])].reverse()) {
         try {

package/src/op/receipt-store.ts

@@ -34,6 +34,8 @@ import {
   referenceInputPaths,
   type EffectReceiptDeclaration,
   type EffectReceiptFlavor,
+  declaredExpectation,
+  withStepOutputs,
 } from "../effect-receipt";
 
 /**
@@ -101,7 +103,14 @@ export function receiptCheckInput(receipt: EffectReceiptDeclaration): ReceiptChe
 // ── Activity contracts ────────────────────────────────────────────────────────
 
 /** Args of the `receiptRead` activity, as the effect step's codegen emits them. */
-export interface ReceiptReadArgs extends ReceiptCheckInput {}
+export interface ReceiptReadArgs extends ReceiptCheckInput {
+  /**
+   * The digest of the step outputs the effect's nested steps read (#3948),
+   * when they read any. Folded into the expectation by {@link withStepOutputs}.
+   */
+  outputs?: string;
+}
+
 
 /** Result of the `receiptRead` activity. `current` is `null` (not `undefined`)
  * for an absent receipt so the value survives JSON transport. */
@@ -183,7 +192,8 @@ export function receiptActivities(store: ReceiptStore, opts?: ReceiptActivityOpt
 
   return {
     async receiptRead(args: ReceiptReadArgs): Promise<ReceiptReadResult> {
-      const expectation = await expectationOf(args);
+      const declared = await expectationOf(args);
+      const expectation = args.outputs !== undefined ? withStepOutputs(declared, args.outputs) : declared;
       const current = await store.read(args.receipt);
       return { current: current ?? null, expectation, applied: current === expectation };
     },
@@ -201,7 +211,7 @@ export function receiptActivities(store: ReceiptStore, opts?: ReceiptActivityOpt
         const current = await store.read(input.receipt);
         if (current === undefined) {
           findings.push({ receipt: input.receipt.name, effect: input.receipt.effect, kind: "absent", expected });
-        } else if (current !== expected) {
+        } else if (declaredExpectation(current) !== expected) {
           findings.push({ receipt: input.receipt.name, effect: input.receipt.effect, kind: "differs", expected, current });
         }
       }

package/src/op/step-output-ref.test.ts

@@ -10,7 +10,7 @@ import { z } from "zod";
 import { activity, phase, effect } from "./builders";
 import type { OpConfig } from "./types";
 import { activityContract, type ActivityContract } from "./activity-contract";
-import { stepOutput, isStepOutputRef, collectStepOutputRefs, validateStepOutputRefs } from "./step-output-ref";
+import { stepOutput, isStepOutputRef, collectStepOutputRefs, validateStepOutputRefs, validateStepOutputRefScope } from "./step-output-ref";
 import { EffectReceipt } from "../effect-receipt";
 
 const lifecycleDiffContract = activityContract(
@@ -248,39 +248,83 @@ describe("validateStepOutputRefs() — structural coverage", () => {
     expect(issues.some((i) => i.message.includes("declares no return schema"))).toBe(true);
   });
 
-  it("flags a reference authored inside onFailure", () => {
+  it("reports every issue across multiple refs, not just the first", () => {
+    const apply1 = activity("applyStacks", { stacks: stepOutput("nope1", "x") });
+    const apply2 = activity("applyStacks", { stacks: stepOutput("nope2", "x") });
+    const config = opWith({ phases: [phase("P", [apply1, apply2])] });
+    const issues = validateStepOutputRefs(config, new Map([["applyStacks", applyStacksContract]]));
+    expect(issues.some((i) => i.message.includes("nope1"))).toBe(true);
+    expect(issues.some((i) => i.message.includes("nope2"))).toBe(true);
+  });
+});
+
+// ── onFailure and effect steps (#3948) ───────────────────────────────────────
+
+describe("validateStepOutputRefs() — onFailure and effect steps (#3948)", () => {
+  const seeded = EffectReceipt("seeded", { effect: "db-seed", flavor: "hash", inputs: { file: "seed.sql", version: 3 } });
+  const contracts = new Map<string, ActivityContract>([
+    ["lifecycleDiff", lifecycleDiffContract],
+    ["applyStacks", applyStacksContract],
+  ]);
+
+  it("an onFailure step may reference any main-phase step", () => {
     const diff = activity("lifecycleDiff", { env: "prod" }, { id: "diff" });
+    const apply = activity("applyStacks", { stacks: ["a"] });
     const rollback = activity("applyStacks", { stacks: stepOutput("diff", "driftedStacks") });
+    const config = opWith({ phases: [phase("Diff", [diff]), phase("Apply", [apply])], onFailure: [phase("Rollback", [rollback])] });
+    expect(validateStepOutputRefs(config, contracts)).toEqual([]);
+  });
+
+  it("an onFailure step's reference is still checked against the producer's contract", () => {
+    const diff = activity("lifecycleDiff", { env: "prod" }, { id: "diff" });
+    const rollback = activity("applyStacks", { stacks: stepOutput("diff", "nope") });
     const config = opWith({ phases: [phase("P", [diff])], onFailure: [phase("Rollback", [rollback])] });
-    const contracts = new Map<string, ActivityContract>([
-      ["lifecycleDiff", lifecycleDiffContract],
-      ["applyStacks", applyStacksContract],
-    ]);
     const issues = validateStepOutputRefs(config, contracts);
-    expect(issues.some((i) => i.message.includes("onFailure compensation"))).toBe(true);
+    expect(issues).toHaveLength(1);
+    expect(issues[0].phase).toBe("Rollback");
+    expect(issues[0].message).toMatch(/path "nope", which does not exist/);
+  });
+
+  it("an onFailure step cannot reference another onFailure step", () => {
+    const diff = activity("lifecycleDiff", { env: "prod" }, { id: "undoDiff" });
+    const rollback = activity("applyStacks", { stacks: stepOutput("undoDiff", "driftedStacks") });
+    const config = opWith({ phases: [phase("P", [activity("applyStacks", { stacks: [] })])], onFailure: [phase("Rollback", [diff, rollback])] });
+    expect(validateStepOutputRefScope(config)[0].message).toMatch(/unknown step id "undoDiff"/);
   });
 
-  it("flags a reference authored inside an effect step's nested steps", () => {
-    const receipt = EffectReceipt("seeded", { effect: "db-seed", flavor: "hash", inputs: { file: "seed.sql", version: 3 } });
+  it("a step inside an effect may reference a step that runs before the effect", () => {
     const diff = activity("lifecycleDiff", { env: "prod" }, { id: "diff" });
     const nested = activity("applyStacks", { stacks: stepOutput("diff", "driftedStacks") });
-    const effectStep = effect(receipt, [nested]);
-    const config = opWith({ phases: [phase("P", [diff, effectStep])] });
-    const contracts = new Map<string, ActivityContract>([
-      ["lifecycleDiff", lifecycleDiffContract],
-      ["applyStacks", applyStacksContract],
-    ]);
-    const issues = validateStepOutputRefs(config, contracts);
-    expect(issues.some((i) => i.message.includes("nested inside an effect step"))).toBe(true);
+    const config = opWith({ phases: [phase("P", [diff, effect(seeded, [nested])])] });
+    expect(validateStepOutputRefs(config, contracts)).toEqual([]);
   });
 
-  it("reports every issue across multiple refs, not just the first", () => {
-    const apply1 = activity("applyStacks", { stacks: stepOutput("nope1", "x") });
-    const apply2 = activity("applyStacks", { stacks: stepOutput("nope2", "x") });
-    const config = opWith({ phases: [phase("P", [apply1, apply2])] });
-    const issues = validateStepOutputRefs(config, new Map([["applyStacks", applyStacksContract]]));
-    expect(issues.some((i) => i.message.includes("nope1"))).toBe(true);
-    expect(issues.some((i) => i.message.includes("nope2"))).toBe(true);
+  it("a step inside an effect in onFailure may reference a main-phase step", () => {
+    const diff = activity("lifecycleDiff", { env: "prod" }, { id: "diff" });
+    const nested = activity("applyStacks", { stacks: stepOutput("diff", "driftedStacks") });
+    const config = opWith({ phases: [phase("P", [diff])], onFailure: [phase("Undo", [effect(seeded, [nested])])] });
+    expect(validateStepOutputRefs(config, contracts)).toEqual([]);
+  });
+
+  it("a step inside an effect cannot reference a step after the effect", () => {
+    const nested = activity("applyStacks", { stacks: stepOutput("diff", "driftedStacks") });
+    const diff = activity("lifecycleDiff", { env: "prod" }, { id: "diff" });
+    const config = opWith({ phases: [phase("P", [effect(seeded, [nested]), diff])] });
+    expect(validateStepOutputRefScope(config)[0].message).toMatch(/step "diff" does not run before this step/);
+  });
+
+  it("nothing can reference a step nested inside an effect (decision A7)", () => {
+    const inner = activity("lifecycleDiff", { env: "prod" }, { id: "inner" });
+    const sibling = activity("applyStacks", { stacks: stepOutput("inner", "driftedStacks") });
+    const later = activity("applyStacks", { stacks: stepOutput("inner", "driftedStacks") });
+    const rollback = activity("applyStacks", { stacks: stepOutput("inner", "driftedStacks") });
+    const config = opWith({
+      phases: [phase("P", [effect(seeded, [inner, sibling]), later])],
+      onFailure: [phase("Rollback", [rollback])],
+    });
+    const issues = validateStepOutputRefScope(config);
+    expect(issues).toHaveLength(3);
+    for (const issue of issues) expect(issue.message).toMatch(/"inner", which is nested inside an effect step/);
   });
 });