@humwick/runner 0.0.0-stage → 0.130.0

package/node_modules/@humwick/offload/dist/types.js

@@ -0,0 +1,176 @@
+import { errMessage } from "@humwick/sdk";
+/** A stable, backend-independent failure surface for callers and escalation sinks. */
+export class OffloadError extends Error {
+    kind;
+    code;
+    taskName;
+    constructor(options) {
+        super(options.message ?? `${options.taskName} ${options.kind}`, { cause: options.cause });
+        this.name = "OffloadError";
+        this.kind = options.kind;
+        this.code = options.code;
+        this.taskName = options.taskName;
+    }
+}
+/**
+ * Sliding-window failure counter driving edge-triggered escalation (#1822 F1/F4, round-3
+ * redesign). A task escalates when it accumulates `threshold` failures within the last
+ * `window` failure-attempts (counted across all tasks); a failure older than the window no
+ * longer counts. This is attempt-based — no wall-clock, no timers — so it is deterministic and
+ * needs no time injection to test.
+ *
+ * WHY windowed rather than a size-capped consecutive counter: any hard *count* cap on a
+ * consecutive-strike map either scans the map per failure (O(cap); an earlier attempt blocked
+ * the event loop ~11s at 40k / ~31s at 100k distinct failures) or silently drops a task that is
+ * genuinely accumulating (a missed page — strictly worse than the leak it replaced). The window
+ * gives all four invariants at once: no lost escalation, no page storm, amortized O(1) per
+ * failure, and a hard memory bound.
+ *
+ * IMPLEMENTATION — the standard sliding-window multiset over a ring of failure events:
+ *  - `#ring[(clock-1) % window]` holds the failure event `window` attempts ago. Each new failure
+ *    overwrites exactly that slot, and the event it evicts is exactly the one aging out — so a
+ *    failure is pushed once and expired once: amortized O(1), never a scan.
+ *  - `#live[name]` is the name's failure count still inside the window = its escalation score.
+ *  - Memory is hard-bounded: the ring holds ≤ `window` events, hence ≤ `window` distinct names.
+ *  - `succeed()` bumps a per-name `#epoch`; events carry the epoch they were recorded under, so a
+ *    success invalidates the name's in-window failures (score resets) in O(1) without scanning
+ *    the ring — the stale events simply don't count as they age out.
+ *  - Latch (`trip`): a per-name flag so an escalation fires ONCE and does not re-fire while the
+ *    task stays continuously failing; it clears when the task succeeds or every failure ages out.
+ *
+ * SEMANTIC NOTE (deliberate change from the first #1822 attempt): escalation is now "threshold
+ * failures WITHIN the window", not "threshold consecutive failures ever". Failures spread wider
+ * apart than the window decay and never trip — which is the actual flap-detection semantic.
+ */
+export class StrikeCounter {
+    #ring;
+    /** Failures still inside the window under the name's CURRENT epoch = its escalation score. */
+    #live = new Map();
+    /** Total ring occurrences per name across all epochs — for O(1) cleanup and the memory bound. */
+    #present = new Map();
+    /** Per-name epoch, bumped by succeed() so pre-success failures stop counting. */
+    #epoch = new Map();
+    /** Names that have escalated and not yet re-armed (edge-trigger latch). */
+    #latched = new Set();
+    #clock = 0;
+    threshold;
+    window;
+    constructor(threshold = 3, escalationWindowAttempts = 4096) {
+        if (!Number.isSafeInteger(threshold) || threshold < 1)
+            throw new RangeError("escalationThreshold must be a positive integer");
+        if (!Number.isSafeInteger(escalationWindowAttempts) || escalationWindowAttempts < 1)
+            throw new RangeError("escalationWindowAttempts must be a positive integer");
+        // A window smaller than the threshold can never hold `threshold` of one name's failures at
+        // once (the ring evicts the oldest before the count gets there), so it would score 1,2,…,
+        // threshold-1 forever and SILENTLY never escalate. Reject it rather than mislead (#1822 LOW-4).
+        if (escalationWindowAttempts < threshold)
+            throw new RangeError("escalationWindowAttempts must be >= escalationThreshold");
+        this.threshold = threshold;
+        this.window = escalationWindowAttempts;
+        this.#ring = new Array(escalationWindowAttempts).fill(undefined);
+    }
+    /** Distinct task names with a failure still inside the window. Bounded by `window`. */
+    get size() {
+        return this.#present.size;
+    }
+    // Removes the event in `slot` (the one aging out of the window) and updates the name's counts.
+    #expire(slot) {
+        const event = this.#ring[slot];
+        if (event === undefined)
+            return;
+        this.#ring[slot] = undefined;
+        const { name, epoch } = event;
+        // Only decrement the score if the event is still under the name's live epoch; an event from
+        // before a succeed() carries a stale epoch and was never counted toward the current score.
+        if (epoch === (this.#epoch.get(name) ?? 0)) {
+            const live = (this.#live.get(name) ?? 0) - 1;
+            if (live <= 0) {
+                this.#live.delete(name);
+                this.#latched.delete(name);
+            }
+            else
+                this.#live.set(name, live);
+        }
+        const present = (this.#present.get(name) ?? 0) - 1;
+        if (present <= 0) {
+            // Every trace of the name has aged out of the window: forget it entirely (this is the
+            // natural memory bound, and it re-arms a latch that went quiet).
+            this.#present.delete(name);
+            this.#epoch.delete(name);
+            this.#live.delete(name);
+            this.#latched.delete(name);
+        }
+        else {
+            this.#present.set(name, present);
+        }
+    }
+    fail(taskName) {
+        this.#clock += 1;
+        const slot = (this.#clock - 1) % this.window;
+        // The event this slot holds is exactly `window` attempts old — evict it before reusing it.
+        this.#expire(slot);
+        const epoch = this.#epoch.get(taskName) ?? 0;
+        this.#ring[slot] = { name: taskName, epoch };
+        this.#present.set(taskName, (this.#present.get(taskName) ?? 0) + 1);
+        const score = (this.#live.get(taskName) ?? 0) + 1;
+        this.#live.set(taskName, score);
+        // A latched name must not re-page while it stays continuously live.
+        if (this.#latched.has(taskName))
+            return 0;
+        return score;
+    }
+    /** Latch an escalation so it fires once until the task re-arms (succeeds or ages out). */
+    trip(taskName) {
+        // Latch ONLY a name that has a failure in the window. Otherwise a caller (or a bug) tripping
+        // arbitrary names would grow #latched without any ring presence to age it out — breaking the
+        // "memory bounded BY the window" invariant, since `size` counts only #present (#1822 MED-3).
+        // In practice trip() is always called right after fail() returned >= threshold, so the name
+        // is present; this guard just makes the bound hold unconditionally.
+        if (this.#present.has(taskName))
+            this.#latched.add(taskName);
+    }
+    succeed(taskName) {
+        // Nothing tracked → nothing to reset (and never create an epoch entry for a name that only
+        // ever succeeds, which would leak one map entry per distinct successful task name).
+        if (!this.#present.has(taskName))
+            return;
+        // Bump the epoch: every in-window failure recorded under the old epoch stops counting, so
+        // the score resets to 0 in O(1). The stale ring events are reclaimed as they age out.
+        this.#epoch.set(taskName, (this.#epoch.get(taskName) ?? 0) + 1);
+        this.#live.delete(taskName);
+        this.#latched.delete(taskName);
+    }
+}
+export function normalizeError(taskName, error, fallback = "rejected") {
+    if (error instanceof OffloadError)
+        return error;
+    const detail = error;
+    return new OffloadError({
+        kind: fallback,
+        taskName,
+        code: typeof detail?.code === "string" ? detail.code : undefined,
+        message: errMessage(error),
+        cause: error,
+    });
+}
+export function log(logger, level, message, fields) {
+    const method = logger?.[level];
+    if (typeof method !== "function")
+        return;
+    try {
+        method.call(logger, message, fields);
+    }
+    catch {
+        // A caller-supplied transport that throws must never break the run it is describing:
+        // logging happens on the settle path, so an escaping throw wedges the backend (#1809 P0-1).
+        // There is no second transport to report this to, so it is deliberately swallowed.
+    }
+}
+export function validateTimeout(timeoutMs) {
+    if (timeoutMs === undefined)
+        return undefined;
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0)
+        throw new RangeError("timeoutMs must be a positive finite number");
+    return timeoutMs;
+}
+//# sourceMappingURL=types.js.map

package/node_modules/@humwick/offload/dist/types.js.map

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

package/node_modules/@humwick/offload/dist/worker-pool.d.ts

@@ -0,0 +1,23 @@
+import { type OffloadDefaults, type OffloadEnvelope } from "./types.js";
+export interface WorkerPoolOptions extends OffloadDefaults {
+    /** A module that default-exports `(input, { taskName }) => output`. Prefer a file URL. */
+    worker: URL | string;
+    size?: number;
+}
+export interface WorkerPoolStats {
+    busy: number;
+    idle: number;
+    queued: number;
+}
+export interface WorkerPool {
+    run<In, Out>(taskName: string, input: In, env?: OffloadEnvelope): Promise<Out>;
+    readonly stats: WorkerPoolStats;
+    readonly offThread: true;
+    destroy(): Promise<void>;
+}
+/**
+ * Fixed native Bun Worker pool. A deadline or abort replaces the whole worker because
+ * CPU-bound synchronous code cannot observe a cancellation message while it is busy.
+ */
+export declare function createWorkerPool(options: WorkerPoolOptions): WorkerPool;
+//# sourceMappingURL=worker-pool.d.ts.map

package/node_modules/@humwick/offload/dist/worker-pool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-pool.d.ts","sourceRoot":"","sources":["../src/worker-pool.ts"],"names":[],"mappings":"AACA,OAAO,EAAgE,KAAK,eAAe,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAEtI,MAAM,WAAW,iBAAkB,SAAQ,eAAe;IACxD,0FAA0F;IAC1F,MAAM,EAAE,GAAG,GAAG,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,UAAU;IACzB,GAAG,CAAC,EAAE,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,EAAE,EAAE,GAAG,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAC/E,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC;IACzB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAqDD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,GAAG,UAAU,CAiYvE"}

package/node_modules/@humwick/offload/dist/worker-pool.js

@@ -0,0 +1,435 @@
+import { beginRun, errorForExit, finishLog, recordResult, startLog } from "./envelope.js";
+import { OffloadError, StrikeCounter, normalizeError, validateTimeout } from "./types.js";
+// For a RETRY-SAFE job (env.retrySafe), a worker death with the job in flight is absorbed by
+// re-dispatching to a fresh worker up to this many times. Reaching the limit means the job's OWN
+// execution repeatedly killed the worker (a real fault), so it is then charged and still
+// escalates. A non-retry-safe (default) job is never re-dispatched — it runs at most once
+// (#1822 HIGH-1). See onWorkerDeath.
+const MAX_JOB_REDISPATCHES = 2;
+/**
+ * Fixed native Bun Worker pool. A deadline or abort replaces the whole worker because
+ * CPU-bound synchronous code cannot observe a cancellation message while it is busy.
+ */
+export function createWorkerPool(options) {
+    const size = options.size ?? Math.max(1, (navigator.hardwareConcurrency || 2) - 1);
+    if (!Number.isSafeInteger(size) || size < 1)
+        throw new RangeError("size must be a positive integer");
+    const workerModule = options.worker instanceof URL ? options.worker.href : options.worker;
+    const slots = [];
+    const queued = [];
+    const counter = new StrikeCounter(options.escalationThreshold, options.escalationWindowAttempts);
+    let nextId = 1;
+    let destroyed = false;
+    let destroyPromise;
+    let dispatching = false;
+    let compactionScheduled = false;
+    let cancelledQueued = 0;
+    const createSlot = () => {
+        const slot = { worker: undefined, generation: 0, replacing: false };
+        spawnInto(slot);
+        return slot;
+    };
+    // A worker that dies while idle (OOM kill, external SIGKILL, a crash between jobs) leaves a
+    // dead handle in the slot. Respawn it so the next run() gets a live worker; nobody is charged
+    // because no job was running (#1822 item 2). There is deliberately NO revival breaker: a tight
+    // spawn-death loop would require the worker BOOTSTRAP itself to fail to load repeatedly, which
+    // cannot happen through the public API (the bootstrap is this package's own module), so a
+    // breaker for it is disproportionate surface (#1822 F3 — simplified). A job that races this
+    // revival is protected by re-dispatch (onWorkerDeath), never by counting idle deaths.
+    const reviveIdle = (slot) => {
+        if (destroyed || slot.replacing)
+            return;
+        void replace(slot);
+    };
+    const spawnInto = (slot) => {
+        if (destroyed)
+            return;
+        const generation = ++slot.generation;
+        // `.js` is intentional: package consumers execute the compiled dist asset. Bun maps this
+        // to the sibling TypeScript source while running the workspace directly in development.
+        const worker = new Worker(new URL("./worker-runtime.js", import.meta.url), { type: "module" });
+        slot.worker = worker;
+        worker.onmessage = (event) => {
+            if (slot.generation !== generation)
+                return;
+            const active = slot.active;
+            if (!active || active.id !== event.data.id)
+                return;
+            if (event.data.ok)
+                settle(slot, active, undefined, event.data.value);
+            else
+                settle(slot, active, new OffloadError({
+                    kind: "worker-error", taskName: active.taskName, code: event.data.error?.code, message: event.data.error?.message ?? "Worker task failed",
+                }));
+        };
+        worker.onerror = (event) => {
+            if (slot.generation !== generation)
+                return;
+            const active = slot.active;
+            if (!active) {
+                reviveIdle(slot);
+                return;
+            }
+            // An uncaught error is by definition an abnormal termination attributable to the running job.
+            onWorkerDeath(slot, active, new OffloadError({ kind: "worker-error", taskName: active.taskName, message: event.message || "Worker errored", cause: event.error }), true);
+        };
+        // Bun reports process.exit(), OOM, and hard crashes through `close` without an `error` event.
+        // Reclaiming the slot here is essential when a caller omitted a timeout — and when the slot is
+        // idle, so a later run() never inherits the dead worker (#1822 item 2). The close event carries
+        // the exit `code`: 0 is a clean exit the worker CHOSE (not the job's fault); anything else is an
+        // abnormal termination attributable to the in-flight job (#1822 MED-4). A missing code is
+        // treated as abnormal — the safe default is to preserve escalation, not to drop it.
+        worker.addEventListener("close", (event) => {
+            if (slot.generation !== generation)
+                return;
+            const active = slot.active;
+            if (!active) {
+                reviveIdle(slot);
+                return;
+            }
+            const code = event.code;
+            const clean = code === 0;
+            onWorkerDeath(slot, active, errorForExit(active.taskName, clean ? undefined : String(code)), !clean);
+        });
+    };
+    const settle = (slot, active, error, value) => {
+        if (active.settled)
+            return;
+        active.settled = true;
+        active.context.cleanup();
+        active.removeAbort();
+        slot.active = undefined;
+        const labels = active.env?.labels ?? {};
+        const logger = active.env?.logger ?? options.logger;
+        finishLog(logger, "worker", active.taskName, labels, active.startedAt, error);
+        void recordResult({
+            counter, taskName: active.taskName, backend: "worker", labels, error,
+            sink: active.env?.onEscalate ?? options.onEscalate, logger,
+        });
+        if (error)
+            active.reject(error);
+        else
+            active.resolve(value);
+        dispatch();
+    };
+    // `error` is omitted only when reviving an idle slot: with no active job there is nothing to
+    // settle and nobody to charge, so the slot is simply respawned (#1822 item 2).
+    const replace = async (slot, error) => {
+        if (slot.replacing)
+            return;
+        slot.replacing = true;
+        const active = slot.active;
+        if (active && error)
+            settle(slot, active, error);
+        const old = slot.worker;
+        slot.generation += 1;
+        try {
+            await old.terminate();
+        }
+        catch { /* worker is already gone */ }
+        if (!destroyed) {
+            spawnInto(slot);
+            slot.replacing = false;
+            dispatch();
+        }
+    };
+    /** Fails exactly one job without touching the slot it was about to occupy. */
+    const failJob = (job, error) => {
+        // Every terminal path must be visible in the structured stream, including the ones that
+        // never reached startLog — otherwise the failure that used to wedge the pool is silent.
+        finishLog(job.env?.logger ?? options.logger, "worker", job.taskName, job.env?.labels ?? {}, performance.now(), error);
+        job.reject(error);
+        void recordResult({
+            counter, taskName: job.taskName, backend: "worker", labels: job.env?.labels ?? {}, error,
+            sink: job.env?.onEscalate ?? options.onEscalate, logger: job.env?.logger ?? options.logger,
+        });
+    };
+    // Attaches the while-queued abort wiring and enqueues a job. Shared by run() and redispatch()
+    // so a re-dispatched job re-arms its abort handling exactly like a fresh one. `front` puts an
+    // innocent, re-dispatched job ahead of newer work so its retry is prompt.
+    const enqueue = (job, front = false) => {
+        const labels = job.env?.labels ?? {};
+        const logger = job.env?.logger ?? options.logger;
+        const signal = job.env?.signal;
+        if (signal?.aborted) {
+            const error = new OffloadError({ kind: "aborted", taskName: job.taskName, message: `${job.taskName} was aborted`, cause: signal.reason });
+            finishLog(logger, "worker", job.taskName, labels, performance.now(), error);
+            job.reject(error);
+            return;
+        }
+        if (signal) {
+            // Without this, a job aborted while queued waits for a slot to free before it is
+            // rejected — unbounded when the occupying worker has no deadline (#1809 P1-8).
+            const onQueuedAbort = () => {
+                if (job.cancelled)
+                    return;
+                job.cancelled = true;
+                cancelledQueued += 1;
+                scheduleCompaction();
+                const error = new OffloadError({ kind: "aborted", taskName: job.taskName, message: `${job.taskName} was aborted`, cause: signal.reason });
+                // An abort that lands mid-run logs `offload failed kind=aborted`; one that lands
+                // while queued must not be the single asymmetric case that logs nothing.
+                finishLog(logger, "worker", job.taskName, labels, performance.now(), error);
+                job.reject(error);
+            };
+            signal.addEventListener("abort", onQueuedAbort, { once: true });
+            job.releaseQueued = () => signal.removeEventListener("abort", onQueuedAbort);
+        }
+        if (front)
+            queued.unshift(job);
+        else
+            queued.push(job);
+        dispatch();
+    };
+    // Fails a job WITHOUT charging a strike, for a death that is not attributable to the job's own
+    // execution (an idle-death race — the job never ran). Still logged so the stream is complete.
+    const failJobUncharged = (job, error) => {
+        finishLog(job.env?.logger ?? options.logger, "worker", job.taskName, job.env?.labels ?? {}, performance.now(), error);
+        job.reject(error);
+    };
+    // A worker died with `active` still in flight and unsettled. Two axes decide the outcome:
+    //  - RE-RUN? Only a retry-safe (idempotent) job may re-run, and only while it has retries left.
+    //    A default job runs AT MOST ONCE, so it is never re-dispatched (#1822 HIGH-1) — re-running
+    //    a side-effecting job would repeat its effect. A retry-safe job re-dispatches on ANY death
+    //    (clean or abnormal) while retries remain, since re-running it is safe by construction.
+    //  - CHARGE? Only when the death is ATTRIBUTABLE to the job's own execution, decided from the
+    //    worker's EXIT MANNER observed by the pool: an abnormal termination (non-zero exit, signal,
+    //    or uncaught error) with this job in flight is charged; a clean exit (code 0 — the worker
+    //    chose to stop) or a job that never reached a worker (postMessage threw) is an idle-race /
+    //    infra event, not a task fault, and is rejected WITHOUT a strike. Exit manner is used instead
+    //    of a worker-sent execution-start frame precisely because that frame can be LOST when a hard
+    //    crash races it, which would let a job that reliably crashes its worker escape escalation
+    //    forever (#1822 MED-4). `attributable` already covers retry-exhaustion: a retry-safe job that
+    //    crashes every worker exhausts its retries on an abnormal death, so that final death charges.
+    const onWorkerDeath = (slot, active, error, attributable) => {
+        const retrySafe = active.retrySafe;
+        if (retrySafe && active.redispatches < MAX_JOB_REDISPATCHES) {
+            redispatch(slot, active);
+            return;
+        }
+        if (attributable) {
+            // `replace` settles the still-attached active job with the error, charging it once.
+            void replace(slot, error);
+            return;
+        }
+        // Clean exit / never executed → do not charge. Detach, respawn a fresh worker, reject the caller.
+        slot.active = undefined;
+        active.removeAbort();
+        active.context.cleanup();
+        void replace(slot);
+        failJobUncharged(active, error);
+    };
+    // Detaches a retry-safe job from a dead slot, respawns a fresh worker there, and re-queues the
+    // SAME caller promise so an idempotent job that raced a worker death runs cleanly. The absolute
+    // deadline is carried on the job, so the retry continues the original deadline (#1822 MED-2).
+    const redispatch = (slot, active) => {
+        slot.active = undefined;
+        active.removeAbort();
+        active.context.cleanup();
+        const job = {
+            id: active.id, taskName: active.taskName, input: active.input, env: active.env,
+            retrySafe: active.retrySafe, timeoutMs: active.timeoutMs,
+            cancelled: false, redispatches: active.redispatches + 1, deadlineAt: active.deadlineAt,
+            releaseQueued: () => { }, resolve: active.resolve, reject: active.reject,
+        };
+        // Respawn FIRST so the slot is marked `replacing` synchronously and dispatch cannot hand the
+        // re-queued job straight back to the same corpse; replace()'s own dispatch then serves it.
+        void replace(slot);
+        enqueue(job, true);
+    };
+    const start = (slot, job) => {
+        job.releaseQueued();
+        let context;
+        let removeAbort;
+        try {
+            // Fix the deadline at the FIRST execution and carry it, so a retry-safe re-dispatch
+            // continues the original deadline rather than restarting the full timeout (#1822 MED-2).
+            // The budget comes from the SUBMISSION-TIME snapshot (`job.timeoutMs`), never from the
+            // mutable envelope, so a caller cannot erase or add a deadline after submission (#1822 MED).
+            const baseTimeoutMs = job.timeoutMs;
+            let effectiveTimeoutMs = baseTimeoutMs;
+            if (baseTimeoutMs !== undefined) {
+                if (job.deadlineAt === undefined)
+                    job.deadlineAt = performance.now() + baseTimeoutMs;
+                const remaining = job.deadlineAt - performance.now();
+                if (remaining <= 0) {
+                    // The absolute deadline set on the first execution has already elapsed. A re-dispatch
+                    // must NOT be granted a fresh run past it (the old `Math.max(1, …)` handed out a 1ms
+                    // execution AFTER expiry — #1822 MED). A genuine timeout is attributable, so charge it.
+                    failJob(job, new OffloadError({ kind: "timeout", taskName: job.taskName, message: `${job.taskName} timed out after ${baseTimeoutMs}ms` }));
+                    return;
+                }
+                effectiveTimeoutMs = remaining;
+            }
+            // Pass the ALREADY-RESOLVED timeout as the authoritative override, so beginRun installs
+            // exactly it and re-reads neither the envelope NOR the mutable pool default at dispatch —
+            // a post-submission mutation of either cannot add or erase this job's deadline (#1822 MED).
+            // `null` (not `undefined`) carries "no deadline" so beginRun does not mistake it for "no
+            // argument" and fall back to the default. The live envelope is still passed for its signal.
+            context = beginRun(job.taskName, job.env, options, undefined, effectiveTimeoutMs ?? null);
+            if (context.signal.aborted) {
+                const error = context.abortError();
+                context.cleanup();
+                failJob(job, error);
+                return;
+            }
+            const run = context;
+            const onAbort = () => { void replace(slot, run.abortError()); };
+            run.signal.addEventListener("abort", onAbort, { once: true });
+            removeAbort = () => run.signal.removeEventListener("abort", onAbort);
+            const active = {
+                ...job, context: run, removeAbort, settled: false,
+                startedAt: startLog(job.env?.logger ?? options.logger, "worker", job.taskName, job.env?.labels ?? {}),
+            };
+            slot.active = active;
+            try {
+                slot.worker.postMessage({ id: job.id, taskName: job.taskName, input: job.input, worker: workerModule });
+            }
+            catch (error) {
+                // postMessage throws when the worker died between dispatch and here (an idle-death race):
+                // the job never reached a worker, so it is NOT attributable — re-dispatch it (retrySafe)
+                // or reject it uncharged rather than charge it for a death it did not cause (#1822 F2).
+                onWorkerDeath(slot, active, normalizeError(job.taskName, error, "worker-error"), false);
+            }
+        }
+        catch (error) {
+            // Anything that throws while starting (an invalid deadline, a hostile logger) must fail
+            // ONLY this job. Letting it escape leaves the slot idle with the queue stuck (#1809 P0-1),
+            // and the caller must still see an OffloadError rather than the raw RangeError.
+            removeAbort?.();
+            context?.cleanup();
+            if (slot.active?.id === job.id)
+                slot.active = undefined;
+            failJob(job, normalizeError(job.taskName, error, "rejected"));
+        }
+    };
+    /**
+     * Iterative on purpose: the previous version recursed through `start()` for every
+     * pre-aborted job, so a mass abort over a deep queue blew the stack (#1809 P0-2).
+     * The guard makes the nested `dispatch()` calls on the settle path no-ops — the loop
+     * below re-reads slot and queue state on every turn, so no wakeup is lost.
+     */
+    const dispatch = () => {
+        if (destroyed || dispatching)
+            return;
+        dispatching = true;
+        try {
+            while (!destroyed && queued.length) {
+                const job = queued[0];
+                if (job.cancelled) {
+                    queued.shift();
+                    cancelledQueued -= 1;
+                    continue;
+                }
+                const slot = slots.find((candidate) => !candidate.active && !candidate.replacing);
+                if (!slot)
+                    break;
+                queued.shift();
+                start(slot, job);
+            }
+        }
+        finally {
+            dispatching = false;
+        }
+    };
+    /**
+     * A mass abort marks jobs in place — splicing each one out would be quadratic over a
+     * deep queue — so the dead entries are swept once per batch instead.
+     */
+    const scheduleCompaction = () => {
+        if (compactionScheduled)
+            return;
+        compactionScheduled = true;
+        queueMicrotask(() => {
+            compactionScheduled = false;
+            if (cancelledQueued <= 0)
+                return;
+            const kept = queued.filter((job) => !job.cancelled);
+            queued.length = 0;
+            for (const job of kept)
+                queued.push(job);
+            cancelledQueued = 0;
+        });
+    };
+    for (let index = 0; index < size; index += 1)
+        slots.push(createSlot());
+    return {
+        offThread: true,
+        get stats() {
+            const busy = slots.filter((slot) => slot.active).length;
+            return { busy, idle: slots.length - busy, queued: queued.length - cancelledQueued };
+        },
+        run(taskName, input, env) {
+            const labels = env?.labels ?? {};
+            const logger = env?.logger ?? options.logger;
+            // Rejecting before the run ever starts is still a terminal outcome, so it gets the same
+            // one line in the structured stream that every other settle path emits.
+            const rejectBeforeStart = (error) => {
+                finishLog(logger, "worker", taskName, labels, performance.now(), error);
+                return Promise.reject(error);
+            };
+            if (destroyed)
+                return rejectBeforeStart(new OffloadError({ kind: "worker-exit", taskName, message: "Worker pool has been destroyed" }));
+            // Validated here rather than at dispatch so an invalid deadline fails the caller fast,
+            // with the OffloadError every backend promises, even when a slot is free (#1809 P0-1). The
+            // validated value is SNAPSHOTTED onto the job so the deadline it drives is fixed at
+            // submission and immune to a later envelope mutation (#1822 MED).
+            let timeoutMs;
+            try {
+                timeoutMs = validateTimeout(env?.timeoutMs ?? options.defaultTimeoutMs);
+            }
+            catch (error) {
+                const normalized = normalizeError(taskName, error, "rejected");
+                // Counted as a strike like the other two backends do for the same input: an invalid
+                // deadline is a genuine caller failure, not a cancellation.
+                void recordResult({ counter, taskName, backend: "worker", labels, error: normalized, sink: env?.onEscalate ?? options.onEscalate, logger });
+                return rejectBeforeStart(normalized);
+            }
+            // `retrySafe` is snapshotted here too, for the same reason (#1822 HIGH): the pool must decide
+            // re-dispatch from the caller's intent AT SUBMISSION, not from whatever `env` holds when a
+            // worker later dies.
+            const retrySafe = env?.retrySafe === true;
+            return new Promise((resolve, reject) => {
+                const job = { id: nextId++, taskName, input, env, retrySafe, timeoutMs, cancelled: false, redispatches: 0, releaseQueued: () => { }, resolve, reject };
+                enqueue(job);
+            });
+        },
+        destroy() {
+            if (destroyPromise)
+                return destroyPromise;
+            destroyed = true;
+            // The split below is INTENTIONAL — do not unify the two.
+            // Cancelled-at-destroy is `aborted`, matching what the async and subprocess runners
+            // already report for teardown: only `aborted` is strike-exempt, so anything else
+            // charges a strike per in-flight job and a pool sitting at its threshold false-pages
+            // on the orderly shutdown every adopter runs. A `run()` arriving AFTER destroy() is a
+            // different event — caller misuse against a dead pool — and deliberately keeps its own
+            // distinguishable `worker-exit` kind.
+            const error = (taskName) => new OffloadError({ kind: "aborted", taskName, message: `${taskName} was cancelled: worker pool destroyed` });
+            while (queued.length) {
+                const job = queued.shift();
+                if (!job)
+                    continue;
+                job.releaseQueued();
+                if (job.cancelled)
+                    continue;
+                const cancellation = error(job.taskName);
+                finishLog(job.env?.logger ?? options.logger, "worker", job.taskName, job.env?.labels ?? {}, performance.now(), cancellation);
+                job.reject(cancellation);
+            }
+            cancelledQueued = 0;
+            const workers = slots.map(async (slot) => {
+                if (slot.active)
+                    settle(slot, slot.active, error(slot.active.taskName));
+                slot.generation += 1;
+                try {
+                    await slot.worker.terminate();
+                }
+                catch { /* already stopped */ }
+            });
+            destroyPromise = Promise.all(workers).then(() => undefined);
+            return destroyPromise;
+        },
+    };
+}
+//# sourceMappingURL=worker-pool.js.map