@intentius/chant 0.57.0 → 0.59.0

package/src/op/cron.ts

@@ -0,0 +1,149 @@
+/**
+ * Cron for an Op's own schedule (#2120) — validation at `Op()` construction
+ * and minute-granularity matching for `chant operator`'s per-op cadence.
+ *
+ * `OpConfig.schedule.cron` is runtime-neutral data: the github lexicon turns
+ * it into `on.schedule`, a hosting lexicon hands it to its own scheduler,
+ * `chant operator` reads it as that Op's tick cadence, and the local one-shot
+ * executor ignores it entirely. Nothing here talks to a scheduler.
+ *
+ * The validator a lexicon's own post-synth cron check imports rather than
+ * keeping its own copy:
+ * deliberately permissive, a pre-submission guard rather than a full parser,
+ * since the final word belongs to whichever scheduler runs the cron.
+ *
+ * {@link cronMatches} is stricter about what it can *evaluate* than
+ * {@link isValidCronExpression} is about what it accepts, so a field carrying
+ * a Quartz extension the evaluator does not implement (`L`, `W`, `#`, `?`)
+ * matches everything rather than nothing — an operator that ticks too often
+ * is a wasted converge, one that never ticks is a silent outage.
+ */
+
+/** Very permissive cron field pattern — catches obvious syntax errors. */
+const CRON_FIELD = /^[0-9*,/\-?LW#]+$/;
+
+/**
+ * True when `expr` looks like 5- or 6-field cron. Field-shape only: it does
+ * not check that a number is in range for its position, and it accepts the
+ * Quartz extensions (`L`, `W`, `#`, `?`) some schedulers take.
+ */
+export function isValidCronExpression(expr: string): boolean {
+  const fields = expr.trim().split(/\s+/);
+  if (fields.length < 5 || fields.length > 6) return false;
+  return fields.every((f) => CRON_FIELD.test(f));
+}
+
+/**
+ * The message `Op()` throws with and a lexicon's post-synth cron check
+ * reports, so one wording covers both the build-time refusal and the
+ * post-synth diagnostic.
+ */
+export function cronSyntaxMessage(expr: string): string {
+  return `cron expression "${expr}" does not look like valid 5- or 6-field cron syntax`;
+}
+
+/** A parsed cron field: either "matches anything" or the exact set it matches. */
+type FieldSpec = { any: true } | { any: false; values: Set<number> };
+
+const ANY: FieldSpec = { any: true };
+
+/**
+ * Parse one field into the set of values it matches. Anything the evaluator
+ * cannot make sense of — a Quartz extension, an inverted range, a zero step —
+ * degrades to {@link ANY} rather than throwing: this runs on an expression
+ * `Op()` already accepted, and refusing at tick time would strand the Op.
+ */
+function parseField(field: string, min: number, max: number): FieldSpec {
+  if (field === "*" || field === "?" || /[LW#]/.test(field)) return ANY;
+
+  const values = new Set<number>();
+  for (const part of field.split(",")) {
+    const [rangePart, stepPart] = part.split("/");
+    const step = stepPart === undefined ? 1 : Number(stepPart);
+    if (!Number.isInteger(step) || step < 1) return ANY;
+
+    let lo: number;
+    let hi: number;
+    if (rangePart === "*" || rangePart === "") {
+      lo = min;
+      hi = max;
+    } else if (rangePart.includes("-")) {
+      const [a, b] = rangePart.split("-");
+      lo = Number(a);
+      hi = Number(b);
+    } else {
+      lo = Number(rangePart);
+      // `5/10` means "from 5, every 10" — a bare `5` means only 5.
+      hi = stepPart === undefined ? lo : max;
+    }
+    if (!Number.isInteger(lo) || !Number.isInteger(hi) || lo > hi) return ANY;
+
+    for (let v = lo; v <= hi; v += step) values.add(v);
+  }
+  return values.size === 0 ? ANY : { any: false, values };
+}
+
+function fieldMatches(spec: FieldSpec, value: number): boolean {
+  return spec.any || spec.values.has(value);
+}
+
+/**
+ * True when `date` falls on a minute `expr` fires at, in the host's local
+ * time zone (the only clock the operator daemon has).
+ *
+ * A 6-field expression is read as Quartz's `second minute hour dom month dow`
+ * and the seconds field is dropped — nothing in chant ticks sub-minute.
+ * Day-of-month and day-of-week follow the usual cron rule: when both are
+ * restricted, either one matching is enough.
+ */
+export function cronMatches(expr: string, date: Date): boolean {
+  const fields = expr.trim().split(/\s+/);
+  const five = fields.length === 6 ? fields.slice(1) : fields;
+  if (five.length !== 5) return false;
+
+  const [minuteF, hourF, domF, monthF, dowF] = five;
+  if (!fieldMatches(parseField(minuteF, 0, 59), date.getMinutes())) return false;
+  if (!fieldMatches(parseField(hourF, 0, 23), date.getHours())) return false;
+  if (!fieldMatches(parseField(monthF, 1, 12), date.getMonth() + 1)) return false;
+
+  const dom = parseField(domF, 1, 31);
+  const dow = parseField(dowF, 0, 7);
+  const weekday = date.getDay();
+  const domOk = fieldMatches(dom, date.getDate());
+  const dowOk = fieldMatches(dow, weekday) || (weekday === 0 && fieldMatches(dow, 7));
+
+  if (dom.any && dow.any) return true;
+  if (dom.any) return dowOk;
+  if (dow.any) return domOk;
+  return domOk || dowOk;
+}
+
+/**
+ * The longest window {@link cronDueBetween} scans minute by minute. Past it
+ * the answer is "yes" without scanning: an operator that has not looked at an
+ * op for two days has certainly missed a fire of any cron worth putting on an
+ * Op, and the alternative — 100k iterations on a clock jump — buys nothing.
+ */
+const MAX_SCAN_MINUTES = 2 * 24 * 60;
+
+/**
+ * True when `expr` fires at some minute in `(after, upTo]` — what a round
+ * asks for an Op it last ticked at `after`. Level-triggered on purpose: a
+ * round that arrives late still ticks the Op it owes rather than waiting for
+ * the next exact match, and several missed fires collapse into the one tick a
+ * convergent verb needs.
+ */
+export function cronDueBetween(expr: string, after: Date, upTo: Date): boolean {
+  if (upTo.getTime() <= after.getTime()) return false;
+
+  const startMs = Math.floor(after.getTime() / 60_000) * 60_000 + 60_000;
+  if (startMs > upTo.getTime()) return false;
+
+  const spanMinutes = Math.floor((upTo.getTime() - startMs) / 60_000) + 1;
+  if (spanMinutes > MAX_SCAN_MINUTES) return true;
+
+  for (let i = 0; i < spanMinutes; i++) {
+    if (cronMatches(expr, new Date(startMs + i * 60_000))) return true;
+  }
+  return false;
+}

package/src/op/discover-root.test.ts

@@ -16,7 +16,8 @@ import { discoverOps } from "./discover";
  * symlink and the walk compares resolved paths).
  */
 let fakeGitRoot = "";
-vi.mock("../runtime-adapter", () => ({
+vi.mock("../runtime-adapter", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("../runtime-adapter")>()),
   getRuntime: () => ({
     spawn: async (cmd: string[]) =>
       cmd[0] === "git" && cmd[1] === "rev-parse"
@@ -66,3 +67,106 @@ describe("discoverOps — the scan root is the project, not the checkout (#2058)
     expect([...ops.keys()].sort()).toEqual(["mine", "root", "theirs"]);
   });
 });
+
+/**
+ * #2171. An Op may be exported by name, not only as the file's default.
+ *
+ * Discovery used to read `mod.default` alone, which forced every runnable Op
+ * into the one export shape the fold path refuses, so an Op under a project's
+ * `sourceDir` cost that project its fold coverage. The default export is still
+ * accepted, unchanged; these cases are the widening around it.
+ *
+ * Same fake-git-root harness as the suite above: the Op files here are written
+ * as plain object literals with a `props` field, which is the shape discovery
+ * actually validates, so the fixtures stay free of the Op builders.
+ */
+describe("discoverOps: an Op may be exported by name (#2171)", () => {
+  const OP_VALUE = (name: string): string =>
+    `{ props: { name: ${JSON.stringify(name)}, overview: "t", phases: [{ name: "Run", steps: [] }] } }`;
+
+  let checkout: string;
+  const write = (file: string, body: string): void => {
+    writeFileSync(join(checkout, "ops", file), body);
+  };
+
+  beforeEach(() => {
+    checkout = realpathSync(mkdtempSync(join(tmpdir(), "chant-op-named-")));
+    fakeGitRoot = checkout;
+    mkdirSync(join(checkout, "ops"), { recursive: true });
+    writeFileSync(join(checkout, "chant.config.json"), JSON.stringify({ lexicons: ["aws"] }));
+  });
+  afterEach(() => rmSync(checkout, { recursive: true, force: true }));
+
+  test("a named export is discovered", async () => {
+    write("named.op.ts", `export const deploy = ${OP_VALUE("deploy")};\n`);
+    const { ops, errors } = await discoverOps({ cwd: checkout });
+    expect(errors).toEqual([]);
+    expect([...ops.keys()]).toEqual(["deploy"]);
+    expect(ops.get("deploy")!.exportName).toBe("deploy");
+  });
+
+  test("the default export still works, and reports itself as the default", async () => {
+    write("legacy.op.ts", `export default ${OP_VALUE("legacy")};\n`);
+    const { ops, errors } = await discoverOps({ cwd: checkout });
+    expect(errors).toEqual([]);
+    expect([...ops.keys()]).toEqual(["legacy"]);
+    expect(ops.get("legacy")!.exportName).toBe("default");
+  });
+
+  test("one file may declare several Ops, and each is registered on its own", async () => {
+    write("many.op.ts", `export const a = ${OP_VALUE("alpha")};\nexport const b = ${OP_VALUE("beta")};\n`);
+    const { ops, errors } = await discoverOps({ cwd: checkout });
+    expect(errors).toEqual([]);
+    expect([...ops.keys()].sort()).toEqual(["alpha", "beta"]);
+    expect(ops.get("alpha")!.filePath).toBe(ops.get("beta")!.filePath);
+  });
+
+  test("a default and a named Op in one file are both registered", async () => {
+    write("both.op.ts", `export default ${OP_VALUE("first")};\nexport const other = ${OP_VALUE("second")};\n`);
+    const { ops, errors } = await discoverOps({ cwd: checkout });
+    expect(errors).toEqual([]);
+    expect([...ops.keys()].sort()).toEqual(["first", "second"]);
+  });
+
+  test("the same Op exported twice is one Op, not a self-collision", async () => {
+    write("aliased.op.ts", `const op = ${OP_VALUE("aliased")};\nexport default op;\nexport { op };\n`);
+    const { ops, errors } = await discoverOps({ cwd: checkout });
+    expect(errors).toEqual([]);
+    expect([...ops.keys()]).toEqual(["aliased"]);
+    expect(ops.get("aliased")!.exportName).toBe("default");
+  });
+
+  test("exports that are not Ops are skipped in silence", async () => {
+    write("mixed.op.ts", `export const meta = { team: "infra" };\nexport const notQuite = { props: { name: "x" } };\nexport const real = ${OP_VALUE("real")};\n`);
+    const { ops, errors } = await discoverOps({ cwd: checkout });
+    expect(errors).toEqual([]);
+    expect([...ops.keys()]).toEqual(["real"]);
+  });
+
+  test("a file exporting no Op at all is the error, and names both accepted shapes", async () => {
+    write("empty.op.ts", `export const meta = { team: "infra" };\n`);
+    const { ops, errors } = await discoverOps({ cwd: checkout });
+    expect(ops.size).toBe(0);
+    expect(errors).toHaveLength(1);
+    expect(errors[0]).toContain("exports no Op");
+    expect(errors[0]).toContain("export default Op({...})");
+    expect(errors[0]).toContain("export const deploy = Op({...})");
+  });
+
+  test("two files declaring the same Op name still collide", async () => {
+    write("one.op.ts", `export const a = ${OP_VALUE("same")};\n`);
+    write("two.op.ts", `export const b = ${OP_VALUE("same")};\n`);
+    const { ops, errors } = await discoverOps({ cwd: checkout });
+    expect(ops.size).toBe(1);
+    expect(errors).toHaveLength(1);
+    expect(errors[0]).toMatch(/^Duplicate Op name "same" in .+ and .+$/);
+  });
+
+  test("two Ops sharing a name inside one file collide, and the message says so", async () => {
+    write("clash.op.ts", `export const a = ${OP_VALUE("twice")};\nexport const b = ${OP_VALUE("twice")};\n`);
+    const { ops, errors } = await discoverOps({ cwd: checkout });
+    expect(ops.size).toBe(1);
+    expect(errors).toHaveLength(1);
+    expect(errors[0]).toContain(`Duplicate Op name "twice" declared twice in`);
+  });
+});

package/src/op/discover.test.ts

@@ -1,8 +1,12 @@
 import { describe, test, expect, vi, beforeEach } from "vitest";
 import { discoverOps } from "./discover";
 
-// Mock getRuntime to return git root pointing at the repo root
-vi.mock("../runtime-adapter", () => ({
+// Mock getRuntime to return git root pointing at the repo root. Partial, via
+// `importOriginal`: the modules a discovered Op file pulls in reach the rest of
+// this module (`moduleDir`, for the lint presets), and a wholesale replacement
+// would make them fail to load rather than fail an assertion.
+vi.mock("../runtime-adapter", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("../runtime-adapter")>()),
   getRuntime: () => ({
     spawn: async (cmd: string[]) => {
       if (cmd[0] === "git" && cmd[1] === "rev-parse") {

package/src/op/discover.ts

@@ -7,6 +7,12 @@ import type { OpConfig } from "./types";
 export interface DiscoveredOp {
   config: OpConfig;
   filePath: string;
+  /**
+   * The export this Op arrived on: `"default"`, or the named export's own
+   * name (#2171). Diagnostic only, and the reason a file may carry more than
+   * one Op without either becoming ambiguous.
+   */
+  exportName: string;
 }
 
 export interface OpDiscoveryResult {
@@ -70,11 +76,71 @@ async function collectOpFiles(dir: string): Promise<string[]> {
   return files;
 }
 
+/** The `OpConfig` behind an exported value, or `undefined` when the value is not an Op. An Op entity carries its config on `.props` (`./resource.ts`); `name` and `phases` are what every consumer of a discovered Op reads. */
+function opConfigOf(value: unknown): OpConfig | undefined {
+  if (!value || typeof value !== "object") return undefined;
+  const config = (value as { props?: unknown }).props as OpConfig | undefined;
+  if (!config || typeof config.name !== "string" || !Array.isArray(config.phases)) return undefined;
+  return config;
+}
+
+/**
+ * Every Op a module exports, default first (#2171).
+ *
+ * Discovery used to read `mod.default` and nothing else, which made
+ * `export default op` the only shape a runnable Op could take. That is also
+ * the one export shape the fold path refuses (`../discovery/fold-import.ts`
+ * scans for it by name and falls the whole file back to run), so an Op living
+ * under a project's `sourceDir` cost that project its fold coverage, and took
+ * every file importing it down too. Accepting a named export removes the
+ * conflict without moving the fold's rule: the default export still works, so
+ * every Op file written against the documented shape keeps running unchanged.
+ *
+ * Non-Op exports are skipped in silence, not reported. An Op file is ordinary
+ * TypeScript and may export a helper, a config literal or a type alongside its
+ * Op; only a file exporting no Op at all is worth an error.
+ *
+ * A file may carry more than one Op, and each is registered on its own. Ops
+ * are keyed by their declared `config.name`, never by the export name or the
+ * file, so two Ops in one file are no more ambiguous to `chant run` than two
+ * Ops in two files, and the duplicate-name check in {@link discoverOps}
+ * covers both the same way. The same object exported twice (`export default
+ * op` alongside `export { op }`) is one Op, deduplicated by identity, not a
+ * self-collision.
+ *
+ * Export order is the module namespace's own: `default` first by construction
+ * here, then the named exports, which the ECMAScript specification requires a
+ * namespace object to enumerate in sorted order. So the discovered set is
+ * deterministic across runs and platforms.
+ */
+function opsExportedBy(mod: Record<string, unknown>): Array<{ exportName: string; config: OpConfig }> {
+  const found: Array<{ exportName: string; config: OpConfig }> = [];
+  const seen = new Set<unknown>();
+
+  const consider = (exportName: string, value: unknown): void => {
+    if (seen.has(value)) return;
+    const config = opConfigOf(value);
+    if (!config) return;
+    seen.add(value);
+    found.push({ exportName, config });
+  };
+
+  consider("default", mod.default);
+  for (const exportName of Object.keys(mod)) {
+    if (exportName === "default") continue;
+    consider(exportName, mod[exportName]);
+  }
+  return found;
+}
+
 /**
  * Discover all Op definitions from `*.op.ts` files under the nearest chant
  * project root (the directory holding `chant.config.ts`/`.json`, walking up
  * from `cwd`), or under the git root when no config exists — see
  * {@link findDiscoveryRoot} (#2058).
+ *
+ * An Op may be the file's default export or a named one, and a file may hold
+ * several. See {@link opsExportedBy} (#2171).
  */
 export async function discoverOps(opts?: { cwd?: string }): Promise<OpDiscoveryResult> {
   const errors: string[] = [];
@@ -87,28 +153,30 @@ export async function discoverOps(opts?: { cwd?: string }): Promise<OpDiscoveryR
 
   for (const filePath of files) {
     try {
-      const mod = await import(filePath);
-      const entity = mod.default;
+      const mod = (await import(filePath)) as Record<string, unknown>;
+      const exported = opsExportedBy(mod);
 
-      if (!entity || typeof entity !== "object") {
-        errors.push(`${filePath}: default export is not an object`);
+      if (exported.length === 0) {
+        errors.push(
+          `${filePath}: exports no Op. Expected \`export default Op({...})\` or a named export such as \`export const deploy = Op({...})\``,
+        );
         continue;
       }
 
-      const config = entity.props as OpConfig | undefined;
+      for (const { exportName, config } of exported) {
+        const priorFile = nameToFile.get(config.name);
+        if (priorFile !== undefined) {
+          errors.push(
+            priorFile === filePath
+              ? `Duplicate Op name "${config.name}" declared twice in ${filePath}`
+              : `Duplicate Op name "${config.name}" in ${filePath} and ${priorFile}`,
+          );
+          continue;
+        }
 
-      if (!config || typeof config.name !== "string" || !Array.isArray(config.phases)) {
-        errors.push(`${filePath}: default export is not a valid Op (missing name or phases)`);
-        continue;
+        nameToFile.set(config.name, filePath);
+        ops.set(config.name, { config, filePath, exportName });
       }
-
-      if (nameToFile.has(config.name)) {
-        errors.push(`Duplicate Op name "${config.name}" in ${filePath} and ${nameToFile.get(config.name)}`);
-        continue;
-      }
-
-      nameToFile.set(config.name, filePath);
-      ops.set(config.name, { config, filePath });
     } catch (err) {
       errors.push(`${filePath}: ${err instanceof Error ? err.message : String(err)}`);
     }

package/src/op/duration.ts

@@ -0,0 +1,21 @@
+/**
+ * The duration-string parser the Op model uses everywhere a timeout is
+ * authored ("5m", "30s", "1h30m", "100ms"). Its own leaf module so both
+ * `./local-executor.ts` (activity start-to-close timeouts) and `./gate.ts`
+ * (a gate's pending-fact expiry) can reach it without importing each other.
+ * Re-exported from `./local-executor.ts`, which is where it lived and where
+ * every existing caller still imports it from.
+ */
+
+/** Parse a duration string ("5m", "30s", "1h30m", "100ms") to milliseconds. Throws when nothing in `s` parses as a quantity+unit. */
+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;
+}

package/src/op/effect-step.test.ts

@@ -11,7 +11,7 @@
  * - `receiptStaleness` (WatchOp's phase) is read-only: it reports absent and
  *   differing receipts as findings and never writes.
  */
-import { describe, test, expect } from "vitest";
+import { describe, test, expect, vi } from "vitest";
 import { EffectReceipt, receiptExpectation, EXISTENCE_EXPECTATION } from "../effect-receipt";
 import { INTRINSIC_MARKER, type Intrinsic } from "../intrinsic";
 import { effect, phase } from "./builders";
@@ -23,7 +23,8 @@ import {
 } from "./receipt-store";
 import type { ActivityFn, ActivityProfile } from "./activity-registry";
 import type { OpConfig, ActivityStep } from "./types";
-import { runOpLocally, findGate, LocalGateUnsupportedError, OpRunFailure } from "./local-executor";
+import { runOpLocally, OpRunFailure } from "./local-executor";
+import { memoryGateLedgerPort } from "./gate";
 
 function fakeIntrinsic(json: unknown): Intrinsic {
   return {
@@ -57,7 +58,7 @@ describe("effect() builder", () => {
       inputs: { file: "seed.sql", version: 3 },
     });
     expect(s.expectation).toBe(receiptExpectation(seeded));
-    expect(s.steps.map((n) => (n.kind === "activity" ? n.fn : n.signalName))).toEqual(["shellCmd"]);
+    expect(s.steps.map((n) => (n.kind === "activity" ? n.fn : n.gate))).toEqual(["shellCmd"]);
   });
 
   test("existence receipts always get the constant expectation, reference inputs or not", () => {
@@ -82,7 +83,7 @@ describe("effect() builder", () => {
 
   test("preserves authored order and nested gates", () => {
     const s = effect(seeded, [
-      { kind: "gate", signalName: "approve-seed" },
+      { kind: "gate", gate: "approve-seed" },
       step("shellCmd", { cmd: "seed" }),
     ]);
     expect(s.steps.map((n) => n.kind)).toEqual(["gate", "activity"]);
@@ -187,7 +188,7 @@ describe("receiptActivities (the injectable store seam)", () => {
 // ── Local executor: read-compare-run-write ────────────────────────────────────
 
 const PROFILES: Record<string, ActivityProfile> = {
-  fastIdempotent: { startToCloseTimeout: "5m", retry: { maximumAttempts: 1 } },
+  fastIdempotent: { timeout: "5m", retry: { maximumAttempts: 1 } },
 };
 
 function activityMap(
@@ -216,7 +217,7 @@ describe("runOpLocally — effect steps", () => {
     const ran: string[] = [];
     const activities = activityMap(store, { runSeed: async () => void ran.push("runSeed") });
     const result = await runOpLocally(seedOp(), activities, PROFILES);
-    expect(result.ok).toBe(true);
+    expect(result.status).toBe("ok");
     expect(ran).toEqual([]);
     expect(writes).toEqual([]);
     // The read records the effect as already applied; the nested step is skipped.
@@ -235,7 +236,7 @@ describe("runOpLocally — effect steps", () => {
       { runSeed: async () => void order.push("runSeed") },
     );
     const result = await runOpLocally(seedOp(), activities, PROFILES);
-    expect(result.ok).toBe(true);
+    expect(result.status).toBe("ok");
     expect(order).toEqual(["runSeed", "write"]);
     expect(writes).toEqual([{ name: "seeded", expectation: receiptExpectation(seeded) }]);
     expect(result.records.map((r) => [r.fn, r.status])).toEqual([
@@ -262,7 +263,7 @@ describe("runOpLocally — effect steps", () => {
     // then writes.
     healthy = true;
     const rerun = await runOpLocally(seedOp(), activities, PROFILES);
-    expect(rerun.ok).toBe(true);
+    expect(rerun.status).toBe("ok");
     expect(writes).toEqual([{ name: "seeded", expectation: receiptExpectation(seeded) }]);
   });
 
@@ -282,19 +283,33 @@ describe("runOpLocally — effect steps", () => {
     ]);
   });
 
-  test("a gate nested in an effect step is rejected up front, like any other gate", () => {
+  test("a gate nested in an effect step stops before the receipt is written (#2119)", async () => {
     const config: OpConfig = {
       name: "gated",
       overview: "",
       phases: [
-        phase("Seed", [effect(seeded, [{ kind: "gate", signalName: "approve-seed" }, step("runSeed")])]),
+        phase("Seed", [effect(seeded, [{ kind: "gate", gate: "approve-seed" }, step("runSeed")])]),
       ],
     };
-    expect(findGate(config)?.signalName).toBe("approve-seed");
     const { store } = memStore();
-    return expect(
-      runOpLocally(config, activityMap(store, { runSeed: async () => {} }), PROFILES),
-    ).rejects.toThrow(LocalGateUnsupportedError);
+    const ran = vi.fn();
+    const result = await runOpLocally(
+      config,
+      activityMap(store, { runSeed: async () => { ran(); } }),
+      PROFILES,
+      undefined,
+      { gates: memoryGateLedgerPort(), now: "2026-09-05T12:00:00.000Z" },
+    );
+    expect(result.status).toBe("gated");
+    expect(result.gate?.gate).toBe("approve-seed");
+    expect(ran).not.toHaveBeenCalled();
+    // The receipt is untouched, so the next run re-proposes the effect.
+    expect(result.records.map((r) => [r.fn, r.status])).toEqual([
+      ["receiptRead", "ok"],
+      ["gate:approve-seed", "skipped"],
+      ["runSeed", "skipped"],
+      ["receiptWrite", "skipped"],
+    ]);
   });
 
   test("an effect step in a parallel phase is refused — read-compare-run-write is ordered", async () => {

package/src/op/emulator-lifecycle.ts

@@ -1,6 +1,6 @@
 import { exec } from "node:child_process";
 import { promisify } from "node:util";
-import { safeHeartbeat, sleep } from "./activity-runtime";
+import { sleep } from "./activity-runtime";
 
 const execAsync = promisify(exec);
 
@@ -158,7 +158,6 @@ export function emulatorLifecycle(spec: EmulatorSpec): EmulatorLifecycle {
     let ok = false;
     while (Date.now() < deadline) {
       if (signal?.aborted) throw new Error(`emulator "${name}" wait aborted`);
-      safeHeartbeat({ step: "emulatorUp", container: name });
       try {
         const res = await fetch(url, { signal });
         if (res.ok && ready(await res.text())) {

package/src/op/gate-name.test.ts

@@ -0,0 +1,65 @@
+/**
+ * The `signalName` -> `gate` rename (#2202) and the one-version bridge that
+ * keeps the old key readable through 0.59.0.
+ */
+import { describe, it, expect } from "vitest";
+import { gateName, usesDeprecatedGateKey, opUsesDeprecatedGateKey } from "./gate-name";
+import type { OpConfig } from "./types";
+
+describe("gateName", () => {
+  it("reads the new key", () => {
+    expect(gateName({ gate: "approve-prod" })).toBe("approve-prod");
+  });
+
+  it("falls back to the deprecated key", () => {
+    expect(gateName({ signalName: "approve-prod" })).toBe("approve-prod");
+  });
+
+  it("prefers the new key when a step somehow carries both", () => {
+    expect(gateName({ gate: "new", signalName: "old" })).toBe("new");
+  });
+});
+
+describe("usesDeprecatedGateKey", () => {
+  it("is true only when the new key is absent", () => {
+    expect(usesDeprecatedGateKey({ signalName: "old" })).toBe(true);
+    expect(usesDeprecatedGateKey({ gate: "new" })).toBe(false);
+    expect(usesDeprecatedGateKey({ gate: "new", signalName: "old" })).toBe(false);
+    expect(usesDeprecatedGateKey({})).toBe(false);
+  });
+});
+
+describe("opUsesDeprecatedGateKey", () => {
+  const op = (phases: OpConfig["phases"], onFailure?: OpConfig["phases"]): OpConfig =>
+    ({ name: "x", overview: "x", phases, ...(onFailure ? { onFailure } : {}) }) as OpConfig;
+
+  it("finds a gate on the old key in a plain phase", () => {
+    expect(opUsesDeprecatedGateKey(op([{ name: "Approve", steps: [{ kind: "gate", signalName: "go" }] }]))).toBe(true);
+  });
+
+  it("finds one nested inside an effect step", () => {
+    const config = op([
+      {
+        name: "Seed",
+        steps: [
+          {
+            kind: "effect",
+            receipt: { name: "seeded", effect: "db-seed", flavor: "hash", inputs: { file: "seed.sql" } },
+            steps: [{ kind: "gate", signalName: "go" }],
+          },
+        ],
+      },
+    ]);
+    expect(opUsesDeprecatedGateKey(config)).toBe(true);
+  });
+
+  it("finds one in an onFailure phase", () => {
+    expect(
+      opUsesDeprecatedGateKey(op([{ name: "Apply", steps: [] }], [{ name: "Undo", steps: [{ kind: "gate", signalName: "go" }] }])),
+    ).toBe(true);
+  });
+
+  it("is false for an Op on the new key", () => {
+    expect(opUsesDeprecatedGateKey(op([{ name: "Approve", steps: [{ kind: "gate", gate: "go" }] }]))).toBe(false);
+  });
+});