@intentius/chant 0.124.13 → 0.124.14

package/dist/op/receipt-store.js

@@ -0,0 +1,94 @@
+/**
+ * Receipt store seam (#1834, epic #1703) — how the `effect()` step and the
+ * receipt-reading Ops reach a materialized receipt without knowing which
+ * lexicon materializes it.
+ *
+ * The store is injectable: core defines the {@link ReceiptStore} interface and
+ * the activity contracts; the receipt row's lexicon implements the store over
+ * its own resource (#1835's aws row over `AWS::SSM::Parameter`) and exports
+ * the bound activities (`receiptRead`, `receiptWrite`, `receiptStaleness`)
+ * from its `op/activities` module via {@link receiptActivities}. The activity
+ * registry then resolves them by name, exactly like `ensureSecret`
+ * (#1829/#1830, provided by the k8s lexicon). Tests bind a mock store the
+ * same way.
+ *
+ * Write discipline (epic #1703 decision log, item 3): the `effect()` step is
+ * the SOLE writer of a receipt — on success of its nested steps, last. The
+ * store interface carries a `write`, but only the effect step's emitted
+ * read-compare-run-write (and its local-executor twin) reaches it.
+ * `receiptStaleness` — the WatchOp phase (#1834) — is read-only by
+ * construction: it never touches `write` and runs nothing.
+ *
+ * Expectation resolution follows the resolution split (decision 5): a fully
+ * static receipt's expectation is stamped at synthesis and rides the step
+ * data ({@link receiptCheckInput}); a hash-flavor receipt with reference
+ * inputs resolves at run, through the store lexicon's
+ * {@link ReceiptActivityOptions.resolveExpectation} hook — never by hashing
+ * placeholders.
+ */
+import { EXISTENCE_EXPECTATION, isEffectReceipt, receiptExpectation, referenceInputPaths, } from "../effect-receipt.js";
+/**
+ * Snapshot a typed receipt declaration into check-input data: the
+ * {@link EffectReceiptRef} plus the synthesis-time expectation when the
+ * receipt is fully static. Used by the `effect()` builder and by WatchOp's
+ * staleness phase — the single place "static enough to hash now" is decided.
+ */
+export function receiptCheckInput(receipt) {
+    if (!isEffectReceipt(receipt)) {
+        throw new Error("receiptCheckInput: expected an EffectReceipt declaration — import the exported const; there is no string form");
+    }
+    const ref = {
+        name: receipt.name,
+        effect: receipt.effect,
+        flavor: receipt.flavor,
+        inputs: receipt.inputs,
+    };
+    // An existence receipt's expectation is a constant, references or not; a
+    // hash receipt is static only when no reference inputs remain.
+    const isStatic = receipt.flavor === "existence" || referenceInputPaths(receipt).length === 0;
+    return isStatic ? { receipt: ref, expectation: receiptExpectation(receipt) } : { receipt: ref };
+}
+/**
+ * Bind the receipt activities to a store. The store's lexicon calls this once
+ * and re-exports the result from its `op/activities` module; the activity
+ * registry picks the functions up by name for both executors.
+ */
+export function receiptActivities(store, opts) {
+    const expectationOf = async (input) => {
+        if (input.expectation !== undefined)
+            return input.expectation;
+        if (input.receipt.flavor === "existence")
+            return EXISTENCE_EXPECTATION;
+        if (opts?.resolveExpectation)
+            return await opts.resolveExpectation(input.receipt);
+        throw new Error(`receipt "${input.receipt.name}": no synthesis-time expectation and no resolveExpectation hook — ` +
+            `a hash-flavor receipt with reference inputs resolves at run (#1703 decision 5), ` +
+            `and hashing placeholders would be a wrong expectation`);
+    };
+    return {
+        async receiptRead(args) {
+            const expectation = await expectationOf(args);
+            const current = await store.read(args.receipt);
+            return { current: current ?? null, expectation, applied: current === expectation };
+        },
+        async receiptWrite(args) {
+            await store.write(args.receipt, args.expectation);
+            return { written: true, receipt: args.receipt.name };
+        },
+        // Read-only: reads and reports, runs nothing, never writes.
+        async receiptStaleness(args) {
+            const findings = [];
+            for (const input of args.receipts) {
+                const expected = await expectationOf(input);
+                const current = await store.read(input.receipt);
+                if (current === undefined) {
+                    findings.push({ receipt: input.receipt.name, effect: input.receipt.effect, kind: "absent", expected });
+                }
+                else if (current !== expected) {
+                    findings.push({ receipt: input.receipt.name, effect: input.receipt.effect, kind: "differs", expected, current });
+                }
+            }
+            return { stale: findings.length > 0, findings };
+        },
+    };
+}

package/dist/op/resource.js

@@ -0,0 +1,23 @@
+import { createResource } from "../runtime.js";
+/**
+ * The Declarable resource backing an Op definition.
+ * 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 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) {
+    return entity?.entityType === OP_ENTITY_TYPE;
+}

package/dist/op/run-context.js

@@ -0,0 +1,28 @@
+/**
+ * The run an activity is part of (#2522).
+ *
+ * An activity is called as `fn(args, signal)`, which says nothing about the
+ * run around it. An activity that deploys somewhere needs the environment the
+ * run was asked for, one that appends a ledger record of its own needs the run
+ * id to name the run that made it, and a step after a gate may need to know the
+ * gate passed and who approved it.
+ *
+ * `runOpLocally` (`./local-executor.ts`) sets this for the whole run, and
+ * {@link currentOpRun} reads it from inside an activity. It is backed by
+ * `AsyncLocalStorage`, so it follows the activity through every `await` and is
+ * `undefined` outside a run.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+const store = new AsyncLocalStorage();
+/**
+ * The run the calling activity is part of, or `undefined` outside a run.
+ * `passedGates` is a copy taken at the time of the call.
+ */
+export function currentOpRun() {
+    const ctx = store.getStore();
+    return ctx ? { ...ctx, passedGates: [...ctx.passedGates] } : undefined;
+}
+/** Run `fn` with `ctx` as the current run. The executor calls this. A runtime that calls activities itself can too. */
+export function withOpRunContext(ctx, fn) {
+    return store.run(ctx, fn);
+}

package/dist/op/run-live.js

@@ -0,0 +1,256 @@
+/**
+ * The in-flight run record: what an Op run is doing while it runs.
+ *
+ * The run ledger (`../lifecycle/run-ledger.ts`) gets one record when a run
+ * settles, so until then a reader sees the previous run. A run that writes to
+ * the ledger (the executor's `ledger` option) also keeps two files beside the
+ * checkout's git directory, outside the working tree and the lifecycle branch:
+ *
+ * - `<git-common-dir>/chant/runs/<key>.json`, the run's id, steward, work
+ *   item, current phase and step, and the phases it has finished with their
+ *   durations, rewritten whole as the run moves;
+ * - `<git-common-dir>/chant/runs/<key>.activity.jsonl`, lines a step's
+ *   process appends while it works, one per line.
+ *
+ * `<key>` folds the member's ledger prefix, the env and the Op's name into one
+ * file name. Both files are removed once the run's ledger record is written.
+ * A run that died without removing them is recognised by its process: a record
+ * whose host is this one and whose pid is gone is not in flight.
+ *
+ * A step's process finds the activity file in `CHANT_RUN_ACTIVITY`, which the
+ * `shellCmd` activity sets for a run that keeps one, and appends a line to it:
+ * a JSON object `{"at": "<ISO-8601>", "text": "..."}`, or plain text. An
+ * in-process activity calls {@link reportRunActivity}.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+import { execFile } from "node:child_process";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { hostname } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+import { promisify } from "node:util";
+import { resolveMemberLedger } from "../lifecycle/member-ledger.js";
+const execFileAsync = promisify(execFile);
+/** The environment variable naming the activity file, for a step's process. */
+export const RUN_ACTIVITY_ENV = "CHANT_RUN_ACTIVITY";
+/** The environment variable naming the run, for a step's process. */
+export const RUN_ID_ENV = "CHANT_RUN_ID";
+/** How many activity lines a reader gets by default: the newest ones. */
+export const IN_FLIGHT_ACTIVITY_LINES = 20;
+/** The file name a run's record is kept under, the prefix and env folded in. */
+function keyOf(prefix, env, op) {
+    return `${prefix}${env}/${op}`.replace(/[\/\\]/g, "__").replace(/[^A-Za-z0-9._@-]/g, "_");
+}
+/** The checkout's shared git directory (the same for every worktree), or null outside a checkout. */
+async function gitCommonDir(cwd) {
+    try {
+        const { stdout } = await execFileAsync("git", ["rev-parse", "--git-common-dir"], { cwd });
+        const dir = stdout.trim();
+        return dir === "" ? null : isAbsolute(dir) ? dir : resolve(cwd, dir);
+    }
+    catch {
+        return null;
+    }
+}
+/** Where the run of `op` in `env` for the project at `cwd` keeps its files, or null outside a checkout. */
+export async function inFlightPaths(cwd, env, op) {
+    const common = await gitCommonDir(cwd);
+    if (!common)
+        return null;
+    const { prefix } = await resolveMemberLedger(cwd);
+    const base = join(common, "chant", "runs", keyOf(prefix, env, op));
+    return { record: `${base}.json`, activity: `${base}.activity.jsonl` };
+}
+function processAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === "EPERM";
+    }
+}
+/** One activity line appended to `file`. Never throws: a report is not worth failing a step for. */
+function appendActivity(file, text) {
+    const line = text.replace(/\s+/g, " ").trim();
+    if (line === "")
+        return;
+    try {
+        appendFileSync(file, `${JSON.stringify({ at: new Date().toISOString(), text: line })}\n`);
+    }
+    catch {
+        // The run's files are gone or unwritable: the line is dropped.
+    }
+}
+/**
+ * A running Op's in-flight record. The executor opens one per run that
+ * writes to the ledger and calls it as the run moves. Every write is
+ * best-effort: a record that can't be written leaves the run as it was.
+ */
+export class LiveRun {
+    constructor(paths, rec) {
+        this.paths = paths;
+        this.running = [];
+        this.rec = rec;
+    }
+    /** Open the record for a run starting now, or undefined when the project is not a checkout. */
+    static async open(opts) {
+        let paths;
+        try {
+            paths = await inFlightPaths(opts.cwd, opts.env, opts.op);
+        }
+        catch {
+            return undefined;
+        }
+        if (!paths)
+            return undefined;
+        const run = new LiveRun(paths, {
+            version: 1,
+            id: opts.id,
+            op: opts.op,
+            env: opts.env,
+            steward: opts.steward ?? null,
+            item: null,
+            started: opts.started,
+            updated: opts.started,
+            host: hostname(),
+            pid: process.pid,
+            phase: null,
+            step: null,
+            phases: [],
+        });
+        try {
+            mkdirSync(join(paths.record, ".."), { recursive: true });
+            writeFileSync(paths.activity, "");
+        }
+        catch {
+            return undefined;
+        }
+        run.write();
+        return run;
+    }
+    /** The file a step's process appends activity lines to. */
+    get activityFile() {
+        return this.paths.activity;
+    }
+    get id() {
+        return this.rec.id;
+    }
+    phaseStarted(name) {
+        this.rec.phase = { name, started: new Date().toISOString() };
+        this.write();
+    }
+    phaseEnded(name, status, durationMs) {
+        this.rec.phases.push({ name, status, durationMs });
+        if (this.rec.phase?.name === name)
+            this.rec.phase = null;
+        this.write();
+    }
+    /** A step started; the returned function says it ended. */
+    stepStarted(fn, id) {
+        const step = { name: id ?? fn, fn, started: new Date().toISOString() };
+        this.running.push(step);
+        this.rec.step = step;
+        this.write();
+        return () => {
+            const at = this.running.indexOf(step);
+            if (at >= 0)
+                this.running.splice(at, 1);
+            this.rec.step = this.running.at(-1) ?? null;
+            this.write();
+        };
+    }
+    item(item) {
+        this.rec.item = item;
+        this.write();
+    }
+    report(text) {
+        appendActivity(this.paths.activity, text);
+    }
+    /** The run has settled and its ledger record is written: remove its files. */
+    close() {
+        for (const file of [this.paths.record, this.paths.activity]) {
+            try {
+                rmSync(file, { force: true });
+            }
+            catch {
+                // Left behind; a reader drops it once this process is gone.
+            }
+        }
+    }
+    write() {
+        this.rec.updated = new Date().toISOString();
+        const tmp = `${this.paths.record}.${process.pid}.tmp`;
+        try {
+            writeFileSync(tmp, JSON.stringify(this.rec));
+            renameSync(tmp, this.paths.record);
+        }
+        catch {
+            // Best-effort, as the module doc says.
+        }
+    }
+}
+const context = new AsyncLocalStorage();
+/** Run `fn` as part of `live`'s run, so the steps under it find it. */
+export function withLiveRun(live, fn) {
+    return live ? context.run(live, fn) : fn();
+}
+/** The run the calling step is part of, when it keeps an in-flight record. */
+export function currentLiveRun() {
+    return context.getStore();
+}
+/** The variables a step's child process gets so it can report activity. Empty outside such a run. */
+export function liveRunEnv() {
+    const live = context.getStore();
+    return live ? { [RUN_ACTIVITY_ENV]: live.activityFile, [RUN_ID_ENV]: live.id } : {};
+}
+/** Append an activity line to the run the calling activity is part of. A no-op outside one. */
+export function reportRunActivity(text) {
+    context.getStore()?.report(text);
+}
+function parseActivity(content, limit) {
+    const raw = content.split("\n").filter((l) => l.trim() !== "");
+    const from = Math.max(0, raw.length - limit);
+    const lines = raw.slice(from).map((line, i) => {
+        const seq = from + i + 1;
+        try {
+            const parsed = JSON.parse(line);
+            if (parsed && typeof parsed === "object" && typeof parsed.text === "string") {
+                return { seq, at: typeof parsed.at === "string" ? parsed.at : null, text: parsed.text };
+            }
+        }
+        catch {
+            // Plain text.
+        }
+        return { seq, at: null, text: line.trim() };
+    });
+    return { total: raw.length, lines };
+}
+/**
+ * The run of `op` in `env` in flight for the project at `cwd`, with its
+ * newest `limit` activity lines, or null when none is. A record left by a
+ * process on this host that is gone is not in flight.
+ */
+export async function readInFlightRun(cwd, env, op, limit = IN_FLIGHT_ACTIVITY_LINES) {
+    const paths = await inFlightPaths(cwd, env, op);
+    if (!paths || !existsSync(paths.record))
+        return null;
+    let rec;
+    try {
+        rec = JSON.parse(readFileSync(paths.record, "utf8"));
+    }
+    catch {
+        return null;
+    }
+    if (rec.version !== 1 || typeof rec.id !== "string" || typeof rec.started !== "string")
+        return null;
+    if (rec.host === hostname() && typeof rec.pid === "number" && !processAlive(rec.pid))
+        return null;
+    let content = "";
+    try {
+        content = readFileSync(paths.activity, "utf8");
+    }
+    catch {
+        // No activity yet.
+    }
+    return { ...rec, phases: Array.isArray(rec.phases) ? rec.phases : [], activity: parseActivity(content, limit) };
+}

package/dist/op/runtime.js

@@ -0,0 +1,21 @@
+/**
+ * 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.
+ */
+/** Map a settled run's ledger status onto the coarser runtime state. */
+export function runStateOf(status) {
+    return status === "ok" ? "completed" : status === "gated" ? "gated" : status === "waiting" ? "waiting" : "failed";
+}

package/dist/op/runtimes/local.js

@@ -0,0 +1,195 @@
+/**
+ * The built-in `local` op runtime (#2121, epic #2114).
+ *
+ * Wraps `runOpLocally` (../local-executor.ts) in the {@link OpRuntimeProvider}
+ * contract so `chant run <op>` has one dispatch path whether the run is hosted
+ * here or by a lexicon's `opRuntime`. Behaviour is the executor's, unchanged:
+ * activities and profiles come from the project's configured lexicons, a gate
+ * is decided against the gate ledger and ends the run `gated` (#2119), and
+ * Ctrl-C aborts through the caller's `AbortSignal`.
+ *
+ * Status, log and list read the run ledger (#2118): every run this provider
+ * starts appends one `OpRunRecord` to `<env>/runs__<op>.jsonl` on the
+ * lifecycle branch, so an answer here outlives the process that produced it
+ * and a run started by cron, CI or another machine is visible too. The
+ * in-memory history stays as the fallback for the case the ledger cannot cover
+ * — a project that is not a checkout, or a run whose append failed — so a
+ * `chant run` followed by `chant run status` in the same process still
+ * answers.
+ */
+import { lexiconNames } from "../../lexicon-module.js";
+import { loadChantConfig } from "../../config.js";
+import { loadActivities, loadProfiles } from "../activity-registry.js";
+import { runOpLocally, OpRunFailure } from "../local-executor.js";
+import { runComponents } from "../../components/cli-support.js";
+import { discoverOps } from "../discover.js";
+import { readRunLedger, runEnvOf, DEFAULT_RUN_ENV } from "../../lifecycle/run-ledger.js";
+import { runStateOf, } from "../runtime.js";
+function statusFrom(op, runId, startedAt, result) {
+    return {
+        op,
+        runId,
+        state: runStateOf(result.status),
+        startedAt,
+        endedAt: new Date().toISOString(),
+        records: result.records,
+        result,
+        ...(result.gate ? { gate: { name: result.gate.gate, since: result.gate.timestamp, ...(result.gate.op !== op ? { op: result.gate.op } : {}) } } : {}),
+        ...(result.record.point ? { point: result.record.point } : {}),
+    };
+}
+/**
+ * A ledger record read back as a runtime status. `records` and `result` are
+ * absent on purpose: the ledger keeps each step's verdict, not the activity
+ * return values a live `OpRunResult` carries, and inventing them would make a
+ * replayed answer look like a live one.
+ */
+function statusFromRecord(record) {
+    return {
+        op: record.op,
+        runId: record.id,
+        state: runStateOf(record.status),
+        startedAt: record.started,
+        endedAt: record.ended,
+        ...(record.gate ? { gate: record.gate } : {}),
+        ...(record.point ? { point: record.point } : {}),
+    };
+}
+/**
+ * Build the local provider. `projectPath` is where `chant.config.ts` is read
+ * from to decide which cloud appliers to load — the same best-effort read the
+ * CLI did inline before the seam existed.
+ */
+export function createLocalOpRuntime(opts = {}) {
+    const runs = new Map();
+    const projectPath = opts.projectPath ?? process.cwd();
+    const record = (status) => {
+        const existing = runs.get(status.op);
+        if (existing)
+            existing.push(status);
+        else
+            runs.set(status.op, [status]);
+    };
+    // A run ledger is keyed `<env>/runs__<op>.jsonl`, and `status`/`log` are
+    // handed a name rather than a config. `start` and `list` know the config and
+    // seed this; otherwise the same `*.op.ts` scan that found the Op in the
+    // first place resolves its `labels.Env`.
+    const envs = new Map();
+    const noteEnv = (op) => {
+        const env = runEnvOf(op);
+        envs.set(op.name, env);
+        return env;
+    };
+    const envFor = async (op) => {
+        const known = envs.get(op);
+        if (known)
+            return known;
+        try {
+            const { ops } = await discoverOps({ cwd: projectPath });
+            for (const discovered of ops.values())
+                noteEnv(discovered.config);
+        }
+        catch {
+            // Not a checkout — nothing to scan; fall through to the default env.
+        }
+        return envs.get(op) ?? DEFAULT_RUN_ENV;
+    };
+    /** This op's ledger history, oldest first. Empty when there is no ledger to read. */
+    const ledgerFor = async (op, env) => {
+        try {
+            const { records } = await readRunLedger(env ?? (await envFor(op)), op, { cwd: projectPath });
+            return records;
+        }
+        catch {
+            return [];
+        }
+    };
+    return {
+        name: "local",
+        async start(op, startOpts) {
+            // The project's configured lexicons decide which cloud appliers to load
+            // (aws -> floci, gcp -> gcpApply, azure -> az group). Best-effort: an
+            // unreadable config just yields the base activities.
+            let lexicons = [];
+            try {
+                lexicons = lexiconNames((await loadChantConfig(projectPath)).config.lexicons ?? []);
+            }
+            catch {
+                // No/invalid chant.config — base activities only.
+            }
+            const [activities, profiles] = await Promise.all([loadActivities(lexicons), loadProfiles()]);
+            // A caller that names the run (#3539: `chant acp` on fountain passes the
+            // conversation id) gets its id on the record; otherwise one is minted.
+            const runId = startOpts.runId ?? `local-${Date.now()}`;
+            const startedAt = new Date().toISOString();
+            noteEnv(op);
+            const settled = (async () => {
+                try {
+                    const result = await runOpLocally(op, activities, profiles, startOpts.signal, {
+                        runId,
+                        // #2522: `--env` reaches the activities through the run context.
+                        ...(startOpts.env !== undefined ? { env: startOpts.env } : {}),
+                        // The run's outcome is a durable fact (#2118): the executor
+                        // appends it here, at the one seam every local run passes
+                        // through, rather than in the CLI handler above it.
+                        ledger: { cwd: projectPath },
+                        // #2301: the run-ledger append goes through the same
+                        // `chant/lifecycle` write as the gate does, so it dies for the
+                        // same reasons — and this runtime declared no sink for it, so
+                        // the failure was caught by `settle` and dropped on the floor.
+                        // A run whose outcome never reached the ledger says so now;
+                        // `chant run status` and `chant run log` will not have it.
+                        onLedgerError: (err) => process.stderr.write(`warning: run "${runId}" of "${op.name}" finished, but its record could not be ` +
+                            `appended to the run ledger: ${err instanceof Error ? err.message : String(err)}\n`),
+                        ...(startOpts.progress ? { onRecord: startOpts.progress } : {}),
+                        ...(startOpts.work ? { work: startOpts.work } : {}),
+                        onWorkLeaseWarning: (message) => process.stderr.write(`warning: "${op.name}" could not renew its work lease, retrying at the next beat: ${message}\n`),
+                    });
+                    const status = statusFrom(op.name, runId, startedAt, result);
+                    record(status);
+                    return status;
+                }
+                catch (err) {
+                    if (err instanceof OpRunFailure) {
+                        const status = statusFrom(op.name, runId, startedAt, err.result);
+                        record(status);
+                        return status;
+                    }
+                    throw err;
+                }
+            })();
+            return { op: op.name, runId, result: () => settled };
+        },
+        async status(op) {
+            const newest = (await ledgerFor(op)).at(-1);
+            if (newest)
+                return statusFromRecord(newest);
+            const history = runs.get(op);
+            return history?.[history.length - 1];
+        },
+        async log(op, logOpts) {
+            const history = (await ledgerFor(op)).reverse();
+            return logOpts?.limit === undefined ? history : history.slice(0, logOpts.limit);
+        },
+        async list(ops) {
+            const out = new Map();
+            for (const op of ops) {
+                const newest = (await ledgerFor(op.name, noteEnv(op))).at(-1);
+                if (newest) {
+                    out.set(op.name, statusFromRecord(newest));
+                    continue;
+                }
+                const history = runs.get(op.name);
+                out.set(op.name, history?.[history.length - 1]);
+            }
+            return out;
+        },
+        async cancel(op) {
+            throw new Error(`the local runtime runs "${op}" in the foreground — there is no detached run to cancel. ` +
+                `Press Ctrl-C in the terminal running it, or pass --on <lexicon> for a hosted run.`);
+        },
+        runComponents(path, selector, options) {
+            return runComponents(path, selector, options);
+        },
+    };
+}