@intentius/chant 0.57.0 → 0.58.0

package/src/op/operator.test.ts

@@ -13,9 +13,27 @@ import {
 } from "./operator";
 import { readLease } from "../lifecycle/lease";
 import { appendConvergeRecord, readConvergeLedger } from "../lifecycle/converge-ledger";
+import { readRunLedger } from "../lifecycle/run-ledger";
+import type { OpRunRecord } from "./runtime";
 
 const PROFILES: Record<string, ActivityProfile> = {};
 
+/** A minimal `OpRunRecord` for a result literal that never touches a ledger. */
+function runRecord(op: string, status: OpRunRecord["status"] = "ok"): OpRunRecord {
+  return {
+    version: 1,
+    id: "00000000-0000-4000-8000-000000000000",
+    op,
+    env: "staging",
+    started: "2026-01-01T00:00:00.000Z",
+    ended: "2026-01-01T00:00:01.000Z",
+    status,
+    labels: {},
+    outcomes: {},
+    phases: [],
+  };
+}
+
 function git(args: string[], cwd: string): { stdout: string; exitCode: number } {
   const r = spawnSync("git", args, { cwd, encoding: "utf-8" });
   return { stdout: r.stdout ?? "", exitCode: r.status ?? -1 };
@@ -34,7 +52,7 @@ async function initRepo(dir: string): Promise<void> {
  * Write a minimal fixture ConvergeOp — the same `{ props: OpConfig }` shape
  * `discoverOps` reads from a real `*.op.ts` file's default export
  * (`../op/discover.ts`), hand-built here rather than going through the real
- * `ConvergeOp()` composite (lexicons/temporal) so this suite tests the
+ * `ConvergeOp()` composite so this suite tests the
  * operator's own discovery/lease/tick-loop logic without depending on that
  * lexicon at all. One "Converge" phase calling a single fake activity —
  * `runOpLocally` doesn't care what the phases are named or how many there
@@ -50,7 +68,26 @@ function writeFixtureConvergeOp(dir: string, opName: string, env: string): void
     name: ${JSON.stringify(opName)},
     overview: "fixture converge op",
     phases: [{ name: "Converge", steps: [{ kind: "activity", fn: "fakeTick", args: {} }] }],
-    searchAttributes: { Converge: "true", Env: ${JSON.stringify(env)}, Dial: "observe" },
+    labels: { Converge: "true", Env: ${JSON.stringify(env)}, Dial: "observe" },
+  },
+};
+`,
+  );
+}
+
+/** The same fixture with a cadence of its own (#2120) — what `ConvergeOp({ schedule })` produces. */
+function writeFixtureScheduledConvergeOp(dir: string, opName: string, env: string, cron: string): void {
+  const opsDir = join(dir, "ops");
+  mkdirSync(opsDir, { recursive: true });
+  writeFileSync(
+    join(opsDir, `${opName}.op.ts`),
+    `export default {
+  props: {
+    name: ${JSON.stringify(opName)},
+    overview: "fixture scheduled converge op",
+    phases: [{ name: "Converge", steps: [{ kind: "activity", fn: "fakeTick", args: {} }] }],
+    labels: { Converge: "true", Env: ${JSON.stringify(env)}, Dial: "observe" },
+    schedule: { cron: ${JSON.stringify(cron)}, overlap: "skip" },
   },
 };
 `,
@@ -99,7 +136,7 @@ function fakeTickActivities(dir: string, env: string, opName: string, opts?: { t
 }
 
 describe("discoverConvergeOps", () => {
-  test("finds only ops with searchAttributes.Converge === 'true'", async () => {
+  test("finds only ops with labels.Converge === 'true'", async () => {
     await withTestDir(async (dir) => {
       await initRepo(dir);
       writeFixtureConvergeOp(dir, "staging-converge", "staging");
@@ -132,6 +169,28 @@ describe("discoverConvergeOps", () => {
       expect(ops.map((d) => d.config.name)).toEqual(["prod-converge", "staging-converge"]);
     });
   });
+
+  test("a ConvergeOp declaring no labels.Env is discovered unfiltered but never matches --env", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      mkdirSync(join(dir, "ops"), { recursive: true });
+      writeFileSync(
+        join(dir, "ops", "envless-converge.op.ts"),
+        `export default {
+  props: {
+    name: "envless-converge",
+    overview: "a hand-built ConvergeOp with no Env label",
+    phases: [{ name: "Converge", steps: [{ kind: "activity", fn: "fakeTick", args: {} }] }],
+    labels: { Converge: "true" },
+  },
+};
+`,
+      );
+
+      expect((await discoverConvergeOps({ cwd: dir })).ops.map((d) => d.config.name)).toEqual(["envless-converge"]);
+      expect((await discoverConvergeOps({ cwd: dir, env: "staging" })).ops).toEqual([]);
+    });
+  });
 });
 
 describe("runOperatorRound — lease + tick execution over a fixture ConvergeOp (offline)", () => {
@@ -142,7 +201,7 @@ describe("runOperatorRound — lease + tick execution over a fixture ConvergeOp
       const activities = fakeTickActivities(dir, "staging", "staging-converge");
 
       const events = await runOperatorRound({ cwd: dir, holder: "op-a", activities, profiles: PROFILES });
-      expect(events).toEqual([{ kind: "ticked", op: "staging-converge", env: "staging", result: expect.objectContaining({ ok: true }) }]);
+      expect(events).toEqual([{ kind: "ticked", op: "staging-converge", env: "staging", result: expect.objectContaining({ status: "ok" }) }]);
 
       const { records } = await readConvergeLedger("staging", { cwd: dir });
       expect(records).toHaveLength(1);
@@ -150,6 +209,27 @@ describe("runOperatorRound — lease + tick execution over a fixture ConvergeOp
     });
   });
 
+  test("the tick's own run lands on the run ledger, keyed by the op's labels.Env (#2118)", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      writeFixtureConvergeOp(dir, "staging-converge", "staging");
+      const activities = fakeTickActivities(dir, "staging", "staging-converge");
+
+      await runOperatorRound({ cwd: dir, holder: "op-a", activities, profiles: PROFILES });
+
+      const { records, malformed } = await readRunLedger("staging", "staging-converge", { cwd: dir });
+      expect(malformed).toBe(0);
+      expect(records).toHaveLength(1);
+      expect(records[0]).toMatchObject({
+        op: "staging-converge",
+        env: "staging",
+        status: "ok",
+        labels: { Converge: "true", Env: "staging", Dial: "observe" },
+      });
+      expect(records[0].phases.map((p) => p.name)).toEqual(["Converge"]);
+    });
+  });
+
   test("a second operator process (different holder) sees the lease held and skips — never queues", async () => {
     await withTestDir(async (dir) => {
       await initRepo(dir);
@@ -330,10 +410,97 @@ describe("runOperatorForever — interval/timer behavior", () => {
   });
 });
 
+describe("runOperatorRound — an Op's own schedule is its tick cadence (#2120)", () => {
+  /** 2026-09-06T13:30 local — a minute `*​/10 * * * *` fires on. */
+  const firing = () => new Date(2026, 8, 6, 13, 30, 0, 0);
+  /** …and 13:33, which it does not. */
+  const quiet = () => new Date(2026, 8, 6, 13, 33, 0, 0);
+
+  test("a round on a firing minute ticks the op", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      writeFixtureScheduledConvergeOp(dir, "staging-converge", "staging", "*/10 * * * *");
+      const activities = fakeTickActivities(dir, "staging", "staging-converge");
+
+      const events = await runOperatorRound({ cwd: dir, holder: "op-a", activities, profiles: PROFILES, now: firing });
+      expect(events).toEqual([
+        { kind: "ticked", op: "staging-converge", env: "staging", result: expect.objectContaining({ status: "ok" }) },
+      ]);
+    });
+  });
+
+  test("a round off the cron skips without touching the lease, and writes no ledger record", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      writeFixtureScheduledConvergeOp(dir, "staging-converge", "staging", "*/10 * * * *");
+      const activities = fakeTickActivities(dir, "staging", "staging-converge");
+
+      const events = await runOperatorRound({ cwd: dir, holder: "op-a", activities, profiles: PROFILES, now: quiet });
+      expect(events).toEqual([
+        { kind: "skipped-not-due", op: "staging-converge", env: "staging", cron: "*/10 * * * *" },
+      ]);
+
+      const { records } = await readConvergeLedger("staging", { cwd: dir });
+      expect(records).toHaveLength(0);
+      expect((await readLease("staging-converge", { cwd: dir })).record).toBeUndefined();
+    });
+  });
+
+  test("a late round still owes the tick: a firing minute passed since this op was last considered", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      writeFixtureScheduledConvergeOp(dir, "staging-converge", "staging", "*/10 * * * *");
+      const activities = fakeTickActivities(dir, "staging", "staging-converge");
+      const scheduleState = new Map<string, Date>();
+
+      // 13:33 — first sight, not a firing minute: recorded, not ticked.
+      const first = await runOperatorRound({ cwd: dir, holder: "op-a", activities, profiles: PROFILES, now: quiet, scheduleState });
+      expect(first[0].kind).toBe("skipped-not-due");
+
+      // 13:42 — 13:40 fired while nobody was looking, so this round ticks.
+      const late = () => new Date(2026, 8, 6, 13, 42, 0, 0);
+      const second = await runOperatorRound({ cwd: dir, holder: "op-a", activities, profiles: PROFILES, now: late, scheduleState });
+      expect(second[0].kind).toBe("ticked");
+
+      // 13:43 — nothing has fired since 13:42.
+      const after = () => new Date(2026, 8, 6, 13, 43, 0, 0);
+      const third = await runOperatorRound({ cwd: dir, holder: "op-a", activities, profiles: PROFILES, now: after, scheduleState });
+      expect(third[0].kind).toBe("skipped-not-due");
+    });
+  });
+
+  test("an op with no cadence of its own still ticks every round — `--interval` is the fallback", async () => {
+    await withTestDir(async (dir) => {
+      await initRepo(dir);
+      writeFixtureConvergeOp(dir, "staging-converge", "staging");
+      const activities = fakeTickActivities(dir, "staging", "staging-converge");
+
+      const events = await runOperatorRound({ cwd: dir, holder: "op-a", activities, profiles: PROFILES, now: quiet });
+      expect(events[0].kind).toBe("ticked");
+    });
+  });
+});
+
 describe("formatRoundLine", () => {
   test("renders each event kind as one line", () => {
-    expect(formatRoundLine({ kind: "ticked", op: "x", env: "staging", result: { op: "x", records: [], totalMs: 1, ok: true } }))
-      .toContain("ticked=1 ok=true");
+    expect(formatRoundLine({
+      kind: "ticked", op: "x", env: "staging",
+      result: {
+        op: "x", records: [], totalMs: 1, status: "ok", startedAt: "2026-09-05T12:00:00.000Z",
+        record: runRecord("x", "ok"),
+      },
+    })).toContain("ticked=1 status=ok");
+    expect(formatRoundLine({
+      kind: "ticked", op: "x", env: "staging",
+      result: {
+        op: "x", records: [], totalMs: 1, status: "gated", startedAt: "2026-09-05T12:00:00.000Z",
+        gate: {
+          version: 1, kind: "pending", op: "x", gate: "rollout-gate",
+          timestamp: "2026-09-05T12:00:00.000Z", expiresAt: "2026-09-07T12:00:00.000Z",
+        },
+        record: runRecord("x", "gated"),
+      },
+    })).toContain('status=gated gate="rollout-gate"');
     expect(formatRoundLine({ kind: "skipped-lease-held", op: "x", env: "staging", heldBy: "holder-a" }))
       .toContain("lease-held:holder-a");
     expect(formatRoundLine({ kind: "tick-failed", op: "x", env: "staging", error: "boom" }))
@@ -342,5 +509,7 @@ describe("formatRoundLine", () => {
       .toContain("fenced=1");
     expect(formatRoundLine({ kind: "lease-error", op: "x", env: "staging", error: "stale lock at .../x.lock" }))
       .toContain("stale lock at .../x.lock");
+    expect(formatRoundLine({ kind: "skipped-not-due", op: "x", env: "staging", cron: "*/10 * * * *" }))
+      .toContain("not-due:*/10 * * * *");
   });
 });

package/src/op/operator.ts

@@ -1,13 +1,13 @@
 /**
- * `chant operator` (#1485, epic #1487) — native durable ticks without
- * Temporal. A deliberately small daemon: a timer, a lease
+ * `chant operator` (#1485, epic #1487) — durable ticks with no service behind
+ * them. A deliberately small daemon: a timer, a lease
  * (../lifecycle/lease.ts), and the existing local executor
  * (./local-executor.ts) in a loop. No new service, no new state store — the
  * lease lives on a git ref, tick state lives on the `chant/lifecycle`
  * orphan branch via the same `convergeTick` activity `chant run <op>`
  * already calls for a single one-shot tick.
  *
- * One round: discover every `ConvergeOp` (searchAttributes `Converge:
+ * One round: discover every `ConvergeOp` (label `Converge:
  * "true"`, optionally filtered to one env), and for each one, try to
  * acquire (or renew) its lease. Win it — run one tick via `runOpLocally` on
  * the Op's own Observe → Converge phases, the identical path `chant run
@@ -37,23 +37,32 @@
  */
 import type { ActivityFn, ActivityProfile } from "./activity-registry";
 import { discoverOps, type DiscoveredOp } from "./discover";
-import { runOpLocally, OpRunFailure, LocalGateUnsupportedError, type OpRunResult } from "./local-executor";
+import { runOpLocally, OpRunFailure, type OpRunResult } from "./local-executor";
 import { acquireLease, stillHoldsLease, currentHolderId, DEFAULT_LEASE_TTL_MS, type LeaseRecord, type AcquireLeaseResult } from "../lifecycle/lease";
 import { StaleLockError } from "../lifecycle/git";
+import { cronMatches, cronDueBetween } from "./cron";
 
-/** Poll interval between rounds — the operator's own cadence, distinct from a `ConvergeOp`'s Temporal `schedule` cron (that field drives the durable path's `TemporalSchedule`, not anything the local executor can read back at discovery time; see this module's doc). Chosen short enough to converge promptly, long enough not to hammer `chant lifecycle plan --live` every few seconds. */
+/**
+ * Poll interval between rounds — the operator's own cadence, and the fallback
+ * for an Op that declares none. Since #2120 an Op can carry its own
+ * `schedule.cron` (`./composites/converge-op.ts`), which this loop honours per
+ * Op: the round still wakes every `intervalMs`, but an Op with a cron is
+ * ticked only on the minutes that cron fires. Chosen short enough to converge
+ * promptly, long enough not to hammer `chant lifecycle plan --live` every few
+ * seconds — and short enough that a per-minute cron is not missed.
+ */
 export const DEFAULT_OPERATOR_INTERVAL_MS = 60_000;
 
-/** One ConvergeOp's own `searchAttributes.Env` (`../../lexicons/temporal/src/composites/converge-op.ts` always sets it). `undefined` for a non-ConvergeOp or a hand-built one missing it — filtered out by `isConvergeOp` before this is trusted. */
+/** One ConvergeOp's own `labels.Env` (`./composites/converge-op.ts` always sets it). `undefined` for a non-ConvergeOp or a hand-built one missing it — filtered out by `isConvergeOp` before this is trusted. */
 function envOf(config: DiscoveredOp["config"]): string | undefined {
-  return config.searchAttributes?.Env;
+  return config.labels?.Env;
 }
 
 function isConvergeOp(config: DiscoveredOp["config"]): boolean {
-  return config.searchAttributes?.Converge === "true";
+  return config.labels?.Converge === "true";
 }
 
-/** Discover every `ConvergeOp` in the project (`searchAttributes.Converge === "true"`), optionally filtered to one environment. Ops that don't declare an `Env` search attribute are excluded from an `--env`-filtered discovery (there's nothing to match), but included when no `env` filter is given. */
+/** Discover every `ConvergeOp` in the project (`labels.Converge === "true"`), optionally filtered to one environment. Ops that don't declare an `Env` label are excluded from an `--env`-filtered discovery (there's nothing to match), but included when no `env` filter is given. */
 export async function discoverConvergeOps(
   opts?: { cwd?: string; env?: string },
 ): Promise<{ ops: DiscoveredOp[]; errors: string[] }> {
@@ -67,6 +76,8 @@ export async function discoverConvergeOps(
 export type OperatorTickEvent =
   | { kind: "ticked"; op: string; env: string; result: OpRunResult }
   | { kind: "skipped-lease-held"; op: string; env: string; heldBy?: string }
+  /** The Op declares its own `schedule.cron` (#2120) and this round did not land on a firing minute — the lease was never touched. An Op without a cron is never reported this way: it ticks every round, on `--interval`. */
+  | { kind: "skipped-not-due"; op: string; env: string; cron: string }
   | { kind: "tick-failed"; op: string; env: string; error: string }
   /** The lease was lost between acquiring it and the tick finishing (e.g. this process stalled past its TTL and another operator reclaimed it) — the tick's own ledger record (written inside `convergeTick`) still landed, since a converge tick is idempotent by design; this event exists purely so `chant operator`'s log and the ledger-independent test surface can see the fencing violation happened. Never a hard failure. */
   | { kind: "fenced"; op: string; env: string }
@@ -96,6 +107,16 @@ export interface OperatorRoundOptions {
   profiles: Record<string, ActivityProfile>;
   now?: () => Date;
   signal?: AbortSignal;
+  /**
+   * When each Op with its own `schedule.cron` was last considered (#2120) —
+   * the state a round needs to answer "has a firing minute passed since I
+   * last looked at this Op?". `runOperatorForever` owns one map across
+   * rounds; a bare `runOperatorRound` with none given falls back to "is this
+   * minute a firing minute", which is what a single round can know on its
+   * own. Every considered Op's entry is updated, ticked or not, so a late
+   * round makes up exactly one tick rather than a backlog.
+   */
+  scheduleState?: Map<string, Date>;
 }
 
 /**
@@ -112,6 +133,24 @@ export async function runOperatorRound(opts: OperatorRoundOptions): Promise<Oper
   for (const { config } of ops) {
     const env = envOf(config) ?? "unknown";
 
+    // An Op that declares its own cadence (#2120) is ticked on that cron
+    // rather than on every round. Level-triggered: the question is whether a
+    // firing minute has passed since this Op was last looked at, so a round
+    // that arrives late still owes exactly one tick — a converge tick
+    // re-observes everything anyway, and several missed fires are one tick's
+    // worth of work.
+    const cron = config.schedule?.cron;
+    if (cron) {
+      const now = (opts.now ?? (() => new Date()))();
+      const lastSeen = opts.scheduleState?.get(config.name);
+      const due = lastSeen === undefined ? cronMatches(cron, now) : cronDueBetween(cron, lastSeen, now);
+      opts.scheduleState?.set(config.name, now);
+      if (!due) {
+        events.push({ kind: "skipped-not-due", op: config.name, env, cron });
+        continue;
+      }
+    }
+
     let acquired: AcquireLeaseResult;
     try {
       acquired = await acquireLease(config.name, holder, {
@@ -137,18 +176,18 @@ export async function runOperatorRound(opts: OperatorRoundOptions): Promise<Oper
 
     const lease = acquired.lease as LeaseRecord;
     try {
-      const result = await runOpLocally(config, opts.activities, opts.profiles, opts.signal);
+      const result = await runOpLocally(config, opts.activities, opts.profiles, opts.signal, {
+        ledger: { cwd: opts.cwd },
+      });
       const held = await stillHoldsLease(config.name, holder, lease.token, { cwd: opts.cwd });
       events.push(held ? { kind: "ticked", op: config.name, env, result } : { kind: "fenced", op: config.name, env });
     } catch (err) {
       const message =
         err instanceof OpRunFailure
           ? `Op "${config.name}" failed — see its ledger record for step-level detail`
-          : err instanceof LocalGateUnsupportedError
+          : err instanceof Error
             ? err.message
-            : err instanceof Error
-              ? err.message
-              : String(err);
+            : String(err);
       events.push({ kind: "tick-failed", op: config.name, env, error: message });
     }
   }
@@ -188,8 +227,13 @@ export interface OperatorLoopOptions extends OperatorRoundOptions {
  */
 export async function runOperatorForever(opts: OperatorLoopOptions): Promise<void> {
   const holder = opts.holder ?? currentHolderId();
+  // Per-op cron state (#2120) lives for the life of the loop. A restart starts
+  // it empty, which means the first round ticks a scheduled Op only if it
+  // lands on a firing minute — a fresh operator owes no catch-up for the ticks
+  // it was not running for.
+  const scheduleState = opts.scheduleState ?? new Map<string, Date>();
   while (!opts.signal?.aborted) {
-    const events = await runOperatorRound({ ...opts, holder });
+    const events = await runOperatorRound({ ...opts, holder, scheduleState });
     opts.onRound?.(events);
     if (opts.signal?.aborted) break;
     await sleepAbortable(opts.intervalMs ?? DEFAULT_OPERATOR_INTERVAL_MS, opts.signal);
@@ -200,9 +244,12 @@ export async function runOperatorForever(opts: OperatorLoopOptions): Promise<voi
 export function formatRoundLine(event: OperatorTickEvent): string {
   switch (event.kind) {
     case "ticked":
-      return `operator: ${event.op}@${event.env} ticked=1 ok=${event.result.ok}`;
+      return `operator: ${event.op}@${event.env} ticked=1 status=${event.result.status}` +
+        (event.result.gate ? ` gate="${event.result.gate.gate}"` : "");
     case "skipped-lease-held":
       return `operator: ${event.op}@${event.env} skipped=1(lease-held${event.heldBy ? `:${event.heldBy}` : ""})`;
+    case "skipped-not-due":
+      return `operator: ${event.op}@${event.env} skipped=1(not-due:${event.cron})`;
     case "tick-failed":
       return `operator: ${event.op}@${event.env} failed=1 error="${event.error}"`;
     case "fenced":

package/src/op/receipt-store.ts

@@ -108,7 +108,7 @@ export interface ReceiptReadArgs extends ReceiptCheckInput {}
 export interface ReceiptReadResult {
   /** The receipt's live stored value, or null when absent. */
   current: string | null;
-  /** The resolved expectation the workflow compares and later writes. */
+  /** The resolved expectation the effect step compares and later writes. */
   expectation: string;
   /** Convenience: `current === expectation`. */
   applied: boolean;

package/src/op/resource.ts

@@ -2,7 +2,25 @@ import { createResource } from "../runtime";
 
 /**
  * The Declarable resource backing an Op definition.
- * entityType: "Temporal::Op", lexicon: "temporal"
+ * entityType: "Chant::Op", lexicon: "chant"
  * Discovered automatically alongside infra files — no pipeline changes needed.
+ *
+ * An Op is chant's own verb, not a runtime's (#2118, epic #2114): the model,
+ * the executor and the ledger all live in core, and a lexicon that hosts runs
+ * is one runtime among several. The entity type says so.
  */
-export const OpResource = createResource("Temporal::Op", "temporal", {});
+export const OP_ENTITY_TYPE = "Chant::Op";
+
+export const OpResource = createResource(OP_ENTITY_TYPE, "chant", {});
+
+/**
+ * Is this entity an Op declaration?
+ *
+ * Duck-typed on `entityType` rather than `instanceof OpResource` for the same
+ * reason `../build.ts`'s dependency inference is: an entity can be built
+ * against a different copy of core (a linked lexicon, a child project) and
+ * still be the same declaration.
+ */
+export function isOpEntity(entity: unknown): boolean {
+  return (entity as { entityType?: string } | null)?.entityType === OP_ENTITY_TYPE;
+}

package/src/op/runtime.ts

@@ -0,0 +1,203 @@
+/**
+ * The op-runtime seam (#2121, epic #2114).
+ *
+ * An Op is a convergent verb; *where* it runs is a separate question from
+ * *what* it does. This module states that question once, as a provider
+ * contract, so `chant run` has one dispatch path instead of a branch per
+ * runtime. Core ships the `local` provider (./runtimes/local.ts) and never
+ * imports a hosting lexicon; a lexicon that hosts runs implements
+ * {@link OpRuntimeProvider} and hangs it off `LexiconPlugin.opRuntime`, where
+ * `chant run <op> --on <lexicon>` finds it.
+ *
+ * The record shapes below are the run ledger's (#2118): what a run wrote to
+ * `<env>/runs__<op>.jsonl` is what a provider's `status` and `log` read back,
+ * so a run's outcome survives the process that produced it. A provider with no
+ * ledger behind it (a hosting lexicon reporting a live run) fills the same
+ * shape from whatever it does know.
+ */
+
+import type { OpConfig } from "./types";
+import type { StepRecord, OpRunResult } from "./local-executor";
+import type { GateResolutionRecord } from "../lifecycle/gate-ledger";
+import type { RunComponentsOptions, RunComponentsResult } from "../components/cli-support";
+
+/**
+ * How a run ended, or that it has not. `gated` is the state a run reaches when
+ * a gate has no recorded resolution — a fact, not a wait (#2119).
+ *
+ * This is the coarse state a *runtime* reports. The ledger records the
+ * executor's own three-state outcome instead ({@link OpRunRecord.status}),
+ * which has no `running` or `cancelled`: a record is only written once a run
+ * has settled.
+ */
+export type OpRunState = "running" | "completed" | "failed" | "gated" | "cancelled";
+
+/** Map a settled run's ledger status onto the coarser runtime state. */
+export function runStateOf(status: OpRunRecord["status"]): OpRunState {
+  return status === "ok" ? "completed" : status === "gated" ? "gated" : "failed";
+}
+
+/** One step's outcome as the run ledger keeps it — `StepRecord` minus the fields only a live renderer needs. */
+export interface OpRunStepRecord {
+  /** The activity function name, or `gate:<signal>` for a gate step. */
+  fn: string;
+  status: StepRecord["status"];
+  durationMs: number;
+  /** The step's `outcomeAttribute` capture, when it declared one. */
+  outcome?: { name: string; value: unknown };
+  /** Who cleared this gate step and when (#2119), for a gate the run passed. */
+  approval?: { gate: string; resolvedBy: string; timestamp: string; url?: string };
+  /** The failure message, for `status: "fail"`. */
+  error?: string;
+}
+
+/** One phase's steps and the verdict they add up to. */
+export interface OpRunPhaseRecord {
+  name: string;
+  /** `fail` if any step failed, `skipped` if every step was skipped, else `ok`. */
+  status: "ok" | "fail" | "skipped";
+  steps: OpRunStepRecord[];
+}
+
+/**
+ * A run's current state, as every runtime reports it.
+ *
+ * `records` and `result` are populated by a runtime that has the executor's
+ * own step records to hand (the local one does, for a run it just executed in
+ * this process); a runtime answering from the ledger alone omits them rather
+ * than inventing them.
+ */
+export interface OpRunStatus {
+  op: string;
+  runId: string;
+  state: OpRunState;
+  /** ISO-8601 instant the run started. */
+  startedAt: string;
+  /** ISO-8601 instant the run settled; absent while it is still running. */
+  endedAt?: string;
+  /** Per-step records, when the runtime has them. */
+  records?: StepRecord[];
+  /** The executor's own result, when the runtime is executing in this process. */
+  result?: OpRunResult;
+  /** The gate this run is waiting on, when `state` is `gated`. */
+  gate?: { name: string; since: string };
+  /** Free-text detail for a failed run. */
+  error?: string;
+}
+
+/**
+ * One immutable, settled Op run — the run ledger's line
+ * (`../lifecycle/run-ledger.ts`), and what `chant run log <op>` prints a row
+ * per.
+ *
+ * This is where a run's outcome lives now that `OpConfig` no longer carries
+ * `searchAttributes` for the generated workflow to upsert (#2118). `labels` is
+ * copied off the declaration so a reader can filter runs the way it filters
+ * declarations; `outcomes` is every `outcomeAttribute` the run captured, later
+ * steps winning over earlier ones for a repeated name, exactly as an upsert
+ * would have.
+ */
+export interface OpRunRecord {
+  /** Schema version, so an incompatible future shape is detected before being misread. */
+  version: 1;
+  /** Stable run id — the same string a pending gate fact records for this run. */
+  id: string;
+  /** The Op's name (`OpConfig.name`). */
+  op: string;
+  /** The Op's `labels.Env`, or `local` when it declares none. */
+  env: string;
+  /** ISO-8601 instant the run started. */
+  started: string;
+  /** ISO-8601 instant the run settled. */
+  ended: string;
+  /**
+   * The executor's three-state outcome. `gated` is neither success nor
+   * failure: the run reached a gate nobody has approved, recorded the fact,
+   * and stopped (#2119).
+   */
+  status: "ok" | "fail" | "gated";
+  /** The Op's own `labels`, copied at run time. */
+  labels: Record<string, string>;
+  /** Every `outcomeAttribute` the run captured, name → value. */
+  outcomes: Record<string, unknown>;
+  /** Per-phase, per-step status, in execution order. */
+  phases: OpRunPhaseRecord[];
+  /** The gate the run stopped on, for `status: "gated"`. */
+  gate?: { name: string; since: string };
+}
+
+/** An {@link OpRunRecord} before the ledger stamps its version and mints an id. */
+export type OpRunRecordInput = Omit<OpRunRecord, "version" | "id"> & { id?: string };
+
+/** A started run. `result()` settles with the run's final status. */
+export interface OpRunHandle {
+  op: string;
+  runId: string;
+  result(): Promise<OpRunStatus>;
+}
+
+/** What a caller hands a runtime when it starts a run. */
+export interface OpRunStartOptions {
+  /** Build-time parameter bindings, when the caller resolved any. */
+  params?: Record<string, unknown>;
+  /** Target environment (`--env`). */
+  env?: string;
+  /**
+   * `-p, --profile <name>` (#2124, restored in #2192) — the named connection
+   * profile this runtime should target. Only a runtime that has profiles
+   * reads it; the local one ignores it, and a runtime that reads it decides
+   * for itself what an unknown name means (fountain refuses it rather than
+   * falling back to its default).
+   */
+  profile?: string;
+  /** Called once per settled step, so `--progress-json` can stream. */
+  progress?: (record: StepRecord) => void;
+  /** Aborts in-flight work (Ctrl-C). */
+  signal?: AbortSignal;
+}
+
+/**
+ * The contract a runtime implements to host Op runs.
+ *
+ * `chant run` resolves exactly one provider per invocation — the named
+ * lexicon's for `--on <name>`, the built-in `local` one otherwise — and every
+ * subcommand calls it. A provider that cannot do something (cancel a
+ * foreground run, host components) says so by throwing a message the CLI
+ * prints verbatim, or by omitting the optional member.
+ */
+export interface OpRuntimeProvider {
+  /** How the CLI names this runtime in messages, and what `--on` matches. */
+  readonly name: string;
+
+  /** Start a run. Rejects with an actionable Error when it cannot. */
+  start(op: OpConfig, opts: OpRunStartOptions): Promise<OpRunHandle>;
+
+  /** The latest run's state, or `undefined` when this runtime has none recorded. */
+  status(op: string): Promise<OpRunStatus | undefined>;
+
+  /** Run history, newest first. Empty when nothing is recorded. */
+  log(op: string, opts?: { limit?: number }): Promise<OpRunRecord[]>;
+
+  /** Latest state for each of `ops`, keyed by op name. */
+  list(ops: OpConfig[]): Promise<Map<string, OpRunStatus | undefined>>;
+
+  /** Cancel the active run. `force` is the CLI's confirmation, already checked. */
+  cancel(op: string, opts: { force: boolean }): Promise<void>;
+
+  /**
+   * Wake a run whose gate has just been resolved. The ledger write is the
+   * fact and `chant approve` owns it; this is the runtime's chance to act on
+   * it. Omit when a run re-reads the ledger on its own.
+   */
+  resolveGate?(op: string, gate: string, resolution: GateResolutionRecord): Promise<void>;
+
+  /**
+   * Host `chant run --components`. Optional: a runtime without it refuses the
+   * flag with one line naming itself.
+   */
+  runComponents?(
+    projectPath: string,
+    selector: string,
+    options: RunComponentsOptions,
+  ): Promise<RunComponentsResult>;
+}