@nimbus-sh/platform 0.7.0 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nimbus-sh/platform",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "The measured Cloudflare platform truths Nimbus is built on \u2014 error taxonomy, limits tables, budget coordination, and wire-format primitives, with zero runtime dependencies.",
   "keywords": [
     "cloudflare",

package/src/diag-counters.ts

@@ -120,6 +120,15 @@ export interface DiagCounters {
      *  Empty when the most recent batch had zero errors. */
     errorsByModule: Record<string, string>;
   };
+  /**
+   * File contents and stdin the session has handed its processes, cumulative
+   * since isolate start: the bytes of each supervisor envelope's answer as it
+   * leaves the session (worker session/supervisor-op.ts answerSupervisorOp)
+   * from readFile, readFileBytes, fsRead, fsReadRange, fsReadBatch, the read
+   * an fsAcquired carries, and cpReadStdin (a pipe's read ahead). A run's
+   * delta is what it was handed, which bounds what it can hold.
+   */
+  supervisorAnsweredBytes: number;
   /** Pipelined R2 race outcomes. All counts are cumulative since
    *  DO-isolate start. Per-tier cache statistics live in cache-stats. */
   r2: {
@@ -141,6 +150,7 @@ const _counters: DiagCounters = {
   inFlightRpcPayloadBytes: 0,
   prefetchBundleBytes: 0,
   prefetchCacheBytes: 0,
+  supervisorAnsweredBytes: 0,
   installFacet: {
     tarballsCompleted: 0,
     cumulativeBytesDecoded: 0,
@@ -167,6 +177,11 @@ export function readDiagCounters(): DiagCounters {
   return { ..._counters };
 }
 
+/** Count `bytes` the session answered a process's supervisor call with. */
+export function recordSupervisorAnswer(bytes: number): void {
+  _counters.supervisorAnsweredBytes += bytes;
+}
+
 /** Set the install phase. */
 export function setInstallPhase(p: InstallPhase): void {
   _counters.installPhase = p;

package/src/heavy-alloc-coord.ts

@@ -82,12 +82,21 @@ export class SupervisorAllocationBudget {
     return this._acquire(bytes, signal, false);
   }
 
+  /** Reserve bytes now or not at all, driving the lifecycle as acquire does. */
+  tryAcquire(bytes: number): ResizableCreditLease | null {
+    const credit = this.credits.tryAcquire(bytes);
+    return credit ? this.wrap(credit, true) : null;
+  }
+
   private async _acquire(
     bytes: number,
     signal: AbortSignal | undefined,
     drivesLifecycle: boolean,
   ): Promise<ResizableCreditLease> {
-    const credit = await this.credits.acquire(bytes, signal);
+    return this.wrap(await this.credits.acquire(bytes, signal), drivesLifecycle);
+  }
+
+  private wrap(credit: ResizableCreditLease, drivesLifecycle: boolean): ResizableCreditLease {
     if (drivesLifecycle) {
       this.lifecycleHolders++;
       if (!this.active) {
@@ -212,6 +221,11 @@ export function acquireSupervisorAllocation(
   return supervisorAllocationBudget.acquire(bytes, signal);
 }
 
+/** Reserve bytes now if they can be granted without waiting, else null. */
+export function tryAcquireSupervisorAllocation(bytes: number): ResizableCreditLease | null {
+  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/src/limits.ts

@@ -66,13 +66,6 @@ export const HYDRATION_DEADLINE_MS = 30_000;
  */
 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
@@ -196,6 +189,14 @@ export const SUPERVISOR_HEAP_CEILING_BYTES = 64 * 1024 * 1024;
 // 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/src/lost-call.ts

@@ -0,0 +1,80 @@
+/**
+ * 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: readonly number[] = [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: unknown): boolean {
+  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: {
+  operation: string;
+  attempt: number;
+  of: number;
+  reason: string;
+}): Record<string, string | number> {
+  return {
+    'do_call.operation': lost.operation,
+    'do_call.attempts': lost.attempt,
+    'do_call.max_attempts': lost.of,
+    'do_call.lost_reason': lost.reason,
+  };
+}

package/src/oom-classify.ts

@@ -209,6 +209,38 @@ export function isTransientDoReset(input: unknown): boolean {
   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: unknown): boolean {
+  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: readonly RegExp[] = [
+  /^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: unknown): boolean {
+  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/src/retry.ts

@@ -0,0 +1,74 @@
+/**
+ * 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: readonly number[], attempt: number): number {
+  const base = schedule[Math.min(attempt, schedule.length - 1)] ?? 0;
+  return Math.max(0, Math.round(base + (Math.random() * 2 - 1) * base * 0.25));
+}
+
+/** 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 async function retrying<T>(attempt: (n: number) => Promise<T>, policy: RetryPolicy<T>): Promise<T> {
+  for (let n = 0; ; n++) {
+    let outcome: RetryOutcome<T>;
+    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<void>((resolve) => setTimeout(resolve, delayMs));
+  }
+}

package/src/utf8.ts

@@ -0,0 +1,31 @@
+/**
+ * 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: string): number {
+  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;
+}