@intentius/chant 0.124.27 → 0.124.29

package/dist/components/fan-out-run.d.ts

@@ -42,6 +42,7 @@ import type { ReleaseIdentity } from "../telemetry-attribution.js";
 import { type FanOutPlan, type FanOutProgress, type FanOutSkip } from "./fan-out.js";
 import { type GateLedgerPort } from "../op/gate.js";
 import type { RunProgressEvent } from "./run-progress.js";
+import { type RunEventSink } from "../run-event-stream.js";
 import type { CapabilityRegistry } from "./capability.js";
 import type { PendingGateRecord } from "../lifecycle/gate-ledger.js";
 import type { DeployContext } from "./capability.js";
@@ -93,6 +94,12 @@ export interface FanOutRunOptions {
     /** Outputs of components this run is not running: the ones the plan lists in `seeds`. */
     componentOutputs?: Record<string, Record<string, unknown>>;
     onProgress?: (event: RunProgressEvent) => void;
+    /**
+     * Where the run's events go (#4041, `--events-json`). A gate over the set
+     * or over a wave is a `gate:<name>` step of a `gate` phase with no
+     * component, settled before the components it lets through start.
+     */
+    onRunEvent?: RunEventSink;
     gates?: GateLedgerPort;
     now?: string;
     /** One approval over the ordered set, bound to `plan.digest`. */

package/dist/components/fan-out-run.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fan-out-run.d.ts","sourceRoot":"","sources":["../../src/components/fan-out-run.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,OAAO,EAGL,KAAK,eAAe,EACpB,KAAK,qBAAqB,EAE3B,MAAM,UAAU,CAAC;AAClB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAChE,OAAO,EAAqC,KAAK,UAAU,EAAE,KAAK,cAAc,EAAE,KAAK,UAAU,EAAE,MAAM,WAAW,CAAC;AACrH,OAAO,EAAmD,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC;AAClG,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AACvD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAClE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClD,OAAO,EAAqB,KAAK,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACxE,OAAO,EAA6E,KAAK,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAE5H;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,mEAAmE;IACnE,EAAE,EAAE,MAAM,CAAC;IACX,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,aAAa,CAAC,EAAE,CACd,SAAS,EAAE,eAAe,EAC1B,GAAG,EAAE,aAAa,EAClB,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,KACtD,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAChC;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,8FAA8F;AAC9F,qBAAa,0BAA2B,SAAQ,KAAK;IAEjD,QAAQ,CAAC,IAAI,EAAE,MAAM;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE;IAH/B,YACW,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAAE,EAO9B;CACF;AAED,wEAAwE;AACxE,MAAM,WAAW,UAAU;IACzB,0FAA0F;IAC1F,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,yFAAyF;IACzF,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC3D,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,CAAC;IAC/C,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,iEAAiE;IACjE,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,2FAA2F;IAC3F,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAChD,qFAAqF;IACrF,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,IAAI,CAAC;IAC7C,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IACnD,4FAA4F;IAC5F,eAAe,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,eAAe,GAAG,SAAS,CAAC;IACrE;;;;;OAKG;IACH,kBAAkB,CAAC,EAAE,CAAC,MAAM,EAAE,qBAAqB,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,KAAK,IAAI,CAAC;CAC5G;AAED,MAAM,WAAW,eAAe;IAC9B,4EAA4E;IAC5E,IAAI,EAAE,UAAU,CAAC;IACjB,MAAM,EAAE,IAAI,GAAG,MAAM,GAAG,OAAO,CAAC;IAChC,OAAO,EAAE,qBAAqB,EAAE,CAAC;IACjC,8EAA8E;IAC9E,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,2DAA2D;IAC3D,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,mFAAmF;IACnF,OAAO,EAAE,UAAU,EAAE,CAAC;IACtB,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAC1D,sEAAsE;IACtE,IAAI,CAAC,EAAE,iBAAiB,CAAC;IACzB,iGAAiG;IACjG,KAAK,CAAC,EAAE,UAAU,EAAE,CAAC;CACtB;AAED;;;;;GAKG;AACH,wBAAsB,SAAS,CAC7B,IAAI,EAAE,UAAU,EAChB,UAAU,EAAE,eAAe,EAAE,EAC7B,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,eAAe,CAAC,CA2I1B"}
+{"version":3,"file":"fan-out-run.d.ts","sourceRoot":"","sources":["../../src/components/fan-out-run.ts"],"names":[],"mappings":"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"}

package/dist/components/fan-out-run.js

@@ -40,8 +40,55 @@
 import { deployContext, runComponentDeploy, } from "./driver.js";
 import { downstreamWithin, remainingFanOut } from "./fan-out.js";
 import { evaluateGate, gitGateLedgerPort } from "../op/gate.js";
+import { emitGateStep, joinRunEventSinks, progressSinkOf } from "../run-event-stream.js";
 import { planWaveComponent } from "./wave-plan.js";
 import { decideWaveGate, runWaveLoop, waveGateName, waveSetDigest } from "../wave-engine.js";
+/** The sink a fan-out emits to: run events, and the older stream through them. */
+function fanOutSink(options) {
+    return joinRunEventSinks(options.onRunEvent, progressSinkOf(options.onProgress));
+}
+/** The 1-based wave of each component in `waves`. */
+function waveNumbers(waves) {
+    const out = new Map();
+    waves.forEach((wave, i) => wave.forEach((name) => out.set(name, i + 1)));
+    return out;
+}
+/**
+ * The settles of components a fan-out does not start (#4007): `blocked`
+ * when a dependency failed or stopped at a gate, `already-applied` when an
+ * earlier attempt applied it. Each is said once, with no `component-start`
+ * before it, so a reader of the stream sees every component of the plan.
+ */
+function skipSettles(emit, waveOf) {
+    const said = new Set();
+    const say = (component, wave, body) => {
+        if (!emit || wave === undefined || said.has(component))
+            return;
+        said.add(component);
+        emit({ type: "component-settle", wave, component, ...body });
+    };
+    return {
+        /** Each component in `blockedBy` not yet said, in wave order then by name. */
+        blocked(blockedBy) {
+            const order = [...blockedBy.keys()].sort((a, b) => (waveOf.get(a) ?? 0) - (waveOf.get(b) ?? 0) || a.localeCompare(b));
+            for (const component of order)
+                say(component, waveOf.get(component), { status: "blocked", blockedBy: blockedBy.get(component) });
+        },
+        /**
+         * What an earlier attempt left (`remainingFanOut`'s skips): the components
+         * it applied, and the ones its failures blocked. Their wave is the one
+         * they have in the derivation, `derived`, which a resumed run re-layers.
+         */
+        carried(skipped, derived) {
+            for (const skip of skipped) {
+                if (skip.reason === "already-applied")
+                    say(skip.component, derived.get(skip.component), { status: "already-applied" });
+                else if (skip.reason === "blocked" && skip.blockedBy)
+                    say(skip.component, derived.get(skip.component), { status: "blocked", blockedBy: skip.blockedBy });
+            }
+        },
+    };
+}
 /** Thrown when `FanOutWaveGate.only` names a wave whose predecessors have not all applied. */
 export class EarlierWaveNotAppliedError extends Error {
     constructor(wave, earlier, components) {
@@ -78,18 +125,24 @@ export async function runFanOut(plan, components, registry, options) {
     if (options.waveGate) {
         return runGatedWaves(plan, active, components, registry, options, options.waveGate, gates, componentOutputs);
     }
+    const emit = fanOutSink(options);
+    emit?.({ type: "run-start", waves: active.waves });
+    const skips = skipSettles(emit, waveNumbers(active.waves));
+    skips.carried(active.skipped, waveNumbers(plan.waves));
     if (options.gate) {
-        const check = await evaluateGate(gates.port, {
-            op: options.gate.op,
-            gate: options.gate.gate,
+        const gate = options.gate;
+        const check = await emitGateStep(emit, gate, () => evaluateGate(gates.port, {
+            op: gate.op,
+            gate: gate.gate,
             planDigest: active.digest,
-            ...(options.gate.description ? { description: options.gate.description } : {}),
-            ...(options.gate.timeout ? { timeout: options.gate.timeout } : {}),
+            ...(gate.description ? { description: gate.description } : {}),
+            ...(gate.timeout ? { timeout: gate.timeout } : {}),
             ...(options.now ? { now: options.now } : {}),
-        });
+        }));
         if (!check.satisfied) {
             // Nothing ran, so nothing is half-applied and there is nothing to
             // compensate. A gate is a fact, not a failure.
+            emit?.({ type: "run-settle", status: "gated", durationMs: null });
             return {
                 plan: active,
                 status: "gated",
@@ -116,20 +169,19 @@ export async function runFanOut(plan, components, registry, options) {
             blockedBy.set(component, by);
         }
     };
-    options.onProgress?.({ type: "run-start", waves: active.waves });
     for (const [waveIndex, wave] of active.waves.entries()) {
         const waveNum = waveIndex + 1;
         // A component whose upstream failed in an earlier wave is not dispatched.
         const runnable = wave.filter((name) => inPlan.has(name) && !blockedBy.has(name));
         if (runnable.length === 0)
             continue;
-        options.onProgress?.({ type: "wave-start", wave: waveNum, components: runnable });
+        emit?.({ type: "wave-start", wave: waveNum, components: runnable });
         const waveResults = await Promise.all(runnable.map(async (name) => {
-            options.onProgress?.({ type: "component-start", wave: waveNum, component: name });
+            emit?.({ type: "component-start", wave: waveNum, component: name });
             const planned = options.plans?.[name];
-            const result = await runComponentDeploy(byName.get(name), { ...fanOutContext(options, name), ...(planned && Object.keys(planned).length > 0 ? { plans: planned } : {}) }, registry, componentOutputs, options.onProgress, gates);
-            options.onProgress?.({
-                type: "component-done",
+            const result = await runComponentDeploy(byName.get(name), { ...fanOutContext(options, name), ...(planned && Object.keys(planned).length > 0 ? { plans: planned } : {}) }, registry, componentOutputs, undefined, gates, emit);
+            emit?.({
+                type: "component-settle",
                 wave: waveNum,
                 component: name,
                 status: result.status === "fail" ? "failed" : result.status,
@@ -155,11 +207,13 @@ export async function runFanOut(plan, components, registry, options) {
             markBlocked(result.component);
         }
         const waveFailed = waveResults.some((r) => r.status === "fail");
-        options.onProgress?.({
-            type: "wave-done",
+        emit?.({
+            type: "wave-settle",
             wave: waveNum,
             status: waveFailed ? "failed" : waveResults.some((r) => r.status === "gated") ? "gated" : "ok",
         });
+        // What this wave's failures and gates hold back settles now, before the next wave starts.
+        skips.blocked(blockedBy);
     }
     const blocked = [...blockedBy.entries()]
         .sort(([a], [b]) => a.localeCompare(b))
@@ -167,7 +221,7 @@ export async function runFanOut(plan, components, registry, options) {
     // A failure outranks a gate: something is actually broken, and reporting the
     // run as "waiting on a human" would hide it. Same precedence the driver uses.
     const status = failed.length > 0 ? "fail" : gatedFact ? "gated" : "ok";
-    options.onProgress?.({ type: "run-done", status: status === "fail" ? "failed" : status });
+    emit?.({ type: "run-settle", status: status === "fail" ? "failed" : status, durationMs: null });
     return {
         plan: active,
         status,
@@ -230,7 +284,10 @@ async function runGatedWaves(plan, active, components, registry, options, waveGa
             blockedBy.set(component, by);
         }
     };
-    options.onProgress?.({ type: "run-start", waves: plan.waves });
+    const emit = fanOutSink(options);
+    emit?.({ type: "run-start", waves: plan.waves });
+    const skips = skipSettles(emit, waveNumbers(plan.waves));
+    skips.carried(active.skipped, waveNumbers(plan.waves));
     await runWaveLoop({
         first: 1,
         onward: (_k, outcome) => outcome === "next",
@@ -284,6 +341,7 @@ async function runGatedWaves(plan, active, components, registry, options, waveGa
                 results.push(planFailure(f.component, f.error ?? "plan failed"));
                 markBlocked(f.component);
             }
+            skips.blocked(blockedBy);
             const toRun = runnable.filter((name) => plansFor.has(name));
             const record = {
                 wave: waveNum,
@@ -300,14 +358,14 @@ async function runGatedWaves(plan, active, components, registry, options, waveGa
                 options.onWaveSettled?.(record);
                 return { end: "next" };
             }
-            const check = await decideWaveGate(gates.port, {
+            const check = await emitGateStep(emit, { op: waveGate.op, gate: gateName }, () => decideWaveGate(gates.port, {
                 op: waveGate.op,
                 gate: gateName,
                 digest,
                 description: waveGate.description ?? `wave ${waveNum} of ${plan.waves.length}: ${toRun.join(", ")}`,
                 ...(waveGate.timeout ? { timeout: waveGate.timeout } : {}),
                 ...(options.now ? { now: options.now } : {}),
-            });
+            }));
             if (!check.satisfied) {
                 // Nothing in this wave ran, and no later wave is planned: its plan
                 // would read outputs this wave has not written.
@@ -324,14 +382,14 @@ async function runGatedWaves(plan, active, components, registry, options, waveGa
             return { go: { check, record, toRun } };
         },
         async apply({ k: waveNum }, { contexts, plansFor, waveFailures }, { check, record, toRun }) {
-            options.onProgress?.({ type: "wave-start", wave: waveNum, components: toRun });
+            emit?.({ type: "wave-start", wave: waveNum, components: toRun });
             const waveResults = await Promise.all(toRun.map(async (name) => {
-                options.onProgress?.({ type: "component-start", wave: waveNum, component: name });
+                emit?.({ type: "component-start", wave: waveNum, component: name });
                 const plans = plansFor.get(name);
                 const ctx = { ...contexts.get(name), ...(Object.keys(plans).length > 0 ? { plans } : {}) };
-                const result = await runComponentDeploy(byName.get(name), ctx, registry, componentOutputs, options.onProgress, gates);
-                options.onProgress?.({
-                    type: "component-done",
+                const result = await runComponentDeploy(byName.get(name), ctx, registry, componentOutputs, undefined, gates, emit);
+                emit?.({
+                    type: "component-settle",
                     wave: waveNum,
                     component: name,
                     status: result.status === "fail" ? "failed" : result.status,
@@ -362,11 +420,12 @@ async function runGatedWaves(plan, active, components, registry, options, waveGa
             };
             waves.push(settled);
             options.onWaveSettled?.(settled);
-            options.onProgress?.({
-                type: "wave-done",
+            emit?.({
+                type: "wave-settle",
                 wave: waveNum,
                 status: waveFailures.length > 0 ? "failed" : waveResults.some((r) => r.status === "gated") ? "gated" : "ok",
             });
+            skips.blocked(blockedBy);
             return "next";
         },
     });
@@ -374,7 +433,7 @@ async function runGatedWaves(plan, active, components, registry, options, waveGa
         .sort(([a], [b]) => a.localeCompare(b))
         .map(([component, by]) => ({ component, reason: "blocked", blockedBy: by }));
     const status = failed.length > 0 ? "fail" : gatedFact ? "gated" : "ok";
-    options.onProgress?.({ type: "run-done", status: status === "fail" ? "failed" : status });
+    emit?.({ type: "run-settle", status: status === "fail" ? "failed" : status, durationMs: null });
     return {
         // The derivation's waves, not the narrowed re-layering: their numbers name the gates.
         plan: { ...active, waves: plan.waves },

package/dist/components/fan-out.d.ts

@@ -73,6 +73,10 @@ export interface FanOutRequest {
      * {@link FanOutPlan.digest} so an approval is bound to *what* would be
      * applied and not only to who would run. Absent, the digest still identifies
      * the derivation — the selection, the order and the edges it came from.
+     *
+     * `chant components fan-out` does not pass it: its approval stays bound to
+     * the derivation, and it binds a resumed attempt's progress to each
+     * component's input instead (./fan-out-inputs.ts, #4081).
      */
     inputDigests?: Record<string, string>;
     /**

package/dist/components/fan-out.d.ts.map

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

package/dist/components/pr-pipeline.d.ts

@@ -29,6 +29,13 @@
  * squash merges and rebase merges alike, and every job measures from the
  * merge base of that commit and its own head (`resolveMergeBase`).
  *
+ * With `events` (#4007) both commands pass `--events-json`, so the job log
+ * carries the run-event stream, and keep a copy of it under the report
+ * directory through `CHANT_RUN_EVENTS_DIR`, so the report artifact carries
+ * it too. With `reportUrl` both pass `--report-url`, which copies the report,
+ * the change set and the events where a reader outside CI can fetch them;
+ * the job's own environment brings the credentials an `s3://` URL needs.
+ *
  * In a workspace member (#3465) both commands run in the member's directory
  * and pass `--member <name>`, so the member's gate (`pr-<number>-<member>`),
  * note and statuses stay apart from every other member's on the same pull
@@ -55,6 +62,12 @@ export declare const PR_LOOP_IMAGE = "node:22";
 export declare const PR_LOOP_SETUP: string[];
 /** The setup lines for a pipeline running in `image`: the install when it is the default image, none otherwise. */
 export declare function prLoopSetup(image: string): string[];
+/**
+ * Where the jobs keep their run-event files with `events` (#4007), as
+ * `CHANT_RUN_EVENTS_DIR`: inside the report directory, so the report
+ * artifact carries them.
+ */
+export declare const PR_LOOP_EVENTS_DIR = ".chant/pr/run-events";
 /** The `prLoop` generator option (`ComponentPipelineOptions.prLoop`). */
 export interface PrLoopPipelineOptions {
     /** The gate the apply waits on. Default `pr-apply`. */
@@ -66,6 +79,18 @@ export interface PrLoopPipelineOptions {
     branch?: string;
     /** Count an approval only from someone who approved the pull request on the forge. Default true. */
     requireReview?: boolean;
+    /**
+     * Stream each job's run events (#4007): `--events-json` on both commands,
+     * and `CHANT_RUN_EVENTS_DIR` set to {@link PR_LOOP_EVENTS_DIR}. Default false.
+     */
+    events?: boolean;
+    /**
+     * Copy each job's report, change set and events to this `s3://` or
+     * `file://` URL (#4007, `--report-url`), under `<pr>/<commit>/`. It is
+     * passed in double quotes, so it may name a variable the job expands,
+     * such as `$CHANT_REPORT_URL`.
+     */
+    reportUrl?: string;
     /**
      * Which GitHub-shaped forge the workflow is for. Set by the forgejo
      * generator, which reuses the github one; a caller never needs to.

package/dist/components/pr-pipeline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pr-pipeline.d.ts","sourceRoot":"","sources":["../../src/components/pr-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAI7C,kEAAkE;AAClE,eAAO,MAAM,kBAAkB,cAAc,CAAC;AAE9C;;;;GAIG;AACH,eAAO,MAAM,eAAe,mCAAmC,CAAC;AAEhE;;;;;GAKG;AACH,eAAO,MAAM,aAAa,YAAW,CAAC;AAEtC,8CAA8C;AAC9C,eAAO,MAAM,aAAa,UAEzB,CAAC;AAEF,mHAAmH;AACnH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAEnD;AAED,yEAAyE;AACzE,MAAM,WAAW,qBAAqB;IACpC,uDAAuD;IACvD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oGAAoG;IACpG,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;OAGG;IACH,KAAK,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC;CAC9B;AAED,8FAA8F;AAC9F,MAAM,WAAW,SAAS;IACxB,yBAAyB;IACzB,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;IAC1B,2EAA2E;IAC3E,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,4FAA4F;IAC5F,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,qBAA0B,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,EAAE,CA2B3H;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAEjE;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAErF;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAU1D"}
+{"version":3,"file":"pr-pipeline.d.ts","sourceRoot":"","sources":["../../src/components/pr-pipeline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAI7C,kEAAkE;AAClE,eAAO,MAAM,kBAAkB,cAAc,CAAC;AAE9C;;;;GAIG;AACH,eAAO,MAAM,eAAe,mCAAmC,CAAC;AAEhE;;;;;GAKG;AACH,eAAO,MAAM,aAAa,YAAW,CAAC;AAEtC,8CAA8C;AAC9C,eAAO,MAAM,aAAa,UAEzB,CAAC;AAEF,mHAAmH;AACnH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAEnD;AAED;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,yBAAqC,CAAC;AAErE,yEAAyE;AACzE,MAAM,WAAW,qBAAqB;IACpC,uDAAuD;IACvD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oGAAoG;IACpG,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,KAAK,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAC;CAC9B;AAED,8FAA8F;AAC9F,MAAM,WAAW,SAAS;IACxB,yBAAyB;IACzB,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;IAC1B,2EAA2E;IAC3E,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,4FAA4F;IAC5F,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,qBAA0B,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,EAAE,CAgC3H;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAEjE;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAErF;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAU1D"}

package/dist/components/pr-pipeline.js

@@ -29,6 +29,13 @@
  * squash merges and rebase merges alike, and every job measures from the
  * merge base of that commit and its own head (`resolveMergeBase`).
  *
+ * With `events` (#4007) both commands pass `--events-json`, so the job log
+ * carries the run-event stream, and keep a copy of it under the report
+ * directory through `CHANT_RUN_EVENTS_DIR`, so the report artifact carries
+ * it too. With `reportUrl` both pass `--report-url`, which copies the report,
+ * the change set and the events where a reader outside CI can fetch them;
+ * the job's own environment brings the credentials an `s3://` URL needs.
+ *
  * In a workspace member (#3465) both commands run in the member's directory
  * and pass `--member <name>`, so the member's gate (`pr-<number>-<member>`),
  * note and statuses stay apart from every other member's on the same pull
@@ -60,6 +67,12 @@ export const PR_LOOP_SETUP = [
 export function prLoopSetup(image) {
     return image === PR_LOOP_IMAGE ? PR_LOOP_SETUP : [];
 }
+/**
+ * Where the jobs keep their run-event files with `events` (#4007), as
+ * `CHANT_RUN_EVENTS_DIR`: inside the report directory, so the report
+ * artifact carries them.
+ */
+export const PR_LOOP_EVENTS_DIR = `${PR_LOOP_REPORT_DIR}/run-events`;
 /**
  * The two jobs for `forge`. `member` is the workspace member the pipeline is
  * generated for; the commands then run in its directory, so `--output` is
@@ -70,16 +83,21 @@ export function prLoopJobs(forge, env, options = {}, member) {
     const common = [
         "--env", env, "--gate", gate, "--output", PR_LOOP_REPORT_DIR, "--forge", forge,
         ...(member ? ["--member", member] : []),
+        ...(options.events ? ["--events-json"] : []),
+        ...(options.reportUrl ? ["--report-url", JSON.stringify(options.reportUrl)] : []),
     ];
     const github = forge !== "gitlab";
-    const token = github ? { GITHUB_TOKEN: GITHUB_JOB_TOKEN } : {};
+    const jobEnv = {
+        ...(github ? { GITHUB_TOKEN: GITHUB_JOB_TOKEN } : {}),
+        ...(options.events ? { CHANT_RUN_EVENTS_DIR: PR_LOOP_EVENTS_DIR } : {}),
+    };
     return [
         {
             jobName: "plan",
             command: ["chant", "components", "pr-plan", "--base", '"$BASE_SHA"', "--pr", '"$PR_NUMBER"', ...common].join(" "),
             env: github
-                ? { BASE_SHA: "${{ github.event.pull_request.base.sha }}", PR_NUMBER: "${{ github.event.pull_request.number }}", ...token }
-                : { BASE_SHA: "$CI_MERGE_REQUEST_DIFF_BASE_SHA", PR_NUMBER: "$CI_MERGE_REQUEST_IID" },
+                ? { BASE_SHA: "${{ github.event.pull_request.base.sha }}", PR_NUMBER: "${{ github.event.pull_request.number }}", ...jobEnv }
+                : { BASE_SHA: "$CI_MERGE_REQUEST_DIFF_BASE_SHA", PR_NUMBER: "$CI_MERGE_REQUEST_IID", ...jobEnv },
         },
         {
             jobName: "apply",
@@ -88,7 +106,7 @@ export function prLoopJobs(forge, env, options = {}, member) {
                 ...(options.requireReview === false ? [] : ["--require-review"]),
                 "--resume", PR_APPLY_RECORD,
             ].join(" "),
-            env: github ? { BASE_SHA: "${{ github.event.before }}", ...token } : { BASE_SHA: "$CI_COMMIT_BEFORE_SHA" },
+            env: github ? { BASE_SHA: "${{ github.event.before }}", ...jobEnv } : { BASE_SHA: "$CI_COMMIT_BEFORE_SHA", ...jobEnv },
             ...(github ? {} : { setup: [gitlabBaseFallback(options.branch)] }),
         },
     ];

package/dist/components/pr-run.d.ts

@@ -41,6 +41,7 @@ import { type ComponentChangeSignal, type FanOutPlan } from "./fan-out.js";
 import type { PrApplyRecord } from "./fan-out-record.js";
 import type { CapabilityRegistry } from "./capability.js";
 import type { RunProgressEvent } from "./run-progress.js";
+import type { RunEventSink } from "../run-event-stream.js";
 export interface PrPlanSetOptions {
     /** Every component in the project. */
     components: DriverComponent[];
@@ -51,7 +52,15 @@ export interface PrPlanSetOptions {
     vars?: Record<string, unknown>;
     /** Outputs supplied by the caller (`--seed-outputs`). They win over outputs read here. */
     seededOutputs?: Record<string, Record<string, unknown>>;
+    /**
+     * Where the planning's events go (#4041): a `plan` phase with no
+     * component, and in it one `plan` step per component, started as its wave
+     * is planned and settled `ok` or `failed`.
+     */
+    onRunEvent?: RunEventSink;
 }
+/** The phase a pull request's planning is, in its run's events. */
+export declare const PR_PLAN_PHASE = "plan";
 /** Every member of a pull request, planned. */
 export interface PrPlanSet {
     /** The change-set document over every member. Its digest is what the gate binds. */
@@ -101,6 +110,8 @@ export interface PrApplyOptions {
     /** The set {@link planPrSet} planned and the gate approved, or {@link resumePrSet}'s set. */
     set: PrPlanSet;
     onProgress?: (event: RunProgressEvent) => void;
+    /** Where the apply's events go (#4041): the fan-out's run events. */
+    onRunEvent?: RunEventSink;
     /**
      * What an earlier attempt at this approved set applied (#3464): its
      * components, which are reported applied and not run again, and the

package/dist/components/pr-run.d.ts.map

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

package/dist/components/pr-run.js

@@ -40,6 +40,8 @@ import { deployUnits } from "./deploy-units.js";
 import { runFanOut } from "./fan-out-run.js";
 import { remainingFanOut } from "./fan-out.js";
 import { planWaveComponent, readComponentOutputs } from "./wave-plan.js";
+/** The phase a pull request's planning is, in its run's events. */
+export const PR_PLAN_PHASE = "plan";
 /** A failed component's members: the units its steps target, else the component itself. */
 function failedParts(component, error) {
     const units = deployUnits(component.deploy).map((u) => u.unit);
@@ -61,6 +63,8 @@ export async function planPrSet(options) {
     const componentOf = new Map();
     const plans = {};
     let failed = false;
+    const emit = options.onRunEvent;
+    emit?.({ type: "phase-start", component: null, phase: PR_PLAN_PHASE });
     for (const wave of options.plan.waves) {
         // The dependencies' outputs first, each read once. A dependency that
         // cannot say leaves its references unresolved, which its dependent's
@@ -75,7 +79,20 @@ export async function planPrSet(options) {
                     outputs[dep] = found;
             }
         }
-        const planned = await Promise.all(wave.map((name) => planWaveComponent(byName.get(name), options.registry, deployContext(options, name), outputs)));
+        const planned = await Promise.all(wave.map(async (name) => {
+            const at = { component: name, phase: PR_PLAN_PHASE, step: "plan" };
+            emit?.({ type: "step-start", ...at });
+            const start = Date.now();
+            const p = await planWaveComponent(byName.get(name), options.registry, deployContext(options, name), outputs);
+            emit?.({
+                type: "step-settle",
+                ...at,
+                status: "error" in p ? "failed" : "ok",
+                durationMs: Date.now() - start,
+                ...("error" in p ? { error: p.error } : {}),
+            });
+            return p;
+        }));
         for (const p of planned) {
             const component = byName.get(p.component);
             if ("error" in p) {
@@ -93,6 +110,7 @@ export async function planPrSet(options) {
             }
         }
     }
+    emit?.({ type: "phase-settle", component: null, phase: PR_PLAN_PHASE, status: failed ? "failed" : "ok" });
     const doc = composeChangeSet(parts);
     const members = doc.members.map((m) => ({
         member: m.member,
@@ -161,6 +179,7 @@ export async function applyPrSet(options) {
         plans: options.set.plans,
         componentOutputs: { ...before },
         ...(options.onProgress ? { onProgress: options.onProgress } : {}),
+        ...(options.onRunEvent ? { onRunEvent: options.onRunEvent } : {}),
         ...(options.onComponentSettled ? { onComponentSettled: options.onComponentSettled } : {}),
     });
     const completed = new Set(run.completed);

package/dist/components/promote-order.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The environment `chant components promote` reads from, given the member's
+ * promotion order (#4030, see `../workspace/promotion-order.ts`). These
+ * refusals are promote's own and are not codes of the workspace read contract.
+ */
+import type { PromotionStep } from "../workspace/promotion-order.js";
+/** The refusals `components promote` gives for the declared order. Stable: scripts may match on them. */
+export declare const PROMOTE_ORDER_CODES: readonly [
+/** `--from` is more than one step behind `--to` in the declared order, and `--allow-skip` was not given. */
+"promote-skips-environment", 
+/** `--to` is the first step of the declared order, so no environment comes before it to default `--from` to. */
+"promote-no-previous-environment", 
+/** `--from` was left out and `--to` is not a step of the declared order, so there is nothing to default it from. */
+"promote-to-not-in-order"];
+export type PromoteOrderCode = (typeof PROMOTE_ORDER_CODES)[number];
+export interface PromotionRefusal {
+    error: {
+        code: PromoteOrderCode;
+        message: string;
+        fix: string;
+    };
+}
+/**
+ * The environment a promote reads from. With an order declared, `--from`
+ * defaults to the step before `to`, and a `--from` that skips a step is
+ * refused unless `allowSkip`. Without an order, or when `to` or `from` is not
+ * a step of it, the order has nothing to say and `from` is returned as given
+ * (`undefined` is the caller's to refuse, as before).
+ */
+export declare function resolvePromotionSource(opts: {
+    order: readonly PromotionStep[];
+    to: string;
+    from?: string;
+    allowSkip?: boolean;
+}): {
+    from: string | undefined;
+} | PromotionRefusal;
+//# sourceMappingURL=promote-order.d.ts.map

package/dist/components/promote-order.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"promote-order.d.ts","sourceRoot":"","sources":["../../src/components/promote-order.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAElE,yGAAyG;AACzG,eAAO,MAAM,mBAAmB;AAC9B,4GAA4G;AAC5G,2BAA2B;AAC3B,gHAAgH;AAChH,iCAAiC;AACjC,oHAAoH;AACpH,yBAAyB,CACjB,CAAC;AACX,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEpE,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE;QAAE,IAAI,EAAE,gBAAgB,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;CACjE;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE;IAC3C,KAAK,EAAE,SAAS,aAAa,EAAE,CAAC;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB,GAAG;IAAE,IAAI,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,GAAG,gBAAgB,CAuClD"}

package/dist/components/promote-order.js

@@ -0,0 +1,62 @@
+/**
+ * The environment `chant components promote` reads from, given the member's
+ * promotion order (#4030, see `../workspace/promotion-order.ts`). These
+ * refusals are promote's own and are not codes of the workspace read contract.
+ */
+/** The refusals `components promote` gives for the declared order. Stable: scripts may match on them. */
+export const PROMOTE_ORDER_CODES = [
+    /** `--from` is more than one step behind `--to` in the declared order, and `--allow-skip` was not given. */
+    "promote-skips-environment",
+    /** `--to` is the first step of the declared order, so no environment comes before it to default `--from` to. */
+    "promote-no-previous-environment",
+    /** `--from` was left out and `--to` is not a step of the declared order, so there is nothing to default it from. */
+    "promote-to-not-in-order",
+];
+/**
+ * The environment a promote reads from. With an order declared, `--from`
+ * defaults to the step before `to`, and a `--from` that skips a step is
+ * refused unless `allowSkip`. Without an order, or when `to` or `from` is not
+ * a step of it, the order has nothing to say and `from` is returned as given
+ * (`undefined` is the caller's to refuse, as before).
+ */
+export function resolvePromotionSource(opts) {
+    const { order, to, from, allowSkip } = opts;
+    const names = order.map((s) => s.name);
+    const list = names.join(", ");
+    const toAt = names.indexOf(to);
+    if (from === undefined) {
+        if (order.length === 0)
+            return { from: undefined };
+        if (toAt < 0) {
+            return {
+                error: {
+                    code: "promote-to-not-in-order",
+                    message: `--from was not given, and "${to}" is not a step of the declared promotion order (${list})`,
+                    fix: `Pass --from <env>, or add "${to}" to the environments array of this member's chant.config.ts.`,
+                },
+            };
+        }
+        if (toAt === 0) {
+            return {
+                error: {
+                    code: "promote-no-previous-environment",
+                    message: `"${to}" is the first step of the declared promotion order (${list}), so there is no environment to promote from`,
+                    fix: `Deploy "${to}" with chant run --env ${to}, or pass --from <env> to promote from an environment outside the order.`,
+                },
+            };
+        }
+        return { from: names[toAt - 1] };
+    }
+    const fromAt = names.indexOf(from);
+    if (toAt >= 0 && fromAt >= 0 && fromAt < toAt - 1 && !allowSkip) {
+        const skipped = names.slice(fromAt + 1, toAt);
+        return {
+            error: {
+                code: "promote-skips-environment",
+                message: `promoting ${from} to ${to} skips ${skipped.join(", ")} in the declared promotion order (${list})`,
+                fix: `Promote to ${skipped[0]} first, or pass --allow-skip to promote ${from} to ${to} anyway.`,
+            },
+        };
+    }
+    return { from };
+}