@nimbus-sh/fabric 0.1.0

package/dist/launch-pacer.js

@@ -0,0 +1,193 @@
+/**
+ * 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 };
+}
+/**
+ * The granting side of {@link LaunchTurnScheduler}: parks suspended launches
+ * and resumes every one of them when the host grants a fresh turn.
+ */
+export class LaunchTurnPump {
+    host;
+    /**
+     * Launches suspended between chunks, waiting for a turn of their own.
+     *
+     * In-memory on purpose: a launch is only meaningful while the process table
+     * entry it is building for exists, and both are lost together if the isolate
+     * resets. What survives a reset is the journal, which names the launch's
+     * INPUTS rather than its position — a resumed queue would be resurrecting
+     * half-built work for pids that no longer exist, where re-driving a launch
+     * from its inputs is the same idempotent work again.
+     */
+    waiters = [];
+    constructor(host) {
+        this.host = host;
+    }
+    /**
+     * How a paced launch asks for a fresh turn.
+     *
+     * The host grants one by calling {@link pump} from a context that is
+     * genuinely a new invocation — the session's alarm. Without such a host
+     * there is no fresh turn to be had, and the launch continues on this one
+     * rather than hanging: that is exactly the single-turn launch this path has
+     * always performed, so a harness or a runtime without alarms loses the
+     * responsiveness but keeps the behaviour.
+     */
+    nextTurn(chunkEnded) {
+        return new Promise((resume) => {
+            this.waiters.push({ resume, chunkEnded });
+            if (this.host.requestTurn) {
+                this.host.requestTurn();
+                return;
+            }
+            setTimeout(() => { void this.pump(); }, 0);
+        });
+    }
+    /**
+     * Run one chunk of every launch waiting for a turn.
+     *
+     * Awaits the chunk each resumed launch then performs, so the invocation that
+     * granted the turn is the invocation that pays for the work — rather than
+     * releasing it into a handler's microtask drain, where nothing owns it and
+     * the runtime may tear the context down mid-chunk.
+     */
+    async pump() {
+        await this.host.recover?.();
+        const waiting = this.waiters;
+        if (waiting.length === 0)
+            return;
+        this.waiters = [];
+        for (const waiter of waiting)
+            waiter.resume();
+        await Promise.all(waiting.map((waiter) => waiter.chunkEnded));
+    }
+    /** Whether any launch is suspended waiting for a turn. */
+    get hasPending() {
+        return this.waiters.length > 0;
+    }
+}
+/**
+ * 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/loader-ledger.d.ts

@@ -0,0 +1,57 @@
+/**
+ * loader-ledger.ts — per-DO accounting for the Worker Loader's two caps.
+ *
+ * Measured on production workerd: a Durable Object admits ~5–6 concurrent
+ * dynamic workers before the platform refuses with "Too many concurrent
+ * dynamic workers", one DO method can drive at most 4 concurrent Loader
+ * fetches, and loader-cache entries are never released — every DISTINCT
+ * `loader.get(id)` permanently consumes one of the dynamic-worker slots for
+ * the object's lifetime. Nimbus stays under the caps by construction
+ * (`IN_DO_THRESHOLD` = 5 in the fanout pool), which until now meant the slots
+ * were counted in prose. This ledger counts them at the fabric's loader call
+ * sites instead — the loader pool's slots, a resident process's keyed worker,
+ * a one-shot's load — so proximity is measurable and a cap failure can name
+ * the ids actually holding slots.
+ *
+ * Measurement only: no admission control. The caps are the platform's, they
+ * are approximate ("~5–6"), and a gate on an approximate number would refuse
+ * work the platform would have run.
+ *
+ * Keyed weakly off the hosting actor's `ctx`, like the facet slot books: the
+ * caps are per Durable Object, and dynamic workers die with the isolate that
+ * loaded them, so a ledger that goes away with its host describes nothing
+ * that still exists.
+ */
+/** Record a keyed `loader.get(id)` — a permanent slot if the id is new. */
+export declare function recordLoaderId(ctx: object, id: string): void;
+/**
+ * Count one call into a dynamic worker as a live Loader fetch; the returned
+ * function ends it (idempotently), from the caller's own `finally`.
+ *
+ * A begin/end pair rather than a wrapper on purpose, and the shape is
+ * load-bearing: wrapping the stub call in a ledger-owned async frame
+ * (`trackLoaderFetch(ctx, () => entrypoint.execute(...))`) left the hosting
+ * Durable Object poisoned after every pooled dispatch — the next fabric
+ * activity hung the object or reset the instance outright (pid base jumped,
+ * every attached WebSocket dropped with no close frame), measured 7/7 on
+ * staging and gone 3/3 with the direct call restored. Same seam-quirk class
+ * as pipelined `fetch.call`, which workerd refuses for dynamically-loaded
+ * workers: an RPC stub call must stay a direct property call awaited by the
+ * frame that made it, so the ledger only brackets it.
+ */
+export declare function beginLoaderFetch(ctx: object): () => void;
+/** Snapshot for the diag surface. Pure read; no I/O. */
+export declare function loaderLedgerStats(ctx: object): {
+    idsEverGotten: string[];
+    liveFetches: number;
+    peakLiveFetches: number;
+};
+/**
+ * Name the per-DO accounting on a "Too many concurrent dynamic workers"
+ * failure; hand every other error back untouched. The platform's message
+ * says only that the cap was hit — which ids hold the slots, and that a
+ * keyed id can never give one back, is what the operator needs to know to
+ * shrink anything.
+ */
+export declare function withDynamicWorkerCapNamed<E>(ctx: object, error: E): E | Error;
+//# sourceMappingURL=loader-ledger.d.ts.map

package/dist/loader-ledger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader-ledger.d.ts","sourceRoot":"","sources":["../src/loader-ledger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAwBH,2EAA2E;AAC3E,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,CAE5D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,IAAI,CAUxD;AAED,wDAAwD;AACxD,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG;IAC9C,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;CACzB,CAOA;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,GAAG,KAAK,CAW7E"}

package/dist/loader-ledger.js

@@ -0,0 +1,91 @@
+/**
+ * loader-ledger.ts — per-DO accounting for the Worker Loader's two caps.
+ *
+ * Measured on production workerd: a Durable Object admits ~5–6 concurrent
+ * dynamic workers before the platform refuses with "Too many concurrent
+ * dynamic workers", one DO method can drive at most 4 concurrent Loader
+ * fetches, and loader-cache entries are never released — every DISTINCT
+ * `loader.get(id)` permanently consumes one of the dynamic-worker slots for
+ * the object's lifetime. Nimbus stays under the caps by construction
+ * (`IN_DO_THRESHOLD` = 5 in the fanout pool), which until now meant the slots
+ * were counted in prose. This ledger counts them at the fabric's loader call
+ * sites instead — the loader pool's slots, a resident process's keyed worker,
+ * a one-shot's load — so proximity is measurable and a cap failure can name
+ * the ids actually holding slots.
+ *
+ * Measurement only: no admission control. The caps are the platform's, they
+ * are approximate ("~5–6"), and a gate on an approximate number would refuse
+ * work the platform would have run.
+ *
+ * Keyed weakly off the hosting actor's `ctx`, like the facet slot books: the
+ * caps are per Durable Object, and dynamic workers die with the isolate that
+ * loaded them, so a ledger that goes away with its host describes nothing
+ * that still exists.
+ */
+import { classifyError } from '@nimbus-sh/core/observability/oom-classify.js';
+const ledgers = new WeakMap();
+function ledger(ctx) {
+    let entry = ledgers.get(ctx);
+    if (!entry) {
+        entry = { ids: new Set(), liveFetches: 0, peakLiveFetches: 0 };
+        ledgers.set(ctx, entry);
+    }
+    return entry;
+}
+/** Record a keyed `loader.get(id)` — a permanent slot if the id is new. */
+export function recordLoaderId(ctx, id) {
+    ledger(ctx).ids.add(id);
+}
+/**
+ * Count one call into a dynamic worker as a live Loader fetch; the returned
+ * function ends it (idempotently), from the caller's own `finally`.
+ *
+ * A begin/end pair rather than a wrapper on purpose, and the shape is
+ * load-bearing: wrapping the stub call in a ledger-owned async frame
+ * (`trackLoaderFetch(ctx, () => entrypoint.execute(...))`) left the hosting
+ * Durable Object poisoned after every pooled dispatch — the next fabric
+ * activity hung the object or reset the instance outright (pid base jumped,
+ * every attached WebSocket dropped with no close frame), measured 7/7 on
+ * staging and gone 3/3 with the direct call restored. Same seam-quirk class
+ * as pipelined `fetch.call`, which workerd refuses for dynamically-loaded
+ * workers: an RPC stub call must stay a direct property call awaited by the
+ * frame that made it, so the ledger only brackets it.
+ */
+export function beginLoaderFetch(ctx) {
+    const entry = ledger(ctx);
+    entry.liveFetches++;
+    entry.peakLiveFetches = Math.max(entry.peakLiveFetches, entry.liveFetches);
+    let ended = false;
+    return () => {
+        if (ended)
+            return;
+        ended = true;
+        entry.liveFetches--;
+    };
+}
+/** Snapshot for the diag surface. Pure read; no I/O. */
+export function loaderLedgerStats(ctx) {
+    const entry = ledger(ctx);
+    return {
+        idsEverGotten: [...entry.ids],
+        liveFetches: entry.liveFetches,
+        peakLiveFetches: entry.peakLiveFetches,
+    };
+}
+/**
+ * Name the per-DO accounting on a "Too many concurrent dynamic workers"
+ * failure; hand every other error back untouched. The platform's message
+ * says only that the cap was hit — which ids hold the slots, and that a
+ * keyed id can never give one back, is what the operator needs to know to
+ * shrink anything.
+ */
+export function withDynamicWorkerCapNamed(ctx, error) {
+    if (classifyError(error) !== 'dynamic_worker_cap')
+        return error;
+    const entry = ledger(ctx);
+    const platform = error instanceof Error ? error.message : String(error);
+    return new Error(`${platform} — this Durable Object has ${entry.ids.size} loader id(s) permanently `
+        + `holding dynamic-worker slots (a loader.get id is never released): `
+        + `${[...entry.ids].join(', ') || '(none recorded)'}; live Loader fetches ${entry.liveFetches}, `
+        + `peak ${entry.peakLiveFetches}`, { cause: error });
+}

package/dist/loader-pool.d.ts

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

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

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