@nimbus-sh/worker 0.1.2 → 0.1.4

package/dist/index.js

@@ -64,8 +64,8 @@ export function getCtxExports() {
     return _getCtxExports();
 }
 // Worker default export — a `createNimbusHandler()` instance running in
-// auto auth mode. The live demo and dogfood embedder are bit-identical
+// auto auth mode. The live demo and hosted-demo embedder are bit-identical
 // from here on; the only difference is `NIMBUS_LEGACY_PUBLIC=1` env var
-// (set on the live demo, unset for the dogfood) flipping auth.mode to
+// (set on the live demo, unset for the hosted-demo) flipping auth.mode to
 // 'legacy' inside the auto-resolver.
 export default createNimbusHandler();

package/dist/loaders/child-process/spawn-facet.d.ts

@@ -1,46 +1,9 @@
 /**
- * spawn-facet.ts — Per-spawn task body run inside a fresh Worker Loader
- * isolate via NimbusFanoutPool.
+ * Per-spawn task body for Worker Loader isolates.
  *
- * Why this exists (gap #1 from arch-gaps wave)
- * ────────────────────────────────────────────
- * Pre-arch-gaps, child_process.spawn from inside a node facet RPCs back
- * to the supervisor's FacetProcessManager._dispatch, which directly
- * invokes either commandRegistry.runPureBuiltin or facetMgr.execStream.
- * Both paths execute IN THE SUPERVISOR'S V8 CONTEXT. The supervisor's
- * heap thus accumulates per-spawn allocation pressure.
- *
- * arch-gaps target: every cp.spawn / spawnSync / exec / execFile call
- * runs inside a fresh Worker Loader isolate. NimbusFanoutPool (proven
- * by F-1 install-batch and F-2 resolver fan-out) provides the auto-
- * routing primitive (in-DO POC C for <5, peer-DO POC B for ≥5).
- *
- * What this task does
- * ───────────────────
- *   1. Mints a per-isolate token (`globalThis.__nimbus_g3_token__`).
- *      The first call into a fresh isolate creates the token; warm
- *      slots reuse it. Distinct tokens across calls = distinct
- *      isolates. Probe surface: audit/probes/arch-gaps/g3-e2e/
- *      child-spawn-isolation.mjs.
- *   2. Delegates the actual command execution to
- *      `env.SUPERVISOR.cpDispatchInline(req, kind)`. This RPC reuses
- *      the existing pure-builtin / facet-direct execution paths
- *      (preserves correctness) but the dispatch envelope itself ran
- *      in a fresh isolate.
- *   3. Returns `{ exitCode, marker, stdout, stderr }`. The supervisor-
- *      side ChildProcessSpawnPool wraps the marker into a per-spawn
- *      stderr line and forwards stdout/stderr to the parent's WS.
- *
- * Single-ownership invariant (carried over from git-freeze Q-fix):
- * stdin (if any) is passed by-value as a string in `req.stdin`; no
- * shared ArrayBuffer/Uint8Array refs. The result envelope returns
- * stdout/stderr as strings (already copied by the structured-clone
- * boundary).
- *
- * Stability invariants (cloudflare-parallel serialises via fn.toString):
- *   - No `this` references.
- *   - No closure capture other than args + (optional) preamble.
- *   - The function is the only export's body; helpers inlined.
+ * The isolate delegates command execution back to the supervisor through a
+ * narrow RPC and returns copied string output. The parent pool owns streaming
+ * and process bookkeeping.
  */
 export interface SpawnInIsolateSpec {
     /** The original cp.spawn payload from node-shims.ts. */
@@ -61,22 +24,14 @@ export interface SpawnInIsolateSpec {
 }
 export interface SpawnInIsolateResult {
     exitCode: number;
-    /** Per-isolate token line: `[g3-spawn-isolate] tok=<TOKEN>\n`.
-     *  Pre-pended to stderr by the supervisor-side spawn-pool when the
-     *  result is forwarded to the cp.spawn parent. Distinct values across
-     *  results = distinct isolates ran the dispatch. */
+    /** Per-isolate token line used by diagnostics that verify isolate routing. */
     marker: string;
     stdout: string;
     stderr: string;
 }
 /**
- * Per-spawn task body. Serialised via fn.toString() and dispatched
- * by NimbusFanoutPool.submitMany. Signature must be (spec, env) so
- * NimbusFanoutPool's internal `fn(item, env)` lines up.
- *
- * `env.SUPERVISOR` is the supervisor-rpc binding wired automatically
- * by NimbusLoaderPool (see src/loaders/loader-pool.ts:288 — bindings
- * default to `{ SUPERVISOR }`).
+ * Signature must remain `(spec, env)` because Worker Loader dispatch calls
+ * the task as `fn(item, env)`.
  */
 export declare const runSpawnInIsolate: (spec: SpawnInIsolateSpec, env: {
     SUPERVISOR: {

package/dist/loaders/child-process/spawn-facet.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"spawn-facet.d.ts","sourceRoot":"","sources":["../../../src/loaders/child-process/spawn-facet.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAEH,MAAM,WAAW,kBAAkB;IACjC,wDAAwD;IACxD,GAAG,EAAE;QACH,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,MAAM,EAAE,CAAC;QACf,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC5B,GAAG,EAAE,MAAM,CAAC;QACZ,KAAK,CAAC,EAAE,GAAG,CAAC;QACZ,QAAQ,CAAC,EAAE,OAAO,CAAC;QACnB,KAAK,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;QACzB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,4DAA4D;IAC5D,IAAI,EAAE,cAAc,GAAG,cAAc,GAAG,SAAS,CAAC;IAClD,uEAAuE;IACvE,aAAa,EAAE,MAAM,GAAG,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB;;;wDAGoD;IACpD,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,GAC5B,MAAM,kBAAkB,EACxB,KAAK;IACH,UAAU,EAAE;QACV,gBAAgB,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;YAChD,QAAQ,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAC;SAClD,CAAC,CAAC;KACJ,CAAC;CACH,KACA,OAAO,CAAC,oBAAoB,CAoD9B,CAAC"}
+{"version":3,"file":"spawn-facet.d.ts","sourceRoot":"","sources":["../../../src/loaders/child-process/spawn-facet.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,kBAAkB;IACjC,wDAAwD;IACxD,GAAG,EAAE;QACH,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,MAAM,EAAE,CAAC;QACf,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC5B,GAAG,EAAE,MAAM,CAAC;QACZ,KAAK,CAAC,EAAE,GAAG,CAAC;QACZ,QAAQ,CAAC,EAAE,OAAO,CAAC;QACnB,KAAK,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;QACzB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;IACF,4DAA4D;IAC5D,IAAI,EAAE,cAAc,GAAG,cAAc,GAAG,SAAS,CAAC;IAClD,uEAAuE;IACvE,aAAa,EAAE,MAAM,GAAG,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,8EAA8E;IAC9E,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,eAAO,MAAM,iBAAiB,GAC5B,MAAM,kBAAkB,EACxB,KAAK;IACH,UAAU,EAAE;QACV,gBAAgB,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;YAChD,QAAQ,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAC;SAClD,CAAC,CAAC;KACJ,CAAC;CACH,KACA,OAAO,CAAC,oBAAoB,CAoD9B,CAAC"}

package/dist/loaders/child-process/spawn-facet.js

@@ -1,55 +1,13 @@
 /**
- * spawn-facet.ts — Per-spawn task body run inside a fresh Worker Loader
- * isolate via NimbusFanoutPool.
+ * Per-spawn task body for Worker Loader isolates.
  *
- * Why this exists (gap #1 from arch-gaps wave)
- * ────────────────────────────────────────────
- * Pre-arch-gaps, child_process.spawn from inside a node facet RPCs back
- * to the supervisor's FacetProcessManager._dispatch, which directly
- * invokes either commandRegistry.runPureBuiltin or facetMgr.execStream.
- * Both paths execute IN THE SUPERVISOR'S V8 CONTEXT. The supervisor's
- * heap thus accumulates per-spawn allocation pressure.
- *
- * arch-gaps target: every cp.spawn / spawnSync / exec / execFile call
- * runs inside a fresh Worker Loader isolate. NimbusFanoutPool (proven
- * by F-1 install-batch and F-2 resolver fan-out) provides the auto-
- * routing primitive (in-DO POC C for <5, peer-DO POC B for ≥5).
- *
- * What this task does
- * ───────────────────
- *   1. Mints a per-isolate token (`globalThis.__nimbus_g3_token__`).
- *      The first call into a fresh isolate creates the token; warm
- *      slots reuse it. Distinct tokens across calls = distinct
- *      isolates. Probe surface: audit/probes/arch-gaps/g3-e2e/
- *      child-spawn-isolation.mjs.
- *   2. Delegates the actual command execution to
- *      `env.SUPERVISOR.cpDispatchInline(req, kind)`. This RPC reuses
- *      the existing pure-builtin / facet-direct execution paths
- *      (preserves correctness) but the dispatch envelope itself ran
- *      in a fresh isolate.
- *   3. Returns `{ exitCode, marker, stdout, stderr }`. The supervisor-
- *      side ChildProcessSpawnPool wraps the marker into a per-spawn
- *      stderr line and forwards stdout/stderr to the parent's WS.
- *
- * Single-ownership invariant (carried over from git-freeze Q-fix):
- * stdin (if any) is passed by-value as a string in `req.stdin`; no
- * shared ArrayBuffer/Uint8Array refs. The result envelope returns
- * stdout/stderr as strings (already copied by the structured-clone
- * boundary).
- *
- * Stability invariants (cloudflare-parallel serialises via fn.toString):
- *   - No `this` references.
- *   - No closure capture other than args + (optional) preamble.
- *   - The function is the only export's body; helpers inlined.
+ * The isolate delegates command execution back to the supervisor through a
+ * narrow RPC and returns copied string output. The parent pool owns streaming
+ * and process bookkeeping.
  */
 /**
- * Per-spawn task body. Serialised via fn.toString() and dispatched
- * by NimbusFanoutPool.submitMany. Signature must be (spec, env) so
- * NimbusFanoutPool's internal `fn(item, env)` lines up.
- *
- * `env.SUPERVISOR` is the supervisor-rpc binding wired automatically
- * by NimbusLoaderPool (see src/loaders/loader-pool.ts:288 — bindings
- * default to `{ SUPERVISOR }`).
+ * Signature must remain `(spec, env)` because Worker Loader dispatch calls
+ * the task as `fn(item, env)`.
  */
 export const runSpawnInIsolate = async function runSpawnInIsolate(spec, env) {
     // Mint or reuse the per-isolate token.
@@ -72,7 +30,7 @@ export const runSpawnInIsolate = async function runSpawnInIsolate(spec, env) {
     }
     // env.SUPERVISOR is auto-injected by NimbusLoaderPool and pinned to
     // THIS DO's id (props.doId = ctx.id.toString()). With the in-DO
-    // POC C route, "this DO" IS the user-session DO whose _cpRegistry
+    // in-DO fanout route, "this DO" IS the user-session DO whose _cpRegistry
     // is populated; cpDispatchInline therefore reaches the right
     // dispatcher.
     if (!env || !env.SUPERVISOR || typeof env.SUPERVISOR.cpDispatchInline !== 'function') {

package/dist/loaders/child-process/spawn-pool.d.ts

@@ -1,49 +1,10 @@
 /**
- * spawn-pool.ts — Supervisor-side wrapper that runs each cp.spawn
- * dispatch in a fresh Worker Loader isolate via NimbusFanoutPool.
+ * Supervisor-side child-process dispatch pool.
  *
- * Why this exists (gap #1 from arch-gaps wave)
- * ────────────────────────────────────────────
- * Closes the architectural gap surfaced by G1 S6: pre-arch-gaps,
- * cp.spawn / spawnSync / exec / execFile from inside a node facet
- * RPCs back to the supervisor's FacetProcessManager._dispatch, which
- * directly invokes commandRegistry.runPureBuiltin / facetMgr.execStream
- * IN-SUPERVISOR. The supervisor accumulates per-spawn allocation
- * pressure.
- *
- * Post-arch-gaps, FacetProcessManager._dispatch routes through this
- * pool, which submits ONE NimbusFanoutPool.submitMany task per spawn.
- * NimbusFanoutPool auto-routes:
- *   < IN_DO_THRESHOLD (5) → POC C in-DO (concurrency = task count, capped at 4)
- *   ≥ IN_DO_THRESHOLD     → POC B peer-DO with stable-id router
- *                            (key = command name, so re-installs of
- *                            the same toolchain cluster on warm peers).
- *
- * The per-spawn task body (`runSpawnInIsolate`) emits a per-isolate
- * marker token and delegates the actual command execution back to the
- * supervisor via `env.SUPERVISOR.cpDispatchInline(req, kind)` — that
- * RPC reuses the existing pure-builtin / facet-direct paths (no
- * correctness regression). The architectural win is the dispatch
- * envelope itself running in a fresh isolate.
- *
- * Why one-task-per-spawn (not batched)
- * ────────────────────────────────────
- * cp.spawn is asynchronous from the parent's perspective: each spawn
- * call returns an emitter immediately, with output streaming as data
- * arrives. Batching multiple unrelated spawns into one submitMany
- * call would couple their lifetimes (any failure aborts the batch).
- * Per-spawn submit gives each call its own isolate-lifecycle envelope,
- * matching the cp.spawn contract.
- *
- * Anti-requirements observed
- * ──────────────────────────
- *   - NO setTimeout / sleep on hot paths.
- *   - NO fallback to in-supervisor dispatch when env.LOADER missing —
- *     NimbusFanoutPool throws BindingError at construction. Caller
- *     (FacetProcessManager._dispatch) propagates the error to the
- *     parent's stderr.
- *   - Single-ownership: stdin/stdout/stderr crossing the loader RPC
- *     boundary are strings (structured-clone boundary copies them).
+ * Child-process calls from Node facets are executed through Worker Loader
+ * isolates instead of allocation-heavy dispatch in the supervisor isolate.
+ * Each spawn receives its own lifecycle envelope while command semantics
+ * continue to flow through the existing supervisor RPC.
  */
 export interface SpawnPoolHooks {
     onStdout(data: string): void;

package/dist/loaders/child-process/spawn-pool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"spawn-pool.d.ts","sourceRoot":"","sources":["../../../src/loaders/child-process/spawn-pool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAKH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,GAAG,CAAC;IACZ,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,KAAK,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,qBAAa,qBAAqB;IAChC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAM;IAC1B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAqB;IACzC;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAmB;IACxC;;;;;OAKG;IACH,OAAO,CAAC,KAAK,CAAuC;gBAExC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,kBAAkB;IAW7C;;;;;;;;OAQG;IACG,MAAM,CACV,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,cAAc,GAAG,cAAc,GAAG,SAAS,EACjD,KAAK,EAAE,cAAc,EACrB,OAAO,EAAE,MAAM,GAAG,MAAM,GACvB,OAAO,CAAC,MAAM,CAAC;CAyDnB"}
+{"version":3,"file":"spawn-pool.d.ts","sourceRoot":"","sources":["../../../src/loaders/child-process/spawn-pool.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,GAAG,CAAC;IACZ,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,KAAK,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,qBAAa,qBAAqB;IAChC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAM;IAC1B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAqB;IACzC;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAmB;IACxC;;;;;OAKG;IACH,OAAO,CAAC,KAAK,CAAuC;gBAExC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,kBAAkB;IAW7C;;;;;;;;OAQG;IACG,MAAM,CACV,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,cAAc,GAAG,cAAc,GAAG,SAAS,EACjD,KAAK,EAAE,cAAc,EACrB,OAAO,EAAE,MAAM,GAAG,MAAM,GACvB,OAAO,CAAC,MAAM,CAAC;CAyDnB"}

package/dist/loaders/child-process/spawn-pool.js

@@ -1,49 +1,10 @@
 /**
- * spawn-pool.ts — Supervisor-side wrapper that runs each cp.spawn
- * dispatch in a fresh Worker Loader isolate via NimbusFanoutPool.
+ * Supervisor-side child-process dispatch pool.
  *
- * Why this exists (gap #1 from arch-gaps wave)
- * ────────────────────────────────────────────
- * Closes the architectural gap surfaced by G1 S6: pre-arch-gaps,
- * cp.spawn / spawnSync / exec / execFile from inside a node facet
- * RPCs back to the supervisor's FacetProcessManager._dispatch, which
- * directly invokes commandRegistry.runPureBuiltin / facetMgr.execStream
- * IN-SUPERVISOR. The supervisor accumulates per-spawn allocation
- * pressure.
- *
- * Post-arch-gaps, FacetProcessManager._dispatch routes through this
- * pool, which submits ONE NimbusFanoutPool.submitMany task per spawn.
- * NimbusFanoutPool auto-routes:
- *   < IN_DO_THRESHOLD (5) → POC C in-DO (concurrency = task count, capped at 4)
- *   ≥ IN_DO_THRESHOLD     → POC B peer-DO with stable-id router
- *                            (key = command name, so re-installs of
- *                            the same toolchain cluster on warm peers).
- *
- * The per-spawn task body (`runSpawnInIsolate`) emits a per-isolate
- * marker token and delegates the actual command execution back to the
- * supervisor via `env.SUPERVISOR.cpDispatchInline(req, kind)` — that
- * RPC reuses the existing pure-builtin / facet-direct paths (no
- * correctness regression). The architectural win is the dispatch
- * envelope itself running in a fresh isolate.
- *
- * Why one-task-per-spawn (not batched)
- * ────────────────────────────────────
- * cp.spawn is asynchronous from the parent's perspective: each spawn
- * call returns an emitter immediately, with output streaming as data
- * arrives. Batching multiple unrelated spawns into one submitMany
- * call would couple their lifetimes (any failure aborts the batch).
- * Per-spawn submit gives each call its own isolate-lifecycle envelope,
- * matching the cp.spawn contract.
- *
- * Anti-requirements observed
- * ──────────────────────────
- *   - NO setTimeout / sleep on hot paths.
- *   - NO fallback to in-supervisor dispatch when env.LOADER missing —
- *     NimbusFanoutPool throws BindingError at construction. Caller
- *     (FacetProcessManager._dispatch) propagates the error to the
- *     parent's stderr.
- *   - Single-ownership: stdin/stdout/stderr crossing the loader RPC
- *     boundary are strings (structured-clone boundary copies them).
+ * Child-process calls from Node facets are executed through Worker Loader
+ * isolates instead of allocation-heavy dispatch in the supervisor isolate.
+ * Each spawn receives its own lifecycle envelope while command semantics
+ * continue to flow through the existing supervisor RPC.
  */
 import { NimbusLoaderPool } from '../loader-pool.js';
 import { runSpawnInIsolate } from './spawn-facet.js';

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

@@ -1,76 +1,29 @@
 /**
- * fanout-pool.ts — two-tier fan-out primitive.
+ * Two-tier fan-out primitive for work that must execute in Worker Loader
+ * facets without tripping workerd's per-DO dynamic-worker ceiling.
  *
- * 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.
+ * 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.
  *
- * 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.
+ * 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.
  */
 /**
- * Threshold at which we switch from in-DO POC C → peer-DO POC B.
+ * 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 → POC C; width >= 5 → POC B.
+ * cap by construction. width < 5 stays local; width >= 5 uses sibling DOs.
  */
 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.
+ * Hard cap on concurrent peer DOs per single submitMany call. Throughput stays
+ * flat through this width while keeping per-request scheduler pressure bounded.
  */
 export declare const MAX_PEER_FANOUT = 32;
 /** Argument shape for `submitMany`. */
@@ -140,8 +93,8 @@ export declare class NimbusFanoutPool {
      * 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)
+     *   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

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

@@ -1 +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"}
+{"version":3,"file":"fanout-pool.d.ts","sourceRoot":"","sources":["../../src/loaders/fanout-pool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAMH;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,IAAI,CAAC;AAEjC;;;GAGG;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;CAyG9B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAUrE"}

package/dist/loaders/fanout-pool.js

@@ -1,79 +1,32 @@
 /**
- * fanout-pool.ts — two-tier fan-out primitive.
+ * Two-tier fan-out primitive for work that must execute in Worker Loader
+ * facets without tripping workerd's per-DO dynamic-worker ceiling.
  *
- * 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.
+ * 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.
  *
- * 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.
+ * 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';
 /**
- * Threshold at which we switch from in-DO POC C → peer-DO POC B.
+ * 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 → POC C; width >= 5 → POC B.
+ * 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. 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.
+ * 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;
 /**
@@ -110,8 +63,8 @@ export class NimbusFanoutPool {
      * 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)
+     *   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
@@ -158,7 +111,7 @@ export class NimbusFanoutPool {
         const shard = hashKeyToShard(key, peerCount);
         return `nbf:${this.opts.tag}:${this.coordDoIdShort}:${shard}`;
     }
-    // ── Private: in-DO dispatch (POC C) ──────────────────────────────
+    // ── 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
@@ -192,7 +145,7 @@ export class NimbusFanoutPool {
             catch { /* best-effort */ }
         }
     }
-    // ── Private: peer-DO dispatch (POC B) ────────────────────────────
+    // ── 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') {
@@ -241,7 +194,7 @@ export class NimbusFanoutPool {
                 // 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.
+                // makes peer-DO fanout work.
                 const peerArgs = bucket.map((t) => t.args);
                 const rpcResp = await stub._rpcFanoutExecute(fnSource, peerArgs, {
                     tag: this.opts.tag,
@@ -271,25 +224,10 @@ export class NimbusFanoutPool {
                 }
             });
         }
-        // [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.
+        // 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.
         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);

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

@@ -15,8 +15,7 @@
  * W7-frame symbols:   encodeWriteBatchStream, decodeWriteBatchStream,
  *   W7_MAGIC, W7_TRAILER.
  *
- * Generated at: 2026-06-04T22:29:13.391Z
- * Tar size: 3.86 KiB
+ * Tar size: 3.84 KiB
  * W7 size:  7.78 KiB
  */
 export declare const TAR_STREAM_PREAMBLE: string;

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

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