@intentius/chant 0.124.23 → 0.124.24

package/dist/op/op-waves.js

@@ -216,6 +216,8 @@ export function assertOpWavesSpec(spec) {
     }
     if (spec.neverOverMcp !== undefined && typeof spec.neverOverMcp !== "boolean")
         throw new Error(`${where}: neverOverMcp must be true or false.`);
+    if (spec.runner !== undefined)
+        assertOpWaveRunner(where, "runner", spec.runner);
     if (spec.notify !== undefined) {
         const problem = notifyConfigProblem(spec.notify, "notify");
         if (problem)
@@ -241,6 +243,12 @@ export function assertOpWavesSpec(spec) {
             if (problems.length > 0)
                 throw new Error(`${where}: wave "${wave.name}": ${problems.join("; ")}.`);
         }
+        if (wave.runner !== undefined)
+            assertOpWaveRunner(where, `wave "${wave.name}" runner`, wave.runner);
+        if (wave.idTokens !== undefined)
+            assertOpWaveIdTokens(where, `wave "${wave.name}" idTokens`, wave.idTokens);
+        if (wave.jobs !== undefined)
+            assertOpWaveJobGroups(where, wave);
         if (wave.discover !== undefined && typeof wave.discover !== "boolean")
             throw new Error(`${where}: wave "${wave.name}" has discover ${JSON.stringify(wave.discover)}; use true or false.`);
         if (wave.rest !== undefined && typeof wave.rest !== "boolean")
@@ -282,7 +290,127 @@ export function assertOpWavesSpec(spec) {
         if (shares > wave.runs.length) {
             throw new Error(`${where}: wave "${wave.name}" has ${shares} shares for ${wave.runs.length} runs, so a share would apply nothing.`);
         }
+        if (wave.jobs !== undefined) {
+            const problem = opWaveGroupsProblem(wave, wave.runs.map((r) => r.target));
+            if (problem)
+                throw new Error(`${where}: ${problem}.`);
+        }
+    }
+}
+const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** Refuse a `runner` no forge could read (#3914). */
+function assertOpWaveRunner(where, field, runner) {
+    const labels = (value) => Array.isArray(value) && value.length > 0 && value.every((l) => typeof l === "string" && l.trim() !== "");
+    if (typeof runner === "string" && runner.trim() !== "")
+        return;
+    if (labels(runner))
+        return;
+    if (runner !== null && typeof runner === "object" && !Array.isArray(runner)) {
+        const { group, labels: l, ...rest } = runner;
+        const extra = Object.keys(rest)[0];
+        if (extra !== undefined)
+            throw new Error(`${where}: ${field}.${extra} is not a setting; a runner group is { "group": "<name>", "labels"?: [...] }.`);
+        if (typeof group === "string" && group.trim() !== "" && (l === undefined || labels(l)))
+            return;
+    }
+    throw new Error(`${where}: ${field} must be a runner label, a non-empty list of labels, or { "group": "<name>", "labels"?: [...] } (GitHub only).`);
+}
+/** Refuse `idTokens` that are not `{ <variable>: <audience> }` (#3914). */
+function assertOpWaveIdTokens(where, field, idTokens) {
+    if (idTokens === null || typeof idTokens !== "object" || Array.isArray(idTokens) || Object.keys(idTokens).length === 0) {
+        throw new Error(`${where}: ${field} must be { "<variable>": "<audience>" }, with at least one token.`);
     }
+    for (const [name, aud] of Object.entries(idTokens)) {
+        if (!ENV_NAME.test(name))
+            throw new Error(`${where}: ${field} names "${name}", which is not a variable name (letters, digits and "_", not starting with a digit).`);
+        if (typeof aud !== "string" || aud.trim() === "")
+            throw new Error(`${where}: ${field}.${name} must be an audience, a non-empty string.`);
+    }
+}
+/** Refuse a wave's `jobs` no pipeline could render (#3914). Which runs each group holds is {@link opWaveGroupsProblem}'s. */
+function assertOpWaveJobGroups(where, wave) {
+    const at = `wave "${wave.name}"`;
+    if (!Array.isArray(wave.jobs) || wave.jobs.length === 0)
+        throw new Error(`${where}: ${at} jobs must be a non-empty list of job groups.`);
+    if ((wave.shares ?? 1) > 1)
+        throw new Error(`${where}: ${at} has jobs and shares; split each job group with its own shares.`);
+    if (wave.rest)
+        throw new Error(`${where}: ${at} has jobs and rest; the waves after it run in its one job, so its apply cannot be split into groups.`);
+    const names = new Set();
+    wave.jobs.forEach((group, i) => {
+        if (group === null || typeof group !== "object")
+            throw new Error(`${where}: ${at} jobs[${i}] must be { "name", "runs", ... }.`);
+        const field = `${at} jobs[${i}]${typeof group.name === "string" ? ` (${group.name})` : ""}`;
+        if (typeof group.name !== "string" || !NAME.test(group.name))
+            throw new Error(`${where}: ${field} must be named with lowercase letters, digits, "-" and "_".`);
+        if (group.name === "decide" || /^share-\d+$/.test(group.name))
+            throw new Error(`${where}: ${field} is named like the wave's own jobs (decide, share-<i>); name it another way.`);
+        if (names.has(group.name))
+            throw new Error(`${where}: ${at} names job group "${group.name}" twice.`);
+        names.add(group.name);
+        const known = new Set(["name", "runs", "shares", "runner", "environment", "variables", "setup", "idTokens"]);
+        const extra = Object.keys(group).find((key) => !known.has(key));
+        if (extra !== undefined)
+            throw new Error(`${where}: ${field}.${extra} is not a setting; a job group takes ${[...known].join(", ")}.`);
+        if (!Array.isArray(group.runs) || group.runs.length === 0 || !group.runs.every((r) => typeof r === "string" && r.trim() !== "")) {
+            throw new Error(`${where}: ${field} runs must be a non-empty list of targets or patterns.`);
+        }
+        const shares = group.shares ?? 1;
+        if (!Number.isInteger(shares) || shares < 1)
+            throw new Error(`${where}: ${field} has shares ${group.shares}; use a whole number from 1.`);
+        if (group.runner !== undefined)
+            assertOpWaveRunner(where, `${field} runner`, group.runner);
+        if (group.idTokens !== undefined)
+            assertOpWaveIdTokens(where, `${field} idTokens`, group.idTokens);
+        if (group.variables !== undefined && (group.variables === null || typeof group.variables !== "object" || Array.isArray(group.variables) || !Object.values(group.variables).every((v) => typeof v === "string"))) {
+            throw new Error(`${where}: ${field} variables must be { "<name>": "<value>" }.`);
+        }
+        if (group.setup !== undefined && !Array.isArray(group.setup))
+            throw new Error(`${where}: ${field} setup must be a list of steps.`);
+        if (group.environment !== undefined && (group.environment === null || typeof group.environment !== "object" || typeof group.environment.name !== "string")) {
+            throw new Error(`${where}: ${field} environment must be { "name", "url"? }.`);
+        }
+    });
+}
+/**
+ * True when `target` matches a job group's `runs` entry (#3914): the target
+ * itself, or a pattern where `*` matches within one `/` segment and `**`
+ * across segments.
+ */
+export function opWaveRunMatches(pattern, target) {
+    if (!pattern.includes("*"))
+        return pattern === target;
+    let re = "";
+    for (let i = 0; i < pattern.length; i++) {
+        const c = pattern[i];
+        if (c === "*" && pattern[i + 1] === "*") {
+            re += ".*";
+            i++;
+        }
+        else if (c === "*")
+            re += "[^/]*";
+        else
+            re += c.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
+    }
+    return new RegExp(`^${re}$`).test(target);
+}
+/** The runs of `runs` that job group `group` holds (#3914). */
+export function opWaveGroupRuns(group, runs) {
+    return runs.filter((run) => group.runs.some((pattern) => opWaveRunMatches(pattern, run.target)));
+}
+/**
+ * What is wrong with how a wave's job groups hold `targets` (#3914): a run in
+ * two groups, or in none. Undefined when each run is in exactly one.
+ */
+export function opWaveGroupsProblem(wave, targets) {
+    for (const target of targets) {
+        const holders = (wave.jobs ?? []).filter((group) => group.runs.some((pattern) => opWaveRunMatches(pattern, target))).map((g) => `"${g.name}"`);
+        if (holders.length > 1)
+            return `wave "${wave.name}" jobs: run "${target}" is in job groups ${holders.join(" and ")}; each run is in exactly one`;
+        if (holders.length === 0)
+            return `wave "${wave.name}" jobs: run "${target}" is in no job group; each run is in exactly one`;
+    }
+    return undefined;
 }
 function assertArgv(where, field, argv) {
     if (!Array.isArray(argv) || argv.length === 0 || !argv.every((part) => typeof part === "string") || argv[0] === "") {
@@ -381,7 +509,7 @@ export function opWaveJobs(spec, specFile) {
         const command = ["chant", "run", "wave", "--spec", specFile, "--wave", String(k), ...(spec.base ? ["--base", spec.base] : [])];
         const prefix = `wave-${k}-${wave.name}`;
         const shares = wave.shares ?? 1;
-        if (shares === 1) {
+        if (shares === 1 && wave.jobs === undefined) {
             jobs.push({ jobName: prefix, wave: k, waveName: wave.name, kind: "wave", needs: previous, command });
             previous = [prefix];
             return;
@@ -390,6 +518,26 @@ export function opWaveJobs(spec, specFile) {
         const decide = `${prefix}-decide`;
         jobs.push({ jobName: decide, wave: k, waveName: wave.name, kind: "decide", needs: previous, command: [...command, "--decide"], record });
         const shareJobs = [];
+        if (wave.jobs !== undefined) {
+            // #3914: a job per group, or per share of a group, each applying its runs under the deciding job's decision.
+            for (const group of wave.jobs) {
+                const groupShares = group.shares ?? 1;
+                const groupCommand = [...command, "--group", group.name];
+                if (groupShares === 1) {
+                    const jobName = `${prefix}-${group.name}`;
+                    shareJobs.push(jobName);
+                    jobs.push({ jobName, wave: k, waveName: wave.name, kind: "share", group: group.name, needs: [decide], command: groupCommand, record });
+                    continue;
+                }
+                for (let share = 1; share <= groupShares; share++) {
+                    const jobName = `${prefix}-${group.name}-share-${share}`;
+                    shareJobs.push(jobName);
+                    jobs.push({ jobName, wave: k, waveName: wave.name, kind: "share", group: group.name, share, needs: [decide], command: [...groupCommand, "--share", String(share)], record });
+                }
+            }
+            previous = shareJobs;
+            return;
+        }
         for (let share = 1; share <= shares; share++) {
             const jobName = `${prefix}-share-${share}`;
             shareJobs.push(jobName);
@@ -399,6 +547,10 @@ export function opWaveJobs(spec, specFile) {
     });
     return jobs;
 }
+/** The job group a job applies (#3914), or undefined for a wave's own jobs. */
+export function opWaveGroupOf(spec, job) {
+    return job.group === undefined ? undefined : spec.waves[job.wave - 1]?.jobs?.find((g) => g.name === job.group);
+}
 /** The wave a job belongs to. */
 export function opWaveOf(spec, job) {
     return spec.waves[job.wave - 1];

package/dist/op/runtimes/local.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"local.d.ts","sourceRoot":"","sources":["../../../src/op/runtimes/local.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAUH,OAAO,EAML,KAAK,iBAAiB,EACvB,MAAM,YAAY,CAAC;AA0CpB;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,GAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,iBAAiB,CAsJ3F"}
+{"version":3,"file":"local.d.ts","sourceRoot":"","sources":["../../../src/op/runtimes/local.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAWH,OAAO,EAML,KAAK,iBAAiB,EACvB,MAAM,YAAY,CAAC;AA0CpB;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,GAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,iBAAiB,CA2J3F"}

package/dist/op/runtimes/local.js

@@ -21,6 +21,7 @@ import { lexiconNames } from "../../lexicon-module.js";
 import { loadChantConfig } from "../../config.js";
 import { loadActivities, loadProfiles } from "../activity-registry.js";
 import { runOpLocally, OpRunFailure } from "../local-executor.js";
+import { stepHeartbeatMs } from "../step-console.js";
 import { runComponents } from "../../components/cli-support.js";
 import { discoverOps } from "../discover.js";
 import { readRunLedger, runEnvOf, DEFAULT_RUN_ENV } from "../../lifecycle/run-ledger.js";
@@ -142,6 +143,11 @@ export function createLocalOpRuntime(opts = {}) {
                         onLedgerError: (err) => process.stderr.write(`warning: run "${runId}" of "${op.name}" finished, but its record could not be ` +
                             `appended to the run ledger: ${err instanceof Error ? err.message : String(err)}\n`),
                         ...(startOpts.progress ? { onRecord: startOpts.progress } : {}),
+                        // #3956: a running step's output, and a still-running line while
+                        // it is quiet, on stderr as they happen; stdout stays the
+                        // `--json` record's and `--progress-json`'s.
+                        stepOutput: (line) => process.stderr.write(`${line}\n`),
+                        stepHeartbeatMs: stepHeartbeatMs(process.env, (message) => process.stderr.write(`warning: ${message}\n`)),
                         ...(startOpts.work ? { work: startOpts.work } : {}),
                         onWorkLeaseWarning: (message) => process.stderr.write(`warning: "${op.name}" could not renew its work lease, retrying at the next beat: ${message}\n`),
                     });

package/dist/op/step-console.d.ts

@@ -0,0 +1,65 @@
+/**
+ * A running step's console (#3956): its output as it arrives, and a
+ * "still running" line while it is quiet.
+ *
+ * The run's own render (`./local-output.ts`) is printed once the run
+ * settles, so before this a 15-minute step printed nothing for 15 minutes and
+ * a watchdog reading the output killed a healthy run. When the caller hands
+ * the executor a writer (`RunOpOptions.stepOutput`, which the local runtime
+ * passes, writing to stderr), each activity step runs with a console:
+ *
+ * - an activity that runs a process (`shellCmd`) passes each line the process
+ *   writes, stdout and stderr alike, through {@link stepOutputLine}, and it is
+ *   printed at once as `[<phase>] <step> | <line>`;
+ * - a step that prints nothing for `heartbeatMs` (an activity that only
+ *   returns a value, or a command that is quiet) gets
+ *   `[<phase>] <step>: still running after <n>s` each time that much passes.
+ *
+ * `<step>` is the step's id when it has one, else its call as the run's
+ * render names it, `fn(arg=value, ...)`, cut to a readable length. Without a
+ * writer there is no console, and `shellCmd` prints a command's stderr when it
+ * ends, as it did before.
+ */
+/** How long a step may be quiet before the runner says it is still running. */
+export declare const DEFAULT_STEP_HEARTBEAT_MS = 60000;
+/** The environment variable that sets the interval: a duration ("30s", "5m"), or `0` / `off`. */
+export declare const STEP_HEARTBEAT_ENV = "CHANT_STEP_HEARTBEAT";
+/** Where a run's step lines go, and how often a quiet step says it is still running. */
+export interface RunConsole {
+    write: (line: string) => void;
+    heartbeatMs?: number;
+}
+/** Run `fn` as a run whose steps print through `run`. Without one, steps get no console. */
+export declare function withRunConsole<T>(run: RunConsole | undefined, fn: () => Promise<T>): Promise<T>;
+/** The name a step's lines carry: its id, else `fn(args)` on one line, cut to {@link MAX_LABEL}. */
+export declare function stepLabel(fn: string, args: Record<string, unknown>, id?: string): string;
+/**
+ * Run `fn` with a console for one step, when the run has one
+ * ({@link withRunConsole}). The heartbeat timer is stopped when `fn`
+ * settles; it never holds the process open on its own.
+ */
+export declare function withStepConsole<T>(opts: {
+    phase: string;
+    label: string;
+}, fn: () => Promise<T>): Promise<T>;
+/** Whether the calling activity runs under a step console, so its output is printed as it arrives. */
+export declare function hasStepConsole(): boolean;
+/** Print one line of the calling step's output. A no-op outside a step console. */
+export declare function stepOutputLine(text: string): void;
+/**
+ * A sink for a stream's chunks that prints whole lines to the calling step's
+ * console as they complete; `end()` prints what is left. The console is the
+ * one current when the splitter is made, since a stream's `data` events need
+ * not run in the step's async context.
+ */
+export declare function stepLineSplitter(): {
+    push(chunk: string | Buffer): void;
+    end(): void;
+};
+/**
+ * The heartbeat interval `CHANT_STEP_HEARTBEAT` sets, or the default. `0` and
+ * `off` turn it off. A value that is not a duration falls back to the default
+ * and says so through `warn`.
+ */
+export declare function stepHeartbeatMs(env?: NodeJS.ProcessEnv, warn?: (message: string) => void): number;
+//# sourceMappingURL=step-console.d.ts.map

package/dist/op/step-console.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"step-console.d.ts","sourceRoot":"","sources":["../../src/op/step-console.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAKH,+EAA+E;AAC/E,eAAO,MAAM,yBAAyB,QAAS,CAAC;AAEhD,iGAAiG;AACjG,eAAO,MAAM,kBAAkB,yBAAyB,CAAC;AASzD,wFAAwF;AACxF,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9B,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAKD,4FAA4F;AAC5F,wBAAgB,cAAc,CAAC,CAAC,EAAE,GAAG,EAAE,UAAU,GAAG,SAAS,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAE/F;AAQD,oGAAoG;AACpG,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAIxF;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CAAC,CAAC,EAAE,IAAI,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CA6BjH;AAED,sGAAsG;AACtG,wBAAgB,cAAc,IAAI,OAAO,CAExC;AAED,mFAAmF;AACnF,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAEjD;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,IAAI;IAAE,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAAC,GAAG,IAAI,IAAI,CAAA;CAAE,CAmBtF;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,EAAE,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,CAU9G"}

package/dist/op/step-console.js

@@ -0,0 +1,140 @@
+/**
+ * A running step's console (#3956): its output as it arrives, and a
+ * "still running" line while it is quiet.
+ *
+ * The run's own render (`./local-output.ts`) is printed once the run
+ * settles, so before this a 15-minute step printed nothing for 15 minutes and
+ * a watchdog reading the output killed a healthy run. When the caller hands
+ * the executor a writer (`RunOpOptions.stepOutput`, which the local runtime
+ * passes, writing to stderr), each activity step runs with a console:
+ *
+ * - an activity that runs a process (`shellCmd`) passes each line the process
+ *   writes, stdout and stderr alike, through {@link stepOutputLine}, and it is
+ *   printed at once as `[<phase>] <step> | <line>`;
+ * - a step that prints nothing for `heartbeatMs` (an activity that only
+ *   returns a value, or a command that is quiet) gets
+ *   `[<phase>] <step>: still running after <n>s` each time that much passes.
+ *
+ * `<step>` is the step's id when it has one, else its call as the run's
+ * render names it, `fn(arg=value, ...)`, cut to a readable length. Without a
+ * writer there is no console, and `shellCmd` prints a command's stderr when it
+ * ends, as it did before.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+import { parseDuration } from "./duration.js";
+/** How long a step may be quiet before the runner says it is still running. */
+export const DEFAULT_STEP_HEARTBEAT_MS = 60000;
+/** The environment variable that sets the interval: a duration ("30s", "5m"), or `0` / `off`. */
+export const STEP_HEARTBEAT_ENV = "CHANT_STEP_HEARTBEAT";
+/** The longest step label a line carries before it is cut. */
+const MAX_LABEL = 60;
+const store = new AsyncLocalStorage();
+const runStore = new AsyncLocalStorage();
+/** Run `fn` as a run whose steps print through `run`. Without one, steps get no console. */
+export function withRunConsole(run, fn) {
+    return run ? runStore.run(run, fn) : fn();
+}
+function formatArgs(args) {
+    return Object.entries(args)
+        .map(([k, v]) => `${k}=${typeof v === "string" ? v : JSON.stringify(v)}`)
+        .join(", ");
+}
+/** The name a step's lines carry: its id, else `fn(args)` on one line, cut to {@link MAX_LABEL}. */
+export function stepLabel(fn, args, id) {
+    if (id)
+        return id;
+    const call = `${fn}(${formatArgs(args)})`.replace(/\s+/g, " ");
+    return call.length > MAX_LABEL ? `${call.slice(0, MAX_LABEL - 4)}...)` : call;
+}
+/**
+ * Run `fn` with a console for one step, when the run has one
+ * ({@link withRunConsole}). The heartbeat timer is stopped when `fn`
+ * settles; it never holds the process open on its own.
+ */
+export async function withStepConsole(opts, fn) {
+    const run = runStore.getStore();
+    if (!run)
+        return fn();
+    const { write } = run;
+    const prefix = `[${opts.phase}] ${opts.label}`;
+    const started = Date.now();
+    let spoke = false;
+    const sink = {
+        line(text) {
+            spoke = true;
+            write(`${prefix} | ${text}`);
+        },
+    };
+    const every = run.heartbeatMs ?? DEFAULT_STEP_HEARTBEAT_MS;
+    const timer = every > 0
+        ? setInterval(() => {
+            if (spoke) {
+                spoke = false;
+                return;
+            }
+            write(`${prefix}: still running after ${Math.round((Date.now() - started) / 1000)}s`);
+        }, every)
+        : undefined;
+    timer?.unref();
+    try {
+        return await store.run(sink, fn);
+    }
+    finally {
+        if (timer)
+            clearInterval(timer);
+    }
+}
+/** Whether the calling activity runs under a step console, so its output is printed as it arrives. */
+export function hasStepConsole() {
+    return store.getStore() !== undefined;
+}
+/** Print one line of the calling step's output. A no-op outside a step console. */
+export function stepOutputLine(text) {
+    store.getStore()?.line(text);
+}
+/**
+ * A sink for a stream's chunks that prints whole lines to the calling step's
+ * console as they complete; `end()` prints what is left. The console is the
+ * one current when the splitter is made, since a stream's `data` events need
+ * not run in the step's async context.
+ */
+export function stepLineSplitter() {
+    const sink = store.getStore();
+    let pending = "";
+    const emit = (line) => sink?.line(line.endsWith("\r") ? line.slice(0, -1) : line);
+    return {
+        push(chunk) {
+            pending += typeof chunk === "string" ? chunk : chunk.toString("utf8");
+            let at = pending.indexOf("\n");
+            while (at >= 0) {
+                emit(pending.slice(0, at));
+                pending = pending.slice(at + 1);
+                at = pending.indexOf("\n");
+            }
+        },
+        end() {
+            if (pending !== "")
+                emit(pending);
+            pending = "";
+        },
+    };
+}
+/**
+ * The heartbeat interval `CHANT_STEP_HEARTBEAT` sets, or the default. `0` and
+ * `off` turn it off. A value that is not a duration falls back to the default
+ * and says so through `warn`.
+ */
+export function stepHeartbeatMs(env = process.env, warn) {
+    const raw = env[STEP_HEARTBEAT_ENV]?.trim();
+    if (!raw)
+        return DEFAULT_STEP_HEARTBEAT_MS;
+    if (raw === "0" || raw.toLowerCase() === "off")
+        return 0;
+    try {
+        return parseDuration(raw);
+    }
+    catch {
+        warn?.(`${STEP_HEARTBEAT_ENV}="${raw}" is not a duration (such as 30s or 5m) or off; using ${DEFAULT_STEP_HEARTBEAT_MS / 1000}s`);
+        return DEFAULT_STEP_HEARTBEAT_MS;
+    }
+}

package/dist/point-decision.d.ts.map

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

package/dist/point-decision.js

@@ -33,6 +33,7 @@ import { samePlanDigest } from "./lifecycle/plan-digest.js";
 import { parseDuration } from "./op/duration.js";
 import { DEFAULT_GATE_POINT_PASS, defaultGatePointStore, gatePointInputs, gateSubject } from "./op/gate-point.js";
 import { resolveGateRunLocator } from "./op/gate-run-locator.js";
+import { refuseGateWithoutRecording } from "./lifecycle/no-record.js";
 export { DEFAULT_GATE_POINT_PASS, GATE_POINT_INPUTS, defaultGatePointStore, gatePointInputs, gatePointOf, gatePointProblems, gateSubject, parseGateSubject, } from "./op/gate-point.js";
 export { isGateRunLocator, resolveGateRunLocator } from "./op/gate-run-locator.js";
 /** Who a resolution written for an answer is by: the people who answered, or the decider that did. */
@@ -41,6 +42,8 @@ function resolvedByOf(q) {
 }
 /** Decide a gate that asks a point: ask it, then record the pending fact or the resolution that cites the answer. */
 export async function evaluatePointGate(port, asker, input) {
+    // #3955: refused before the point is asked, which would itself write to the ledger.
+    refuseGateWithoutRecording(input.op, input.gate);
     const now = input.now ?? new Date().toISOString();
     const facts = { component: input.op, name: input.gate, env: input.env ?? null, planDigest: input.planDigest ?? null };
     const q = await asker.ask({ point: input.point.name, inputs: input.inputs ?? {}, facts, subject: gateSubject(input.op, input.gate, input.env), ...(input.point.store ? { store: input.point.store } : {}) });