@intentius/chant 0.1.14 → 0.1.15

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

@@ -0,0 +1,247 @@
+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);
+  });
+});
+
+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);
+}

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

@@ -0,0 +1,54 @@
+import { describe, test, expect } from "vitest";
+import type { OpRunResult } from "./local-executor";
+import { renderHuman, renderJson } from "./local-output";
+
+const RESULT: OpRunResult = {
+  op: "hello",
+  totalMs: 100,
+  ok: true,
+  records: [
+    { phase: "Greet", fn: "shellCmd", args: { cmd: "echo hello from chant" }, status: "ok", durationMs: 42 },
+    { phase: "Check", fn: "lifecycleDiff", args: { env: "prod" }, status: "ok", durationMs: 1200,
+      outcome: { name: "Drift", value: false } },
+  ],
+};
+
+describe("renderHuman", () => {
+  test("renders phase banners, step lines, outcomes, and a summary", () => {
+    const lines: string[] = [];
+    renderHuman(RESULT, (l) => lines.push(l));
+    const out = lines.join("\n");
+    expect(out).toContain("[phase] Greet");
+    expect(out).toContain("✓ shellCmd(cmd=echo hello from chant)   42ms");
+    expect(out).toContain("[phase] Check");
+    expect(out).toContain("[outcome] Drift=false");
+    expect(out).toContain("✓ lifecycleDiff(env=prod)   1.2s");
+    expect(out).toContain('Op "hello" completed in 0.1s');
+  });
+
+  test("renders failures with ✗ and the error", () => {
+    const failed: OpRunResult = {
+      op: "deploy", totalMs: 50, ok: false,
+      records: [{ phase: "Apply", fn: "kubectlApply", args: { manifest: "x.yaml" }, status: "fail", durationMs: 10, error: "boom" }],
+    };
+    const lines: string[] = [];
+    renderHuman(failed, (l) => lines.push(l));
+    const out = lines.join("\n");
+    expect(out).toContain("✗ kubectlApply(manifest=x.yaml)");
+    expect(out).toContain("boom");
+    expect(out).toContain('Op "deploy" failed');
+  });
+});
+
+describe("renderJson", () => {
+  test("prints valid JSON parseable back to OpRunResult", () => {
+    const lines: string[] = [];
+    renderJson(RESULT, (l) => lines.push(l));
+    expect(lines).toHaveLength(1);
+    const parsed = JSON.parse(lines[0]) as OpRunResult;
+    expect(parsed.op).toBe("hello");
+    expect(parsed.ok).toBe(true);
+    expect(parsed.records).toHaveLength(2);
+    expect(parsed.records[1].outcome).toEqual({ name: "Drift", value: false });
+  });
+});

package/src/op/local-output.ts

@@ -0,0 +1,63 @@
+/**
+ * Renderers for local Op execution. Both consume the same `OpRunResult`:
+ * `renderHuman` is the default (logs to stderr), `renderJson` prints the
+ * machine-readable record array to stdout and nothing else.
+ */
+
+import type { OpRunResult, StepRecord } from "./local-executor";
+
+type Writer = (line: string) => void;
+
+const stderr: Writer = (line) => process.stderr.write(line + "\n");
+const stdout: Writer = (line) => process.stdout.write(line + "\n");
+
+function formatArgs(args: Record<string, unknown>): string {
+  return Object.entries(args)
+    .map(([k, v]) => `${k}=${typeof v === "string" ? v : JSON.stringify(v)}`)
+    .join(", ");
+}
+
+function formatDuration(ms: number): string {
+  return ms < 1000 ? `${ms}ms` : `${(ms / 1000).toFixed(1)}s`;
+}
+
+/**
+ * Render a run result as human-readable progress. Defaults to stderr so stdout
+ * stays clean for piping (the `--json` renderer owns stdout).
+ */
+export function renderHuman(result: OpRunResult, write: Writer = stderr): void {
+  let currentPhase: string | undefined;
+  for (const record of result.records) {
+    if (record.phase !== currentPhase) {
+      currentPhase = record.phase;
+      write(`[phase] ${currentPhase}`);
+    }
+    const mark = record.status === "ok" ? "✓" : record.status === "fail" ? "✗" : "•";
+    const call = `${record.fn}(${formatArgs(record.args)})`;
+    if (record.status === "skipped") {
+      write(`  ${mark} ${call}   skipped`);
+    } else {
+      write(`  ${mark} ${call}   ${formatDuration(record.durationMs)}`);
+    }
+    if (record.outcome) {
+      write(`    [outcome] ${record.outcome.name}=${String(record.outcome.value)}`);
+    }
+    if (record.error) {
+      write(`    ${record.error}`);
+    }
+  }
+
+  const total = `${(result.totalMs / 1000).toFixed(1)}s`;
+  if (result.ok) {
+    write(`Op "${result.op}" completed in ${total}`);
+  } else {
+    write(`Op "${result.op}" failed after ${total}`);
+  }
+}
+
+/** Render a run result as JSON on stdout (and nothing else on stdout). */
+export function renderJson(result: OpRunResult, write: Writer = stdout): void {
+  write(JSON.stringify(result));
+}
+
+export type { OpRunResult, StepRecord };

package/src/op/op.test.ts

@@ -4,7 +4,7 @@
 
 import { describe, expect, it } from "vitest";
 import { Op, phase, activity, gate, build, kubectlApply, helmInstall,
-         waitForStack, gitlabPipeline, stateSnapshot, shell, teardown } from "./builders";
+         waitForStack, gitlabPipeline, lifecycleSnapshot, shell, teardown } from "./builders";
 import { DECLARABLE_MARKER, type Declarable } from "../declarable";
 
 // ── Op() ──────────────────────────────────────────────────────────────────────
@@ -177,9 +177,9 @@ describe("pre-built shortcuts", () => {
     expect(a.profile).toBe("longInfra");
   });
 
-  it("stateSnapshot() produces stateSnapshot activity with env arg", () => {
-    const a = stateSnapshot("prod");
-    expect(a.fn).toBe("stateSnapshot");
+  it("lifecycleSnapshot() produces lifecycleSnapshot activity with env arg", () => {
+    const a = lifecycleSnapshot("prod");
+    expect(a.fn).toBe("lifecycleSnapshot");
     expect(a.args?.env).toBe("prod");
     expect("profile" in a).toBe(false);
   });