@nimbus-sh/fabric 0.7.0 → 0.8.0

package/dist/workerd-facet-host.js

@@ -13,9 +13,11 @@
  * `HostedProcess` and never imports this file.
  */
 import { disposeRpcResource } from '@nimbus-sh/platform/rpc-dispose.js';
+import { StorageLedger, forgetFacetStorage } from '@nimbus-sh/core/runtime/storage-ledger.js';
 import { getCtxExports, stagedBootAssembler, supervisorEntrypoint, supervisorEntrypointName, } from './composition.js';
 import { assertModuleMapWithinCodeLimit, beginLoaderFetch, facetNameCount, facetNameCountDurable, recordFacetNameMinted, recordLoaderId, withDynamicWorkerCapNamed, withFacetBudgetNamed, } from './budgets.js';
 import { RESIDENT_PROCESS_CLASS, residentLoaderConfig, } from './process-fabric.js';
+import { supervisorLoaderKey } from './supervisor-props.js';
 export function getNimbusCtxExports() {
     const ctxExports = getCtxExports();
     if (!ctxExports || typeof ctxExports !== 'object') {
@@ -35,7 +37,9 @@ export async function createLoadedWorkerEntrypoint(ctxExports, supervisor, stage
     }
     return await ctxExports.NimbusLoadedEntrypoint({
         props: {
-            key: `nimbus-process:${supervisor.doId}:${supervisor.pid}`,
+            // The entrypoint's loader outlives this instance, and a warm worker keeps
+            // the SUPERVISOR binding it was built with.
+            key: supervisorLoaderKey(`nimbus-process:${supervisor.doId}:${supervisor.pid}`, supervisor),
             name,
             depth: 0,
             supervisor,
@@ -126,37 +130,38 @@ export const DURABLE_FACET_NAME_PREFIX = 'app-slot-';
  * Slot books, per hosting actor, because the facet index is per Durable
  * Object.
  *
- * Keyed weakly off `ctx`, and that is sound rather than lossy: a facet cannot
- * outlive the Durable Object hosting it, so a book that goes away with its
- * host describes nothing that still exists. A fresh incarnation restarts at
- * slot 0 and re-attaches to the SQLite a previous incarnation left there —
- * which is safe for the reason the store is sealed until it has reconciled.
- * Its persisted cursor is either datable against the current authority, in
- * which case the ACQUIRE delta brings it current, or it carries a different
- * VFS epoch, in which case `invalidatedSince` can only answer poison and the
- * whole store is dropped. A process therefore cannot boot onto a previous
- * tenant's filesystem even when release never ran.
+ * Keyed weakly off `ctx`, so a book describes one incarnation. A facet that
+ * is still running when that incarnation ends outlives it (measured: a timer
+ * or an outgoing call keeps it going), and a `get` of its name with a new
+ * class then resets the whole object. So a fresh incarnation's first get of
+ * each name ends whatever runs there first: a minted `proc-slot-` name is
+ * deleted, which also wipes the storage a previous incarnation left, and an
+ * explicit name is aborted, which keeps it.
  *
- * The book names only the `proc-slot-` space. Durable `app-slot-` names are
- * allocated against DO storage instead (their owner survives a reset), so a
- * fresh incarnation's `next` starting at 0 can never collide with them even
+ * The book allocates only the `proc-slot-` space. Durable `app-slot-` names
+ * are allocated against DO storage instead (their owner survives a reset), so
+ * a fresh incarnation's `next` starting at 0 can never collide with them even
  * before the durable ledger is adopted.
  */
 const slotBooks = new WeakMap();
 function slotBook(ctx) {
     let book = slotBooks.get(ctx);
     if (!book) {
-        book = { free: [], next: 0, held: new Map() };
+        book = { free: [], next: 0, held: new Map(), live: new Set() };
         slotBooks.set(ctx, book);
     }
     return book;
 }
-/** Take a slot for `pid`, reusing a returned one before minting a new name. */
+/**
+ * Take a slot for `pid`, reusing a returned one before minting a new name.
+ * `minted` names may still hold storage a previous incarnation of this actor
+ * left there, so the caller deletes it before the first get.
+ */
 function acquireSlot(ctx, pid) {
     const book = slotBook(ctx);
     const existing = book.held.get(pid);
     if (existing !== undefined)
-        return existing;
+        return { slot: existing, minted: false };
     const reused = book.free.length > 0;
     const slot = reused ? book.free.shift() : book.next++;
     book.held.set(pid, slot);
@@ -164,7 +169,7 @@ function acquireSlot(ctx, pid) {
     // in the budgets ledger (see budgets.ts).
     if (!reused)
         recordFacetNameMinted(ctx, book.next);
-    return slot;
+    return { slot, minted: !reused };
 }
 /** Return `pid`'s slot to the free list. */
 function releaseSlot(ctx, pid) {
@@ -177,14 +182,34 @@ function releaseSlot(ctx, pid) {
     book.free.sort((a, b) => a - b);
 }
 /**
- * Drop one facet's SQLite by name — the ONLY call site that may delete facet
- * storage. `spawnResident` releases ephemeral processes with abort+delete
- * (storage is slot-reuse hygiene) and durable ones with abort alone (the
- * storage IS the durable application's state); explicit removal arrives here
- * through the coordinator's durable-slot book, owner-checked.
+ * Drop one facet's SQLite by name, and its row in the session's storage
+ * ledger (N18) in the same step: the only way a facet database is deleted.
+ * `spawnResident` releases ephemeral processes with abort+delete (storage is
+ * slot-reuse hygiene) and durable ones with abort alone (the storage IS the
+ * durable application's state); explicit removal arrives here through the
+ * coordinator's durable-slot book, owner-checked.
  */
+/** The session's storage ledger (N18), over this actor's SQL; null where it has none. */
+function sessionLedger(ctx) {
+    const sql = ctx.storage?.sql;
+    return sql ? new StorageLedger(sql) : null;
+}
+const facetNames = new WeakMap();
+function facetOfPid(ctx) {
+    let names = facetNames.get(ctx);
+    if (!names)
+        facetNames.set(ctx, names = new Map());
+    return names;
+}
+/** The facet a running resident process `pid` lives in on this actor, for its storage ledger row. */
+export function residentFacetOf(ctx, pid) {
+    return facetNames.get(ctx)?.get(pid);
+}
 export function deleteFacetStorage(ctx, name) {
     facetContainer(ctx).delete(name);
+    const sql = ctx.storage?.sql;
+    if (sql)
+        forgetFacetStorage(sql, name);
 }
 /**
  * The process surface of one hosting actor: how a resident process comes
@@ -241,8 +266,15 @@ function spawnResident(ctx, env, disk, supervisor, params) {
         throw new Error(`Nimbus: an explicit facet name must carry the '${DURABLE_FACET_NAME_PREFIX}' `
             + `prefix, got '${explicit.name}'`);
     }
-    const slot = explicit ? undefined : acquireSlot(ctx, params.pid);
+    const grant = explicit ? undefined : acquireSlot(ctx, params.pid);
+    const slot = grant?.slot;
     const name = explicit ? explicit.name : residentFacetName(slot);
+    if (grant?.minted) {
+        try {
+            deleteFacetStorage(ctx, name);
+        }
+        catch { /* nothing stored under this name */ }
+    }
     // The start callback is the ONLY way this facet is ever created, and it
     // fires AT MOST ONCE. Every later use goes through the stub below, so the
     // callback running a second time means the facet was released or died —
@@ -262,8 +294,18 @@ function spawnResident(ctx, env, disk, supervisor, params) {
         evaluated = true;
         return { class: residentProcessClass(ctx, env, disk, supervisor, params) };
     };
+    const book = slotBook(ctx);
+    const ledger = sessionLedger(ctx);
     let facet;
     try {
+        // N18: the fill is admitted, and recorded under the facet's name, before
+        // the facet exists; a refusal leaves no facet.
+        if (ledger !== null && params.storageBytes !== undefined)
+            ledger.fill(name, params.storageBytes);
+        // get() with a new class on a facet an earlier incarnation left running resets this object.
+        if (explicit && !book.live.has(name)) {
+            facets.abort(name, new Error('Nimbus: a new incarnation takes this facet name'));
+        }
         facet = facets.get(name, start);
     }
     catch (error) {
@@ -271,16 +313,22 @@ function spawnResident(ctx, env, disk, supervisor, params) {
             releaseSlot(ctx, params.pid);
         throw withFacetBudgetNamed(facetNameCount(ctx), error);
     }
+    if (explicit)
+        book.live.add(name);
+    facetOfPid(ctx).set(params.pid, name);
     let disposed = false;
     const release = async () => {
         if (disposed)
             return;
         disposed = true;
         released = true;
+        facetOfPid(ctx).delete(params.pid);
         try {
             facets.abort(name, new Error('Nimbus: resident process released'));
         }
         catch { /* already gone */ }
+        if (explicit)
+            book.live.delete(name);
         // The two release classes: an ephemeral facet's SQLite is slot-reuse
         // hygiene — the name is handed out again, so the store must not be — and
         // a durable one's is the application itself: abort ends the process, the
@@ -288,7 +336,7 @@ function spawnResident(ctx, env, disk, supervisor, params) {
         // deleteFacetStorage call ever drops it.
         if (!explicit?.durable) {
             try {
-                facets.delete(name);
+                deleteFacetStorage(ctx, name);
             }
             catch { /* already gone */ }
         }
@@ -299,7 +347,11 @@ function spawnResident(ctx, env, disk, supervisor, params) {
     };
     let started;
     try {
-        started = facet.startProcess(params.startArgs);
+        // The allowance the ledger admitted, for the facet's store to keep under.
+        const startArgs = ledger !== null && params.storageBytes !== undefined && params.startArgs !== null && typeof params.startArgs === 'object'
+            ? { ...params.startArgs, storage: { facet: name, grant: params.storageBytes } }
+            : params.startArgs;
+        started = facet.startProcess(startArgs);
     }
     catch (error) {
         void release();
@@ -309,7 +361,18 @@ function spawnResident(ctx, env, disk, supervisor, params) {
     // this one, and it is annotated AFTER awaiting the ledger — the first
     // failure of a fresh incarnation must compare against the persisted count,
     // not the zero its adoption read has not yet replaced.
-    started = started.catch(async (error) => {
+    started = started.then((payload) => {
+        // Once the facet is up (N18) its row is the cap its store keeps under
+        // (what it measures plus what it may still grow into), or what it
+        // measures if that is more (overshoot).
+        const { databaseSize: size, storageCap: cap } = (payload ?? {});
+        const measured = typeof size === 'number' && Number.isFinite(size) ? size : null;
+        const capped = typeof cap === 'number' && Number.isFinite(cap) ? cap : null;
+        const row = capped !== null ? Math.max(capped, measured ?? 0) : measured;
+        if (ledger !== null && row !== null)
+            ledger.reportSize(name, row);
+        return payload;
+    }, async (error) => {
         throw withFacetBudgetNamed(await facetNameCountDurable(ctx), error);
     });
     // A caller reads whichever of `started` and the lifecycle it needs, so keep
@@ -339,11 +402,14 @@ function residentProcessClass(ctx, env, disk, supervisor, params) {
         throw new Error('Nimbus: env.LOADER binding missing or invalid. Resident processes require '
             + 'the Worker Loader binding; add it via worker_loaders in wrangler.jsonc.');
     }
+    // A warm worker keeps the SUPERVISOR binding it was built with, and the
+    // loader outlives this instance.
+    const loaderKey = supervisorLoaderKey(params.workerKey, supervisor);
     try {
         const worker = loader
-            .get(params.workerKey, () => residentWorkerConfig(env, disk, supervisor, params.boot))
+            .get(loaderKey, () => residentWorkerConfig(env, disk, supervisor, params.boot))
             .getDurableObjectClass(RESIDENT_PROCESS_CLASS);
-        recordLoaderId(ctx, params.workerKey);
+        recordLoaderId(ctx, loaderKey);
         return worker;
     }
     catch (error) {
@@ -356,7 +422,7 @@ async function runOneShot(ctx, env, supervisor, params, consume) {
         throw new Error('Nimbus: env.LOADER binding missing or invalid. Running a program requires '
             + 'the Worker Loader binding; add it via worker_loaders in wrangler.jsonc.');
     }
-    const supervisorRpc = supervisorEntrypoint();
+    const supervisorRpc = supervisorEntrypoint(undefined, supervisor.route?.supervisorEntrypoint);
     let supervisorBinding;
     let worker;
     let entrypoint;
@@ -439,9 +505,9 @@ export async function residentWorkerConfig(env, disk, supervisor, boot) {
         ? await stagedBootAssembler()(env, boot.stage)
         : await residentLoaderConfig(boot.code, disk());
     assertModuleMapWithinCodeLimit(configModules(config));
-    const supervisorRpc = supervisorEntrypoint();
+    const supervisorRpc = supervisorEntrypoint(undefined, supervisor.route?.supervisorEntrypoint);
     if (!supervisorRpc) {
-        throw new Error(`Nimbus: ctx.exports.${supervisorEntrypointName() ?? '<supervisor entrypoint>'} unavailable`);
+        throw new Error(`Nimbus: ctx.exports.${supervisor.route?.supervisorEntrypoint ?? supervisorEntrypointName() ?? '<supervisor entrypoint>'} unavailable`);
     }
     return { ...config, env: { SUPERVISOR: supervisorRpc({ props: supervisor }) } };
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nimbus-sh/fabric",
-  "version": "0.7.0",
-  "description": "The Cloudflare half of Nimbus — Durable Object facet hosting, dynamic-worker loader pools, the resident-process fabric, and DO alarm/hibernation machinery.",
+  "version": "0.8.0",
+  "description": "The Cloudflare half of Nimbus \u2014 Durable Object facet hosting, dynamic-worker loader pools, the resident-process fabric, and DO alarm/hibernation machinery.",
   "keywords": [
     "cloudflare",
     "workers",
@@ -45,13 +45,13 @@
     "LICENSE"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.json --noCheck --noEmit false --declaration true --declarationMap true --outDir dist --rootDir src",
-    "prepack": "bun run build",
+    "build": "node ../../scripts/clean-dist.mjs && tsc -p tsconfig.json --noCheck --noEmit false --declaration true --declarationMap true --outDir dist --rootDir src",
+    "prepublishOnly": "bun ../../scripts/dist-integrity.mjs --publish",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@nimbus-sh/core": "^0.11.0",
-    "@nimbus-sh/platform": "^0.5.0",
+    "@nimbus-sh/core": "^0.13.0",
+    "@nimbus-sh/platform": "^0.6.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {

package/src/bindings.ts

@@ -26,8 +26,8 @@
 import { WorkerEntrypoint } from 'cloudflare:workers';
 import { z } from 'zod/v4';
 import { disposeRpcResource, useRpcResource } from '@nimbus-sh/platform/rpc-dispose.js';
-import { hostNamespace, supervisorEntrypoint, supervisorEntrypointName } from './composition.js';
-import { stagedBootAssembler } from './composition.js';
+import { hostNamespace, supervisorEntrypoint, supervisorEntrypointName, stagedBootAssembler } from './composition.js';
+import type { HostRoute } from './composition.js';
 import { hostNamespaceBinding, hostOpDispatch, type HostOpDispatch } from './host-dispatch.js';
 import { assertModuleMapWithinCodeLimit } from './budgets.js';
 import type { EntrypointLoopbackFactory } from './composition.js';
@@ -114,6 +114,8 @@ interface NimbusAssetsProps {
   assetsDir?: string;
   /** Supervisor DO id whose VFS holds the assets. */
   doId?: string;
+  /** The way back to that DO, minted with the binding. */
+  route?: HostRoute;
 }
 
 /**
@@ -164,9 +166,9 @@ export class NimbusAssetsRPC extends WorkerEntrypoint<object, NimbusAssetsProps>
     let stub: DurableObjectStub | null = null;
     let dispatch: HostOpDispatch;
     try {
-      const ns = hostNamespaceBinding(this.env, 'NimbusAssetsRPC');
+      const ns = hostNamespaceBinding(this.env, 'NimbusAssetsRPC', props.route);
       stub = ns.get(ns.idFromString(doId));
-      dispatch = hostOpDispatch(stub, 'NimbusAssetsRPC');
+      dispatch = hostOpDispatch(stub, 'NimbusAssetsRPC', props.route);
     } catch (e) {
       disposeRpcResource(stub);
       return new Response(`ASSETS binding not wired: ${e instanceof Error ? e.message : String(e)}`, { status: 500 });
@@ -307,6 +309,12 @@ const _NIMBUS_LOADED_CODES: Map<string, WorkerCode> = new Map();
 const _LOADED_CODES_MAX = 32;
 let _loadedCodesEvictions = 0;
 
+const HostRouteSchema = z.object({
+  supervisorEntrypoint: z.string().min(1),
+  hostNamespace: z.string().min(1),
+  hostDispatchMethod: z.string().min(1),
+});
+
 const NimbusLoadedEntrypointPropsSchema = z.object({
   key: z.string().min(1),
   name: z.string().nullable().optional(),
@@ -315,6 +323,9 @@ const NimbusLoadedEntrypointPropsSchema = z.object({
     doId: z.string().min(1),
     pid: z.number().int().nonnegative(),
     writerId: z.string().uuid(),
+    route: HostRouteSchema.optional(),
+    /** The host instance's delivery incarnation (ResidentSupervisorProps). */
+    hostIncarnation: z.string().uuid().optional(),
   }).optional(),
   /**
    * Staged-artifact spec, for a ONE-SHOT run. The module map — ~23 MB for
@@ -532,11 +543,12 @@ export class NimbusLoadedEntrypoint extends WorkerEntrypoint<NimbusLoaderShimEnv
 
   async _supervisorBinding(props: NimbusLoadedEntrypointProps): Promise<unknown> {
     if (!props.supervisor) return undefined;
-    const factory = supervisorEntrypoint(ctxExportsOf(this.ctx));
+    // The route names the entrypoint too: this stateless hop may run in an
+    // isolate whose composition is not the host's.
+    const name = props.supervisor.route?.supervisorEntrypoint ?? supervisorEntrypointName();
+    const factory = supervisorEntrypoint(ctxExportsOf(this.ctx), name ?? undefined);
     if (!factory) {
-      throw new Error(
-        `Nimbus: ctx.exports.${supervisorEntrypointName() ?? '<supervisor entrypoint>'} unavailable`,
-      );
+      throw new Error(`Nimbus: ctx.exports.${name ?? '<supervisor entrypoint>'} unavailable`);
     }
     return await factory({ props: props.supervisor });
   }
@@ -691,6 +703,8 @@ export class NimbusLoadedEntrypoint extends WorkerEntrypoint<NimbusLoaderShimEnv
 interface NimbusDoNamespaceProps {
   bindingName?: string;
   supervisorDoId?: string;
+  /** The way back to the supervisor DO, minted with the binding. */
+  route?: HostRoute;
 }
 
 /**
@@ -755,6 +769,7 @@ export class NimbusDurableObjectNamespace extends WorkerEntrypoint<unknown, Nimb
       props: {
         bindingName: props.bindingName,
         supervisorDoId: props.supervisorDoId,
+        route: props.route,
         id: String(id),
       },
     });
@@ -789,9 +804,9 @@ export class NimbusDOStub extends WorkerEntrypoint<object, NimbusDoStubProps> {
     let stub: DurableObjectStub | null = null;
     let dispatch: HostOpDispatch;
     try {
-      const ns = hostNamespaceBinding(this.env ?? {}, 'NimbusDOStub');
+      const ns = hostNamespaceBinding(this.env ?? {}, 'NimbusDOStub', props.route);
       stub = ns.get(ns.idFromString(supervisorDoId));
-      dispatch = hostOpDispatch(stub, 'NimbusDOStub');
+      dispatch = hostOpDispatch(stub, 'NimbusDOStub', props.route);
     } catch (e) {
       disposeRpcResource(stub);
       return new Response(`Nimbus: ${e instanceof Error ? e.message : String(e)}`, { status: 500 });

package/src/connections.ts

@@ -3,7 +3,7 @@
  * state over the WebSocket attachment.
  *
  * Specified from Proteus's DeviceSocketHub (`cf-backend/src/user/device-hub.ts`)
- * and CLI rpc gate (`cf-backend/src/cli/rpc-gate.ts`), which split the
+ * and its original CLI rpc gate (`cf-backend/src/cli/rpc-gate.ts`), which split the
  * pattern into its two halves:
  *   - a TAG is the immutable-at-accept lookup key and authorization — it
  *     rides the hibernation state, which is why the rpc gate persists auth

package/src/do-calls.ts

@@ -3,12 +3,14 @@
  * the one property that decides whether a retry is safe.
  *
  * Both consumers asked for this. Proteus hand-wrote the retry
- * (`cf-backend/src/lib/do-rpc.ts`) with the rule its header states:
+ * (originally `cf-backend/src/lib/do-rpc.ts`) with the rule its header states:
  * "An operation that appends, sends, charges or mints is never wrapped: a
  * dropped call there may already have run, so a retry is a correctness bug
  * wearing resilience as a costume." agent-core has no retry machinery at all
  * and its backlog calls the gap "the most production-proven gap in the
  * corpus". Here the rule is a type: `idempotent` retries, `mutating` cannot.
+ * A mutation earns a retry only by carrying an identity its callee applies
+ * at most once; it is then `idempotent` by construction (see `mutating`).
  *
  * What the platform contract requires, and this keeps:
  *   - a FRESH stub per attempt. Cloudflare documents that many exceptions
@@ -20,6 +22,11 @@
  *     object is what overloaded it.
  *   - attempts and backoff are the consumer-proven bounds: 3 attempts total,
  *     full-jitter delays in [0, 2**attempt * 60ms).
+ *   - an `idempotent` call may also be HEDGED (`hedgeAfterMs`): an attempt
+ *     that has not answered by then is joined by the same call on a fresh
+ *     stub, both left running, the first success taken. Hedges count
+ *     against the attempts, and a callee that joins a repeat to the call it
+ *     is already serving makes one that did arrive cost nothing.
  *
  * The resolver MINTS a stub per call and the verb disposes each one it
  * minted — that ownership is what makes the fresh-stub retry real.
@@ -47,10 +54,38 @@ export interface DoCallRetryPolicy {
   maxAttempts?: number;
   baseDelayMs?: number;
   /**
-   * Called once per retry, before its backoff delay, with the failure the
-   * retry is answering. The consumer's logging seam: Proteus's hand-rolled
-   * predecessor logged every retry so a flaky object is visible in Workers
-   * Logs rather than silently absorbed, and `operation` names it there.
+   * No repeat — retry or hedge — starts once this long has passed since the
+   * first attempt did; the failure in hand surfaces instead. A mutation made
+   * repeatable by an identity its callee dedupes needs it: the callee keeps
+   * what answers a repeat for a bounded time, so the caller's repeats must
+   * stop well inside it. Unbounded when absent.
+   */
+  retryWindowMs?: number;
+  /**
+   * Hedge an attempt that has not answered after this long: send the same
+   * call again on a fresh stub while the first stays in flight. The caller
+   * gets the first success; an answer after it is disposed and dropped. That
+   * is only harmless when a second delivery of the call changes nothing — a
+   * read — and cheap only when the callee joins a repeat to the call it is
+   * already serving. A hedge is an attempt: it counts against `maxAttempts`,
+   * and has its own deadline. Never hedged when absent.
+   *
+   * With attempts overlapping, a failure decides less. A retryable one is
+   * retried after its backoff while attempts remain, and `overloaded` stops
+   * every further repeat; either way the call keeps waiting on the attempts
+   * still in flight, and fails with the last failure only once none is. Any
+   * other failure is the callee's answer — the call ran — and is the call's
+   * at once.
+   */
+  hedgeAfterMs?: number;
+  /**
+   * Called once per retry, as it starts — after its backoff delay — with the
+   * failure the retry is answering. A retry a hedge made unnecessary, or
+   * that no attempt is left for, is never announced. The consumer's logging
+   * seam: Proteus's hand-rolled predecessor logged every retry so a flaky
+   * object is visible in Workers Logs rather than silently absorbed, and
+   * `operation` names it there. A callback that throws fails the call with
+   * its error.
    */
   onRetry?(info: DoCallRetryInfo): void;
 }
@@ -60,7 +95,10 @@ export interface DoCallRetryPolicy {
 export interface DoCallRetryInfo {
   operation: string;
   classification: DoCallClass;
-  /** The 1-based attempt that failed; the retry about to run is attempt+1. */
+  /**
+   * The 1-based number of the attempt that failed. Without hedging the retry
+   * is attempt+1; with it, other attempts may have started in between.
+   */
   attempt: number;
   maxAttempts: number;
   error: unknown;
@@ -102,11 +140,20 @@ export class DoCallError extends Error {
 
 /**
  * Call another Durable Object with an operation that is safe to repeat: a
- * read, or a converge-to-a-value write. Transient failures retry on a fresh
- * stub with full-jitter backoff; overloaded and permanent failures surface
- * unchanged, as does the last error at exhaustion.
+ * read, a converge-to-a-value write, or a mutation carrying an identity its
+ * callee applies at most once (see {@link mutating}). Transient failures
+ * retry on a fresh stub with full-jitter backoff; overloaded and permanent
+ * failures surface unchanged, as does the last error once no attempt may be
+ * repeated — attempts spent, or the policy's retry window closed. With
+ * `hedgeAfterMs`, an attempt still unanswered by then is joined by another
+ * on a fresh stub, and the first answer is taken: a success, or the
+ * callee's own error. A transient or overloaded failure then ends the call
+ * only once no attempt is left in flight.
+ *
+ * A failure of the resolver or of `onRetry` is the caller's own, and fails
+ * the call with it at once.
  */
-export async function idempotent<S, T>(
+export function idempotent<S, T>(
   operation: string,
   stub: DoStubResolver<S>,
   call: (stub: S) => Promise<T>,
@@ -114,23 +161,118 @@ export async function idempotent<S, T>(
 ): Promise<T> {
   const maxAttempts = policy.maxAttempts ?? MAX_ATTEMPTS;
   const baseDelayMs = policy.baseDelayMs ?? BASE_DELAY_MS;
-  for (let attempt = 1; ; attempt++) {
-    const minted = await stub();
-    try {
-      const result = await call(minted);
-      disposeRpcResource(minted);
-      return result;
-    } catch (error) {
-      // A stub that threw may be permanently broken; it is never reused.
-      disposeRpcResource(minted);
+  const { hedgeAfterMs, retryWindowMs } = policy;
+  const startedAt = Date.now();
+  // The executor form: fabric's library target predates Promise.withResolvers.
+  return new Promise<T>((resolve, reject) => {
+    const hedges = new Set<ReturnType<typeof setTimeout>>();
+    let started = 0;
+    // Attempts in flight, or backing off before their retry: while one is,
+    // a failure is not the call's answer.
+    let live = 0;
+    // An attempt was shed as overloaded: nothing is repeated after it.
+    let refused = false;
+    let settled = false;
+
+    const settle = (answer: () => void): void => {
+      if (settled) return;
+      settled = true;
+      for (const timer of hedges) clearTimeout(timer);
+      hedges.clear();
+      answer();
+    };
+    /** May another attempt start at `at`? */
+    const canRepeat = (at: number): boolean =>
+      !settled && !refused && started < maxAttempts
+      && (retryWindowMs === undefined || at - startedAt <= retryWindowMs);
+    /** `error` ended an attempt that will not be repeated: the call's answer, once nothing else is live. */
+    const exhausted = <E>(error: E): void => {
+      if (live === 0) settle(() => reject(error));
+    };
+
+    /** A failed attempt, numbered: repeat it after its backoff, or let it stand. */
+    const failed = async <E>(number: number, error: E): Promise<void> => {
+      if (settled) return;
       const classification = classifyDoCall(error);
-      if (!isRetryableDoCall(classification) || attempt >= maxAttempts) throw error;
-      policy.onRetry?.({ operation, classification, attempt, maxAttempts, error });
-      await new Promise<void>((resolve) => {
-        setTimeout(resolve, Math.floor(Math.random() * 2 ** attempt * baseDelayMs));
+      if (classification === 'overloaded') {
+        // A shed call is no answer: nothing more is sent, and an attempt
+        // still in flight may yet answer.
+        refused = true;
+        exhausted(error);
+        return;
+      }
+      if (!isRetryableDoCall(classification)) {
+        // The call ran and its answer is this error — ENOENT is a read's answer as much as bytes are.
+        settle(() => reject(error));
+        return;
+      }
+      const delayMs = Math.floor(Math.random() * 2 ** number * baseDelayMs);
+      if (!canRepeat(Date.now() + delayMs)) {
+        exhausted(error);
+        return;
+      }
+      live++;
+      await new Promise<void>((wake) => {
+        setTimeout(wake, delayMs);
       });
-    }
-  }
+      live--;
+      // A hedge may have taken the last attempt, or answered, meanwhile.
+      if (!canRepeat(Date.now())) {
+        exhausted(error);
+        return;
+      }
+      policy.onRetry?.({ operation, classification, attempt: number, maxAttempts, error });
+      attempt();
+    };
+
+    const run = async (): Promise<void> => {
+      const number = ++started;
+      live++;
+      const minted = await stub();
+      if (settled) {
+        live--;
+        disposeRpcResource(minted);
+        return;
+      }
+      const hedge = hedgeAfterMs === undefined ? undefined : setTimeout(() => {
+        if (hedge !== undefined) hedges.delete(hedge);
+        if (canRepeat(Date.now())) attempt();
+      }, hedgeAfterMs);
+      if (hedge !== undefined) hedges.add(hedge);
+      /** This attempt has its answer: it hedges no more, and its stub goes. */
+      const answered = (): void => {
+        if (hedge !== undefined) {
+          clearTimeout(hedge);
+          hedges.delete(hedge);
+        }
+        live--;
+        // A stub that threw may be permanently broken; none is ever reused.
+        disposeRpcResource(minted);
+      };
+      let result: T;
+      try {
+        result = await call(minted);
+      } catch (error) {
+        answered();
+        await failed(number, error);
+        return;
+      }
+      answered();
+      if (settled) {
+        // Another attempt answered first: this answer is dropped, so nothing of it is kept.
+        disposeRpcResource(result);
+        return;
+      }
+      settle(() => resolve(result));
+    };
+
+    /** Start an attempt. Whatever it throws outside the call itself fails the call. */
+    const attempt = (): void => {
+      run().catch((error) => settle(() => reject(error)));
+    };
+
+    attempt();
+  });
 }
 
 /**
@@ -138,6 +280,21 @@ export async function idempotent<S, T>(
  * or mints. NEVER retried — a dropped call may already have run. Failure
  * surfaces as a {@link DoCallError} carrying the classification, so the
  * caller can tell a refusal from an indeterminate drop.
+ *
+ * The rule is about the call as sent, not the operation's kind. A mutation
+ * the callee applies at most once per identity the call carries is
+ * repeatable by construction: a repeat of one that already ran is answered
+ * from the callee's record and applies nothing. Nimbus has two:
+ *   - delivered filesystem mutations (@nimbus-sh/core supervisor-delivery):
+ *     a delivery id plus the callee INSTANCE's incarnation. The record lives
+ *     in that instance's memory, and any other instance — or a callee that
+ *     predates delivery — refuses the call permanently rather than apply it
+ *     without one;
+ *   - appends: writer, module incarnation and operation sequence, recorded
+ *     durably until acknowledged.
+ * Such a call goes through {@link idempotent}, re-sending the same identity
+ * on every attempt, with a `retryWindowMs` inside the callee's retention of
+ * that record. Without such an identity, a mutation stays here.
  */
 export async function mutating<S, T>(
   operation: string,