@nimbus-sh/worker 0.2.3 → 0.4.0

package/scripts/bundle-esbuild-wasm.mjs

@@ -5,7 +5,7 @@
  * Why this exists
  * ───────────────
  * Pre-bundling npm packages (the `Pre-bundling N modules…` step in
- * src/npm/installer.ts) runs inside NimbusLoaderPool isolates so each
+ * src/npm/installer.ts) runs inside NimbusIsolatePool isolates so each
  * `esbuild.build()` allocation hits a fresh 128 MiB envelope rather
  * than the supervisor's. The facet needs two pieces of esbuild-wasm
  * at module-load time:
@@ -175,7 +175,7 @@ async function main() {
  * esbuild-wasm-bundle.generated.ts — AUTO-GENERATED by scripts/bundle-esbuild-wasm.mjs
  * DO NOT EDIT.
  *
- * Bundled esbuild-wasm ${version} adapter for use inside NimbusLoaderPool
+ * Bundled esbuild-wasm ${version} adapter for use inside NimbusIsolatePool
  * isolates. Only the JS adapter is bundled here (~117 KiB); the wasm
  * binary itself lives in the static-assets layer at
  * public/_assets/esbuild-${version}.wasm and is fetched on demand by

package/scripts/bundle-facet-workers.mjs

@@ -4,7 +4,7 @@
  * injects into dynamic workers.
  *
  * WHY this exists:
- *   Dynamic workers (NimbusFacetPool / NimbusLoaderPool) receive their
+ *   Dynamic workers (NimbusFacetPool / NimbusIsolatePool) receive their
  *   module source as strings — they cannot import supervisor modules,
  *   and user functions cannot capture supervisor closure variables. Any
  *   TypeScript the injected code needs must therefore be esbuild-bundled
@@ -51,6 +51,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const root = join(__dirname, '..');
 const coreRoot = join(root, '..', 'core');
+const platformRoot = join(root, '..', 'platform');
 
 /**
  * Bundle one TS source into a self-contained ESM string suitable for
@@ -273,11 +274,8 @@ async function main() {
   //    facet has no access to the encoder symbol (cloudflare-parallel
   //    serialises via fn.toString() — no runtime imports).
   //
-  //    The W7-frame module imports a TypeScript type from sqlite-vfs,
-  //    which esbuild's type-stripping handles transparently. The
-  //    runtime output has no imports.
   const w7Stripped = await bundleAsPreamble(
-    join(coreRoot, 'src', '_shared', 'w7-frame.ts'),
+    join(platformRoot, 'src', 'w7-frame.ts'),
     'w7-frame',
   );
 
@@ -291,7 +289,7 @@ async function main() {
     ' *',
     ' * Produced by scripts/bundle-facet-workers.mjs from:',
     ' *   - @nimbus-sh/core src/_shared/tarball-stream.ts (streaming tar primitives)',
-    ' *   - @nimbus-sh/core src/_shared/w7-frame.ts (W7 streaming bulk-write encoder)',
+    ' *   - @nimbus-sh/platform src/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',
@@ -327,7 +325,7 @@ async function main() {
     ' *',
     ' * Self-contained IIFE that installs globalThis.__nimbusVirtualSockets.',
     ' * Consumed by python-runner.ts and ruby-runner.ts: spliced into the',
-    ' * socket process worker module source passed to NimbusLoaderPool.',
+    ' * socket process worker module source passed to NimbusIsolatePool.',
     ' *',
     ` * Size: ${(kernelSrc.length / 1024).toFixed(2)} KiB`,
     ' */',

package/scripts/bundle-sqlite-wasm.mjs

@@ -5,7 +5,7 @@
  *
  * Why this exists
  * ───────────────
- * `import { DatabaseSync } from "node:sqlite"` runs inside NimbusLoaderPool
+ * `import { DatabaseSync } from "node:sqlite"` runs inside NimbusIsolatePool
  * facet isolates. sql.js (Emscripten SQLite) needs two pieces at facet
  * runtime:
  *

package/dist/facets/inner-do-registry.d.ts

@@ -1,41 +0,0 @@
-/**
- * inner-do-registry.ts — Module-level registry of inner DO classes.
- *
- * `nimbus-wrangler` populates this on each successful buildAndLoad()
- * with the DurableObject classes extracted from the freshly-loaded
- * inner Worker via `worker.getDurableObjectClass(name)`. The supervisor
- * DO (`NimbusSession`) reads it on each inner-DO fetch to synthesize a
- * NimbusDurableObjectNamespace stub for `env.MY_DO`.
- *
- * Why a separate leaf module:
- *   Before this extraction, the registry lived inside nimbus-session.ts,
- *   which forced nimbus-wrangler.ts to import from nimbus-session.ts —
- *   producing the cycle
- *     index.ts -> nimbus-session.ts -> nimbus-wrangler.ts -> nimbus-session.ts
- *   Promoting the registry to its own leaf breaks that cycle without
- *   changing any semantics. The Map identity is preserved across the
- *   isolate (it's still process-scoped — module-level state — survives
- *   across DO instances in the same workerd process).
- *
- * Key shape:
- *   `<supervisor-DO-id>:<binding-name>` — both halves are required to
- *   prevent multiple supervisor DOs in the same isolate from clobbering
- *   each other's registrations.
- *
- * The values are DurableObject class constructors. `any` here is
- * deliberate: the inner DO's class shape is whatever the user defines
- * in their inner Worker, and we only need to invoke it via
- * `ctx.facets.get(name, { class: cls, id })` — workerd does the rest.
- */
-/** Look up a registered inner-DO class. Returns undefined if not found. */
-export declare function getInnerDoClass(supervisorDoId: string, bindingName: string): any | undefined;
-/**
- * Register an inner DO class for synthesis. Called by nimbus-wrangler.ts
- * after each successful buildAndLoad() with the class extracted from
- * the fresh worker stub. Keys are `<doId>:<bindingName>` so multiple
- * supervisor DOs don't collide.
- */
-export declare function registerInnerDoClass(supervisorDoId: string, bindingName: string, cls: any): void;
-/** Clear all registrations belonging to a supervisor DO (called on rebuild). */
-export declare function clearInnerDoClasses(supervisorDoId: string): void;
-//# sourceMappingURL=inner-do-registry.d.ts.map

package/dist/facets/inner-do-registry.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"inner-do-registry.d.ts","sourceRoot":"","sources":["../../src/facets/inner-do-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAIH,2EAA2E;AAC3E,wBAAgB,eAAe,CAAC,cAAc,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,GAAG,GAAG,SAAS,CAE5F;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,cAAc,EAAE,MAAM,EACtB,WAAW,EAAE,MAAM,EACnB,GAAG,EAAE,GAAG,GACP,IAAI,CAEN;AAED,gFAAgF;AAChF,wBAAgB,mBAAmB,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAKhE"}

package/dist/facets/inner-do-registry.js

@@ -1,51 +0,0 @@
-/**
- * inner-do-registry.ts — Module-level registry of inner DO classes.
- *
- * `nimbus-wrangler` populates this on each successful buildAndLoad()
- * with the DurableObject classes extracted from the freshly-loaded
- * inner Worker via `worker.getDurableObjectClass(name)`. The supervisor
- * DO (`NimbusSession`) reads it on each inner-DO fetch to synthesize a
- * NimbusDurableObjectNamespace stub for `env.MY_DO`.
- *
- * Why a separate leaf module:
- *   Before this extraction, the registry lived inside nimbus-session.ts,
- *   which forced nimbus-wrangler.ts to import from nimbus-session.ts —
- *   producing the cycle
- *     index.ts -> nimbus-session.ts -> nimbus-wrangler.ts -> nimbus-session.ts
- *   Promoting the registry to its own leaf breaks that cycle without
- *   changing any semantics. The Map identity is preserved across the
- *   isolate (it's still process-scoped — module-level state — survives
- *   across DO instances in the same workerd process).
- *
- * Key shape:
- *   `<supervisor-DO-id>:<binding-name>` — both halves are required to
- *   prevent multiple supervisor DOs in the same isolate from clobbering
- *   each other's registrations.
- *
- * The values are DurableObject class constructors. `any` here is
- * deliberate: the inner DO's class shape is whatever the user defines
- * in their inner Worker, and we only need to invoke it via
- * `ctx.facets.get(name, { class: cls, id })` — workerd does the rest.
- */
-const _NIMBUS_INNER_DO_CLASSES = new Map();
-/** Look up a registered inner-DO class. Returns undefined if not found. */
-export function getInnerDoClass(supervisorDoId, bindingName) {
-    return _NIMBUS_INNER_DO_CLASSES.get(supervisorDoId + ':' + bindingName);
-}
-/**
- * Register an inner DO class for synthesis. Called by nimbus-wrangler.ts
- * after each successful buildAndLoad() with the class extracted from
- * the fresh worker stub. Keys are `<doId>:<bindingName>` so multiple
- * supervisor DOs don't collide.
- */
-export function registerInnerDoClass(supervisorDoId, bindingName, cls) {
-    _NIMBUS_INNER_DO_CLASSES.set(supervisorDoId + ':' + bindingName, cls);
-}
-/** Clear all registrations belonging to a supervisor DO (called on rebuild). */
-export function clearInnerDoClasses(supervisorDoId) {
-    const prefix = supervisorDoId + ':';
-    for (const k of _NIMBUS_INNER_DO_CLASSES.keys()) {
-        if (k.startsWith(prefix))
-            _NIMBUS_INNER_DO_CLASSES.delete(k);
-    }
-}

package/dist/facets/launch-pacer.d.ts

@@ -1,111 +0,0 @@
-/**
- * launch-pacer.ts — spreading a resident launch across Durable Object turns.
- *
- * Building a resident process is the largest single span of computation this
- * session performs: for pi it walks a 17 MB source tree through eight
- * enrichment passes, serializes a 22.9 MB module map, and writes that map into
- * the image store. Done in one turn it occupied the session DO's only thread
- * for 15-35 s, and a session that cannot reach its thread cannot service the
- * terminal WebSocket — the launch turn finished `outcome=ok` and the terminal
- * died anyway, painting "[process terminal closed]" over a process that was
- * still running.
- *
- * A faster launch does not fix that. A launch half the length still blocks the
- * thread for as long as it runs, and the socket is dropped inside that window
- * whether or not the work succeeds. What fixes it is never holding the thread
- * for long in the first place, which means suspending the launch at bounded
- * intervals and resuming it on a fresh turn. Responsiveness stops depending on
- * how long the total work takes.
- *
- * A fresh turn is also a fresh CPU budget. The same launches that dropped the
- * socket were also being killed with `exceededCpu` at 31.8 s and 32.5 s
- * against a 30 s ceiling, and no amount of yielding *within* one invocation
- * moves that: CPU accrues to the invocation, not to the pause. Only genuinely
- * re-entering the object resets it.
- *
- * Progress is measured in bytes rather than milliseconds because workerd's
- * clock does not advance without I/O — a wall-clock guard inside a span of
- * pure computation reads zero however many seconds it burns, which is why the
- * phase costs behind this module had to be recovered from per-turn `cpuTime`
- * rather than measured in place. Bytes are what the work is actually
- * proportional to, and they are exact. The same reasoning is why
- * `git/network-facet.ts` bounds its checkout chunks by entries and decoded
- * bytes and treats its wall guard as coarse.
- */
-/** How a paced launch gets back onto a fresh Durable Object turn. */
-export interface LaunchTurnScheduler {
-    /**
-     * Suspend until a fresh turn is running this launch again.
-     *
-     * `chunkEnded` settles when the resumed launch reaches its next suspension
-     * point or finishes, so whoever grants the turn can await the work it just
-     * released rather than letting it run detached in a handler's microtask
-     * drain.
-     */
-    nextTurn(chunkEnded: Promise<void>): Promise<void>;
-}
-/**
- * Bytes of launch work one turn may perform before it must yield.
- *
- * Sized so a chunk stays far below both the CPU ceiling and the span in which
- * a terminal socket is at risk, while keeping the number of turn handoffs —
- * each an alarm round trip — small enough not to dominate a launch. pi's
- * 22.9 MB map crosses this about a dozen times per phase that handles it.
- */
-export declare const LAUNCH_CHUNK_MAX_BYTES = 2000000;
-/**
- * Accounts launch progress and ends the turn when a chunk's worth has been
- * spent.
- *
- * Callers report the work they are about to do or have just done and await
- * the result; a pacer that is not yielding returns without suspending, so the
- * one-shot exec path — which passes no pacer at all — keeps its exact
- * behaviour and cost. Nothing here decides WHAT the launch does, only where it
- * is allowed to stop.
- */
-export declare class LaunchPacer {
-    private readonly scheduler;
-    private readonly maxChunkBytes;
-    private readonly stillWanted?;
-    /** Turn handoffs this launch has taken. Reported with the launch. */
-    chunks: number;
-    /** Total work accounted, for the same report. */
-    bytes: number;
-    private spent;
-    private chunkEnded;
-    /**
-     * @param stillWanted Checked every time the launch resumes. A launch spans
-     *   many turns, so anything may have happened to what it is building for
-     *   while it was suspended; throwing from here is how a launch stops instead
-     *   of spending turn after turn on work nothing will use. Checked at the one
-     *   place a launch can be interrupted, rather than at whichever phases
-     *   remembered to ask.
-     */
-    constructor(scheduler: LaunchTurnScheduler, maxChunkBytes?: number, stillWanted?: (() => void) | undefined);
-    /**
-     * Account `bytes` of completed work, ending the turn if a chunk is full.
-     *
-     * Safe to call anywhere the launch holds no state that a concurrent turn
-     * could invalidate — which is why the image store registers its whole root
-     * set before the first call rather than one entry at a time.
-     */
-    spend(bytes: number): Promise<void>;
-    /**
-     * The launch has finished (or failed). Releases the turn still waiting on
-     * the chunk it resumed, so a launch that ends mid-chunk does not strand the
-     * handler that granted it.
-     */
-    settle(): void;
-}
-/**
- * Chunk bound for this session, honouring the verification knob.
- *
- * `NIMBUS_LAUNCH_CHUNK_BYTES` forces a small bound so an ordinary launch —
- * not just a pathological one — crosses several turns and exercises every
- * suspension point. Without it the multi-turn path would only ever be
- * reached by the largest programs, which is the same reason
- * `git/commands.ts` carries `NIMBUS_GIT_CHECKOUT_CHUNK_ENTRIES`. Unset in
- * production, where the default applies.
- */
-export declare function launchChunkMaxBytes(env: unknown): number;
-//# sourceMappingURL=launch-pacer.d.ts.map

package/dist/facets/launch-pacer.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"launch-pacer.d.ts","sourceRoot":"","sources":["../../src/facets/launch-pacer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,qEAAqE;AACrE,MAAM,WAAW,mBAAmB;IAClC;;;;;;;OAOG;IACH,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpD;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,UAAY,CAAC;AAEhD;;;;;;;;;GASG;AACH,qBAAa,WAAW;IAkBpB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,aAAa;IAC9B,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC;IAnB/B,qEAAqE;IACrE,MAAM,SAAK;IACX,iDAAiD;IACjD,KAAK,SAAK;IAEV,OAAO,CAAC,KAAK,CAAK;IAClB,OAAO,CAAC,UAAU,CAA8D;IAEhF;;;;;;;OAOG;gBAEgB,SAAS,EAAE,mBAAmB,EAC9B,aAAa,GAAE,MAA+B,EAC9C,WAAW,CAAC,GAAE,MAAM,IAAI,aAAA;IAG3C;;;;;;OAMG;IACG,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAczC;;;;OAIG;IACH,MAAM,IAAI,IAAI;CAIf;AAQD;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAMxD"}

package/dist/facets/launch-pacer.js

@@ -1,130 +0,0 @@
-/**
- * launch-pacer.ts — spreading a resident launch across Durable Object turns.
- *
- * Building a resident process is the largest single span of computation this
- * session performs: for pi it walks a 17 MB source tree through eight
- * enrichment passes, serializes a 22.9 MB module map, and writes that map into
- * the image store. Done in one turn it occupied the session DO's only thread
- * for 15-35 s, and a session that cannot reach its thread cannot service the
- * terminal WebSocket — the launch turn finished `outcome=ok` and the terminal
- * died anyway, painting "[process terminal closed]" over a process that was
- * still running.
- *
- * A faster launch does not fix that. A launch half the length still blocks the
- * thread for as long as it runs, and the socket is dropped inside that window
- * whether or not the work succeeds. What fixes it is never holding the thread
- * for long in the first place, which means suspending the launch at bounded
- * intervals and resuming it on a fresh turn. Responsiveness stops depending on
- * how long the total work takes.
- *
- * A fresh turn is also a fresh CPU budget. The same launches that dropped the
- * socket were also being killed with `exceededCpu` at 31.8 s and 32.5 s
- * against a 30 s ceiling, and no amount of yielding *within* one invocation
- * moves that: CPU accrues to the invocation, not to the pause. Only genuinely
- * re-entering the object resets it.
- *
- * Progress is measured in bytes rather than milliseconds because workerd's
- * clock does not advance without I/O — a wall-clock guard inside a span of
- * pure computation reads zero however many seconds it burns, which is why the
- * phase costs behind this module had to be recovered from per-turn `cpuTime`
- * rather than measured in place. Bytes are what the work is actually
- * proportional to, and they are exact. The same reasoning is why
- * `git/network-facet.ts` bounds its checkout chunks by entries and decoded
- * bytes and treats its wall guard as coarse.
- */
-/**
- * Bytes of launch work one turn may perform before it must yield.
- *
- * Sized so a chunk stays far below both the CPU ceiling and the span in which
- * a terminal socket is at risk, while keeping the number of turn handoffs —
- * each an alarm round trip — small enough not to dominate a launch. pi's
- * 22.9 MB map crosses this about a dozen times per phase that handles it.
- */
-export const LAUNCH_CHUNK_MAX_BYTES = 2_000_000;
-/**
- * Accounts launch progress and ends the turn when a chunk's worth has been
- * spent.
- *
- * Callers report the work they are about to do or have just done and await
- * the result; a pacer that is not yielding returns without suspending, so the
- * one-shot exec path — which passes no pacer at all — keeps its exact
- * behaviour and cost. Nothing here decides WHAT the launch does, only where it
- * is allowed to stop.
- */
-export class LaunchPacer {
-    scheduler;
-    maxChunkBytes;
-    stillWanted;
-    /** Turn handoffs this launch has taken. Reported with the launch. */
-    chunks = 0;
-    /** Total work accounted, for the same report. */
-    bytes = 0;
-    spent = 0;
-    chunkEnded;
-    /**
-     * @param stillWanted Checked every time the launch resumes. A launch spans
-     *   many turns, so anything may have happened to what it is building for
-     *   while it was suspended; throwing from here is how a launch stops instead
-     *   of spending turn after turn on work nothing will use. Checked at the one
-     *   place a launch can be interrupted, rather than at whichever phases
-     *   remembered to ask.
-     */
-    constructor(scheduler, maxChunkBytes = LAUNCH_CHUNK_MAX_BYTES, stillWanted) {
-        this.scheduler = scheduler;
-        this.maxChunkBytes = maxChunkBytes;
-        this.stillWanted = stillWanted;
-    }
-    /**
-     * Account `bytes` of completed work, ending the turn if a chunk is full.
-     *
-     * Safe to call anywhere the launch holds no state that a concurrent turn
-     * could invalidate — which is why the image store registers its whole root
-     * set before the first call rather than one entry at a time.
-     */
-    async spend(bytes) {
-        this.bytes += bytes;
-        this.spent += bytes;
-        if (this.spent < this.maxChunkBytes)
-            return;
-        this.spent = 0;
-        this.chunks++;
-        // Release the turn that resumed us before asking for the next one.
-        this.chunkEnded?.resolve();
-        const ended = withResolvers();
-        this.chunkEnded = ended;
-        await this.scheduler.nextTurn(ended.promise);
-        this.stillWanted?.();
-    }
-    /**
-     * The launch has finished (or failed). Releases the turn still waiting on
-     * the chunk it resumed, so a launch that ends mid-chunk does not strand the
-     * handler that granted it.
-     */
-    settle() {
-        this.chunkEnded?.resolve();
-        this.chunkEnded = undefined;
-    }
-}
-function withResolvers() {
-    let resolve;
-    const promise = new Promise((r) => { resolve = r; });
-    return { promise, resolve };
-}
-/**
- * Chunk bound for this session, honouring the verification knob.
- *
- * `NIMBUS_LAUNCH_CHUNK_BYTES` forces a small bound so an ordinary launch —
- * not just a pathological one — crosses several turns and exercises every
- * suspension point. Without it the multi-turn path would only ever be
- * reached by the largest programs, which is the same reason
- * `git/commands.ts` carries `NIMBUS_GIT_CHECKOUT_CHUNK_ENTRIES`. Unset in
- * production, where the default applies.
- */
-export function launchChunkMaxBytes(env) {
-    const raw = env
-        ?.NIMBUS_LAUNCH_CHUNK_BYTES;
-    if (!raw)
-        return LAUNCH_CHUNK_MAX_BYTES;
-    const parsed = Number(raw);
-    return Number.isFinite(parsed) && parsed > 0 ? parsed : LAUNCH_CHUNK_MAX_BYTES;
-}

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

@@ -1,207 +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.
- */
-/**
- * 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 declare 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 declare 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 declare const PEER_TRANSIENT_RESET_RETRIES = 3;
-export declare const PEER_RETRY_BACKOFF_MS: number[];
-/**
- * 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 declare const PEER_OVERLOAD_BACKOFF_MS: number[];
-/**
- * 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 declare const FANOUT_PHASE_SIZE = 4;
-/** 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;
-    /**
-     * Invoking process pid, baked into each facet's SUPERVISOR binding so
-     * filesystem RPCs (writeBatchStream) are authorized under the caller's
-     * credential (mirrors NimbusLoaderPool's supervisorPid). Threaded to both
-     * the in-DO loader pool and, via `_rpcFanoutExecute`, the peer-DO pools.
-     * npm install passes the shell command's `ctx.pid`; resolve leaves it 0.
-     */
-    supervisorPid?: number;
-    /**
-     * Called once per completed peer-DO dispatch phase with that phase's shard
-     * count and elapsed ms. Phases are barriers, so this is what tells a caller
-     * whether its fan-out is bounded by shard work or by the number of barriers.
-     * Not called on the in-DO path, which has no phases.
-     */
-    onDispatchPhase?: (width: number, elapsedMs: number) => void;
-    /**
-     * Cap on peer DOs this pool will spread one submitMany across. Defaults to
-     * MAX_PEER_FANOUT. Tasks beyond the cap bucket into the peers that exist and
-     * run through their in-peer pool, so lowering it trades peers for barriers
-     * without lowering total concurrency: each peer runs its bucket at
-     * concurrency 4, so N peers still resolve 4N tasks at once.
-     *
-     * A caller sets this when its per-task work is small enough that a peer per
-     * task buys nothing but round-trips — one task per peer costs ⌈tasks/
-     * FANOUT_PHASE_SIZE⌉ barriers, and each barrier costs a cold sibling start.
-     */
-    maxPeers?: number;
-}
-/**
- * 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   -> 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).
-     */
-    submitMany<A, R>(tasks: FanoutTask<A>[], fn: (item: A, env: any) => R | Promise<R>): Promise<R[]>;
-    /** Report which topology a task count uses without dispatching. */
-    topologyFor(taskCount: number): 'in-do' | 'peer-do' | 'empty';
-    /**
-     * 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: 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

@@ -1 +0,0 @@
-{"version":3,"file":"fanout-pool.d.ts","sourceRoot":"","sources":["../../src/loaders/fanout-pool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAQH;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,IAAI,CAAC;AAEjC;;;GAGG;AACH,eAAO,MAAM,eAAe,KAAK,CAAC;AAElC;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,4BAA4B,IAAI,CAAC;AAC9C,eAAO,MAAM,qBAAqB,UAAmB,CAAC;AAEtD;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,UAAqB,CAAC;AAE3D;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,iBAAiB,IAAI,CAAC;AAEnC,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;IACzB;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7D;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AA4BD;;;;;;;;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,mEAAmE;IACnE,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,GAAG,OAAO;IAK7D;;;;;;OAMG;IACH,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM;YAOvC,aAAa;YAoCb,eAAe;CAyJ9B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAUrE"}