@nimbus-sh/fabric 0.1.0

package/dist/ctx-exports.d.ts

@@ -0,0 +1,47 @@
+/**
+ * ctx-exports.ts — leaf module holding the ctx.exports reference.
+ *
+ * Isolated from the embedder's entry module so helpers (notably
+ * loader-pool.ts) can read `ctx.exports` without transitively importing the
+ * Durable Object classes. Keeping this a leaf (no imports) lets the pool be
+ * unit-tested in a plain Node/Bun process.
+ *
+ * The embedder's fetch handler calls `setCtxExports(ctx.exports)` on the
+ * first request; callers like the loader pool read via `getCtxExports()`.
+ * If the pool is constructed before the first fetch (unlikely) it just gets
+ * null — the caller decides how to degrade.
+ */
+/**
+ * One entry of `ctx.exports`: a top-level entrypoint's loopback factory, which
+ * mints a Service Binding stub for that entrypoint when called with props.
+ *
+ * The stub's RPC surface belongs to the entrypoint CLASS, which this leaf
+ * cannot see — `Cloudflare.Exports` is derived from the embedder's own main
+ * module, so for a library it evaluates to `{}`. A caller that knows the class
+ * names the surface it expects (`factory<MySupervisorRpc>({ props })`); one
+ * that does not gets `unknown` and has to narrow, same as
+ * `DurableObjectNamespace<T>` and `RpcStub<T>` in @cloudflare/workers-types.
+ */
+export type EntrypointLoopbackFactory = <Stub = unknown>(options: {
+    props: object;
+}) => Stub;
+/**
+ * `ctx.exports` itself — one factory per top-level entrypoint export, keyed by
+ * export name. Absent names read as undefined, which is how a caller finds out
+ * the embedder's entry module does not re-export the class it needs.
+ */
+export type CtxExports = Record<string, EntrypointLoopbackFactory | undefined>;
+export declare function setCtxExports(value: CtxExports): void;
+export declare function getCtxExports(): CtxExports | null;
+export declare function setSupervisorEntrypointName(name: string): void;
+/**
+ * Resolve the registered supervisor entrypoint on an exports object —
+ * `exportsObj` when given (a WorkerEntrypoint reads its own ctx.exports),
+ * the held ctx.exports otherwise. Calling the result with props mints one
+ * supervisor binding (`env.SUPERVISOR`) for one hosted program. Null when
+ * either half is missing; the caller decides whether that degrades or throws.
+ */
+export declare function supervisorEntrypoint(exportsObj?: unknown): EntrypointLoopbackFactory | null;
+/** The registered name, for error messages that point at the missing export. */
+export declare function supervisorEntrypointName(): string | null;
+//# sourceMappingURL=ctx-exports.d.ts.map

package/dist/ctx-exports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ctx-exports.d.ts","sourceRoot":"","sources":["../src/ctx-exports.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;;;;;;;;;GAUG;AACH,MAAM,MAAM,yBAAyB,GAAG,CAAC,IAAI,GAAG,OAAO,EAAE,OAAO,EAAE;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,KAAK,IAAI,CAAC;AAE7F;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,yBAAyB,GAAG,SAAS,CAAC,CAAC;AAI/E,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAGrD;AAED,wBAAgB,aAAa,IAAI,UAAU,GAAG,IAAI,CAEjD;AAUD,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAG9D;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,UAAU,CAAC,EAAE,OAAO,GAAG,yBAAyB,GAAG,IAAI,CAM3F;AAED,gFAAgF;AAChF,wBAAgB,wBAAwB,IAAI,MAAM,GAAG,IAAI,CAExD"}

package/dist/ctx-exports.js

@@ -0,0 +1,54 @@
+/**
+ * ctx-exports.ts — leaf module holding the ctx.exports reference.
+ *
+ * Isolated from the embedder's entry module so helpers (notably
+ * loader-pool.ts) can read `ctx.exports` without transitively importing the
+ * Durable Object classes. Keeping this a leaf (no imports) lets the pool be
+ * unit-tested in a plain Node/Bun process.
+ *
+ * The embedder's fetch handler calls `setCtxExports(ctx.exports)` on the
+ * first request; callers like the loader pool read via `getCtxExports()`.
+ * If the pool is constructed before the first fetch (unlikely) it just gets
+ * null — the caller decides how to degrade.
+ */
+let _ctxExports = null;
+export function setCtxExports(value) {
+    if (_ctxExports)
+        return; // first-write-wins, same as the prior inline impl
+    _ctxExports = value;
+}
+export function getCtxExports() {
+    return _ctxExports;
+}
+/**
+ * The fabric mints supervisor bindings for the programs it hosts, but the
+ * entrypoint class that answers them belongs to the embedder, so its
+ * ctx.exports name is registered once at composition time rather than
+ * hardcoded here. First-write-wins, same as the ctx.exports holder above.
+ */
+let _supervisorEntrypointName = null;
+export function setSupervisorEntrypointName(name) {
+    if (_supervisorEntrypointName)
+        return;
+    _supervisorEntrypointName = name;
+}
+/**
+ * Resolve the registered supervisor entrypoint on an exports object —
+ * `exportsObj` when given (a WorkerEntrypoint reads its own ctx.exports),
+ * the held ctx.exports otherwise. Calling the result with props mints one
+ * supervisor binding (`env.SUPERVISOR`) for one hosted program. Null when
+ * either half is missing; the caller decides whether that degrades or throws.
+ */
+export function supervisorEntrypoint(exportsObj) {
+    const exports = exportsObj ?? _ctxExports;
+    if (!_supervisorEntrypointName)
+        return null;
+    if ((typeof exports !== 'object' && typeof exports !== 'function') || exports === null)
+        return null;
+    const factory = exports[_supervisorEntrypointName];
+    return typeof factory === 'function' ? factory : null;
+}
+/** The registered name, for error messages that point at the missing export. */
+export function supervisorEntrypointName() {
+    return _supervisorEntrypointName;
+}

package/dist/facet-image-store.d.ts

@@ -0,0 +1,112 @@
+/**
+ * facet-image-store.ts — materializing resident-process boot images into the
+ * content-addressed image store, and sweeping the ones nothing boots from.
+ *
+ * A resident process's module map is sized by the user's disk, so it does not
+ * ride inside the boot spec — the store writes it once and the session keeps
+ * only a path (see process-fabric.ts, ResidentCodeSpec.vfsTextModules). This
+ * module owns the write protocol: paced slicing so no one turn holds a
+ * transaction the platform resets the object over, register-roots-before-
+ * first-byte so the sweep can never observe an unrooted image, size-equality
+ * as the completeness test, and a mark-sweep rooted off the live process
+ * table.
+ *
+ * The filesystem itself stays the embedder's, reached through the
+ * {@link FacetImageBlobStore} port — the store decides what is written where
+ * and when; the port decides how bytes land on a disk and with what modes and
+ * credentials.
+ */
+import type { LaunchPacer } from './launch-pacer.js';
+/**
+ * Bytes of an image written in one storage transaction.
+ *
+ * The bound is the VFS's own, not a knob: a `writeRange` whose chunks fit
+ * inside one transaction is committed in place, and one that does not falls
+ * back to copy-on-write — which rewrites every chunk of the file, per slice,
+ * making a sliced write quadratic in its size. A whole number of chunks is
+ * the other half of that: a slice that ends mid-chunk makes the next one read
+ * the partial chunk back to complete it.
+ */
+export declare const FACET_IMAGE_WRITE_SLICE_BYTES: number;
+/**
+ * What the store needs from the disk it writes images to — derived from the
+ * writes it actually performs, nothing more. Modes, credentials and path
+ * normalization are the implementation's: the store passes the same
+ * store-relative paths it later roots and sweeps by.
+ */
+export interface FacetImageBlobStore {
+    /** Create a directory (and its parents) if it does not exist. */
+    mkdirp(dir: string): void;
+    /** The file's current size in bytes, or null when it does not exist. */
+    sizeOf(path: string): number | null;
+    /** Create or REPLACE the file with exactly these bytes (truncating). */
+    writeFile(path: string, bytes: Uint8Array): void;
+    /** Write bytes at an offset, growing the file. */
+    writeRange(path: string, offset: number, bytes: Uint8Array): void;
+    /** Entry names directly under `dir`. Throws when the dir is unreadable. */
+    list(dir: string): string[];
+    /** Remove a file. Throws when it is already gone. */
+    unlink(path: string): void;
+}
+/**
+ * The content-addressed image store of one hosting Durable Object.
+ *
+ * The store is written by the kernel and read by the process, so nothing
+ * here depends on which credential spawned what. Digest collisions are the
+ * hash's problem; everything else is idempotent — an image already present
+ * at its own digest is already the bytes we were about to write.
+ */
+export declare class FacetImageStore {
+    private readonly blobs;
+    private readonly isLive;
+    /** pid → the boot images its facet loads from; the image sweep's root set. */
+    private residentImages;
+    private dirReady;
+    /**
+     * @param blobs The disk the images land on, resolved per use — the embedder
+     *   may not have a filesystem yet when the store is constructed, and throws
+     *   from here when a write is asked for without one.
+     * @param isLive Whether a pid still names a running process. The root set
+     *   is the process table, reached through this one predicate.
+     */
+    constructor(blobs: () => FacetImageBlobStore, isLive: (pid: number) => boolean);
+    /**
+     * The image store's directory, created before the first filesystem view is
+     * built rather than on the first image write.
+     *
+     * Lazily created, it made the store perturb the very view every manifest is
+     * built from: the root listing gained an entry the moment an image landed,
+     * so the next spawn of an identical program generated different text and
+     * addressed a different image. Existing before the first walk makes it
+     * stable.
+     *
+     * Sited on the embedder's exec path and not where its filesystem is
+     * attached, because that runs while the Durable Object is coming up —
+     * including on every wake — and a synchronous filesystem write there costs
+     * the session its startup. Measured: a throwaway built that way stopped
+     * accepting terminal connections at all, while the same build without it
+     * served them.
+     */
+    ensureDir(): void;
+    /**
+     * Materialize generated module sources in the content-addressed image store
+     * and return the module-name → path map naming them.
+     *
+     * Writing the sources here, once, is what lets the session stop holding
+     * them: after this returns, the only thing it keeps is a path.
+     */
+    materialize(pid: number, modules: Record<string, string>, pacer: LaunchPacer): Promise<Record<string, string>>;
+    /**
+     * Drop every image no running process boots from.
+     *
+     * Content addressing means a changed program writes a NEW image rather than
+     * replacing one, so a watch loop — or simply a session that runs a few
+     * different programs — would otherwise leave one bundle-sized file behind
+     * per distinct version. The root set is the process table, which is exact:
+     * an image is live for precisely as long as the process that boots from it.
+     * Nothing is left for a TTL or an eviction heuristic to guess at, and after
+     * a DO reset the table is empty so every orphan goes.
+     */
+    private sweep;
+}
+//# sourceMappingURL=facet-image-store.d.ts.map

package/dist/facet-image-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"facet-image-store.d.ts","sourceRoot":"","sources":["../src/facet-image-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD;;;;;;;;;GASG;AACH,eAAO,MAAM,6BAA6B,QAA0D,CAAC;AAErG;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,iEAAiE;IACjE,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,wEAAwE;IACxE,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IACpC,wEAAwE;IACxE,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;IACjD,kDAAkD;IAClD,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;IAClE,2EAA2E;IAC3E,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC5B,qDAAqD;IACrD,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED;;;;;;;GAOG;AACH,qBAAa,eAAe;IAaxB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM;IAbzB,8EAA8E;IAC9E,OAAO,CAAC,cAAc,CAA+B;IACrD,OAAO,CAAC,QAAQ,CAAS;IAEzB;;;;;;OAMG;gBAEgB,KAAK,EAAE,MAAM,mBAAmB,EAChC,MAAM,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO;IAGnD;;;;;;;;;;;;;;;;OAgBG;IACH,SAAS,IAAI,IAAI;IAOjB;;;;;;OAMG;IACG,WAAW,CACf,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC/B,KAAK,EAAE,WAAW,GACjB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAoDlC;;;;;;;;;;OAUG;IACH,OAAO,CAAC,KAAK;CAgBd"}

package/dist/facet-image-store.js

@@ -0,0 +1,181 @@
+/**
+ * facet-image-store.ts — materializing resident-process boot images into the
+ * content-addressed image store, and sweeping the ones nothing boots from.
+ *
+ * A resident process's module map is sized by the user's disk, so it does not
+ * ride inside the boot spec — the store writes it once and the session keeps
+ * only a path (see process-fabric.ts, ResidentCodeSpec.vfsTextModules). This
+ * module owns the write protocol: paced slicing so no one turn holds a
+ * transaction the platform resets the object over, register-roots-before-
+ * first-byte so the sweep can never observe an unrooted image, size-equality
+ * as the completeness test, and a mark-sweep rooted off the live process
+ * table.
+ *
+ * The filesystem itself stays the embedder's, reached through the
+ * {@link FacetImageBlobStore} port — the store decides what is written where
+ * and when; the port decides how bytes land on a disk and with what modes and
+ * credentials.
+ */
+import { MAX_TX_BLOB_BYTES, CHUNK_SIZE } from '@nimbus-sh/core/constants.js';
+import { FACET_IMAGE_DIR, facetImageDigest, facetImagePath } from './process-fabric.js';
+/**
+ * Bytes of an image written in one storage transaction.
+ *
+ * The bound is the VFS's own, not a knob: a `writeRange` whose chunks fit
+ * inside one transaction is committed in place, and one that does not falls
+ * back to copy-on-write — which rewrites every chunk of the file, per slice,
+ * making a sliced write quadratic in its size. A whole number of chunks is
+ * the other half of that: a slice that ends mid-chunk makes the next one read
+ * the partial chunk back to complete it.
+ */
+export const FACET_IMAGE_WRITE_SLICE_BYTES = Math.floor(MAX_TX_BLOB_BYTES / CHUNK_SIZE) * CHUNK_SIZE;
+/**
+ * The content-addressed image store of one hosting Durable Object.
+ *
+ * The store is written by the kernel and read by the process, so nothing
+ * here depends on which credential spawned what. Digest collisions are the
+ * hash's problem; everything else is idempotent — an image already present
+ * at its own digest is already the bytes we were about to write.
+ */
+export class FacetImageStore {
+    blobs;
+    isLive;
+    /** pid → the boot images its facet loads from; the image sweep's root set. */
+    residentImages = new Map();
+    dirReady = false;
+    /**
+     * @param blobs The disk the images land on, resolved per use — the embedder
+     *   may not have a filesystem yet when the store is constructed, and throws
+     *   from here when a write is asked for without one.
+     * @param isLive Whether a pid still names a running process. The root set
+     *   is the process table, reached through this one predicate.
+     */
+    constructor(blobs, isLive) {
+        this.blobs = blobs;
+        this.isLive = isLive;
+    }
+    /**
+     * The image store's directory, created before the first filesystem view is
+     * built rather than on the first image write.
+     *
+     * Lazily created, it made the store perturb the very view every manifest is
+     * built from: the root listing gained an entry the moment an image landed,
+     * so the next spawn of an identical program generated different text and
+     * addressed a different image. Existing before the first walk makes it
+     * stable.
+     *
+     * Sited on the embedder's exec path and not where its filesystem is
+     * attached, because that runs while the Durable Object is coming up —
+     * including on every wake — and a synchronous filesystem write there costs
+     * the session its startup. Measured: a throwaway built that way stopped
+     * accepting terminal connections at all, while the same build without it
+     * served them.
+     */
+    ensureDir() {
+        if (this.dirReady)
+            return;
+        this.dirReady = true;
+        try {
+            this.blobs().mkdirp(FACET_IMAGE_DIR);
+        }
+        catch { /* a session whose disk is not writable has no images to store */ }
+    }
+    /**
+     * Materialize generated module sources in the content-addressed image store
+     * and return the module-name → path map naming them.
+     *
+     * Writing the sources here, once, is what lets the session stop holding
+     * them: after this returns, the only thing it keeps is a path.
+     */
+    async materialize(pid, modules, pacer) {
+        const fs = this.blobs();
+        const images = {};
+        const sources = new Map();
+        for (const [moduleName, source] of Object.entries(modules)) {
+            const path = facetImagePath(await facetImageDigest(source));
+            images[moduleName] = path;
+            sources.set(path, source);
+            await pacer.spend(source.length);
+        }
+        // Register the WHOLE root set here, in one synchronous step, before any
+        // byte of it exists on disk. That ordering is the entire protocol between
+        // a launch and the sweep: an image is rooted from before it is written, so
+        // a sweep can never observe a file this launch has written but not yet
+        // claimed. The old loop achieved it by not awaiting at all, which read as
+        // "the writes must not be interrupted" — they may be. What must not be
+        // interrupted is the gap between writing and rooting, and rooting first
+        // closes it for every write that follows, however many turns they span.
+        this.residentImages.set(pid, [...sources.keys()]);
+        fs.mkdirp(FACET_IMAGE_DIR);
+        for (const [path, source] of sources) {
+            const stored = path.replace(/^\/+/, '');
+            const bytes = new TextEncoder().encode(source);
+            // An image at its full size is a COMPLETE one: a write only ever grows
+            // the file from offset zero, so a write cut short by a reset leaves a
+            // strictly shorter file and fails this test. Size is enough of a check
+            // because the reader verifies the digest before the loader sees it.
+            if (fs.sizeOf(stored) === bytes.byteLength) {
+                await pacer.spend(bytes.byteLength);
+                continue;
+            }
+            // Sliced because the platform resets the object over what ONE TURN has
+            // outstanding, not over what it eventually writes — pi's 22.9 MB map
+            // went in as a single write and took the session down with it ~25% of
+            // the time. Spending between slices is what puts the rest of the image
+            // on later turns; the slice bound is what keeps any one of them small.
+            let offset = 0;
+            do {
+                const slice = bytes.subarray(offset, offset + FACET_IMAGE_WRITE_SLICE_BYTES);
+                // The first slice REPLACES the file, so an interrupted write's remains
+                // are truncated to a known length rather than left as a tail past this
+                // content.
+                if (offset === 0)
+                    fs.writeFile(stored, slice);
+                else
+                    fs.writeRange(stored, offset, slice);
+                offset += slice.byteLength;
+                await pacer.spend(slice.byteLength);
+            } while (offset < bytes.byteLength);
+        }
+        this.sweep(fs);
+        return images;
+    }
+    /**
+     * Drop every image no running process boots from.
+     *
+     * Content addressing means a changed program writes a NEW image rather than
+     * replacing one, so a watch loop — or simply a session that runs a few
+     * different programs — would otherwise leave one bundle-sized file behind
+     * per distinct version. The root set is the process table, which is exact:
+     * an image is live for precisely as long as the process that boots from it.
+     * Nothing is left for a TTL or an eviction heuristic to guess at, and after
+     * a DO reset the table is empty so every orphan goes.
+     */
+    sweep(fs) {
+        const live = new Set();
+        for (const [pid, paths] of this.residentImages) {
+            if (this.isLive(pid)) {
+                for (const path of paths)
+                    live.add(path);
+            }
+            else {
+                this.residentImages.delete(pid);
+            }
+        }
+        let names;
+        try {
+            names = fs.list(FACET_IMAGE_DIR);
+        }
+        catch {
+            return;
+        }
+        for (const name of names) {
+            if (live.has(`/${FACET_IMAGE_DIR}/${name}`))
+                continue;
+            try {
+                fs.unlink(`${FACET_IMAGE_DIR}/${name}`);
+            }
+            catch { /* already gone */ }
+        }
+    }
+}

package/dist/fanout-pool.d.ts

@@ -0,0 +1,223 @@
+/**
+ * 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 LoaderPool.
+ * Wider batches are sharded across sibling NimbusSession DOs, each of
+ * which owns its own four-loader budget.
+ *
+ * Routing is deterministic: each task has a stable key, and the key maps
+ * to a sibling DO shard. There is no silent fallback to width-1 execution;
+ * missing LOADER or NIMBUS_SESSION bindings fail loudly so install and
+ * runtime operations do not appear successful after partial dispatch.
+ */
+import { type FacetTaskFn } from './loader-pool.js';
+import type { WorkerLoader } from './vendor/types.js';
+/**
+ * The sibling-session namespace the peer-DO topology routes through. Ids are
+ * derived from a name so a task key always lands on the same peer.
+ */
+interface PeerSessionNamespace {
+    idFromName(name: string): DurableObjectId;
+    get(id: DurableObjectId): unknown;
+}
+/** The bindings a fan-out needs off the coordinator DO's env. */
+export interface FanoutPoolEnv {
+    LOADER?: WorkerLoader;
+    NIMBUS_SESSION?: PeerSessionNamespace;
+}
+/**
+ * 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 FanoutPool's constructor. */
+export interface FanoutPoolOptions {
+    /**
+     * 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 LoaderPool'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
+     * LoaderPool's submit calls and to the peer-DO RPC's own
+     * LoaderPool.
+     */
+    timeoutMs?: number;
+    /**
+     * Preamble bundled into every facet (in-DO and inside each peer
+     * DO). Same semantics as LoaderPool's preamble option.
+     */
+    preamble?: string;
+    /**
+     * Wasm modules forwarded to every facet. Same semantics as
+     * LoaderPool's wasmModules option.
+     */
+    wasmModules?: Record<string, ArrayBuffer>;
+    /**
+     * Extra bindings forwarded to every facet. Same semantics as
+     * LoaderPool's extraBindings option.
+     */
+    extraBindings?: Record<string, unknown>;
+    /**
+     * If set, skip the supervisor-RPC binding injection (mirrors
+     * LoaderPool'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 LoaderPool'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 FanoutPool {
+    private readonly env;
+    private readonly ctx;
+    private readonly opts;
+    private readonly coordDoId;
+    private readonly coordDoIdShort;
+    constructor(rawEnv: unknown, ctx: DurableObjectState, opts: FanoutPoolOptions);
+    /**
+     * Dispatch `tasks` across the appropriate topology and return
+     * results in input order.
+     *
+     * Routing:
+     *   tasks.length < 5   -> coordinator-local LoaderPool
+     *   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
+     * LoaderPool'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 LoaderPool.submit. The function is serialized via
+     * the vendored serializeFunction (same as LoaderPool#prepare).
+     */
+    submitMany<A, R>(tasks: FanoutTask<A>[], fn: FacetTaskFn<A, 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;
+export {};
+//# sourceMappingURL=fanout-pool.d.ts.map

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

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