@intentius/chant 0.124.26 → 0.124.28

package/src/run-event-stream.ts

@@ -0,0 +1,306 @@
+/**
+ * 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";
+import type { GateCheck } from "./op/gate";
+import { resolveCommitSha } from "./lifecycle/commit-sha";
+import { resolveCiRun, type RunOrigin } from "./lifecycle/release-ledger";
+import {
+  createRunEventWriter,
+  type RunEventBody,
+  type RunEventKind,
+  type RunEventRun,
+  type RunEventRuntime,
+  type RunEventSettleStatus,
+} from "./run-event";
+
+/** 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 function joinRunEventSinks(...sinks: Array<RunEventSink | undefined>): RunEventSink | undefined {
+  const live = sinks.filter((s): s is RunEventSink => 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 or a gate's decision, so those map to nothing
+ * and `--progress-json` prints what it printed before #4041.
+ */
+export function progressOfRunEvent(body: RunEventBody): RunProgressEvent | undefined {
+  const progressStatus = (s: RunEventSettleStatus): "ok" | "failed" | "gated" => (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":
+      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: ((event: RunProgressEvent) => void) | undefined): RunEventSink | undefined {
+  if (!onProgress) return undefined;
+  return (body) => {
+    const event = progressOfRunEvent(body);
+    if (event) onProgress(event);
+  };
+}
+
+/** 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 function runEventRunOf(input: {
+  kind: RunEventKind;
+  name: string;
+  runId: string;
+  gitSha?: string;
+  ci?: CiRun;
+  steward?: boolean;
+  runtime?: RunEventRuntime;
+  runOrigin?: RunOrigin;
+}): RunEventRun {
+  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: {
+  kind: RunEventKind;
+  name: string;
+  runId?: string;
+  cwd?: string;
+  env?: NodeJS.ProcessEnv;
+}): Promise<RunEventRun> {
+  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" } } : {}),
+  });
+}
+
+/** 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 function openRunEventStream(
+  run: RunEventRun,
+  write: (line: string) => void,
+  opts: { now?: () => Date; chant?: string } = {},
+): RunEventStream {
+  const now = opts.now ?? (() => new Date());
+  const writer = createRunEventWriter({ run, write, now, ...(opts.chant ? { chant: opts.chant } : {}) });
+  let startedAt: number | undefined;
+  let settled = false;
+
+  const emit: RunEventSink = (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;
+    },
+  };
+}
+
+/** 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 function gateEventsOf(check: GateCheck, at: GateStepAt, opts: { durationMs: number | null; message?: string }): RunEventBody[] {
+  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: RunEventSink | undefined,
+  at: { op: string; gate: string },
+  decide: () => Promise<GateCheck>,
+  message?: (check: Extract<GateCheck, { satisfied: false }>) => string | undefined,
+): Promise<GateCheck> {
+  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: GateCheck;
+  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;
+}

package/src/run-event.test.ts

@@ -0,0 +1,277 @@
+/**
+ * #4019: the run-event contract. One schema for Op, component and pipeline
+ * runs, the one writer, and the two older streams mapped onto it. Every
+ * line the writer prints is checked against `run-event.schema.json`.
+ */
+
+import { describe, expect, test } from "vitest";
+import type { RunProgressEvent } from "./components/run-progress";
+import type { StepRecord } from "./op/local-executor";
+import { contract, validSchema } from "./workspace/__fixtures__/contract-repo";
+import { READ_CONTRACT_FLOOR, READ_CONTRACT_VERSION } from "./workspace/reason-codes";
+import {
+  buildRunEvent,
+  createRunEventWriter,
+  RUN_EVENT_CONTRACT_VERSION,
+  RUN_EVENT_FLOOR,
+  RUN_EVENT_SCHEMA_ID,
+  RUN_EVENT_TYPES,
+  runEventOfProgress,
+  runEventsOfStepRecord,
+  serializeRunEvent,
+  type RunEvent,
+  type RunEventBody,
+  type RunEventRun,
+} from "./run-event";
+import schema from "./workspace/run-event.schema.json";
+
+const { validate, expectValid } = contract(schema);
+
+const SHA = "0123456789abcdef0123456789abcdef01234567";
+
+const OP_RUN: RunEventRun = {
+  runId: "6f1c2d4e-0000-4000-8000-000000000001",
+  kind: "op",
+  name: "deploy-api",
+  gitSha: SHA,
+  runtime: "local",
+  runOrigin: { forge: "local" },
+};
+
+/** A writer that keeps its lines, on a clock that ticks a second per event. */
+function capture(run: RunEventRun) {
+  const lines: string[] = [];
+  let t = Date.parse("2026-10-16T12:00:00.000Z");
+  const writer = createRunEventWriter({ run, write: (l) => lines.push(l), now: () => new Date((t += 1000)), chant: "0.124.28" });
+  const events = () => lines.map((l) => JSON.parse(l) as RunEvent);
+  return { writer, lines, events };
+}
+
+describe("the run-event schema", () => {
+  test("is a valid draft 2020-12 document at the contract version, naming its floor and the read contract's", () => {
+    expect(validSchema(schema)).toBe(true);
+    expect(schema.$id).toBe(RUN_EVENT_SCHEMA_ID);
+    expect(RUN_EVENT_SCHEMA_ID).toBe(`https://intentius.io/chant/schemas/workspace/run-event/v${READ_CONTRACT_VERSION}/run-event.schema.json`);
+    const envelope = schema.$defs.envelope.properties;
+    expect(envelope.contract).toEqual({ const: RUN_EVENT_CONTRACT_VERSION });
+    expect(envelope.$schema).toEqual({ const: RUN_EVENT_SCHEMA_ID });
+    expect(schema.description).toContain(`written by chant ${RUN_EVENT_FLOOR} and newer`);
+    expect(schema.description).toContain(`chant ${READ_CONTRACT_FLOOR} and newer`);
+  });
+
+  test("names exactly the event types the code does, and every one requires the envelope", () => {
+    const defs = schema.$defs as Record<string, { allOf?: Array<{ $ref?: string; properties?: { type?: { const?: string } } }> }>;
+    const refs = schema.oneOf.map((o) => o.$ref.replace("#/$defs/", ""));
+    expect([...refs].sort()).toEqual([...RUN_EVENT_TYPES].sort());
+    for (const t of RUN_EVENT_TYPES) {
+      const parts = defs[t].allOf!;
+      expect(parts[0].$ref, t).toBe("#/$defs/envelope");
+      expect(parts[1].properties!.type!.const, t).toBe(t);
+    }
+  });
+
+  test("keeps the step statuses closed, with skipped and room for cached", () => {
+    const status = schema.$defs["step-settle"].allOf[1].properties!.status as { enum: string[] };
+    expect(status.enum).toEqual(["ok", "failed", "skipped", "cached", "gated", "waiting"]);
+    const one = buildRunEvent({ type: "step-settle", component: null, phase: "p", step: "s", status: "ok", durationMs: 1 }, { run: OP_RUN, seq: 3 });
+    expectValid(one);
+    for (const bad of ["fail", "running", "done"]) expect(validate({ ...one, status: bad }), bad).toBe(false);
+    expect(validate({ ...one, status: "skipped", skip: "receipt" })).toBe(true);
+    expect(validate({ ...one, status: "skipped", skip: "because" })).toBe(false);
+  });
+
+  test("refuses an event missing the run, the commit or the runtime, or at another contract", () => {
+    const one = buildRunEvent({ type: "run-start", waves: null }, { run: OP_RUN, seq: 0 });
+    expectValid(one);
+    for (const field of ["runId", "kind", "name", "gitSha", "runtime", "runOrigin", "seq", "at", "chant"] as const) {
+      const copy: Record<string, unknown> = { ...one };
+      delete copy[field];
+      expect(validate(copy), field).toBe(false);
+    }
+    expect(validate({ ...one, gitSha: "main" })).toBe(false);
+    expect(validate({ ...one, gitSha: null })).toBe(true);
+    expect(validate({ ...one, runtime: "cloud" })).toBe(false);
+    expect(validate({ ...one, runOrigin: { forge: "jenkins" } })).toBe(false);
+    expect(validate({ ...one, contract: 2 })).toBe(false);
+    expect(validate({ ...one, type: "run-done" })).toBe(false);
+  });
+
+  test("lets a reader ignore fields it does not know", () => {
+    expectValid({ ...buildRunEvent({ type: "run-start", waves: null }, { run: OP_RUN, seq: 0 }), later: true });
+  });
+});
+
+describe("the one writer", () => {
+  test("writes an Op run as one line per event, each valid, with the run on every line and seq counting from 0", () => {
+    const { writer, lines, events } = capture(OP_RUN);
+    const bodies: RunEventBody[] = [
+      { type: "run-start", waves: null },
+      { type: "phase-start", component: null, phase: "build" },
+      { type: "step-start", component: null, phase: "build", step: "shell" },
+      { type: "step-settle", component: null, phase: "build", step: "shell", status: "ok", durationMs: 412 },
+      { type: "step-start", component: null, phase: "build", step: "effect:schema" },
+      { type: "step-settle", component: null, phase: "build", step: "effect:schema", status: "skipped", skip: "receipt", durationMs: 3 },
+      { type: "step-settle", component: null, phase: "build", step: "cache-restore", status: "cached", durationMs: 0 },
+      { type: "phase-settle", component: null, phase: "build", status: "ok" },
+      { type: "phase-start", component: null, phase: "release" },
+      { type: "step-start", component: null, phase: "release", step: "gate:prod" },
+      { type: "gate-waiting", component: null, phase: "release", step: "gate:prod", op: "deploy-api", gate: "prod", point: null },
+      { type: "step-settle", component: null, phase: "release", step: "gate:prod", status: "gated", durationMs: 20 },
+      { type: "phase-settle", component: null, phase: "release", status: "gated" },
+      { type: "run-settle", status: "gated", durationMs: 1500 },
+    ];
+    for (const b of bodies) writer.emit(b);
+    expect(writer.next).toBe(bodies.length);
+    expect(lines.every((l) => l.endsWith("\n") && !l.slice(0, -1).includes("\n"))).toBe(true);
+    const evs = events();
+    evs.forEach((e, i) => {
+      expectValid(e);
+      expect(e.seq).toBe(i);
+      expect(e).toMatchObject({ $schema: RUN_EVENT_SCHEMA_ID, contract: 1, chant: "0.124.28", runId: OP_RUN.runId, kind: "op", name: "deploy-api", gitSha: SHA, runtime: "local", runOrigin: { forge: "local" } });
+      expect(e.type).toBe(bodies[i].type);
+    });
+    expect(evs[0].at).toBe("2026-10-16T12:00:01.000Z");
+    expect(Object.keys(evs[0]).slice(0, 5)).toEqual(["$schema", "contract", "chant", "seq", "at"]);
+    expect(evs.at(-1)).toMatchObject({ type: "run-settle", status: "gated" });
+  });
+
+  test("writes a pipeline run in forge CI, its stages as phases and its jobs as steps, with the CI locator", () => {
+    const { writer, events } = capture({
+      runId: "8812345",
+      kind: "pipeline",
+      name: "main",
+      gitSha: SHA,
+      runtime: "ci",
+      runOrigin: { forge: "gitlab", repo: "acme/api", url: "https://gitlab.example.com/acme/api/-/pipelines/8812345" },
+    });
+    writer.emit({ type: "run-start", waves: null });
+    writer.emit({ type: "phase-start", component: null, phase: "test" });
+    writer.emit({ type: "step-start", component: null, phase: "test", step: "unit" });
+    writer.emit({ type: "step-settle", component: null, phase: "test", step: "unit", status: "failed", durationMs: 9000, error: "exit 1" });
+    writer.emit({ type: "phase-settle", component: null, phase: "test", status: "failed" });
+    writer.emit({ type: "run-settle", status: "failed", durationMs: 9100, error: "job unit failed" });
+    for (const e of events()) expectValid(e);
+  });
+
+  test("writes a steward run with its approval and an open decision point", () => {
+    const { writer, events } = capture({ ...OP_RUN, runtime: "steward", runOrigin: { forge: "op", url: "https://fountain.example.com/threads/t-1" } });
+    writer.emit({ type: "gate-resolved", component: null, phase: "release", step: "gate:prod", op: "deploy-api", gate: "prod", resolvedBy: "alice", resolvedAt: "2026-10-16T11:00:00.000Z", via: "quorum" });
+    writer.emit({ type: "gate-waiting", component: null, phase: "release", step: "pick-region", op: "deploy-api", gate: null, point: "A-0042" });
+    writer.emit({ type: "step-settle", component: null, phase: "release", step: "pick-region", status: "waiting", durationMs: 5, message: "region?" });
+    writer.emit({ type: "run-settle", status: "waiting", durationMs: 40 });
+    for (const e of events()) expectValid(e);
+  });
+
+  test("serializes one event as one JSON line", () => {
+    const e = buildRunEvent({ type: "run-start", waves: [["a"], ["b", "c"]] }, { run: OP_RUN, seq: 0, at: "2026-10-16T12:00:00.000Z", chant: "1.0.0" });
+    expect(serializeRunEvent(e)).toBe(JSON.stringify(e) + "\n");
+    expect(e.at).toBe("2026-10-16T12:00:00.000Z");
+  });
+
+  test("is exported from @intentius/chant", async () => {
+    const root = await import("./index");
+    expect(root.createRunEventWriter).toBe(createRunEventWriter);
+    expect(root.RUN_EVENT_SCHEMA_ID).toBe(RUN_EVENT_SCHEMA_ID);
+  }, 60_000);
+});
+
+describe("RunProgressEvent in terms of the run-event contract", () => {
+  const progress: RunProgressEvent[] = [
+    { type: "run-start", waves: [["db"], ["api", "web"]] },
+    { type: "wave-start", wave: 1, components: ["db"] },
+    { type: "component-start", wave: 1, component: "db" },
+    { type: "phase-start", component: "db", phase: "deploy" },
+    { type: "step", component: "db", phase: "deploy", step: "apply", status: "running" },
+    { type: "step", component: "db", phase: "deploy", step: "apply", status: "failed", error: "boom" },
+    { type: "step", component: "db", phase: "deploy", step: "verify", status: "ok" },
+    { type: "phase-done", component: "db", phase: "deploy", status: "failed" },
+    { type: "component-done", wave: 1, component: "db", status: "gated" },
+    { type: "wave-done", wave: 1, status: "failed" },
+    { type: "run-done", status: "failed" },
+  ];
+
+  test("maps every variant to a valid event that keeps its fields", () => {
+    const { writer, events } = capture({ ...OP_RUN, kind: "component", name: "db,api,web" });
+    for (const p of progress) writer.emit(runEventOfProgress(p));
+    const evs = events();
+    for (const e of evs) expectValid(e);
+    expect(evs.map((e) => e.type)).toEqual([
+      "run-start",
+      "wave-start",
+      "component-start",
+      "phase-start",
+      "step-start",
+      "step-settle",
+      "step-settle",
+      "phase-settle",
+      "component-settle",
+      "wave-settle",
+      "run-settle",
+    ]);
+    expect(evs[0]).toMatchObject({ waves: [["db"], ["api", "web"]] });
+    expect(evs[5]).toMatchObject({ component: "db", step: "apply", status: "failed", error: "boom", durationMs: null });
+    expect(evs[8]).toMatchObject({ component: "db", status: "gated" });
+  });
+});
+
+describe("StepRecord in terms of the run-event contract", () => {
+  const ctx = { op: "deploy-api" };
+  const base = { phase: "release", args: {}, durationMs: 12 } as const;
+  const types = (r: StepRecord) => runEventsOfStepRecord(r, ctx).map((b) => b.type);
+  const settle = (r: StepRecord) => runEventsOfStepRecord(r, ctx).at(-1)!;
+
+  test("ok and fail settle ok and failed, with the error", () => {
+    expect(settle({ ...base, fn: "shell", status: "ok" })).toEqual({ type: "step-settle", component: null, phase: "release", step: "shell", status: "ok", durationMs: 12 });
+    expect(settle({ ...base, fn: "shell", status: "fail", error: "exit 2" })).toMatchObject({ status: "failed", error: "exit 2" });
+  });
+
+  test("an approved gate resolves before its step settles ok", () => {
+    const r: StepRecord = { ...base, fn: "gate:prod", status: "ok", approval: { gate: "prod", resolvedBy: "alice", timestamp: "2026-10-16T11:00:00.000Z", via: "policy", url: "https://x" } };
+    expect(types(r)).toEqual(["gate-resolved", "step-settle"]);
+    expect(runEventsOfStepRecord(r, ctx)[0]).toEqual({ type: "gate-resolved", component: null, phase: "release", step: "gate:prod", op: "deploy-api", gate: "prod", resolvedBy: "alice", resolvedAt: "2026-10-16T11:00:00.000Z", via: "policy", url: "https://x" });
+  });
+
+  test("a step waiting on a gate or a decision point settles gated or waiting, after gate-waiting", () => {
+    const own: StepRecord = { ...base, fn: "workspace-upgrade", status: "skipped", gate: { op: "workspace-upgrade", gate: "all" } };
+    expect(types(own)).toEqual(["gate-waiting", "step-settle"]);
+    expect(runEventsOfStepRecord(own, ctx)[0]).toMatchObject({ op: "workspace-upgrade", gate: "all", point: null });
+    expect(settle(own)).toMatchObject({ status: "gated" });
+
+    const point: StepRecord = { ...base, fn: "pick", status: "skipped", point: { id: "A-1", point: "region", state: "escalated", path: "answers/A-1.md", subject: null, steward: null } };
+    expect(runEventsOfStepRecord(point, ctx)[0]).toMatchObject({ type: "gate-waiting", gate: null, point: "A-1" });
+    expect(settle(point)).toMatchObject({ status: "waiting" });
+
+    const pointGate: StepRecord = { ...point, fn: "gate:prod" };
+    expect(runEventsOfStepRecord(pointGate, ctx)[0]).toMatchObject({ gate: "prod", point: "A-1" });
+
+    const mismatch: StepRecord = { ...base, fn: "gate:prod", status: "skipped", refusal: "approved for another plan" };
+    expect(runEventsOfStepRecord(mismatch, ctx)[0]).toMatchObject({ type: "gate-waiting", gate: "prod", message: "approved for another plan" });
+    expect(settle(mismatch)).toMatchObject({ status: "gated", message: "approved for another plan" });
+  });
+
+  test("skips say why when the record does, and null when it does not", () => {
+    expect(settle({ ...base, fn: "build", status: "skipped", resumed: { run: "r-1", gate: "prod" } })).toMatchObject({ status: "skipped", skip: "resumed" });
+    expect(settle({ ...base, fn: "workLease:claim", status: "skipped", refusal: "no item ready" })).toMatchObject({ status: "skipped", skip: "refused", message: "no item ready" });
+    expect(settle({ ...base, fn: "gate:prod", status: "skipped" })).toMatchObject({ status: "skipped", skip: null });
+    expect(settle({ ...base, fn: "migrate", status: "skipped", durationMs: 0 })).toMatchObject({ status: "skipped", skip: null, durationMs: 0 });
+  });
+
+  test("every mapped record writes valid events", () => {
+    const { writer, events } = capture(OP_RUN);
+    const records: StepRecord[] = [
+      { ...base, fn: "shell", status: "ok" },
+      { ...base, fn: "shell", status: "fail", error: "x" },
+      { ...base, fn: "gate:prod", status: "ok", approval: { gate: "prod", resolvedBy: "a", timestamp: "2026-10-16T11:00:00.000Z" } },
+      { ...base, fn: "gate:prod", status: "skipped", refusal: "r" },
+      { ...base, fn: "build", status: "skipped", resumed: { run: "r-1", gate: "prod" } },
+      { ...base, fn: "migrate", status: "skipped" },
+    ];
+    for (const r of records) for (const b of runEventsOfStepRecord(r, { ...ctx, component: "api" })) writer.emit(b);
+    const evs = events();
+    expect(evs.length).toBe(8);
+    for (const e of evs) {
+      expectValid(e);
+      expect(e).toMatchObject({ component: "api" });
+    }
+  });
+});