@nimbus-sh/platform 0.7.1 → 0.8.0

package/README.md

@@ -124,7 +124,7 @@ export function* slices(bytes: Uint8Array): Generator<Uint8Array> {
 | `MAX_TX_LOGICAL_ROWS` / `MAX_TX_SQL_EXECS` | 256 / 64 | rows and execs in that same transaction |
 | `SQLITE_MAX_ROW_BYTES` | 2,000,000 | bytes per ROW, key length included; budget values against the row bound |
 | `SQLITE_MAX_STATEMENT_BYTES` | 100 KiB | SQL text per exec |
-| `SQLITE_MAX_BOUND_PARAMETERS` | 100 | bound parameters per query; a batched insert breaches this first |
+| `SQL_MAX_BOUND_PARAMETERS` | 100 | bound parameters per statement (101 fail); a batched insert breaches this first |
 | `DO_STORAGE_LIMIT_BYTES` | 10,000,000,000 | storage per Durable Object, shared by every facet and clone under it, with no copy-on-write credit |
 | `BLOCK_CONCURRENCY_CANCEL_MS` | 30,000 | how long a `blockConcurrencyWhile()` callback may run before the object is reset |
 | `WS_ATTACHMENT_LIMIT_BYTES` | 16,384 | serialized bytes per hibernatable WebSocket attachment |

package/dist/heavy-alloc-coord.d.ts

@@ -51,7 +51,10 @@ export declare class SupervisorAllocationBudget {
      * stops a large read overlapping a large write.
      */
     acquireWithoutLifecycle(bytes: number, signal?: AbortSignal): Promise<ResizableCreditLease>;
+    /** Reserve bytes now or not at all, driving the lifecycle as acquire does. */
+    tryAcquire(bytes: number): ResizableCreditLease | null;
     private _acquire;
+    private wrap;
 }
 /**
  * A registered observer (typically a SqliteVFS) receives shrink/restore
@@ -77,6 +80,8 @@ export declare function registerAllocObserver(o: AllocObserver): () => void;
  * Reserve an exact number of supervisor-resident bytes.
  */
 export declare function acquireSupervisorAllocation(bytes: number, signal?: AbortSignal): Promise<ResizableCreditLease>;
+/** Reserve bytes now if they can be granted without waiting, else null. */
+export declare function tryAcquireSupervisorAllocation(bytes: number): ResizableCreditLease | null;
 /**
  * Reserve bytes for a filesystem READ. Takes the same byte credit as any
  * other owner but does not shrink the disposable VFS cache, which reads are

package/dist/heavy-alloc-coord.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"heavy-alloc-coord.d.ts","sourceRoot":"","sources":["../src/heavy-alloc-coord.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAOH,OAAO,EAEL,KAAK,oBAAoB,EACzB,KAAK,yBAAyB,EAC/B,MAAM,2BAA2B,CAAC;AAEnC,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,UAAU,yBAAyB;IACjC,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;CACrB;AAED;;;GAGG;AACH,qBAAa,0BAA0B;IAWnC,QAAQ,CAAC,QAAQ,EAAE,MAAM;IACzB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAX5B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;IAC7C,OAAO,CAAC,MAAM,CAAS;IACvB;;;;OAIG;IACH,OAAO,CAAC,gBAAgB,CAAK;gBAGlB,QAAQ,EAAE,MAAM,EACR,SAAS,GAAE,yBAA8B,EAC1D,OAAO,GAAE,yBAA8B;IAKzC,IAAI,KAAK,IAAI,+BAA+B,CAK3C;IAED;;;;OAIG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAI3E;;;;;;;;OAQG;IACH,uBAAuB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,oBAAoB,CAAC;YAI7E,QAAQ;CAmCvB;AAED;;;GAGG;AACH,UAAU,aAAa;IACrB,8DAA8D;IAC9D,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;IACvB,8DAA8D;IAC9D,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;CACxB;AAiBD;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,aAAa,GAAG,MAAM,IAAI,CAWlE;AAqCD;;GAEG;AACH,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,MAAM,EACb,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,oBAAoB,CAAC,CAE/B;AAED;;;;GAIG;AACH,wBAAgB,+BAA+B,CAC7C,KAAK,EAAE,MAAM,EACb,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,oBAAoB,CAAC,CAE/B;AAED;;;GAGG;AACH,wBAAsB,iBAAiB,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC,CAMjF;AAED,wBAAgB,8BAA8B,IAAI,+BAA+B,CAEhF"}
+{"version":3,"file":"heavy-alloc-coord.d.ts","sourceRoot":"","sources":["../src/heavy-alloc-coord.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAOH,OAAO,EAEL,KAAK,oBAAoB,EACzB,KAAK,yBAAyB,EAC/B,MAAM,2BAA2B,CAAC;AAEnC,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,UAAU,yBAAyB;IACjC,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;CACrB;AAED;;;GAGG;AACH,qBAAa,0BAA0B;IAWnC,QAAQ,CAAC,QAAQ,EAAE,MAAM;IACzB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAX5B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;IAC7C,OAAO,CAAC,MAAM,CAAS;IACvB;;;;OAIG;IACH,OAAO,CAAC,gBAAgB,CAAK;gBAGlB,QAAQ,EAAE,MAAM,EACR,SAAS,GAAE,yBAA8B,EAC1D,OAAO,GAAE,yBAA8B;IAKzC,IAAI,KAAK,IAAI,+BAA+B,CAK3C;IAED;;;;OAIG;IACH,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAI3E;;;;;;;;OAQG;IACH,uBAAuB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,oBAAoB,CAAC;IAI3F,8EAA8E;IAC9E,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,oBAAoB,GAAG,IAAI;YAKxC,QAAQ;IAQtB,OAAO,CAAC,IAAI;CA8Bb;AAED;;;GAGG;AACH,UAAU,aAAa;IACrB,8DAA8D;IAC9D,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;IACvB,8DAA8D;IAC9D,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;CACxB;AAiBD;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,aAAa,GAAG,MAAM,IAAI,CAWlE;AAqCD;;GAEG;AACH,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,MAAM,EACb,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,oBAAoB,CAAC,CAE/B;AAED,2EAA2E;AAC3E,wBAAgB,8BAA8B,CAAC,KAAK,EAAE,MAAM,GAAG,oBAAoB,GAAG,IAAI,CAEzF;AAED;;;;GAIG;AACH,wBAAgB,+BAA+B,CAC7C,KAAK,EAAE,MAAM,EACb,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,oBAAoB,CAAC,CAE/B;AAED;;;GAGG;AACH,wBAAsB,iBAAiB,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC,CAMjF;AAED,wBAAgB,8BAA8B,IAAI,+BAA+B,CAEhF"}

package/dist/heavy-alloc-coord.js

@@ -55,8 +55,15 @@ export class SupervisorAllocationBudget {
     acquireWithoutLifecycle(bytes, signal) {
         return this._acquire(bytes, signal, false);
     }
+    /** Reserve bytes now or not at all, driving the lifecycle as acquire does. */
+    tryAcquire(bytes) {
+        const credit = this.credits.tryAcquire(bytes);
+        return credit ? this.wrap(credit, true) : null;
+    }
     async _acquire(bytes, signal, drivesLifecycle) {
-        const credit = await this.credits.acquire(bytes, signal);
+        return this.wrap(await this.credits.acquire(bytes, signal), drivesLifecycle);
+    }
+    wrap(credit, drivesLifecycle) {
         if (drivesLifecycle) {
             this.lifecycleHolders++;
             if (!this.active) {
@@ -160,6 +167,10 @@ const supervisorAllocationBudget = new SupervisorAllocationBudget(SUPERVISOR_IN_
 export function acquireSupervisorAllocation(bytes, signal) {
     return supervisorAllocationBudget.acquire(bytes, signal);
 }
+/** Reserve bytes now if they can be granted without waiting, else null. */
+export function tryAcquireSupervisorAllocation(bytes) {
+    return supervisorAllocationBudget.tryAcquire(bytes);
+}
 /**
  * Reserve bytes for a filesystem READ. Takes the same byte credit as any
  * other owner but does not shrink the disposable VFS cache, which reads are

package/dist/limits.d.ts

@@ -46,12 +46,6 @@ export declare const HYDRATION_DEADLINE_MS = 30000;
  * statements, a batched multi-VALUES insert being the realistic breach).
  */
 export declare const SQLITE_MAX_STATEMENT_BYTES: number;
-/**
- * Maximum bound parameters per query. The easiest cap to hit accidentally:
- * a batched insert of more than 100/columns rows in one statement breaches
- * it.
- */
-export declare const SQLITE_MAX_BOUND_PARAMETERS = 100;
 /**
  * Maximum bytes of one string, BLOB, or table ROW — the bound is per ROW,
  * key length included, not per value. The measured single-value ceiling is
@@ -107,6 +101,7 @@ export declare const MAX_RPC_SAFE_PAYLOAD_BYTES: number;
 export declare const ONE_SHOT_MODULE_MAP_MAX_BYTES: number;
 export declare const SUPERVISOR_HEAP_CEILING_BYTES: number;
 export declare const FACET_OWN_WRITE_MEMORY_BYTES: number;
+export declare const WASI_RESIDENT_STORE_BYTES: number;
 export declare const SUPERVISOR_IN_FLIGHT_ALLOCATION_BUDGET_BYTES: number;
 export declare const SUPERVISOR_READ_RESERVE_BYTES: number;
 export declare const MAX_GLOBAL_WRITE_STREAM_CREDIT_BYTES: number;

package/dist/limits.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"limits.d.ts","sourceRoot":"","sources":["../src/limits.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AASH;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,QAAS,CAAC;AAEjC,eAAO,MAAM,iBAAiB,QAAkB,CAAC;AACjD,eAAO,MAAM,mBAAmB,MAAM,CAAC;AACvC,eAAO,MAAM,gBAAgB,KAAK,CAAC;AAEnC;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,MAAM,CAAC;AAI5C;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,sBAAsB,cAAiB,CAAC;AAMrD,eAAO,MAAM,qBAAqB,QAAS,CAAC;AAE5C;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,QAAa,CAAC;AAErD;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,MAAM,CAAC;AAE/C;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,UAAY,CAAC;AAI9C;;;;;;;;GAQG;AACH,eAAO,MAAM,2BAA2B,QAAS,CAAC;AAIlD;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB,OAAQ,CAAC;AAE3C;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,8BAA8B,QAAS,CAAC;AAIrD;;;;;;;;;GASG;AACH,eAAO,MAAM,yBAAyB,QAAS,CAAC;AAOhD,eAAO,MAAM,0BAA0B,QAAmB,CAAC;AAmB3D,eAAO,MAAM,6BAA6B,QAAmB,CAAC;AA6B9D,eAAO,MAAM,6BAA6B,QAAmB,CAAC;AAM9D,eAAO,MAAM,4BAA4B,QAAmB,CAAC;AAO7D,eAAO,MAAM,4CAA4C,QAAmB,CAAC;AAY7E,eAAO,MAAM,6BAA6B,QAAc,CAAC;AAKzD,eAAO,MAAM,oCAAoC,QAAkB,CAAC;AAQpE,eAAO,MAAM,0BAA0B,QAA6B,CAAC;AACrE,eAAO,MAAM,sBAAsB,IAAI,CAAC"}
+{"version":3,"file":"limits.d.ts","sourceRoot":"","sources":["../src/limits.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AASH;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,QAAS,CAAC;AAEjC,eAAO,MAAM,iBAAiB,QAAkB,CAAC;AACjD,eAAO,MAAM,mBAAmB,MAAM,CAAC;AACvC,eAAO,MAAM,gBAAgB,KAAK,CAAC;AAEnC;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,MAAM,CAAC;AAI5C;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,sBAAsB,cAAiB,CAAC;AAMrD,eAAO,MAAM,qBAAqB,QAAS,CAAC;AAE5C;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,QAAa,CAAC;AAErD;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,UAAY,CAAC;AAI9C;;;;;;;;GAQG;AACH,eAAO,MAAM,2BAA2B,QAAS,CAAC;AAIlD;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB,OAAQ,CAAC;AAE3C;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,8BAA8B,QAAS,CAAC;AAIrD;;;;;;;;;GASG;AACH,eAAO,MAAM,yBAAyB,QAAS,CAAC;AAOhD,eAAO,MAAM,0BAA0B,QAAmB,CAAC;AAmB3D,eAAO,MAAM,6BAA6B,QAAmB,CAAC;AA6B9D,eAAO,MAAM,6BAA6B,QAAmB,CAAC;AAM9D,eAAO,MAAM,4BAA4B,QAAmB,CAAC;AAQ7D,eAAO,MAAM,yBAAyB,QAAmB,CAAC;AAO1D,eAAO,MAAM,4CAA4C,QAAmB,CAAC;AAY7E,eAAO,MAAM,6BAA6B,QAAc,CAAC;AAKzD,eAAO,MAAM,oCAAoC,QAAkB,CAAC;AAQpE,eAAO,MAAM,0BAA0B,QAA6B,CAAC;AACrE,eAAO,MAAM,sBAAsB,IAAI,CAAC"}

package/dist/limits.js

@@ -57,12 +57,6 @@ export const HYDRATION_DEADLINE_MS = 30_000;
  * statements, a batched multi-VALUES insert being the realistic breach).
  */
 export const SQLITE_MAX_STATEMENT_BYTES = 100 * 1024;
-/**
- * Maximum bound parameters per query. The easiest cap to hit accidentally:
- * a batched insert of more than 100/columns rows in one statement breaches
- * it.
- */
-export const SQLITE_MAX_BOUND_PARAMETERS = 100;
 /**
  * Maximum bytes of one string, BLOB, or table ROW — the bound is per ROW,
  * key length included, not per value. The measured single-value ceiling is
@@ -173,6 +167,13 @@ export const SUPERVISOR_HEAP_CEILING_BYTES = 64 * 1024 * 1024;
 // works: at most this many bytes, least recently used out first. An eighth
 // of a facet's measured ~208-256 MiB, the rest left to the program.
 export const FACET_OWN_WRITE_MEMORY_BYTES = 32 * 1024 * 1024;
+// A WASI process's copy of the namespace and of the files it reads
+// (core runtime/wasi/resident-filesystem.ts): held in its facet's heap beside
+// the guest's linear memory, and never past this. Names are listed and bytes
+// fetched only as the program asks for them, so the cap bounds a tree walker
+// or a program that reads much, not what a short run holds. Past it the store
+// holds nothing more and the session answers.
+export const WASI_RESIDENT_STORE_BYTES = 32 * 1024 * 1024;
 // Shared allowance for transient allocations in the supervisor DO. With the
 // VFS LRU shrunk to 8 MiB during an active reservation, 40 MiB of admitted
 // payload plus the 9 MiB bundle baseline stays below the 64 MiB soft ceiling

package/dist/lost-call.d.ts

@@ -0,0 +1,62 @@
+/**
+ * lost-call.ts — the one policy for a call that never reaches the session.
+ *
+ * The platform drops calls into a Durable Object now and then, and the
+ * caller cannot tell a call that never arrived from one that is slow:
+ *   - reads, SupervisorRPC → session, under three concurrent sessions
+ *     (2026-09-28): 11 of 521 read batches never reached the session and
+ *     were still pending 110-560 s later; every read that answered did so
+ *     within 5 s;
+ *   - write waves, a facet's writeBatchStream (2026-10-06, two next.js
+ *     clones): the transport read the stream's first ~1 MiB within 0.1 s
+ *     and nothing more, while the session held no stream, credit,
+ *     allocation or transaction for it and kept committing other waves;
+ *     healthy, with 8 producers saturating one session, the longest gap
+ *     between a wave's reads was 2.5 s and the slowest wave 5.3 s;
+ *   - calls that fail at once, "Network connection lost." (`retryable`),
+ *     which classifyDoCall names.
+ *
+ * Detection and timings live here; the recovery depends on what a second
+ * delivery would do. A read is idempotent, so it is hedged: the same call
+ * on a fresh stub, the first answer taken (fabric do-calls `hedgeAfterMs`).
+ * A write wave carries a stream the first attempt consumes, so it cannot be
+ * hedged: it is re-encoded and re-sent under a fence (`WaveFence`), and the
+ * session refuses an attempt older than one it has seen from the same
+ * writer, so a late original never applies over its re-send.
+ */
+/** An idempotent call unanswered this long is hedged on a fresh stub. */
+export declare const LOST_CALL_HEDGE_AFTER_MS = 5000;
+/** A stream nothing has read for this long, before its end, never reached the session. */
+export declare const LOST_STREAM_STALL_MS = 10000;
+/** A call unanswered this long after its stream ended is taken as lost. */
+export declare const LOST_STREAM_ANSWER_MS = 20000;
+/**
+ * How long a write-wave epoch the session issued admits attempts. Anything
+ * sent under an epoch the session does not know, or one past this, is
+ * refused: a call lost for longer than this can only be refused, never
+ * admitted. A writer opens a new epoch once half of this has passed.
+ */
+export declare const WAVE_EPOCH_TTL_MS: number;
+/**
+ * Waits before each re-send of a lost non-idempotent call (±25% jitter):
+ * ~42 s in all, to outlast a coordinator queue deep enough to shed. Its
+ * length is the bound on re-sends.
+ */
+export declare const LOST_CALL_RESEND_BACKOFF_MS: readonly number[];
+/**
+ * Whether `error` is the platform losing a fenced call: a dropped
+ * connection, a replaced isolate, a storage reset, or an object that shed
+ * it. Overloaded is included for fenced re-sends only: the platform's advice
+ * is not to retry an overloaded object, but these are few and backed off,
+ * and npm measured one re-send recover a 119-package install that one shed
+ * cost 31 packages (do-calls' unfenced verbs still never retry it).
+ */
+export declare function isLostFencedCall(error: unknown): boolean;
+/** The attributes a lost call is logged and traced under, by every caller. */
+export declare function lostCallAttributes(lost: {
+    operation: string;
+    attempt: number;
+    of: number;
+    reason: string;
+}): Record<string, string | number>;
+//# sourceMappingURL=lost-call.d.ts.map

package/dist/lost-call.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lost-call.d.ts","sourceRoot":"","sources":["../src/lost-call.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAIH,yEAAyE;AACzE,eAAO,MAAM,wBAAwB,OAAQ,CAAC;AAE9C,0FAA0F;AAC1F,eAAO,MAAM,oBAAoB,QAAS,CAAC;AAE3C,2EAA2E;AAC3E,eAAO,MAAM,qBAAqB,QAAS,CAAC;AAE5C;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,QAAc,CAAC;AAE7C;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,EAAE,SAAS,MAAM,EAA+C,CAAC;AAEzG;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAGxD;AAED,8EAA8E;AAC9E,wBAAgB,kBAAkB,CAAC,IAAI,EAAE;IACvC,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;CAChB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAOlC"}

package/dist/lost-call.js

@@ -0,0 +1,67 @@
+/**
+ * lost-call.ts — the one policy for a call that never reaches the session.
+ *
+ * The platform drops calls into a Durable Object now and then, and the
+ * caller cannot tell a call that never arrived from one that is slow:
+ *   - reads, SupervisorRPC → session, under three concurrent sessions
+ *     (2026-09-28): 11 of 521 read batches never reached the session and
+ *     were still pending 110-560 s later; every read that answered did so
+ *     within 5 s;
+ *   - write waves, a facet's writeBatchStream (2026-10-06, two next.js
+ *     clones): the transport read the stream's first ~1 MiB within 0.1 s
+ *     and nothing more, while the session held no stream, credit,
+ *     allocation or transaction for it and kept committing other waves;
+ *     healthy, with 8 producers saturating one session, the longest gap
+ *     between a wave's reads was 2.5 s and the slowest wave 5.3 s;
+ *   - calls that fail at once, "Network connection lost." (`retryable`),
+ *     which classifyDoCall names.
+ *
+ * Detection and timings live here; the recovery depends on what a second
+ * delivery would do. A read is idempotent, so it is hedged: the same call
+ * on a fresh stub, the first answer taken (fabric do-calls `hedgeAfterMs`).
+ * A write wave carries a stream the first attempt consumes, so it cannot be
+ * hedged: it is re-encoded and re-sent under a fence (`WaveFence`), and the
+ * session refuses an attempt older than one it has seen from the same
+ * writer, so a late original never applies over its re-send.
+ */
+import { classifyDoCall, isRetryableDoCall } from './oom-classify.js';
+/** An idempotent call unanswered this long is hedged on a fresh stub. */
+export const LOST_CALL_HEDGE_AFTER_MS = 5_000;
+/** A stream nothing has read for this long, before its end, never reached the session. */
+export const LOST_STREAM_STALL_MS = 10_000;
+/** A call unanswered this long after its stream ended is taken as lost. */
+export const LOST_STREAM_ANSWER_MS = 20_000;
+/**
+ * How long a write-wave epoch the session issued admits attempts. Anything
+ * sent under an epoch the session does not know, or one past this, is
+ * refused: a call lost for longer than this can only be refused, never
+ * admitted. A writer opens a new epoch once half of this has passed.
+ */
+export const WAVE_EPOCH_TTL_MS = 10 * 60_000;
+/**
+ * Waits before each re-send of a lost non-idempotent call (±25% jitter):
+ * ~42 s in all, to outlast a coordinator queue deep enough to shed. Its
+ * length is the bound on re-sends.
+ */
+export const LOST_CALL_RESEND_BACKOFF_MS = [250, 1_000, 3_000, 6_000, 12_000, 20_000];
+/**
+ * Whether `error` is the platform losing a fenced call: a dropped
+ * connection, a replaced isolate, a storage reset, or an object that shed
+ * it. Overloaded is included for fenced re-sends only: the platform's advice
+ * is not to retry an overloaded object, but these are few and backed off,
+ * and npm measured one re-send recover a 119-package install that one shed
+ * cost 31 packages (do-calls' unfenced verbs still never retry it).
+ */
+export function isLostFencedCall(error) {
+    const kind = classifyDoCall(error);
+    return isRetryableDoCall(kind) || kind === 'overloaded';
+}
+/** The attributes a lost call is logged and traced under, by every caller. */
+export function lostCallAttributes(lost) {
+    return {
+        'do_call.operation': lost.operation,
+        'do_call.attempts': lost.attempt,
+        'do_call.max_attempts': lost.of,
+        'do_call.lost_reason': lost.reason,
+    };
+}

package/dist/oom-classify.d.ts

@@ -110,6 +110,20 @@ export declare function classifyMessage(msg: string): OomCause;
  * (`loaders/process-fabric.ts`) — recurs, exhausts the budget and surfaces.
  */
 export declare function isTransientDoReset(input: unknown): boolean;
+/**
+ * The platform's own word that the actor a call reached was reset or killed:
+ * its `durableObjectReset` flag, or one of its termination sentences, whole.
+ * Text a program wrote never counts, however it reads: a process whose host
+ * this matches is ended (fabric process-host.ts HostLoss).
+ */
+export declare function isHostReset(input: unknown): boolean;
+/**
+ * A failure the platform reports without a cause: workerd's "internal error;
+ * reference = <id>", whose reference only Cloudflare can look up. The error
+ * may carry `durableObjectReset` (the object it reached was reset), and
+ * nothing else; the caller has to name what it was doing.
+ */
+export declare function isUnexplainedPlatformError(input: unknown): boolean;
 /**
  * Workerd shed the call because the target Durable Object's input-gate
  * queue was too deep or too old: "Durable Object is overloaded."

package/dist/oom-classify.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"oom-classify.d.ts","sourceRoot":"","sources":["../src/oom-classify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AAEH,QAAA,MAAM,UAAU,kLAYN,CAAC;AAEX,MAAM,MAAM,QAAQ,GAAG,OAAO,UAAU,CAAC,MAAM,CAAC,CAAC;AAEjD,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAE5D;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,QAAQ,CAItD;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ,CAmErD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAO1D;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEtD;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,WAAW;AACrB,8CAA8C;AAC5C,oBAAoB;AACtB,8CAA8C;GAC5C,iBAAiB;AACnB,uEAAuE;GACrE,eAAe;AACjB,wDAAwD;GACtD,gBAAgB;AAClB;kDACkD;GAChD,YAAY;AACd,kEAAkE;GAChE,WAAW,CAAC;AAEhB;2DAC2D;AAC3D,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAK7D;AAmBD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,CAsB1D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAiBpD"}
+{"version":3,"file":"oom-classify.d.ts","sourceRoot":"","sources":["../src/oom-classify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AAEH,QAAA,MAAM,UAAU,kLAYN,CAAC;AAEX,MAAM,MAAM,QAAQ,GAAG,OAAO,UAAU,CAAC,MAAM,CAAC,CAAC;AAEjD,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAE5D;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,QAAQ,CAItD;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ,CAmErD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAO1D;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAInD;AAYD;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAElE;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEtD;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,WAAW;AACrB,8CAA8C;AAC5C,oBAAoB;AACtB,8CAA8C;GAC5C,iBAAiB;AACnB,uEAAuE;GACrE,eAAe;AACjB,wDAAwD;GACtD,gBAAgB;AAClB;kDACkD;GAChD,YAAY;AACd,kEAAkE;GAChE,WAAW,CAAC;AAEhB;2DAC2D;AAC3D,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAK7D;AAmBD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,CAsB1D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAiBpD"}

package/dist/oom-classify.js

@@ -214,6 +214,36 @@ export function isTransientDoReset(input) {
         return true;
     return false;
 }
+/**
+ * The platform's own word that the actor a call reached was reset or killed:
+ * its `durableObjectReset` flag, or one of its termination sentences, whole.
+ * Text a program wrote never counts, however it reads: a process whose host
+ * this matches is ended (fabric process-host.ts HostLoss).
+ */
+export function isHostReset(input) {
+    if (typeof input === 'object' && input !== null && Reflect.get(input, 'durableObjectReset') === true)
+        return true;
+    const message = readMessage(input).trim().replace(/^broken\.\w+;\s*jsg\.\w+:\s*/, '');
+    return HOST_TERMINATIONS.some((signature) => signature.test(message));
+}
+const HOST_TERMINATIONS = [
+    /^Durable Object's isolate exceeded its memory limit (?:and was reset\.|due to )/,
+    /^Worker (?:has )?exceeded memory limit\.$/,
+    /^(?:Python )?Worker exceeded CPU time limit\.?$/,
+    /^Durable Object exceeded its CPU time limit and was reset\.$/,
+    /^Durable Object reset because its code was updated\.$/,
+    /^Internal error (?:in|while starting up) Durable Object storage caused object to be reset; reference = \S+$/,
+    /^Durable Object storage operation exceeded timeout which caused the object to be reset\.$/,
+];
+/**
+ * A failure the platform reports without a cause: workerd's "internal error;
+ * reference = <id>", whose reference only Cloudflare can look up. The error
+ * may carry `durableObjectReset` (the object it reached was reset), and
+ * nothing else; the caller has to name what it was doing.
+ */
+export function isUnexplainedPlatformError(input) {
+    return /^internal error; reference = \S+$/i.test(readMessage(input).trim());
+}
 /**
  * Workerd shed the call because the target Durable Object's input-gate
  * queue was too deep or too old: "Durable Object is overloaded."

package/dist/retry.d.ts

@@ -0,0 +1,49 @@
+/**
+ * retry.ts — the one retry policy: the loop that tries an operation again
+ * when its outcome is worth another try, and the wait between tries.
+ *
+ * Each caller names what is worth another try and how far apart, because
+ * that is what differs and was measured per transport:
+ *   - the npm registry (npm/registry-retry.ts): a 5xx or a request that
+ *     never answered, 500/1500/4500 ms;
+ *   - a git server (git/pack/transport.ts): an idempotent request that
+ *     failed in transit, stalled, or met a transient edge status, 1/3 s;
+ *   - a lost write wave (lost-call.ts LOST_CALL_RESEND_BACKOFF_MS).
+ * Every wait is its schedule's entry ±25%, uniformly, so concurrent callers
+ * that failed together do not try again together.
+ *
+ * Self-contained, both functions: a facet that cannot import carries them
+ * by source (fn.toString(); the npm install facet's preamble does).
+ */
+/**
+ * The wait before re-try `attempt` (0-based, the try that just failed):
+ * `schedule[attempt]`, its last entry once past the end, ±25%.
+ */
+export declare function retryDelayMs(schedule: readonly number[], attempt: number): number;
+/** An attempt's outcome: what it returned, or what it threw. */
+export type RetryOutcome<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly error: unknown;
+};
+export interface RetryPolicy<T> {
+    /** How many times to try again after the first try. */
+    readonly retries: number;
+    /** The waits before each re-try, for retryDelayMs. */
+    readonly schedule: readonly number[];
+    /** Why `outcome` is worth another try, or null to keep it. Not asked of the last try. */
+    retryReason(outcome: RetryOutcome<T>): string | null;
+    /** A returned value given up for another try (its body cancelled, its stub disposed). */
+    discard?(value: T): unknown;
+    /** Each re-try, 1-based, with its wait and why. */
+    onRetry?(retry: number, of: number, delayMs: number, reason: string): void;
+}
+/**
+ * `attempt(n)` for n = 0, 1, … until its outcome is not worth another try
+ * or the policy's re-tries are spent; then that outcome: its value
+ * returned, its error thrown.
+ */
+export declare function retrying<T>(attempt: (n: number) => Promise<T>, policy: RetryPolicy<T>): Promise<T>;
+//# sourceMappingURL=retry.d.ts.map

package/dist/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../src/retry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH;;;GAGG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAGjF;AAED,gEAAgE;AAChE,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GAAG;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC;AAEzH,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B,uDAAuD;IACvD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,sDAAsD;IACtD,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,yFAAyF;IACzF,WAAW,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,MAAM,GAAG,IAAI,CAAC;IACrD,yFAAyF;IACzF,OAAO,CAAC,CAAC,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC;IAC5B,mDAAmD;IACnD,OAAO,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5E;AAED;;;;GAIG;AACH,wBAAsB,QAAQ,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAyBxG"}

package/dist/retry.js

@@ -0,0 +1,59 @@
+/**
+ * retry.ts — the one retry policy: the loop that tries an operation again
+ * when its outcome is worth another try, and the wait between tries.
+ *
+ * Each caller names what is worth another try and how far apart, because
+ * that is what differs and was measured per transport:
+ *   - the npm registry (npm/registry-retry.ts): a 5xx or a request that
+ *     never answered, 500/1500/4500 ms;
+ *   - a git server (git/pack/transport.ts): an idempotent request that
+ *     failed in transit, stalled, or met a transient edge status, 1/3 s;
+ *   - a lost write wave (lost-call.ts LOST_CALL_RESEND_BACKOFF_MS).
+ * Every wait is its schedule's entry ±25%, uniformly, so concurrent callers
+ * that failed together do not try again together.
+ *
+ * Self-contained, both functions: a facet that cannot import carries them
+ * by source (fn.toString(); the npm install facet's preamble does).
+ */
+/**
+ * The wait before re-try `attempt` (0-based, the try that just failed):
+ * `schedule[attempt]`, its last entry once past the end, ±25%.
+ */
+export function retryDelayMs(schedule, attempt) {
+    const base = schedule[Math.min(attempt, schedule.length - 1)] ?? 0;
+    return Math.max(0, Math.round(base + (Math.random() * 2 - 1) * base * 0.25));
+}
+/**
+ * `attempt(n)` for n = 0, 1, … until its outcome is not worth another try
+ * or the policy's re-tries are spent; then that outcome: its value
+ * returned, its error thrown.
+ */
+export async function retrying(attempt, policy) {
+    for (let n = 0;; n++) {
+        let outcome;
+        try {
+            outcome = { ok: true, value: await attempt(n) };
+        }
+        catch (error) {
+            outcome = { ok: false, error };
+        }
+        const reason = n < policy.retries ? policy.retryReason(outcome) : null;
+        if (reason === null) {
+            if (outcome.ok)
+                return outcome.value;
+            throw outcome.error;
+        }
+        if (outcome.ok && policy.discard) {
+            try {
+                await policy.discard(outcome.value);
+            }
+            catch {
+                // It is being given up either way.
+            }
+        }
+        const delayMs = retryDelayMs(policy.schedule, n);
+        policy.onRetry?.(n + 1, policy.retries, delayMs, reason);
+        // The executor form: this package's lib (ES2022) has no Promise.withResolvers.
+        await new Promise((resolve) => setTimeout(resolve, delayMs));
+    }
+}

package/dist/utf8.d.ts

@@ -0,0 +1,11 @@
+/**
+ * utf8.ts — the UTF-8 length of a string, without encoding it.
+ *
+ * Bounds on names and payloads are in bytes, and the hot ones (every path a
+ * W7 wave or a listing page carries) were measured by encoding the string
+ * into a new buffer only to read its length. This counts the same bytes
+ * TextEncoder would write: one to four per code point, and three for a
+ * lone surrogate, which it writes as U+FFFD.
+ */
+export declare function utf8Length(text: string): number;
+//# sourceMappingURL=utf8.d.ts.map

package/dist/utf8.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utf8.d.ts","sourceRoot":"","sources":["../src/utf8.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAqB/C"}

package/dist/utf8.js

@@ -0,0 +1,35 @@
+/**
+ * utf8.ts — the UTF-8 length of a string, without encoding it.
+ *
+ * Bounds on names and payloads are in bytes, and the hot ones (every path a
+ * W7 wave or a listing page carries) were measured by encoding the string
+ * into a new buffer only to read its length. This counts the same bytes
+ * TextEncoder would write: one to four per code point, and three for a
+ * lone surrogate, which it writes as U+FFFD.
+ */
+export function utf8Length(text) {
+    let bytes = text.length;
+    for (let index = 0; index < text.length; index++) {
+        const unit = text.charCodeAt(index);
+        if (unit < 0x80)
+            continue;
+        if (unit < 0x800) {
+            bytes += 1;
+        }
+        else if (unit >= 0xd800 && unit <= 0xdbff && index + 1 < text.length) {
+            const next = text.charCodeAt(index + 1);
+            if (next >= 0xdc00 && next <= 0xdfff) {
+                // A pair: two units, four bytes.
+                bytes += 2;
+                index++;
+            }
+            else {
+                bytes += 2;
+            }
+        }
+        else {
+            bytes += 2;
+        }
+    }
+    return bytes;
+}