@nimbus-sh/worker 0.1.0

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

@@ -0,0 +1,195 @@
+/**
+ * fanout-pool.ts — two-tier fan-out primitive.
+ *
+ * Background
+ * ──────────
+ * The supervisor DO sits behind a V8 invariant: at most **4 concurrent
+ * env.LOADER.get(...).getEntrypoint().fetch(...)** calls per DO method
+ * invocation (3 from a Worker handler context). Beyond that, additional
+ * dispatches serialize against the cap and produce
+ * `Too many concurrent dynamic workers` errors. See
+ * `audit/sections/FANOUT-AUDIT.md` and
+ * `docs/research/poc-multi-backend-findings.md` for the measurement
+ * data.
+ *
+ * The existing `NimbusLoaderPool` (src/loaders/loader-pool.ts) defaults
+ * `concurrency = 4` precisely because of this cap. Every wide fan-out
+ * site in `src/npm/installer.ts` (resolver, install-batch, pre-bundle)
+ * was forced into a `concurrency: 1` outer pool with an internal
+ * limiter inside ONE facet — see the explicit comment at
+ * installer.ts:654 ("collapses what was 4 concurrent dynamic workers
+ * (pool.map slots) into 1").
+ *
+ * Two validated topologies (POC findings)
+ * ───────────────────────────────────────
+ *   POC C  in-DO fan-out          1 coordinator DO + N≤4 loaders   4.03× at N=4
+ *   POC B  DO Pool + 1 Loader/DO  N peer DOs × 1 loader each       7.75× at N=8, flat to N=32
+ *
+ * `NimbusFanoutPool` exposes ONE `submitMany` API that routes
+ * automatically:
+ *   width <  IN_DO_THRESHOLD   →  POC C (uses existing NimbusLoaderPool)
+ *   width >= IN_DO_THRESHOLD   →  POC B (peer NimbusSession DOs)
+ *
+ * IN_DO_THRESHOLD is 5 — exactly above the V8 cap so we never use the
+ * in-DO path beyond the safe ceiling, and the peer-DO path takes over
+ * cleanly for the wider workloads.
+ *
+ * Stable-id router
+ * ────────────────
+ * Each task carries a `key` (string). The router maps
+ * `key → siblingId = peerNamespace(coordDoIdShort, hash(key) mod N)`.
+ * Same key → same peer DO across runs. Tests can predict which peer
+ * handles which task, and warm peer isolates are reusable across
+ * back-to-back fan-outs that share keys.
+ *
+ * Hard-fail policy
+ * ────────────────
+ * Anti-requirement: NO fallback. If `env.LOADER` is missing, throw
+ * (existing NimbusLoaderPool already does). If
+ * `env.NIMBUS_SESSION` is missing AND a peer-DO route is needed,
+ * throw. Callers MUST get a deterministic error rather than silently
+ * collapsing back to width-1. The supervisor error handler logs and
+ * the install fails loudly — same posture every other facet binding
+ * has.
+ *
+ * Backpressure
+ * ────────────
+ * Hard cap: `MAX_PEER_FANOUT = 32` (POC B's flat zone). If
+ * `tasks.length > 32`, the surplus is queued and dispatched in
+ * subsequent rounds after the first 32 settle. This keeps the
+ * per-request peer-DO count bounded.
+ */
+/**
+ * Threshold at which we switch from in-DO POC C → peer-DO POC B.
+ *
+ * Set to **5** so the in-DO path stays below the V8 4-loaders-per-method
+ * cap by construction. width < 5 → POC C; width >= 5 → POC B.
+ */
+export declare const IN_DO_THRESHOLD = 5;
+/**
+ * Hard cap on concurrent peer DOs per single submitMany call. POC B
+ * measured flat throughput from N=8 to N=32; we use the ceiling so
+ * pathological 500-pkg installs still parallelise as wide as the
+ * topology supports.
+ */
+export declare const MAX_PEER_FANOUT = 32;
+/** Argument shape for `submitMany`. */
+export interface FanoutTask<A> {
+    /**
+     * Routing key for the stable-id router. Same key → same peer DO
+     * (when on the peer-DO path). Tests use this to predict placement.
+     */
+    key: string;
+    /** Argument passed to the user fn. */
+    args: A;
+}
+/** Options handed to NimbusFanoutPool's constructor. */
+export interface NimbusFanoutPoolOptions {
+    /**
+     * Tag prepended to peer-DO ids and in-DO loader ids for debugging
+     * (e.g. "npm-install-batch"). Affects neither isolate identity (in-DO
+     * path uses the existing NimbusLoaderPool's tag-fold) nor peer-DO
+     * deterministic placement (peer ids fold tag + key).
+     */
+    tag: string;
+    /**
+     * Per-task timeout in ms. Default 60_000. Forwarded to the in-DO
+     * NimbusLoaderPool's submit calls and to the peer-DO RPC's own
+     * NimbusLoaderPool.
+     */
+    timeoutMs?: number;
+    /**
+     * Preamble bundled into every facet (in-DO and inside each peer
+     * DO). Same semantics as NimbusLoaderPool's preamble option.
+     */
+    preamble?: string;
+    /**
+     * Wasm modules forwarded to every facet. Same semantics as
+     * NimbusLoaderPool's wasmModules option.
+     */
+    wasmModules?: Record<string, ArrayBuffer>;
+    /**
+     * Extra bindings forwarded to every facet. Same semantics as
+     * NimbusLoaderPool's extraBindings option.
+     */
+    extraBindings?: Record<string, unknown>;
+    /**
+     * If set, skip the supervisor-RPC binding injection (mirrors
+     * NimbusLoaderPool's omitSupervisor flag).
+     */
+    omitSupervisor?: boolean;
+}
+/**
+ * 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 declare class NimbusFanoutPool {
+    private readonly env;
+    private readonly ctx;
+    private readonly opts;
+    private readonly coordDoId;
+    private readonly coordDoIdShort;
+    constructor(env: any, ctx: DurableObjectState, opts: NimbusFanoutPoolOptions);
+    /**
+     * Dispatch `tasks` across the appropriate topology and return
+     * results in input order.
+     *
+     * Routing:
+     *   tasks.length < 5   →  POC C in-DO via NimbusLoaderPool (concurrency = tasks.length, capped at 4)
+     *   tasks.length >= 5  →  POC B peer-DO via env.NIMBUS_SESSION sibling DOs (deterministic stable-id router)
+     *
+     * 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).
+     */
+    submitMany<A, R>(tasks: FanoutTask<A>[], fn: (item: A, env: any) => R | Promise<R>): Promise<R[]>;
+    /**
+     * Diagnostic: report which topology a given task count would use.
+     * Used by tests to assert routing without exercising the full
+     * dispatch path.
+     */
+    topologyFor(taskCount: number): 'in-do' | 'peer-do' | 'empty';
+    /**
+     * Compute the deterministic peer-DO id for a given task key, given
+     * the peer count. Exposed so tests can assert routing predictions
+     * BEFORE running the dispatch.
+     *
+     * Shape: `nbf:${tag}:${coordDoIdShort}:${shard}` where
+     * `shard = hash(key) mod peerCount`. The hash is hashSource()
+     * (FNV-1a over a single-string input — adequate for routing; not
+     * cryptographic). Peer count is `min(tasks.length, MAX_PEER_FANOUT)`.
+     */
+    peerSiblingId(key: string, peerCount: number): string;
+    private _dispatchInDo;
+    private _dispatchPeerDo;
+}
+/**
+ * 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 declare function hashKeyToShard(key: string, peerCount: number): number;
+//# sourceMappingURL=fanout-pool.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fanout-pool.d.ts","sourceRoot":"","sources":["../../src/loaders/fanout-pool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AAMH;;;;;GAKG;AACH,eAAO,MAAM,eAAe,IAAI,CAAC;AAEjC;;;;;GAKG;AACH,eAAO,MAAM,eAAe,KAAK,CAAC;AAElC,uCAAuC;AACvC,MAAM,WAAW,UAAU,CAAC,CAAC;IAC3B;;;OAGG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ,sCAAsC;IACtC,IAAI,EAAE,CAAC,CAAC;CACT;AAED,wDAAwD;AACxD,MAAM,WAAW,uBAAuB;IACtC;;;;;OAKG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC;IAC1C;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;;;;GAQG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAM;IAC1B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAqB;IACzC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAA0B;IAC/C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;gBAE5B,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,kBAAkB,EAAE,IAAI,EAAE,uBAAuB;IAiB5E;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,UAAU,CAAC,CAAC,EAAE,CAAC,EACnB,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,EACtB,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,GAAG,EAAE,GAAG,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GACxC,OAAO,CAAC,CAAC,EAAE,CAAC;IASf;;;;OAIG;IACH,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,GAAG,OAAO;IAK7D;;;;;;;;;OASG;IACH,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM;YAOvC,aAAa;YAmCb,eAAe;CAwH9B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAUrE"}

package/dist/loaders/fanout-pool.js

@@ -0,0 +1,326 @@
+/**
+ * fanout-pool.ts — two-tier fan-out primitive.
+ *
+ * Background
+ * ──────────
+ * The supervisor DO sits behind a V8 invariant: at most **4 concurrent
+ * env.LOADER.get(...).getEntrypoint().fetch(...)** calls per DO method
+ * invocation (3 from a Worker handler context). Beyond that, additional
+ * dispatches serialize against the cap and produce
+ * `Too many concurrent dynamic workers` errors. See
+ * `audit/sections/FANOUT-AUDIT.md` and
+ * `docs/research/poc-multi-backend-findings.md` for the measurement
+ * data.
+ *
+ * The existing `NimbusLoaderPool` (src/loaders/loader-pool.ts) defaults
+ * `concurrency = 4` precisely because of this cap. Every wide fan-out
+ * site in `src/npm/installer.ts` (resolver, install-batch, pre-bundle)
+ * was forced into a `concurrency: 1` outer pool with an internal
+ * limiter inside ONE facet — see the explicit comment at
+ * installer.ts:654 ("collapses what was 4 concurrent dynamic workers
+ * (pool.map slots) into 1").
+ *
+ * Two validated topologies (POC findings)
+ * ───────────────────────────────────────
+ *   POC C  in-DO fan-out          1 coordinator DO + N≤4 loaders   4.03× at N=4
+ *   POC B  DO Pool + 1 Loader/DO  N peer DOs × 1 loader each       7.75× at N=8, flat to N=32
+ *
+ * `NimbusFanoutPool` exposes ONE `submitMany` API that routes
+ * automatically:
+ *   width <  IN_DO_THRESHOLD   →  POC C (uses existing NimbusLoaderPool)
+ *   width >= IN_DO_THRESHOLD   →  POC B (peer NimbusSession DOs)
+ *
+ * IN_DO_THRESHOLD is 5 — exactly above the V8 cap so we never use the
+ * in-DO path beyond the safe ceiling, and the peer-DO path takes over
+ * cleanly for the wider workloads.
+ *
+ * Stable-id router
+ * ────────────────
+ * Each task carries a `key` (string). The router maps
+ * `key → siblingId = peerNamespace(coordDoIdShort, hash(key) mod N)`.
+ * Same key → same peer DO across runs. Tests can predict which peer
+ * handles which task, and warm peer isolates are reusable across
+ * back-to-back fan-outs that share keys.
+ *
+ * Hard-fail policy
+ * ────────────────
+ * Anti-requirement: NO fallback. If `env.LOADER` is missing, throw
+ * (existing NimbusLoaderPool already does). If
+ * `env.NIMBUS_SESSION` is missing AND a peer-DO route is needed,
+ * throw. Callers MUST get a deterministic error rather than silently
+ * collapsing back to width-1. The supervisor error handler logs and
+ * the install fails loudly — same posture every other facet binding
+ * has.
+ *
+ * Backpressure
+ * ────────────
+ * Hard cap: `MAX_PEER_FANOUT = 32` (POC B's flat zone). If
+ * `tasks.length > 32`, the surplus is queued and dispatched in
+ * subsequent rounds after the first 32 settle. This keeps the
+ * per-request peer-DO count bounded.
+ */
+import { serializeFunction } from './vendor/serialize.js';
+import { BindingError } from './vendor/errors.js';
+import { NimbusLoaderPool } from './loader-pool.js';
+/**
+ * Threshold at which we switch from in-DO POC C → peer-DO POC B.
+ *
+ * Set to **5** so the in-DO path stays below the V8 4-loaders-per-method
+ * cap by construction. width < 5 → POC C; width >= 5 → POC B.
+ */
+export const IN_DO_THRESHOLD = 5;
+/**
+ * Hard cap on concurrent peer DOs per single submitMany call. POC B
+ * measured flat throughput from N=8 to N=32; we use the ceiling so
+ * pathological 500-pkg installs still parallelise as wide as the
+ * topology supports.
+ */
+export const MAX_PEER_FANOUT = 32;
+/**
+ * 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   →  POC C in-DO via NimbusLoaderPool (concurrency = tasks.length, capped at 4)
+     *   tasks.length >= 5  →  POC B peer-DO via env.NIMBUS_SESSION sibling DOs (deterministic stable-id router)
+     *
+     * 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);
+    }
+    /**
+     * Diagnostic: report which topology a given task count would use.
+     * Used by tests to assert routing without exercising the full
+     * dispatch path.
+     */
+    topologyFor(taskCount) {
+        if (taskCount === 0)
+            return 'empty';
+        return taskCount < IN_DO_THRESHOLD ? 'in-do' : 'peer-do';
+    }
+    /**
+     * Compute the deterministic peer-DO id for a given task key, given
+     * the peer count. Exposed so tests can assert routing predictions
+     * BEFORE running the dispatch.
+     *
+     * Shape: `nbf:${tag}:${coordDoIdShort}:${shard}` where
+     * `shard = hash(key) mod peerCount`. The hash is hashSource()
+     * (FNV-1a over a single-string input — adequate for routing; not
+     * cryptographic). 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 (POC C) ──────────────────────────────
+    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,
+        });
+        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 (POC B) ────────────────────────────
+    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, 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 stub = ns.get(id);
+            dispatchers.push(async () => {
+                // 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 POC B work.
+                const peerArgs = bucket.map((t) => t.args);
+                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,
+                });
+                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]);
+                    results[origIdx] = peerResults[i];
+                }
+            });
+        }
+        // [P0a wave-4d STAGGERED FAN-OUT]
+        // Dispatching all N shards via a single Promise.all triggered N
+        // simultaneous peer-DO cold-starts. Under concurrent-session load
+        // (N sessions × M shards each), the workerd DO scheduler queue
+        // overflows → workerd cancels some shards with "Durable Object
+        // is overloaded" → batch-fanout aborts. Verified prod 15d3bfda:
+        // 17-33% session failure rate at N=12 concurrent.
+        //
+        // Wave-4d fix: chunk dispatch into PHASES. Each phase fires
+        // FANOUT_PHASE_SIZE shards via Promise.all and AWAITS phase
+        // completion before the next phase starts. Reduces simultaneous
+        // peer-DO cold-starts from N to FANOUT_PHASE_SIZE per session.
+        //
+        // FANOUT_PHASE_SIZE = 4: empirically the breakpoint where workerd
+        // schedules without queue overflow at N=12 concurrent (4 × 12 = 48
+        // simultaneous DO cold-starts, vs 8 × 12 = 96 for single-phase).
+        //
+        // NOT a sleep/setTimeout — pure Promise-chain serialization. Phase 2
+        // dispatchers START immediately when Phase 1 completes; no idle gap.
+        const FANOUT_PHASE_SIZE = 4;
+        for (let i = 0; i < dispatchers.length; i += FANOUT_PHASE_SIZE) {
+            const phase = dispatchers.slice(i, i + FANOUT_PHASE_SIZE);
+            await Promise.all(phase.map((d) => d()));
+        }
+        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/generated-workers.d.ts

@@ -0,0 +1,26 @@
+/**
+ * generated-workers.ts — AUTO-GENERATED. DO NOT EDIT.
+ *
+ * Produced by scripts/bundle-facet-workers.mjs from:
+ *   - src/npm/tarball-stream.ts (streaming tar primitives)
+ *   - src/_shared/w7-frame.ts   (W7 streaming bulk-write encoder)
+ *
+ * Consumed by src/loaders/loader-pool.ts callers via the `preamble`
+ * option. The preamble is injected at the top of every generated
+ * worker module so user functions can reference the exported
+ * helpers by name.
+ *
+ * Tar-stream symbols: parseTarHeader, streamTarEntries,
+ *   readableStreamToAsyncIterable, MAX_FILE_BYTES.
+ * W7-frame symbols:   encodeWriteBatchStream, decodeWriteBatchStream,
+ *   W7_MAGIC, W7_TRAILER.
+ *
+ * Generated at: 2026-06-02T20:52:06.510Z
+ * Tar size: 3.84 KiB
+ * W7 size:  7.77 KiB
+ */
+export declare const TAR_STREAM_PREAMBLE: string;
+export declare const TAR_STREAM_PREAMBLE_SIZE: number;
+export declare const W7_FRAME_PREAMBLE: string;
+export declare const W7_FRAME_PREAMBLE_SIZE: number;
+//# sourceMappingURL=generated-workers.d.ts.map

package/dist/loaders/generated-workers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generated-workers.d.ts","sourceRoot":"","sources":["../../src/loaders/generated-workers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,eAAO,MAAM,mBAAmB,EAAE,MAAygI,CAAC;AAE5iI,eAAO,MAAM,wBAAwB,EAAE,MAAa,CAAC;AAErD,eAAO,MAAM,iBAAiB,EAAE,MAA+iQ,CAAC;AAEhlQ,eAAO,MAAM,sBAAsB,EAAE,MAAa,CAAC"}

package/dist/loaders/generated-workers.js

@@ -0,0 +1,25 @@
+/**
+ * generated-workers.ts — AUTO-GENERATED. DO NOT EDIT.
+ *
+ * Produced by scripts/bundle-facet-workers.mjs from:
+ *   - src/npm/tarball-stream.ts (streaming tar primitives)
+ *   - src/_shared/w7-frame.ts   (W7 streaming bulk-write encoder)
+ *
+ * Consumed by src/loaders/loader-pool.ts callers via the `preamble`
+ * option. The preamble is injected at the top of every generated
+ * worker module so user functions can reference the exported
+ * helpers by name.
+ *
+ * Tar-stream symbols: parseTarHeader, streamTarEntries,
+ *   readableStreamToAsyncIterable, MAX_FILE_BYTES.
+ * W7-frame symbols:   encodeWriteBatchStream, decodeWriteBatchStream,
+ *   W7_MAGIC, W7_TRAILER.
+ *
+ * Generated at: 2026-06-02T20:52:06.510Z
+ * Tar size: 3.84 KiB
+ * W7 size:  7.77 KiB
+ */
+export const TAR_STREAM_PREAMBLE = "// src/npm/tarball-stream.ts\nvar MAX_FILE_BYTES = 2e7;\nfunction parseTarHeader(block) {\n  if (block[0] === 0) return null;\n  let name = \"\";\n  for (let i = 0; i < 100 && block[i] !== 0; i++) {\n    name += String.fromCharCode(block[i]);\n  }\n  let prefix = \"\";\n  for (let i = 345; i < 500 && block[i] !== 0; i++) {\n    prefix += String.fromCharCode(block[i]);\n  }\n  if (prefix) name = prefix + \"/\" + name;\n  name = name.replace(/^package\\//, \"\");\n  let sizeStr = \"\";\n  for (let i = 124; i < 136 && block[i] !== 0; i++) {\n    sizeStr += String.fromCharCode(block[i]);\n  }\n  const size = parseInt(sizeStr.trim(), 8) || 0;\n  const typeFlag = block[156];\n  return { name, size, typeFlag };\n}\nasync function* readableStreamToAsyncIterable(rs) {\n  const reader = rs.getReader();\n  try {\n    while (true) {\n      const { value, done } = await reader.read();\n      if (done) return;\n      if (value && value.length > 0) yield value;\n    }\n  } finally {\n    try {\n      reader.releaseLock();\n    } catch {\n    }\n  }\n}\nasync function* streamTarEntries(source, onSkip) {\n  let carry = new Uint8Array(0);\n  let state = { kind: \"header\" };\n  function concat(a, b) {\n    if (a.length === 0) return b;\n    if (b.length === 0) return a;\n    const out = new Uint8Array(a.length + b.length);\n    out.set(a, 0);\n    out.set(b, a.length);\n    return out;\n  }\n  for await (const chunkRaw of source) {\n    let buf = concat(carry, chunkRaw);\n    let cursor = 0;\n    while (true) {\n      if (state.kind === \"header\") {\n        if (buf.length - cursor < 512) break;\n        const header = buf.subarray(cursor, cursor + 512);\n        const parsed = parseTarHeader(header);\n        cursor += 512;\n        if (!parsed) return;\n        const { name, size, typeFlag } = parsed;\n        const pad = size === 0 ? 0 : (512 - size % 512) % 512;\n        const isRegularFile = typeFlag === 48 || typeFlag === 0;\n        if (size === 0) {\n          if (isRegularFile && name) {\n            yield { name, data: new Uint8Array(0) };\n          }\n          state = { kind: \"header\" };\n          continue;\n        }\n        if (!isRegularFile || !name || size > MAX_FILE_BYTES) {\n          if (onSkip) {\n            const reason = !isRegularFile ? \"non-regular\" : !name ? \"no-name\" : \"too-large\";\n            try {\n              onSkip(name, size, reason);\n            } catch {\n            }\n          }\n          state = { kind: \"skip\", remaining: size + pad };\n          continue;\n        }\n        state = {\n          kind: \"file\",\n          name,\n          remaining: size,\n          fileBuf: new Uint8Array(size),\n          fileOffset: 0,\n          pad,\n          skip: false\n        };\n        continue;\n      }\n      if (state.kind === \"file\") {\n        const avail2 = buf.length - cursor;\n        if (avail2 === 0) break;\n        if (state.remaining > 0) {\n          const take2 = Math.min(state.remaining, avail2);\n          state.fileBuf.set(buf.subarray(cursor, cursor + take2), state.fileOffset);\n          state.fileOffset += take2;\n          state.remaining -= take2;\n          cursor += take2;\n          if (state.remaining > 0) break;\n        }\n        if (state.pad > 0) {\n          const avail22 = buf.length - cursor;\n          if (avail22 === 0) break;\n          const take2 = Math.min(state.pad, avail22);\n          state.pad -= take2;\n          cursor += take2;\n          if (state.pad > 0) break;\n        }\n        yield { name: state.name, data: state.fileBuf };\n        state = { kind: \"header\" };\n        continue;\n      }\n      const avail = buf.length - cursor;\n      if (avail === 0) break;\n      const take = Math.min(state.remaining, avail);\n      cursor += take;\n      state.remaining -= take;\n      if (state.remaining > 0) break;\n      state = { kind: \"header\" };\n    }\n    if (cursor >= buf.length) {\n      carry = new Uint8Array(0);\n    } else if (cursor === 0) {\n      carry = buf;\n    } else {\n      carry = buf.slice(cursor);\n    }\n  }\n}";
+export const TAR_STREAM_PREAMBLE_SIZE = 3932;
+export const W7_FRAME_PREAMBLE = "// src/_shared/w7-frame.ts\nvar W7_MAGIC = new Uint8Array([78, 87, 55, 1]);\nvar W7_TRAILER = new Uint8Array([78, 69, 78, 68]);\nvar ENCODER_QUEUE_HWM = 256 * 1024;\nvar ENCODER_EMIT_CAP = 64 * 1024;\nvar _peakInFlight = 0;\nvar _currentInFlight = 0;\nfunction _peakInFlightBytes() {\n  return _peakInFlight;\n}\nfunction _resetPeakInFlightBytes() {\n  _peakInFlight = 0;\n  _currentInFlight = 0;\n}\nfunction _trackInFlightAdd(n) {\n  _currentInFlight += n;\n  if (_currentInFlight > _peakInFlight) _peakInFlight = _currentInFlight;\n}\nfunction _trackInFlightSub(n) {\n  _currentInFlight -= n;\n  if (_currentInFlight < 0) _currentInFlight = 0;\n}\nfunction encodeWriteBatchStream(payload) {\n  const inodes = payload.inodes ?? [];\n  const chunks = payload.chunks ?? [];\n  const deletePaths = payload.deletePaths;\n  let phase = 0;\n  let chunkIdx = 0;\n  const enc = new TextEncoder();\n  const headerBytes = enc.encode(JSON.stringify({\n    inodes,\n    deletePaths,\n    chunkCount: chunks.length\n  }));\n  const source = {\n    type: \"bytes\",\n    pull(controller) {\n      try {\n        if (phase === 0) {\n          enqueue(controller, W7_MAGIC.slice());\n          phase = 1;\n          return;\n        }\n        if (phase === 1) {\n          const hdr = new Uint8Array(4 + headerBytes.length);\n          writeU32LE(hdr, 0, headerBytes.length);\n          hdr.set(headerBytes, 4);\n          enqueue(controller, hdr);\n          phase = 2;\n          return;\n        }\n        if (phase === 2) {\n          if (chunkIdx >= chunks.length) {\n            phase = 3;\n          } else {\n            const c = chunks[chunkIdx++];\n            const pathBytes = enc.encode(c.path);\n            const data = c.data instanceof Uint8Array ? c.data : new Uint8Array(c.data);\n            const headerSize = 4 + pathBytes.length + 4 + 4;\n            const headerOut = new Uint8Array(headerSize);\n            let o = 0;\n            writeU32LE(headerOut, o, pathBytes.length);\n            o += 4;\n            headerOut.set(pathBytes, o);\n            o += pathBytes.length;\n            writeU32LE(headerOut, o, c.chunkId);\n            o += 4;\n            writeU32LE(headerOut, o, data.length);\n            o += 4;\n            enqueue(controller, headerOut);\n            if (data.length === 0) return;\n            if (data.length <= ENCODER_EMIT_CAP) {\n              enqueue(controller, data);\n            } else {\n              for (let i = 0; i < data.length; i += ENCODER_EMIT_CAP) {\n                enqueue(controller, data.subarray(i, Math.min(i + ENCODER_EMIT_CAP, data.length)));\n              }\n            }\n            return;\n          }\n        }\n        if (phase === 3) {\n          enqueue(controller, W7_TRAILER.slice());\n          phase = 4;\n          controller.close();\n          return;\n        }\n        controller.close();\n      } catch (e) {\n        controller.error(e);\n      }\n    },\n    cancel() {\n      phase = 4;\n      chunkIdx = chunks.length;\n    }\n  };\n  return new ReadableStream(source, {\n    // Byte streams (`type: 'bytes'`) MUST use the default byte-counted\n    // strategy: highWaterMark is in bytes, size is implicit. Custom\n    // `size` callbacks are forbidden — they throw at construction.\n    highWaterMark: ENCODER_QUEUE_HWM\n  });\n  function enqueue(controller, bytes) {\n    _trackInFlightAdd(bytes.byteLength);\n    controller.enqueue(bytes);\n    queueMicrotask(() => _trackInFlightSub(bytes.byteLength));\n  }\n}\nasync function decodeWriteBatchStream(stream) {\n  const reader = stream.getReader();\n  const buf = new ByteBuffer(reader);\n  const magic = await buf.readExact(4, \"magic\");\n  if (!bytesEqual(magic, W7_MAGIC)) {\n    try {\n      reader.releaseLock();\n    } catch {\n    }\n    throw new Error(`w7-frame: bad magic, expected NW7\\\\x01, got ${Array.from(magic).map((b) => b.toString(16)).join(\" \")}`);\n  }\n  const hdrLenBytes = await buf.readExact(4, \"header-length\");\n  const hdrLen = readU32LE(hdrLenBytes, 0);\n  if (hdrLen < 0 || hdrLen > 64 * 1024 * 1024) {\n    throw new Error(`w7-frame: implausible header length ${hdrLen}`);\n  }\n  const hdrJson = await buf.readExact(hdrLen, \"header-json\");\n  let header;\n  try {\n    header = JSON.parse(new TextDecoder().decode(hdrJson));\n  } catch (e) {\n    throw new Error(`w7-frame: header JSON parse failed: ${e?.message || e}`);\n  }\n  if (!header || !Array.isArray(header.inodes) || typeof header.chunkCount !== \"number\") {\n    throw new Error(\"w7-frame: header missing required fields (inodes / chunkCount)\");\n  }\n  const chunkIter = {\n    [Symbol.asyncIterator]() {\n      let idx = 0;\n      let exhausted = false;\n      return {\n        async next() {\n          if (exhausted) return { value: void 0, done: true };\n          if (idx >= header.chunkCount) {\n            const trailer = await buf.readExact(4, \"trailer\");\n            if (!bytesEqual(trailer, W7_TRAILER)) {\n              throw new Error(\n                `w7-frame: bad trailer, expected NEND, got ${Array.from(trailer).map((b) => String.fromCharCode(b)).join(\"\")}`\n              );\n            }\n            try {\n              reader.releaseLock();\n            } catch {\n            }\n            exhausted = true;\n            return { value: void 0, done: true };\n          }\n          const pathLenBytes = await buf.readExact(4, \"chunk-path-length\");\n          const pathLen = readU32LE(pathLenBytes, 0);\n          if (pathLen < 0 || pathLen > 64 * 1024) {\n            throw new Error(`w7-frame: implausible path length ${pathLen} at chunk ${idx}`);\n          }\n          const pathBytes = await buf.readExact(pathLen, \"chunk-path\");\n          const path = new TextDecoder().decode(pathBytes);\n          const chunkIdBytes = await buf.readExact(4, \"chunk-id\");\n          const chunkId = readU32LE(chunkIdBytes, 0);\n          const dataLenBytes = await buf.readExact(4, \"chunk-data-length\");\n          const dataLen = readU32LE(dataLenBytes, 0);\n          if (dataLen < 0 || dataLen > 64 * 1024 * 1024) {\n            throw new Error(`w7-frame: implausible data length ${dataLen} at chunk ${idx}`);\n          }\n          const data = await buf.readExact(dataLen, \"chunk-data\");\n          idx++;\n          return { value: { path, chunkId, data }, done: false };\n        },\n        async return() {\n          exhausted = true;\n          try {\n            reader.releaseLock();\n          } catch {\n          }\n          return { value: void 0, done: true };\n        }\n      };\n    }\n  };\n  return {\n    inodes: header.inodes,\n    deletePaths: header.deletePaths,\n    chunkIter\n  };\n}\nfunction writeU32LE(out, off, n) {\n  out[off] = n & 255;\n  out[off + 1] = n >>> 8 & 255;\n  out[off + 2] = n >>> 16 & 255;\n  out[off + 3] = n >>> 24 & 255;\n}\nfunction readU32LE(buf, off) {\n  return (buf[off] | buf[off + 1] << 8 | buf[off + 2] << 16 | buf[off + 3] << 24) >>> 0;\n}\nfunction bytesEqual(a, b) {\n  if (a.length !== b.length) return false;\n  for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;\n  return true;\n}\nvar ByteBuffer = class {\n  constructor(reader) {\n    this.reader = reader;\n  }\n  chunks = [];\n  avail = 0;\n  done = false;\n  async readExact(n, label) {\n    if (n === 0) return new Uint8Array(0);\n    while (this.avail < n) {\n      if (this.done) {\n        throw new Error(\n          `w7-frame: stream ended ${this.avail} bytes into expected ${n}-byte ${label}`\n        );\n      }\n      const { value, done } = await this.reader.read();\n      if (done) {\n        this.done = true;\n      } else if (value && value.length > 0) {\n        this.chunks.push(value);\n        this.avail += value.length;\n      }\n    }\n    const out = new Uint8Array(n);\n    let copied = 0;\n    while (copied < n) {\n      const head = this.chunks[0];\n      const take = Math.min(head.length, n - copied);\n      out.set(head.subarray(0, take), copied);\n      copied += take;\n      if (take === head.length) {\n        this.chunks.shift();\n      } else {\n        this.chunks[0] = head.subarray(take);\n      }\n    }\n    this.avail -= n;\n    return out;\n  }\n};";
+export const W7_FRAME_PREAMBLE_SIZE = 7954;

package/dist/loaders/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Parallel dispatch utilities for Nimbus.
+ *
+ * Only the Nimbus-scoped pool is re-exported. The vendored
+ * cloudflare-parallel surface is intentionally NOT exposed here — callers
+ * must use the wrapper so they inherit stable-slot isolate reuse, Nimbus
+ * compat flags, and SupervisorRPC autoinjection.
+ *
+ * See src/loaders/loader-pool.ts for the pool implementation and
+ * src/loaders/vendor/ for the upstream cloudflare-parallel library.
+ */
+export { NimbusLoaderPool } from './loader-pool.js';
+export type { NimbusLoaderPoolOptions, NimbusLoaderCallOptions, NimbusLoaderMapOptions, } from './loader-pool.js';
+export { BindingError, ExecutionError, RetryExhaustedError, TimeoutError, } from './loader-pool.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/loaders/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/loaders/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,YAAY,EACV,uBAAuB,EACvB,uBAAuB,EACvB,sBAAsB,GACvB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,YAAY,EACZ,cAAc,EACd,mBAAmB,EACnB,YAAY,GACb,MAAM,kBAAkB,CAAC"}

package/dist/loaders/index.js

@@ -0,0 +1,13 @@
+/**
+ * Parallel dispatch utilities for Nimbus.
+ *
+ * Only the Nimbus-scoped pool is re-exported. The vendored
+ * cloudflare-parallel surface is intentionally NOT exposed here — callers
+ * must use the wrapper so they inherit stable-slot isolate reuse, Nimbus
+ * compat flags, and SupervisorRPC autoinjection.
+ *
+ * See src/loaders/loader-pool.ts for the pool implementation and
+ * src/loaders/vendor/ for the upstream cloudflare-parallel library.
+ */
+export { NimbusLoaderPool } from './loader-pool.js';
+export { BindingError, ExecutionError, RetryExhaustedError, TimeoutError, } from './loader-pool.js';