@nimbus-sh/worker 0.2.3 → 0.4.0

package/dist/loaders/fanout-pool.js

@@ -1,363 +0,0 @@
-/**
- * Two-tier fan-out primitive for work that must execute in Worker Loader
- * facets without tripping workerd's per-DO dynamic-worker ceiling.
- *
- * A single Durable Object method can drive at most four concurrent
- * Worker Loader fetches before extra dispatches serialize or fail. Small
- * batches therefore run in the coordinator DO through NimbusLoaderPool.
- * Wider batches are sharded across sibling NimbusSession DOs, each of
- * which owns its own four-loader budget.
- *
- * Routing is deterministic: each task has a stable key, and the key maps
- * to a sibling DO shard. There is no silent fallback to width-1 execution;
- * missing LOADER or NIMBUS_SESSION bindings fail loudly so install and
- * runtime operations do not appear successful after partial dispatch.
- */
-import { serializeFunction } from './vendor/serialize.js';
-import { BindingError } from './vendor/errors.js';
-import { NimbusLoaderPool } from './loader-pool.js';
-import { disposeRpcResource } from '@nimbus-sh/core/_shared/rpc-dispose.js';
-import { describeError, isDoOverloaded, isTransientDoReset } from '@nimbus-sh/core/observability/oom-classify.js';
-/**
- * Threshold at which routing switches from coordinator-local loaders to
- * sibling Durable Objects.
- *
- * Set to **5** so the in-DO path stays below the V8 4-loaders-per-method
- * cap by construction. width < 5 stays local; width >= 5 uses sibling DOs.
- */
-export const IN_DO_THRESHOLD = 5;
-/**
- * Hard cap on concurrent peer DOs per single submitMany call. Throughput stays
- * flat through this width while keeping per-request scheduler pressure bounded.
- */
-export const MAX_PEER_FANOUT = 32;
-/**
- * Bounded retries for a peer-DO shard dispatch that rejects with a
- * transient platform reset (code roll-over, storage cold-start hiccup).
- * Sibling DOs are addressed by stable name, so the retry re-dispatches
- * the SAME shard to the re-provisioning object; the fanned-out work
- * (packument resolution, tarball materialisation) is idempotent, so
- * re-running a shard is safe. Budget mirrors the resolve-facet's own
- * per-fetch retry policy so a single flaky cold start no longer fails a
- * whole install. The same budget covers an overloaded peer, on the longer
- * schedule below. Non-transient rejections (OOM, count mismatch, genuine
- * task throw) are NOT retried — they propagate on the first hit.
- */
-export const PEER_TRANSIENT_RESET_RETRIES = 3;
-export const PEER_RETRY_BACKOFF_MS = [250, 750, 1500];
-/**
- * Backoff for a shard whose peer DO was shed as overloaded. The object is
- * alive and the shard never ran; what it needs is time for the input-gate
- * queue to drain, so the schedule is an order of magnitude longer than the
- * reset schedule. A whole-batch abort here used to fail an entire install.
- */
-export const PEER_OVERLOAD_BACKOFF_MS = [1000, 3000, 6000];
-/**
- * Peer shards dispatched per phase. Each phase is a barrier that costs its
- * slowest member, so a wide fan-out pays ⌈shards / FANOUT_PHASE_SIZE⌉ serial
- * round-trips; the size trades that serialization against simultaneous cold
- * sibling DO starts.
- *
- * The six-barrier profile once measured on a 123-package install (21 shards of
- * ~6 packages, 10.6/6.8/21.8/7.9/34.6/4.8 s) came from the shard count, not
- * from this width. Capping install shards at INSTALL_PEER_CAP fixed it at the
- * source and that install now clears in two phases. Widening to 8 on top of
- * that bought one further barrier and doubled the simultaneous cold sibling-DO
- * starts, which is the account-level pressure the phasing exists for: twelve
- * concurrent Markflow installs went from 48 simultaneous peer starts to 96 and
- * began timing out. Phasing does not change how many peers start, only how
- * many start at once, so this width is set by the burst the scheduler
- * tolerates rather than by the barrier count.
- */
-export const FANOUT_PHASE_SIZE = 4;
-function isNimbusFanoutPeerStub(value) {
-    if ((typeof value !== 'object' && typeof value !== 'function') || value === null) {
-        return false;
-    }
-    const execute = Reflect.get(value, '_rpcFanoutExecute');
-    return typeof execute === 'function';
-}
-function fanoutPeerStub(value) {
-    if ((typeof value !== 'object' && typeof value !== 'function') || value === null) {
-        throw new BindingError('NimbusFanoutPool: NIMBUS_SESSION.get() did not return a peer stub.');
-    }
-    if (!isNimbusFanoutPeerStub(value)) {
-        throw new BindingError('NimbusFanoutPool: peer stub does not expose _rpcFanoutExecute().');
-    }
-    return value;
-}
-/**
- * Two-tier fan-out pool. Constructed by the supervisor DO; routes
- * each `submitMany` call automatically based on width.
- *
- * Lifetime: cheap to construct (no async init). Multiple submitMany
- * calls share NO state — each is dispatched fresh. The class
- * exists primarily as a clean API surface; per-call dispatch state
- * lives only inside submitMany's promise.
- */
-export class NimbusFanoutPool {
-    env;
-    ctx;
-    opts;
-    coordDoId;
-    coordDoIdShort;
-    constructor(env, ctx, opts) {
-        // Hard-fail on missing LOADER. NimbusLoaderPool also enforces this,
-        // but we check up front so the diagnostic points at the fanout-pool
-        // construction site rather than the deferred loader-pool one.
-        if (!env?.LOADER || typeof env.LOADER.get !== 'function') {
-            throw new BindingError('NimbusFanoutPool: env.LOADER binding missing or invalid. ' +
-                'Add a [[worker_loaders]] entry to wrangler.jsonc.');
-        }
-        this.env = env;
-        this.ctx = ctx;
-        this.opts = opts;
-        this.coordDoId = ctx.id.toString();
-        this.coordDoIdShort = this.coordDoId.slice(0, 12);
-    }
-    /**
-     * Dispatch `tasks` across the appropriate topology and return
-     * results in input order.
-     *
-     * Routing:
-     *   tasks.length < 5   -> coordinator-local NimbusLoaderPool
-     *   tasks.length >= 5  -> sibling NimbusSession DOs
-     *
-     * Backpressure: if `tasks.length > MAX_PEER_FANOUT (32)`, tasks
-     * are sharded modulo `MAX_PEER_FANOUT` and each shard's bucket
-     * runs serially inside its assigned peer DO via the in-peer
-     * NimbusLoaderPool's concurrency (capped at 4 there too). A
-     * single submitMany call returns when ALL tasks complete (or any
-     * throws).
-     *
-     * `fn` is the user function executed per task. It runs INSIDE a
-     * Worker Loader isolate (in the in-DO path) or inside a peer DO's
-     * Worker Loader isolate (in the peer-DO path); same trust posture
-     * as NimbusLoaderPool.submit. The function is serialized via
-     * the vendored serializeFunction (same as NimbusLoaderPool#prepare).
-     */
-    async submitMany(tasks, fn) {
-        if (tasks.length === 0)
-            return [];
-        if (tasks.length < IN_DO_THRESHOLD) {
-            return this._dispatchInDo(tasks, fn);
-        }
-        return this._dispatchPeerDo(tasks, fn);
-    }
-    /** Report which topology a task count uses without dispatching. */
-    topologyFor(taskCount) {
-        if (taskCount === 0)
-            return 'empty';
-        return taskCount < IN_DO_THRESHOLD ? 'in-do' : 'peer-do';
-    }
-    /**
-     * Compute the deterministic peer-DO id for a task key and peer count.
-     *
-     * Shape: `nbf:${tag}:${coordDoIdShort}:${shard}` where
-     * `shard = hash(key) mod peerCount`. Peer count is
-     * `min(tasks.length, MAX_PEER_FANOUT)`.
-     */
-    peerSiblingId(key, peerCount) {
-        const shard = hashKeyToShard(key, peerCount);
-        return `nbf:${this.opts.tag}:${this.coordDoIdShort}:${shard}`;
-    }
-    // ── Private: in-DO dispatch (in-DO fanout) ──────────────────────────────
-    async _dispatchInDo(tasks, fn) {
-        // Use the existing NimbusLoaderPool. Concurrency = task count
-        // (capped at 4 by constructor — tasks.length is already < 5
-        // here, so the cap won't bite). Each task = one pool.submit;
-        // pool.map runs them with stable-slot reuse.
-        const concurrency = Math.min(tasks.length, IN_DO_THRESHOLD - 1);
-        const pool = new NimbusLoaderPool(this.env, this.ctx, {
-            concurrency,
-            timeoutMs: this.opts.timeoutMs,
-            tag: this.opts.tag,
-            preamble: this.opts.preamble,
-            wasmModules: this.opts.wasmModules,
-            extraBindings: this.opts.extraBindings,
-            omitSupervisor: this.opts.omitSupervisor,
-            supervisorPid: this.opts.supervisorPid,
-        });
-        try {
-            // pool.map runs the function over `items` with concurrency-bounded
-            // slot reuse. Each slot is one warm loader isolate; we get exactly
-            // `concurrency` loader isolates total — well under the 4-cap.
-            const items = tasks.map((t) => t.args);
-            const results = await pool.map(fn, items);
-            // pool.map returns Array<R | null> (null on per-item failure with
-            // onError='null'/'skip'). Default onError='throw' rejects on
-            // first failure, so successful settle here implies all R values.
-            return results;
-        }
-        finally {
-            try {
-                pool.dispose();
-            }
-            catch { /* best-effort */ }
-        }
-    }
-    // ── Private: peer-DO dispatch (peer-DO fanout) ────────────────────────────
-    async _dispatchPeerDo(tasks, fn) {
-        const ns = this.env?.NIMBUS_SESSION;
-        if (!ns || typeof ns.idFromName !== 'function' || typeof ns.get !== 'function') {
-            throw new BindingError('NimbusFanoutPool: env.NIMBUS_SESSION binding missing or invalid. ' +
-                'The peer-DO topology requires it. ' +
-                'Add the binding via durable_objects.bindings in wrangler.jsonc.');
-        }
-        // Serialize the user function ONCE here on the supervisor side.
-        // Each peer DO receives the same fnSource string; warm peer
-        // loader isolates (keyed on fnHash) reuse across calls with
-        // identical fns.
-        const fnSource = serializeFunction(fn);
-        // Cap peer count at MAX_PEER_FANOUT. Tasks beyond N=32 are
-        // bucketed into existing shards — each shard's peer DO then
-        // runs its bucket through its in-DO NimbusLoaderPool.map
-        // (concurrency capped at 4 there).
-        const peerCount = Math.min(tasks.length, this.opts.maxPeers ?? MAX_PEER_FANOUT);
-        // Group tasks by deterministic shard. Same key → same shard, so
-        // tests can predict which peer handles which task.
-        const shards = new Map();
-        for (const t of tasks) {
-            const shard = hashKeyToShard(t.key, peerCount);
-            let bucket = shards.get(shard);
-            if (!bucket) {
-                bucket = [];
-                shards.set(shard, bucket);
-            }
-            bucket.push(t);
-        }
-        // Dispatch each shard to its peer DO. Build a map from
-        // task → its place in the original tasks array so we can
-        // reassemble results in input order.
-        const taskIndex = new Map();
-        tasks.forEach((t, i) => taskIndex.set(t, i));
-        const results = new Array(tasks.length);
-        // Build one async dispatcher per shard (closure capturing siblingName,
-        // bucket). NOT eagerly-started — wrapped in a thunk so we can stagger
-        // dispatch via Promise chains without forcing all shards to start
-        // simultaneously.
-        const dispatchers = [];
-        for (const [shard, bucket] of shards) {
-            const siblingName = `nbf:${this.opts.tag}:${this.coordDoIdShort}:${shard}`;
-            const id = ns.idFromName(siblingName);
-            const peerArgs = bucket.map((t) => t.args);
-            dispatchers.push(async () => {
-                for (let attempt = 0;; attempt++) {
-                    // Fresh stub per attempt: after a transient reset the previous
-                    // stub points at a torn-down object, so a retry re-resolves the
-                    // sibling by its stable id.
-                    const peerStub = ns.get(id);
-                    const stub = fanoutPeerStub(peerStub);
-                    try {
-                        // Each peer DO RPC call uses ONE LOADER worker on its side.
-                        // Supervisor → peer DO is a stub.fetch / RPC method call,
-                        // NOT an env.LOADER.get(); that's the cap-sidestep that
-                        // makes peer-DO fanout work.
-                        const rpcResp = await stub._rpcFanoutExecute(fnSource, peerArgs, {
-                            tag: this.opts.tag,
-                            timeoutMs: this.opts.timeoutMs,
-                            preamble: this.opts.preamble,
-                            wasmModules: this.opts.wasmModules,
-                            extraBindings: this.opts.extraBindings,
-                            omitSupervisor: this.opts.omitSupervisor,
-                            // INSTALL-HONESTY: forward the COORDINATOR's full doId so
-                            // the peer's NimbusLoaderPool can mint a SUPERVISOR
-                            // binding that routes back HERE (the user's session DO),
-                            // not to the peer DO itself. Without this, peer DOs'
-                            // env.SUPERVISOR.writeBatch / writeBatchStream / stdout /
-                            // ... write into the peer's own VFS — invisible to the
-                            // user. See INSTALL-HONESTY-retro.md.
-                            coordinatorDoId: this.coordDoId,
-                            // Credential source for peer-side writeBatchStream — the
-                            // invoking process pid, so package writes are authorized
-                            // as the user (not rejected as pid:0).
-                            supervisorPid: this.opts.supervisorPid,
-                        });
-                        try {
-                            const peerResults = rpcResp.results ?? [];
-                            if (peerResults.length !== bucket.length) {
-                                throw new Error(`peer DO returned ${peerResults.length} results for ${bucket.length} tasks ` +
-                                    `(siblingName=${siblingName})`);
-                            }
-                            // Place each result back into its original input slot.
-                            for (let i = 0; i < bucket.length; i++) {
-                                const origIdx = taskIndex.get(bucket[i]);
-                                if (origIdx === undefined) {
-                                    throw new Error(`peer DO result had no original task index (siblingName=${siblingName})`);
-                                }
-                                results[origIdx] = peerResults[i];
-                            }
-                        }
-                        finally {
-                            disposeRpcResource(rpcResp);
-                        }
-                        return;
-                    }
-                    catch (err) {
-                        const schedule = isTransientDoReset(err) ? PEER_RETRY_BACKOFF_MS
-                            : isDoOverloaded(err) ? PEER_OVERLOAD_BACKOFF_MS
-                                : null;
-                        if (schedule && attempt < PEER_TRANSIENT_RESET_RETRIES) {
-                            const backoff = schedule[Math.min(attempt, schedule.length - 1)];
-                            await new Promise((r) => setTimeout(r, backoff));
-                            continue;
-                        }
-                        // Re-throwing bare loses everything only this frame knows: which
-                        // sibling ran the shard, how wide it was, and how many attempts
-                        // it already cost. Callers report the message, so a rejection the
-                        // platform words as `internal error` arrived at the user with no
-                        // way to tell a one-off peer from a shard that had exhausted its
-                        // retries. `cause` keeps the original for anything that inspects
-                        // errors rather than reads them.
-                        throw new Error(`peer shard ${siblingName} (${bucket.length} task${bucket.length === 1 ? '' : 's'}) `
-                            + `failed after ${attempt + 1} attempt${attempt === 0 ? '' : 's'}: ${describeError(err)}`, { cause: err });
-                    }
-                    finally {
-                        disposeRpcResource(peerStub);
-                    }
-                }
-            });
-        }
-        // Dispatch peer shards in bounded phases. A single Promise.all across all
-        // shards can create too many simultaneous cold sibling DO starts under
-        // concurrent installs. Promise-chain phasing limits scheduler pressure
-        // without sleeps, timers, or idle gaps between phases.
-        //
-        // A phase is a hard barrier: no shard in phase N+1 starts until every
-        // shard in phase N returns, so `width@ms` per phase is what separates
-        // "the shards are slow" from "there are too many barriers".
-        for (let i = 0; i < dispatchers.length; i += FANOUT_PHASE_SIZE) {
-            const phase = dispatchers.slice(i, i + FANOUT_PHASE_SIZE);
-            const phaseStartedAt = Date.now();
-            await Promise.all(phase.map((d) => d()));
-            this.opts.onDispatchPhase?.(phase.length, Date.now() - phaseStartedAt);
-        }
-        return results;
-    }
-}
-/**
- * Stable hash → shard. Uses a fresh djb2 over the key (NOT
- * hashSource) and modulos by peerCount.
- *
- * Why not reuse hashSource: hashSource returns a base-36 string,
- * NOT hex — its alphabet is `[0-9a-z]`. parseInt(str, 16) on a
- * base-36 string aborts at the first non-hex char (any of g-z),
- * which produces extremely poor distribution: keys with the same
- * leading-hex-prefix collide regardless of their suffix. (Seen in
- * the wild: `task-0 .. task-7` all collided onto shard 4.)
- *
- * Deterministic: same key + same peerCount → same shard, every run.
- * Tests use this to predict placement.
- */
-export function hashKeyToShard(key, peerCount) {
-    if (peerCount <= 1)
-        return 0;
-    // djb2, returning an unsigned 32-bit integer — full 2^32 range,
-    // no string-format conversion gotchas. peerCount <= MAX_PEER_FANOUT
-    // (32) << 2^32, so the modulo distributes uniformly for any input.
-    let h = 5381;
-    for (let i = 0; i < key.length; i++) {
-        h = ((h << 5) + h + key.charCodeAt(i)) | 0;
-    }
-    return (h >>> 0) % peerCount;
-}

package/dist/loaders/loader-pool.d.ts

@@ -1,294 +0,0 @@
-/**
- * loader-pool.ts — Nimbus loader-isolate pool based on cloudflare-parallel.
- *
- * Adds Nimbus-specific behavior to the upstream pool design:
- *   1. **Stable-slot isolate reuse**. Upstream's #counter++ gives every
- *      dispatch a fresh isolate — fine for one-off AI calls, terrible for
- *      running 67 npm tarball extractions (cold-start dominates). We pin
- *      each job to `slot = cursor % concurrency` and use stable loader
- *      IDs `nfp:${fnHash}:slot-${i}:g${generation}`, so a pool of
- *      concurrency=4 keeps at most 4 warm isolates rather than N fresh ones.
- *   2. **Nimbus defaults**: compatibilityDate = CF_COMPAT_DATE (matches
- *      the supervisor worker), compatibilityFlags = ['nodejs_compat'],
- *      globalOutbound = undefined (inherit parent network so the facet can
- *      reach https://registry.npmjs.org without a proxy binding).
- *   3. **SupervisorRPC autoinjection**. The pool grabs a SupervisorRPC
- *      stub from `getCtxExports()` and forwards it as `env.SUPERVISOR` to
- *      every facet, same pattern as git-network-facet.ts. Callers can add
- *      more bindings via `extraBindings`.
- *   4. **Fail-loud defaults**: timeout 60s, retries 0, onError 'throw'.
- *      Caller opts in to leniency.
- *
- * The vendored directory contains only the upstream serialization, error,
- * and binding types used by this implementation.
- */
-/** Options handed to NimbusLoaderPool's constructor. */
-export interface NimbusLoaderPoolOptions {
-    /** Maximum concurrent in-flight facets. Default 4. */
-    concurrency?: number;
-    /** Per-task timeout in ms. Default 60_000. */
-    timeoutMs?: number;
-    /**
-     * Per-task retry attempts AFTER the initial failure. Default 0.
-     * Set to a small number only if transient RPC errors are common.
-     */
-    retries?: number;
-    /**
-     * Additional bindings forwarded to each facet. These merge on top of the
-     * default `{ SUPERVISOR: SupervisorRPC({ doId, pid:0 }) }`. Use this to
-     * give facets access to KV, R2, AI, or additional supervisor-level APIs.
-     */
-    extraBindings?: Record<string, unknown>;
-    /**
-     * Optional tag used in loader IDs for debugging (e.g. "npm-install").
-     * Does NOT affect isolate identity — same fn + same tag = same slot.
-     */
-    tag?: string;
-    /**
-     * If true, omit the default SupervisorRPC binding. Use this for pools
-     * that don't need DO callbacks (e.g. a pure CPU compute pool).
-     */
-    omitSupervisor?: boolean;
-    /**
-     * Loader cache scope. Defaults to `session`, which bakes the owning DO id
-     * into the loader key so stateful facets cannot leak bindings or globals
-     * across sessions. Use `global` only for stateless compute modules that do
-     * not receive a Supervisor binding and do not retain user state.
-     */
-    cacheScope?: 'session' | 'global';
-    /**
-     * Override the `doId` baked into the auto-injected SUPERVISOR binding.
-     * Default: `ctx.id.toString()` (the DO that constructs the pool).
-     *
-     * Used by NimbusFanoutPool's peer-DO branch (peer-DO fanout): peer DOs
-     * construct their per-task NimbusLoaderPool from inside
-     * `_rpcFanoutExecute`, where `ctx` is the PEER DO's ctx. Without this
-     * override the peer's auto-injected SUPERVISOR routes back to the
-     * peer DO itself — so writes (e.g. install-batch-facet's
-     * writeBatchStream) land in the peer's VFS instead of the
-     * COORDINATOR's. The user's terminal session is on the coordinator;
-     * writes-to-peer are invisible. See INSTALL-HONESTY-retro.md.
-     *
-     * When set, the auto-injected SupervisorRPC uses this string as the
-     * `props.doId`, routing all SUPERVISOR.* calls back to the
-     * coordinator. Effective only when `omitSupervisor !== true`.
-     */
-    supervisorDoIdOverride?: string;
-    /**
-     * Process pid baked into the auto-injected SUPERVISOR binding's props.
-     * The supervisor derives the write credential from this pid
-     * (`SupervisorRPC._pid()` → `processes.cred(pid)`), so any facet that
-     * calls a filesystem RPC (`writeBatchStream`, `writeFile`, …) must be
-     * dispatched with the invoking process's real pid — otherwise the RPC
-     * throws "missing or invalid process pid in props". npm install threads
-     * the shell command's `ctx.pid` here so package files land as the user.
-     * Left 0 (default) for pools whose facets touch only cache/registry RPCs
-     * (npm resolve, pre-bundle), which never call `_pid()`.
-     */
-    supervisorPid?: number;
-    /**
-     * Raw JavaScript source prepended to every generated worker module.
-     * Lets callers inject bundled helpers, such as a tar parser. The user
-     * function can reference top-level names declared in the preamble as if
-     * they were in lexical scope.
-     *
-     * Example: `preamble: 'export const parse = ...; const helper = ...;'`
-     * — the preamble runs at module-load time; any side effects happen
-     * inside the facet isolate.
-     *
-     * Preamble text is bytes-stable for a given pool — it's part of the
-     * loader-cache key (fnHash), so changing the preamble invalidates all
-     * warm slots.
-     */
-    preamble?: string;
-    /**
-     * WebAssembly modules to ship into the facet via the LOADER's
-     * `modules` map. Map keys are module specifier paths (e.g.
-     * `'esbuild.wasm'`); values are the raw bytes.
-     *
-     * Workerd registers each entry as `{ wasm: ArrayBuffer }` in the
-     * worker's modules map. The pool prepends a static
-     * `import __NIMBUS_WASM_<id> from './<key>';` to the generated
-     * worker.js so workerd compiles each at module-load (startup phase,
-     * where wasm code generation is permitted). The compiled Modules
-     * are exposed via `globalThis.__NIMBUS_WASM[<key>]` for the user
-     * function to read at request time.
-     *
-     * Why this works when other paths don't:
-     *   - request-time `WebAssembly.compile()` — disallowed by workerd
-     *     in this deploy.
-     *   - request-time RPC of a pre-compiled Module — workerd
-     *     structured-clone refuses ("Unable to deserialize cloned data").
-     *   - inlining bytes in the preamble — 16 MiB string per dispatch
-     *     OOMs the supervisor at module-source allocation time.
-     *   - LOADER modules-map (this) — bytes ride INSIDE the worker code
-     *     blob; workerd compiles wasm during its own startup pipeline,
-     *     never crossing structured-clone, never executing JS eval.
-     *
-     * The bytes ARE part of the loader-cache key (workerd hashes the
-     * whole WorkerCode), so changing the wasm bytes invalidates warm
-     * slots — desirable when the bundled wasm version changes.
-     */
-    wasmModules?: Record<string, ArrayBuffer>;
-}
-/** Per-call override (merged with pool defaults). */
-export interface NimbusLoaderCallOptions {
-    timeoutMs?: number;
-    retries?: number;
-    /**
-     * Per-call WebAssembly modules. Merged with the pool's
-     * constructor-time `wasmModules` at dispatch time and shipped via
-     * the LOADER's modules map (same `{ wasm: ArrayBuffer }` shape).
-     *
-     * Shipping path validated empirically against prod (see
-     * `WebAssembly.instantiate(bytes)` is blocked at request-time but
-     * the LOADER-modules path compiles bytes during the inner
-     * worker's module-load phase, where wasm code generation IS
-     * permitted. The bytes ride INSIDE the worker code blob; workerd
-     * never crosses structured-clone, never executes user-eval.
-     *
-     * Cache key impact: per-call bytes are fingerprinted (length +
-     * first/last byte per module) and folded into the loader cache
-     * key. Identical bytes on the same slot → warm reuse; different
-     * bytes → fresh isolate. The pool's existing `wasmHash` field
-     * captures CONSTRUCTOR-time bytes only; per-call bytes get an
-     * independent fingerprint mixed into the slot id at dispatch.
-     *
-     * Naming collision rule: a per-call key MUST NOT collide with a
-     * constructor-time key (after identifier sanitisation). The
-     * dispatch path throws BindingError if it does — silently
-     * shadowing the constructor's wasm would break the cache-key
-     * invariant downstream callers rely on.
-     *
-     * Used by the `wasm-runner` shell command in src/runtime/
-     * wasm-runner.ts to ship user-supplied .wasm bytes from VFS into
-     * a fresh facet isolate per invocation.
-     */
-    wasmModules?: Record<string, ArrayBuffer>;
-}
-/** Per-map override. Adds onError strategy for partial failures. */
-export interface NimbusLoaderMapOptions extends NimbusLoaderCallOptions {
-    /** Concurrency override for this call. Defaults to pool's concurrency. */
-    concurrency?: number;
-    /**
-     * What to do when an individual item fails:
-     *   - 'throw' (default): reject whole map on first failure.
-     *   - 'null': replace failed items with null in the result array.
-     *   - 'skip': omit failed items from the result array.
-     * We default to 'throw' — install-time failures are not silently ignored.
-     */
-    onError?: 'throw' | 'null' | 'skip';
-}
-export interface LoaderWorkerModuleSourceOptions {
-    fnSource: string;
-    preamble?: string;
-    wasmEntries?: ReadonlyArray<{
-        name: string;
-        id: string;
-    }>;
-    hasBindings: boolean;
-}
-/** Assemble the exact JavaScript module parsed by a dynamic loader worker. */
-export declare function assembleLoaderWorkerModuleSource(options: LoaderWorkerModuleSourceOptions): string;
-/**
- * Nimbus-scoped parallel dispatch over `env.LOADER`. Tasks are pure
- * functions whose last argument is an `env` object containing the
- * forwarded bindings (default: `{ SUPERVISOR }`).
- *
- * Typical use:
- *
- *   const pool = new NimbusLoaderPool(env, ctx, {
- *     concurrency: 4,
- *     tag: 'npm-install',
- *   });
- *   const results = await pool.map(
- *     async (pkg, env) => env.SUPERVISOR.writeBatch(buildPayload(pkg)),
- *     toFetch,
- *   );
- */
-export declare class NimbusLoaderPool {
-    #private;
-    private readonly loader;
-    private readonly concurrency;
-    private readonly defaultTimeoutMs;
-    private readonly defaultRetries;
-    private readonly tag;
-    private readonly slotGenerations;
-    private bindings;
-    private readonly preamble;
-    private readonly preambleHash;
-    /**
-     * WASM modules to ship in the LOADER `modules` map. See
-     * NimbusLoaderPoolOptions.wasmModules for the rationale. Stored in
-     * insertion order so the per-import preamble we generate matches
-     * across pool dispatches (cache-key stability).
-     */
-    private readonly wasmModules;
-    /** Hash of (name + byte length + first/last bytes) of every wasm
-     *  module, folded into the loader cache key so changes invalidate
-     *  warm slots. Hashing the FULL bytes would be O(20+ MiB) per dispatch
-     *  and is unnecessary — wasm bytes are pinned at deploy time, the
-     *  length+endpoints are a strong-enough fingerprint. */
-    private readonly wasmHash;
-    /**
-     * Short prefix of the owning DO's id, baked into the loader.get()
-     * cache key so warm isolates are scoped to ONE session. Without this,
-     * session A's pool and session B's pool (same `tag` + `fnHash`) share
-     * an isolate — which means B's writeBatch RPCs routed through A's
-     * env.SUPERVISOR binding (minted with A's doId at construction
-     * time). B's install reports success but the writes land in A's VFS,
-     * leaving B with only the git-clone seed files (~119 instead of ~1491).
-     * 12 chars is enough entropy for DO ids to collide-free per process.
-     */
-    private readonly doIdShort;
-    constructor(env: any, ctx: DurableObjectState, opts?: NimbusLoaderPoolOptions);
-    /** Effective concurrency used when no per-call override is supplied. */
-    get defaultConcurrency(): number;
-    /**
-     * Run `fn` once with `arg` on a slot isolate. Returns the result or
-     * throws TimeoutError / RetryExhaustedError / ExecutionError.
-     */
-    submit<T, R>(fn: (arg: T, env: any) => R | Promise<R>, arg: T, opts?: NimbusLoaderCallOptions): Promise<Awaited<R>>;
-    /**
-     * Run `fn` on every item in `items`, at most `concurrency` at a time,
-     * pinned to stable slots so warm isolates are reused.
-     *
-     * Results are returned in input order. Failure handling per `onError`.
-     */
-    map<T, R>(fn: (item: T, env: any) => R | Promise<R>, items: T[], opts?: NimbusLoaderMapOptions): Promise<Array<Awaited<R> | null>>;
-    /**
-     * Same shape as `map`, but accepts a pre-serialized function source
-     * string instead of a live function reference. Used by
-     * `NimbusFanoutPool`'s peer-DO leg, where the function was already
-     * serialized on the coordinator side and forwarded over RPC.
-     *
-     * The fnSource MUST be the output of `serializeFunction(fn)`
-     * (typically forwarded directly from a coordinator RPC). Bytes-
-     * stable invariants:
-     *   - `fnHash = hashSource(fnSource)` must be deterministic so
-     *     warm slots are correctly keyed.
-     *   - `fnSource` must NOT reference `this` — same rule as
-     *     `serializeFunction`.
-     *
-     * No fn-validation runs here (it already ran on the coordinator);
-     * the peer trusts the caller to forward a valid serialization.
-     */
-    mapSource<T, R>(fnSource: string, items: T[], opts?: NimbusLoaderMapOptions): Promise<Array<Awaited<R> | null>>;
-    /**
-     * Release any RPC stubs held by the pool. Call this once the caller
-     * is done with the pool (post-`map`/`submit`) so the underlying
-     * stubs don't linger in workerd's deferred-destruction queue.
-     *
-     * Primary target: the SUPERVISOR binding stub we minted at
-     * construction time (via `ctxExports.SupervisorRPC({props})`). It's
-     * a cross-isolate RPC stub — without explicit disposal it stays
-     * referenced until the parent isolate's event-handler context
-     * finishes, which during npm install means "until the whole install
-     * completes" — long enough to accumulate alongside other leaked
-     * stubs and trip the QueueState::ACTIVE fatal.
-     *
-     * Safe to call more than once; idempotent.
-     */
-    dispose(): void;
-}
-//# sourceMappingURL=loader-pool.d.ts.map

package/dist/loaders/loader-pool.d.ts.map

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