@intentius/chant 0.56.0 → 0.58.0

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 {
@@ -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,7 +283,7 @@ 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: "",
@@ -290,11 +291,25 @@ describe("runOpLocally — effect steps", () => {
         phase("Seed", [effect(seeded, [{ kind: "gate", signalName: "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.ts

@@ -0,0 +1,155 @@
+/**
+ * Gate-as-fact (#2119, epic #2114) — the one place that decides what happens
+ * when a run reaches a `gate`, shared by the Op executor
+ * (`./local-executor.ts`) and the component driver
+ * (`../components/driver.ts`) so the two can never drift.
+ *
+ * A gate used to be a wait, which meant a runtime that cannot wait had to
+ * refuse the whole op before its first step (`LocalGateUnsupportedError`,
+ * deleted with this). It is a fact now: the run reads the gate ledger
+ * (`../lifecycle/gate-ledger.ts`) for a resolution someone wrote with `chant
+ * approve`, and either walks through carrying the approver, or records a
+ * pending fact and ends. Nothing blocks, nothing is queued, nothing has to be
+ * resumed — the next run re-evaluates from the ledger, which is exactly the
+ * level-triggered shape a converge tick already has.
+ *
+ * The staleness rule is the same one `chant operator status` has applied since
+ * #1485: a resolution counts only if it is newer than the newest pending fact
+ * for that gate. Approving before the gate was ever reached does not
+ * pre-authorize a future run's gate that has since been recorded pending; a
+ * resolution from last month does not answer the fact this run just wrote.
+ *
+ * Ledger access goes through {@link GateLedgerPort} rather than straight to
+ * git, so a test (and the operator's own in-memory paths) can drive the
+ * decision without an orphan branch on disk.
+ */
+
+import {
+  appendPendingGate,
+  isPendingGateExpired,
+  latestPendingGate,
+  latestResolutionSince,
+  readGateLedger,
+  resolveApprovalUrl,
+  DEFAULT_GATE_EXPIRY,
+  type GateResolutionRecord,
+  type PendingGateInput,
+  type PendingGateRecord,
+} from "../lifecycle/gate-ledger";
+import { pushLifecycle } from "../lifecycle/git";
+import { parseDuration } from "./duration";
+
+/** The gate ledger, as the two executors need it: read both kinds of line, append a pending fact. */
+export interface GateLedgerPort {
+  read(op: string): Promise<{ resolutions: GateResolutionRecord[]; pending: PendingGateRecord[] }>;
+  appendPending(input: PendingGateInput): Promise<PendingGateRecord>;
+}
+
+/**
+ * The real port: the `chant/lifecycle` orphan branch. Pushes best-effort after
+ * appending, the same two-step-collapsed-into-one shape `chant approve` uses
+ * (`../cli/handlers/operator.ts` calls `pushLifecycle().catch(...)` right after
+ * its append) — a pending fact that only ever reaches the local branch is still
+ * a correct local answer, so a missing remote never fails the run.
+ */
+export function gitGateLedgerPort(opts?: { cwd?: string }): GateLedgerPort {
+  return {
+    async read(op) {
+      const { resolutions, pending } = await readGateLedger(op, opts);
+      return { resolutions, pending };
+    },
+    async appendPending(input) {
+      const { record } = await appendPendingGate(input, opts);
+      await pushLifecycle(opts).catch(() => undefined);
+      return record;
+    },
+  };
+}
+
+/** A gate ledger held in memory — what a test, or a caller that has already read the ledger, hands {@link evaluateGate}. */
+export function memoryGateLedgerPort(
+  seed: { resolutions?: GateResolutionRecord[]; pending?: PendingGateRecord[] } = {},
+): GateLedgerPort & { appended: PendingGateRecord[] } {
+  const resolutions = [...(seed.resolutions ?? [])];
+  const pending = [...(seed.pending ?? [])];
+  const appended: PendingGateRecord[] = [];
+  return {
+    appended,
+    async read() {
+      return { resolutions: [...resolutions], pending: [...pending] };
+    },
+    async appendPending(input) {
+      const record: PendingGateRecord = { version: 1, kind: "pending", ...input };
+      pending.push(record);
+      appended.push(record);
+      return record;
+    },
+  };
+}
+
+/** What a caller has to say about the gate it just reached. */
+export interface GateCheckInput {
+  /** The op the gate belongs to — the component's name, on the driver. */
+  op: string;
+  /** The gate's signal name. */
+  gate: string;
+  description?: string;
+  /** The gate's authored `timeout`, which becomes the pending fact's expiry. Default {@link DEFAULT_GATE_EXPIRY}. */
+  timeout?: string;
+  /** Identifies the run that reached the gate, when the caller has one. */
+  runId?: string;
+  /** ISO-8601 "now" — supplied by the caller, so the decision is deterministic under test. */
+  now?: string;
+}
+
+/** Either the gate is answered, or it is a standing fact. */
+export type GateCheck =
+  | { satisfied: true; resolution: GateResolutionRecord }
+  | { satisfied: false; pending: PendingGateRecord; recorded: boolean };
+
+/** The beginning of time — the anchor for a gate that has never been recorded pending, so any resolution for it counts. */
+const EPOCH = new Date(0).toISOString();
+
+/**
+ * Decide a gate against the ledger, recording the pending fact when it isn't
+ * answered.
+ *
+ * - A resolution newer than the newest pending fact satisfies the gate.
+ * - Otherwise, a pending fact that hasn't expired stands as it is: the run
+ *   ends `gated` and the ledger is left alone, so an operator ticking every
+ *   minute against an unapproved gate does not append a line a minute.
+ * - Otherwise (no pending fact, or the newest one has expired) a fresh pending
+ *   fact is appended and the run ends `gated`. `recorded` says which of the
+ *   two happened, so a renderer can tell "just recorded" from "still standing".
+ */
+export async function evaluateGate(port: GateLedgerPort, input: GateCheckInput): Promise<GateCheck> {
+  const now = input.now ?? new Date().toISOString();
+  const { resolutions, pending } = await port.read(input.op);
+
+  const standing = latestPendingGate(pending, input.gate);
+  const resolution = latestResolutionSince(resolutions, input.gate, standing?.timestamp ?? EPOCH);
+  if (resolution) return { satisfied: true, resolution };
+
+  if (standing && !isPendingGateExpired(standing, now)) {
+    return { satisfied: false, pending: standing, recorded: false };
+  }
+
+  const url = resolveApprovalUrl();
+  const record = await port.appendPending({
+    op: input.op,
+    gate: input.gate,
+    timestamp: now,
+    expiresAt: new Date(
+      new Date(now).getTime() + parseDuration(input.timeout ?? DEFAULT_GATE_EXPIRY),
+    ).toISOString(),
+    ...(input.description ? { description: input.description } : {}),
+    ...(input.runId ? { runId: input.runId } : {}),
+    ...(url ? { url } : {}),
+  });
+  return { satisfied: false, pending: record, recorded: true };
+}
+
+/** The line every renderer prints to say how a pending gate is cleared. */
+export function approveCommand(op: string, gate: string): string {
+  return `chant approve ${op} ${gate}`;
+}

package/src/op/generate-pipeline.test.ts

@@ -9,7 +9,9 @@
  */
 
 import { describe, test, expect, vi } from "vitest";
-import { generateOpsPipeline } from "./generate-pipeline";
+import { generateOpsPipeline, withOpSchedules } from "./generate-pipeline";
+import type { DiscoveredOp } from "./discover";
+import type { OpConfig } from "./types";
 import type { ScheduledOpSpec, OpPipelineResult } from "../lexicon";
 
 vi.mock("@intentius/chant-lexicon-gitlab", () => ({
@@ -22,7 +24,12 @@ vi.mock("@intentius/chant-lexicon-gitlab", () => ({
     package: () => "gitlab",
     generateOpPipeline: (ops: ScheduledOpSpec[]): OpPipelineResult => ({
       files: ops.map((o) => ({ name: `${o.name}.yml`, yaml: `# ${o.name} @ ${o.schedule}` })),
-      jobs: ops.map((o) => ({ jobName: o.name, op: o.name, schedule: o.schedule, findingMode: o.findingMode ?? "report" })),
+      jobs: ops.map((o) => ({
+        jobName: o.name,
+        op: o.name,
+        trigger: o.trigger ?? { kind: "cron" as const, schedule: o.schedule! },
+        findingMode: o.findingMode ?? "report",
+      })),
     }),
   },
 }));
@@ -48,6 +55,61 @@ describe("generateOpsPipeline", () => {
     const result = await generateOpsPipeline(specs, "gitlab");
     expect(result.success).toBe(true);
     expect(result.files).toEqual([{ name: "alb-deploy.yml", yaml: "# alb-deploy @ 0 6 * * *" }]);
-    expect(result.jobs).toEqual([{ jobName: "alb-deploy", op: "alb-deploy", schedule: "0 6 * * *", findingMode: "issue" }]);
+    expect(result.jobs).toEqual([
+      { jobName: "alb-deploy", op: "alb-deploy", trigger: { kind: "cron", schedule: "0 6 * * *" }, findingMode: "issue" },
+    ]);
+  });
+
+  // #2084: `trigger` is new and optional — a spec built the old way (`schedule`
+  // only, no `trigger`) must still round-trip through `generateOpsPipeline`
+  // unchanged, since every pre-#2084 caller (`WorkflowAuditOp`,
+  // `PipelineAuditOp`, `ReconcileOp`) only ever sets `schedule`.
+  test("a legacy `{ schedule }` spec with no `trigger` round-trips unchanged", async () => {
+    const specs: ScheduledOpSpec[] = [{ name: "alb-deploy", schedule: "0 6 * * *" }];
+    const result = await generateOpsPipeline(specs, "gitlab");
+    expect(result.success).toBe(true);
+    expect(result.files).toEqual([{ name: "alb-deploy.yml", yaml: "# alb-deploy @ 0 6 * * *" }]);
+    expect(result.jobs).toEqual([
+      { jobName: "alb-deploy", op: "alb-deploy", trigger: { kind: "cron", schedule: "0 6 * * *" }, findingMode: "report" },
+    ]);
+  });
+});
+
+describe("withOpSchedules — the Op's own cadence reaches the CI generator (#2120)", () => {
+  function discovered(entries: Array<[string, OpConfig]>): Map<string, DiscoveredOp> {
+    return new Map(entries.map(([name, config]) => [name, { config, filePath: `${name}.op.ts`, exportName: "default" }]));
+  }
+
+  const scheduled: OpConfig = {
+    name: "prod-watch",
+    overview: "watch prod",
+    phases: [],
+    schedule: { cron: "*/10 * * * *", overlap: "skip" },
+  };
+  const unscheduled: OpConfig = { name: "one-shot", overview: "no cadence", phases: [] };
+
+  test("a scheduled Op's cadence lands on its spec as opSchedule", () => {
+    const [spec] = withOpSchedules([{ name: "prod-watch" }], discovered([["prod-watch", scheduled]]));
+    expect(spec.opSchedule).toEqual({ cron: "*/10 * * * *", overlap: "skip" });
+  });
+
+  test("an Op with no cadence leaves its spec untouched", () => {
+    const input: ScheduledOpSpec[] = [{ name: "one-shot", schedule: "0 6 * * *" }];
+    expect(withOpSchedules(input, discovered([["one-shot", unscheduled]]))).toEqual(input);
+  });
+
+  test("an explicit trigger or schedule on the spec is preserved alongside it — resolveOpTrigger picks", () => {
+    const [spec] = withOpSchedules(
+      [{ name: "prod-watch", trigger: { kind: "push", branches: ["main"] } }],
+      discovered([["prod-watch", scheduled]]),
+    );
+    expect(spec.trigger).toEqual({ kind: "push", branches: ["main"] });
+    expect(spec.opSchedule).toEqual({ cron: "*/10 * * * *", overlap: "skip" });
+  });
+
+  test("the input specs are not mutated", () => {
+    const input: ScheduledOpSpec[] = [{ name: "prod-watch" }];
+    withOpSchedules(input, discovered([["prod-watch", scheduled]]));
+    expect(input[0].opSchedule).toBeUndefined();
   });
 });