@intentius/chant 0.124.26 → 0.124.28

package/dist/run-event.js

@@ -0,0 +1,207 @@
+/**
+ * The run-event contract (#4019, behold #678): one stream of events for Op
+ * runs, component runs and pipeline runs, so anything that shows a run reads
+ * the same fields wherever the run happened.
+ *
+ * `workspace/run-event.schema.json` is the contract. These types
+ * mirror it, and {@link createRunEventWriter} and {@link writeRunEvent} are
+ * the one writer: every emitter hands a writer the type-specific body and
+ * the writer stamps the run's identity, the sequence number, the time and the
+ * contract fields on it, then writes one JSON line. The emitters themselves
+ * are in `./run-event-stream.ts` and the runtimes (#4041); the files
+ * they are kept in, replay and `--follow` are `./run-event-store.ts` (#4042).
+ *
+ * Two older streams predate this one and keep their shape behind
+ * `--progress-json`, while `--events-json` prints this one (#4041):
+ * `RunProgressEvent` (`./components/run-progress.ts`, from `chant run
+ * --components --progress-json`) and the Op path's `StepRecord` lines
+ * (`./op/local-executor.ts`, from `chant run <op> --progress-json`).
+ * {@link runEventOfProgress} and {@link runEventsOfStepRecord} say how each
+ * maps onto this contract.
+ *
+ * This module imports no runtime code beyond the chant version (`./chant-version.ts`), so a consumer
+ * can import the types and the writer without loading the rest of chant. It
+ * lives outside `workspace/` so that a level-0 import of `@intentius/chant`
+ * loads no workspace module (#2526).
+ */
+import { CHANT_VERSION } from "./chant-version.js";
+/** The schema's `$id`, which every event carries as `$schema`. */
+export const RUN_EVENT_SCHEMA_ID = "https://intentius.io/chant/schemas/workspace/run-event/v1/run-event.schema.json";
+/** The contract version every event carries as `contract`. */
+export const RUN_EVENT_CONTRACT_VERSION = 1;
+/** The first chant that writes contract version 1 of the run-event stream. */
+export const RUN_EVENT_FLOOR = "0.124.28";
+/** Every event type, in the order a reader meets them. Closed: part of the contract. */
+export const RUN_EVENT_TYPES = [
+    "run-start",
+    "wave-start",
+    "component-start",
+    "phase-start",
+    "step-start",
+    "gate-waiting",
+    "gate-resolved",
+    "step-settle",
+    "phase-settle",
+    "component-settle",
+    "wave-settle",
+    "run-settle",
+];
+/** One event as its line: JSON with the envelope first, then the body, and a newline. */
+export function serializeRunEvent(event) {
+    return JSON.stringify(event) + "\n";
+}
+/**
+ * Build one event from its body and the run it belongs to. The envelope's
+ * fields come first, so every line reads the same way. No body names an
+ * envelope field, so neither overrides the other.
+ */
+export function buildRunEvent(body, stamp) {
+    const at = stamp.at === undefined ? new Date().toISOString() : typeof stamp.at === "string" ? stamp.at : stamp.at.toISOString();
+    const { runId, kind, name, gitSha, runtime, runOrigin } = stamp.run;
+    const envelope = {
+        $schema: RUN_EVENT_SCHEMA_ID,
+        contract: RUN_EVENT_CONTRACT_VERSION,
+        chant: stamp.chant ?? CHANT_VERSION,
+        seq: stamp.seq,
+        at,
+        runId,
+        kind,
+        name,
+        gitSha,
+        runtime,
+        runOrigin,
+    };
+    return { ...envelope, ...body };
+}
+/** Build one event and hand its line to `write`. Returns the event written. */
+export function writeRunEvent(body, stamp, write) {
+    const event = buildRunEvent(body, stamp);
+    write(serializeRunEvent(event));
+    return event;
+}
+/** The one writer of a run's stream (#4019). Each `emit` writes one line and moves the sequence on. */
+export function createRunEventWriter(opts) {
+    const write = opts.write ?? ((line) => void process.stdout.write(line));
+    const now = opts.now ?? (() => new Date());
+    let seq = opts.seq ?? 0;
+    return {
+        emit(body) {
+            return writeRunEvent(body, { run: opts.run, seq: seq++, at: now(), chant: opts.chant }, write);
+        },
+        get next() {
+            return seq;
+        },
+    };
+}
+// ── The older streams, in terms of this one ─────────────────────────────────
+/**
+ * A `RunProgressEvent` (`chant run --components --progress-json`) as a
+ * run-event body. The older stream has no step timings, so `durationMs` is
+ * null on the settles it maps to.
+ */
+export function runEventOfProgress(event) {
+    switch (event.type) {
+        case "run-start":
+            return { type: "run-start", waves: event.waves };
+        case "wave-start":
+            return { type: "wave-start", wave: event.wave, components: event.components };
+        case "component-start":
+            return { type: "component-start", wave: event.wave, component: event.component };
+        case "phase-start":
+            return { type: "phase-start", component: event.component, phase: event.phase };
+        case "step":
+            if (event.status === "running")
+                return { type: "step-start", component: event.component, phase: event.phase, step: event.step };
+            return {
+                type: "step-settle",
+                component: event.component,
+                phase: event.phase,
+                step: event.step,
+                status: event.status,
+                durationMs: null,
+                ...(event.error !== undefined ? { error: event.error } : {}),
+            };
+        case "phase-done":
+            return { type: "phase-settle", component: event.component, phase: event.phase, status: event.status };
+        case "component-done":
+            return { type: "component-settle", wave: event.wave, component: event.component, status: event.status };
+        case "wave-done":
+            return { type: "wave-settle", wave: event.wave, status: event.status };
+        case "run-done":
+            return { type: "run-settle", status: event.status, durationMs: null };
+    }
+}
+const GATE_PREFIX = "gate:";
+/**
+ * A settled `StepRecord` (`chant run <op> --progress-json`) as run-event
+ * bodies: a gate's `gate-resolved` or `gate-waiting` when the record carries
+ * one, then the `step-settle`. `op` is the run's Op, which a gate is recorded
+ * under unless the record names another.
+ *
+ * A record skipped with nothing to say why maps to `skip: null`. The local
+ * executor writes the same record for a gate nobody has approved, for a step
+ * of an effect whose receipt matched and for a step an earlier failure
+ * stopped, so only an emitter that knows which can say `gated`, `receipt` or
+ * `not-run`. The run's own status still says `gated`. The local executor
+ * (#4041) knows, and passes `skip` for a bare skipped record and `gate` for
+ * a gate step nobody has approved; it passes `index`, the step's place in
+ * its phase, too.
+ */
+export function runEventsOfStepRecord(record, ctx) {
+    const component = ctx.component ?? null;
+    const at = { component, phase: record.phase, step: record.fn, ...(ctx.index !== undefined ? { index: ctx.index } : {}) };
+    const out = [];
+    const settle = (status, extra = {}) => ({
+        type: "step-settle",
+        ...at,
+        status,
+        durationMs: record.durationMs,
+        ...extra,
+    });
+    const gateOfFn = record.fn.startsWith(GATE_PREFIX) ? record.fn.slice(GATE_PREFIX.length) : null;
+    if (record.approval) {
+        const a = record.approval;
+        out.push({
+            type: "gate-resolved",
+            ...at,
+            op: ctx.op,
+            gate: a.gate,
+            resolvedBy: a.resolvedBy,
+            resolvedAt: a.timestamp,
+            via: a.via ?? null,
+            ...(a.url !== undefined ? { url: a.url } : {}),
+        });
+    }
+    if (record.status === "ok") {
+        out.push(settle("ok"));
+        return out;
+    }
+    if (record.status === "fail") {
+        out.push(settle("failed", record.error !== undefined ? { error: record.error } : {}));
+        return out;
+    }
+    const message = record.refusal !== undefined ? { message: record.refusal } : {};
+    const stoppedAt = record.gate ?? ctx.gate;
+    if (record.point) {
+        out.push({ type: "gate-waiting", ...at, op: ctx.op, gate: gateOfFn, point: record.point.id, ...message });
+        out.push(settle("waiting", message));
+    }
+    else if (stoppedAt) {
+        out.push({ type: "gate-waiting", ...at, op: stoppedAt.op, gate: stoppedAt.gate, point: null, ...message });
+        out.push(settle("gated", message));
+    }
+    else if (gateOfFn !== null && record.refusal !== undefined) {
+        out.push({ type: "gate-waiting", ...at, op: ctx.op, gate: gateOfFn, point: null, ...message });
+        out.push(settle("gated", message));
+    }
+    else if (record.resumed) {
+        out.push(settle("skipped", { skip: "resumed", message: `resumed at gate ${record.resumed.gate} from run ${record.resumed.run}` }));
+    }
+    else if (record.refusal !== undefined) {
+        out.push(settle("skipped", { skip: "refused", ...message }));
+    }
+    else {
+        out.push(settle("skipped", { skip: ctx.skip ?? null }));
+    }
+    return out;
+}