@cotal-ai/runtime 0.48.2 → 0.50.0

package/dist/host-starvation.d.ts

@@ -0,0 +1,183 @@
+/**
+ * The host's two clocks, as ONE injectable object.
+ *
+ * Deliberately a single source rather than two independent `now`/`wall` parameters. With two, a
+ * suite could step the wall while handing the window a clock that by construction never moved, so
+ * the clock-step cells passed just as happily against the very wall-clock window they were written
+ * to refuse. Measured on this tree: with `now` and `wall` separate, forcing the window back onto
+ * `Date.now()` left all 41 cells GREEN. One clock means a test steps THE HOST, and which member the
+ * window reads becomes the implementation's own choice, which a cell can therefore grade.
+ */
+export interface HostClock {
+    /**
+     * Never steps, counts only forward at its own rate, origin arbitrary. Every window is measured
+     * on this. Not `Date.now()`, and that is the whole correction above: a wall clock states what
+     * time it IS, which an operator or NTP daemon may revise at any moment, while this file asks how
+     * much time PASSED and whether this process got to run during it.
+     */
+    monotonic(): number;
+    /** Wall time. Steps under NTP, operator edits, VM resume. Reported in the window, never measured on. */
+    wall(): number;
+}
+/** The real host. */
+export declare const systemClock: HostClock;
+/** How often the observer checks in. Short enough that a window of a few seconds carries enough
+ *  ticks for a shortfall to mean something, long enough that the observer is not itself load. */
+export declare const LOOP_TICK_MS = 250;
+/** A point in the observer's history. Windows are differences between two of these. */
+export interface LoopLagMark {
+    /** Monotonic. The window's length is a difference of these, never of wall readings. */
+    readonly at: number;
+    /** The WALL reading at the same instant, carried only so a step can be NOTICED. */
+    readonly wallAt: number;
+    readonly lagMs: number;
+    readonly ticks: number;
+}
+/** What the loop did across one window. */
+export interface LoopLagWindow {
+    /** Wall time the window covers. */
+    readonly elapsedMs: number;
+    /** Total lateness the observer's ticks accumulated inside it. */
+    readonly lagMs: number;
+    /** Ticks the window was long enough to contain. */
+    readonly ticksExpected: number;
+    /** Ticks that actually ran. */
+    readonly ticksObserved: number;
+    /**
+     * How far the WALL clock disagreed with the monotonic window across this interval.
+     *
+     * Reported rather than acted on, and that is the point: the verdict does not depend on it, so a
+     * step cannot change the answer. It exists so an operator reading a starvation notice under a
+     * simultaneous NTP correction can see that both happened, and so the suite can assert that the
+     * step occurred and the window did NOT move with it.
+     */
+    readonly wallSkewMs: number;
+}
+export interface LoopLagObserver {
+    /** Take a point to measure from. */
+    mark(): LoopLagMark;
+    /** What the loop did between `mark` and now. */
+    since(mark: LoopLagMark): LoopLagWindow;
+}
+/** An observer for a test to drive. Pass a `clock` whose `monotonic` STEPS and you are grading
+ *  exactly the failure mode the real `systemClock` exists to remove. */
+export declare function loopLagObserver(tickMs?: number, clock?: HostClock): LoopLagObserver & {
+    stop(): void;
+};
+export declare function loopLag(): LoopLagObserver;
+/** Lag under this is never starvation, whatever share of the window it is: a 40ms window in which
+ *  the loop was 12ms late is a loop that is running. */
+export declare const STARVED_FLOOR_MS = 1000;
+/** And it must be a real share of the window. `4` = a quarter. A read that took a minute and lost
+ *  two seconds to lag was served by a loop that was running for 58 of them. */
+export declare const STARVED_SHARE_DIVISOR = 4;
+/** And the ticks must actually be missing. `2` = the loop kept at least half of them. A window that
+ *  reports large lag while losing no ticks is a clock that moved, not a loop that stopped. */
+export declare const STARVED_TICK_KEPT_DIVISOR = 2;
+/**
+ * Is this failure the SHAPE a client-side deadline produces?
+ *
+ * Read off the error's CLASS, never its message. The NATS client's timeout carries the bare text
+ * `timeout`, and so do several unrelated failures in this tree and in other people's, so matching the
+ * word would classify a broker's refusal as starvation the moment somebody phrased one that way.
+ *
+ * Two accepting branches, because the client raises the deadline in two shapes: on its own for a
+ * plain API call, and wrapped in a `RequestError` when the deadline ends a request. Each has a
+ * refusing cell that differs from it only in the class involved.
+ */
+export declare function isDeadlineShaped(error: unknown): boolean;
+/** Was this process demonstrably not scheduled across the window? */
+export declare function wasStarved(w: LoopLagWindow): boolean;
+/**
+ * What a failed pause-plane operation actually was.
+ *
+ * `fault` is TODAY'S ANSWER AND IT IS UNCHANGED: the caller raises, the interpreter records
+ * `L4000`, and a genuine broken host or handler reads exactly as it did before this file existed.
+ * The two things that move are the cases where the error is DEADLINE-SHAPED, which was never
+ * evidence about the plane's health at all, only about a reply that did not arrive in time:
+ *
+ *   - `starved`, when this process can show its own loop was not running (#1508). The deadline
+ *     could not fire because nothing could.
+ *   - `transient`, when the loop WAS running (#1619). The deadline fired honestly and the reply
+ *     was merely late, which is a property of one request and not of the pause behind it.
+ */
+export type PauseCondition = {
+    readonly condition: "starved";
+    readonly window: LoopLagWindow;
+} | {
+    readonly condition: "transient";
+    readonly window: LoopLagWindow;
+} | {
+    readonly condition: "fault";
+};
+export declare function classifyPauseFailure(error: unknown, window: LoopLagWindow): PauseCondition;
+/**
+ * How many CONSECUTIVE starved attempts a pause operation gets before the host is declared unable
+ * to serve it.
+ *
+ * A BOUND IS MANDATORY and it is the reason this is a count rather than "retry until served": a
+ * caller that genuinely cannot be served must fail, not hang, and an unbounded retry on a host that
+ * never recovers is a run that is neither alive nor dead. Each attempt costs at least the client's
+ * own deadline before it can fail again, so the count is a real wall-clock bound and not a spin.
+ */
+export declare const STARVED_ATTEMPTS = 6;
+/**
+ * A macrotask yield between starved attempts.
+ *
+ * NOT A WIDENED DEADLINE, and the difference is the whole point of this file: the deadline is
+ * unchanged, and this is a pause between re-entries of an operation that already elapsed one. It
+ * earns its place twice. A retry that re-enters synchronously occupies the very loop whose absence
+ * it is reacting to, so it would spin at full CPU during exactly the window the host needs back;
+ * and a starved loop cannot run a timer either, so waiting on one is itself a small measurement of
+ * whether scheduling has returned.
+ */
+export declare const STARVED_YIELD_MS = 250;
+/**
+ * How many CONSECUTIVE late replies a pause operation gets before the plane is declared unable to
+ * answer it (#1619).
+ *
+ * COUNTED SEPARATELY from {@link STARVED_ATTEMPTS}, and not merged with it, because the two are
+ * different diagnoses with different remedies and an operator acts on which one they got: one says
+ * give this host capacity, the other says the broker is not answering. Counting them apart also
+ * keeps the whole call bounded no matter how the two interleave — neither counter is ever reset, so
+ * an alternating sequence cannot retry forever between them.
+ */
+export declare const POLL_ATTEMPTS = 6;
+/**
+ * The first wait between late replies, DOUBLED each time and capped at {@link POLL_BACKOFF_MAX_MS}.
+ *
+ * Backoff rather than the flat yield starvation uses, because the two are waiting for different
+ * things to recover. A starved loop needs the CPU back, which the next macrotask already measures;
+ * a plane answering late is usually a broker under momentary load, and re-issuing at the same
+ * cadence adds to exactly the queue that is already behind. Each attempt additionally costs the
+ * client's own deadline before it can fail again, so the bound is real wall-clock time either way.
+ */
+export declare const POLL_BACKOFF_MS = 250;
+export declare const POLL_BACKOFF_MAX_MS = 2000;
+/**
+ * Perform a pause-plane operation, and do not let this host's own starvation, or one late reply
+ * from the plane, be recorded as the effect's failure.
+ *
+ * THE OPERATION MUST BE IDEMPOTENT, which the pause plane's are by construction: `arm` mints
+ * idempotently-if-identical and otherwise attaches, and `settle` reads a one-use fact that is
+ * either there or not. Re-entering either after a starved or unanswered attempt observes the same
+ * world.
+ *
+ * A SLEEP PROMISES AT-LEAST, NOT AT-MOST, so a starved one COMPLETES LATE rather than failing: the
+ * broker armed a real timer, it fired while this process was off the CPU, and the fact is waiting
+ * to be read. Retrying reads it and the step settles `ok`. That is the whole repair for the
+ * incident in #1508, the run in it would have completed.
+ *
+ * AND A PARKED STEP IS NOT ITS POLLS (#1619). While a pause is parked this host issues roughly one
+ * 5s plane read per second for the step's whole duration, so the chance that ONE of them gets a
+ * late reply grows with how long the step waits — measured, the asks over 7.5 minutes died and the
+ * ones under 4.5 did not. A late reply says nothing about the pause, which is durable on the plane
+ * and still answerable, so it is re-read rather than raised.
+ *
+ * WHAT IS NOT SWALLOWED: a failure that is not deadline-shaped is raised on the FIRST attempt with
+ * no retry and no inspection of the loop, keeping `L4000` and its message exactly as they are
+ * today. And neither retry is unbounded: each condition carries its own count, and exhausting
+ * either fails under a code that names what was measured.
+ */
+export declare function servedDespiteStarvation<T>(operation: () => Promise<T>, lag: LoopLagObserver, what: string, onStarved?: (note: string) => void): Promise<T>;
+//# sourceMappingURL=host-starvation.d.ts.map

package/dist/host-starvation.d.ts.map

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

package/dist/host-starvation.js

@@ -0,0 +1,329 @@
+/**
+ * Did this process get scheduled? The evidence a starved host can obtain about itself, and what
+ * follows from it.
+ *
+ * THE DEFECT THIS EXISTS FOR (#1508). A `sleep` reads the pause plane while it waits. Every one of
+ * those reads rides a NATS API request with a 5s client-side deadline, and that deadline is a
+ * `setTimeout`. When the host is loaded hard enough that this process does not return to its event
+ * loop for longer than the deadline, the deadline's own timer cannot fire either, so it fires the
+ * instant the loop frees, rejects with the client's bare `timeout`, and does so even though the
+ * broker answered long ago and the reply is sitting in the socket buffer. The interpreter flattens
+ * that into `{ code: "L4000", kind: "handler-fault" }`, and the run dies with a record naming the
+ * effect as the thing that broke. Measured on this tree before the repair: the identical read
+ * returned in 1ms on a healthy loop and rejected `TimeoutError: timeout` after 9001ms with the loop
+ * blocked, with the broker healthy immediately before and immediately after.
+ *
+ * A WALL-CLOCK DEADLINE CANNOT TELL THE TWO APART, which is the whole reason this file is not a
+ * larger timeout. "The timer did not fire" and "this process was never scheduled" produce the
+ * identical observation, an elapsed deadline with no answer, so widening the deadline only moves
+ * the load at which the misattribution happens. The distinction has to come from a DIFFERENT
+ * measurement, and there is one the process can take about itself: whether its own event loop ran.
+ *
+ * TWO INDEPENDENT SIGNALS, and the independence is structural rather than hopeful:
+ *
+ *   - LAG: a repeating tick records how late it was against the instant it was scheduled for. A
+ *     loop that is running answers within a few ms; a loop that is blocked answers with the whole
+ *     block.
+ *   - TICK SHORTFALL: how many ticks the window should have contained against how many it did. A
+ *     blocked loop loses ticks outright.
+ *
+ * Lag alone would be fooled by a clock that steps forward, which inflates every interval measured
+ * against it while the loop was in fact running fine and losing no ticks. The shortfall is what
+ * refuses that case, and it can only refuse it if the two are measured against DIFFERENT clocks.
+ *
+ * SO THE WINDOW IS MONOTONIC, and this is the correction a reviewer measured rather than argued.
+ * An earlier draft derived `ticksExpected` from `Date.now()`, the same reading that inflates the
+ * lag, so a forward step inflated BOTH while `ticksObserved` could not follow and a perfectly
+ * healthy loop read as starved. Measured on this tree before the repair, loop healthy throughout:
+ * a +10s step over a 1.2s window gave `{elapsed 11201, lag 10003, expected 44, observed 4}` and
+ * classified `starved`, and +60s gave `{elapsed 61201, lag 60000, expected 244, observed 4}`. Worse
+ * in the direction that matters here, a BACKWARD step during a genuine 3s block gave
+ * `{elapsed 0, lag 0, expected 0, observed 1}` and classified `fault`, which is #1508's own
+ * misattribution returning under an NTP correction. Both are gone once the window is measured on a
+ * clock that only moves forward at its own rate.
+ */
+import { EffectError } from "@cotal-ai/lang";
+/** The real host. */
+export const systemClock = {
+    monotonic: () => performance.now(),
+    wall: () => Date.now(),
+};
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+// The measurement
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+/** How often the observer checks in. Short enough that a window of a few seconds carries enough
+ *  ticks for a shortfall to mean something, long enough that the observer is not itself load. */
+export const LOOP_TICK_MS = 250;
+/**
+ * The observer, as a self-rescheduling unrefed tick.
+ *
+ * UNREFED, because an observer is not a reason for a process to stay alive: a run that has finished
+ * must exit, and a refed 250ms timer would hold it open forever. RESCHEDULED FROM INSIDE THE TICK
+ * rather than as an interval, because `setInterval` under a blocked loop coalesces its missed fires
+ * into one and the count of what DID run stops being readable, and the count is half the evidence.
+ */
+class TickLoopLag {
+    tickMs;
+    clock;
+    lagMs = 0;
+    ticks = 0;
+    timer;
+    constructor(tickMs = LOOP_TICK_MS, 
+    /** The host's clock. One object, so a suite steps the HOST and not one chosen reading. */
+    clock = systemClock) {
+        this.tickMs = tickMs;
+        this.clock = clock;
+    }
+    start() {
+        if (this.timer === undefined)
+            this.schedule();
+        return this;
+    }
+    /** Stop observing. Only the tests need this; the process observer runs for the process. */
+    stop() {
+        if (this.timer !== undefined)
+            clearTimeout(this.timer);
+        this.timer = undefined;
+    }
+    /**
+     * The reading a TICK measures itself against, as its own named function.
+     *
+     * Extracted so the wall-clock regression has a single code-only line to be restored on. It was
+     * previously reachable only by rewriting `due` and `late` together, which spans the comment
+     * between them, and this repo refuses a mutation anchor that includes prose, correctly, since a
+     * later tidy of that comment would silently disarm the mutation and nothing would go red.
+     */
+    tickNow() {
+        return this.clock.monotonic();
+    }
+    schedule() {
+        const due = this.tickNow() + this.tickMs;
+        const timer = setTimeout(() => {
+            // Lateness against the instant this tick was SCHEDULED for, not against the previous tick:
+            // measuring tick-to-tick would report a healthy loop's own jitter as lag and would miss a
+            // block that straddled exactly one tick.
+            const late = this.tickNow() - due;
+            if (late > 0)
+                this.lagMs += late;
+            this.ticks += 1;
+            this.schedule();
+        }, this.tickMs);
+        // `unref` is present on Node's timer and absent on the DOM's; the host here is Node, and the
+        // optional call keeps this file loadable under a bundler that types it the other way.
+        timer.unref?.();
+        this.timer = timer;
+    }
+    mark() {
+        return {
+            at: this.clock.monotonic(),
+            wallAt: this.clock.wall(),
+            lagMs: this.lagMs,
+            ticks: this.ticks,
+        };
+    }
+    since(mark) {
+        const elapsedMs = Math.max(0, this.clock.monotonic() - mark.at);
+        return {
+            elapsedMs,
+            lagMs: Math.max(0, this.lagMs - mark.lagMs),
+            ticksExpected: Math.floor(elapsedMs / this.tickMs),
+            ticksObserved: Math.max(0, this.ticks - mark.ticks),
+            // Signed, and NOT clamped: a backward step is as much a fact as a forward one, and the
+            // operator reading the notice wants to know which way it went.
+            wallSkewMs: (this.clock.wall() - mark.wallAt) - elapsedMs,
+        };
+    }
+}
+/** An observer for a test to drive. Pass a `clock` whose `monotonic` STEPS and you are grading
+ *  exactly the failure mode the real `systemClock` exists to remove. */
+export function loopLagObserver(tickMs = LOOP_TICK_MS, clock = systemClock) {
+    return new TickLoopLag(tickMs, clock).start();
+}
+/**
+ * The process's observer.
+ *
+ * ONE PER PROCESS, because event-loop lag is a property of the process and not of a run, a handler
+ * or a pause: two observers would measure the same loop twice and cost two timers to do it. Started
+ * on first use so a build that never performs an effect never arms it.
+ */
+let processObserver;
+export function loopLag() {
+    processObserver ??= new TickLoopLag().start();
+    return processObserver;
+}
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+// The classification
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+/** Lag under this is never starvation, whatever share of the window it is: a 40ms window in which
+ *  the loop was 12ms late is a loop that is running. */
+export const STARVED_FLOOR_MS = 1_000;
+/** And it must be a real share of the window. `4` = a quarter. A read that took a minute and lost
+ *  two seconds to lag was served by a loop that was running for 58 of them. */
+export const STARVED_SHARE_DIVISOR = 4;
+/** And the ticks must actually be missing. `2` = the loop kept at least half of them. A window that
+ *  reports large lag while losing no ticks is a clock that moved, not a loop that stopped. */
+export const STARVED_TICK_KEPT_DIVISOR = 2;
+const nameOf = (e) => {
+    const n = e?.name;
+    return typeof n === "string" ? n : undefined;
+};
+/**
+ * Is this failure the SHAPE a client-side deadline produces?
+ *
+ * Read off the error's CLASS, never its message. The NATS client's timeout carries the bare text
+ * `timeout`, and so do several unrelated failures in this tree and in other people's, so matching the
+ * word would classify a broker's refusal as starvation the moment somebody phrased one that way.
+ *
+ * Two accepting branches, because the client raises the deadline in two shapes: on its own for a
+ * plain API call, and wrapped in a `RequestError` when the deadline ends a request. Each has a
+ * refusing cell that differs from it only in the class involved.
+ */
+export function isDeadlineShaped(error) {
+    if (nameOf(error) === "TimeoutError")
+        return true;
+    if (nameOf(error) === "RequestError" && nameOf(error.cause) === "TimeoutError")
+        return true;
+    return false;
+}
+/** Was this process demonstrably not scheduled across the window? */
+export function wasStarved(w) {
+    if (w.lagMs < STARVED_FLOOR_MS)
+        return false;
+    if (w.lagMs * STARVED_SHARE_DIVISOR < w.elapsedMs)
+        return false;
+    // The second signal, and the one a clock jump cannot fake: a loop that ran is a loop whose ticks
+    // happened. `ticksExpected === 0` is a window too short to have contained one, which is no
+    // evidence of starvation and is refused here rather than read as a total shortfall.
+    if (w.ticksExpected === 0)
+        return false;
+    if (w.ticksObserved * STARVED_TICK_KEPT_DIVISOR >= w.ticksExpected)
+        return false;
+    return true;
+}
+export function classifyPauseFailure(error, window) {
+    if (!isDeadlineShaped(error))
+        return { condition: "fault" };
+    if (!wasStarved(window))
+        return { condition: "transient", window };
+    return { condition: "starved", window };
+}
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+// The policy
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+/**
+ * How many CONSECUTIVE starved attempts a pause operation gets before the host is declared unable
+ * to serve it.
+ *
+ * A BOUND IS MANDATORY and it is the reason this is a count rather than "retry until served": a
+ * caller that genuinely cannot be served must fail, not hang, and an unbounded retry on a host that
+ * never recovers is a run that is neither alive nor dead. Each attempt costs at least the client's
+ * own deadline before it can fail again, so the count is a real wall-clock bound and not a spin.
+ */
+export const STARVED_ATTEMPTS = 6;
+/**
+ * A macrotask yield between starved attempts.
+ *
+ * NOT A WIDENED DEADLINE, and the difference is the whole point of this file: the deadline is
+ * unchanged, and this is a pause between re-entries of an operation that already elapsed one. It
+ * earns its place twice. A retry that re-enters synchronously occupies the very loop whose absence
+ * it is reacting to, so it would spin at full CPU during exactly the window the host needs back;
+ * and a starved loop cannot run a timer either, so waiting on one is itself a small measurement of
+ * whether scheduling has returned.
+ */
+export const STARVED_YIELD_MS = 250;
+/**
+ * How many CONSECUTIVE late replies a pause operation gets before the plane is declared unable to
+ * answer it (#1619).
+ *
+ * COUNTED SEPARATELY from {@link STARVED_ATTEMPTS}, and not merged with it, because the two are
+ * different diagnoses with different remedies and an operator acts on which one they got: one says
+ * give this host capacity, the other says the broker is not answering. Counting them apart also
+ * keeps the whole call bounded no matter how the two interleave — neither counter is ever reset, so
+ * an alternating sequence cannot retry forever between them.
+ */
+export const POLL_ATTEMPTS = 6;
+/**
+ * The first wait between late replies, DOUBLED each time and capped at {@link POLL_BACKOFF_MAX_MS}.
+ *
+ * Backoff rather than the flat yield starvation uses, because the two are waiting for different
+ * things to recover. A starved loop needs the CPU back, which the next macrotask already measures;
+ * a plane answering late is usually a broker under momentary load, and re-issuing at the same
+ * cadence adds to exactly the queue that is already behind. Each attempt additionally costs the
+ * client's own deadline before it can fail again, so the bound is real wall-clock time either way.
+ */
+export const POLL_BACKOFF_MS = 250;
+export const POLL_BACKOFF_MAX_MS = 2_000;
+/**
+ * Perform a pause-plane operation, and do not let this host's own starvation, or one late reply
+ * from the plane, be recorded as the effect's failure.
+ *
+ * THE OPERATION MUST BE IDEMPOTENT, which the pause plane's are by construction: `arm` mints
+ * idempotently-if-identical and otherwise attaches, and `settle` reads a one-use fact that is
+ * either there or not. Re-entering either after a starved or unanswered attempt observes the same
+ * world.
+ *
+ * A SLEEP PROMISES AT-LEAST, NOT AT-MOST, so a starved one COMPLETES LATE rather than failing: the
+ * broker armed a real timer, it fired while this process was off the CPU, and the fact is waiting
+ * to be read. Retrying reads it and the step settles `ok`. That is the whole repair for the
+ * incident in #1508, the run in it would have completed.
+ *
+ * AND A PARKED STEP IS NOT ITS POLLS (#1619). While a pause is parked this host issues roughly one
+ * 5s plane read per second for the step's whole duration, so the chance that ONE of them gets a
+ * late reply grows with how long the step waits — measured, the asks over 7.5 minutes died and the
+ * ones under 4.5 did not. A late reply says nothing about the pause, which is durable on the plane
+ * and still answerable, so it is re-read rather than raised.
+ *
+ * WHAT IS NOT SWALLOWED: a failure that is not deadline-shaped is raised on the FIRST attempt with
+ * no retry and no inspection of the loop, keeping `L4000` and its message exactly as they are
+ * today. And neither retry is unbounded: each condition carries its own count, and exhausting
+ * either fails under a code that names what was measured.
+ */
+export async function servedDespiteStarvation(operation, lag, what, onStarved = (note) => console.error(note)) {
+    let last;
+    let starved = 0;
+    let unanswered = 0;
+    for (let attempt = 1;; attempt += 1) {
+        const mark = lag.mark();
+        try {
+            return await operation();
+        }
+        catch (error) {
+            const verdict = classifyPauseFailure(error, lag.since(mark));
+            // The genuine fault: out by the same door it used before this wrapper existed, carrying its
+            // own error, so the journal records what it always recorded.
+            if (verdict.condition === "fault")
+                throw error;
+            last = verdict.window;
+            const evidence = describe(last);
+            if (verdict.condition === "transient") {
+                unanswered += 1;
+                if (unanswered >= POLL_ATTEMPTS) {
+                    throw new EffectError("L4026", "pause-unanswered", `${what} could not be served: the pause plane did not answer ${unanswered} consecutive reads before their client deadline, while this host's own event loop was running (${evidence}). `
+                        + `The pause and its timer are intact on the plane and nothing about the program or the resource it waits on is at fault; `
+                        + `the run can be resumed once the broker is answering.`, { attempts: unanswered, lagMs: last.lagMs, elapsedMs: last.elapsedMs, ticksExpected: last.ticksExpected, ticksObserved: last.ticksObserved });
+                }
+                // SAID OUT LOUD, for the same reason the starved notice is: a run that is merely taking a
+                // while looks identical to one whose plane reads keep timing out, and the operator is the
+                // person who can act on the difference.
+                onStarved(`${what}: attempt ${attempt} reached its client deadline while this host WAS scheduling the run's process (${evidence}); the plane's reply was late, retrying rather than failing the step`);
+                // Unrefed, as below: a retry loop is not a reason for a finished process to stay alive.
+                await new Promise((r) => setTimeout(r, Math.min(POLL_BACKOFF_MS * 2 ** (unanswered - 1), POLL_BACKOFF_MAX_MS)).unref?.());
+                continue;
+            }
+            starved += 1;
+            if (starved >= STARVED_ATTEMPTS) {
+                throw new EffectError("L4025", "host-starved", `${what} could not be served: this host did not schedule the run's process across ${starved} consecutive attempts (${evidence}). `
+                    + `The pause and its timer are intact on the plane and nothing about the program or the resource it waits on is at fault; `
+                    + `the run can be resumed once the host has capacity.`, { attempts: starved, lagMs: last.lagMs, elapsedMs: last.elapsedMs, ticksExpected: last.ticksExpected, ticksObserved: last.ticksObserved });
+            }
+            // SAID OUT LOUD, once per starved attempt. The operator reading a slow run is the person who
+            // can act on this, and "the host is overloaded" is not deducible from a run that is merely
+            // taking a while.
+            onStarved(`${what}: attempt ${attempt} reached its client deadline while this host was not scheduling the run's process (${evidence}); retrying rather than failing the step`);
+            // Unrefed: a retry loop is not a reason for a finished process to stay alive.
+            await new Promise((r) => setTimeout(r, STARVED_YIELD_MS).unref?.());
+        }
+    }
+}
+const describe = (w) => `event-loop lag ${Math.round(w.lagMs)}ms of a ${Math.round(w.elapsedMs)}ms window, ${w.ticksObserved} of ${w.ticksExpected} scheduled ticks observed`;
+//# sourceMappingURL=host-starvation.js.map

package/dist/host-starvation.js.map

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

package/dist/index.d.ts

@@ -10,11 +10,11 @@
  */
 export { RunJournalStore, RunJournalUnavailable } from "./journal-store.js";
 export { startRun, driveRun, PauseToken, type RunLease, type DriveRequest, type DriveOutcome, type AdoptingHandler, type SeatAdoptingHandler } from "./run-driver.js";
-export { MeshHandler, EpfSettleWatcher, CheckpointAnswerMissing, waitConsumerName, waitConsumerConfig, rearmOutstandingPauses, outstandingPauseTokens, readSupervise, spawnArgs, type MeshHandlerBinding, type SettleWatcher, } from "./mesh-handler.js";
+export { MeshHandler, EpfSettleWatcher, CheckpointAnswerMissing, waitConsumerName, waitConsumerConfig, rearmOutstandingPauses, outstandingPauseTokens, readSupervise, spawnArgs, canonicalCwd, type MeshHandlerBinding, type SettleWatcher, } from "./mesh-handler.js";
 export { resolveCheckpoint, locateOpenCheckpoint, answerOpenCheckpoint, openCheckpointToken, CheckpointNotOpen, type OpenCheckpoint, type ResolveCheckpointDeps, type ResolveCheckpointRequest, type ResolveCheckpointResult, } from "./resolve-checkpoint.js";
 export { renderRunContext, UnrenderableNotice, type RunContextRender } from "./run-context.js";
 export { migrateRun, commitMigration, migrationSeats, MigrationNotAdmissible, type MigrateRequest, type MigrateReport, type MigrateOrphan, type MigrateOverrides, type MigrateDivergence, type OrphanVerdict, } from "./migrate.js";
 export { planFork, commitFork, ForkNotAdmissible, CutJournal, CutReached, type ForkRequest, type ForkPlan, type ForkRefusal, type ForkCommitResult, } from "./fork.js";
 export { runWorkflow } from "./run-command.js";
-export { cotalLangRunHost } from "./run-host.js";
+export { cotalLangRunHost, journalOutcomeOf } from "./run-host.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAC5E,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,UAAU,EAAE,KAAK,QAAQ,EAAE,KAAK,YAAY,EAAE,KAAK,YAAY,EAAE,KAAK,eAAe,EAAE,KAAK,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtK,OAAO,EACL,WAAW,EACX,gBAAgB,EAChB,uBAAuB,EACvB,gBAAgB,EAChB,kBAAkB,EAClB,sBAAsB,EACtB,sBAAsB,EACtB,aAAa,EACb,SAAS,EACT,KAAK,kBAAkB,EACvB,KAAK,aAAa,GACnB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,iBAAiB,EACjB,oBAAoB,EACpB,oBAAoB,EACpB,mBAAmB,EACnB,iBAAiB,EACjB,KAAK,cAAc,EACnB,KAAK,qBAAqB,EAC1B,KAAK,wBAAwB,EAC7B,KAAK,uBAAuB,GAC7B,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAC/F,OAAO,EACL,UAAU,EACV,eAAe,EACf,cAAc,EACd,sBAAsB,EACtB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,aAAa,GACnB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,QAAQ,EACR,UAAU,EACV,iBAAiB,EACjB,UAAU,EACV,UAAU,EACV,KAAK,WAAW,EAChB,KAAK,QAAQ,EACb,KAAK,WAAW,EAChB,KAAK,gBAAgB,GACtB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAC5E,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,UAAU,EAAE,KAAK,QAAQ,EAAE,KAAK,YAAY,EAAE,KAAK,YAAY,EAAE,KAAK,eAAe,EAAE,KAAK,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtK,OAAO,EACL,WAAW,EACX,gBAAgB,EAChB,uBAAuB,EACvB,gBAAgB,EAChB,kBAAkB,EAClB,sBAAsB,EACtB,sBAAsB,EACtB,aAAa,EACb,SAAS,EACT,YAAY,EACZ,KAAK,kBAAkB,EACvB,KAAK,aAAa,GACnB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,iBAAiB,EACjB,oBAAoB,EACpB,oBAAoB,EACpB,mBAAmB,EACnB,iBAAiB,EACjB,KAAK,cAAc,EACnB,KAAK,qBAAqB,EAC1B,KAAK,wBAAwB,EAC7B,KAAK,uBAAuB,GAC7B,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAC/F,OAAO,EACL,UAAU,EACV,eAAe,EACf,cAAc,EACd,sBAAsB,EACtB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACtB,KAAK,aAAa,GACnB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,QAAQ,EACR,UAAU,EACV,iBAAiB,EACjB,UAAU,EACV,UAAU,EACV,KAAK,WAAW,EAChB,KAAK,QAAQ,EACb,KAAK,WAAW,EAChB,KAAK,gBAAgB,GACtB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -10,13 +10,13 @@
  */
 export { RunJournalStore, RunJournalUnavailable } from "./journal-store.js";
 export { startRun, driveRun, PauseToken } from "./run-driver.js";
-export { MeshHandler, EpfSettleWatcher, CheckpointAnswerMissing, waitConsumerName, waitConsumerConfig, rearmOutstandingPauses, outstandingPauseTokens, readSupervise, spawnArgs, } from "./mesh-handler.js";
+export { MeshHandler, EpfSettleWatcher, CheckpointAnswerMissing, waitConsumerName, waitConsumerConfig, rearmOutstandingPauses, outstandingPauseTokens, readSupervise, spawnArgs, canonicalCwd, } from "./mesh-handler.js";
 export { resolveCheckpoint, locateOpenCheckpoint, answerOpenCheckpoint, openCheckpointToken, CheckpointNotOpen, } from "./resolve-checkpoint.js";
 export { renderRunContext, UnrenderableNotice } from "./run-context.js";
 export { migrateRun, commitMigration, migrationSeats, MigrationNotAdmissible, } from "./migrate.js";
 export { planFork, commitFork, ForkNotAdmissible, CutJournal, CutReached, } from "./fork.js";
 export { runWorkflow } from "./run-command.js";
-export { cotalLangRunHost } from "./run-host.js";
+export { cotalLangRunHost, journalOutcomeOf } from "./run-host.js";
 // Self-register `cotal run` — the workflow-run operator surface — and the `run-host` the manager
 // drives runs through (SPEC 14.3). Importing this package from a composition root (bin/run.ts) is
 // what puts the command on the CLI and the host in the manager's reach; library users who import
@@ -31,19 +31,22 @@ const runCommand = {
     kind: "command",
     name: "run",
     group: "Manager",
-    summary: "operate workflow runs — start, resume, list, inspect, answer (hosted by the manager)",
-    usage: "run <start --file <program> [--timeout <dur>] | resume <runId> [--local --file <program>] | ps [--endpoint <ep>] | journal <runId> [--endpoint <ep>] | answer <runId> <stepKey> [--value <json>] [--artifact <ref>] [--endpoint <ep>] [--local --by <who>]> [--local]",
+    summary: "operate workflow runs — start, resume, list, inspect, answer (hosted by the manager), revoke",
+    usage: "run <start --file <program> [--timeout <dur>] | resume <runId> [--local --file <program>] | ps [--endpoint <ep>] | journal <runId> [--endpoint <ep>] | answer <runId> <stepKey> [--value <json>] [--artifact <ref>] [--endpoint <ep>] [--local --by <who>] | revoke <runId> --local --by <who> --reason <text>> [--local [--admit-read <channels> --admit-publish <channels>]]",
     flags: [
         ...targetFlags,
         { name: "file", type: "string", short: "f", value: "<program>", description: "cotal-lang program source (start; resume --local when no program is recorded)" },
         { name: "local", type: "boolean", description: "drive in this process instead of on the manager (bare broker, or a run the manager cannot host)" },
+        { name: "admit-read", type: "string", value: "<channels>", description: "start --local: the channels the run may read, comma-separated patterns or `none` (required; SPEC 14.8)" },
+        { name: "admit-publish", type: "string", value: "<channels>", description: "start --local: the channels the run may post to, comma-separated patterns or `none` (required; SPEC 14.8)" },
         { name: "endpoint", type: "string", value: "<ep>", description: "endpoint the run record lives under (ps, journal, answer; default: manager)" },
         { name: "timeout", type: "string", value: "<dur>", description: "default checkpoint timeout for this drive (default: 1h)" },
-        { name: "by", type: "string", value: "<who>", description: "who is answering (answer --local only; the manager records the caller)" },
+        { name: "by", type: "string", value: "<who>", description: "who is answering or revoking (answer --local, revoke; the manager records the caller for a hosted answer)" },
+        { name: "reason", type: "string", value: "<text>", description: "revoke: why the run's admission is revoked, recorded on the marker (required)" },
         { name: "value", type: "string", value: "<json>", description: "checkpoint answer payload as JSON (answer)" },
         { name: "artifact", type: "string", value: "<ref>", description: "artifact reference attached to the answer (answer)" },
     ],
-    positionals: "<start|resume|ps|journal|answer> …",
+    positionals: "<start|resume|ps|journal|answer|revoke> …",
     run: (args) => runWorkflowCommand(args),
 };
 registry.register(runCommand);

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAC5E,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,UAAU,EAAuG,MAAM,iBAAiB,CAAC;AACtK,OAAO,EACL,WAAW,EACX,gBAAgB,EAChB,uBAAuB,EACvB,gBAAgB,EAChB,kBAAkB,EAClB,sBAAsB,EACtB,sBAAsB,EACtB,aAAa,EACb,SAAS,GAGV,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,iBAAiB,EACjB,oBAAoB,EACpB,oBAAoB,EACpB,mBAAmB,EACnB,iBAAiB,GAKlB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAyB,MAAM,kBAAkB,CAAC;AAC/F,OAAO,EACL,UAAU,EACV,eAAe,EACf,cAAc,EACd,sBAAsB,GAOvB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,QAAQ,EACR,UAAU,EACV,iBAAiB,EACjB,UAAU,EACV,UAAU,GAKX,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEjD,iGAAiG;AACjG,kGAAkG;AAClG,iGAAiG;AACjG,gGAAgG;AAChG,iBAAiB;AACjB,OAAO,EAAE,QAAQ,EAAgB,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,EAAE,WAAW,IAAI,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACrE,OAAO,EAAE,gBAAgB,IAAI,OAAO,EAAE,MAAM,eAAe,CAAC;AAE5D,QAAQ,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;AAE3B,MAAM,UAAU,GAAY;IAC1B,IAAI,EAAE,SAAS;IACf,IAAI,EAAE,KAAK;IACX,KAAK,EAAE,SAAS;IAChB,OAAO,EAAE,sFAAsF;IAC/F,KAAK,EACH,uQAAuQ;IACzQ,KAAK,EAAE;QACL,GAAG,WAAW;QACd,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,+EAA+E,EAAE;QAC9J,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,iGAAiG,EAAE;QAClJ,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,6EAA6E,EAAE;QAC/I,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,yDAAyD,EAAE;QAC3H,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,wEAAwE,EAAE;QACrI,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,4CAA4C,EAAE;QAC7G,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,oDAAoD,EAAE;KACxH;IACD,WAAW,EAAE,oCAAoC;IACjD,GAAG,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,kBAAkB,CAAC,IAAI,CAAC;CACxC,CAAC;AAEF,QAAQ,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}