@nimbus-sh/fabric 0.1.0

package/dist/fanout-pool.js

@@ -0,0 +1,368 @@
+/**
+ * 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 { serializeFunction } from './vendor/serialize.js';
+import { BindingError } from './vendor/errors.js';
+import { LoaderPool } from './loader-pool.js';
+import { disposeRpcResource } from '@nimbus-sh/core/_shared/rpc-dispose.js';
+import { describeError, isDoOverloaded, isTransientDoReset } from '@nimbus-sh/core/observability/oom-classify.js';
+/**
+ * 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 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 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 const PEER_TRANSIENT_RESET_RETRIES = 3;
+export const PEER_RETRY_BACKOFF_MS = [250, 750, 1500];
+/**
+ * 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 const PEER_OVERLOAD_BACKOFF_MS = [1000, 3000, 6000];
+/**
+ * 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 const FANOUT_PHASE_SIZE = 4;
+function isFanoutPeerStub(value) {
+    if ((typeof value !== 'object' && typeof value !== 'function') || value === null) {
+        return false;
+    }
+    const execute = Reflect.get(value, '_rpcFanoutExecute');
+    return typeof execute === 'function';
+}
+function fanoutPeerStub(value) {
+    if ((typeof value !== 'object' && typeof value !== 'function') || value === null) {
+        throw new BindingError('FanoutPool: NIMBUS_SESSION.get() did not return a peer stub.');
+    }
+    if (!isFanoutPeerStub(value)) {
+        throw new BindingError('FanoutPool: peer stub does not expose _rpcFanoutExecute().');
+    }
+    return value;
+}
+/**
+ * Two-tier fan-out pool. Constructed by the supervisor DO; routes
+ * each `submitMany` call automatically based on width.
+ *
+ * Lifetime: cheap to construct (no async init). Multiple submitMany
+ * calls share NO state — each is dispatched fresh. The class
+ * exists primarily as a clean API surface; per-call dispatch state
+ * lives only inside submitMany's promise.
+ */
+export class FanoutPool {
+    env;
+    ctx;
+    opts;
+    coordDoId;
+    coordDoIdShort;
+    constructor(rawEnv, ctx, opts) {
+        // A host hands its whole env over; the bindings are claimed here and the
+        // LOADER claim is checked immediately. Hard-fail on a missing LOADER —
+        // LoaderPool also enforces this, but checking up front points the
+        // diagnostic at the fanout-pool construction site rather than the
+        // deferred loader-pool one.
+        const env = rawEnv ?? {};
+        if (!env.LOADER || typeof env.LOADER.get !== 'function') {
+            throw new BindingError('FanoutPool: env.LOADER binding missing or invalid. ' +
+                'Add a [[worker_loaders]] entry to wrangler.jsonc.');
+        }
+        this.env = env;
+        this.ctx = ctx;
+        this.opts = opts;
+        this.coordDoId = ctx.id.toString();
+        this.coordDoIdShort = this.coordDoId.slice(0, 12);
+    }
+    /**
+     * Dispatch `tasks` across the appropriate topology and return
+     * results in input order.
+     *
+     * Routing:
+     *   tasks.length < 5   -> 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).
+     */
+    async submitMany(tasks, fn) {
+        if (tasks.length === 0)
+            return [];
+        if (tasks.length < IN_DO_THRESHOLD) {
+            return this._dispatchInDo(tasks, fn);
+        }
+        return this._dispatchPeerDo(tasks, fn);
+    }
+    /** Report which topology a task count uses without dispatching. */
+    topologyFor(taskCount) {
+        if (taskCount === 0)
+            return 'empty';
+        return taskCount < IN_DO_THRESHOLD ? 'in-do' : 'peer-do';
+    }
+    /**
+     * 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, peerCount) {
+        const shard = hashKeyToShard(key, peerCount);
+        return `nbf:${this.opts.tag}:${this.coordDoIdShort}:${shard}`;
+    }
+    // ── Private: in-DO dispatch (in-DO fanout) ──────────────────────────────
+    async _dispatchInDo(tasks, fn) {
+        // Use the existing LoaderPool. Concurrency = task count
+        // (capped at 4 by constructor — tasks.length is already < 5
+        // here, so the cap won't bite). Each task = one pool.submit;
+        // pool.map runs them with stable-slot reuse.
+        const concurrency = Math.min(tasks.length, IN_DO_THRESHOLD - 1);
+        const pool = new LoaderPool(this.env, this.ctx, {
+            concurrency,
+            timeoutMs: this.opts.timeoutMs,
+            tag: this.opts.tag,
+            preamble: this.opts.preamble,
+            wasmModules: this.opts.wasmModules,
+            extraBindings: this.opts.extraBindings,
+            omitSupervisor: this.opts.omitSupervisor,
+            supervisorPid: this.opts.supervisorPid,
+        });
+        try {
+            // pool.map runs the function over `items` with concurrency-bounded
+            // slot reuse. Each slot is one warm loader isolate; we get exactly
+            // `concurrency` loader isolates total — well under the 4-cap.
+            const items = tasks.map((t) => t.args);
+            const results = await pool.map(fn, items);
+            // pool.map returns Array<R | null> (null on per-item failure with
+            // onError='null'/'skip'). Default onError='throw' rejects on
+            // first failure, so successful settle here implies all R values.
+            return results;
+        }
+        finally {
+            try {
+                pool.dispose();
+            }
+            catch { /* best-effort */ }
+        }
+    }
+    // ── Private: peer-DO dispatch (peer-DO fanout) ────────────────────────────
+    async _dispatchPeerDo(tasks, fn) {
+        const ns = this.env?.NIMBUS_SESSION;
+        if (!ns || typeof ns.idFromName !== 'function' || typeof ns.get !== 'function') {
+            throw new BindingError('FanoutPool: env.NIMBUS_SESSION binding missing or invalid. ' +
+                'The peer-DO topology requires it. ' +
+                'Add the binding via durable_objects.bindings in wrangler.jsonc.');
+        }
+        // Serialize the user function ONCE here on the supervisor side.
+        // Each peer DO receives the same fnSource string; warm peer
+        // loader isolates (keyed on fnHash) reuse across calls with
+        // identical fns.
+        const fnSource = serializeFunction(fn);
+        // Cap peer count at MAX_PEER_FANOUT. Tasks beyond N=32 are
+        // bucketed into existing shards — each shard's peer DO then
+        // runs its bucket through its in-DO LoaderPool.map
+        // (concurrency capped at 4 there).
+        const peerCount = Math.min(tasks.length, this.opts.maxPeers ?? MAX_PEER_FANOUT);
+        // Group tasks by deterministic shard. Same key → same shard, so
+        // tests can predict which peer handles which task.
+        const shards = new Map();
+        for (const t of tasks) {
+            const shard = hashKeyToShard(t.key, peerCount);
+            let bucket = shards.get(shard);
+            if (!bucket) {
+                bucket = [];
+                shards.set(shard, bucket);
+            }
+            bucket.push(t);
+        }
+        // Dispatch each shard to its peer DO. Build a map from
+        // task → its place in the original tasks array so we can
+        // reassemble results in input order.
+        const taskIndex = new Map();
+        tasks.forEach((t, i) => {
+            taskIndex.set(t, i);
+        });
+        const results = new Array(tasks.length);
+        // Build one async dispatcher per shard (closure capturing siblingName,
+        // bucket). NOT eagerly-started — wrapped in a thunk so we can stagger
+        // dispatch via Promise chains without forcing all shards to start
+        // simultaneously.
+        const dispatchers = [];
+        for (const [shard, bucket] of shards) {
+            const siblingName = `nbf:${this.opts.tag}:${this.coordDoIdShort}:${shard}`;
+            const id = ns.idFromName(siblingName);
+            const peerArgs = bucket.map((t) => t.args);
+            dispatchers.push(async () => {
+                for (let attempt = 0;; attempt++) {
+                    // Fresh stub per attempt: after a transient reset the previous
+                    // stub points at a torn-down object, so a retry re-resolves the
+                    // sibling by its stable id.
+                    const peerStub = ns.get(id);
+                    const stub = fanoutPeerStub(peerStub);
+                    try {
+                        // Each peer DO RPC call uses ONE LOADER worker on its side.
+                        // Supervisor → peer DO is a stub.fetch / RPC method call,
+                        // NOT an env.LOADER.get(); that's the cap-sidestep that
+                        // makes peer-DO fanout work.
+                        const rpcResp = await stub._rpcFanoutExecute(fnSource, peerArgs, {
+                            tag: this.opts.tag,
+                            timeoutMs: this.opts.timeoutMs,
+                            preamble: this.opts.preamble,
+                            wasmModules: this.opts.wasmModules,
+                            extraBindings: this.opts.extraBindings,
+                            omitSupervisor: this.opts.omitSupervisor,
+                            // INSTALL-HONESTY: forward the COORDINATOR's full doId so
+                            // the peer's LoaderPool can mint a SUPERVISOR
+                            // binding that routes back HERE (the user's session DO),
+                            // not to the peer DO itself. Without this, peer DOs'
+                            // env.SUPERVISOR.writeBatch / writeBatchStream / stdout /
+                            // ... write into the peer's own VFS — invisible to the
+                            // user. See INSTALL-HONESTY-retro.md.
+                            coordinatorDoId: this.coordDoId,
+                            // Credential source for peer-side writeBatchStream — the
+                            // invoking process pid, so package writes are authorized
+                            // as the user (not rejected as pid:0).
+                            supervisorPid: this.opts.supervisorPid,
+                        });
+                        try {
+                            const peerResults = rpcResp.results ?? [];
+                            if (peerResults.length !== bucket.length) {
+                                throw new Error(`peer DO returned ${peerResults.length} results for ${bucket.length} tasks ` +
+                                    `(siblingName=${siblingName})`);
+                            }
+                            // Place each result back into its original input slot.
+                            for (let i = 0; i < bucket.length; i++) {
+                                const origIdx = taskIndex.get(bucket[i]);
+                                if (origIdx === undefined) {
+                                    throw new Error(`peer DO result had no original task index (siblingName=${siblingName})`);
+                                }
+                                results[origIdx] = peerResults[i];
+                            }
+                        }
+                        finally {
+                            disposeRpcResource(rpcResp);
+                        }
+                        return;
+                    }
+                    catch (err) {
+                        const schedule = isTransientDoReset(err) ? PEER_RETRY_BACKOFF_MS
+                            : isDoOverloaded(err) ? PEER_OVERLOAD_BACKOFF_MS
+                                : null;
+                        if (schedule && attempt < PEER_TRANSIENT_RESET_RETRIES) {
+                            const backoff = schedule[Math.min(attempt, schedule.length - 1)];
+                            await new Promise((r) => setTimeout(r, backoff));
+                            continue;
+                        }
+                        // Re-throwing bare loses everything only this frame knows: which
+                        // sibling ran the shard, how wide it was, and how many attempts
+                        // it already cost. Callers report the message, so a rejection the
+                        // platform words as `internal error` arrived at the user with no
+                        // way to tell a one-off peer from a shard that had exhausted its
+                        // retries. `cause` keeps the original for anything that inspects
+                        // errors rather than reads them.
+                        throw new Error(`peer shard ${siblingName} (${bucket.length} task${bucket.length === 1 ? '' : 's'}) `
+                            + `failed after ${attempt + 1} attempt${attempt === 0 ? '' : 's'}: ${describeError(err)}`, { cause: err });
+                    }
+                    finally {
+                        disposeRpcResource(peerStub);
+                    }
+                }
+            });
+        }
+        // Dispatch peer shards in bounded phases. A single Promise.all across all
+        // shards can create too many simultaneous cold sibling DO starts under
+        // concurrent installs. Promise-chain phasing limits scheduler pressure
+        // without sleeps, timers, or idle gaps between phases.
+        //
+        // A phase is a hard barrier: no shard in phase N+1 starts until every
+        // shard in phase N returns, so `width@ms` per phase is what separates
+        // "the shards are slow" from "there are too many barriers".
+        for (let i = 0; i < dispatchers.length; i += FANOUT_PHASE_SIZE) {
+            const phase = dispatchers.slice(i, i + FANOUT_PHASE_SIZE);
+            const phaseStartedAt = Date.now();
+            await Promise.all(phase.map((d) => d()));
+            this.opts.onDispatchPhase?.(phase.length, Date.now() - phaseStartedAt);
+        }
+        return results;
+    }
+}
+/**
+ * Stable hash → shard. Uses a fresh djb2 over the key (NOT
+ * hashSource) and modulos by peerCount.
+ *
+ * Why not reuse hashSource: hashSource returns a base-36 string,
+ * NOT hex — its alphabet is `[0-9a-z]`. parseInt(str, 16) on a
+ * base-36 string aborts at the first non-hex char (any of g-z),
+ * which produces extremely poor distribution: keys with the same
+ * leading-hex-prefix collide regardless of their suffix. (Seen in
+ * the wild: `task-0 .. task-7` all collided onto shard 4.)
+ *
+ * Deterministic: same key + same peerCount → same shard, every run.
+ * Tests use this to predict placement.
+ */
+export function hashKeyToShard(key, peerCount) {
+    if (peerCount <= 1)
+        return 0;
+    // djb2, returning an unsigned 32-bit integer — full 2^32 range,
+    // no string-format conversion gotchas. peerCount <= MAX_PEER_FANOUT
+    // (32) << 2^32, so the modulo distributes uniformly for any input.
+    let h = 5381;
+    for (let i = 0; i < key.length; i++) {
+        h = ((h << 5) + h + key.charCodeAt(i)) | 0;
+    }
+    return (h >>> 0) % peerCount;
+}

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @nimbus-sh/fabric — the Cloudflare-specific DO/facet machinery of Nimbus.
+ *
+ * Root export for workerd contexts. `bindings.ts` imports
+ * `cloudflare:workers`, so importing this root module outside workerd fails
+ * at resolution; non-workerd consumers (tests, tooling) import the subpath
+ * modules they need instead.
+ */
+export * from './alarms.js';
+export * from './bindings.js';
+export * from './ctx-exports.js';
+export * from './facet-image-store.js';
+export * from './fanout-pool.js';
+export * from './inner-do-registry.js';
+export * from './launch-journal.js';
+export * from './launch-pacer.js';
+export * from './loader-ledger.js';
+export * from './loader-pool.js';
+export * from './process-fabric.js';
+export * from './process-host.js';
+export * from './workerd-facet-host.js';
+export * from './ws-hibernation-config.js';
+export * from './vendor/errors.js';
+export * from './vendor/serialize.js';
+export * from './vendor/types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AACjC,cAAc,wBAAwB,CAAC;AACvC,cAAc,kBAAkB,CAAC;AACjC,cAAc,wBAAwB,CAAC;AACvC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,yBAAyB,CAAC;AACxC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,mBAAmB,CAAC"}

package/dist/index.js

@@ -0,0 +1,25 @@
+/**
+ * @nimbus-sh/fabric — the Cloudflare-specific DO/facet machinery of Nimbus.
+ *
+ * Root export for workerd contexts. `bindings.ts` imports
+ * `cloudflare:workers`, so importing this root module outside workerd fails
+ * at resolution; non-workerd consumers (tests, tooling) import the subpath
+ * modules they need instead.
+ */
+export * from './alarms.js';
+export * from './bindings.js';
+export * from './ctx-exports.js';
+export * from './facet-image-store.js';
+export * from './fanout-pool.js';
+export * from './inner-do-registry.js';
+export * from './launch-journal.js';
+export * from './launch-pacer.js';
+export * from './loader-ledger.js';
+export * from './loader-pool.js';
+export * from './process-fabric.js';
+export * from './process-host.js';
+export * from './workerd-facet-host.js';
+export * from './ws-hibernation-config.js';
+export * from './vendor/errors.js';
+export * from './vendor/serialize.js';
+export * from './vendor/types.js';

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

@@ -0,0 +1,41 @@
+/**
+ * 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 the inner worker's own Durable Object classes, as
+ * `worker.getDurableObjectClass(name)` hands them over: opaque tokens whose
+ * only use is `ctx.facets.get(name, { class: cls, id })`, which is exactly what
+ * workerd's `DurableObjectClass` models.
+ */
+/** Look up a registered inner-DO class. Returns undefined if not found. */
+export declare function getInnerDoClass(supervisorDoId: string, bindingName: string): DurableObjectClass | 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: DurableObjectClass): 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/inner-do-registry.d.ts.map

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

package/dist/inner-do-registry.js

@@ -0,0 +1,51 @@
+/**
+ * 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 the inner worker's own Durable Object classes, as
+ * `worker.getDurableObjectClass(name)` hands them over: opaque tokens whose
+ * only use is `ctx.facets.get(name, { class: cls, id })`, which is exactly what
+ * workerd's `DurableObjectClass` models.
+ */
+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);
+    }
+}