@intentius/chant-lexicon-temporal 0.1.12 → 0.1.15

package/src/op/activities/{state.ts → lifecycle.ts}

@@ -3,32 +3,32 @@ import { promisify } from "node:util";
 
 const execAsync = promisify(exec);
 
-export interface StateSnapshotArgs {
+export interface LifecycleSnapshotArgs {
   /** Environment name (e.g. "dev", "staging", "prod"). */
   env: string;
 }
 
 /**
- * Take a chant state snapshot for the given environment.
+ * Take a chant lifecycle snapshot for the given environment.
  * Uses fastIdempotent profile — 5m timeout, 3 retries.
  */
-export async function stateSnapshot(args: StateSnapshotArgs): Promise<void> {
-  const { stdout, stderr } = await execAsync(`chant state snapshot ${args.env}`);
+export async function lifecycleSnapshot(args: LifecycleSnapshotArgs, signal?: AbortSignal): Promise<void> {
+  const { stdout, stderr } = await execAsync(`chant lifecycle snapshot ${args.env}`, { signal });
   if (stdout) console.log(stdout);
   if (stderr) console.error(stderr);
 }
 
-export interface StateDiffArgs {
+export interface LifecycleDiffArgs {
   /** Environment name (e.g. "dev", "staging", "prod"). */
   env: string;
   /**
-   * When true, run `chant state diff <env> --live` (queries cloud APIs).
+   * When true, run `chant lifecycle diff <env> --live` (queries cloud APIs).
    * When false (default), run digest-only diff against the last snapshot.
    */
   live?: boolean;
 }
 
-export interface StateDiffResult {
+export interface LifecycleDiffResult {
   /** Combined stdout + stderr from the chant command. */
   output: string;
   /** Process exit code (0 = success). */
@@ -36,13 +36,13 @@ export interface StateDiffResult {
   /**
    * True when the diff output contains any drift indicators
    * (MISSING / ORPHAN / DRIFTED / DISAPPEARED section headers from
-   * `chant state diff --live`).
+   * `chant lifecycle diff --live`).
    */
   drifted: boolean;
 }
 
 /**
- * Section headers emitted by `chant state diff --live` that indicate a
+ * Section headers emitted by `chant lifecycle diff --live` that indicate a
  * non-empty drift category. See packages/core/src/cli/handlers/state.ts.
  */
 const DRIFT_HEADERS = [
@@ -60,7 +60,7 @@ function detectDrift(output: string): boolean {
 }
 
 /**
- * Run `chant state diff <env>` and return the output + structured drift
+ * Run `chant lifecycle diff <env>` and return the output + structured drift
  * flag. Read-only; intended for use inside watch/observation workflows.
  * Uses fastIdempotent profile.
  *
@@ -69,10 +69,10 @@ function detectDrift(output: string): boolean {
  * cli/state.mdx. Pair with `outcomeAttribute: { name: "Drift", from: "drifted" }`
  * on a WatchOp activity step to surface drift as a workflow search attribute.
  */
-export async function stateDiff(args: StateDiffArgs): Promise<StateDiffResult> {
+export async function lifecycleDiff(args: LifecycleDiffArgs, signal?: AbortSignal): Promise<LifecycleDiffResult> {
   const liveFlag = args.live ? " --live" : "";
   try {
-    const { stdout, stderr } = await execAsync(`chant state diff ${args.env}${liveFlag}`);
+    const { stdout, stderr } = await execAsync(`chant lifecycle diff ${args.env}${liveFlag}`, { signal });
     const output = `${stdout}${stderr}`.trim();
     if (output) console.log(output);
     return { output, exitCode: 0, drifted: detectDrift(output) };

package/src/op/activities/reconcile.test.ts

@@ -0,0 +1,59 @@
+import { describe, test, expect } from "vitest";
+import { reconcilePr, reconcileSummary, reconcileBranchName, entriesFromPlan } from "./reconcile";
+
+const entries = [
+  { name: "bucket", action: "adopt", type: "AWS::S3::Bucket" },
+  { name: "queue", action: "update", type: "AWS::SQS::Queue" },
+];
+
+describe("reconcileBranchName (#122)", () => {
+  test("deterministic, slugified per env", () => {
+    expect(reconcileBranchName("prod")).toBe("chant/reconcile-prod");
+    expect(reconcileBranchName("us-east/1")).toBe("chant/reconcile-us-east-1");
+  });
+});
+
+describe("reconcileSummary (#122)", () => {
+  test("summarizes which entries triggered the reconcile", () => {
+    const body = reconcileSummary("prod", entries);
+    expect(body).toContain("live environment `prod`");
+    expect(body).toContain("| bucket | adopt | AWS::S3::Bucket |");
+    expect(body).toContain("| queue | update | AWS::SQS::Queue |");
+  });
+
+  test("handles an empty entry set", () => {
+    expect(reconcileSummary("prod", [])).toContain("_(none)_");
+  });
+});
+
+describe("entriesFromPlan (#123)", () => {
+  test("maps a ChangeSet, dropping noop entries", () => {
+    const plan = JSON.stringify({
+      env: "prod",
+      entries: [
+        { name: "a", action: "create", type: "T1", evidence: {}, ownership: "unknown" },
+        { name: "b", action: "noop", type: "T2", evidence: {}, ownership: "unknown" },
+        { name: "c", action: "delete", type: "T3", evidence: {}, ownership: "owned" },
+      ],
+    });
+    expect(entriesFromPlan(plan)).toEqual([
+      { name: "a", action: "create", type: "T1" },
+      { name: "c", action: "delete", type: "T3" },
+    ]);
+  });
+
+  test("tolerates an empty / entry-less plan", () => {
+    expect(entriesFromPlan(JSON.stringify({ env: "prod" }))).toEqual([]);
+  });
+});
+
+describe("reconcilePr report mode (#122)", () => {
+  test("returns the summary without any git/network IO", async () => {
+    const result = await reconcilePr({ env: "prod", entries, mode: "report" });
+    expect(result.mode).toBe("report");
+    expect(result.prUrl).toBeUndefined();
+    expect(result.branch).toBeUndefined();
+    expect(result.summary).toContain("| bucket | adopt | AWS::S3::Bucket |");
+    expect(result.entries).toEqual(entries);
+  });
+});

package/src/op/activities/reconcile.ts

@@ -0,0 +1,165 @@
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+
+const execAsync = promisify(exec);
+
+/** What the reconcile activity does with the regenerated source. */
+export type ReconcileMode = "pull-request" | "issue" | "report";
+
+/** A change-set entry that triggered reconciliation. */
+export interface ReconcileEntry {
+  /** chant entity name. */
+  name: string;
+  /** create | update | delete | adopt | noop (from `chant lifecycle plan`). */
+  action: string;
+  /** Resource type, when known. */
+  type?: string;
+}
+
+export interface ReconcilePrArgs {
+  /** Environment to reconcile from (passed to `chant import --from`). */
+  env: string;
+  /**
+   * The change-set entries that triggered this reconcile. Omit to derive them
+   * from `chant lifecycle plan <env> --json` at run time — the form used inside a
+   * workflow, where the entries aren't known until the activity runs.
+   */
+  entries?: ReconcileEntry[];
+  /** What to produce. Default: pull-request. */
+  mode?: ReconcileMode;
+  /** Output directory for regenerated source. Default: ./infra. */
+  output?: string;
+  /** Branch to open the PR from. Default: chant/reconcile-<env>. */
+  branch?: string;
+  /** Restrict live import to chant-owned resources. */
+  owned?: boolean;
+  /** PR / issue title. Default derived from env. */
+  title?: string;
+}
+
+export interface ReconcileResult {
+  mode: ReconcileMode;
+  /** Branch created (pull-request mode). */
+  branch?: string;
+  /** Opened PR URL (pull-request mode). */
+  prUrl?: string;
+  /** Opened issue URL (issue mode). */
+  issueUrl?: string;
+  /** The markdown summary used as the PR/issue body. */
+  summary: string;
+  /** The entries that triggered the reconcile. */
+  entries: ReconcileEntry[];
+}
+
+/** Default branch name for a reconcile PR. Deterministic — no timestamp. */
+export function reconcileBranchName(env: string): string {
+  const safe = env.replace(/[^a-zA-Z0-9._-]+/g, "-");
+  return `chant/reconcile-${safe}`;
+}
+
+/**
+ * Build the markdown body summarizing which change-set entries triggered the
+ * reconcile. Pure — used as the PR/issue body and returned in `report` mode.
+ */
+export function reconcileSummary(env: string, entries: ReconcileEntry[]): string {
+  const lines = [
+    `Reconcile from live environment \`${env}\`.`,
+    "",
+    "This PR regenerates chant TypeScript from live state to close the gap between the cloud and source. It was triggered by the following change-set entries:",
+    "",
+    "| Entry | Action | Type |",
+    "|---|---|---|",
+  ];
+  for (const e of entries) {
+    lines.push(`| ${e.name} | ${e.action} | ${e.type ?? ""} |`);
+  }
+  if (entries.length === 0) {
+    lines.push("| _(none)_ | | |");
+  }
+  lines.push("");
+  lines.push("Review the diff before merging — live import may surface values that need redaction.");
+  return lines.join("\n");
+}
+
+function shellQuote(s: string): string {
+  return `'${s.replace(/'/g, "'\\''")}'`;
+}
+
+/**
+ * Map a `chant lifecycle plan --json` ChangeSet to reconcile entries, dropping
+ * `noop` entries (nothing to reconcile). Pure — exported for testing.
+ */
+export function entriesFromPlan(planJson: string): ReconcileEntry[] {
+  const cs = JSON.parse(planJson) as {
+    entries?: Array<{ name: string; action: string; type?: string }>;
+  };
+  return (cs.entries ?? [])
+    .filter((e) => e.action !== "noop")
+    .map((e) => ({ name: e.name, action: e.action, type: e.type }));
+}
+
+/** Derive reconcile entries from `chant lifecycle plan`. */
+async function derivePlanEntries(
+  env: string,
+  owned: boolean,
+  signal?: AbortSignal,
+): Promise<ReconcileEntry[]> {
+  const ownedFlag = owned ? " --owned" : "";
+  const { stdout } = await execAsync(
+    `chant lifecycle plan ${shellQuote(env)}${ownedFlag} --json`,
+    { signal },
+  );
+  return entriesFromPlan(stdout);
+}
+
+/**
+ * Reconcile activity: turn regenerated TypeScript into a reviewable artifact.
+ *
+ * - `report` — return the summary only; no git, no network.
+ * - `issue` — open a GitHub issue describing the drift (no code change).
+ * - `pull-request` — create a branch, regenerate source via
+ *   `chant import --from <env>`, commit, push, and open a PR whose diff is the
+ *   regenerated TypeScript. Never commits to the main branch.
+ *
+ * Requires `chant` and (for non-report modes) `gh`/`git` in the environment.
+ */
+export async function reconcilePr(args: ReconcilePrArgs, signal?: AbortSignal): Promise<ReconcileResult> {
+  const mode = args.mode ?? "pull-request";
+  const owned = args.owned ?? false;
+  const entries = args.entries ?? (await derivePlanEntries(args.env, owned, signal));
+  const summary = reconcileSummary(args.env, entries);
+  const title = args.title ?? `Reconcile ${args.env}: ${entries.length} change(s) from live`;
+
+  if (mode === "report") {
+    return { mode, summary, entries };
+  }
+
+  if (mode === "issue") {
+    const { stdout } = await execAsync(
+      `gh issue create --title ${shellQuote(title)} --body ${shellQuote(summary)}`,
+      { signal },
+    );
+    return { mode, summary, entries, issueUrl: stdout.trim() };
+  }
+
+  // pull-request
+  const branch = args.branch ?? reconcileBranchName(args.env);
+  const output = args.output ?? "./infra";
+  const ownedFlag = owned ? " --owned" : "";
+
+  // Never touch the main branch: cut a fresh branch first.
+  await execAsync(`git checkout -b ${shellQuote(branch)}`, { signal });
+  await execAsync(
+    `chant import --from ${shellQuote(args.env)}${ownedFlag} --output ${shellQuote(output)} --force`,
+    { signal },
+  );
+  await execAsync(`git add ${shellQuote(output)}`, { signal });
+  await execAsync(`git commit -m ${shellQuote(title)}`, { signal });
+  await execAsync(`git push -u origin ${shellQuote(branch)}`, { signal });
+  const { stdout } = await execAsync(
+    `gh pr create --title ${shellQuote(title)} --body ${shellQuote(summary)} --head ${shellQuote(branch)}`,
+    { signal },
+  );
+
+  return { mode, branch, summary, entries, prUrl: stdout.trim() };
+}

package/src/op/activities/shell.ts

@@ -15,10 +15,11 @@ export interface ShellCmdArgs {
  * Run an arbitrary shell command.
  * Uses fastIdempotent profile — 5m timeout, 3 retries.
  */
-export async function shellCmd(args: ShellCmdArgs): Promise<string> {
+export async function shellCmd(args: ShellCmdArgs, signal?: AbortSignal): Promise<string> {
   const { stdout, stderr } = await execAsync(args.cmd, {
     cwd: args.cwd,
     env: { ...process.env, ...args.env },
+    signal,
   });
   if (stderr) console.error(stderr);
   return stdout.trim();

package/src/op/activities/teardown.ts

@@ -10,11 +10,12 @@ export interface ChantTeardownArgs {
 
 /**
  * Run `chant teardown` in the given project path.
- * Uses longInfra profile — 20m timeout, heartbeat every 60s.
+ * Uses longInfra profile — 20m timeout.
  */
-export async function chantTeardown(args: ChantTeardownArgs): Promise<void> {
+export async function chantTeardown(args: ChantTeardownArgs, signal?: AbortSignal): Promise<void> {
   const { stdout, stderr } = await execAsync("npm run teardown", {
     cwd: args.path,
+    signal,
   });
   if (stdout) console.log(stdout);
   if (stderr) console.error(stderr);

package/src/op/activities/util.ts

@@ -0,0 +1,24 @@
+/** Shared helpers for activity implementations. */
+
+/**
+ * Sleep for `ms`, rejecting early if `signal` aborts. Polling activities use
+ * this between attempts so a local-executor timeout or Ctrl-C interrupts the
+ * wait instead of running it to completion.
+ */
+export function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(new Error("aborted"));
+      return;
+    }
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(new Error("aborted"));
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}

package/src/op/activities/wait.ts

@@ -1,6 +1,7 @@
 import { exec } from "node:child_process";
 import { promisify } from "node:util";
-import { Context } from "@temporalio/activity";
+import { safeHeartbeat } from "./heartbeat";
+import { sleep } from "./util";
 
 const execAsync = promisify(exec);
 
@@ -17,36 +18,41 @@ export interface WaitForStackArgs {
 
 /**
  * Poll until a Kubernetes Deployment or StatefulSet named `name` is fully rolled out.
- * Uses k8sWait profile — 15m timeout, heartbeat every 60s.
+ * Uses k8sWait profile — 15m timeout, heartbeat every poll.
  */
-export async function waitForStack(args: WaitForStackArgs): Promise<void> {
+export async function waitForStack(args: WaitForStackArgs, signal?: AbortSignal): Promise<void> {
   const ns = args.namespace ? `-n ${args.namespace}` : "";
   const ctx = args.context ? `--context ${args.context}` : "";
   const interval = args.intervalMs ?? 10_000;
   let attempt = 0;
 
   while (true) {
+    if (signal?.aborted) throw new Error("waitForStack aborted");
     attempt++;
-    Context.current().heartbeat({ step: "waitForStack", stack: args.name, attempt });
+    safeHeartbeat({ step: "waitForStack", stack: args.name, attempt });
 
     try {
       await execAsync(
         `kubectl rollout status deployment/${args.name} ${ns} ${ctx} --timeout=30s`,
+        { signal },
       );
       return;
     } catch {
+      if (signal?.aborted) throw new Error("waitForStack aborted");
       // Not ready yet — wait and retry
     }
 
     try {
       await execAsync(
         `kubectl rollout status statefulset/${args.name} ${ns} ${ctx} --timeout=30s`,
+        { signal },
       );
       return;
     } catch {
+      if (signal?.aborted) throw new Error("waitForStack aborted");
       // Not ready yet
     }
 
-    await new Promise((r) => setTimeout(r, interval));
+    await sleep(interval, signal);
   }
 }

package/src/op/compile-smoke.test.ts

@@ -0,0 +1,122 @@
+/**
+ * Generated-output compile-smoke (#162).
+ *
+ * Type-checks the serializer's emitted workflow.ts / worker.ts / activities.ts
+ * against the REAL activity signatures and the @temporalio types. The runtime
+ * harness (runtime.test.ts) proves the emitted control flow runs; this proves
+ * the emitted code still type-checks — so an activity signature change that the
+ * serializer or its callers don't track is caught as a compile error rather
+ * than drifting silently.
+ *
+ * Each op is serialized into a temp project laid out exactly as `chant build`
+ * writes it (chant.config.ts at the root, files under ops/<name>/), then run
+ * through the TypeScript compiler API. Expectation: zero diagnostics.
+ */
+import { describe, test, expect, afterAll } from "vitest";
+import ts from "typescript";
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { serializeOps } from "./serializer";
+import { ApplyOp } from "../composites/apply-op";
+import { ReconcileOp } from "../composites/reconcile-op";
+import type { Declarable } from "@intentius/chant/declarable";
+
+const ROOT = fileURLToPath(new URL("./__compile__", import.meta.url));
+
+afterAll(() => rmSync(ROOT, { recursive: true, force: true }));
+
+// Minimal chant.config.ts so the generated worker's `../../chant.config.js`
+// import resolves. The worker reads it dynamically, so the shape only needs to
+// type-check.
+const CHANT_CONFIG = `import type { TemporalChantConfig } from "@intentius/chant-lexicon-temporal";
+// Annotated (not \`satisfies\`) so \`profiles\` keeps its Record type and the
+// generated worker can index it by a runtime profile name.
+const temporal: TemporalChantConfig = {
+  profiles: { local: { address: "localhost:7233", namespace: "default", taskQueue: "tq" } },
+  defaultProfile: "local",
+};
+export default { temporal };
+`;
+
+/** Serialize `ops` into a temp project and return any type diagnostics. */
+function compileGenerated(label: string, ops: Map<string, Declarable>): string[] {
+  const projectDir = join(ROOT, label);
+  mkdirSync(projectDir, { recursive: true });
+  writeFileSync(join(projectDir, "chant.config.ts"), CHANT_CONFIG);
+
+  const files = serializeOps(ops);
+  const targets: string[] = [];
+  for (const [rel, content] of Object.entries(files)) {
+    const abs = join(projectDir, rel);
+    mkdirSync(join(abs, ".."), { recursive: true });
+    writeFileSync(abs, content as string);
+    targets.push(abs);
+  }
+
+  const program = ts.createProgram(targets, {
+    noEmit: true,
+    strict: true,
+    skipLibCheck: true,
+    target: ts.ScriptTarget.ES2022,
+    module: ts.ModuleKind.ESNext,
+    // Bundler resolution mirrors how chant resolves its `.js`-suffixed ESM
+    // imports back to the `.ts` sources (the same model tsx uses at runtime).
+    moduleResolution: ts.ModuleResolutionKind.Bundler,
+    esModuleInterop: true,
+    types: [],
+  });
+
+  // Only assert on diagnostics in the GENERATED files. The program transitively
+  // pulls in chant + @temporalio source; their diagnostics aren't what this test
+  // is about (they're checked by their own builds).
+  return ts
+    .getPreEmitDiagnostics(program)
+    .filter((d) => d.file && d.file.fileName.startsWith(projectDir))
+    .map((d) => {
+      const where = d.file!.fileName.split("/").slice(-2).join("/");
+      return `${where}: ${ts.flattenDiagnosticMessageText(d.messageText, " ")}`;
+    });
+}
+
+function opMap(...resources: Array<{ op: unknown }>): Map<string, Declarable> {
+  const m = new Map<string, Declarable>();
+  for (const r of resources) {
+    const op = r.op as Declarable & { props?: { name?: string } };
+    m.set(op.props?.name ?? String(m.size), op);
+  }
+  return m;
+}
+
+describe("generated output compile-smoke (#162)", () => {
+  test("ApplyOp output (build → plan → gate → apply, onFailure rollback) type-checks", () => {
+    const diags = compileGenerated(
+      "apply",
+      opMap(ApplyOp({ name: "prod-apply", env: "prod", target: "cloudformation", delete: "gated" })),
+    );
+    expect(diags).toEqual([]);
+  });
+
+  test("ReconcileOp output (snapshot → plan → reconcile PR) type-checks", () => {
+    const diags = compileGenerated(
+      "reconcile",
+      opMap(ReconcileOp({ name: "prod-reconcile", env: "prod", scope: { owned: true } })),
+    );
+    expect(diags).toEqual([]);
+  });
+
+  test("workflow.ts calls activities with their declared argument types", () => {
+    // A hand-built Op that passes a WRONG arg shape must surface as a type
+    // error — guards the smoke itself against false greens.
+    const bad: Map<string, Declarable> = new Map([
+      ["bad", {
+        props: {
+          name: "bad", overview: "o", taskQueue: "bad",
+          phases: [{ name: "P", steps: [{ kind: "activity", fn: "chantBuild", args: { nope: 1 } }] }],
+        },
+      } as unknown as Declarable],
+    ]);
+    const diags = compileGenerated("bad", bad);
+    expect(diags.some((d) => d.includes("workflow.ts"))).toBe(true);
+  });
+});

package/src/op/op-serializer.test.ts

@@ -94,6 +94,35 @@ describe("serializeOps()", () => {
       expect(wf).toContain("TEMPORAL_ACTIVITY_PROFILES.longInfra");
     });
 
+    it("passes the whole profile object to proxyActivities (carries every retry field, incl. nonRetryableErrorTypes)", () => {
+      // The worker must spread the entire profile — not a hand-picked subset of
+      // fields — so retry policy reaches Temporal's ActivityOptions intact. This
+      // is what makes the --temporal path honor nonRetryableErrorTypes the same
+      // way the local executor does. Reconstructing the options inline would
+      // silently drop any field not explicitly copied; this locks that out.
+      const ops = new Map([
+        makeOp({
+          name: "deploy", overview: "o",
+          phases: [{ name: "Build", steps: [{ kind: "activity", fn: "chantBuild", args: { path: "./a" } }] }],
+        }),
+      ]);
+      const wf = serializeOps(ops)["ops/deploy/workflow.ts"];
+      expect(wf).toMatch(/proxyActivities<typeof activities>\(\s*TEMPORAL_ACTIVITY_PROFILES\.fastIdempotent,\s*\)/);
+    });
+
+    it("imports activity profiles from the config leaf, not the package root (workflow-sandbox-safe)", () => {
+      // The package root re-exports the plugin/serializer (node:fs/path), which
+      // Temporal's workflow sandbox forbids — importing profiles from the root
+      // makes the worker's bundler reject the generated workflow. config.ts is
+      // import-free, so the workflow bundle stays Node-free.
+      const ops = new Map([
+        makeOp({ name: "deploy", overview: "o", phases: [{ name: "Build", steps: [{ kind: "activity", fn: "chantBuild" }] }] }),
+      ]);
+      const wf = serializeOps(ops)["ops/deploy/workflow.ts"];
+      expect(wf).toContain("from '@intentius/chant-lexicon-temporal/config'");
+      expect(wf).not.toContain("from '@intentius/chant-lexicon-temporal';");
+    });
+
     it("generates sequential await calls for a non-parallel phase", () => {
       const ops = new Map([
         makeOp({
@@ -211,6 +240,50 @@ describe("serializeOps()", () => {
       expect(wf).toContain("onFailure compensation");
       expect(wf).toContain("// Phase: Rollback");
     });
+
+    it("runs onFailure compensation ONLY on failure: main phases are wrapped in try/catch (#168)", () => {
+      const ops = new Map([
+        makeOp({
+          name: "deploy", overview: "o",
+          phases: [{ name: "Apply", steps: [{ kind: "activity", fn: "helmInstall", args: { name: "r", chart: "c" } }] }],
+          onFailure: [{ name: "Rollback", steps: [{ kind: "activity", fn: "helmInstall", args: { name: "r", chart: "c" } }] }],
+        }),
+      ]);
+      const wf = serializeOps(ops)["ops/deploy/workflow.ts"];
+      // Main phase guarded; compensation lives in the catch and re-throws the original error.
+      expect(wf).toContain("try {");
+      expect(wf).toContain("} catch (__opErr) {");
+      expect(wf).toContain("throw __opErr;");
+      // The compensation Phase upsert must appear after the catch opens, never before.
+      expect(wf.indexOf("catch (__opErr)")).toBeLessThan(wf.indexOf('Phase: ["Rollback"]'));
+    });
+
+    it("has no try/catch when there is no onFailure (#168)", () => {
+      const ops = new Map([
+        makeOp({
+          name: "plain", overview: "o",
+          phases: [{ name: "Apply", steps: [{ kind: "activity", fn: "helmInstall", args: { name: "r", chart: "c" } }] }],
+        }),
+      ]);
+      const wf = serializeOps(ops)["ops/plain/workflow.ts"];
+      expect(wf).not.toContain("catch (__opErr)");
+    });
+
+    it("runs onFailure phases in reverse order, matching the local executor (#168)", () => {
+      const ops = new Map([
+        makeOp({
+          name: "deploy", overview: "o",
+          phases: [{ name: "Apply", steps: [] }],
+          onFailure: [
+            { name: "Rollback", steps: [] },
+            { name: "Notify", steps: [] },
+          ],
+        }),
+      ]);
+      const wf = serializeOps(ops)["ops/deploy/workflow.ts"];
+      // Declared order Rollback→Notify, so compensation emits Notify before Rollback.
+      expect(wf.indexOf('Phase: ["Notify"]')).toBeLessThan(wf.indexOf('Phase: ["Rollback"]'));
+    });
   });
 
   // ── activities.ts ───────────────────────────────────────────────────────────
@@ -394,14 +467,14 @@ describe("serializeOps()", () => {
             {
               name: "Diff",
               steps: [
-                { kind: "activity", fn: "stateDiff", args: { env: "prod" }, outcomeAttribute: { name: "Drift", from: "drifted" } },
+                { kind: "activity", fn: "lifecycleDiff", args: { env: "prod" }, outcomeAttribute: { name: "Drift", from: "drifted" } },
               ],
             },
           ],
         }),
       ]);
       const wf = serializeOps(ops)["ops/watch/workflow.ts"];
-      expect(wf).toContain('const __r0 = await stateDiff({"env":"prod"});');
+      expect(wf).toContain('const __r0 = await lifecycleDiff({"env":"prod"});');
       expect(wf).toContain('upsertSearchAttributes({ "Drift": [String(__r0?.drifted)] });');
     });