@nimbus-sh/platform 0.1.0

package/dist/limits.js

@@ -0,0 +1,146 @@
+/**
+ * limits.ts — the measured Cloudflare platform limits Nimbus is built
+ * against.
+ *
+ * Every constant here is a fact about the platform — a hard ceiling, or a
+ * measured envelope proven safe against one — rather than a Nimbus policy
+ * choice. Policy constants (versions, defaults, feature bounds) live in
+ * `@nimbus-sh/core/constants.js`; this table is what they are derived from.
+ */
+// ── Storage-transaction bounds ──────────────────────────────────────────
+//
+// The platform resets a Durable Object over what ONE TURN has outstanding
+// in storage ("Internal error in Durable Object storage caused object to
+// be reset"), not over what it eventually writes. These bounds keep any
+// one transaction below that wall.
+/**
+ * The storage/wire chunk quantum: bytes per content chunk in the SQLite
+ * VFS schema, and therefore the unit every transaction bound and streamed
+ * write frame is denominated in. SQLite's per-ROW value cap is 2 MB (key
+ * length included, measured single-value ceiling 2,199,981 B), so 64 KiB
+ * keeps a chunk row far under it while amortizing per-row overhead.
+ */
+export const CHUNK_SIZE = 65_536;
+export const MAX_TX_BLOB_BYTES = 1 * 1024 * 1024;
+export const MAX_TX_LOGICAL_ROWS = 256;
+export const MAX_TX_SQL_EXECS = 64;
+// ── SQLite storage walls ────────────────────────────────────────────────
+/**
+ * Storage per SQLite-backed Durable Object: 10 decimal GB documented
+ * (Workers Paid), shared by the root object, every facet beneath it, and
+ * every clone — a copy-on-write clone consumes its FULL logical bytes with
+ * no CoW credit. Probed window: 10.58e9 logical bytes fit, 11.6e9 failed —
+ * 10 GiB (10,737,418,240) falls INSIDE that window and is not a number to
+ * design to. At the wall, ordinary writes fail catchably as SQLITE_FULL
+ * ('database or disk is full') while reads and DELETEs keep working, so the
+ * recovery is to drain; a facet CLONE over the wall is an uncatchable reset
+ * that empties the destination, so clone admission is decided BEFORE the
+ * clone, with reserve.
+ */
+export const DO_STORAGE_LIMIT_BYTES = 10_000_000_000;
+/**
+ * Maximum SQL statement text per exec. Documented "100 KB"; read as binary
+ * KiB because the value is SQLite's compile-time SQLITE_MAX_SQL_LENGTH
+ * rather than a billing quantity (unverified reading — reached by generated
+ * 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
+ * 2,199,981 bytes, ABOVE this constant: budgeting each value against the
+ * row bound is conservative and correct, budgeting a row against the value
+ * ceiling is not. Writes over it fail; reads and deletes keep working.
+ */
+export const SQLITE_MAX_ROW_BYTES = 2_000_000;
+// ── Init-gate hazard ────────────────────────────────────────────────────
+/**
+ * A `blockConcurrencyWhile()` callback still pending this long is
+ * cancelled and the Durable Object is RESET — every event queued behind
+ * the gate dies with it. Proven by probe (reset observed at 31 s against a
+ * 31 s-busy neighbour; cold activations track a busy neighbour 1:1), and
+ * partyserver runs `onStart()` inside the gate, so ordinary traffic can
+ * reach this. Anything on that path must be bounded well below this;
+ * fabric defers async reconciliation off the gate entirely (`onColdStart`).
+ */
+export const BLOCK_CONCURRENCY_CANCEL_MS = 30_000;
+// ── WebSocket attachment bound ──────────────────────────────────────────
+/**
+ * Bytes one hibernatable WebSocket attachment may serialize to. Verified in
+ * workerd source at the pinned version (v1.20260603.1,
+ * src/workerd/api/web-socket.h: `MAX_ATTACHMENT_SIZE = 1024 * 16`). The
+ * bound is on the SERIALIZED bytes — workerd re-serializes on every
+ * `serializeAttachment` call to check it — not on UTF-8 JSON text, so a
+ * JSON-length measurement is an approximation and only the platform's own
+ * refusal ("A WebSocket 'attachment' cannot be larger than 16384 bytes.")
+ * is the ceiling.
+ */
+export const WS_ATTACHMENT_LIMIT_BYTES = 16_384;
+// ── RPC payload envelope ────────────────────────────────────────────────
+// Largest byte payload Nimbus sends through an ordinary Workers RPC value.
+// The platform limit is 32 MiB; 28 MiB leaves room for structured-clone
+// metadata and matches the proven on-demand facet transfer envelope.
+export const MAX_RPC_SAFE_PAYLOAD_BYTES = 28 * 1024 * 1024;
+// ── Supervisor heap budget [C'.1] ───────────────────────────────────────
+//
+// Three distinct memory regimes, not one shared pool:
+//
+//   - Supervisor DO isolate: 128 MiB HARD platform ceiling ("Each isolate
+//     can consume up to 128 MB of memory" —
+//     https://developers.cloudflare.com/workers/platform/limits/).
+//   - Facets: ~208-256 MiB EACH, measured — memory independent of the
+//     supervisor and of each other (1,664 MiB live across 8 facets +
+//     parent) but CPU SHARED across the actor thread. See
+//     packages/fabric/src/process-fabric.ts.
+//   - Peer DOs: independent memory AND CPU budgets, measured 1.2 GiB
+//     live across 8 peers.
+//
+// Nimbus targets HALF of the supervisor's 128 MiB as a self-imposed soft
+// ceiling so the supervisor always has runway when workerd LRU-evicts
+// neighbours or AIR (Asynchronous Isolate Recreation) folds growing
+// isolates.
+//
+// 64 MiB is a soft admission budget, not a measurement — the right value
+// is unmeasured — and nothing enforces it directly.
+// heap-estimate.ts sums the INSTRUMENTED contributors —
+// the supervisor baseline, VFS LRU and in-flight writes, pre-bundle
+// slices, streaming RPC buffers, and the prefetch-bundle build lease and
+// cache gauge — which is a lower bound, not full coverage; allocation
+// sites known to be missing are listed in HEAP_BLIND_SPOTS. Read a low
+// percentOfCeiling accordingly.
+export const SUPERVISOR_HEAP_CEILING_BYTES = 64 * 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
+// with 7 MiB left for metadata, structured-clone overhead, and runtime state.
+// This is 31.25% of the platform's 128 MiB hard isolate ceiling.
+export const SUPERVISOR_IN_FLIGHT_ALLOCATION_BUDGET_BYTES = 40 * 1024 * 1024;
+// Reserved slice of that allowance for chunk-sized filesystem reads, so a
+// read is never queued behind a multi-megabyte owner for a wait that has
+// nothing to do with its own cost. A read only draws on this when the shared
+// budget is already contended — which is exactly when the VFS LRU is shrunk
+// to 8 MiB — so peak accounting is 40 + 1 admitted, 8 LRU, 9 bundle baseline:
+// 58 MiB, still under the 64 MiB soft ceiling.
+//
+// 1 MiB is 16 concurrent READ_STREAM_CHUNK_BYTES reads. The point is not
+// depth, it is that a read loop keeps moving while a heavy owner works
+// instead of stopping dead for the duration.
+export const SUPERVISOR_READ_RESERVE_BYTES = 1024 * 1024;
+// Global bound on supervisor-resident write-stream credit, shared by every
+// concurrent streamed bulk write into one DO. Part of the same supervisor
+// budget arithmetic as the allocation budget above.
+export const MAX_GLOBAL_WRITE_STREAM_CREDIT_BYTES = 8 * 1024 * 1024;
+// ── Pre-bundle admission envelope ───────────────────────────────────────
+//
+// The proven-safe envelope for shipping module slices through a shared DO
+// isolate: one slice at the RPC envelope at a time. Measured the hard way —
+// concurrency=2 of max slices crashed Mossaic-scale installs on shared DO
+// isolates. The heap estimator's pre-bundle lane models exactly this bound.
+export const PRE_BUNDLE_SLICE_CAP_BYTES = MAX_RPC_SAFE_PAYLOAD_BYTES;
+export const PRE_BUNDLE_CONCURRENCY = 1;

package/dist/oom-classify.d.ts

@@ -0,0 +1,172 @@
+/**
+ * oom-classify.ts — discriminator for OOM-like errors at Nimbus
+ * boundaries.
+ *
+ * Why this exists
+ * ───────────────
+ * Nimbus has at least five distinct "the work failed" failure modes
+ * that all surface today as either a thrown JS Error or a console
+ * line:
+ *
+ *   1. SQLITE_NOMEM at the storage layer (per-DO SQLite cap, post-
+ *      STOR/SPEC: Address SQLITE_NOMEM issues).
+ *   2. Isolate memory exhaustion → 'oom'.
+ *   3. Isolate CPU-budget exhaustion → 'cpu_exceeded'.
+ *   4. Structured-clone refusal (`Cannot deserialize cloned data`)
+ *      between supervisor ↔ facet RPC (32 MiB cap).
+ *   5. RPC timeout (TimeoutError from facet-pool's per-task race).
+ *
+ * Plus a few platform-side terminations (subrequest cap, condemnation,
+ * hard eviction) that the user sees but Nimbus has no first-party
+ * signal for.
+ *
+ * Memory and CPU are separate buckets
+ * ───────────────────────────────────
+ * workerd models them as distinct trace outcomes — `exceededMemory` vs
+ * `exceededCpu` (EventOutcome, workerd/io/outcome.capnp) — and words the
+ * two message families so neither one's signature appears in the other:
+ *
+ *   memory  "Worker has exceeded memory limit."
+ *           "Worker exceeded memory limit."
+ *           "broken.exceededMemory; jsg.Error: Durable Object's isolate
+ *            exceeded its memory limit …"
+ *           "Memory limit exceeded"                    (RangeError)
+ *   cpu     "Worker exceeded CPU time limit."
+ *           "Durable Object exceeded its CPU time limit and was reset."
+ *           "Python Worker exceeded CPU time limit"
+ *
+ * Read a low 'cpu_exceeded' count carefully: neither condition reliably
+ * produces a message. Both are uncatchable inside the isolate that died,
+ * so the string is only observable by a CALLER across an RPC boundary,
+ * and Nimbus has repeatedly measured isolates vanishing with no throw at
+ * all. Absence of 'cpu_exceeded' entries is therefore NOT evidence that
+ * CPU was not the cause — confirm against `wrangler tail` either way.
+ *
+ * Without a classifier, every recordFailure() call has to stringify-
+ * match its own error site. With this module, we pin the regex once
+ * and reuse it everywhere.
+ *
+ * Inputs we accept
+ * ────────────────
+ * The classifier accepts:
+ *   - Error instances (read e.message)
+ *   - plain strings (use directly — for stderr-line classification at
+ *     facet-exit boundaries where we don't have an Error)
+ *   - anything else (return 'unknown')
+ *
+ * Output values
+ * ─────────────
+ * Same set used by `DiagFailure.cause` in oom-discriminator.ts. Keep
+ * the union narrow and additive — adding a new value is fine, but
+ * never re-purpose an existing one.
+ */
+declare const OOM_CAUSES: readonly ["sqlite_nomem", "sqlite_full", "oom", "cpu_exceeded", "clone_refused", "rpc_timeout", "subrequest_cap", "dynamic_worker_cap", "condemnation", "hard_evict", "unknown"];
+export type OomCause = typeof OOM_CAUSES[number];
+export declare function isOomCause(input: unknown): input is OomCause;
+/**
+ * Classify an error or message string into an OomCause. Returns
+ * 'unknown' when no signature matches — callers should still record
+ * the message via DiagFailure.message so a human can later widen the
+ * classifier rules.
+ */
+export declare function classifyError(input: unknown): OomCause;
+/**
+ * Variant for callers that already have the message string. Prefer
+ * classifyError() at boundaries; this is exposed for cases where the
+ * message has already been extracted (e.g. truncated / sanitised).
+ */
+export declare function classifyMessage(msg: string): OomCause;
+/**
+ * Transient Durable Object reset — the object was reset by the platform
+ * mid-request for a reason unrelated to the request's own resource use:
+ * a code deploy rolling over, or a storage-subsystem cold-start hiccup.
+ * The in-flight request/RPC rejects, but the work itself never ran to a
+ * conclusion and is safe to re-attempt.
+ *
+ * Deliberately narrow: it must NOT match resource kills ("isolate exceeded
+ * its memory limit and was reset", "Durable Object exceeded its CPU time
+ * limit and was reset"), which classifyMessage() routes to 'oom' and
+ * 'cpu_exceeded' — those recur on retry and must surface, not loop. Note
+ * both end in "and was reset"; the checks below key on the CAUSE clause,
+ * never on the reset itself.
+ * Observed verbatim signatures:
+ *   - "Durable Object reset because its code was updated."
+ *   - "Internal error while starting up Durable Object storage caused
+ *      object to be reset; reference = ..."
+ *   - "Internal error in Durable Object storage caused object to be reset;
+ *      reference = ..."
+ *   - "Durable Object storage operation exceeded timeout which caused
+ *      the object to be reset."
+ *
+ * The second and third are the SAME condition worded for two moments —
+ * startup versus a live write — and only the first was matched here, which is
+ * why an object reset mid-write still failed a whole install. Nimbus has
+ * measured the live-write wording twice: a 45.7 MB single-turn write reset the
+ * object once and the same write then succeeded 12/12 on retry
+ * (`vfs/facet-resident-store.ts`), and it reset a session DO mid-npm-install
+ * on 2026-08-10 (probe `agentic-cli/new/pi-official-installer`). Retrying is
+ * bounded, so the one case that is NOT transient — crossing the object's
+ * storage budget, which the platform also reports this way
+ * (`loaders/process-fabric.ts`) — recurs, exhausts the budget and surfaces.
+ */
+export declare function isTransientDoReset(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."
+ *
+ * Distinct from `isTransientDoReset` on purpose. The object is alive and
+ * the work never started, so the call is safe to re-attempt — but the
+ * cause is queue pressure, so the only useful retry is one that backs off
+ * long enough for the queue to drain. Callers pair this with a longer
+ * backoff than a reset retry uses.
+ */
+export declare function isDoOverloaded(input: unknown): boolean;
+/**
+ * How one failed Durable Object call relates to a retry. The taxonomy
+ * Proteus hand-wrote in `cf-backend/src/lib/do-rpc.ts:71-79` because the
+ * Agents SDK does not export its own, plus the `overloaded` class both
+ * consumers need: Cloudflare documents that errors carry `.retryable` and
+ * `.overloaded`, that a retryable error should be retried with backoff on a
+ * FRESH stub, and that an overloaded one must not be retried at all
+ * (developers.cloudflare.com/durable-objects/best-practices/error-handling).
+ */
+export type DoCallClass = 
+/** A deploy replaced the isolate mid-call. */
+'superseded_isolate'
+/** The stub or storage connection dropped. */
+ | 'connection_lost'
+/** Storage reset the object — cold start, live write, or a timeout. */
+ | 'storage_reset'
+/** The runtime flagged the error `retryable` itself. */
+ | 'retryable_flag'
+/** The object shed the call under queue pressure. NEVER retried: retrying
+ *  an overloaded object is what overloaded it. */
+ | 'overloaded'
+/** Everything else — the call ran and the answer is the error. */
+ | 'permanent';
+/** The classes a fresh-stub retry may act on. `overloaded` is deliberately
+ *  outside: the platform's own docs forbid retrying it. */
+export declare function isRetryableDoCall(input: DoCallClass): boolean;
+/**
+ * Classify one failed Durable Object call. Overloaded is checked first, per
+ * link, because it vetoes everything: an overloaded-and-retryable error is
+ * overloaded. The `.retryable` flag is also read per link — it is a
+ * property, not prose, so the rendered chain cannot carry it. The walk is
+ * cycle-guarded.
+ */
+export declare function classifyDoCall(input: unknown): DoCallClass;
+/**
+ * One line about a failure, in terms someone can act on.
+ *
+ * npm install's catch sites each wrote `e?.remoteMessage || e?.message ||
+ * String(e)`. That reduces a failure to a bare sentence, and when the platform
+ * declines to describe a rejected Durable Object call the sentence is the word
+ * `internal error` — which is how `resolver-fanout layer 2 failed: internal
+ * error` reached users for months carrying nothing at all. The message is
+ * often the least we know: the error's class, whether the description came
+ * from a remote isolate, and which condition it classifies as are all still in
+ * hand, and naming them costs nothing and invents nothing.
+ */
+export declare function describeError(input: unknown): string;
+export {};
+//# sourceMappingURL=oom-classify.d.ts.map

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

@@ -0,0 +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,CAkErD;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,CAgBpD"}

package/dist/oom-classify.js

@@ -0,0 +1,336 @@
+/**
+ * oom-classify.ts — discriminator for OOM-like errors at Nimbus
+ * boundaries.
+ *
+ * Why this exists
+ * ───────────────
+ * Nimbus has at least five distinct "the work failed" failure modes
+ * that all surface today as either a thrown JS Error or a console
+ * line:
+ *
+ *   1. SQLITE_NOMEM at the storage layer (per-DO SQLite cap, post-
+ *      STOR/SPEC: Address SQLITE_NOMEM issues).
+ *   2. Isolate memory exhaustion → 'oom'.
+ *   3. Isolate CPU-budget exhaustion → 'cpu_exceeded'.
+ *   4. Structured-clone refusal (`Cannot deserialize cloned data`)
+ *      between supervisor ↔ facet RPC (32 MiB cap).
+ *   5. RPC timeout (TimeoutError from facet-pool's per-task race).
+ *
+ * Plus a few platform-side terminations (subrequest cap, condemnation,
+ * hard eviction) that the user sees but Nimbus has no first-party
+ * signal for.
+ *
+ * Memory and CPU are separate buckets
+ * ───────────────────────────────────
+ * workerd models them as distinct trace outcomes — `exceededMemory` vs
+ * `exceededCpu` (EventOutcome, workerd/io/outcome.capnp) — and words the
+ * two message families so neither one's signature appears in the other:
+ *
+ *   memory  "Worker has exceeded memory limit."
+ *           "Worker exceeded memory limit."
+ *           "broken.exceededMemory; jsg.Error: Durable Object's isolate
+ *            exceeded its memory limit …"
+ *           "Memory limit exceeded"                    (RangeError)
+ *   cpu     "Worker exceeded CPU time limit."
+ *           "Durable Object exceeded its CPU time limit and was reset."
+ *           "Python Worker exceeded CPU time limit"
+ *
+ * Read a low 'cpu_exceeded' count carefully: neither condition reliably
+ * produces a message. Both are uncatchable inside the isolate that died,
+ * so the string is only observable by a CALLER across an RPC boundary,
+ * and Nimbus has repeatedly measured isolates vanishing with no throw at
+ * all. Absence of 'cpu_exceeded' entries is therefore NOT evidence that
+ * CPU was not the cause — confirm against `wrangler tail` either way.
+ *
+ * Without a classifier, every recordFailure() call has to stringify-
+ * match its own error site. With this module, we pin the regex once
+ * and reuse it everywhere.
+ *
+ * Inputs we accept
+ * ────────────────
+ * The classifier accepts:
+ *   - Error instances (read e.message)
+ *   - plain strings (use directly — for stderr-line classification at
+ *     facet-exit boundaries where we don't have an Error)
+ *   - anything else (return 'unknown')
+ *
+ * Output values
+ * ─────────────
+ * Same set used by `DiagFailure.cause` in oom-discriminator.ts. Keep
+ * the union narrow and additive — adding a new value is fine, but
+ * never re-purpose an existing one.
+ */
+const OOM_CAUSES = [
+    'sqlite_nomem',
+    'sqlite_full',
+    'oom',
+    'cpu_exceeded',
+    'clone_refused',
+    'rpc_timeout',
+    'subrequest_cap',
+    'dynamic_worker_cap',
+    'condemnation',
+    'hard_evict',
+    'unknown',
+];
+export function isOomCause(input) {
+    return OOM_CAUSES.some((cause) => cause === input);
+}
+/**
+ * Classify an error or message string into an OomCause. Returns
+ * 'unknown' when no signature matches — callers should still record
+ * the message via DiagFailure.message so a human can later widen the
+ * classifier rules.
+ */
+export function classifyError(input) {
+    const msg = readMessage(input);
+    if (msg.length === 0)
+        return 'unknown';
+    return classifyMessage(msg);
+}
+/**
+ * Variant for callers that already have the message string. Prefer
+ * classifyError() at boundaries; this is exposed for cases where the
+ * message has already been extracted (e.g. truncated / sanitised).
+ */
+export function classifyMessage(msg) {
+    // Use lower-case match for forgiveness; SQLITE_NOMEM is canonically
+    // upper but stderr can be either.
+    const m = msg.toLowerCase();
+    // SQLITE_FULL: the 10 GB storage wall (platform catalog do.storage.bytes,
+    // DO_STORAGE_LIMIT_BYTES). A DIFFERENT condition from NOMEM with the
+    // opposite remedy: reads and DELETEs keep working, so the recovery is to
+    // drain data — where NOMEM asks for a smaller transaction. agent-core maps
+    // this to the same generic code as a malformed statement, which is the
+    // defect this split exists to avoid.
+    if (m.includes('sqlite_full'))
+        return 'sqlite_full';
+    if (m.includes('database or disk is full'))
+        return 'sqlite_full';
+    // SQLITE_NOMEM signals
+    if (m.includes('sqlite_nomem'))
+        return 'sqlite_nomem';
+    if (m.includes('out of memory'))
+        return 'sqlite_nomem';
+    // Structured-clone refusal — a 32 MiB-cap cousin
+    if (m.includes('deserialize cloned data'))
+        return 'clone_refused';
+    if (m.includes('could not be cloned'))
+        return 'clone_refused';
+    // RPC timeout (Nimbus's TimeoutError from facet-pool)
+    if (m.includes('timeouterror'))
+        return 'rpc_timeout';
+    if (/\btimed?\s*out\b/.test(m))
+        return 'rpc_timeout';
+    // Subrequest cap (Cloudflare platform)
+    if (m.includes('too many subrequests'))
+        return 'subrequest_cap';
+    // Worker Loader concurrency cap (Cloudflare platform): a Durable Object
+    // admits ~5-6 concurrent dynamic workers, and loader-cache entries are
+    // never released — every distinct loader.get(id) permanently consumes a
+    // slot, so this cap recurs until the DO itself is replaced.
+    if (m.includes('too many concurrent dynamic workers'))
+        return 'dynamic_worker_cap';
+    // Memory exhaustion. workerd trace outcome `exceededMemory`; in-band it
+    // arrives as a `broken.exceededMemory` actor break, a "…exceeded [its]
+    // memory limit" kill, or the "Memory limit exceeded" RangeError.
+    if (m.includes('exceededmemory'))
+        return 'oom';
+    if (/exceeded (?:its )?memory limit/.test(m))
+        return 'oom';
+    if (m.includes('memory limit exceeded'))
+        return 'oom';
+    if (m.includes('memory limit') && m.includes('reset'))
+        return 'oom';
+    // CPU-budget exhaustion. A DIFFERENT platform condition from memory —
+    // workerd reports it as trace outcome `exceededCpu`. Never fold the two:
+    // a CPU kill recurs on the same input, a memory kill recurs on the same
+    // working-set size, and the remedies are opposites.
+    //
+    // `cpu time limit` covers both scopes, which differ only by the
+    // possessive: "Worker exceeded CPU time limit." and "Durable Object
+    // exceeded its CPU time limit and was reset."
+    //
+    // Wall-clock handler timeouts are deliberately NOT matched here.
+    // "Actor exceeded event execution time and was disconnected." is the
+    // caller-configurable setHibernatableWebSocketEventTimeout() bound and
+    // "Alarm exceeded its allowed execution time" is its alarm twin. Both
+    // are elapsed-time bounds a handler blocked on I/O trips without burning
+    // CPU, so bucketing them here would repeat the merge this split undoes.
+    if (m.includes('cpu time limit'))
+        return 'cpu_exceeded';
+    if (m.includes('exceeded cpu limit'))
+        return 'cpu_exceeded';
+    // Explicit eviction (per CF research §A.1.2)
+    if (m.includes('condemned'))
+        return 'condemnation';
+    if (m.includes('hard evict'))
+        return 'hard_evict';
+    return 'unknown';
+}
+/**
+ * Transient Durable Object reset — the object was reset by the platform
+ * mid-request for a reason unrelated to the request's own resource use:
+ * a code deploy rolling over, or a storage-subsystem cold-start hiccup.
+ * The in-flight request/RPC rejects, but the work itself never ran to a
+ * conclusion and is safe to re-attempt.
+ *
+ * Deliberately narrow: it must NOT match resource kills ("isolate exceeded
+ * its memory limit and was reset", "Durable Object exceeded its CPU time
+ * limit and was reset"), which classifyMessage() routes to 'oom' and
+ * 'cpu_exceeded' — those recur on retry and must surface, not loop. Note
+ * both end in "and was reset"; the checks below key on the CAUSE clause,
+ * never on the reset itself.
+ * Observed verbatim signatures:
+ *   - "Durable Object reset because its code was updated."
+ *   - "Internal error while starting up Durable Object storage caused
+ *      object to be reset; reference = ..."
+ *   - "Internal error in Durable Object storage caused object to be reset;
+ *      reference = ..."
+ *   - "Durable Object storage operation exceeded timeout which caused
+ *      the object to be reset."
+ *
+ * The second and third are the SAME condition worded for two moments —
+ * startup versus a live write — and only the first was matched here, which is
+ * why an object reset mid-write still failed a whole install. Nimbus has
+ * measured the live-write wording twice: a 45.7 MB single-turn write reset the
+ * object once and the same write then succeeded 12/12 on retry
+ * (`vfs/facet-resident-store.ts`), and it reset a session DO mid-npm-install
+ * on 2026-08-10 (probe `agentic-cli/new/pi-official-installer`). Retrying is
+ * bounded, so the one case that is NOT transient — crossing the object's
+ * storage budget, which the platform also reports this way
+ * (`loaders/process-fabric.ts`) — recurs, exhausts the budget and surfaces.
+ */
+export function isTransientDoReset(input) {
+    const m = readMessage(input).toLowerCase();
+    if (m.length === 0)
+        return false;
+    if (m.includes('reset because its code was updated'))
+        return true;
+    if (m.includes('durable object storage caused object to be reset'))
+        return true;
+    if (m.includes('storage operation') && m.includes('reset'))
+        return true;
+    return false;
+}
+/**
+ * Workerd shed the call because the target Durable Object's input-gate
+ * queue was too deep or too old: "Durable Object is overloaded."
+ *
+ * Distinct from `isTransientDoReset` on purpose. The object is alive and
+ * the work never started, so the call is safe to re-attempt — but the
+ * cause is queue pressure, so the only useful retry is one that backs off
+ * long enough for the queue to drain. Callers pair this with a longer
+ * backoff than a reset retry uses.
+ */
+export function isDoOverloaded(input) {
+    return readMessage(input).toLowerCase().includes('durable object is overloaded');
+}
+/** The classes a fresh-stub retry may act on. `overloaded` is deliberately
+ *  outside: the platform's own docs forbid retrying it. */
+export function isRetryableDoCall(input) {
+    return input === 'superseded_isolate'
+        || input === 'connection_lost'
+        || input === 'storage_reset'
+        || input === 'retryable_flag';
+}
+/**
+ * Prose signatures of the transient classes, matched against the rendered
+ * cause chain — a wrapper error (Proteus measured its SqlError doing this)
+ * drops the `.retryable` property, so only the joined prose survives it.
+ *
+ * `storage_reset` carries the live-write wording on purpose. Proteus's
+ * mirror of the SDK matcher excludes it because a storage-budget breach is
+ * reported the same way; Nimbus measured the reset-mid-write case succeed
+ * 12/12 on retry ({@link isTransientDoReset}), and a bounded retry lets the
+ * budget-wall case recur and surface.
+ */
+const DO_CALL_TRANSIENT = [
+    ['superseded_isolate', /reset because its code was updated|this script has been upgraded/i],
+    ['connection_lost', /network connection lost/i],
+    ['storage_reset', /durable object storage caused object to be reset|storage operation exceeded timeout which caused the object to be reset/i],
+];
+/**
+ * Classify one failed Durable Object call. Overloaded is checked first, per
+ * link, because it vetoes everything: an overloaded-and-retryable error is
+ * overloaded. The `.retryable` flag is also read per link — it is a
+ * property, not prose, so the rendered chain cannot carry it. The walk is
+ * cycle-guarded.
+ */
+export function classifyDoCall(input) {
+    if (!(input instanceof Error))
+        return 'permanent';
+    const seen = new Set();
+    const messages = [];
+    let flagged = false;
+    let link = input;
+    while (link !== null && !seen.has(link)) {
+        seen.add(link);
+        const overloaded = ('overloaded' in link && link.overloaded === true)
+            || isDoOverloaded(link.message);
+        if (overloaded)
+            return 'overloaded';
+        if ('retryable' in link && link.retryable === true)
+            flagged = true;
+        messages.push(link.message ?? '');
+        const cause = link.cause;
+        link = cause instanceof Error ? cause : null;
+    }
+    const chain = messages.join('; ');
+    for (const [transient, pattern] of DO_CALL_TRANSIENT) {
+        if (pattern.test(chain))
+            return transient;
+    }
+    if (flagged)
+        return 'retryable_flag';
+    return 'permanent';
+}
+/**
+ * One line about a failure, in terms someone can act on.
+ *
+ * npm install's catch sites each wrote `e?.remoteMessage || e?.message ||
+ * String(e)`. That reduces a failure to a bare sentence, and when the platform
+ * declines to describe a rejected Durable Object call the sentence is the word
+ * `internal error` — which is how `resolver-fanout layer 2 failed: internal
+ * error` reached users for months carrying nothing at all. The message is
+ * often the least we know: the error's class, whether the description came
+ * from a remote isolate, and which condition it classifies as are all still in
+ * hand, and naming them costs nothing and invents nothing.
+ */
+export function describeError(input) {
+    const remote = typeof input === 'object' && input !== null
+        ? input.remoteMessage
+        : undefined;
+    const message = (typeof remote === 'string' && remote.length > 0)
+        ? `${remote} (remote)`
+        : readMessage(input) || String(input);
+    const name = input instanceof Error && input.name && input.name !== 'Error'
+        ? `${input.name}: `
+        : '';
+    const cause = classifyError(input);
+    const suffix = cause !== 'unknown' ? ` [${cause}]`
+        : isTransientDoReset(input) ? ' [transient-do-reset]'
+            : isDoOverloaded(input) ? ' [do-overloaded]'
+                : '';
+    return `${name}${message}${suffix}`;
+}
+function readMessage(input) {
+    if (input == null)
+        return '';
+    if (typeof input === 'string')
+        return input;
+    if (input instanceof Error)
+        return input.message ?? '';
+    // Some thrown values are plain objects with .message
+    if (typeof input === 'object') {
+        const m = input.message;
+        if (typeof m === 'string')
+            return m;
+    }
+    try {
+        return String(input);
+    }
+    catch {
+        return '';
+    }
+}