@intentius/chant 0.45.0 → 0.49.0

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

@@ -0,0 +1,311 @@
+/**
+ * effect() step + receipt store seam + local-executor semantics (#1834, epic
+ * #1703). The contract under test:
+ *
+ * - the builder takes the typed EffectReceipt declaration only (no string
+ *   form — enforced at the type level and at runtime);
+ * - read-compare-run-write: a matching receipt skips the nested steps; a
+ *   mismatch runs them and writes the receipt ONLY on their success, last;
+ * - a nested-step failure leaves the receipt untouched (stale), so a rerun
+ *   re-proposes the effect;
+ * - `receiptStaleness` (WatchOp's phase) is read-only: it reports absent and
+ *   differing receipts as findings and never writes.
+ */
+import { describe, test, expect } from "vitest";
+import { EffectReceipt, receiptExpectation, EXISTENCE_EXPECTATION } from "../effect-receipt";
+import { INTRINSIC_MARKER, type Intrinsic } from "../intrinsic";
+import { effect, phase } from "./builders";
+import {
+  receiptActivities,
+  receiptCheckInput,
+  type ReceiptStore,
+  type EffectReceiptRef,
+} from "./receipt-store";
+import type { ActivityFn, ActivityProfile } from "./activity-registry";
+import type { OpConfig, ActivityStep } from "./types";
+import { runOpLocally, findGate, LocalGateUnsupportedError, OpRunFailure } from "./local-executor";
+
+function fakeIntrinsic(json: unknown): Intrinsic {
+  return {
+    [INTRINSIC_MARKER]: true,
+    toJSON: () => json,
+  };
+}
+
+const seeded = EffectReceipt("seeded", {
+  effect: "db-seed",
+  flavor: "hash",
+  inputs: { file: "seed.sql", version: 3 },
+});
+
+const step = (fn: string, args?: Record<string, unknown>): ActivityStep => ({
+  kind: "activity",
+  fn,
+  ...(args ? { args } : {}),
+});
+
+// ── Builder ───────────────────────────────────────────────────────────────────
+
+describe("effect() builder", () => {
+  test("wraps nested steps with the receipt's identity data and stamps a static expectation", () => {
+    const s = effect(seeded, [step("shellCmd", { cmd: "npm run db:seed" })]);
+    expect(s.kind).toBe("effect");
+    expect(s.receipt).toEqual({
+      name: "seeded",
+      effect: "db-seed",
+      flavor: "hash",
+      inputs: { file: "seed.sql", version: 3 },
+    });
+    expect(s.expectation).toBe(receiptExpectation(seeded));
+    expect(s.steps.map((n) => (n.kind === "activity" ? n.fn : n.signalName))).toEqual(["shellCmd"]);
+  });
+
+  test("existence receipts always get the constant expectation, reference inputs or not", () => {
+    const r = EffectReceipt("booted", {
+      effect: "bootstrap",
+      flavor: "existence",
+      inputs: { endpoint: fakeIntrinsic({ __attrRef: { entity: "Db", attribute: "endpoint" } }) },
+    });
+    expect(effect(r, []).expectation).toBe(EXISTENCE_EXPECTATION);
+  });
+
+  test("a hash receipt with reference inputs carries no synthesis-time expectation (resolves at run, #1703 decision 5)", () => {
+    const r = EffectReceipt("migrated", {
+      effect: "db-migrate",
+      flavor: "hash",
+      inputs: { endpoint: fakeIntrinsic({ __attrRef: { entity: "Db", attribute: "endpoint" } }) },
+    });
+    const s = effect(r, []);
+    expect(s.expectation).toBeUndefined();
+    expect("expectation" in s).toBe(false);
+  });
+
+  test("preserves authored order and nested gates", () => {
+    const s = effect(seeded, [
+      { kind: "gate", signalName: "approve-seed" },
+      step("shellCmd", { cmd: "seed" }),
+    ]);
+    expect(s.steps.map((n) => n.kind)).toEqual(["gate", "activity"]);
+  });
+
+  test("refuses anything that is not the typed receipt declaration", () => {
+    expect(() => effect({ name: "seeded" } as never, [])).toThrow(/no string form/);
+    // Type level: a string receipt name must not compile.
+    // @ts-expect-error — receipt is the EffectReceipt declaration, never a string
+    expect(() => effect("seeded", [])).toThrow(/no string form/);
+  });
+
+  test("effect steps do not nest", () => {
+    const inner = effect(seeded, []);
+    expect(() => effect(seeded, [inner as never])).toThrow(/do not nest/);
+  });
+});
+
+// ── Receipt store seam ────────────────────────────────────────────────────────
+
+function memStore(initial?: Record<string, string>): {
+  store: ReceiptStore;
+  values: Map<string, string>;
+  writes: Array<{ name: string; expectation: string }>;
+} {
+  const values = new Map(Object.entries(initial ?? {}));
+  const writes: Array<{ name: string; expectation: string }> = [];
+  const store: ReceiptStore = {
+    async read(r: EffectReceiptRef) {
+      return values.get(r.name);
+    },
+    async write(r: EffectReceiptRef, expectation: string) {
+      writes.push({ name: r.name, expectation });
+      values.set(r.name, expectation);
+    },
+  };
+  return { store, values, writes };
+}
+
+describe("receiptActivities (the injectable store seam)", () => {
+  const input = receiptCheckInput(seeded);
+  const expected = receiptExpectation(seeded);
+
+  test("receiptRead: absent receipt reads as current null, applied false", async () => {
+    const { store } = memStore();
+    const { receiptRead } = receiptActivities(store);
+    expect(await receiptRead(input)).toEqual({ current: null, expectation: expected, applied: false });
+  });
+
+  test("receiptRead: matching receipt reads as applied true", async () => {
+    const { store } = memStore({ seeded: expected });
+    const { receiptRead } = receiptActivities(store);
+    expect(await receiptRead(input)).toEqual({ current: expected, expectation: expected, applied: true });
+  });
+
+  test("receiptRead: refuses to invent an expectation for a reference-carrying hash receipt without a resolver", async () => {
+    const r = EffectReceipt("migrated", {
+      effect: "db-migrate",
+      flavor: "hash",
+      inputs: { endpoint: fakeIntrinsic("placeholder") },
+    });
+    const { store } = memStore();
+    const { receiptRead } = receiptActivities(store);
+    await expect(receiptRead(receiptCheckInput(r))).rejects.toThrow(/resolveExpectation/);
+  });
+
+  test("receiptWrite stores the expectation", async () => {
+    const { store, writes, values } = memStore();
+    const { receiptWrite } = receiptActivities(store);
+    await receiptWrite({ receipt: input.receipt, expectation: expected });
+    expect(writes).toEqual([{ name: "seeded", expectation: expected }]);
+    expect(values.get("seeded")).toBe(expected);
+  });
+
+  test("receiptStaleness reports absent and differing receipts as findings, and never writes", async () => {
+    const fresh = EffectReceipt("fresh", { effect: "e1", flavor: "hash", inputs: { v: 1 } });
+    const differs = EffectReceipt("differs", { effect: "e2", flavor: "hash", inputs: { v: 2 } });
+    const absent = EffectReceipt("absent", { effect: "e3", flavor: "existence" });
+    const { store, writes } = memStore({
+      fresh: receiptExpectation(fresh),
+      differs: "sha256:stale",
+    });
+    const { receiptStaleness } = receiptActivities(store);
+    const result = await receiptStaleness({
+      receipts: [fresh, differs, absent].map(receiptCheckInput),
+    });
+    expect(result.stale).toBe(true);
+    expect(result.findings).toEqual([
+      { receipt: "differs", effect: "e2", kind: "differs", expected: receiptExpectation(differs), current: "sha256:stale" },
+      { receipt: "absent", effect: "e3", kind: "absent", expected: EXISTENCE_EXPECTATION },
+    ]);
+    expect(writes).toEqual([]);
+  });
+
+  test("receiptStaleness with everything fresh reports stale false", async () => {
+    const { store } = memStore({ seeded: expected });
+    const { receiptStaleness } = receiptActivities(store);
+    expect(await receiptStaleness({ receipts: [input] })).toEqual({ stale: false, findings: [] });
+  });
+});
+
+// ── Local executor: read-compare-run-write ────────────────────────────────────
+
+const PROFILES: Record<string, ActivityProfile> = {
+  fastIdempotent: { startToCloseTimeout: "5m", retry: { maximumAttempts: 1 } },
+};
+
+function activityMap(
+  store: ReceiptStore,
+  extra: Record<string, ActivityFn>,
+): Map<string, ActivityFn> {
+  const map = new Map<string, ActivityFn>();
+  for (const [name, fn] of Object.entries(receiptActivities(store))) {
+    map.set(name, fn as unknown as ActivityFn);
+  }
+  for (const [name, fn] of Object.entries(extra)) map.set(name, fn);
+  return map;
+}
+
+function seedOp(): OpConfig {
+  return {
+    name: "seed-op",
+    overview: "",
+    phases: [phase("Seed", [effect(seeded, [step("runSeed")])])],
+  };
+}
+
+describe("runOpLocally — effect steps", () => {
+  test("matching receipt skips the nested steps and writes nothing", async () => {
+    const { store, writes } = memStore({ seeded: receiptExpectation(seeded) });
+    const ran: string[] = [];
+    const activities = activityMap(store, { runSeed: async () => void ran.push("runSeed") });
+    const result = await runOpLocally(seedOp(), activities, PROFILES);
+    expect(result.ok).toBe(true);
+    expect(ran).toEqual([]);
+    expect(writes).toEqual([]);
+    // The read records the effect as already applied; the nested step is skipped.
+    expect(result.records.map((r) => [r.fn, r.status])).toEqual([
+      ["receiptRead", "ok"],
+      ["runSeed", "skipped"],
+    ]);
+    expect(result.records[0].outcome).toEqual({ name: "EffectApplied", value: true });
+  });
+
+  test("mismatch runs the nested steps, then writes the receipt once, last", async () => {
+    const { store, writes } = memStore();
+    const order: string[] = [];
+    const activities = activityMap(
+      { read: store.read, write: async (r, e) => { order.push("write"); await store.write(r, e); } },
+      { runSeed: async () => void order.push("runSeed") },
+    );
+    const result = await runOpLocally(seedOp(), activities, PROFILES);
+    expect(result.ok).toBe(true);
+    expect(order).toEqual(["runSeed", "write"]);
+    expect(writes).toEqual([{ name: "seeded", expectation: receiptExpectation(seeded) }]);
+    expect(result.records.map((r) => [r.fn, r.status])).toEqual([
+      ["receiptRead", "ok"],
+      ["runSeed", "ok"],
+      ["receiptWrite", "ok"],
+    ]);
+  });
+
+  test("a nested failure leaves the receipt untouched, and a rerun re-proposes the effect", async () => {
+    const { store, writes, values } = memStore();
+    let healthy = false;
+    const activities = activityMap(store, {
+      runSeed: async () => {
+        if (!healthy) throw new Error("seed blew up");
+      },
+    });
+
+    await expect(runOpLocally(seedOp(), activities, PROFILES)).rejects.toThrow(OpRunFailure);
+    expect(writes).toEqual([]);
+    expect(values.has("seeded")).toBe(false);
+
+    // The receipt is stale, so the next run runs the effect again — and only
+    // then writes.
+    healthy = true;
+    const rerun = await runOpLocally(seedOp(), activities, PROFILES);
+    expect(rerun.ok).toBe(true);
+    expect(writes).toEqual([{ name: "seeded", expectation: receiptExpectation(seeded) }]);
+  });
+
+  test("the failed run records the write as skipped, not run", async () => {
+    const { store } = memStore();
+    const activities = activityMap(store, {
+      runSeed: async () => {
+        throw new Error("boom");
+      },
+    });
+    const failure = await runOpLocally(seedOp(), activities, PROFILES).catch((e: OpRunFailure) => e);
+    expect(failure).toBeInstanceOf(OpRunFailure);
+    expect((failure as OpRunFailure).result.records.map((r) => [r.fn, r.status])).toEqual([
+      ["receiptRead", "ok"],
+      ["runSeed", "fail"],
+      ["receiptWrite", "skipped"],
+    ]);
+  });
+
+  test("a gate nested in an effect step is rejected up front, like any other gate", () => {
+    const config: OpConfig = {
+      name: "gated",
+      overview: "",
+      phases: [
+        phase("Seed", [effect(seeded, [{ kind: "gate", signalName: "approve-seed" }, step("runSeed")])]),
+      ],
+    };
+    expect(findGate(config)?.signalName).toBe("approve-seed");
+    const { store } = memStore();
+    return expect(
+      runOpLocally(config, activityMap(store, { runSeed: async () => {} }), PROFILES),
+    ).rejects.toThrow(LocalGateUnsupportedError);
+  });
+
+  test("an effect step in a parallel phase is refused — read-compare-run-write is ordered", async () => {
+    const config: OpConfig = {
+      name: "par",
+      overview: "",
+      phases: [phase("P", [effect(seeded, [step("runSeed")])], { parallel: true })],
+    };
+    const { store } = memStore();
+    await expect(
+      runOpLocally(config, activityMap(store, { runSeed: async () => {} }), PROFILES),
+    ).rejects.toThrow(/parallel phase/);
+  });
+});

package/src/op/index.ts

@@ -1,5 +1,6 @@
-export { Op, phase, activity, gate, build, kubectlApply, helmInstall, waitForStack, waitForReady,
-         gitlabPipeline, lifecycleSnapshot, shell, teardown, k3dUp, k3dDown, flociUp, flociDown,
+export { Op, phase, activity, gate, effect, build, kubectlApply, helmInstall, helmInstallPinned, waitForStack, waitForReady,
+         gitlabPipeline, lifecycleSnapshot, shell, ensureSecret, teardown, envTeardown, k3dUp, k3dDown,
+         k3sInstall, k3sUninstall, flociUp, flociDown,
          flociAzUp, flociAzDown, flociGcpUp, flociGcpDown, httpCheck,
          azGroupEnsure, azGroupDelete, azApply, azDelete, awsApply, awsDelete, gcpApply, gcpDelete, policyGate,
          spriteCreate, spriteExec, spriteCheckpoint, spriteRestore, listCheckpoints, spriteDestroy,
@@ -13,7 +14,13 @@ export { emulatorLifecycle, emulatorsOf, endpointEnvVars } from "./emulator-life
 export type { EmulatorSpec, EmulatorCapability, EmulatorDeclaration, EmulatorUpArgs, EmulatorLifecycle } from "./emulator-lifecycle";
 export { checkFreshness, compare, formatResult, latestRelease, parseVersion, unpinned } from "./emulator-freshness";
 export type { FreshnessResult } from "./emulator-freshness";
-export type { OpConfig, PhaseDefinition, StepDefinition, ActivityStep, GateStep } from "./types";
+export type { OpConfig, PhaseDefinition, StepDefinition, ActivityStep, GateStep, EffectStep } from "./types";
+export { receiptActivities, receiptCheckInput } from "./receipt-store";
+export type {
+  ReceiptStore, EffectReceiptRef, ReceiptCheckInput, ReceiptActivities, ReceiptActivityOptions,
+  ReceiptReadArgs, ReceiptReadResult, ReceiptWriteArgs,
+  ReceiptStalenessArgs, ReceiptStalenessResult, ReceiptStaleFinding,
+} from "./receipt-store";
 export { discoverOps } from "./discover";
 export type { DiscoveredOp, OpDiscoveryResult } from "./discover";
 export { loadActivities, loadProfiles, resolveActivity } from "./activity-registry";

package/src/op/local-executor.ts

@@ -11,8 +11,9 @@
  * so core never statically depends on `@intentius/chant-lexicon-temporal`.
  */
 
-import type { OpConfig, PhaseDefinition, ActivityStep, GateStep, StepDefinition } 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";
 
 // ── Records ─────────────────────────────────────────────────────────────────
 
@@ -69,6 +70,7 @@ const FALLBACK_TIMEOUT_MS = 5 * 60_000;
 
 const isActivity = (s: StepDefinition): s is ActivityStep => s.kind === "activity";
 const isGate = (s: StepDefinition): s is GateStep => s.kind === "gate";
+const isEffect = (s: StepDefinition): s is EffectStep => s.kind === "effect";
 
 /** Parse a Temporal duration string ("5m", "30s", "1h30m", "100ms") to ms. */
 export function parseDuration(s: string): number {
@@ -92,12 +94,18 @@ function resolvePath(value: unknown, path?: string): unknown {
   );
 }
 
-/** Find the first gate step anywhere in the Op (phases + onFailure), if any. */
+/** Find the first gate step anywhere in the Op (phases + onFailure, including
+ * gates nested inside effect steps), if any. */
 export function findGate(config: OpConfig): GateStep | undefined {
   const all = [...config.phases, ...(config.onFailure ?? [])];
   for (const phase of all) {
-    const gate = phase.steps.find(isGate);
-    if (gate) return gate;
+    for (const step of phase.steps) {
+      if (isGate(step)) return step;
+      if (isEffect(step)) {
+        const nested = step.steps.find(isGate);
+        if (nested) return nested;
+      }
+    }
   }
   return undefined;
 }
@@ -145,6 +153,13 @@ async function callWithTimeout(
 
 // ── Step + phase execution ────────────────────────────────────────────────��─
 
+/** A finished step: its record plus (on success) the activity's return value —
+ * the effect-step path needs `receiptRead`'s result, not just its status. */
+interface RanStep {
+  record: StepRecord;
+  result?: unknown;
+}
+
 /** Run one activity step with retry + timeout. Never throws — returns a record. */
 async function runStep(
   step: ActivityStep,
@@ -152,7 +167,7 @@ async function runStep(
   activities: Map<string, ActivityFn>,
   profiles: Record<string, ActivityProfile>,
   signal?: AbortSignal,
-): Promise<StepRecord> {
+): Promise<RanStep> {
   const args = step.args ?? {};
   const base = { phase: phaseName, fn: step.fn, args };
   const start = Date.now();
@@ -161,7 +176,7 @@ async function runStep(
   try {
     fn = resolveActivity(activities, step.fn);
   } catch (err) {
-    return { ...base, status: "fail", durationMs: 0, error: errMessage(err) };
+    return { record: { ...base, status: "fail", durationMs: 0, error: errMessage(err) } };
   }
 
   const profile = profiles[step.profile ?? DEFAULT_PROFILE] ?? {};
@@ -190,7 +205,7 @@ async function runStep(
           value: resolvePath(result, step.outcomeAttribute.from),
         };
       }
-      return record;
+      return { record, result };
     } catch (err) {
       lastErr = err;
       // Stop retrying on abort (Ctrl-C / timeout cascade) or a non-retryable error.
@@ -204,7 +219,105 @@ async function runStep(
       break;
     }
   }
-  return { ...base, status: "fail", durationMs: Date.now() - start, error: errMessage(lastErr) };
+  return { record: { ...base, status: "fail", durationMs: Date.now() - start, error: errMessage(lastErr) } };
+}
+
+// ── Effect steps (#1834) ──────────────────────────────────────────────────────
+
+/** 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 {
+  return {
+    kind: "activity",
+    fn: "receiptRead",
+    args: {
+      receipt: step.receipt,
+      ...(step.expectation !== undefined ? { expectation: step.expectation } : {}),
+    },
+    profile: "fastIdempotent",
+    outcomeAttribute: { name: "EffectApplied", from: "applied" },
+  };
+}
+
+/** A skipped-record for a step that will not run. */
+function skippedRecord(phaseName: string, fn: string, args?: Record<string, unknown>): StepRecord {
+  return { phase: phaseName, fn, args: args ?? {}, status: "skipped", durationMs: 0 };
+}
+
+/**
+ * Run one effect step: read-compare-run-write. On a match the nested steps are
+ * recorded as skipped ("effect already applied") and nothing is written. On a
+ * mismatch the nested steps run in authored order; only when every one
+ * succeeds is the receipt written — last, once (the sole writer, #1703
+ * decision 3). Any failure leaves the receipt untouched (stale), so the next
+ * run re-proposes the effect.
+ */
+async function runEffectStep(
+  step: EffectStep,
+  phaseName: string,
+  activities: Map<string, ActivityFn>,
+  profiles: Record<string, ActivityProfile>,
+  signal?: AbortSignal,
+): Promise<{ records: StepRecord[]; failed: boolean }> {
+  const records: StepRecord[] = [];
+
+  const read = await runStep(receiptReadStep(step), phaseName, activities, profiles, signal);
+  records.push(read.record);
+  if (read.record.status === "fail") return { records, failed: true };
+
+  const result = read.result as Partial<ReceiptReadResult> | undefined;
+  if (typeof result?.expectation !== "string") {
+    records.push({
+      phase: phaseName,
+      fn: `effect:${step.receipt.name}`,
+      args: {},
+      status: "fail",
+      durationMs: 0,
+      error: "receiptRead returned no expectation — the receipt store activity must return { current, expectation }",
+    });
+    return { records, failed: true };
+  }
+  const expectation = result.expectation;
+
+  if (result.current === expectation) {
+    // Effect already applied — skip the nested steps, write nothing.
+    for (const nested of step.steps) {
+      if (nested.kind === "activity") records.push(skippedRecord(phaseName, nested.fn, nested.args));
+    }
+    return { records, failed: false };
+  }
+
+  // Gates are pre-flighted by findGate; only activities remain here.
+  const nestedActivities = step.steps.filter(isActivity);
+  for (let i = 0; i < nestedActivities.length; i++) {
+    const ran = await runStep(nestedActivities[i], phaseName, activities, profiles, signal);
+    records.push(ran.record);
+    if (ran.record.status === "fail") {
+      // Receipt left untouched (stale) — the next run re-proposes the effect.
+      for (const skipped of nestedActivities.slice(i + 1)) {
+        records.push(skippedRecord(phaseName, skipped.fn, skipped.args));
+      }
+      records.push(skippedRecord(phaseName, "receiptWrite"));
+      return { records, failed: true };
+    }
+  }
+
+  // Sole writer of the receipt: on success of every nested step, last.
+  const wrote = await runStep(
+    {
+      kind: "activity",
+      fn: "receiptWrite",
+      args: { receipt: step.receipt, expectation },
+      profile: "fastIdempotent",
+    },
+    phaseName,
+    activities,
+    profiles,
+    signal,
+  );
+  records.push(wrote.record);
+  return { records, failed: wrote.record.status === "fail" };
 }
 
 /** Run a phase. Throws PhaseFailure (with records so far) if any step fails. */
@@ -214,35 +327,57 @@ async function runPhase(
   profiles: Record<string, ActivityProfile>,
   signal?: AbortSignal,
 ): Promise<StepRecord[]> {
-  // Defensive: gates are pre-flighted, but never execute one if it slips through.
-  const gate = phase.steps.find(isGate);
+  // Defensive: gates are pre-flighted, but never execute one if it slips
+  // through — including a gate nested inside an effect step.
+  const gate =
+    phase.steps.find(isGate) ??
+    phase.steps.filter(isEffect).flatMap((e) => e.steps).find(isGate);
   if (gate) throw new LocalGateUnsupportedError(gate.signalName);
 
-  const steps = phase.steps.filter(isActivity);
-
   if (phase.parallel) {
-    const records = await Promise.all(
-      steps.map((s) => runStep(s, phase.name, activities, profiles, signal)),
-    );
+    const eff = phase.steps.find(isEffect);
+    if (eff) {
+      throw new Error(
+        `effect step "${eff.receipt.name}" cannot run in a parallel phase — read-compare-run-write is ordered`,
+      );
+    }
+    const steps = phase.steps.filter(isActivity);
+    const records = (
+      await Promise.all(steps.map((s) => runStep(s, phase.name, activities, profiles, signal)))
+    ).map((r) => r.record);
     if (records.some((r) => r.status === "fail")) throw new PhaseFailure(records);
     return records;
   }
 
+  const steps = phase.steps.filter((s): s is ActivityStep | EffectStep => !isGate(s));
   const records: StepRecord[] = [];
+
+  const skipRemaining = (from: number) => {
+    for (const skipped of steps.slice(from)) {
+      if (isEffect(skipped)) {
+        records.push(skippedRecord(phase.name, `effect:${skipped.receipt.name}`));
+      } else {
+        records.push(skippedRecord(phase.name, skipped.fn, skipped.args));
+      }
+    }
+  };
+
   for (let i = 0; i < steps.length; i++) {
-    const record = await runStep(steps[i], phase.name, activities, profiles, signal);
+    const step = steps[i];
+    if (isEffect(step)) {
+      const { records: effRecords, failed } = await runEffectStep(step, phase.name, activities, profiles, signal);
+      records.push(...effRecords);
+      if (failed) {
+        skipRemaining(i + 1);
+        throw new PhaseFailure(records);
+      }
+      continue;
+    }
+    const { record } = await runStep(step, phase.name, activities, profiles, signal);
     records.push(record);
     if (record.status === "fail") {
       // Mark the remaining steps in this phase as skipped, then abort.
-      for (const skipped of steps.slice(i + 1)) {
-        records.push({
-          phase: phase.name,
-          fn: skipped.fn,
-          args: skipped.args ?? {},
-          status: "skipped",
-          durationMs: 0,
-        });
-      }
+      skipRemaining(i + 1);
       throw new PhaseFailure(records);
     }
   }
@@ -266,6 +401,18 @@ export async function runOpLocally(
   const gate = findGate(config);
   if (gate) throw new LocalGateUnsupportedError(gate.signalName);
 
+  // Effect steps are ordered (read-compare-run-write): refuse them in a
+  // parallel phase up front, with the phase named, rather than mid-run.
+  for (const phase of [...config.phases, ...(config.onFailure ?? [])]) {
+    const eff = phase.parallel ? phase.steps.find(isEffect) : undefined;
+    if (eff) {
+      throw new Error(
+        `phase "${phase.name}": effect step "${eff.receipt.name}" cannot run in a ` +
+          `parallel phase — read-compare-run-write is ordered`,
+      );
+    }
+  }
+
   const records: StepRecord[] = [];
   const start = Date.now();
 

package/src/op/op.test.ts

@@ -3,8 +3,8 @@
  */
 
 import { describe, expect, it } from "vitest";
-import { Op, phase, activity, gate, build, kubectlApply, helmInstall,
-         waitForStack, gitlabPipeline, lifecycleSnapshot, shell, teardown, policyGate } from "./builders";
+import { Op, phase, activity, gate, build, kubectlApply, helmInstall, helmInstallPinned,
+         waitForStack, gitlabPipeline, lifecycleSnapshot, shell, ensureSecret, teardown, policyGate } from "./builders";
 import { DECLARABLE_MARKER, type Declarable } from "../declarable";
 
 // ── Op() ──────────────────────────────────────────────────────────────────────
@@ -163,6 +163,16 @@ describe("pre-built shortcuts", () => {
     expect(a.profile).toBe("longInfra");
   });
 
+  it("helmInstallPinned() produces a helmInstall activity keyed by contentDigest, no chart", () => {
+    const a = helmInstallPinned("my-release", "sha256:abc", { namespace: "web" });
+    expect(a.fn).toBe("helmInstall");
+    expect(a.args?.name).toBe("my-release");
+    expect(a.args?.contentDigest).toBe("sha256:abc");
+    expect(a.args?.namespace).toBe("web");
+    expect(a.args?.chart).toBeUndefined();
+    expect(a.profile).toBe("longInfra");
+  });
+
   it("waitForStack() produces waitForStack activity with k8sWait profile", () => {
     const a = waitForStack("my-stack");
     expect(a.fn).toBe("waitForStack");
@@ -190,6 +200,19 @@ describe("pre-built shortcuts", () => {
     expect(a.args?.cmd).toBe("echo hello");
   });
 
+  it("ensureSecret() produces ensureSecret activity with name/keys args and no material-shaped field", () => {
+    const a = ensureSecret("master-key", ["MASTER_SECRETS_KEY"], {
+      metadata: { "chant.dev/provenance": "generated-once" },
+    });
+    expect(a.fn).toBe("ensureSecret");
+    expect(a.args?.name).toBe("master-key");
+    expect(a.args?.keys).toEqual(["MASTER_SECRETS_KEY"]);
+    expect(a.args?.metadata).toEqual({ "chant.dev/provenance": "generated-once" });
+    // The step is contract-only: nothing on it could carry secret material.
+    expect(a.args && "value" in a.args).toBe(false);
+    expect(a.args && "data" in a.args).toBe(false);
+  });
+
   it("teardown() produces chantTeardown activity with longInfra profile", () => {
     const a = teardown("./project");
     expect(a.fn).toBe("chantTeardown");