@intentius/chant 0.1.14 → 0.1.16

package/src/op/builders.ts

@@ -60,36 +60,72 @@ export function gate(
 
 // ── Pre-built activity shortcuts ──────────────────────────────────────────────
 
+/**
+ * Pull an optional `profile` override out of an opts bag, returning the
+ * remaining keys (which become activity args) separately.
+ *
+ * Without this, a `profile` passed in opts would spread into the activity's
+ * **args** rather than set the step's `profile` — a silent no-op on the step's
+ * timeout. The activity then runs under the default profile, so a step the
+ * author tagged `longInfra` (20m) would still get the 5m default. Routing it
+ * here lets every shortcut accept a `profile` override that actually takes.
+ */
+function takeProfile(
+  opts: Record<string, unknown> | undefined,
+): { args: Record<string, unknown>; profile?: ActivityStep["profile"] } {
+  if (!opts) return { args: {} };
+  const { profile, ...args } = opts as { profile?: ActivityStep["profile"] } & Record<string, unknown>;
+  return { args, profile };
+}
+
 /** Run `npm run build` (or `chant build`) in the given project directory. */
-export const build = (path: string, opts?: Record<string, unknown>): ActivityStep =>
-  activity("chantBuild", { path, ...opts });
+export const build = (path: string, opts?: Record<string, unknown>): ActivityStep => {
+  const { args, profile } = takeProfile(opts);
+  return activity("chantBuild", { path, ...args }, profile);
+};
 
-/** Run `kubectl apply -f <manifest>`. Uses `longInfra` profile. */
-export const kubectlApply = (manifest: string, opts?: Record<string, unknown>): ActivityStep =>
-  activity("kubectlApply", { manifest, ...opts }, "longInfra");
+/** Run `kubectl apply -f <manifest>`. Defaults to the `longInfra` profile (override via `opts.profile`). */
+export const kubectlApply = (manifest: string, opts?: Record<string, unknown>): ActivityStep => {
+  const { args, profile } = takeProfile(opts);
+  return activity("kubectlApply", { manifest, ...args }, profile ?? "longInfra");
+};
 
-/** Run `helm upgrade --install`. Uses `longInfra` profile. */
+/** Run `helm upgrade --install`. Defaults to the `longInfra` profile (override via `opts.profile`). */
 export const helmInstall = (
   name: string,
   chart: string,
-  opts?: { values?: string; namespace?: string; [k: string]: unknown },
-): ActivityStep => activity("helmInstall", { name, chart, ...opts }, "longInfra");
+  opts?: { values?: string; namespace?: string; profile?: ActivityStep["profile"]; [k: string]: unknown },
+): ActivityStep => {
+  const { args, profile } = takeProfile(opts);
+  return activity("helmInstall", { name, chart, ...args }, profile ?? "longInfra");
+};
 
-/** Poll for stack readiness (kubectl rollout, CloudFormation complete, etc). Uses `k8sWait` profile. */
-export const waitForStack = (name: string, opts?: Record<string, unknown>): ActivityStep =>
-  activity("waitForStack", { name, ...opts }, "k8sWait");
+/** Poll for stack readiness (kubectl rollout, CloudFormation complete, etc). Defaults to the `k8sWait` profile (override via `opts.profile`). */
+export const waitForStack = (name: string, opts?: Record<string, unknown>): ActivityStep => {
+  const { args, profile } = takeProfile(opts);
+  return activity("waitForStack", { name, ...args }, profile ?? "k8sWait");
+};
 
-/** Trigger and wait for a GitLab CI pipeline to complete. Uses `longInfra` profile. */
-export const gitlabPipeline = (name: string, opts?: Record<string, unknown>): ActivityStep =>
-  activity("gitlabPipeline", { name, ...opts }, "longInfra");
+/** Trigger and wait for a GitLab CI pipeline to complete. Defaults to the `longInfra` profile (override via `opts.profile`). */
+export const gitlabPipeline = (name: string, opts?: Record<string, unknown>): ActivityStep => {
+  const { args, profile } = takeProfile(opts);
+  return activity("gitlabPipeline", { name, ...args }, profile ?? "longInfra");
+};
 
-/** Take a chant state snapshot for the given environment. */
-export const stateSnapshot = (env: string): ActivityStep =>
-  activity("stateSnapshot", { env });
+/** Take a chant lifecycle snapshot for the given environment. */
+export const lifecycleSnapshot = (env: string): ActivityStep =>
+  activity("lifecycleSnapshot", { env });
 
-/** Run an arbitrary shell command. */
-export const shell = (cmd: string, opts?: { env?: Record<string, string> }): ActivityStep =>
-  activity("shellCmd", { cmd, ...opts });
+/**
+ * Run an arbitrary shell command. Tag long-running commands with a `profile`
+ * (e.g. `longInfra` for a multi-GB image push) so they get the right
+ * start-to-close timeout under both the local executor and Temporal.
+ */
+export const shell = (
+  cmd: string,
+  opts?: { env?: Record<string, string>; profile?: ActivityStep["profile"] },
+): ActivityStep =>
+  activity("shellCmd", { cmd, ...(opts?.env ? { env: opts.env } : {}) }, opts?.profile);
 
 /** Run `chant teardown` in the given project directory. Uses `longInfra` profile. */
 export const teardown = (path: string): ActivityStep =>

package/src/op/index.ts

@@ -1,6 +1,11 @@
 export { Op, phase, activity, gate, build, kubectlApply, helmInstall, waitForStack,
-         gitlabPipeline, stateSnapshot, shell, teardown } from "./builders";
+         gitlabPipeline, lifecycleSnapshot, shell, teardown } from "./builders";
 export { OpResource } from "./resource";
 export type { OpConfig, PhaseDefinition, StepDefinition, ActivityStep, GateStep } from "./types";
 export { discoverOps } from "./discover";
 export type { DiscoveredOp, OpDiscoveryResult } from "./discover";
+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";

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

@@ -0,0 +1,263 @@
+import { describe, test, expect, vi } from "vitest";
+import type { OpConfig } from "./types";
+import type { ActivityFn, ActivityProfile } from "./activity-registry";
+import {
+  runOpLocally,
+  parseDuration,
+  findGate,
+  LocalGateUnsupportedError,
+  OpRunFailure,
+} from "./local-executor";
+
+// Fast profiles so retry/timeout tests run in milliseconds.
+const PROFILES: Record<string, ActivityProfile> = {
+  fastIdempotent: {
+    startToCloseTimeout: "5m",
+    retry: { maximumAttempts: 3, initialInterval: "5ms", backoffCoefficient: 2 },
+  },
+  quickTimeout: {
+    startToCloseTimeout: "50ms",
+    retry: { maximumAttempts: 2, initialInterval: "1ms", backoffCoefficient: 1 },
+  },
+  single: { startToCloseTimeout: "5m", retry: { maximumAttempts: 1 } },
+};
+
+function op(partial: Partial<OpConfig>): OpConfig {
+  return { name: "test-op", overview: "", phases: [], ...partial };
+}
+
+describe("parseDuration", () => {
+  test("parses single and compound durations", () => {
+    expect(parseDuration("5m")).toBe(300_000);
+    expect(parseDuration("30s")).toBe(30_000);
+    expect(parseDuration("100ms")).toBe(100);
+    expect(parseDuration("1h30m")).toBe(5_400_000);
+    expect(parseDuration("48h")).toBe(172_800_000);
+  });
+  test("throws on garbage", () => {
+    expect(() => parseDuration("soon")).toThrow(/unparseable/);
+  });
+});
+
+describe("runOpLocally — sequencing", () => {
+  test("runs phases and steps in declared order", async () => {
+    const order: string[] = [];
+    const make = (tag: string): ActivityFn => async () => { order.push(tag); };
+    const activities = new Map<string, ActivityFn>([
+      ["a", make("a")], ["b", make("b")], ["c", make("c")],
+    ]);
+    const config = op({
+      phases: [
+        { name: "P1", steps: [{ kind: "activity", fn: "a" }] },
+        { name: "P2", steps: [{ kind: "activity", fn: "b" }] },
+        { name: "P3", steps: [{ kind: "activity", fn: "c" }] },
+      ],
+    });
+    const result = await runOpLocally(config, activities, PROFILES);
+    expect(order).toEqual(["a", "b", "c"]);
+    expect(result.ok).toBe(true);
+    expect(result.records.map((r) => r.fn)).toEqual(["a", "b", "c"]);
+  });
+
+  test("parallel phase runs steps concurrently (~max, not sum)", async () => {
+    const slow = (ms: number): ActivityFn => async () => { await new Promise((r) => setTimeout(r, ms)); };
+    const activities = new Map<string, ActivityFn>([["s1", slow(60)], ["s2", slow(60)]]);
+    const config = op({
+      phases: [{ name: "P", parallel: true, steps: [
+        { kind: "activity", fn: "s1" }, { kind: "activity", fn: "s2" },
+      ] }],
+    });
+    const start = Date.now();
+    await runOpLocally(config, activities, PROFILES);
+    const elapsed = Date.now() - start;
+    expect(elapsed).toBeLessThan(110); // ~60 (max), well under 120 (sum)
+  });
+});
+
+describe("runOpLocally — retry + timeout", () => {
+  test("retries until success", async () => {
+    let calls = 0;
+    const flaky: ActivityFn = async () => {
+      calls++;
+      if (calls < 3) throw new Error("transient");
+      return "ok";
+    };
+    const config = op({ phases: [{ name: "P", steps: [{ kind: "activity", fn: "flaky" }] }] });
+    const result = await runOpLocally(config, new Map([["flaky", flaky]]), PROFILES);
+    expect(calls).toBe(3);
+    expect(result.records[0].status).toBe("ok");
+  });
+
+  test("times out a slow attempt and retries", async () => {
+    let calls = 0;
+    const slow: ActivityFn = async () => {
+      calls++;
+      // First attempt hangs past the 50ms timeout; second resolves fast.
+      await new Promise((r) => setTimeout(r, calls === 1 ? 200 : 1));
+    };
+    // Map the default profile to quickTimeout (50ms timeout, 2 attempts).
+    const config = op({
+      phases: [{ name: "P", steps: [{ kind: "activity", fn: "slow" }] }],
+    });
+    const profiles = { ...PROFILES, fastIdempotent: PROFILES.quickTimeout };
+    const result = await runOpLocally(config, new Map([["slow", slow]]), profiles);
+    expect(calls).toBe(2);
+    expect(result.records[0].status).toBe("ok");
+  });
+
+  test("rejects after exhausting retries", async () => {
+    const always: ActivityFn = async () => { throw new Error("nope"); };
+    const config = op({ phases: [{ name: "P", steps: [{ kind: "activity", fn: "always" }] }] });
+    await expect(runOpLocally(config, new Map([["always", always]]), PROFILES)).rejects.toBeInstanceOf(OpRunFailure);
+  });
+
+  test("honors a step's non-default profile timeout (not the default)", async () => {
+    // The default profile would time out at 50ms; the step is tagged longInfra,
+    // which gives it room. Guards the bug where a profiled step silently got the
+    // default cap (local vs --temporal disagreement).
+    const slow: ActivityFn = async () => { await new Promise((r) => setTimeout(r, 150)); return "done"; };
+    const profiles = {
+      fastIdempotent: { startToCloseTimeout: "50ms", retry: { maximumAttempts: 1 } },
+      longInfra: { startToCloseTimeout: "5m", retry: { maximumAttempts: 1 } },
+    };
+    const config = op({
+      phases: [{ name: "P", steps: [{ kind: "activity", fn: "slow", profile: "longInfra" }] }],
+    });
+    const result = await runOpLocally(config, new Map([["slow", slow]]), profiles);
+    expect(result.records[0].status).toBe("ok");
+  });
+});
+
+describe("runOpLocally — cancellation", () => {
+  test("aborts the activity's signal on timeout", async () => {
+    let abortedSeen = false;
+    const hang: ActivityFn = async (_args, signal) => {
+      await new Promise<void>((resolve) => {
+        signal?.addEventListener("abort", () => { abortedSeen = true; resolve(); });
+        setTimeout(resolve, 5000); // would hang far past the timeout if not aborted
+      });
+      throw new Error("abandoned");
+    };
+    const config = op({ phases: [{ name: "P", steps: [{ kind: "activity", fn: "hang" }] }] });
+    const profiles = { ...PROFILES, fastIdempotent: { startToCloseTimeout: "30ms", retry: { maximumAttempts: 1 } } };
+    await expect(runOpLocally(config, new Map([["hang", hang]]), profiles)).rejects.toBeInstanceOf(OpRunFailure);
+    expect(abortedSeen).toBe(true);
+  });
+
+  test("stops retrying once the run signal aborts (Ctrl-C)", async () => {
+    const controller = new AbortController();
+    let calls = 0;
+    const failOnAbort: ActivityFn = async () => {
+      calls++;
+      controller.abort(); // simulate SIGINT mid-attempt
+      throw new Error("boom");
+    };
+    const config = op({ phases: [{ name: "P", steps: [{ kind: "activity", fn: "failOnAbort" }] }] });
+    // fastIdempotent permits 3 attempts; the abort must cut it to 1.
+    await expect(
+      runOpLocally(config, new Map([["failOnAbort", failOnAbort]]), PROFILES, controller.signal),
+    ).rejects.toBeInstanceOf(OpRunFailure);
+    expect(calls).toBe(1);
+  });
+
+  test("skips onFailure compensation when aborted", async () => {
+    const controller = new AbortController();
+    const comp = vi.fn();
+    const main: ActivityFn = async () => { controller.abort(); throw new Error("boom"); };
+    const config = op({
+      phases: [{ name: "Main", steps: [{ kind: "activity", fn: "main" }] }],
+      onFailure: [{ name: "C", steps: [{ kind: "activity", fn: "comp" }] }],
+    });
+    const activities = new Map<string, ActivityFn>([["main", main], ["comp", async () => { comp(); }]]);
+    await expect(runOpLocally(config, activities, PROFILES, controller.signal)).rejects.toBeInstanceOf(OpRunFailure);
+    expect(comp).not.toHaveBeenCalled();
+  });
+});
+
+describe("runOpLocally — non-retryable errors", () => {
+  test("fails immediately on a non-retryable error type", async () => {
+    let calls = 0;
+    const fatal: ActivityFn = async () => {
+      calls++;
+      const e = new Error("bad manifest");
+      e.name = "ValidationError";
+      throw e;
+    };
+    const profiles = {
+      ...PROFILES,
+      fastIdempotent: {
+        startToCloseTimeout: "5m",
+        retry: { maximumAttempts: 3, initialInterval: "1ms", nonRetryableErrorTypes: ["ValidationError"] },
+      },
+    };
+    const config = op({ phases: [{ name: "P", steps: [{ kind: "activity", fn: "fatal" }] }] });
+    await expect(runOpLocally(config, new Map([["fatal", fatal]]), profiles)).rejects.toBeInstanceOf(OpRunFailure);
+    expect(calls).toBe(1);
+  });
+});
+
+describe("runOpLocally — outcomeAttribute", () => {
+  test("captures a dot-path from the return value", async () => {
+    const diff: ActivityFn = async () => ({ output: "...", exitCode: 0, drifted: false });
+    const config = op({
+      phases: [{ name: "Check", steps: [
+        { kind: "activity", fn: "lifecycleDiff", outcomeAttribute: { name: "Drift", from: "drifted" } },
+      ] }],
+    });
+    const result = await runOpLocally(config, new Map([["lifecycleDiff", diff]]), PROFILES);
+    expect(result.records[0].outcome).toEqual({ name: "Drift", value: false });
+  });
+});
+
+describe("runOpLocally — onFailure", () => {
+  test("runs compensation phases in reverse and rejects with ok=false", async () => {
+    const order: string[] = [];
+    const make = (tag: string, fail = false): ActivityFn => async () => {
+      order.push(tag);
+      if (fail) throw new Error("boom");
+    };
+    const activities = new Map<string, ActivityFn>([
+      ["main", make("main", true)],
+      ["comp1", make("comp1")],
+      ["comp2", make("comp2")],
+    ]);
+    const config = op({
+      phases: [{ name: "Main", steps: [{ kind: "activity", fn: "main" }] }],
+      onFailure: [
+        { name: "C1", steps: [{ kind: "activity", fn: "comp1" }] },
+        { name: "C2", steps: [{ kind: "activity", fn: "comp2" }] },
+      ],
+    });
+    const err = await runOpLocally(config, activities, PROFILES).catch((e) => e);
+    expect(err).toBeInstanceOf(OpRunFailure);
+    expect(err.result.ok).toBe(false);
+    // Main fails (3 attempts), then compensation runs in reverse: comp2, comp1.
+    expect(order).toEqual(["main", "main", "main", "comp2", "comp1"]);
+  });
+});
+
+describe("runOpLocally — gate rejection", () => {
+  test("rejects before running any step when a gate is present", async () => {
+    const ran = vi.fn();
+    const activities = new Map<string, ActivityFn>([["a", async () => { ran(); }]]);
+    const config = op({
+      phases: [
+        { name: "P", steps: [
+          { kind: "activity", fn: "a" },
+          { kind: "gate", signalName: "approve-prod" },
+        ] },
+      ],
+    });
+    await expect(runOpLocally(config, activities, PROFILES)).rejects.toBeInstanceOf(LocalGateUnsupportedError);
+    await expect(runOpLocally(config, activities, PROFILES)).rejects.toThrow(/--temporal/);
+    expect(ran).not.toHaveBeenCalled();
+  });
+
+  test("findGate locates a gate in phases or onFailure", () => {
+    expect(findGate(op({ phases: [{ name: "P", steps: [{ kind: "activity", fn: "a" }] }] }))).toBeUndefined();
+    const gated = findGate(op({
+      phases: [{ name: "P", steps: [{ kind: "gate", signalName: "g" }] }],
+    }));
+    expect(gated?.signalName).toBe("g");
+  });
+});

package/src/op/local-executor.ts

@@ -0,0 +1,300 @@
+/**
+ * Local Op executor — runs an Op's phases in-process with no Temporal worker.
+ *
+ * A first-class peer to Temporal mode for dev loops, CI, and drift/observation
+ * Ops. Provides phase sequencing, parallel phases, per-step retry + timeout via
+ * activity profiles, `outcomeAttribute` capture, and `onFailure` compensation.
+ * Gates and schedules are unsupported and rejected before any phase runs.
+ *
+ * The executor is deliberately decoupled from the Temporal lexicon: activity
+ * implementations and profiles are passed in (loaded dynamically by the CLI),
+ * so core never statically depends on `@intentius/chant-lexicon-temporal`.
+ */
+
+import type { OpConfig, PhaseDefinition, ActivityStep, GateStep, StepDefinition } from "./types";
+import { resolveActivity, type ActivityFn, type ActivityProfile } from "./activity-registry";
+
+// ── Records ─────────────────────────────────────────────────────────────────
+
+export interface StepRecord {
+  phase: string;
+  fn: string;
+  args: Record<string, unknown>;
+  status: "ok" | "fail" | "skipped";
+  durationMs: number;
+  outcome?: { name: string; value: unknown };
+  error?: string;
+}
+
+export interface OpRunResult {
+  op: string;
+  records: StepRecord[];
+  totalMs: number;
+  ok: boolean;
+}
+
+// ── Errors ────────────────────────────────────────────────────────────────��─
+
+/** Thrown when an Op contains a gate (or schedule) that local mode cannot run. */
+export class LocalGateUnsupportedError extends Error {
+  constructor(public readonly signalName: string) {
+    super(
+      `gate "${signalName}" is not supported in local mode — gates and schedules ` +
+        `need a durable runtime. Re-run with --temporal.`,
+    );
+    this.name = "LocalGateUnsupportedError";
+  }
+}
+
+/** Thrown on terminal Op failure; carries the partial run result for rendering. */
+export class OpRunFailure extends Error {
+  constructor(public readonly result: OpRunResult) {
+    super(`Op "${result.op}" failed`);
+    this.name = "OpRunFailure";
+  }
+}
+
+/** Internal: a phase aborted; carries records produced before the abort. */
+class PhaseFailure extends Error {
+  constructor(public readonly records: StepRecord[]) {
+    super("phase failed");
+    this.name = "PhaseFailure";
+  }
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────��─
+
+const DEFAULT_PROFILE = "fastIdempotent";
+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";
+
+/** Parse a Temporal duration string ("5m", "30s", "1h30m", "100ms") to ms. */
+export function parseDuration(s: string): number {
+  const units: Record<string, number> = { ms: 1, s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000 };
+  let total = 0;
+  let matched = false;
+  for (const m of s.matchAll(/(\d+)(ms|s|m|h|d)/g)) {
+    total += Number(m[1]) * units[m[2]];
+    matched = true;
+  }
+  if (!matched) throw new Error(`unparseable duration: "${s}"`);
+  return total;
+}
+
+/** Resolve a dot-path into a value; returns the whole value when path is absent. */
+function resolvePath(value: unknown, path?: string): unknown {
+  if (!path) return value;
+  return path.split(".").reduce<unknown>(
+    (acc, key) => (acc == null ? acc : (acc as Record<string, unknown>)[key]),
+    value,
+  );
+}
+
+/** Find the first gate step anywhere in the Op (phases + onFailure), 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;
+  }
+  return undefined;
+}
+
+const sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));
+
+/**
+ * Race a single activity attempt against its start-to-close timeout. On timeout
+ * (or when the run-level `parentSignal` aborts, e.g. Ctrl-C) the attempt's
+ * `AbortSignal` fires so the activity can kill its child process, then the call
+ * rejects so the retry loop can react. The losing promise is swallowed to keep
+ * its eventual rejection from surfacing as an unhandled rejection.
+ */
+async function callWithTimeout(
+  fn: ActivityFn,
+  args: Record<string, unknown>,
+  timeoutMs: number,
+  parentSignal?: AbortSignal,
+): Promise<unknown> {
+  const controller = new AbortController();
+  const onParentAbort = () => controller.abort();
+  if (parentSignal) {
+    if (parentSignal.aborted) controller.abort();
+    else parentSignal.addEventListener("abort", onParentAbort, { once: true });
+  }
+
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timeout = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => {
+      controller.abort();
+      reject(new Error(`activity timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+  });
+
+  const call = Promise.resolve(fn(args, controller.signal));
+  call.catch(() => {}); // losing-race rejection must not become unhandled
+
+  try {
+    return await Promise.race([call, timeout]);
+  } finally {
+    if (timer) clearTimeout(timer);
+    if (parentSignal) parentSignal.removeEventListener("abort", onParentAbort);
+  }
+}
+
+// ── Step + phase execution ────────────────────────────────────────────────��─
+
+/** Run one activity step with retry + timeout. Never throws — returns a record. */
+async function runStep(
+  step: ActivityStep,
+  phaseName: string,
+  activities: Map<string, ActivityFn>,
+  profiles: Record<string, ActivityProfile>,
+  signal?: AbortSignal,
+): Promise<StepRecord> {
+  const args = step.args ?? {};
+  const base = { phase: phaseName, fn: step.fn, args };
+  const start = Date.now();
+
+  let fn: ActivityFn;
+  try {
+    fn = resolveActivity(activities, step.fn);
+  } catch (err) {
+    return { ...base, status: "fail", durationMs: 0, error: errMessage(err) };
+  }
+
+  const profile = profiles[step.profile ?? DEFAULT_PROFILE] ?? {};
+  const timeoutMs = profile.startToCloseTimeout
+    ? parseDuration(profile.startToCloseTimeout)
+    : FALLBACK_TIMEOUT_MS;
+  const maxAttempts =
+    profile.retry?.maximumAttempts && profile.retry.maximumAttempts > 0
+      ? profile.retry.maximumAttempts
+      : 1;
+  const initial = profile.retry?.initialInterval ? parseDuration(profile.retry.initialInterval) : 0;
+  const backoff = profile.retry?.backoffCoefficient ?? 1;
+  const maxInterval = profile.retry?.maximumInterval
+    ? parseDuration(profile.retry.maximumInterval)
+    : Infinity;
+  const nonRetryable = profile.retry?.nonRetryableErrorTypes ?? [];
+
+  let lastErr: unknown;
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      const result = await callWithTimeout(fn, args, timeoutMs, signal);
+      const record: StepRecord = { ...base, status: "ok", durationMs: Date.now() - start };
+      if (step.outcomeAttribute) {
+        record.outcome = {
+          name: step.outcomeAttribute.name,
+          value: resolvePath(result, step.outcomeAttribute.from),
+        };
+      }
+      return record;
+    } catch (err) {
+      lastErr = err;
+      // Stop retrying on abort (Ctrl-C / timeout cascade) or a non-retryable error.
+      const fatal =
+        signal?.aborted || (err instanceof Error && nonRetryable.includes(err.name));
+      if (!fatal && attempt < maxAttempts) {
+        const wait = Math.min(initial * Math.pow(backoff, attempt - 1), maxInterval);
+        if (wait > 0) await sleep(wait);
+        continue;
+      }
+      break;
+    }
+  }
+  return { ...base, status: "fail", durationMs: Date.now() - start, error: errMessage(lastErr) };
+}
+
+/** Run a phase. Throws PhaseFailure (with records so far) if any step fails. */
+async function runPhase(
+  phase: PhaseDefinition,
+  activities: Map<string, ActivityFn>,
+  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);
+  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)),
+    );
+    if (records.some((r) => r.status === "fail")) throw new PhaseFailure(records);
+    return records;
+  }
+
+  const records: StepRecord[] = [];
+  for (let i = 0; i < steps.length; i++) {
+    const record = await runStep(steps[i], 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,
+        });
+      }
+      throw new PhaseFailure(records);
+    }
+  }
+  return records;
+}
+
+// ── Public API ────────────────────────────────────────────────────────────��─
+
+/**
+ * Execute an Op locally. Resolves with the run result on success; rejects with
+ * `OpRunFailure` (carrying the partial result) on terminal failure, after
+ * running any `onFailure` phases in reverse order. Throws
+ * `LocalGateUnsupportedError` up front if the Op contains a gate.
+ */
+export async function runOpLocally(
+  config: OpConfig,
+  activities: Map<string, ActivityFn>,
+  profiles: Record<string, ActivityProfile>,
+  signal?: AbortSignal,
+): Promise<OpRunResult> {
+  const gate = findGate(config);
+  if (gate) throw new LocalGateUnsupportedError(gate.signalName);
+
+  const records: StepRecord[] = [];
+  const start = Date.now();
+
+  try {
+    for (const phase of config.phases) {
+      if (signal?.aborted) throw new PhaseFailure([]);
+      records.push(...(await runPhase(phase, activities, profiles, signal)));
+    }
+  } catch (err) {
+    if (err instanceof PhaseFailure) records.push(...err.records);
+
+    // 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.
+    if (!signal?.aborted) {
+      for (const phase of [...(config.onFailure ?? [])].reverse()) {
+        try {
+          records.push(...(await runPhase(phase, activities, profiles, signal)));
+        } catch (compErr) {
+          if (compErr instanceof PhaseFailure) records.push(...compErr.records);
+        }
+      }
+    }
+
+    throw new OpRunFailure({ op: config.name, records, totalMs: Date.now() - start, ok: false });
+  }
+
+  return { op: config.name, records, totalMs: Date.now() - start, ok: true };
+}
+
+function errMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}