@humwick/runner 0.0.0-stage → 0.130.1

package/node_modules/@humwick/offload/dist/subprocess-runner.d.ts

@@ -0,0 +1,62 @@
+import { type OffloadDefaults, type OffloadEnvelope } from "./types.js";
+export interface SubprocessSpec {
+    command: string[];
+    cwd?: string;
+    env?: Record<string, string | undefined>;
+    /**
+     * Exit codes that are a normal ANSWER rather than a failure. Defaults to `[0]`; pass
+     * `"any"` when every code is data (a land gate whose failing codes are not enumerable).
+     *
+     * Probe-shaped callers use a non-zero exit as data — `tmux has-session` exits 1 when the
+     * session is absent, `git rev-parse` exits 128 outside a repo, `which` exits 1. Without
+     * this they reject AND take an escalation strike for a healthy result, which inverts the
+     * signal: the sink pages on a healthy fleet, then latches (it only re-arms on a success,
+     * which never comes in that steady state) so the real outage is silent.
+     *
+     * `"any"` includes SIGNAL DEATHS — a child killed by SIGKILL (137) or SIGSEGV (139)
+     * returns as a success and RE-ARMS the strike counter. That is intended for a land gate,
+     * where an OOM-killed gate is simply a failed gate, but it means an infrastructure death
+     * reads as a healthy answer and will never escalate. Prefer an explicit code list unless
+     * the failing codes genuinely cannot be enumerated. Timeout and abort still throw.
+     */
+    okExitCodes?: readonly number[] | "any";
+}
+export interface SubprocessResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    /** True when either stream hit `maxOutputBytes` and the captured text was cut short. */
+    truncated: boolean;
+}
+export interface SubprocessRunnerOptions extends OffloadDefaults {
+    concurrency?: number;
+    /**
+     * How long a child may keep running after SIGTERM before it is SIGKILLed. This is the
+     * slack on the deadline: a run cannot outlive `timeoutMs + killGraceMs` (plus a short
+     * reap window) even if it traps or ignores SIGTERM. Defaults to 2000ms.
+     */
+    killGraceMs?: number;
+    /** Captured bytes per stream before output is truncated. Defaults to 8 MiB. */
+    maxOutputBytes?: number;
+}
+export interface SubprocessRunner {
+    run(taskName: string, process: SubprocessSpec, env?: OffloadEnvelope): Promise<SubprocessResult>;
+    readonly stats: {
+        active: number;
+        queued: number;
+    };
+    /** A subprocess owns the heavy work, so maintenance callers may mark their await window off-thread. */
+    readonly offThread: true;
+    /** Resolves when everything accepted so far has finished. Does not cancel anything. */
+    drain(): Promise<void>;
+    /** SIGKILLs and awaits every live child, settles every outstanding caller, and refuses new work. */
+    destroy(): Promise<void>;
+}
+/**
+ * Bounded wrapper around the repo's standard `Bun.spawn(... { stdout: "pipe", stderr: "pipe" })`
+ * pattern. On POSIX, each run gets its own process group so timeout/abort also kills
+ * descendants (for example shell, git, or install subprocess trees); Windows falls back
+ * to Bun's direct-child kill because POSIX process groups do not exist there.
+ */
+export declare function createSubprocessRunner(options?: SubprocessRunnerOptions): SubprocessRunner;
+//# sourceMappingURL=subprocess-runner.d.ts.map

package/node_modules/@humwick/offload/dist/subprocess-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subprocess-runner.d.ts","sourceRoot":"","sources":["../src/subprocess-runner.ts"],"names":[],"mappings":"AAEA,OAAO,EAAgE,KAAK,eAAe,EAAE,KAAK,eAAe,EAAE,MAAM,YAAY,CAAC;AAEtI,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACzC;;;;;;;;;;;;;;;OAeG;IACH,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,KAAK,CAAC;CACzC;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,wFAAwF;IACxF,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,uBAAwB,SAAQ,eAAe;IAC9D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+EAA+E;IAC/E,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,gBAAgB;IAC/B,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,EAAE,GAAG,CAAC,EAAE,eAAe,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IACjG,QAAQ,CAAC,KAAK,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IACnD,uGAAuG;IACvG,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC;IACzB,uFAAuF;IACvF,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,oGAAoG;IACpG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAmFD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,GAAE,uBAA4B,GAAG,gBAAgB,CA4L9F"}

package/node_modules/@humwick/offload/dist/subprocess-runner.js

@@ -0,0 +1,295 @@
+import PQueue from "p-queue";
+import { beginRun, finishLog, recordResult, startLog } from "./envelope.js";
+import { OffloadError, StrikeCounter, normalizeError, validateTimeout } from "./types.js";
+const DEFAULT_KILL_GRACE_MS = 2_000;
+const DEFAULT_MAX_OUTPUT_BYTES = 8 * 1024 * 1024;
+/** How long to wait for a SIGKILLed child to be reaped before giving its slot back anyway. */
+const REAP_GRACE_MS = 1_000;
+/**
+ * `detached` children are reparented rather than reaped when the host dies (#1809 P1-5), so
+ * every live group is killed from a single process-level exit hook. One module-scoped hook
+ * keeps runner instances from piling up `exit` listeners.
+ */
+const liveChildren = new Set();
+let exitHookInstalled = false;
+function killGroup(child, signal) {
+    try {
+        if (process.platform !== "win32")
+            process.kill(-child.pid, signal);
+        else
+            child.kill();
+    }
+    catch {
+        try {
+            child.kill(signal);
+        }
+        catch { /* the child is already gone */ }
+    }
+}
+function trackChild(child) {
+    liveChildren.add(child);
+    if (exitHookInstalled)
+        return;
+    exitHookInstalled = true;
+    process.on("exit", () => {
+        for (const live of liveChildren)
+            killGroup(live, "SIGKILL");
+    });
+}
+/** Reads a stream up to `limit` bytes, then keeps draining so the child never blocks on a full pipe. */
+async function readCapped(stream, limit) {
+    if (!stream)
+        return { text: "", truncated: false };
+    const reader = stream.getReader();
+    const chunks = [];
+    let size = 0;
+    let truncated = false;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (!value)
+                continue;
+            const remaining = limit - size;
+            if (remaining <= 0) {
+                truncated = true;
+                continue;
+            }
+            if (value.byteLength > remaining) {
+                chunks.push(value.subarray(0, remaining));
+                size = limit;
+                truncated = true;
+                continue;
+            }
+            chunks.push(value);
+            size += value.byteLength;
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    const buffer = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) {
+        buffer.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return { text: new TextDecoder().decode(buffer), truncated };
+}
+/**
+ * Bounded wrapper around the repo's standard `Bun.spawn(... { stdout: "pipe", stderr: "pipe" })`
+ * pattern. On POSIX, each run gets its own process group so timeout/abort also kills
+ * descendants (for example shell, git, or install subprocess trees); Windows falls back
+ * to Bun's direct-child kill because POSIX process groups do not exist there.
+ */
+export function createSubprocessRunner(options = {}) {
+    const queue = new PQueue({ concurrency: options.concurrency ?? 1 });
+    const counter = new StrikeCounter(options.escalationThreshold, options.escalationWindowAttempts);
+    const killGraceMs = options.killGraceMs ?? DEFAULT_KILL_GRACE_MS;
+    const maxOutputBytes = options.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;
+    if (!Number.isFinite(killGraceMs) || killGraceMs < 0)
+        throw new RangeError("killGraceMs must be a non-negative finite number");
+    if (!Number.isSafeInteger(maxOutputBytes) || maxOutputBytes < 1)
+        throw new RangeError("maxOutputBytes must be a positive integer");
+    const live = new Set();
+    const children = new Set();
+    let destroyed = false;
+    const abortedError = (taskName, cause) => new OffloadError({ kind: "aborted", taskName, message: `${taskName} was aborted`, cause });
+    const destroyedError = (taskName) => new OffloadError({ kind: "aborted", taskName, message: `${taskName} was cancelled: subprocess runner destroyed` });
+    return {
+        offThread: true,
+        get stats() { return { active: queue.pending, queued: queue.size }; },
+        async run(taskName, spec, env) {
+            const labels = env?.labels ?? {};
+            const logger = env?.logger ?? options.logger;
+            const sink = env?.onEscalate ?? options.onEscalate;
+            const reportRejection = async (error) => {
+                // Rejecting before the run reaches startLog is still a terminal outcome; without this
+                // the structured stream shows nothing at all for it.
+                finishLog(logger, "subprocess", taskName, labels, performance.now(), error);
+                await recordResult({ counter, taskName, backend: "subprocess", labels, error, sink, logger });
+                throw error;
+            };
+            if (!spec.command.length)
+                return reportRejection(new OffloadError({ kind: "rejected", taskName, message: "Subprocess command must not be empty" }));
+            if (destroyed)
+                return reportRejection(destroyedError(taskName));
+            if (env?.signal?.aborted)
+                return reportRejection(abortedError(taskName, env.signal.reason));
+            try {
+                validateTimeout(env?.timeoutMs ?? options.defaultTimeoutMs);
+            }
+            catch (error) {
+                return reportRejection(normalizeError(taskName, error, "rejected"));
+            }
+            let publish;
+            let published = false;
+            const outcome = new Promise((resolve) => {
+                publish = (value) => { if (!published) {
+                    published = true;
+                    resolve(value);
+                } };
+            });
+            let started = false;
+            let cancelled = false;
+            const entry = {
+                taskName,
+                teardown: new AbortController(),
+                settled: outcome.then(() => undefined),
+                cancelIfQueued: (error) => {
+                    if (started || cancelled)
+                        return;
+                    cancelled = true;
+                    // The single funnel for both abort-while-queued and destroy()-cancels-queued, so
+                    // the one line each terminal path owes the structured stream is emitted here. The
+                    // callback bails on `cancelled` without logging, which keeps it to exactly one.
+                    finishLog(logger, "subprocess", taskName, labels, performance.now(), error);
+                    publish({ ok: false, error });
+                },
+            };
+            live.add(entry);
+            // p-queue's own `signal` option used to provide prompt abort for queued runs, but it
+            // also released the slot while the child kept running (#1809 P1-7).
+            const signal = env?.signal;
+            const onQueuedAbort = signal ? () => entry.cancelIfQueued(abortedError(taskName, signal.reason)) : undefined;
+            if (signal && onQueuedAbort)
+                signal.addEventListener("abort", onQueuedAbort, { once: true });
+            const task = queue.add(async () => {
+                if (signal && onQueuedAbort)
+                    signal.removeEventListener("abort", onQueuedAbort);
+                let context;
+                let child;
+                let onAbort;
+                let killTimer;
+                let abandonTimer;
+                let reaped = false;
+                let abandon;
+                const abandoned = new Promise((resolve) => { abandon = () => resolve("abandoned"); });
+                try {
+                    if (cancelled)
+                        return;
+                    if (destroyed || entry.teardown.signal.aborted) {
+                        const error = destroyedError(taskName);
+                        finishLog(logger, "subprocess", taskName, labels, performance.now(), error);
+                        publish({ ok: false, error });
+                        return;
+                    }
+                    started = true;
+                    context = beginRun(taskName, env, options, entry.teardown.signal);
+                    const run = context;
+                    const startedAt = startLog(logger, "subprocess", taskName, labels);
+                    // SIGTERM alone bounds nothing: a child that traps or ignores it runs to completion
+                    // while holding the slot (#1809 P0-3). Escalate to a group SIGKILL, then stop
+                    // waiting altogether so the deadline is real even for an unkillable child.
+                    onAbort = () => {
+                        if (!child || reaped)
+                            return;
+                        killGroup(child, "SIGTERM");
+                        killTimer = setTimeout(() => {
+                            // `reaped` keeps a late timer from signalling a process group whose pid the
+                            // kernel may already have handed to somebody else.
+                            if (!child || reaped)
+                                return;
+                            killGroup(child, "SIGKILL");
+                            abandonTimer = setTimeout(abandon, REAP_GRACE_MS);
+                        }, killGraceMs);
+                    };
+                    run.signal.addEventListener("abort", onAbort, { once: true });
+                    try {
+                        if (run.signal.aborted)
+                            throw run.abortError();
+                        child = Bun.spawn(spec.command, {
+                            cwd: spec.cwd,
+                            env: spec.env ? { ...process.env, ...spec.env } : process.env,
+                            stdin: "ignore", stdout: "pipe", stderr: "pipe",
+                            detached: process.platform !== "win32",
+                        });
+                        trackChild(child);
+                        children.add(child);
+                        const exiting = child;
+                        void exiting.exited.then(() => {
+                            reaped = true;
+                            liveChildren.delete(exiting);
+                            children.delete(exiting);
+                        });
+                        const completed = Promise.all([
+                            readCapped(child.stdout, maxOutputBytes),
+                            readCapped(child.stderr, maxOutputBytes),
+                            child.exited,
+                        ]);
+                        const settledRun = await Promise.race([completed, abandoned]);
+                        if (settledRun === "abandoned") {
+                            throw run.signal.aborted
+                                ? run.abortError()
+                                : new OffloadError({ kind: "timeout", taskName, message: `${taskName} did not exit after SIGKILL` });
+                        }
+                        const [stdout, stderr, exitCode] = settledRun;
+                        if (run.signal.aborted)
+                            throw run.abortError();
+                        const okExitCodes = spec.okExitCodes ?? [0];
+                        if (okExitCodes !== "any" && !okExitCodes.includes(exitCode))
+                            throw new OffloadError({
+                                kind: "rejected", taskName, code: String(exitCode), message: `${taskName} exited ${exitCode}: ${stderr.text.trim() || stdout.text.trim()}`,
+                            });
+                        const result = { exitCode, stdout: stdout.text, stderr: stderr.text, truncated: stdout.truncated || stderr.truncated };
+                        finishLog(logger, "subprocess", taskName, labels, startedAt);
+                        await recordResult({ counter, taskName, backend: "subprocess", labels, sink, logger });
+                        publish({ ok: true, value: result });
+                    }
+                    catch (error) {
+                        const normalized = run.signal.aborted ? run.abortError() : normalizeError(taskName, error);
+                        finishLog(logger, "subprocess", taskName, labels, startedAt, normalized);
+                        await recordResult({ counter, taskName, backend: "subprocess", labels, error: normalized, sink, logger });
+                        publish({ ok: false, error: normalized });
+                    }
+                    finally {
+                        if (onAbort)
+                            run.signal.removeEventListener("abort", onAbort);
+                        run.cleanup();
+                    }
+                }
+                catch (error) {
+                    const normalized = normalizeError(taskName, error, "rejected");
+                    finishLog(logger, "subprocess", taskName, labels, performance.now(), normalized);
+                    await recordResult({ counter, taskName, backend: "subprocess", labels, error: normalized, sink, logger });
+                    publish({ ok: false, error: normalized });
+                }
+                finally {
+                    context?.cleanup();
+                    // Keep the slot until the child is actually reaped, so the concurrency cap and
+                    // `stats` stay true while a kill is in flight (#1809 P1-7). `abandoned` bounds
+                    // this: the SIGKILL escalation above always ends the wait.
+                    if (child)
+                        await Promise.race([child.exited, abandoned]);
+                    if (killTimer)
+                        clearTimeout(killTimer);
+                    if (abandonTimer)
+                        clearTimeout(abandonTimer);
+                    live.delete(entry);
+                }
+            });
+            void task.catch(() => undefined);
+            const result = await outcome;
+            if (!result.ok)
+                throw result.error;
+            return result.value;
+        },
+        drain: () => queue.onIdle(),
+        async destroy() {
+            destroyed = true;
+            const outstanding = [...live];
+            for (const entry of outstanding) {
+                entry.cancelIfQueued(destroyedError(entry.taskName));
+                entry.teardown.abort(new DOMException("Subprocess runner destroyed", "AbortError"));
+            }
+            for (const child of children)
+                killGroup(child, "SIGKILL");
+            await Promise.all([
+                ...outstanding.map((entry) => entry.settled),
+                ...[...children].map((child) => child.exited),
+            ]);
+        },
+    };
+}
+//# sourceMappingURL=subprocess-runner.js.map

package/node_modules/@humwick/offload/dist/subprocess-runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subprocess-runner.js","sourceRoot":"","sources":["../src/subprocess-runner.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,SAAS,CAAC;AAC7B,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,YAAY,EAAE,QAAQ,EAAmB,MAAM,eAAe,CAAC;AAC7F,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,eAAe,EAA8C,MAAM,YAAY,CAAC;AA0DtI,MAAM,qBAAqB,GAAG,KAAK,CAAC;AACpC,MAAM,wBAAwB,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;AACjD,8FAA8F;AAC9F,MAAM,aAAa,GAAG,KAAK,CAAC;AAE5B;;;;GAIG;AACH,MAAM,YAAY,GAAG,IAAI,GAAG,EAAS,CAAC;AACtC,IAAI,iBAAiB,GAAG,KAAK,CAAC;AAE9B,SAAS,SAAS,CAAC,KAAY,EAAE,MAAsB;IACrD,IAAI,CAAC;QACH,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO;YAAE,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;;YAC9D,KAAK,CAAC,IAAI,EAAE,CAAC;IACpB,CAAC;IAAC,MAAM,CAAC;QACP,IAAI,CAAC;YAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAAC,CAAC;QAAC,MAAM,CAAC,CAAC,+BAA+B,CAAC,CAAC;IACvE,CAAC;AACH,CAAC;AAED,SAAS,UAAU,CAAC,KAAY;IAC9B,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACxB,IAAI,iBAAiB;QAAE,OAAO;IAC9B,iBAAiB,GAAG,IAAI,CAAC;IACzB,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,GAAG,EAAE;QACtB,KAAK,MAAM,IAAI,IAAI,YAAY;YAAE,SAAS,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;IAC9D,CAAC,CAAC,CAAC;AACL,CAAC;AAED,wGAAwG;AACxG,KAAK,UAAU,UAAU,CAAC,MAAyC,EAAE,KAAa;IAChF,IAAI,CAAC,MAAM;QAAE,OAAO,EAAE,IAAI,EAAE,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;IACnD,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,EAAE,CAAC;IAClC,MAAM,MAAM,GAAiB,EAAE,CAAC;IAChC,IAAI,IAAI,GAAG,CAAC,CAAC;IACb,IAAI,SAAS,GAAG,KAAK,CAAC;IACtB,IAAI,CAAC;QACH,SAAS,CAAC;YACR,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;YAC5C,IAAI,IAAI;gBAAE,MAAM;YAChB,IAAI,CAAC,KAAK;gBAAE,SAAS;YACrB,MAAM,SAAS,GAAG,KAAK,GAAG,IAAI,CAAC;YAC/B,IAAI,SAAS,IAAI,CAAC,EAAE,CAAC;gBACnB,SAAS,GAAG,IAAI,CAAC;gBACjB,SAAS;YACX,CAAC;YACD,IAAI,KAAK,CAAC,UAAU,GAAG,SAAS,EAAE,CAAC;gBACjC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC;gBAC1C,IAAI,GAAG,KAAK,CAAC;gBACb,SAAS,GAAG,IAAI,CAAC;gBACjB,SAAS;YACX,CAAC;YACD,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACnB,IAAI,IAAI,KAAK,CAAC,UAAU,CAAC;QAC3B,CAAC;IACH,CAAC;YAAS,CAAC;QACT,MAAM,CAAC,WAAW,EAAE,CAAC;IACvB,CAAC;IACD,MAAM,MAAM,GAAG,IAAI,UAAU,CAAC,IAAI,CAAC,CAAC;IACpC,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;QAC1B,MAAM,IAAI,KAAK,CAAC,UAAU,CAAC;IAC7B,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,CAAC;AAC/D,CAAC;AAYD;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB,CAAC,OAAO,GAA4B,EAAE;IAC1E,MAAM,KAAK,GAAG,IAAI,MAAM,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,WAAW,IAAI,CAAC,EAAE,CAAC,CAAC;IACpE,MAAM,OAAO,GAAG,IAAI,aAAa,CAAC,OAAO,CAAC,mBAAmB,EAAE,OAAO,CAAC,wBAAwB,CAAC,CAAC;IACjG,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,qBAAqB,CAAC;IACjE,MAAM,cAAc,GAAG,OAAO,CAAC,cAAc,IAAI,wBAAwB,CAAC;IAC1E,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,WAAW,GAAG,CAAC;QAAE,MAAM,IAAI,UAAU,CAAC,kDAAkD,CAAC,CAAC;IAC/H,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,cAAc,CAAC,IAAI,cAAc,GAAG,CAAC;QAAE,MAAM,IAAI,UAAU,CAAC,2CAA2C,CAAC,CAAC;IACnI,MAAM,IAAI,GAAG,IAAI,GAAG,EAAW,CAAC;IAChC,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAS,CAAC;IAClC,IAAI,SAAS,GAAG,KAAK,CAAC;IAEtB,MAAM,YAAY,GAAG,CAAC,QAAgB,EAAE,KAAe,EAAgB,EAAE,CACvE,IAAI,YAAY,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,QAAQ,cAAc,EAAE,KAAK,EAAE,CAAC,CAAC;IAC7F,MAAM,cAAc,GAAG,CAAC,QAAgB,EAAgB,EAAE,CACxD,IAAI,YAAY,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,QAAQ,6CAA6C,EAAE,CAAC,CAAC;IAErH,OAAO;QACL,SAAS,EAAE,IAAI;QACf,IAAI,KAAK,KAAK,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;QACrE,KAAK,CAAC,GAAG,CAAC,QAAgB,EAAE,IAAoB,EAAE,GAAqB;YACrE,MAAM,MAAM,GAAG,GAAG,EAAE,MAAM,IAAI,EAAE,CAAC;YACjC,MAAM,MAAM,GAAG,GAAG,EAAE,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC;YAC7C,MAAM,IAAI,GAAG,GAAG,EAAE,UAAU,IAAI,OAAO,CAAC,UAAU,CAAC;YACnD,MAAM,eAAe,GAAG,KAAK,EAAE,KAAmB,EAAkB,EAAE;gBACpE,sFAAsF;gBACtF,qDAAqD;gBACrD,SAAS,CAAC,MAAM,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,CAAC,GAAG,EAAE,EAAE,KAAK,CAAC,CAAC;gBAC5E,MAAM,YAAY,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;gBAC9F,MAAM,KAAK,CAAC;YACd,CAAC,CAAC;YACF,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM;gBAAE,OAAO,eAAe,CAAC,IAAI,YAAY,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,OAAO,EAAE,sCAAsC,EAAE,CAAC,CAAC,CAAC;YACpJ,IAAI,SAAS;gBAAE,OAAO,eAAe,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC,CAAC;YAChE,IAAI,GAAG,EAAE,MAAM,EAAE,OAAO;gBAAE,OAAO,eAAe,CAAC,YAAY,CAAC,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;YAC5F,IAAI,CAAC;gBACH,eAAe,CAAC,GAAG,EAAE,SAAS,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAAC;YAC9D,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,OAAO,eAAe,CAAC,cAAc,CAAC,QAAQ,EAAE,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC;YACtE,CAAC;YAED,IAAI,OAAoC,CAAC;YACzC,IAAI,SAAS,GAAG,KAAK,CAAC;YACtB,MAAM,OAAO,GAAG,IAAI,OAAO,CAAU,CAAC,OAAO,EAAE,EAAE;gBAC/C,OAAO,GAAG,CAAC,KAAK,EAAE,EAAE,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC;oBAAC,SAAS,GAAG,IAAI,CAAC;oBAAC,OAAO,CAAC,KAAK,CAAC,CAAC;gBAAC,CAAC,CAAC,CAAC,CAAC;YACjF,CAAC,CAAC,CAAC;YACH,IAAI,OAAO,GAAG,KAAK,CAAC;YACpB,IAAI,SAAS,GAAG,KAAK,CAAC;YACtB,MAAM,KAAK,GAAY;gBACrB,QAAQ;gBACR,QAAQ,EAAE,IAAI,eAAe,EAAE;gBAC/B,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC;gBACtC,cAAc,EAAE,CAAC,KAAK,EAAE,EAAE;oBACxB,IAAI,OAAO,IAAI,SAAS;wBAAE,OAAO;oBACjC,SAAS,GAAG,IAAI,CAAC;oBACjB,iFAAiF;oBACjF,kFAAkF;oBAClF,gFAAgF;oBAChF,SAAS,CAAC,MAAM,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,CAAC,GAAG,EAAE,EAAE,KAAK,CAAC,CAAC;oBAC5E,OAAO,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;gBAChC,CAAC;aACF,CAAC;YACF,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;YAEhB,qFAAqF;YACrF,oEAAoE;YACpE,MAAM,MAAM,GAAG,GAAG,EAAE,MAAM,CAAC;YAC3B,MAAM,aAAa,GAAG,MAAM,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,cAAc,CAAC,YAAY,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;YAC7G,IAAI,MAAM,IAAI,aAAa;gBAAE,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,aAAa,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YAE7F,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,KAAK,IAAI,EAAE;gBAChC,IAAI,MAAM,IAAI,aAAa;oBAAE,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC;gBAChF,IAAI,OAA+B,CAAC;gBACpC,IAAI,KAAwB,CAAC;gBAC7B,IAAI,OAAiC,CAAC;gBACtC,IAAI,SAAoD,CAAC;gBACzD,IAAI,YAAuD,CAAC;gBAC5D,IAAI,MAAM,GAAG,KAAK,CAAC;gBACnB,IAAI,OAAoB,CAAC;gBACzB,MAAM,SAAS,GAAG,IAAI,OAAO,CAAc,CAAC,OAAO,EAAE,EAAE,GAAG,OAAO,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;gBACnG,IAAI,CAAC;oBACH,IAAI,SAAS;wBAAE,OAAO;oBACtB,IAAI,SAAS,IAAI,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;wBAC/C,MAAM,KAAK,GAAG,cAAc,CAAC,QAAQ,CAAC,CAAC;wBACvC,SAAS,CAAC,MAAM,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,CAAC,GAAG,EAAE,EAAE,KAAK,CAAC,CAAC;wBAC5E,OAAO,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;wBAC9B,OAAO;oBACT,CAAC;oBACD,OAAO,GAAG,IAAI,CAAC;oBACf,OAAO,GAAG,QAAQ,CAAC,QAAQ,EAAE,GAAG,EAAE,OAAO,EAAE,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;oBAClE,MAAM,GAAG,GAAG,OAAO,CAAC;oBACpB,MAAM,SAAS,GAAG,QAAQ,CAAC,MAAM,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;oBACnE,oFAAoF;oBACpF,8EAA8E;oBAC9E,2EAA2E;oBAC3E,OAAO,GAAG,GAAG,EAAE;wBACb,IAAI,CAAC,KAAK,IAAI,MAAM;4BAAE,OAAO;wBAC7B,SAAS,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;wBAC5B,SAAS,GAAG,UAAU,CAAC,GAAG,EAAE;4BAC1B,4EAA4E;4BAC5E,mDAAmD;4BACnD,IAAI,CAAC,KAAK,IAAI,MAAM;gCAAE,OAAO;4BAC7B,SAAS,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;4BAC5B,YAAY,GAAG,UAAU,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC;wBACpD,CAAC,EAAE,WAAW,CAAC,CAAC;oBAClB,CAAC,CAAC;oBACF,GAAG,CAAC,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;oBAC9D,IAAI,CAAC;wBACH,IAAI,GAAG,CAAC,MAAM,CAAC,OAAO;4BAAE,MAAM,GAAG,CAAC,UAAU,EAAE,CAAC;wBAC/C,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE;4BAC9B,GAAG,EAAE,IAAI,CAAC,GAAG;4BACb,GAAG,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG;4BAC7D,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM;4BAC/C,QAAQ,EAAE,OAAO,CAAC,QAAQ,KAAK,OAAO;yBACvC,CAAC,CAAC;wBACH,UAAU,CAAC,KAAK,CAAC,CAAC;wBAClB,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;wBACpB,MAAM,OAAO,GAAG,KAAK,CAAC;wBACtB,KAAK,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE;4BAC5B,MAAM,GAAG,IAAI,CAAC;4BACd,YAAY,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;4BAC7B,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;wBAC3B,CAAC,CAAC,CAAC;wBACH,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC;4BAC5B,UAAU,CAAC,KAAK,CAAC,MAA2C,EAAE,cAAc,CAAC;4BAC7E,UAAU,CAAC,KAAK,CAAC,MAA2C,EAAE,cAAc,CAAC;4BAC7E,KAAK,CAAC,MAAM;yBACb,CAAC,CAAC;wBACH,MAAM,UAAU,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC;wBAC9D,IAAI,UAAU,KAAK,WAAW,EAAE,CAAC;4BAC/B,MAAM,GAAG,CAAC,MAAM,CAAC,OAAO;gCACtB,CAAC,CAAC,GAAG,CAAC,UAAU,EAAE;gCAClB,CAAC,CAAC,IAAI,YAAY,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,OAAO,EAAE,GAAG,QAAQ,6BAA6B,EAAE,CAAC,CAAC;wBACzG,CAAC;wBACD,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,CAAC,GAAG,UAAU,CAAC;wBAC9C,IAAI,GAAG,CAAC,MAAM,CAAC,OAAO;4BAAE,MAAM,GAAG,CAAC,UAAU,EAAE,CAAC;wBAC/C,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,IAAI,CAAC,CAAC,CAAC,CAAC;wBAC5C,IAAI,WAAW,KAAK,KAAK,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,QAAQ,CAAC;4BAAE,MAAM,IAAI,YAAY,CAAC;gCACnF,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,CAAC,QAAQ,CAAC,EAAE,OAAO,EAAE,GAAG,QAAQ,WAAW,QAAQ,KAAK,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE;6BAC3I,CAAC,CAAC;wBACH,MAAM,MAAM,GAAqB,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,IAAI,EAAE,SAAS,EAAE,MAAM,CAAC,SAAS,IAAI,MAAM,CAAC,SAAS,EAAE,CAAC;wBACzI,SAAS,CAAC,MAAM,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,CAAC,CAAC;wBAC7D,MAAM,YAAY,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;wBACvF,OAAO,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC;oBACvC,CAAC;oBAAC,OAAO,KAAK,EAAE,CAAC;wBACf,MAAM,UAAU,GAAG,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,cAAc,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;wBAC3F,SAAS,CAAC,MAAM,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC;wBACzE,MAAM,YAAY,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;wBAC1G,OAAO,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC,CAAC;oBAC5C,CAAC;4BAAS,CAAC;wBACT,IAAI,OAAO;4BAAE,GAAG,CAAC,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;wBAC9D,GAAG,CAAC,OAAO,EAAE,CAAC;oBAChB,CAAC;gBACH,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBACf,MAAM,UAAU,GAAG,cAAc,CAAC,QAAQ,EAAE,KAAK,EAAE,UAAU,CAAC,CAAC;oBAC/D,SAAS,CAAC,MAAM,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,CAAC,GAAG,EAAE,EAAE,UAAU,CAAC,CAAC;oBACjF,MAAM,YAAY,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;oBAC1G,OAAO,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC,CAAC;gBAC5C,CAAC;wBAAS,CAAC;oBACT,OAAO,EAAE,OAAO,EAAE,CAAC;oBACnB,+EAA+E;oBAC/E,+EAA+E;oBAC/E,2DAA2D;oBAC3D,IAAI,KAAK;wBAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC;oBACzD,IAAI,SAAS;wBAAE,YAAY,CAAC,SAAS,CAAC,CAAC;oBACvC,IAAI,YAAY;wBAAE,YAAY,CAAC,YAAY,CAAC,CAAC;oBAC7C,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;gBACrB,CAAC;YACH,CAAC,CAAC,CAAC;YACH,KAAK,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;YAEjC,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC;YAC7B,IAAI,CAAC,MAAM,CAAC,EAAE;gBAAE,MAAM,MAAM,CAAC,KAAK,CAAC;YACnC,OAAO,MAAM,CAAC,KAAK,CAAC;QACtB,CAAC;QACD,KAAK,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,MAAM,EAAE;QAC3B,KAAK,CAAC,OAAO;YACX,SAAS,GAAG,IAAI,CAAC;YACjB,MAAM,WAAW,GAAG,CAAC,GAAG,IAAI,CAAC,CAAC;YAC9B,KAAK,MAAM,KAAK,IAAI,WAAW,EAAE,CAAC;gBAChC,KAAK,CAAC,cAAc,CAAC,cAAc,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC;gBACrD,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,YAAY,CAAC,6BAA6B,EAAE,YAAY,CAAC,CAAC,CAAC;YACtF,CAAC;YACD,KAAK,MAAM,KAAK,IAAI,QAAQ;gBAAE,SAAS,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;YAC1D,MAAM,OAAO,CAAC,GAAG,CAAC;gBAChB,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC;gBAC5C,GAAG,CAAC,GAAG,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC;aAC9C,CAAC,CAAC;QACL,CAAC;KACF,CAAC;AACJ,CAAC"}

package/node_modules/@humwick/offload/dist/types.d.ts

@@ -0,0 +1,111 @@
+export type OffloadErrorKind = "timeout" | "aborted" | "worker-error" | "worker-exit" | "rejected";
+/** A stable, backend-independent failure surface for callers and escalation sinks. */
+export declare class OffloadError extends Error {
+    readonly kind: OffloadErrorKind;
+    readonly code?: string;
+    readonly taskName: string;
+    constructor(options: {
+        kind: OffloadErrorKind;
+        taskName: string;
+        code?: string;
+        message?: string;
+        cause?: unknown;
+    });
+}
+export type OffloadLogFields = Record<string, unknown>;
+/** Deliberately structural: server, runner and orchestrator can pass their existing logger adapters. */
+export interface OffloadLogger {
+    debug?(message: string, fields?: OffloadLogFields): void;
+    info?(message: string, fields?: OffloadLogFields): void;
+    warn?(message: string, fields?: OffloadLogFields): void;
+    error?(message: string, fields?: OffloadLogFields): void;
+}
+export interface EscalationEvent {
+    taskName: string;
+    backend: "worker" | "async" | "subprocess";
+    error: OffloadError;
+    strikes: number;
+    labels: Record<string, string>;
+}
+export type EscalationSink = (event: EscalationEvent) => void | Promise<void>;
+/** The common per-run contract. No backend-specific options leak into this envelope. */
+export interface OffloadEnvelope {
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    logger?: OffloadLogger;
+    labels?: Record<string, string>;
+    onEscalate?: EscalationSink;
+    /**
+     * Opt in to automatic re-dispatch after an ambiguous worker death (WorkerPool only; the async
+     * and subprocess runners never re-run). Default is AT-MOST-ONCE: if the worker dies with this
+     * job in flight, the job is rejected (`worker-exit`) and never re-run — because a re-run would
+     * repeat any side effect the job already performed (an HTTP POST, a mutation). Set this ONLY
+     * when the job is idempotent/retry-safe (pure compute), in which case a worker death is
+     * absorbed by re-dispatching to a fresh worker up to a bounded number of times (#1822 HIGH-1).
+     * Command/handler offload (side-effecting) must leave this unset.
+     */
+    retrySafe?: boolean;
+}
+export interface OffloadDefaults {
+    defaultTimeoutMs?: number;
+    logger?: OffloadLogger;
+    onEscalate?: EscalationSink;
+    /** Consecutive failed runs for a task before its injected sink fires. Defaults to 3. */
+    escalationThreshold?: number;
+    /**
+     * Size, in failure-attempts, of the sliding window the strike counter escalates over: a task
+     * escalates when it accumulates `escalationThreshold` failures within this many consecutive
+     * failure-attempts (counted across ALL tasks). A task with no failure inside the window is
+     * forgotten, which is ALSO what bounds memory — the counter holds at most this many failure
+     * events, so at most this many distinct names, at once (#1822 items 1 and 4). Adoption keys
+     * runs by dynamic names (workspace/agent ids); the window is what keeps that from growing
+     * without bound. Defaults to 4096.
+     */
+    escalationWindowAttempts?: number;
+}
+/**
+ * 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 declare class StrikeCounter {
+    #private;
+    readonly threshold: number;
+    readonly window: number;
+    constructor(threshold?: number, escalationWindowAttempts?: number);
+    /** Distinct task names with a failure still inside the window. Bounded by `window`. */
+    get size(): number;
+    fail(taskName: string): number;
+    /** Latch an escalation so it fires once until the task re-arms (succeeds or ages out). */
+    trip(taskName: string): void;
+    succeed(taskName: string): void;
+}
+export declare function normalizeError(taskName: string, error: unknown, fallback?: OffloadErrorKind): OffloadError;
+export declare function log(logger: OffloadLogger | undefined, level: keyof OffloadLogger, message: string, fields: OffloadLogFields): void;
+export declare function validateTimeout(timeoutMs: number | undefined): number | undefined;
+//# sourceMappingURL=types.d.ts.map

package/node_modules/@humwick/offload/dist/types.d.ts.map

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