@intentius/chant 0.124.27 → 0.124.29

package/src/run-event-stream.test.ts

@@ -0,0 +1,175 @@
+/**
+ * #4041: the emitters' side of the run-event contract. The stream holds a
+ * run to the shape the schema promises, the older `--progress-json` lines
+ * come back unchanged from the bodies the driver now emits, and a run is
+ * named by the commit and CI run #4020 resolves.
+ */
+
+import { describe, expect, test } from "vitest";
+import type { RunProgressEvent } from "./components/run-progress";
+import { memoryGateLedgerPort, type GateCheck } from "./op/gate";
+import type { RunEventBody, RunEventRun } from "./run-event";
+import {
+  emitGateStep,
+  gateEventsOf,
+  joinRunEventSinks,
+  openRunEventStream,
+  progressOfRunEvent,
+  progressSinkOf,
+  resolveRunEventRun,
+  runEventRunOf,
+} from "./run-event-stream";
+import { checkRunEventLines } from "./workspace/__fixtures__/run-event-check";
+
+const SHA = "0123456789abcdef0123456789abcdef01234567";
+const RUN: RunEventRun = { runId: "local-1", kind: "component", name: "api", gitSha: SHA, runtime: "local", runOrigin: { forge: "local" } };
+
+function capture(run: RunEventRun = RUN) {
+  const lines: string[] = [];
+  let t = Date.parse("2026-10-16T12:00:00.000Z");
+  const stream = openRunEventStream(run, (l) => lines.push(l), { now: () => new Date((t += 1000)), chant: "0.124.28" });
+  return { stream, lines };
+}
+
+describe("openRunEventStream", () => {
+  test("opens with run-start, drops a second one, times run-settle, and writes nothing after it", () => {
+    const { stream, lines } = capture();
+    stream.emit({ type: "run-start", waves: [["api"]] });
+    stream.emit({ type: "run-start", waves: [["other"]] });
+    stream.emit({ type: "phase-start", component: "api", phase: "Apply" });
+    stream.emit({ type: "phase-settle", component: "api", phase: "Apply", status: "ok" });
+    stream.emit({ type: "run-settle", status: "ok", durationMs: null });
+    stream.emit({ type: "phase-start", component: "api", phase: "late" });
+    stream.settle("failed", "too late");
+    const events = checkRunEventLines(lines);
+    expect(events.map((e) => e.type)).toEqual(["run-start", "phase-start", "phase-settle", "run-settle"]);
+    expect(events[0]).toMatchObject({ waves: [["api"]] });
+    // Untimed by the emitter, so the stream timed it from run-start.
+    expect(events.at(-1)).toMatchObject({ status: "ok", durationMs: expect.any(Number) });
+    expect((events.at(-1) as { durationMs: number }).durationMs).toBeGreaterThan(0);
+    expect(stream.settled).toBe(true);
+  });
+
+  test("a stream whose emitter never said run-start still opens with one, and settle ends it with the error", () => {
+    const { stream, lines } = capture();
+    stream.emit({ type: "step-start", component: null, phase: "Build", step: "make", index: 0 });
+    stream.emit({ type: "step-settle", component: null, phase: "Build", step: "make", index: 0, status: "failed", durationMs: 5, error: "boom" });
+    stream.settle("failed", "boom");
+    const events = checkRunEventLines(lines);
+    expect(events[0]).toMatchObject({ type: "run-start", waves: null });
+    expect(events.at(-1)).toMatchObject({ type: "run-settle", status: "failed", error: "boom" });
+  });
+
+  test("nested drops the inner run's framing, so the outer run settles it", () => {
+    const { stream, lines } = capture();
+    stream.emit({ type: "run-start", waves: [["a"]] });
+    stream.nested({ type: "run-start", waves: [["a"]] });
+    stream.nested({ type: "wave-start", wave: 1, components: ["a"] });
+    stream.nested({ type: "wave-settle", wave: 1, status: "ok" });
+    stream.nested({ type: "run-settle", status: "ok", durationMs: null });
+    expect(stream.settled).toBe(false);
+    stream.settle("gated");
+    expect(checkRunEventLines(lines).map((e) => e.type)).toEqual(["run-start", "wave-start", "wave-settle", "run-settle"]);
+  });
+});
+
+describe("progressOfRunEvent: --progress-json keeps its shape", () => {
+  test("each body the driver emits maps back to the RunProgressEvent it replaced, key order and all", () => {
+    const pairs: Array<[RunEventBody, RunProgressEvent]> = [
+      [{ type: "run-start", waves: [["a"]] }, { type: "run-start", waves: [["a"]] }],
+      [{ type: "wave-start", wave: 1, components: ["a"] }, { type: "wave-start", wave: 1, components: ["a"] }],
+      [{ type: "component-start", wave: 1, component: "a" }, { type: "component-start", wave: 1, component: "a" }],
+      [{ type: "phase-start", component: "a", phase: "Apply" }, { type: "phase-start", component: "a", phase: "Apply" }],
+      [{ type: "step-start", component: "a", phase: "Apply", step: "apply", index: 0 }, { type: "step", component: "a", phase: "Apply", step: "apply", status: "running" }],
+      [
+        { type: "step-settle", component: "a", phase: "Apply", step: "apply", index: 0, status: "failed", durationMs: 4, error: "no" },
+        { type: "step", component: "a", phase: "Apply", step: "apply", status: "failed", error: "no" },
+      ],
+      [{ type: "phase-settle", component: "a", phase: "Apply", status: "gated" }, { type: "phase-done", component: "a", phase: "Apply", status: "gated" }],
+      [{ type: "component-settle", wave: 1, component: "a", status: "failed" }, { type: "component-done", wave: 1, component: "a", status: "failed" }],
+      [{ type: "wave-settle", wave: 1, status: "ok" }, { type: "wave-done", wave: 1, status: "ok" }],
+      [{ type: "run-settle", status: "ok", durationMs: 12 }, { type: "run-done", status: "ok" }],
+    ];
+    for (const [body, old] of pairs) expect(JSON.stringify(progressOfRunEvent(body))).toBe(JSON.stringify(old));
+  });
+
+  test("what the older stream never printed maps to nothing: gate steps, skipped steps, gate decisions, phases outside a component", () => {
+    const none: RunEventBody[] = [
+      { type: "step-start", component: "a", phase: "Apply", step: "gate:prod", index: 0 },
+      { type: "step-settle", component: "a", phase: "Apply", step: "gate:prod", index: 0, status: "gated", durationMs: 1 },
+      { type: "step-settle", component: "a", phase: "Apply", step: "apply", index: 1, status: "skipped", skip: "not-run", durationMs: null },
+      { type: "gate-waiting", component: "a", phase: "Apply", step: "gate:prod", op: "a", gate: "prod", point: null },
+      { type: "phase-start", component: null, phase: "gate" },
+      { type: "phase-settle", component: null, phase: "gate", status: "ok" },
+    ];
+    for (const body of none) expect(progressOfRunEvent(body)).toBeUndefined();
+  });
+
+  test("progressSinkOf and joinRunEventSinks hand each body to every sink, and to none when none is given", () => {
+    const old: RunProgressEvent[] = [];
+    const bodies: RunEventBody[] = [];
+    const sink = joinRunEventSinks((b) => bodies.push(b), progressSinkOf((e) => old.push(e)), undefined)!;
+    sink({ type: "run-start", waves: [] });
+    sink({ type: "gate-waiting", component: null, phase: "gate", step: "gate:g", op: "fan-out", gate: "g", point: null });
+    expect(bodies).toHaveLength(2);
+    expect(old).toEqual([{ type: "run-start", waves: [] }]);
+    expect(joinRunEventSinks(undefined, progressSinkOf(undefined))).toBeUndefined();
+  });
+});
+
+describe("a gate's decision as events", () => {
+  const at = { component: null, phase: "gate", step: "gate:pr-apply", op: "pr-12", gate: "pr-apply" };
+
+  test("approved: gate-resolved and an ok settle; not approved: gate-waiting and a gated settle", () => {
+    const approved: GateCheck = {
+      satisfied: true,
+      resolution: { version: 1, kind: "resolution", op: "pr-12", gate: "pr-apply", resolvedBy: "github:alice", timestamp: "2026-10-16T11:00:00.000Z" },
+    } as GateCheck;
+    expect(gateEventsOf(approved, at, { durationMs: 3 })).toEqual([
+      { type: "gate-resolved", component: null, phase: "gate", step: "gate:pr-apply", op: "pr-12", gate: "pr-apply", resolvedBy: "github:alice", resolvedAt: "2026-10-16T11:00:00.000Z", via: null },
+      { type: "step-settle", component: null, phase: "gate", step: "gate:pr-apply", status: "ok", durationMs: 3 },
+    ]);
+  });
+
+  test("emitGateStep frames the decision as a gate phase, schema-valid, start before settle", async () => {
+    const { stream, lines } = capture();
+    const port = memoryGateLedgerPort();
+    const check = await emitGateStep(stream.emit, { op: "fan-out", gate: "ship" }, () =>
+      import("./op/gate").then((g) => g.evaluateGate(port, { op: "fan-out", gate: "ship", now: "2026-10-16T12:00:00.000Z" })),
+    );
+    expect(check.satisfied).toBe(false);
+    stream.settle("gated");
+    const events = checkRunEventLines(lines);
+    expect(events.map((e) => e.type)).toEqual(["run-start", "phase-start", "step-start", "gate-waiting", "step-settle", "phase-settle", "run-settle"]);
+    expect(events[4]).toMatchObject({ status: "gated", step: "gate:ship" });
+  });
+});
+
+describe("a run's identity (#4020's sources)", () => {
+  test("outside CI: a local id, the local origin and the local runtime", async () => {
+    const run = await resolveRunEventRun({ kind: "component", name: "api", cwd: "/nonexistent", env: {} });
+    expect(run).toMatchObject({ kind: "component", name: "api", gitSha: null, runtime: "local", runOrigin: { forge: "local" } });
+    expect(run.runId).toMatch(/^local-\d+$/);
+  });
+
+  test("in a GitHub job: the CI run's id and origin, the commit the job is for, and the ci runtime", async () => {
+    const env = { GITHUB_RUN_ID: "77", GITHUB_REPOSITORY: "acme/app", GITHUB_SERVER_URL: "https://github.com", GITHUB_SHA: SHA };
+    const run = await resolveRunEventRun({ kind: "component", name: "api", cwd: "/nonexistent", env });
+    expect(run).toEqual({
+      runId: "77",
+      kind: "component",
+      name: "api",
+      gitSha: SHA,
+      runtime: "ci",
+      runOrigin: { forge: "github", repo: "acme/app", url: "https://github.com/acme/app/actions/runs/77" },
+    });
+    // An id of the caller's own, not the CI run's, lives in no CI id space.
+    expect((await resolveRunEventRun({ kind: "component", name: "api", runId: "run-9", cwd: "/nonexistent", env })).runOrigin).toEqual({ forge: "local" });
+  });
+
+  test("a steward's run is the op id space on the steward runtime", () => {
+    expect(runEventRunOf({ kind: "op", name: "deploy", runId: "conv-1", steward: true })).toEqual({
+      runId: "conv-1", kind: "op", name: "deploy", gitSha: null, runtime: "steward", runOrigin: { forge: "op" },
+    });
+  });
+});

package/src/run-event-stream.ts

@@ -0,0 +1,309 @@
+/**
+ * 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, 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: 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":
+      // 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: ((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;
+}