@intentius/chant 0.57.0 → 0.59.0

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,34 @@
  */
 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";
+import { createChangeSignalGate, DEFAULT_SIGNAL_FLOOR_MS, type WakeReason } from "./change-signal";
+import type { ChangeSubscription } from "../lexicon";
 
-/** 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 +78,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 +109,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 +135,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 +178,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 });
     }
   }
@@ -172,11 +213,67 @@ function sleepAbortable(ms: number, signal?: AbortSignal): Promise<void> {
   });
 }
 
+/**
+ * One lexicon's change-signal seam, already bound to an environment (#1981).
+ *
+ * The loop never sees a `LexiconPlugin`: core's operator does not import
+ * plugins, and binding happens where plugins are already loaded
+ * (`collectChangeSubscribers` in `../cli/plugins.ts`), the same extract-then-
+ * thread shape `collectBuildRootContributors` uses for build roots.
+ */
+export interface ChangeSubscriber {
+  /** Which lexicon supplies the signal. Log lines only; never a fact. */
+  lexicon: string;
+  subscribe(ctx: {
+    onChange: () => void;
+    onError: (message: string) => void;
+    signal: AbortSignal;
+  }): Promise<ChangeSubscription>;
+}
+
+/**
+ * What the loop's change-signal machinery reports, alongside the per-op tick
+ * events. Separate from {@link OperatorTickEvent} on purpose: none of this is
+ * about an Op, and none of it is an observation.
+ */
+export type OperatorSignalEvent =
+  /** A lexicon's subscription is live and the loop may now wake early. */
+  | { kind: "subscribed"; lexicon: string }
+  /** Establishing it failed. The loop keeps its timer and retries next round. */
+  | { kind: "subscribe-failed"; lexicon: string; error: string }
+  /** A live subscription died. Reported once; the next round re-subscribes. */
+  | { kind: "subscription-lost"; lexicon: string; error: string }
+  /** A signal shortened the sleep. The round that follows is an ordinary round. */
+  | { kind: "woken"; afterMs: number };
+
+/** Render one signal event as `chant operator`'s log line shape. */
+export function formatSignalLine(event: OperatorSignalEvent): string {
+  switch (event.kind) {
+    case "subscribed":
+      return `operator: ${event.lexicon} change signal subscribed (the timer still runs)`;
+    case "subscribe-failed":
+      return `operator: ${event.lexicon} change signal unavailable, polling on the timer (${event.error})`;
+    case "subscription-lost":
+      return `operator: ${event.lexicon} change signal lost, polling on the timer until the next round re-subscribes (${event.error})`;
+    case "woken":
+      return `operator: woken by a change signal after ${event.afterMs}ms, running an ordinary round`;
+  }
+}
+
 export interface OperatorLoopOptions extends OperatorRoundOptions {
   /** @default DEFAULT_OPERATOR_INTERVAL_MS */
   intervalMs?: number;
   /** Called after every round completes — the CLI's one-line-per-tick log lives here, not inside the loop itself, so a test can drive rounds without capturing stdout. */
   onRound?: (events: OperatorTickEvent[]) => void;
+  /**
+   * Change-signal seams to keep subscribed for the life of the loop (#1981).
+   * Omitted, or empty, and the loop is exactly what it was: a timer.
+   */
+  subscribers?: readonly ChangeSubscriber[];
+  /** @default DEFAULT_SIGNAL_FLOOR_MS. The shortest gap a signal may force between two rounds. */
+  signalFloorMs?: number;
+  /** Called for every subscription and wake event. The CLI logs one line each. */
+  onSignalEvent?: (event: OperatorSignalEvent) => void;
 }
 
 /**
@@ -185,14 +282,97 @@ export interface OperatorLoopOptions extends OperatorRoundOptions {
  * (issue: "if it dies, nothing breaks and nothing is lost") — this function
  * is exactly `while (!aborted) { round(); sleep(); }`, nothing durable lives
  * in its own memory that a restart would need to recover.
+ *
+ * With `subscribers` (#1981) the sleep gains a second wake source, and only a
+ * wake source. A signal aborts the current sleep; the round that follows is
+ * the same round the timer would have run, deriving everything from a fresh
+ * observation. Nothing a subscription reports reaches a tick, because the
+ * seam has nowhere to put it: `onChange` takes no arguments.
  */
 export async function runOperatorForever(opts: OperatorLoopOptions): Promise<void> {
   const holder = opts.holder ?? currentHolderId();
-  while (!opts.signal?.aborted) {
-    const events = await runOperatorRound({ ...opts, holder });
-    opts.onRound?.(events);
-    if (opts.signal?.aborted) break;
-    await sleepAbortable(opts.intervalMs ?? DEFAULT_OPERATOR_INTERVAL_MS, opts.signal);
+  // 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>();
+  const intervalMs = opts.intervalMs ?? DEFAULT_OPERATOR_INTERVAL_MS;
+  const subscribers = opts.subscribers ?? [];
+
+  // Nothing to subscribe to: the loop below is byte for byte the loop that
+  // shipped before #1981, and takes none of the machinery's cost.
+  if (subscribers.length === 0) {
+    while (!opts.signal?.aborted) {
+      const events = await runOperatorRound({ ...opts, holder, scheduleState });
+      opts.onRound?.(events);
+      if (opts.signal?.aborted) break;
+      await sleepAbortable(intervalMs, opts.signal);
+    }
+    return;
+  }
+
+  const gate = createChangeSignalGate({ floorMs: opts.signalFloorMs ?? DEFAULT_SIGNAL_FLOOR_MS });
+  // The subscriptions the loop currently holds, by lexicon. A lexicon absent
+  // from this map is one to (re-)subscribe on the next round, which is how a
+  // killed watch comes back without a special retry path.
+  const live = new Map<string, ChangeSubscription>();
+  // Stops every subscription at once when the loop ends, whatever ends it.
+  const subscriptionsAbort = new AbortController();
+
+  const closeAll = async (): Promise<void> => {
+    subscriptionsAbort.abort();
+    const open = [...live.values()];
+    live.clear();
+    // A close that throws must not mask why the loop is unwinding.
+    await Promise.allSettled(open.map((s) => s.close()));
+  };
+
+  const ensureSubscribed = async (): Promise<void> => {
+    for (const subscriber of subscribers) {
+      if (live.has(subscriber.lexicon) || subscriptionsAbort.signal.aborted) continue;
+      try {
+        const subscription = await subscriber.subscribe({
+          onChange: () => gate.signal(),
+          onError: (error) => {
+            // Reported once, then forgotten: dropping it from `live` is what
+            // makes the next round re-subscribe. The loop itself is untouched.
+            if (!live.delete(subscriber.lexicon)) return;
+            opts.onSignalEvent?.({ kind: "subscription-lost", lexicon: subscriber.lexicon, error });
+          },
+          signal: subscriptionsAbort.signal,
+        });
+        live.set(subscriber.lexicon, subscription);
+        opts.onSignalEvent?.({ kind: "subscribed", lexicon: subscriber.lexicon });
+      } catch (err) {
+        // A subscription that cannot be established is a slower loop, never a
+        // stopped one: report it and fall through to the timer.
+        opts.onSignalEvent?.({
+          kind: "subscribe-failed",
+          lexicon: subscriber.lexicon,
+          error: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+  };
+
+  try {
+    while (!opts.signal?.aborted) {
+      gate.roundStarted();
+      const startedAt = Date.now();
+      const events = await runOperatorRound({ ...opts, holder, scheduleState });
+      opts.onRound?.(events);
+      if (opts.signal?.aborted) break;
+
+      await ensureSubscribed();
+      if (opts.signal?.aborted) break;
+
+      const reason: WakeReason = await gate.wait(intervalMs, opts.signal);
+      if (reason === "signal") {
+        opts.onSignalEvent?.({ kind: "woken", afterMs: Date.now() - startedAt });
+      }
+    }
+  } finally {
+    await closeAll();
   }
 }
 
@@ -200,9 +380,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>;
+}