sealkeep 0.9.0 → 0.11.0

package/dist/src/background-bandwidth.d.ts

@@ -0,0 +1,46 @@
+import { type ByteStream } from "./byte-stream.js";
+import { type DaemonProcessIdentityLookup, type DaemonWorkerLease } from "./daemon-lease.js";
+type Clock = {
+    now?: () => number;
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+};
+export type BackgroundBandwidthReservationOptions = {
+    signal?: AbortSignal;
+    burstBytes?: number;
+    /** A busy governor fails closed after this bound; it never steals a stale-looking lock. */
+    lockWaitMs?: number;
+    /** Test/embedding seam. Production uses the kernel-backed daemon process generation. */
+    processIdentityLookup?: DaemonProcessIdentityLookup;
+    identityLookupTimeoutMs?: number;
+} & Clock;
+export type BackgroundBandwidthStartupRecoveryOptions = {
+    /** In-lifetime supervised cleanup must touch only the just-exited child. */
+    expectedOwner?: {
+        pid: number;
+        processIdentity: string;
+    };
+    /** Test/embedding seam. Production uses the kernel-backed daemon process generation. */
+    processIdentityLookup?: DaemonProcessIdentityLookup;
+    identityLookupTimeoutMs?: number;
+    /** Adversarial ordering seam: invoked after stale ownership is proved, before the exact final check. */
+    beforeFinalLockCheck?: () => void | Promise<void>;
+};
+/** Cross-process reservation shared by the daemon and its index child. */
+export declare function reserveBackgroundBytes(dataDir: string, bytes: number, bytesPerSecond: number, options?: BackgroundBandwidthReservationOptions): Promise<number>;
+/**
+ * Recovers a crash-left bandwidth mutex before a daemon starts any lane.
+ *
+ * This is deliberately unavailable to ordinary reservations. The daemon's
+ * process-generation lease supplies the mutual exclusion that a POSIX pathname
+ * alone cannot: once stale ownership is proved, no legitimate worker may
+ * recreate the fixed lock name between the final inode/content check and
+ * unlink. Unknown, live, malformed, or concurrently replaced locks fail closed.
+ */
+export declare function recoverBackgroundBandwidthLockAtDaemonStartup(dataDir: string, daemonLease: Pick<DaemonWorkerLease, "assertOwned">, options?: BackgroundBandwidthStartupRecoveryOptions): Promise<"absent" | "recovered" | "not-owned">;
+/** One aggregate background transfer lane for a vault, even across processes. */
+export declare function paceBackgroundByteStream(dataDir: string, chunks: ByteStream, bytesPerSecond: number, options?: {
+    signal?: AbortSignal;
+    burstBytes?: number;
+    onProgress?: (bytes: number) => void;
+} & Clock): ByteStream;
+export {};

package/dist/src/background-bandwidth.js

@@ -0,0 +1,301 @@
+import { randomUUID } from "node:crypto";
+import { constants as fsConstants } from "node:fs";
+import { link, lstat, mkdir, open, readFile, rename, rm, unlink } from "node:fs/promises";
+import { join } from "node:path";
+import { ARCHIVE_IO_CHUNK_BYTES, paceByteStream } from "./byte-stream.js";
+import { daemonProcessIdentity, classifyDaemonProcessGeneration, } from "./daemon-lease.js";
+const DEFAULT_LOCK_WAIT_MS = 2_000;
+const DEFAULT_IDENTITY_LOOKUP_TIMEOUT_MS = 1_000;
+function errorCode(error) {
+    return typeof error === "object" && error !== null && "code" in error
+        ? String(error.code)
+        : undefined;
+}
+function lockFingerprint(details) {
+    return {
+        dev: String(details.dev),
+        ino: String(details.ino),
+        bytes: String(details.size),
+        links: String(details.nlink),
+        mtimeNs: "mtimeNs" in details ? String(details.mtimeNs) : String(details.mtimeMs),
+        ctimeNs: "ctimeNs" in details ? String(details.ctimeNs) : String(details.ctimeMs),
+    };
+}
+function sameLock(left, right) {
+    return left.raw === right.raw
+        && left.fingerprint.dev === right.fingerprint.dev
+        && left.fingerprint.ino === right.fingerprint.ino
+        && left.fingerprint.bytes === right.fingerprint.bytes
+        && left.fingerprint.links === right.fingerprint.links
+        && left.fingerprint.mtimeNs === right.fingerprint.mtimeNs
+        && left.fingerprint.ctimeNs === right.fingerprint.ctimeNs;
+}
+function parseLockOwner(raw) {
+    try {
+        const value = JSON.parse(raw);
+        if (value.version !== 1
+            || typeof value.token !== "string" || !/^[A-Za-z0-9_-]{16,128}$/.test(value.token)
+            || !Number.isSafeInteger(value.pid) || (value.pid ?? 0) <= 0
+            || typeof value.processIdentity !== "string" || value.processIdentity.length < 1 || value.processIdentity.length > 512
+            || !Number.isFinite(value.createdAtMs))
+            return null;
+        return value;
+    }
+    catch {
+        return null;
+    }
+}
+async function observeBandwidthLock(path) {
+    const noFollow = typeof fsConstants.O_NOFOLLOW === "number" ? fsConstants.O_NOFOLLOW : 0;
+    let handle;
+    try {
+        handle = await open(path, fsConstants.O_RDONLY | noFollow);
+        const [details, pathDetails, raw] = await Promise.all([
+            handle.stat({ bigint: true }),
+            lstat(path, { bigint: true }),
+            handle.readFile("utf8"),
+        ]);
+        if (!details.isFile() || !pathDetails.isFile()
+            || details.dev !== pathDetails.dev || details.ino !== pathDetails.ino) {
+            throw new Error("Background bandwidth lock is not one exact regular file");
+        }
+        const owner = parseLockOwner(raw);
+        if (!owner)
+            throw new Error("Background bandwidth lock is malformed; refusing unsafe automatic recovery");
+        return { raw, owner, fingerprint: lockFingerprint(details) };
+    }
+    catch (error) {
+        if (errorCode(error) === "ENOENT")
+            return null;
+        throw error;
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+    }
+}
+async function boundedIdentityLookup(lookup, pid, timeoutMs) {
+    let timer;
+    const deadline = new Promise((resolve) => {
+        timer = setTimeout(() => resolve({ state: "unknown" }), Math.max(1, timeoutMs));
+    });
+    try {
+        const result = await Promise.race([Promise.resolve().then(() => lookup(pid)), deadline]);
+        if (result.state === "dead" || result.state === "unknown")
+            return result;
+        if (result.state === "identified" && typeof result.identity === "string"
+            && result.identity.length > 0 && result.identity.length <= 512)
+            return result;
+        return { state: "unknown" };
+    }
+    catch {
+        return { state: "unknown" };
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+async function publishBandwidthLock(runtime, lockPath, owner) {
+    const temporary = join(runtime, `.background-bandwidth.${owner.token}.${randomUUID()}.pending`);
+    const raw = `${JSON.stringify(owner)}\n`;
+    let handle;
+    try {
+        handle = await open(temporary, "wx", 0o600);
+        await handle.writeFile(raw, "utf8");
+        await handle.sync();
+        await handle.close();
+        handle = undefined;
+        try {
+            // The public lock name appears only after complete, fsynced owner data
+            // exists. A crash during publication therefore leaves an ignorable temp,
+            // never a malformed permanent lock.
+            await link(temporary, lockPath);
+        }
+        catch (error) {
+            if (errorCode(error) === "EEXIST")
+                return null;
+            throw error;
+        }
+        // Drop the publication name before fingerprinting ownership. Removing a
+        // hard link changes nlink/ctime; recording the two-link intermediate state
+        // would make the owner's later exact release reject its own lock.
+        await rm(temporary, { force: true });
+        const observed = await observeBandwidthLock(lockPath);
+        if (!observed || observed.raw !== raw) {
+            throw new Error("Background bandwidth lock publication could not be verified");
+        }
+        return observed;
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+        await rm(temporary, { force: true }).catch(() => undefined);
+    }
+}
+async function releaseBandwidthLock(path, owned) {
+    const current = await observeBandwidthLock(path);
+    if (!current || !sameLock(owned, current)) {
+        throw new Error("Background bandwidth lock ownership changed before release");
+    }
+    // Per-reservation code never removes or replaces an existing lock. Therefore
+    // legitimate contenders cannot change this name between the exact check and
+    // unlink; supervised cleanup runs only before a daemon starts any workers.
+    await unlink(path);
+}
+async function syncDirectory(path) {
+    let handle;
+    try {
+        handle = await open(path, "r");
+        await handle.sync();
+    }
+    catch (error) {
+        if (process.platform !== "win32")
+            throw error;
+    }
+    finally {
+        await handle?.close().catch(() => undefined);
+    }
+}
+const sleepAbortable = async (ms, signal) => {
+    signal?.throwIfAborted();
+    await new Promise((resolve, reject) => {
+        let timer;
+        const aborted = () => {
+            if (timer)
+                clearTimeout(timer);
+            signal?.removeEventListener("abort", aborted);
+            reject(signal?.reason instanceof Error ? signal.reason : new DOMException("Background transfer cancelled", "AbortError"));
+        };
+        timer = setTimeout(() => { signal?.removeEventListener("abort", aborted); resolve(); }, ms);
+        signal?.addEventListener("abort", aborted, { once: true });
+    });
+};
+/** Cross-process reservation shared by the daemon and its index child. */
+export async function reserveBackgroundBytes(dataDir, bytes, bytesPerSecond, options = {}) {
+    if (!Number.isFinite(bytesPerSecond) || bytesPerSecond <= 0)
+        throw new Error("Background byte rate must be positive");
+    if (!Number.isFinite(bytes) || bytes < 0)
+        throw new Error("Background byte reservation must be non-negative");
+    const now = options.now ?? Date.now;
+    const sleep = options.sleep ?? sleepAbortable;
+    const runtime = join(dataDir, "runtime");
+    const statePath = join(runtime, "background-bandwidth.json");
+    const lockPath = join(runtime, "background-bandwidth.lock");
+    await mkdir(runtime, { recursive: true, mode: 0o700 });
+    const lookup = options.processIdentityLookup ?? daemonProcessIdentity;
+    const identity = await boundedIdentityLookup(lookup, process.pid, options.identityLookupTimeoutMs ?? DEFAULT_IDENTITY_LOOKUP_TIMEOUT_MS);
+    if (identity.state !== "identified") {
+        throw new Error("Sealkeep could not identify this process, so background bandwidth reservation failed closed");
+    }
+    const owner = {
+        version: 1,
+        token: randomUUID(),
+        pid: process.pid,
+        processIdentity: identity.identity,
+        createdAtMs: Date.now(),
+    };
+    const deadline = performance.now() + Math.max(0, options.lockWaitMs ?? DEFAULT_LOCK_WAIT_MS);
+    let lock = null;
+    for (;;) {
+        options.signal?.throwIfAborted();
+        lock = await publishBandwidthLock(runtime, lockPath, owner);
+        if (lock)
+            break;
+        const remaining = deadline - performance.now();
+        if (remaining <= 0) {
+            throw new Error("Background bandwidth governor is busy; refusing to bypass its shared transfer limit");
+        }
+        await sleep(Math.min(10, remaining), options.signal);
+    }
+    try {
+        const current = await readFile(statePath, "utf8")
+            .then((raw) => JSON.parse(raw))
+            .catch(() => ({}));
+        const observed = now();
+        const burst = Math.max(0, options.burstBytes ?? ARCHIVE_IO_CHUNK_BYTES);
+        const previousAt = Number.isFinite(current.at) ? Number(current.at) : observed;
+        const previousTokens = Number.isFinite(current.tokens) ? Math.max(0, Number(current.tokens)) : burst;
+        const baseAt = Math.max(observed, previousAt);
+        const available = previousAt <= observed
+            ? Math.min(burst, previousTokens + (observed - previousAt) / 1_000 * bytesPerSecond)
+            : 0;
+        const deficit = Math.max(0, bytes - available);
+        const reservedAt = baseAt + deficit / bytesPerSecond * 1_000;
+        const tokens = deficit > 0 ? 0 : available - bytes;
+        const temp = `${statePath}.${process.pid}.${randomUUID()}.tmp`;
+        const state = await open(temp, "wx", 0o600);
+        try {
+            await state.writeFile(JSON.stringify({ at: reservedAt, tokens }));
+            await state.sync();
+        }
+        finally {
+            await state.close();
+        }
+        await rename(temp, statePath);
+        return Math.max(0, reservedAt - observed);
+    }
+    finally {
+        await releaseBandwidthLock(lockPath, lock);
+    }
+}
+/**
+ * Recovers a crash-left bandwidth mutex before a daemon starts any lane.
+ *
+ * This is deliberately unavailable to ordinary reservations. The daemon's
+ * process-generation lease supplies the mutual exclusion that a POSIX pathname
+ * alone cannot: once stale ownership is proved, no legitimate worker may
+ * recreate the fixed lock name between the final inode/content check and
+ * unlink. Unknown, live, malformed, or concurrently replaced locks fail closed.
+ */
+export async function recoverBackgroundBandwidthLockAtDaemonStartup(dataDir, daemonLease, options = {}) {
+    await daemonLease.assertOwned();
+    const runtime = join(dataDir, "runtime");
+    const lockPath = join(runtime, "background-bandwidth.lock");
+    const observed = await observeBandwidthLock(lockPath);
+    if (!observed)
+        return "absent";
+    if (options.expectedOwner && (observed.owner.pid !== options.expectedOwner.pid
+        || observed.owner.processIdentity !== options.expectedOwner.processIdentity))
+        return "not-owned";
+    const owner = await boundedIdentityLookup(options.processIdentityLookup ?? daemonProcessIdentity, observed.owner.pid, options.identityLookupTimeoutMs ?? DEFAULT_IDENTITY_LOOKUP_TIMEOUT_MS);
+    const generation = classifyDaemonProcessGeneration(owner, observed.owner.processIdentity);
+    if (generation === "unknown") {
+        throw new Error("Background bandwidth lock owner could not be verified; daemon startup failed closed");
+    }
+    if (generation === "current") {
+        throw new Error("A live background transfer still owns the bandwidth governor; daemon startup failed closed");
+    }
+    await options.beforeFinalLockCheck?.();
+    await daemonLease.assertOwned();
+    const current = await observeBandwidthLock(lockPath);
+    if (!current || !sameLock(observed, current)) {
+        throw new Error("Background bandwidth lock changed during supervised recovery; it was left intact");
+    }
+    await unlink(lockPath);
+    await syncDirectory(runtime);
+    return "recovered";
+}
+/** One aggregate background transfer lane for a vault, even across processes. */
+export function paceBackgroundByteStream(dataDir, chunks, bytesPerSecond, options = {}) {
+    // Deterministic transport tests inject their own clock. Production uses the
+    // durable cross-process bucket above.
+    const paced = options.now || options.sleep
+        ? paceByteStream(chunks, bytesPerSecond, options)
+        : {
+            async *[Symbol.asyncIterator]() {
+                for await (const chunk of chunks) {
+                    const delay = await reserveBackgroundBytes(dataDir, chunk.length, bytesPerSecond, options);
+                    if (delay > 0)
+                        await sleepAbortable(delay, options.signal);
+                    yield chunk;
+                }
+            },
+        };
+    return {
+        async *[Symbol.asyncIterator]() {
+            for await (const chunk of paced) {
+                options.onProgress?.(chunk.length);
+                yield chunk;
+            }
+        },
+    };
+}

package/dist/src/background-cpu.d.ts

@@ -0,0 +1,82 @@
+/** Pure duty-cycle calculation shared by every low-priority CPU lane. */
+export declare function backgroundCpuDelayMs(cpuMs: number, wallMs: number, target: number, maximumMs?: number): number;
+export declare const BACKGROUND_CPU_TOTAL_TARGET = 0.3;
+/** Only accepts the already-owned ChildProcess handle, never an arbitrary PID.
+ * Policy refusal is not proof of exit; callers retain their close/barrier fence. */
+export declare function signalOwnedBackgroundProcess(child: {
+    kill(signal: NodeJS.Signals): boolean;
+}, signal: NodeJS.Signals): boolean;
+/** These workers own no stdout/stderr pipe (only ignore/inherit plus IPC).
+ * A denied kill can prevent Node's later `close` bookkeeping even after the
+ * exact child emits `exit`. Either event proves this captured child ended;
+ * callers still perform their generation-dead barrier retirement. */
+export declare function onOwnedBackgroundProcessExit(child: Pick<ChildProcess, "once">, listener: (code: number | null, signal: NodeJS.Signals | null) => void): void;
+/** One share is reserved for the responsive parent process's cooperative
+ * sealing/retention work. Child shares are released only when governing stops.
+ * This intentionally leaves some capacity unused when the parent is idle. */
+export declare function createBackgroundCpuBudget(totalTarget?: number): {
+    parentTarget: (requested: number) => number;
+    register(): {
+        target: (requested: number) => number;
+        release(): void;
+    };
+};
+export type BackgroundCpuBudget = ReturnType<typeof createBackgroundCpuBudget>;
+/** Shared by all background work hosted by this daemon process. Never pauses
+ * the daemon itself, so heartbeat, cancellation and hook I/O remain runnable. */
+export declare const backgroundDaemonCpuBudget: {
+    parentTarget: (requested: number) => number;
+    register(): {
+        target: (requested: number) => number;
+        release(): void;
+    };
+};
+/**
+ * Creates one cooperative CPU lane. Each checkpoint accounts only for the work
+ * since the previous checkpoint, so slow network I/O cannot build up a credit
+ * that later permits a long compression burst at full core speed.
+ */
+export declare function createBackgroundCpuYield(options: {
+    target: number;
+    signal?: AbortSignal;
+    cpuUsage?: typeof process.cpuUsage;
+    now?: () => number;
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+    maximumSleepMs?: number;
+    /** Owned children already have the parent governor: they explicitly opt out
+     * of this process-local parent accounting instead of paying twice. */
+    budget?: BackgroundCpuBudget | null;
+}): () => Promise<void>;
+export type BackgroundProcessCpuGovernor = {
+    /** Stop governing and make sure the owned process is runnable again. */
+    stop(): void;
+};
+/**
+ * Enforces a short wall-clock duty cycle from a process other than the worker.
+ *
+ * Cooperative checkpoints can account for JavaScript, compression and crypto,
+ * but they cannot interrupt a stop-the-world collection: the event loop that
+ * would choose to sleep is the thing being collected. A historical worker is
+ * already an owned child, so its parent can impose the missing hard boundary
+ * with 30 ms runnable / 70 ms paused windows on POSIX. This bounds even native
+ * V8 work; Windows retains the cooperative controller (and deliberately does
+ * not receive Unix signals).
+ */
+export declare function startBackgroundProcessCpuGovernor(options: {
+    target: number;
+    /** Must identify only the caller's owned child process. */
+    signal: (signal: NodeJS.Signals) => boolean;
+    platform?: NodeJS.Platform;
+    periodMs?: number;
+    setTimer?: (callback: () => void, ms: number) => NodeJS.Timeout;
+    clearTimer?: (timer: NodeJS.Timeout) => void;
+    /** Explicit aggregate allocation; standalone governor diagnostics omit it. */
+    budget?: BackgroundCpuBudget;
+    /** Owning workers probe both controls before sending any secret/work IPC. */
+    verifySignals?: boolean;
+    /** A lost governor is a failed pass, never permission to run at full speed. */
+    onFailure?: (error: Error & {
+        code: string;
+    }) => void;
+}): BackgroundProcessCpuGovernor;
+import type { ChildProcess } from "node:child_process";

package/dist/src/background-cpu.js

@@ -0,0 +1,212 @@
+/** Pure duty-cycle calculation shared by every low-priority CPU lane. */
+export function backgroundCpuDelayMs(cpuMs, wallMs, target, maximumMs = 1_000) {
+    if (!Number.isFinite(cpuMs) || cpuMs <= 0 || !Number.isFinite(wallMs) || wallMs <= 0)
+        return 0;
+    if (!Number.isFinite(target) || target <= 0 || target > 1)
+        throw new Error("Background CPU target must be between 0 and 1");
+    const delay = cpuMs / target - wallMs;
+    return Math.max(0, Math.min(maximumMs, Math.ceil(delay)));
+}
+export const BACKGROUND_CPU_TOTAL_TARGET = 0.30;
+/** Only accepts the already-owned ChildProcess handle, never an arbitrary PID.
+ * Policy refusal is not proof of exit; callers retain their close/barrier fence. */
+export function signalOwnedBackgroundProcess(child, signal) {
+    try {
+        return child.kill(signal);
+    }
+    catch {
+        return false;
+    }
+}
+/** These workers own no stdout/stderr pipe (only ignore/inherit plus IPC).
+ * A denied kill can prevent Node's later `close` bookkeeping even after the
+ * exact child emits `exit`. Either event proves this captured child ended;
+ * callers still perform their generation-dead barrier retirement. */
+export function onOwnedBackgroundProcessExit(child, listener) {
+    let ended = false;
+    const done = (code, signal) => {
+        if (ended)
+            return;
+        ended = true;
+        listener(code, signal);
+    };
+    child.once("exit", done);
+    // Failed spawn may emit close without an exit; it cannot own live work.
+    child.once("close", done);
+}
+/** One share is reserved for the responsive parent process's cooperative
+ * sealing/retention work. Child shares are released only when governing stops.
+ * This intentionally leaves some capacity unused when the parent is idle. */
+export function createBackgroundCpuBudget(totalTarget = BACKGROUND_CPU_TOTAL_TARGET) {
+    backgroundCpuDelayMs(1, 1, totalTarget);
+    const members = new Set();
+    const target = (requested) => Math.min(requested, totalTarget / (members.size + 1));
+    return {
+        parentTarget: target,
+        register() {
+            const id = Symbol("owned-background-child");
+            members.add(id);
+            return { target, release() { members.delete(id); } };
+        },
+    };
+}
+/** Shared by all background work hosted by this daemon process. Never pauses
+ * the daemon itself, so heartbeat, cancellation and hook I/O remain runnable. */
+export const backgroundDaemonCpuBudget = createBackgroundCpuBudget();
+const sleepAbortable = async (ms, signal) => {
+    signal?.throwIfAborted();
+    await new Promise((resolve, reject) => {
+        let timer;
+        const aborted = () => {
+            if (timer)
+                clearTimeout(timer);
+            signal?.removeEventListener("abort", aborted);
+            reject(signal?.reason instanceof Error ? signal.reason : new DOMException("Background work cancelled", "AbortError"));
+        };
+        timer = setTimeout(() => { signal?.removeEventListener("abort", aborted); resolve(); }, ms);
+        signal?.addEventListener("abort", aborted, { once: true });
+    });
+};
+/**
+ * Creates one cooperative CPU lane. Each checkpoint accounts only for the work
+ * since the previous checkpoint, so slow network I/O cannot build up a credit
+ * that later permits a long compression burst at full core speed.
+ */
+export function createBackgroundCpuYield(options) {
+    const cpuUsage = options.cpuUsage ?? process.cpuUsage;
+    const now = options.now ?? Date.now;
+    const sleep = options.sleep ?? sleepAbortable;
+    // Explicit foreground/embedding targets above the automatic .30 policy
+    // retain their old meaning. Only automatic low-priority work joins by
+    // default; an owned child opts out because its parent already governs it.
+    const budget = options.budget === undefined
+        ? (options.target <= BACKGROUND_CPU_TOTAL_TARGET ? backgroundDaemonCpuBudget : null)
+        : options.budget;
+    let previousCpu = cpuUsage();
+    let previousWall = now();
+    // Validate before work begins rather than after the first expensive chunk.
+    backgroundCpuDelayMs(1, 1, options.target, options.maximumSleepMs);
+    return async () => {
+        options.signal?.throwIfAborted();
+        // V8 may finish concurrent marking/sweeping while JavaScript is asleep.
+        // Sampling only before the sleep and resetting the baseline afterwards
+        // silently forgave that CPU. On a large index this produced isolated
+        // 80%+ process spikes despite a nominal 30% lane. Keep the same window
+        // open until work performed by *all* process threads, including work that
+        // happened during the repayment sleep, has actually been repaid.
+        for (;;) {
+            const observedAt = now();
+            const used = cpuUsage(previousCpu);
+            const cpuMs = (used.user + used.system) / 1_000;
+            const wallMs = Math.max(1, observedAt - previousWall);
+            const delay = backgroundCpuDelayMs(cpuMs, wallMs, budget?.parentTarget(options.target) ?? options.target, options.maximumSleepMs);
+            if (delay <= 1)
+                break;
+            await sleep(delay, options.signal);
+            options.signal?.throwIfAborted();
+        }
+        options.signal?.throwIfAborted();
+        previousCpu = cpuUsage();
+        previousWall = now();
+    };
+}
+/**
+ * Enforces a short wall-clock duty cycle from a process other than the worker.
+ *
+ * Cooperative checkpoints can account for JavaScript, compression and crypto,
+ * but they cannot interrupt a stop-the-world collection: the event loop that
+ * would choose to sleep is the thing being collected. A historical worker is
+ * already an owned child, so its parent can impose the missing hard boundary
+ * with 30 ms runnable / 70 ms paused windows on POSIX. This bounds even native
+ * V8 work; Windows retains the cooperative controller (and deliberately does
+ * not receive Unix signals).
+ */
+export function startBackgroundProcessCpuGovernor(options) {
+    backgroundCpuDelayMs(1, 1, options.target);
+    const allocation = options.budget?.register();
+    if ((options.platform ?? process.platform) === "win32")
+        return { stop() { allocation?.release(); } };
+    const periodMs = Math.max(20, Math.floor(options.periodMs ?? 100));
+    // Timers and SIGSTOP are not real-time primitives: a runnable window can
+    // overrun by a few milliseconds before the kernel observes the stop. Keep a
+    // small fixed headroom so the measured process stays near the requested
+    // target instead of routinely landing several points above it.
+    const runnableMs = () => Math.max(1, Math.min(periodMs - 1, Math.floor(periodMs * (allocation?.target(options.target) ?? options.target) * 0.90)));
+    let lastRunnableMs = runnableMs();
+    const setTimer = options.setTimer ?? ((callback, ms) => setTimeout(callback, ms));
+    const clearTimer = options.clearTimer ?? ((timer) => clearTimeout(timer));
+    let timer;
+    let stopped = false;
+    let paused = false;
+    const send = (signal) => {
+        try {
+            return options.signal(signal);
+        }
+        catch {
+            return false;
+        }
+    };
+    const failed = () => {
+        stopped = true;
+        allocation?.release();
+        options.onFailure?.(Object.assign(new Error("Background CPU process control is unavailable"), {
+            code: "background_cpu_control_unavailable",
+        }));
+    };
+    const run = () => {
+        if (stopped)
+            return;
+        if (paused) {
+            if (!send("SIGCONT")) {
+                failed();
+                return;
+            }
+            paused = false;
+        }
+        lastRunnableMs = runnableMs();
+        timer = setTimer(pause, lastRunnableMs);
+        timer.unref?.();
+    };
+    const pause = () => {
+        if (stopped)
+            return;
+        if (!send("SIGSTOP")) {
+            failed();
+            return;
+        }
+        paused = true;
+        timer = setTimer(run, periodMs - lastRunnableMs);
+        timer.unref?.();
+    };
+    if (options.verifySignals) {
+        if (!send("SIGSTOP"))
+            failed();
+        else {
+            paused = true;
+            if (!send("SIGCONT"))
+                failed();
+            else
+                paused = false;
+        }
+    }
+    if (!stopped) {
+        timer = setTimer(pause, lastRunnableMs);
+        timer.unref?.();
+    }
+    return {
+        stop() {
+            if (stopped)
+                return;
+            stopped = true;
+            allocation?.release();
+            if (timer)
+                clearTimer(timer);
+            timer = undefined;
+            // Never strand the child stopped if its owner cancels, times out, or
+            // receives the result between two pulses.
+            if (paused)
+                send("SIGCONT");
+            paused = false;
+        },
+    };
+}

package/dist/src/background-worker-error.d.ts

@@ -0,0 +1,12 @@
+/** Bounded machine-readable code only; never serialize provider details or
+ * arbitrary error properties across a background worker boundary. */
+export type BackgroundWorkerError = {
+    name?: string;
+    message: string;
+    stack?: string;
+    code?: string;
+};
+export declare function backgroundWorkerErrorToWire(cause: unknown): BackgroundWorkerError;
+export declare function backgroundWorkerErrorFromWire(wire: BackgroundWorkerError): Error & {
+    code?: string;
+};

package/dist/src/background-worker-error.js

@@ -0,0 +1,18 @@
+function safeCode(value) {
+    return typeof value === "string" && /^[A-Za-z0-9_-]{1,64}$/.test(value) ? value : undefined;
+}
+export function backgroundWorkerErrorToWire(cause) {
+    const error = cause instanceof Error ? cause : new Error(String(cause));
+    const code = safeCode(error.code);
+    return { name: error.name, message: error.message, stack: error.stack, ...(code ? { code } : {}) };
+}
+export function backgroundWorkerErrorFromWire(wire) {
+    const error = new Error(wire.message);
+    error.name = wire.name ?? "Error";
+    if (wire.stack)
+        error.stack = wire.stack;
+    const code = safeCode(wire.code);
+    if (code)
+        error.code = code;
+    return error;
+}