@intentius/chant 0.124.27 → 0.124.29

package/dist/run-event-store.js

@@ -0,0 +1,251 @@
+/**
+ * Where a run's events are kept on this host, and how to read them back
+ * (#4042). `chant run events <run>` replays a run from here and `--follow`
+ * tails it.
+ *
+ * Each run gets one file, `<git-common-dir>/chant/run-events/<run id>.jsonl`,
+ * holding the lines the one writer (`./run-event.ts`) produced, byte for byte
+ * as `--events-json` prints them. It sits beside the in-flight records
+ * (`./op/run-live.ts`), outside the working tree and off `chant/lifecycle`:
+ * the run ledger's growth is #4036's concern and these files add none to it.
+ * Unlike the in-flight record they are kept after the run settles, until
+ * `chant lifecycle gc --yes` deletes the ones its retention policy lets go
+ * (#4036, {@link planRunEventPrune}).
+ *
+ * Every write is best-effort. A run whose events cannot be kept still runs.
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { gitCommonDir } from "./op/run-live.js";
+/** The directory name under `<git-common-dir>/chant/` that holds the files. */
+export const RUN_EVENTS_DIR = "run-events";
+/** The file name a run id is kept under: anything that is not a plain file-name character becomes `_`. */
+export function runEventFileName(runId) {
+    return `${runId.replace(/[^A-Za-z0-9._@-]/g, "_")}.jsonl`;
+}
+/**
+ * The environment variable that names the directory run events are kept in,
+ * in place of the checkout's. The test suite sets it to a per-run temp
+ * directory, so no test writes to the real repository's store (worktrees
+ * share one git directory).
+ */
+export const RUN_EVENTS_DIR_ENV = "CHANT_RUN_EVENTS_DIR";
+/** The directory the checkout at `cwd` keeps run events in (`CHANT_RUN_EVENTS_DIR` when set), or null outside a checkout. */
+export async function runEventsDir(cwd) {
+    const override = process.env[RUN_EVENTS_DIR_ENV];
+    if (override)
+        return override;
+    const common = await gitCommonDir(cwd);
+    return common ? join(common, "chant", RUN_EVENTS_DIR) : null;
+}
+/** Open the file for `runId`, or undefined outside a checkout or where it cannot be created. */
+export async function openRunEventStore(cwd, runId) {
+    let dir;
+    try {
+        dir = await runEventsDir(cwd);
+    }
+    catch {
+        return undefined;
+    }
+    if (!dir)
+        return undefined;
+    const path = join(dir, runEventFileName(runId));
+    try {
+        mkdirSync(dir, { recursive: true });
+        // A run id used again (a re-run of the same CI run) replaces the earlier stream.
+        writeFileSync(path, "");
+    }
+    catch {
+        return undefined;
+    }
+    return {
+        path,
+        write(line) {
+            try {
+                appendFileSync(path, line);
+            }
+            catch {
+                // The directory is gone or unwritable: the line is dropped.
+            }
+        },
+    };
+}
+/** A write function that hands each line to every function given, or undefined when none is. */
+export function teeLines(...writes) {
+    const live = writes.filter((w) => w !== undefined);
+    if (live.length === 0)
+        return undefined;
+    if (live.length === 1)
+        return live[0];
+    return (line) => {
+        for (const w of live)
+            w(line);
+    };
+}
+/** The events in `text`, one per whole line. Returns what is left of an unfinished last line. */
+export function parseRunEventLines(text) {
+    const events = [];
+    const parts = text.split("\n");
+    const rest = parts.pop() ?? "";
+    for (const part of parts) {
+        if (part.trim() === "")
+            continue;
+        try {
+            events.push(JSON.parse(part));
+        }
+        catch {
+            // A line that is not JSON is not an event: skipped.
+        }
+    }
+    return { events, rest };
+}
+/** The runs stored for the checkout at `cwd`, newest first. */
+export async function listStoredRuns(cwd) {
+    const dir = await runEventsDir(cwd);
+    if (!dir || !existsSync(dir))
+        return [];
+    const runs = [];
+    for (const entry of readdirSync(dir)) {
+        if (!entry.endsWith(".jsonl"))
+            continue;
+        const file = join(dir, entry);
+        try {
+            const first = readFileSync(file, "utf8").split("\n", 1)[0] ?? "";
+            if (first === "")
+                continue;
+            const head = JSON.parse(first);
+            if (typeof head.runId !== "string")
+                continue;
+            runs.push({ runId: head.runId, name: String(head.name ?? ""), file, mtimeMs: statSync(file).mtimeMs });
+        }
+        catch {
+            // Unreadable or not an event file: not listed.
+        }
+    }
+    return runs.sort((a, b) => b.mtimeMs - a.mtimeMs);
+}
+/**
+ * The file for `ref`: a run id, else the name of an Op or a component
+ * selection, for which the newest stored run of that name stands. Null when
+ * nothing matches (a run that has not written its first line yet included).
+ */
+export async function findStoredRun(cwd, ref) {
+    const dir = await runEventsDir(cwd);
+    if (!dir)
+        return null;
+    const direct = join(dir, runEventFileName(ref));
+    if (existsSync(direct)) {
+        const byId = (await listStoredRuns(cwd)).find((r) => r.file === direct);
+        return byId ?? { runId: ref, name: "", file: direct, mtimeMs: statSync(direct).mtimeMs };
+    }
+    return (await listStoredRuns(cwd)).find((r) => r.name === ref) ?? null;
+}
+/** Whether `event` ends a stream. */
+export const isRunSettle = (event) => event.type === "run-settle";
+/**
+ * Read `file` from the start and hand each event to `onEvent` (with its raw
+ * line). Without `follow` it stops at the end of the file. With it, it keeps
+ * reading what is appended, by polling every `pollMs`, until `run-settle` is
+ * read, `signal` aborts, or `idleMs` passes with nothing new (when given).
+ * Resolves with the `run-settle` event, or undefined when the stream had
+ * none (a replay of a run still going, or a follow that was cut short).
+ */
+export async function readRunEvents(file, onEvent, opts = {}) {
+    const pollMs = opts.pollMs ?? 100;
+    let offset = 0;
+    let rest = "";
+    let lastGrowth = Date.now();
+    for (;;) {
+        let size = 0;
+        try {
+            size = statSync(file).size;
+        }
+        catch {
+            // Not there yet (a follow started before the run opened its file).
+        }
+        if (size > offset) {
+            const buf = readFileSync(file);
+            const chunk = buf.subarray(offset, size).toString("utf8");
+            offset = size;
+            lastGrowth = Date.now();
+            const text = rest + chunk;
+            const parts = text.split("\n");
+            rest = parts.pop() ?? "";
+            for (const part of parts) {
+                if (part.trim() === "")
+                    continue;
+                let event;
+                try {
+                    event = JSON.parse(part);
+                }
+                catch {
+                    continue;
+                }
+                onEvent(event, `${part}\n`);
+                if (isRunSettle(event))
+                    return event;
+            }
+        }
+        else if (!opts.follow) {
+            return undefined;
+        }
+        else if (opts.signal?.aborted) {
+            return undefined;
+        }
+        else if (opts.idleMs !== undefined && Date.now() - lastGrowth > opts.idleMs) {
+            return undefined;
+        }
+        else {
+            await new Promise((resolve) => {
+                const timer = setTimeout(resolve, pollMs);
+                opts.signal?.addEventListener("abort", () => { clearTimeout(timer); resolve(); }, { once: true });
+            });
+        }
+    }
+}
+/**
+ * Which run event files the policy lets go (#4036): every file older than
+ * `days` by its last write, apart from the newest `keep`. A run still going
+ * writes its file as it goes, so it is never older than the window. Reads
+ * only; {@link pruneRunEvents} deletes.
+ */
+export async function planRunEventPrune(cwd, policy, now) {
+    const dir = await runEventsDir(cwd);
+    if (!dir || !existsSync(dir))
+        return { dir, remove: [], keep: [] };
+    const files = [];
+    for (const entry of readdirSync(dir)) {
+        if (!entry.endsWith(".jsonl"))
+            continue;
+        const file = join(dir, entry);
+        try {
+            const st = statSync(file);
+            if (!st.isFile())
+                continue;
+            files.push({ file, bytes: st.size, modified: new Date(st.mtimeMs).toISOString(), ms: st.mtimeMs });
+        }
+        catch {
+            // Gone between the listing and the stat.
+        }
+    }
+    files.sort((a, b) => b.ms - a.ms || (a.file < b.file ? -1 : 1));
+    const cutoff = now.getTime() - policy.days * 86400000;
+    const remove = [];
+    const keep = [];
+    files.forEach(({ ms, ...f }, i) => (i >= policy.keep && ms < cutoff ? remove : keep).push(f));
+    return { dir, remove, keep };
+}
+/** Delete the files a plan lets go. Returns how many were deleted; a file already gone is not counted. */
+export function pruneRunEvents(plan) {
+    let n = 0;
+    for (const f of plan.remove) {
+        try {
+            rmSync(f.file);
+            n++;
+        }
+        catch {
+            // Already gone.
+        }
+    }
+    return n;
+}

package/dist/run-event-stream.d.ts

@@ -0,0 +1,133 @@
+/**
+ * The emitters' side of the run-event contract (#4041): what a runtime or a
+ * command needs to print a run's stream through the one writer in
+ * `./run-event.ts`.
+ *
+ * Every emitter hands bodies to a {@link RunEventSink}. The CLI opens a
+ * {@link RunEventStream} over a run's identity, which stamps each body
+ * through `createRunEventWriter` and makes sure the stream opens with
+ * `run-start` and ends with one `run-settle`, even when the run threw before
+ * it said so itself. The components driver emits bodies only, and
+ * {@link progressOfRunEvent} turns them back into the older
+ * `RunProgressEvent` lines that `--progress-json` still prints.
+ *
+ * Kept apart from `./run-event.ts`, which a level-0 import loads: this
+ * module reads git and the CI environment.
+ */
+import type { RunProgressEvent } from "./components/run-progress.js";
+import type { GateCheck } from "./op/gate.js";
+import { type RunOrigin } from "./lifecycle/release-ledger.js";
+import { type RunEventBody, type RunEventKind, type RunEventRun, type RunEventRuntime, type RunEventSettleStatus } from "./run-event.js";
+/** Where an emitter hands a run's events, before the writer stamps them. */
+export type RunEventSink = (body: RunEventBody) => void;
+/** One sink that hands each body to every sink given, or undefined when none is. */
+export declare function joinRunEventSinks(...sinks: Array<RunEventSink | undefined>): RunEventSink | undefined;
+/**
+ * A run-event body as the older `RunProgressEvent`, or undefined when that
+ * stream had no such event. It never printed a gate step, a skipped step,
+ * a phase outside a component, a gate's decision or a component the run did
+ * not start (`blocked`, `already-applied`, #4007), so those map to nothing
+ * and `--progress-json` prints what it printed before #4041.
+ */
+export declare function progressOfRunEvent(body: RunEventBody): RunProgressEvent | undefined;
+/** A `RunProgressEvent` callback as a sink of run-event bodies, through {@link progressOfRunEvent}. */
+export declare function progressSinkOf(onProgress: ((event: RunProgressEvent) => void) | undefined): RunEventSink | undefined;
+/** The CI run the environment names, as `resolveCiRun` gives it. */
+type CiRun = {
+    runId: string;
+    runOrigin: RunOrigin;
+};
+/**
+ * A run's identity from what the emitter already knows. The runtime is `ci`
+ * inside a CI job, `steward` in a steward's turn and `local` otherwise; the
+ * origin is the CI run's, `op` for a steward's run, and `local` otherwise. An
+ * Op run keeps its own run id in CI, as its run record does (#4020).
+ */
+export declare function runEventRunOf(input: {
+    kind: RunEventKind;
+    name: string;
+    runId: string;
+    gitSha?: string;
+    ci?: CiRun;
+    steward?: boolean;
+    runtime?: RunEventRuntime;
+    runOrigin?: RunOrigin;
+}): RunEventRun;
+/**
+ * A run's identity, resolved: the commit from `resolveCommitSha` and the CI
+ * run from `resolveCiRun` (#4020). Without `runId`, a CI run is named by its
+ * CI run id and any other by a locally minted `local-<ms>` id, the spelling
+ * `resolveRunId` uses for a release record.
+ */
+export declare function resolveRunEventRun(input: {
+    kind: RunEventKind;
+    name: string;
+    runId?: string;
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+}): Promise<RunEventRun>;
+/** One run's stream: the writer, held to the shape the contract promises. */
+export interface RunEventStream {
+    /** The run every event names. */
+    readonly run: RunEventRun;
+    /** Write a body. */
+    emit: RunEventSink;
+    /**
+     * A sink for a part of the run that frames itself as a whole run, such as
+     * the fan-out a pull request's apply runs: its `run-start` and
+     * `run-settle` are dropped, and the caller settles the run.
+     */
+    nested: RunEventSink;
+    /** End the stream with `run-settle`, unless it has ended. */
+    settle(status: RunEventSettleStatus, error?: string): void;
+    /** Whether `run-settle` has been written. */
+    readonly settled: boolean;
+}
+/**
+ * Open a run's stream over `write`. The first event is always `run-start`
+ * (one with `waves: null` is written first when the emitter starts with
+ * something else), a second `run-start` is dropped, `run-settle` gets the
+ * time since `run-start` when the emitter did not time it, and nothing is
+ * written after `run-settle`.
+ */
+export declare function openRunEventStream(run: RunEventRun, write: (line: string) => void, opts?: {
+    now?: () => Date;
+    chant?: string;
+}): RunEventStream;
+/** Where a gate step sits, for {@link gateEventsOf}. */
+export interface GateStepAt {
+    component: string | null;
+    phase: string;
+    /** `gate:<name>`. */
+    step: string;
+    index?: number;
+    /** The op the gate is recorded under. */
+    op: string;
+    gate: string;
+}
+/**
+ * A decided gate as events: `gate-resolved` and an `ok` settle when an
+ * approval stands, `gate-waiting` and a `gated` settle when none does.
+ * `message` says why it did not pass, for a person.
+ */
+export declare function gateEventsOf(check: GateCheck, at: GateStepAt, opts: {
+    durationMs: number | null;
+    message?: string;
+}): RunEventBody[];
+/** The phase a gate outside any component is the one step of: a fan-out's, a wave's or a pull request's. */
+export declare const GATE_PHASE = "gate";
+/**
+ * Decide a gate that stands outside any component, and emit it as the one
+ * step of a {@link GATE_PHASE} phase: `phase-start`, `step-start`, the
+ * decision through {@link gateEventsOf}, the settle and `phase-settle`. A
+ * decision that throws settles the step `failed` and is rethrown. `message`
+ * says, for a person, why a gate that did not pass did not.
+ */
+export declare function emitGateStep(emit: RunEventSink | undefined, at: {
+    op: string;
+    gate: string;
+}, decide: () => Promise<GateCheck>, message?: (check: Extract<GateCheck, {
+    satisfied: false;
+}>) => string | undefined): Promise<GateCheck>;
+export {};
+//# sourceMappingURL=run-event-stream.d.ts.map

package/dist/run-event-stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-event-stream.d.ts","sourceRoot":"","sources":["../src/run-event-stream.ts"],"names":[],"mappings":"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"}

package/dist/run-event-stream.js

@@ -0,0 +1,242 @@
+/**
+ * The emitters' side of the run-event contract (#4041): what a runtime or a
+ * command needs to print a run's stream through the one writer in
+ * `./run-event.ts`.
+ *
+ * Every emitter hands bodies to a {@link RunEventSink}. The CLI opens a
+ * {@link RunEventStream} over a run's identity, which stamps each body
+ * through `createRunEventWriter` and makes sure the stream opens with
+ * `run-start` and ends with one `run-settle`, even when the run threw before
+ * it said so itself. The components driver emits bodies only, and
+ * {@link progressOfRunEvent} turns them back into the older
+ * `RunProgressEvent` lines that `--progress-json` still prints.
+ *
+ * Kept apart from `./run-event.ts`, which a level-0 import loads: this
+ * module reads git and the CI environment.
+ */
+import { resolveCommitSha } from "./lifecycle/commit-sha.js";
+import { resolveCiRun } from "./lifecycle/release-ledger.js";
+import { createRunEventWriter, } from "./run-event.js";
+/** One sink that hands each body to every sink given, or undefined when none is. */
+export function joinRunEventSinks(...sinks) {
+    const live = sinks.filter((s) => s !== undefined);
+    if (live.length === 0)
+        return undefined;
+    if (live.length === 1)
+        return live[0];
+    return (body) => {
+        for (const sink of live)
+            sink(body);
+    };
+}
+const GATE_PREFIX = "gate:";
+/**
+ * A run-event body as the older `RunProgressEvent`, or undefined when that
+ * stream had no such event. It never printed a gate step, a skipped step,
+ * a phase outside a component, a gate's decision or a component the run did
+ * not start (`blocked`, `already-applied`, #4007), so those map to nothing
+ * and `--progress-json` prints what it printed before #4041.
+ */
+export function progressOfRunEvent(body) {
+    const progressStatus = (s) => (s === "waiting" ? "gated" : s);
+    switch (body.type) {
+        case "run-start":
+            return { type: "run-start", waves: body.waves ?? [] };
+        case "wave-start":
+            return { type: "wave-start", wave: body.wave, components: body.components };
+        case "component-start":
+            return { type: "component-start", wave: body.wave, component: body.component };
+        case "phase-start":
+            return body.component === null ? undefined : { type: "phase-start", component: body.component, phase: body.phase };
+        case "step-start":
+            if (body.component === null || body.step.startsWith(GATE_PREFIX))
+                return undefined;
+            return { type: "step", component: body.component, phase: body.phase, step: body.step, status: "running" };
+        case "step-settle":
+            if (body.component === null || body.step.startsWith(GATE_PREFIX))
+                return undefined;
+            if (body.status !== "ok" && body.status !== "failed")
+                return undefined;
+            return {
+                type: "step",
+                component: body.component,
+                phase: body.phase,
+                step: body.step,
+                status: body.status,
+                ...(body.error !== undefined ? { error: body.error } : {}),
+            };
+        case "phase-settle":
+            return body.component === null
+                ? undefined
+                : { type: "phase-done", component: body.component, phase: body.phase, status: progressStatus(body.status) };
+        case "component-settle":
+            // A component the run did not start (#4007) was never in the older stream.
+            if (body.status === "blocked" || body.status === "already-applied")
+                return undefined;
+            return { type: "component-done", wave: body.wave, component: body.component, status: progressStatus(body.status) };
+        case "wave-settle":
+            return { type: "wave-done", wave: body.wave, status: progressStatus(body.status) };
+        case "run-settle":
+            return { type: "run-done", status: progressStatus(body.status) };
+        case "gate-waiting":
+        case "gate-resolved":
+            return undefined;
+    }
+}
+/** A `RunProgressEvent` callback as a sink of run-event bodies, through {@link progressOfRunEvent}. */
+export function progressSinkOf(onProgress) {
+    if (!onProgress)
+        return undefined;
+    return (body) => {
+        const event = progressOfRunEvent(body);
+        if (event)
+            onProgress(event);
+    };
+}
+/**
+ * A run's identity from what the emitter already knows. The runtime is `ci`
+ * inside a CI job, `steward` in a steward's turn and `local` otherwise; the
+ * origin is the CI run's, `op` for a steward's run, and `local` otherwise. An
+ * Op run keeps its own run id in CI, as its run record does (#4020).
+ */
+export function runEventRunOf(input) {
+    return {
+        runId: input.runId,
+        kind: input.kind,
+        name: input.name,
+        gitSha: input.gitSha ?? null,
+        runtime: input.runtime ?? (input.ci ? "ci" : input.steward ? "steward" : "local"),
+        runOrigin: input.runOrigin ?? input.ci?.runOrigin ?? (input.steward ? { forge: "op" } : { forge: "local" }),
+    };
+}
+/**
+ * A run's identity, resolved: the commit from `resolveCommitSha` and the CI
+ * run from `resolveCiRun` (#4020). Without `runId`, a CI run is named by its
+ * CI run id and any other by a locally minted `local-<ms>` id, the spelling
+ * `resolveRunId` uses for a release record.
+ */
+export async function resolveRunEventRun(input) {
+    const env = input.env ?? process.env;
+    const ci = resolveCiRun(env);
+    const gitSha = await resolveCommitSha({ ...(input.cwd ? { cwd: input.cwd } : {}), env });
+    const runId = input.runId ?? ci?.runId ?? `local-${Date.now()}`;
+    // An explicit id that is not the CI run's is one the caller minted, so the
+    // origin says local, as `resolveRunId` records it on a release.
+    const inCiSpace = ci !== undefined && runId === ci.runId;
+    return runEventRunOf({
+        kind: input.kind,
+        name: input.name,
+        runId,
+        ...(gitSha ? { gitSha } : {}),
+        ...(ci ? { ci } : {}),
+        ...(ci && !inCiSpace ? { runOrigin: { forge: "local" } } : {}),
+    });
+}
+/**
+ * Open a run's stream over `write`. The first event is always `run-start`
+ * (one with `waves: null` is written first when the emitter starts with
+ * something else), a second `run-start` is dropped, `run-settle` gets the
+ * time since `run-start` when the emitter did not time it, and nothing is
+ * written after `run-settle`.
+ */
+export function openRunEventStream(run, write, opts = {}) {
+    const now = opts.now ?? (() => new Date());
+    const writer = createRunEventWriter({ run, write, now, ...(opts.chant ? { chant: opts.chant } : {}) });
+    let startedAt;
+    let settled = false;
+    const emit = (body) => {
+        if (settled)
+            return;
+        if (body.type === "run-start") {
+            if (startedAt !== undefined)
+                return;
+            startedAt = now().getTime();
+            writer.emit(body);
+            return;
+        }
+        if (startedAt === undefined)
+            emit({ type: "run-start", waves: null });
+        if (body.type === "run-settle") {
+            settled = true;
+            writer.emit(body.durationMs === null ? { ...body, durationMs: Math.max(0, now().getTime() - startedAt) } : body);
+            return;
+        }
+        writer.emit(body);
+    };
+    return {
+        run,
+        emit,
+        nested: (body) => {
+            if (body.type !== "run-start" && body.type !== "run-settle")
+                emit(body);
+        },
+        settle(status, error) {
+            if (settled)
+                return;
+            emit({ type: "run-settle", status, durationMs: null, ...(error !== undefined ? { error } : {}) });
+        },
+        get settled() {
+            return settled;
+        },
+    };
+}
+/**
+ * A decided gate as events: `gate-resolved` and an `ok` settle when an
+ * approval stands, `gate-waiting` and a `gated` settle when none does.
+ * `message` says why it did not pass, for a person.
+ */
+export function gateEventsOf(check, at, opts) {
+    const where = { component: at.component, phase: at.phase, step: at.step, ...(at.index !== undefined ? { index: at.index } : {}) };
+    const message = opts.message !== undefined ? { message: opts.message } : {};
+    if (check.satisfied) {
+        return [
+            {
+                type: "gate-resolved",
+                ...where,
+                op: at.op,
+                gate: at.gate,
+                resolvedBy: check.resolution.resolvedBy,
+                resolvedAt: check.resolution.timestamp,
+                via: check.via ?? null,
+                ...(check.resolution.url ? { url: check.resolution.url } : {}),
+            },
+            { type: "step-settle", ...where, status: "ok", durationMs: opts.durationMs },
+        ];
+    }
+    return [
+        { type: "gate-waiting", ...where, op: check.pending.op, gate: at.gate, point: null, ...message },
+        { type: "step-settle", ...where, status: "gated", durationMs: opts.durationMs, ...message },
+    ];
+}
+/** The phase a gate outside any component is the one step of: a fan-out's, a wave's or a pull request's. */
+export const GATE_PHASE = "gate";
+/**
+ * Decide a gate that stands outside any component, and emit it as the one
+ * step of a {@link GATE_PHASE} phase: `phase-start`, `step-start`, the
+ * decision through {@link gateEventsOf}, the settle and `phase-settle`. A
+ * decision that throws settles the step `failed` and is rethrown. `message`
+ * says, for a person, why a gate that did not pass did not.
+ */
+export async function emitGateStep(emit, at, decide, message) {
+    const where = { component: null, phase: GATE_PHASE, step: `gate:${at.gate}` };
+    emit?.({ type: "phase-start", component: null, phase: GATE_PHASE });
+    emit?.({ type: "step-start", ...where });
+    const start = Date.now();
+    let check;
+    try {
+        check = await decide();
+    }
+    catch (err) {
+        emit?.({ type: "step-settle", ...where, status: "failed", durationMs: Date.now() - start, error: err instanceof Error ? err.message : String(err) });
+        emit?.({ type: "phase-settle", component: null, phase: GATE_PHASE, status: "failed" });
+        throw err;
+    }
+    const why = check.satisfied
+        ? undefined
+        : (message?.(check) ?? (check.mismatch ? "an approval stands for this gate, but for another plan" : undefined));
+    for (const body of gateEventsOf(check, { ...where, op: at.op, gate: at.gate }, { durationMs: Date.now() - start, ...(why !== undefined ? { message: why } : {}) })) {
+        emit?.(body);
+    }
+    emit?.({ type: "phase-settle", component: null, phase: GATE_PHASE, status: check.satisfied ? "ok" : "gated" });
+    return check;
+}