@intentius/chant 0.49.0 → 0.50.0

package/src/op/generate-pipeline.ts

@@ -0,0 +1,99 @@
+/**
+ * Generate mode's Op counterpart (#927): synthesize scheduled CI for
+ * stateless Ops — the cron-triggered sibling of `generateComponentsPipeline`
+ * (../components/cli-support.ts, #563/#688). A component pipeline triggers a
+ * deploy-time graph on `workflow_dispatch`; this triggers already-built Ops
+ * on a cron, each via `chant run <name>` on the local executor — the same
+ * one-shot invocation documented at docs/src/content/docs/guide/ops.mdx. Core
+ * owns only Op discovery, so a typo'd name fails fast before any CI is
+ * generated; the CI-specific synthesis is contributed by the target
+ * lexicon's `generateOpPipeline` (../lexicon.ts), exactly like
+ * `generateComponentPipeline`.
+ *
+ * There is no dependency graph between scheduled Ops the way there is
+ * between components — `Op.depends` orders phases within one run, not
+ * separately scheduled cron triggers — so this does not call
+ * `resolveComponentGraph`; each `ScheduledOpSpec` is generated independently.
+ */
+
+import { discoverOps } from "./discover";
+import {
+  isLexiconPlugin,
+  type LexiconPlugin,
+  type ComponentPipelineOptions,
+  type ScheduledOpSpec,
+  type OpPipelineFile,
+  type OpPipelineJob,
+} from "../lexicon";
+
+/**
+ * Load a lexicon's plugin (`@intentius/chant-lexicon-<name>`) to reach its
+ * `generateOpPipeline`. Tolerant: returns null when the package can't be
+ * resolved. Kept local (rather than imported from
+ * `../components/cli-support.ts`) so this module carries no dependency on
+ * `components/`.
+ */
+async function loadLexiconPlugin(name: string): Promise<LexiconPlugin | null> {
+  let mod: Record<string, unknown>;
+  try {
+    mod = (await import(`@intentius/chant-lexicon-${name}`)) as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+  for (const value of Object.values(mod)) {
+    if (isLexiconPlugin(value)) return value;
+  }
+  return null;
+}
+
+/** Result of generating scheduled CI for a set of Ops (generate mode's Op counterpart, #927). */
+export interface GenerateOpsPipelineResult {
+  success: boolean;
+  /** One generated CI file per scheduled Op, when `success` is true. */
+  files?: OpPipelineFile[];
+  /** Every generated job, for a machine-readable view. */
+  jobs?: OpPipelineJob[];
+  error?: string;
+}
+
+/**
+ * Synthesize scheduled CI for `ops` targeting `lexicon`: validate every named
+ * Op exists (`discoverOps`, under the git root — mirrors `chant run <name>`'s
+ * own resolution), then dispatch to the lexicon's `generateOpPipeline`. No
+ * deploy/audit logic is inlined into the generated YAML — the finding-mode
+ * behavior lives in the Op's own activity args, set by the composite that
+ * built it (`WorkflowAuditOp`, `PipelineAuditOp`, `ReconcileOp`, …); this
+ * function only wires the cron trigger and the token/permission surface the
+ * declared `findingMode` needs.
+ */
+export async function generateOpsPipeline(
+  ops: ScheduledOpSpec[],
+  lexicon: string,
+  options?: ComponentPipelineOptions,
+  cwd?: string,
+): Promise<GenerateOpsPipelineResult> {
+  const plugin = await loadLexiconPlugin(lexicon);
+  if (!plugin?.generateOpPipeline) {
+    return {
+      success: false,
+      error: `Lexicon "${lexicon}" does not support Op generate mode (no generateOpPipeline). GitLab, GitHub, and Forgejo are supported today.`,
+    };
+  }
+
+  const discovered = await discoverOps({ cwd });
+  if (discovered.errors.length > 0) {
+    return { success: false, error: discovered.errors.join("\n") };
+  }
+
+  const unknown = ops.filter((spec) => !discovered.ops.has(spec.name));
+  if (unknown.length > 0) {
+    const known = [...discovered.ops.keys()].sort().join(", ");
+    return {
+      success: false,
+      error: `Unknown Op(s): ${unknown.map((s) => s.name).join(", ")}.${known ? ` Known Ops: ${known}` : " No Ops discovered."}`,
+    };
+  }
+
+  const { files, jobs } = plugin.generateOpPipeline(ops, options);
+  return { success: true, files, jobs };
+}

package/src/op/index.ts

@@ -23,8 +23,38 @@ export type {
 } from "./receipt-store";
 export { discoverOps } from "./discover";
 export type { DiscoveredOp, OpDiscoveryResult } from "./discover";
+export { generateOpsPipeline } from "./generate-pipeline";
+export type { GenerateOpsPipelineResult } from "./generate-pipeline";
 export { loadActivities, loadProfiles, resolveActivity } from "./activity-registry";
 export type { ActivityFn, ActivityProfile } from "./activity-registry";
 export { runOpLocally, parseDuration, findGate, LocalGateUnsupportedError, OpRunFailure } from "./local-executor";
 export type { StepRecord, OpRunResult } from "./local-executor";
 export { renderHuman, renderJson } from "./local-output";
+export {
+  activityContract, isActivityContract, collectActivityContracts, validateActivitySteps, KNOWN_ACTIVITY_PROFILES,
+  pathExistsInSchema,
+} from "./activity-contract";
+export type { ActivityContract, ActivityContractIssue } from "./activity-contract";
+export { stepOutput, isStepOutputRef, collectStepOutputRefs, validateStepOutputRefs, validateStepOutputRefScope, makeOutProxy } from "./step-output-ref";
+export type { StepOutputRef, WithStepRefs } from "./step-output-ref";
+export type { NamedActivityStep } from "./builders";
+export {
+  eq, neq, gt, gte, lt, lte, truthy, falsy, allOf, anyOf,
+  evaluatePredicate, isWellFormedPredicate, predicateReferencesField,
+  run, report,
+  when, duplicateRuleIds,
+  DEFAULT_FLAP_THRESHOLD,
+} from "./converge-rule";
+export type {
+  FieldComparisonOp, FieldTruthinessOp,
+  FieldComparisonPredicate, FieldTruthinessPredicate, AllOfPredicate, AnyOfPredicate, SymptomPredicate,
+  RunAction, ReportAction, RuleAction, ConvergeRule,
+} from "./converge-rule";
+export {
+  discoverConvergeOps, runOperatorRound, runOperatorForever, formatRoundLine,
+  DEFAULT_OPERATOR_INTERVAL_MS,
+} from "./operator";
+export type { OperatorTickEvent, OperatorRoundOptions, OperatorLoopOptions } from "./operator";
+export { classifyOpVerbClass, isGated } from "./op-verb-class";
+export type { OpVerbClass } from "./op-verb-class";
+export { takeProfileAndId } from "./builders";

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

@@ -8,6 +8,7 @@ import {
   LocalGateUnsupportedError,
   OpRunFailure,
 } from "./local-executor";
+import { stepOutput } from "./step-output-ref";
 
 // Fast profiles so retry/timeout tests run in milliseconds.
 const PROFILES: Record<string, ActivityProfile> = {
@@ -261,3 +262,94 @@ describe("runOpLocally — gate rejection", () => {
     expect(gated?.signalName).toBe("g");
   });
 });
+
+describe("runOpLocally — step-output references (#1290)", () => {
+  test("a later step receives the producer's resolved value, not the placeholder", async () => {
+    const received: unknown[] = [];
+    const activities = new Map<string, ActivityFn>([
+      ["produce", async () => ({ driftedStacks: ["a", "b"], count: 2 })],
+      ["consume", async (args) => { received.push(args); }],
+    ]);
+    const config = op({
+      phases: [{ name: "P", steps: [
+        { kind: "activity", fn: "produce", id: "diff" },
+        { kind: "activity", fn: "consume", args: { stacks: stepOutput("diff", "driftedStacks") } },
+      ] }],
+    });
+    const result = await runOpLocally(config, activities, PROFILES);
+    expect(result.ok).toBe(true);
+    expect(received).toEqual([{ stacks: ["a", "b"] }]);
+    // The recorded step also shows the resolved value, not the raw ref object.
+    expect(result.records[1].args).toEqual({ stacks: ["a", "b"] });
+  });
+
+  test("a whole-value reference (no path) passes the entire producer result", async () => {
+    const received: unknown[] = [];
+    const activities = new Map<string, ActivityFn>([
+      ["produce", async () => ({ ok: true, detail: "x" })],
+      ["consume", async (args) => { received.push(args); }],
+    ]);
+    const config = op({
+      phases: [{ name: "P", steps: [
+        { kind: "activity", fn: "produce", id: "p" },
+        { kind: "activity", fn: "consume", args: { result: stepOutput("p") } },
+      ] }],
+    });
+    await runOpLocally(config, activities, PROFILES);
+    expect(received).toEqual([{ result: { ok: true, detail: "x" } }]);
+  });
+
+  test("resolves a reference nested inside an object and an array", async () => {
+    const received: unknown[] = [];
+    const activities = new Map<string, ActivityFn>([
+      ["produce", async () => ({ name: "prod" })],
+      ["consume", async (args) => { received.push(args); }],
+    ]);
+    const config = op({
+      phases: [{ name: "P", steps: [
+        { kind: "activity", fn: "produce", id: "p" },
+        {
+          kind: "activity",
+          fn: "consume",
+          args: { config: { tags: ["static", stepOutput("p", "name")] } },
+        },
+      ] }],
+    });
+    await runOpLocally(config, activities, PROFILES);
+    expect(received).toEqual([{ config: { tags: ["static", "prod"] } }]);
+  });
+
+  test("an unresolvable path resolves to undefined instead of throwing", async () => {
+    const received: unknown[] = [];
+    const activities = new Map<string, ActivityFn>([
+      ["produce", async () => ({})],
+      ["consume", async (args) => { received.push(args); }],
+    ]);
+    const config = op({
+      phases: [{ name: "P", steps: [
+        { kind: "activity", fn: "produce", id: "p" },
+        { kind: "activity", fn: "consume", args: { v: stepOutput("p", "a.b") } },
+      ] }],
+    });
+    const result = await runOpLocally(config, activities, PROFILES);
+    expect(result.ok).toBe(true);
+    expect(received).toEqual([{ v: undefined }]);
+  });
+
+  test("e2e: chant run (non-temporal) end to end — producer object flows to consumer", async () => {
+    const activities = new Map<string, ActivityFn>([
+      ["lifecycleDiff", async () => ({ driftedStacks: ["stack-a"], drifted: true })],
+      ["applyStacks", async (args) => ({ applied: args.stacks })],
+    ]);
+    const config = op({
+      phases: [
+        { name: "Diff", steps: [{ kind: "activity", fn: "lifecycleDiff", id: "diff", args: { env: "prod" } }] },
+        { name: "Apply", steps: [{ kind: "activity", fn: "applyStacks", args: { stacks: stepOutput("diff", "driftedStacks") } }] },
+      ],
+    });
+    const result = await runOpLocally(config, activities, PROFILES);
+    expect(result.ok).toBe(true);
+    expect(result.records.every((r) => r.status === "ok")).toBe(true);
+    expect(result.records[1].args).toEqual({ stacks: ["stack-a"] });
+  });
+});

package/src/op/local-executor.ts

@@ -14,6 +14,7 @@
 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 ─────────────────────────────────────────────────────────────────
 
@@ -94,6 +95,25 @@ function resolvePath(value: unknown, path?: string): unknown {
   );
 }
 
+/**
+ * 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 {
@@ -160,15 +180,22 @@ interface RanStep {
   result?: unknown;
 }
 
-/** Run one activity step with retry + timeout. Never throws — returns a record. */
+/**
+ * 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<RanStep> {
-  const args = step.args ?? {};
+  const args = resolveStepOutputRefs(step.args ?? {}, resultsById) as Record<string, unknown>;
   const base = { phase: phaseName, fn: step.fn, args };
   const start = Date.now();
 
@@ -198,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 = {
@@ -258,11 +286,12 @@ async function runEffectStep(
   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, signal);
+  const read = await runStep(receiptReadStep(step), phaseName, activities, profiles, resultsById, signal);
   records.push(read.record);
   if (read.record.status === "fail") return { records, failed: true };
 
@@ -291,7 +320,7 @@ async function runEffectStep(
   // 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);
+    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.
@@ -314,6 +343,7 @@ async function runEffectStep(
     phaseName,
     activities,
     profiles,
+    resultsById,
     signal,
   );
   records.push(wrote.record);
@@ -325,6 +355,7 @@ 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
@@ -343,7 +374,7 @@ async function runPhase(
     }
     const steps = phase.steps.filter(isActivity);
     const records = (
-      await Promise.all(steps.map((s) => runStep(s, phase.name, activities, profiles, signal)))
+      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;
@@ -365,7 +396,7 @@ async function runPhase(
   for (let i = 0; i < steps.length; i++) {
     const step = steps[i];
     if (isEffect(step)) {
-      const { records: effRecords, failed } = await runEffectStep(step, phase.name, activities, profiles, signal);
+      const { records: effRecords, failed } = await runEffectStep(step, phase.name, activities, profiles, resultsById, signal);
       records.push(...effRecords);
       if (failed) {
         skipRemaining(i + 1);
@@ -373,7 +404,7 @@ async function runPhase(
       }
       continue;
     }
-    const { record } = await runStep(step, phase.name, activities, profiles, signal);
+    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.
@@ -416,10 +447,15 @@ export async function runOpLocally(
   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);
@@ -429,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;
+}