@intentius/chant 0.46.0 → 0.50.0

package/src/op/local-executor.ts

@@ -11,8 +11,10 @@
  * 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";
+import { isStepOutputRef } from "./step-output-ref";
 
 // ── Records ─────────────────────────────────────────────────────────────────
 
@@ -69,6 +71,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 +95,37 @@ function resolvePath(value: unknown, path?: string): unknown {
   );
 }
 
-/** Find the first gate step anywhere in the Op (phases + onFailure), if any. */
+/**
+ * Deep-walk `value`, replacing every {@link StepOutputRef} with the recorded
+ * result of its producer step, resolved through the ref's optional dot-path
+ * exactly like the serializer's compiled `__rN?.path?.segments` (chant #1290)
+ * — `resolvePath` gives the same "undefined intermediate resolves to
+ * undefined, never throws" semantics. A reference to a step whose result
+ * isn't in `resultsById` (never ran, or ran out of the scope
+ * `validateStepOutputRefs` allows) resolves to `undefined`, the same way a
+ * producer whose declared field is absent would.
+ */
+function resolveStepOutputRefs(value: unknown, resultsById: ReadonlyMap<string, unknown>): unknown {
+  if (isStepOutputRef(value)) return resolvePath(resultsById.get(value.step), value.path);
+  if (Array.isArray(value)) return value.map((v) => resolveStepOutputRefs(v, resultsById));
+  if (value && typeof value === "object") {
+    return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, resolveStepOutputRefs(v, resultsById)]));
+  }
+  return value;
+}
+
+/** 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,15 +173,29 @@ async function callWithTimeout(
 
 // ── Step + phase execution ────────────────────────────────────────────────��─
 
-/** Run one activity step with retry + timeout. Never throws — returns a record. */
+/** 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. Any {@link StepOutputRef} in `step.args` is resolved against
+ * `resultsById` before the activity is called (#1290) — the local executor
+ * is a first-class peer of the Temporal path, so an unresolved placeholder
+ * must never reach an activity function; see `resolveStepOutputRefs`.
+ */
 async function runStep(
   step: ActivityStep,
   phaseName: string,
   activities: Map<string, ActivityFn>,
   profiles: Record<string, ActivityProfile>,
+  resultsById: Map<string, unknown>,
   signal?: AbortSignal,
-): Promise<StepRecord> {
-  const args = step.args ?? {};
+): Promise<RanStep> {
+  const args = resolveStepOutputRefs(step.args ?? {}, resultsById) as Record<string, unknown>;
   const base = { phase: phaseName, fn: step.fn, args };
   const start = Date.now();
 
@@ -161,7 +203,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] ?? {};
@@ -183,6 +225,7 @@ async function runStep(
   for (let attempt = 1; attempt <= maxAttempts; attempt++) {
     try {
       const result = await callWithTimeout(fn, args, timeoutMs, signal);
+      if (step.id) resultsById.set(step.id, result);
       const record: StepRecord = { ...base, status: "ok", durationMs: Date.now() - start };
       if (step.outcomeAttribute) {
         record.outcome = {
@@ -190,7 +233,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 +247,107 @@ 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>,
+  resultsById: Map<string, unknown>,
+  signal?: AbortSignal,
+): Promise<{ records: StepRecord[]; failed: boolean }> {
+  const records: StepRecord[] = [];
+
+  const read = await runStep(receiptReadStep(step), phaseName, activities, profiles, resultsById, 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, resultsById, 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,
+    resultsById,
+    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. */
@@ -212,37 +355,60 @@ async function runPhase(
   phase: PhaseDefinition,
   activities: Map<string, ActivityFn>,
   profiles: Record<string, ActivityProfile>,
+  resultsById: Map<string, unknown>,
   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, resultsById, 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, resultsById, signal);
+      records.push(...effRecords);
+      if (failed) {
+        skipRemaining(i + 1);
+        throw new PhaseFailure(records);
+      }
+      continue;
+    }
+    const { record } = await runStep(step, phase.name, activities, profiles, resultsById, 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,13 +432,30 @@ 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();
 
+  // Completed step id → its activity result (#1290). Populated as main-phase
+  // steps finish, so a later step's step-output references resolve to real
+  // values before reaching an activity function — see `runStep`.
+  const resultsById = new Map<string, unknown>();
+
   try {
     for (const phase of config.phases) {
       if (signal?.aborted) throw new PhaseFailure([]);
-      records.push(...(await runPhase(phase, activities, profiles, signal)));
+      records.push(...(await runPhase(phase, activities, profiles, resultsById, signal)));
     }
   } catch (err) {
     if (err instanceof PhaseFailure) records.push(...err.records);
@@ -282,7 +465,7 @@ export async function runOpLocally(
     if (!signal?.aborted) {
       for (const phase of [...(config.onFailure ?? [])].reverse()) {
         try {
-          records.push(...(await runPhase(phase, activities, profiles, signal)));
+          records.push(...(await runPhase(phase, activities, profiles, resultsById, signal)));
         } catch (compErr) {
           if (compErr instanceof PhaseFailure) records.push(...compErr.records);
         }

package/src/op/op-verb-class.test.ts

@@ -0,0 +1,126 @@
+import { describe, test, expect } from "vitest";
+import { classifyOpVerbClass, isGated } from "./op-verb-class";
+import type { OpConfig } from "./types";
+
+function cfg(phases: OpConfig["phases"], onFailure?: OpConfig["onFailure"]): Pick<OpConfig, "phases" | "onFailure"> {
+  return { phases, ...(onFailure ? { onFailure } : {}) };
+}
+
+describe("classifyOpVerbClass", () => {
+  test("read-only for a WatchOp-shaped composition (snapshot + diff)", () => {
+    const config = cfg([
+      { name: "Snapshot", steps: [{ kind: "activity", fn: "lifecycleSnapshot", args: { env: "prod" } }] },
+      { name: "Diff", steps: [{ kind: "activity", fn: "lifecycleDiff", args: { env: "prod" } }] },
+    ]);
+    expect(classifyOpVerbClass(config)).toBe("read-only");
+  });
+
+  test("read-only for an empty phase list", () => {
+    expect(classifyOpVerbClass(cfg([]))).toBe("read-only");
+  });
+
+  test("mutating for nativeApply with deleteMode never", () => {
+    const config = cfg([
+      { name: "Apply", steps: [{ kind: "activity", fn: "nativeApply", args: { target: "kubectl", env: "prod", output: "dist", deleteMode: "never" } }] },
+    ]);
+    expect(classifyOpVerbClass(config)).toBe("mutating");
+  });
+
+  test("mutating for nativeApply with no deleteMode at all", () => {
+    const config = cfg([
+      { name: "Apply", steps: [{ kind: "activity", fn: "nativeApply", args: { target: "kubectl", env: "prod", output: "dist" } }] },
+    ]);
+    expect(classifyOpVerbClass(config)).toBe("mutating");
+  });
+
+  test("destructive for nativeApply with deleteMode owned-only", () => {
+    const config = cfg([
+      { name: "Apply", steps: [{ kind: "activity", fn: "nativeApply", args: { target: "kubectl", env: "prod", output: "dist", deleteMode: "owned-only" } }] },
+    ]);
+    expect(classifyOpVerbClass(config)).toBe("destructive");
+  });
+
+  test("destructive for nativeApply with deleteMode gated", () => {
+    const config = cfg([
+      { name: "Apply", steps: [{ kind: "activity", fn: "nativeApply", args: { target: "kubectl", env: "prod", output: "dist", deleteMode: "gated" } }] },
+    ]);
+    expect(classifyOpVerbClass(config)).toBe("destructive");
+  });
+
+  test("destructive for envTeardown regardless of args", () => {
+    const config = cfg([{ name: "Teardown", steps: [{ kind: "activity", fn: "envTeardown", args: { env: "staging" } }] }]);
+    expect(classifyOpVerbClass(config)).toBe("destructive");
+  });
+
+  test("destructive for awsDelete/azDelete/gcpDelete/chantTeardown", () => {
+    for (const fn of ["awsDelete", "azDelete", "gcpDelete", "chantTeardown"]) {
+      const config = cfg([{ name: "P", steps: [{ kind: "activity", fn, args: {} }] }]);
+      expect(classifyOpVerbClass(config)).toBe("destructive");
+    }
+  });
+
+  test("fail-closed: an unrecognized activity fn is mutating, not read-only", () => {
+    const config = cfg([{ name: "P", steps: [{ kind: "activity", fn: "someBespokeCustomActivity", args: {} }] }]);
+    expect(classifyOpVerbClass(config)).toBe("mutating");
+  });
+
+  test("a single destructive step outranks other read-only/mutating steps in the same Op", () => {
+    const config = cfg([
+      { name: "Diff", steps: [{ kind: "activity", fn: "lifecycleDiff", args: { env: "prod" } }] },
+      { name: "Teardown", steps: [{ kind: "activity", fn: "envTeardown", args: { env: "prod" } }] },
+    ]);
+    expect(classifyOpVerbClass(config)).toBe("destructive");
+  });
+
+  test("checks onFailure phases too", () => {
+    const config = cfg(
+      [{ name: "Apply", steps: [{ kind: "activity", fn: "lifecycleDiff", args: { env: "prod" } }] }],
+      [{ name: "Rollback", steps: [{ kind: "activity", fn: "envTeardown", args: { env: "prod" } }] }],
+    );
+    expect(classifyOpVerbClass(config)).toBe("destructive");
+  });
+
+  test("looks inside an effect step's nested activity steps", () => {
+    const config = cfg([
+      {
+        name: "Seed",
+        steps: [
+          {
+            kind: "effect",
+            receipt: { name: "seeded", lexicon: "aws" } as never,
+            steps: [{ kind: "activity", fn: "nativeApply", args: { target: "kubectl", env: "prod", output: "dist", deleteMode: "gated" } }],
+          },
+        ],
+      },
+    ]);
+    expect(classifyOpVerbClass(config)).toBe("destructive");
+  });
+});
+
+describe("isGated", () => {
+  test("false with no gate step", () => {
+    expect(isGated(cfg([{ name: "Apply", steps: [{ kind: "activity", fn: "nativeApply", args: {} }] }]))).toBe(false);
+  });
+
+  test("true with a gate step in the main phases", () => {
+    expect(
+      isGated(
+        cfg([
+          { name: "Approve", steps: [{ kind: "gate", signalName: "approve-x" }] },
+          { name: "Apply", steps: [{ kind: "activity", fn: "nativeApply", args: {} }] },
+        ]),
+      ),
+    ).toBe(true);
+  });
+
+  test("true with a gate step in onFailure", () => {
+    expect(
+      isGated(
+        cfg(
+          [{ name: "Apply", steps: [{ kind: "activity", fn: "nativeApply", args: {} }] }],
+          [{ name: "Rollback", steps: [{ kind: "gate", signalName: "approve-rollback" }] }],
+        ),
+      ),
+    ).toBe(true);
+  });
+});

package/src/op/op-verb-class.ts

@@ -0,0 +1,115 @@
+/**
+ * Op verb classification (#1484) — generalizes `delete: "never" | "owned-only"
+ * | "gated"` (`../lifecycle` teardown/apply's `DeleteMode`) up one level, to
+ * the whole Op: read-only, mutating, or destructive. `ConvergeOp`'s
+ * dial × verb-class matrix (the issue's "Autonomy" table) needs to answer
+ * "what kind of thing is this dispatched Op, from the outside" for an
+ * arbitrary declared Op — including one this project's authors wrote, not
+ * just the pre-built composites — so classification walks `OpConfig`'s
+ * steps rather than trusting a self-reported tag.
+ *
+ * There is no existing per-Op verb-class field (`searchAttributes` is a free
+ * `Record<string,string>` an author may or may not set — `ApplyOp` tags
+ * `{ Apply: "true" }` but nothing requires it, and it carries no verb-class
+ * semantics on its own) and no existing "which activity names are
+ * destructive" registry (`../lint/pipeline-change-gate.ts`'s classifier is
+ * shaped for a `Component` composition's capability-verb steps, not an
+ * `OpConfig`'s activity steps — a genuinely different graph). This module is
+ * that registry's Op-shaped sibling: a small, explicit set of known
+ * mutating/destructive activity function names, plus the one piece of
+ * structured signal that already exists (`nativeApply`'s `deleteMode` arg).
+ *
+ * Fail-closed by construction: an activity `fn` this module doesn't
+ * recognize is classified `mutating`, never `read-only` — an unknown step
+ * might do anything, and "unknown never remediates" (the issue's own honesty
+ * requirement for symptoms) applies here too: this module never silently
+ * clears an Op to free-run just because its steps aren't in the known-safe
+ * list.
+ */
+
+import { findGate } from "./local-executor";
+import type { ActivityStep, EffectStep, OpConfig, StepDefinition } from "./types";
+
+export type OpVerbClass = "read-only" | "mutating" | "destructive";
+
+/** Activity function names known to be read-only — verification, observation, audit. Anything not in this set is treated as at least `mutating` (fail-closed). */
+const READ_ONLY_ACTIVITY_FNS: ReadonlySet<string> = new Set([
+  "lifecycleSnapshot",
+  "lifecycleDiff",
+  "httpCheck",
+  "policyGate",
+  "workflowSupplyChainAudit",
+  "pipelineSupplyChainAudit",
+  "receiptStaleness",
+  "waitForStack",
+  "waitForReady",
+  "waitForArgoSync",
+  "spriteReadFile",
+  "spriteListDir",
+  "listCheckpoints",
+  "convergeTick",
+]);
+
+/** Activity function names that always delete/destroy, regardless of args. */
+const ALWAYS_DESTRUCTIVE_ACTIVITY_FNS: ReadonlySet<string> = new Set([
+  "envTeardown",
+  "chantTeardown",
+  "azDelete",
+  "awsDelete",
+  "gcpDelete",
+  "spriteDestroy",
+  "k3dDown",
+  "k3sUninstall",
+]);
+
+function stepsOf(config: Pick<OpConfig, "phases" | "onFailure">): ActivityStep[] {
+  const all: StepDefinition[] = [...config.phases, ...(config.onFailure ?? [])].flatMap((p) => p.steps);
+  const flat: ActivityStep[] = [];
+  for (const step of all) {
+    if (step.kind === "activity") flat.push(step);
+    else if (step.kind === "effect") flat.push(...(step as EffectStep).steps.filter((s): s is ActivityStep => s.kind === "activity"));
+  }
+  return flat;
+}
+
+/**
+ * Classify an Op's own composition. Pure — reads only the passed config, no
+ * I/O. `nativeApply`'s `deleteMode` (`"never" | "owned-only" | "gated"`) is
+ * read straight off the step's `args` — `"owned-only"`/`"gated"` are
+ * destructive (both can delete a live resource), `"never"`/absent is merely
+ * mutating (creates/updates only). A step whose `fn` matches neither the
+ * read-only nor the destructive set is `mutating` by default (fail-closed).
+ */
+export function classifyOpVerbClass(config: Pick<OpConfig, "phases" | "onFailure">): OpVerbClass {
+  let sawMutating = false;
+
+  for (const step of stepsOf(config)) {
+    if (ALWAYS_DESTRUCTIVE_ACTIVITY_FNS.has(step.fn)) return "destructive";
+
+    if (step.fn === "nativeApply") {
+      const deleteMode = step.args?.deleteMode;
+      if (deleteMode === "owned-only" || deleteMode === "gated") return "destructive";
+      sawMutating = true;
+      continue;
+    }
+
+    if (step.fn === "compensateApply") {
+      // Rollback compensation — mutating (it re-applies a prior state), not
+      // itself a fresh destructive act.
+      sawMutating = true;
+      continue;
+    }
+
+    if (READ_ONLY_ACTIVITY_FNS.has(step.fn)) continue;
+
+    // Unknown or known-mutating fn: fail-closed to mutating.
+    sawMutating = true;
+  }
+
+  return sawMutating ? "mutating" : "read-only";
+}
+
+/** Does this Op have its own approval gate anywhere in its phases (main or `onFailure`)? Thin re-export of `findGate` under the name this module's callers reach for. */
+export function isGated(config: Pick<OpConfig, "phases" | "onFailure">): boolean {
+  return findGate(config as OpConfig) !== undefined;
+}

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");