@nimbus-sh/fabric 0.8.0 → 0.10.0

package/dist/budgets.d.ts

@@ -1,34 +1,59 @@
 /**
  * budgets.ts — per-DO accounting for the platform budgets the fabric spends:
- * the Worker Loader's two caps, the facet-ID lifetime budget, and the
- * dynamic-worker module-map ceiling.
+ * the Durable Object's Dynamic Worker concurrency limit, the facet-ID
+ * lifetime budget, and the dynamic-worker module-map ceiling.
  *
- * 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.
+ * The Dynamic Worker model is Cloudflare's documented one
+ * ({@link DO_DYNAMIC_WORKER_LIMIT}): a Durable Object may have a fixed number
+ * of DISTINCT Dynamic Workers with in-flight requests at once, shared across
+ * every concurrent request to that object (one I/O context), and any number
+ * of in-flight requests to the same Dynamic Worker count as one. Only
+ * in-flight requests count: a loader id with nothing in flight holds nothing.
  *
- * 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.
+ * The ledger counts, per hosting actor, the distinct workers that are in
+ * flight right now, keyed by loader id (a fresh key per unkeyed `load`), plus
+ * the width fan-outs have claimed and not yet released. A fan-out spends only
+ * the {@link dynamicWorkerHeadroom} that leaves, so work a Durable Object
+ * already has in flight — a resident process, the esbuild facet, a git
+ * network op, another fan-out — keeps its slots. Work that would rather wait
+ * than be refused waits on the ledger ({@link beginLoaderFetchWhenFree}) and
+ * is let in, in the order it asked, by whichever release makes room.
  *
  * 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
+ * limit is 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`.
+ * Distinct Dynamic Workers one Durable Object may have with in-flight
+ * requests at once, shared across all concurrent requests to that object;
+ * multiple in-flight requests to one Dynamic Worker count once.
+ * https://developers.cloudflare.com/changelog/post/2026-08-28-durable-objects-dynamic-workers-limit/
+ */
+export declare const DO_DYNAMIC_WORKER_LIMIT = 10;
+/**
+ * Ends one hold, idempotently. Pass the error the call failed with, if it
+ * did: a "Dynamic worker concurrency limit exceeded" refusal pauses the
+ * ledger's admissions (see {@link beginLoaderFetchWhenFree}); anything else,
+ * or nothing, just ends the hold.
+ */
+export type EndLoaderFetch = (failure?: unknown) => void;
+/**
+ * A width one fan-out reserved with {@link claimDynamicWorkers}. Holds taken
+ * under it (`beginLoaderFetch(ctx, key, claim)`) count inside that width, not
+ * on top of it, until `release` (idempotent).
+ */
+export interface DynamicWorkerClaim {
+    release(): void;
+}
+/**
+ * Hold the Dynamic Worker `workerKey` in flight on this actor's ledger; the
+ * returned function ends the hold (idempotently), from the caller's own
+ * `finally`. Holds on one key nest: the worker counts once until the last
+ * one ends, as the platform counts it. Under a `claim`, the hold counts
+ * inside the claim's width. This never waits: it is for work the actor
+ * starts regardless (a resident process); {@link beginLoaderFetchWhenFree}
+ * waits for room.
  *
  * 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
@@ -41,19 +66,67 @@ export declare function recordLoaderId(ctx: object, id: string): void;
  * 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;
+export declare function beginLoaderFetch(ctx: object, workerKey: string, claim?: DynamicWorkerClaim): EndLoaderFetch;
+/**
+ * {@link beginLoaderFetch} once the ledger has room: resolves, holding
+ * `workerKey`, as soon as that worker is already in flight (holds on it
+ * count once) or a distinct worker more fits — within the `claim`'s width,
+ * or the actor's headroom. Waits are let in in the order they asked, by
+ * whoever's release makes the room: a hold's end, a claim's release, a
+ * pause's end. The hold is taken as the wait is let in, so a freed slot
+ * wakes one waiter and no other caller can take it first; once resolved, it
+ * is the caller's to end.
+ *
+ * A call refused with "Dynamic worker concurrency limit exceeded" ends its
+ * hold with the refusal (`end(error)`) and waits again: the refusal pauses
+ * admission (50 ms, doubling to 2 s while refusals continue), because the
+ * platform counts a worker for a moment after its call returns and no
+ * release can show that.
+ *
+ * `signal` abandons the wait: it rejects with the signal's reason and holds
+ * nothing. A wait outlives nothing on its own: bound it with a signal when
+ * room may never come (a resident process holds its worker for as long as
+ * it runs).
+ *
+ *   const end = await beginLoaderFetchWhenFree(ctx, key, { signal });
+ *   try { return await worker.getEntrypoint().run(); }
+ *   catch (error) { end(error); throw error; }
+ *   finally { end(); }
+ */
+export declare function beginLoaderFetchWhenFree(ctx: object, workerKey: string, options?: {
+    signal?: AbortSignal;
+    claim?: DynamicWorkerClaim;
+}): Promise<EndLoaderFetch>;
+/**
+ * Distinct Dynamic Workers this actor may still put in flight: the limit
+ * less what is held and claimed right now, and none while a limit refusal's
+ * pause lasts. Never negative.
+ */
+export declare function dynamicWorkerHeadroom(ctx: object): number;
+/**
+ * Claim `width` distinct Dynamic Workers for one fan-out, or null when the
+ * headroom cannot hold it. The claim counts until `release` (idempotent), so
+ * a second fan-out sizing itself meanwhile sees it; the claimant's own
+ * dispatches, held under the claim, count inside it.
+ */
+export declare function claimDynamicWorkers(ctx: object, width: number): DynamicWorkerClaim | null;
 /** Snapshot for the diag surface. Pure read; no I/O. */
 export declare function loaderLedgerStats(ctx: object): {
-    idsEverGotten: string[];
-    liveFetches: number;
-    peakLiveFetches: number;
+    limit: number;
+    inFlightWorkers: string[];
+    claimed: number;
+    headroom: number;
+    peak: number;
+    /** Waits not yet admitted. */
+    waiting: number;
+    /** Length of the pause a limit refusal started, while it lasts; 0 when admitting. */
+    pauseMs: number;
 };
 /**
- * Name the per-DO accounting on a "Too many concurrent dynamic workers"
+ * Name the per-DO accounting on a "Dynamic worker concurrency limit exceeded"
  * 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.
+ * says only that the limit was hit — which workers were in flight, and what
+ * fan-outs had claimed, is what the operator needs to know to shrink anything.
  */
 export declare function withDynamicWorkerCapNamed<E>(ctx: object, error: E): E | Error;
 /**

package/dist/budgets.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"budgets.d.ts","sourceRoot":"","sources":["../src/budgets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;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;AAID;;;;;;;GAOG;AACH,eAAO,MAAM,+BAA+B,WAAa,CAAC;AAE1D;;;;;;;;;;;;;GAaG;AACH,wBAAgB,8BAA8B,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAoBrF;AAuBD;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,QAAS,CAAC;AAE/C,sEAAsE;AACtE,eAAO,MAAM,yBAAyB,iCAAiC,CAAC;AAExE,mEAAmE;AACnE,UAAU,sBAAsB;IAC9B,OAAO,EAAE;QACP,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;QAC7C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;KACjD,CAAC;CACH;AAqCD;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,sBAAsB,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAatF;AAED,4EAA4E;AAC5E,wBAAgB,cAAc,CAAC,GAAG,EAAE,sBAAsB,GAAG,MAAM,CAGlE;AAED,4EAA4E;AAC5E,wBAAsB,qBAAqB,CAAC,GAAG,EAAE,sBAAsB,GAAG,OAAO,CAAC,MAAM,CAAC,CAIxF;AAED;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CACjC,GAAG,EAAE,sBAAsB,GAC1B,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAK/C;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAU9E"}
+{"version":3,"file":"budgets.d.ts","sourceRoot":"","sources":["../src/budgets.ts"],"names":[],"mappings":"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"}

package/dist/budgets.js

@@ -1,46 +1,174 @@
 /**
  * budgets.ts — per-DO accounting for the platform budgets the fabric spends:
- * the Worker Loader's two caps, the facet-ID lifetime budget, and the
- * dynamic-worker module-map ceiling.
+ * the Durable Object's Dynamic Worker concurrency limit, the facet-ID
+ * lifetime budget, and the dynamic-worker module-map ceiling.
  *
- * 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.
+ * The Dynamic Worker model is Cloudflare's documented one
+ * ({@link DO_DYNAMIC_WORKER_LIMIT}): a Durable Object may have a fixed number
+ * of DISTINCT Dynamic Workers with in-flight requests at once, shared across
+ * every concurrent request to that object (one I/O context), and any number
+ * of in-flight requests to the same Dynamic Worker count as one. Only
+ * in-flight requests count: a loader id with nothing in flight holds nothing.
  *
- * 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.
+ * The ledger counts, per hosting actor, the distinct workers that are in
+ * flight right now, keyed by loader id (a fresh key per unkeyed `load`), plus
+ * the width fan-outs have claimed and not yet released. A fan-out spends only
+ * the {@link dynamicWorkerHeadroom} that leaves, so work a Durable Object
+ * already has in flight — a resident process, the esbuild facet, a git
+ * network op, another fan-out — keeps its slots. Work that would rather wait
+ * than be refused waits on the ledger ({@link beginLoaderFetchWhenFree}) and
+ * is let in, in the order it asked, by whichever release makes room.
  *
  * 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
+ * limit is 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/platform/oom-classify.js';
+import { hostWasmIdentity } from './host-wasm.js';
+/**
+ * Distinct Dynamic Workers one Durable Object may have with in-flight
+ * requests at once, shared across all concurrent requests to that object;
+ * multiple in-flight requests to one Dynamic Worker count once.
+ * https://developers.cloudflare.com/changelog/post/2026-08-28-durable-objects-dynamic-workers-limit/
+ */
+export const DO_DYNAMIC_WORKER_LIMIT = 10;
+/**
+ * The first pause after a limit refusal, doubling while refusals continue,
+ * up to {@link REFUSAL_PAUSE_MAX_MS}. A deployed Durable Object admitted a
+ * batch it had refused after a 6 s pause.
+ */
+const REFUSAL_PAUSE_MS = 50;
+const REFUSAL_PAUSE_MAX_MS = 2_000;
 const ledgers = new WeakMap();
+const claimEntries = new WeakMap();
 function ledger(ctx) {
     let entry = ledgers.get(ctx);
     if (!entry) {
-        entry = { ids: new Set(), liveFetches: 0, peakLiveFetches: 0 };
+        entry = {
+            inFlight: new Map(), claims: new Set(), peak: 0,
+            waiters: [], pauseMs: 0, pauseTimer: undefined, epoch: 0, refusals: 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);
+/** Distinct workers counted: each claim's width (or more, if its holds exceed it), plus held keys no claim covers. */
+function inUse(entry) {
+    let count = 0;
+    const covered = new Set();
+    for (const claim of entry.claims) {
+        count += Math.max(claim.width, claim.keys.size);
+        for (const key of claim.keys.keys())
+            covered.add(key);
+    }
+    for (const key of entry.inFlight.keys())
+        if (!covered.has(key))
+            count++;
+    return count;
+}
+function headroom(entry) {
+    return entry.pauseMs > 0 ? 0 : Math.max(0, DO_DYNAMIC_WORKER_LIMIT - inUse(entry));
+}
+function claimOf(ctx, claim) {
+    if (claim === undefined)
+        return undefined;
+    const owned = claimEntries.get(claim);
+    if (owned === undefined || owned.ledger !== ledger(ctx)) {
+        throw new Error('Nimbus: a Dynamic Worker claim is used only on the ledger of the actor that claimed it');
+    }
+    return owned.ledger.claims.has(owned.entry) ? owned.entry : undefined;
+}
+function count(map, key, by) {
+    const open = (map.get(key) ?? 0) + by;
+    if (open > 0)
+        map.set(key, open);
+    else
+        map.delete(key);
+}
+/** Take one hold; the caller admits waiters after. */
+function hold(entry, workerKey, claim) {
+    count(entry.inFlight, workerKey, 1);
+    if (claim)
+        count(claim.keys, workerKey, 1);
+    entry.peak = Math.max(entry.peak, inUse(entry));
+    const epoch = entry.epoch;
+    let ended = false;
+    return (failure) => {
+        if (ended)
+            return;
+        ended = true;
+        count(entry.inFlight, workerKey, -1);
+        if (claim)
+            count(claim.keys, workerKey, -1);
+        if (classifyError(failure) === 'dynamic_worker_cap')
+            refused(entry, epoch);
+        else if (epoch === entry.epoch && entry.pauseMs === 0)
+            entry.refusals = 0;
+        admitWaiters(entry);
+    };
+}
+/**
+ * The platform refused a worker this ledger counted room for: it still
+ * counts workers the ledger has released, which no release here can show.
+ * So nothing new is admitted until a pause has passed. A refusal of a call
+ * that began before the latest pause started or ended is the same lag and
+ * changes nothing; one of a call let in after it doubles the next pause.
+ */
+function refused(entry, epoch) {
+    if (epoch !== entry.epoch)
+        return;
+    if (entry.pauseTimer !== undefined)
+        clearTimeout(entry.pauseTimer);
+    entry.pauseMs = Math.min(REFUSAL_PAUSE_MAX_MS, REFUSAL_PAUSE_MS * 2 ** entry.refusals);
+    entry.refusals++;
+    entry.epoch++;
+    entry.pauseTimer = setTimeout(() => {
+        entry.pauseMs = 0;
+        entry.pauseTimer = undefined;
+        entry.epoch++;
+        admitWaiters(entry);
+    }, entry.pauseMs);
+}
+function admissible(entry, waiter) {
+    // Requests to a worker already in flight count once, even while paused.
+    if (entry.inFlight.has(waiter.key))
+        return true;
+    if (entry.pauseMs > 0)
+        return false;
+    if (waiter.claim && entry.claims.has(waiter.claim) && waiter.claim.keys.size < waiter.claim.width)
+        return true;
+    return inUse(entry) < DO_DYNAMIC_WORKER_LIMIT;
+}
+/**
+ * Let in every waiter that fits, in the order they asked: each takes its
+ * hold here, so a freed slot goes to exactly one waiter and is never left
+ * between a wake and a begin. Run after every change that can make room.
+ * A waiter let in on a new key lets in the later ones on that key, and the
+ * earlier ones too: the scan starts over.
+ */
+function admitWaiters(entry) {
+    for (let i = 0; i < entry.waiters.length;) {
+        const waiter = entry.waiters[i];
+        if (!admissible(entry, waiter)) {
+            i++;
+            continue;
+        }
+        const joins = entry.inFlight.has(waiter.key);
+        entry.waiters.splice(i, 1);
+        waiter.admit(hold(entry, waiter.key, waiter.claim));
+        if (!joins)
+            i = 0;
+    }
 }
 /**
- * Count one call into a dynamic worker as a live Loader fetch; the returned
- * function ends it (idempotently), from the caller's own `finally`.
+ * Hold the Dynamic Worker `workerKey` in flight on this actor's ledger; the
+ * returned function ends the hold (idempotently), from the caller's own
+ * `finally`. Holds on one key nest: the worker counts once until the last
+ * one ends, as the platform counts it. Under a `claim`, the hold counts
+ * inside the claim's width. This never waits: it is for work the actor
+ * starts regardless (a resident process); {@link beginLoaderFetchWhenFree}
+ * waits for room.
  *
  * 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
@@ -53,43 +181,130 @@ export function recordLoaderId(ctx, id) {
  * 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) {
+export function beginLoaderFetch(ctx, workerKey, claim) {
     const entry = ledger(ctx);
-    entry.liveFetches++;
-    entry.peakLiveFetches = Math.max(entry.peakLiveFetches, entry.liveFetches);
-    let ended = false;
-    return () => {
-        if (ended)
+    const end = hold(entry, workerKey, claimOf(ctx, claim));
+    admitWaiters(entry);
+    return end;
+}
+/**
+ * {@link beginLoaderFetch} once the ledger has room: resolves, holding
+ * `workerKey`, as soon as that worker is already in flight (holds on it
+ * count once) or a distinct worker more fits — within the `claim`'s width,
+ * or the actor's headroom. Waits are let in in the order they asked, by
+ * whoever's release makes the room: a hold's end, a claim's release, a
+ * pause's end. The hold is taken as the wait is let in, so a freed slot
+ * wakes one waiter and no other caller can take it first; once resolved, it
+ * is the caller's to end.
+ *
+ * A call refused with "Dynamic worker concurrency limit exceeded" ends its
+ * hold with the refusal (`end(error)`) and waits again: the refusal pauses
+ * admission (50 ms, doubling to 2 s while refusals continue), because the
+ * platform counts a worker for a moment after its call returns and no
+ * release can show that.
+ *
+ * `signal` abandons the wait: it rejects with the signal's reason and holds
+ * nothing. A wait outlives nothing on its own: bound it with a signal when
+ * room may never come (a resident process holds its worker for as long as
+ * it runs).
+ *
+ *   const end = await beginLoaderFetchWhenFree(ctx, key, { signal });
+ *   try { return await worker.getEntrypoint().run(); }
+ *   catch (error) { end(error); throw error; }
+ *   finally { end(); }
+ */
+export function beginLoaderFetchWhenFree(ctx, workerKey, options = {}) {
+    const { signal } = options;
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(signal.reason);
             return;
-        ended = true;
-        entry.liveFetches--;
+        }
+        const entry = ledger(ctx);
+        const abandon = () => {
+            const at = entry.waiters.indexOf(waiter);
+            if (at < 0)
+                return;
+            entry.waiters.splice(at, 1);
+            reject(signal?.reason);
+        };
+        const waiter = {
+            key: workerKey,
+            claim: claimOf(ctx, options.claim),
+            admit(end) {
+                signal?.removeEventListener('abort', abandon);
+                resolve(end);
+            },
+        };
+        entry.waiters.push(waiter);
+        signal?.addEventListener('abort', abandon, { once: true });
+        admitWaiters(entry);
+    });
+}
+/**
+ * Distinct Dynamic Workers this actor may still put in flight: the limit
+ * less what is held and claimed right now, and none while a limit refusal's
+ * pause lasts. Never negative.
+ */
+export function dynamicWorkerHeadroom(ctx) {
+    return headroom(ledger(ctx));
+}
+/**
+ * Claim `width` distinct Dynamic Workers for one fan-out, or null when the
+ * headroom cannot hold it. The claim counts until `release` (idempotent), so
+ * a second fan-out sizing itself meanwhile sees it; the claimant's own
+ * dispatches, held under the claim, count inside it.
+ */
+export function claimDynamicWorkers(ctx, width) {
+    const entry = ledger(ctx);
+    if (width < 1 || width > headroom(entry))
+        return null;
+    const claim = { width, keys: new Map() };
+    entry.claims.add(claim);
+    entry.peak = Math.max(entry.peak, inUse(entry));
+    const handle = {
+        release() {
+            if (!entry.claims.delete(claim))
+                return;
+            admitWaiters(entry);
+        },
     };
+    claimEntries.set(handle, { ledger: entry, entry: claim });
+    return handle;
 }
 /** 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,
+        limit: DO_DYNAMIC_WORKER_LIMIT,
+        inFlightWorkers: [...entry.inFlight.keys()],
+        claimed: claimedWidth(entry),
+        headroom: headroom(entry),
+        peak: entry.peak,
+        waiting: entry.waiters.length,
+        pauseMs: entry.pauseMs,
     };
 }
+function claimedWidth(entry) {
+    let width = 0;
+    for (const claim of entry.claims)
+        width += claim.width;
+    return width;
+}
 /**
- * Name the per-DO accounting on a "Too many concurrent dynamic workers"
+ * Name the per-DO accounting on a "Dynamic worker concurrency limit exceeded"
  * 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.
+ * says only that the limit was hit — which workers were in flight, and what
+ * fan-outs had claimed, 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 });
+    return new Error(`${platform} — this Durable Object had ${entry.inFlight.size} distinct dynamic worker(s) in flight `
+        + `(${[...entry.inFlight.keys()].join(', ') || 'none recorded'}) and ${claimedWidth(entry)} claimed by fan-outs, `
+        + `against a limit of ${DO_DYNAMIC_WORKER_LIMIT}; peak ${entry.peak}`, { cause: error });
 }
 // ── Dynamic-worker module-map ceiling ───────────────────────────────────────
 /**
@@ -136,13 +351,18 @@ export function assertModuleMapWithinCodeLimit(modules) {
 }
 /**
  * Bytes one module-map member carries, across the loader's content kinds
- * (plain string, `{ js | cjs | py | text }`, `{ wasm | data }`). With an
- * encoder, text is measured exactly; without one, by code-unit length.
+ * (plain string, `{ js | cjs | py | text }`, `{ wasm | data }`, a bare
+ * WebAssembly.Module). With an encoder, text is measured exactly; without
+ * one, by code-unit length. A compiled module counts the wire size its host
+ * described (host-wasm.ts); one nobody described counts nothing here and is
+ * left to the platform's own refusal, as the text undercount is.
  */
 function memberBytes(content, encoder) {
     const textBytes = (text) => encoder ? encoder.encode(text).byteLength : text.length;
     if (typeof content === 'string')
         return textBytes(content);
+    if (content instanceof WebAssembly.Module)
+        return hostWasmIdentity(content)?.bytes ?? 0;
     if (content !== null && typeof content === 'object') {
         for (const value of Object.values(content)) {
             if (typeof value === 'string')
@@ -151,6 +371,8 @@ function memberBytes(content, encoder) {
                 return value.byteLength;
             if (ArrayBuffer.isView(value))
                 return value.byteLength;
+            if (value instanceof WebAssembly.Module)
+                return hostWasmIdentity(value)?.bytes ?? 0;
         }
     }
     return 0;

package/dist/do-calls.d.ts

@@ -40,6 +40,7 @@
  * namespace stubs, where the thunk shape is production-proven in Proteus.
  */
 import { type DoCallClass } from '@nimbus-sh/platform/oom-classify.js';
+import { type SpanRecorder } from '@nimbus-sh/platform/tracing.js';
 export interface DoCallRetryPolicy {
     maxAttempts?: number;
     baseDelayMs?: number;
@@ -78,7 +79,26 @@ export interface DoCallRetryPolicy {
      * its error.
      */
     onRetry?(info: DoCallRetryInfo): void;
+    /**
+     * Where the call's telemetry goes: its span's recorder. Each attempt lost
+     * to a transient or overloaded failure is recorded as an exception whose
+     * `code` is the failure's class, and once the call has settled it gets
+     * `do_call.attempts` (started), `do_call.hedges` (started by a hedge),
+     * `do_call.answered_by` (the attempt whose answer the call took, absent
+     * when none answered) and `do_call.outcome` ({@link DoCallOutcome}).
+     * Nothing recorded can change the call's answer. Records nothing when
+     * absent.
+     */
+    span?: SpanRecorder;
 }
+/**
+ * How an `idempotent` call ended: `answered` (an attempt succeeded),
+ * `callee_error` (the callee's own failure, which is an answer),
+ * `exhausted` (the last transient failure, no repeat left), `overloaded`
+ * (shed, nothing repeated after it), or `caller_error` (the resolver or
+ * `onRetry` threw).
+ */
+export type DoCallOutcome = 'answered' | 'callee_error' | 'exhausted' | 'overloaded' | 'caller_error';
 /** What one retry is answering: which call, which platform class, which
  *  attempt just failed out of how many. */
 export interface DoCallRetryInfo {

package/dist/do-calls.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"do-calls.d.ts","sourceRoot":"","sources":["../src/do-calls.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,EAAqC,KAAK,WAAW,EAAE,MAAM,qCAAqC,CAAC;AAU1G,MAAM,WAAW,iBAAiB;IAChC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;;;;;;;;;;OAeG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;;;;OAQG;IACH,OAAO,CAAC,CAAC,IAAI,EAAE,eAAe,GAAG,IAAI,CAAC;CACvC;AAED;2CAC2C;AAC3C,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,WAAW,CAAC;IAC5B;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,OAAO,CAAC;CAChB;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,IAAI,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;AAErD;;;;;GAKG;AACH,qBAAa,WAAY,SAAQ,KAAK;IAElC,QAAQ,CAAC,SAAS,EAAE,MAAM;IAC1B,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,UAAU;IACxC,QAAQ,CAAC,cAAc,EAAE,WAAW;gBAF3B,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,YAAY,GAAG,UAAU,EAC/B,cAAc,EAAE,WAAW,EACpC,KAAK,EAAE,OAAO;CASjB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,CAAC,EAC7B,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,cAAc,CAAC,CAAC,CAAC,EACvB,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,EAC7B,MAAM,GAAE,iBAAsB,GAC7B,OAAO,CAAC,CAAC,CAAC,CAmHZ;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,QAAQ,CAAC,CAAC,EAAE,CAAC,EACjC,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,cAAc,CAAC,CAAC,CAAC,EACvB,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,GAC5B,OAAO,CAAC,CAAC,CAAC,CAUZ"}
+{"version":3,"file":"do-calls.d.ts","sourceRoot":"","sources":["../src/do-calls.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,EAAqC,KAAK,WAAW,EAAE,MAAM,qCAAqC,CAAC;AAE1G,OAAO,EAAY,KAAK,YAAY,EAAE,MAAM,gCAAgC,CAAC;AAS7E,MAAM,WAAW,iBAAiB;IAChC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;;;;;;;;;;;OAeG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;;;;OAQG;IACH,OAAO,CAAC,CAAC,IAAI,EAAE,eAAe,GAAG,IAAI,CAAC;IACtC;;;;;;;;;OASG;IACH,IAAI,CAAC,EAAE,YAAY,CAAC;CACrB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,cAAc,GAAG,WAAW,GAAG,YAAY,GAAG,cAAc,CAAC;AAEtG;2CAC2C;AAC3C,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,WAAW,CAAC;IAC5B;;;OAGG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,OAAO,CAAC;CAChB;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,IAAI,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;AAErD;;;;;GAKG;AACH,qBAAa,WAAY,SAAQ,KAAK;IAElC,QAAQ,CAAC,SAAS,EAAE,MAAM;IAC1B,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,UAAU;IACxC,QAAQ,CAAC,cAAc,EAAE,WAAW;gBAF3B,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,YAAY,GAAG,UAAU,EAC/B,cAAc,EAAE,WAAW,EACpC,KAAK,EAAE,OAAO;CASjB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,CAAC,EAC7B,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,cAAc,CAAC,CAAC,CAAC,EACvB,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,EAC7B,MAAM,GAAE,iBAAsB,GAC7B,OAAO,CAAC,CAAC,CAAC,CAgIZ;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,QAAQ,CAAC,CAAC,EAAE,CAAC,EACjC,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,cAAc,CAAC,CAAC,CAAC,EACvB,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,GAC5B,OAAO,CAAC,CAAC,CAAC,CAUZ"}