@nimbus-sh/platform 0.5.1 → 0.7.0

package/src/heavy-alloc-coord.ts

@@ -24,8 +24,6 @@ export interface SupervisorAllocationBudgetStats {
   readonly current: number;
   readonly peak: number;
   readonly queued: number;
-  /** Credit held for an owner's whole lifetime; see `acquireResident`. */
-  readonly resident: number;
 }
 
 interface AllocationBudgetLifecycle {
@@ -84,24 +82,12 @@ export class SupervisorAllocationBudget {
     return this._acquire(bytes, signal, false);
   }
 
-  /**
-   * Reserve bytes an owner holds for its whole lifetime, not for one
-   * operation. Recorded as a floor: a later claim larger than what remains
-   * around it is refused with both numbers rather than parked forever.
-   */
-  acquireResidentBytes(bytes: number, signal?: AbortSignal): Promise<ResizableCreditLease> {
-    return this._acquire(bytes, signal, true, true);
-  }
-
   private async _acquire(
     bytes: number,
     signal: AbortSignal | undefined,
     drivesLifecycle: boolean,
-    resident = false,
   ): Promise<ResizableCreditLease> {
-    const credit = resident
-      ? await this.credits.acquireResident(bytes, signal)
-      : await this.credits.acquire(bytes, signal);
+    const credit = await this.credits.acquire(bytes, signal);
     if (drivesLifecycle) {
       this.lifecycleHolders++;
       if (!this.active) {
@@ -238,17 +224,6 @@ export function acquireSupervisorReadAllocation(
   return supervisorAllocationBudget.acquireWithoutLifecycle(bytes, signal);
 }
 
-/**
- * Reserve bytes for the whole life of the owner that takes them — an image
- * a pool keeps until it is disposed. See `acquireResidentBytes`.
- */
-export function acquireResidentSupervisorAllocation(
-  bytes: number,
-  signal?: AbortSignal,
-): Promise<ResizableCreditLease> {
-  return supervisorAllocationBudget.acquireResidentBytes(bytes, signal);
-}
-
 /**
  * Reserve the full budget for an allocation whose retained size is not known
  * accurately enough to overlap safely with other heavy work.

package/src/limits.ts

@@ -52,6 +52,12 @@ export const SQL_MAX_BOUND_PARAMETERS = 100;
  */
 export const DO_STORAGE_LIMIT_BYTES = 10_000_000_000;
 
+// N17: how long a launch that reads synchronously (WASI) waits for the paths
+// it names to hydrate out of a lazy import before it fails with EIO naming
+// the first that is not local. Bounded so a fetch that never resolves cannot
+// hold a launch forever.
+export const HYDRATION_DEADLINE_MS = 30_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
@@ -119,7 +125,7 @@ export const RESIDENT_KEEPALIVE_DETACHED_MS = 60_000;
 
 /**
  * Bytes one hibernatable WebSocket attachment may serialize to. Verified in
- * workerd source at the pinned version (v1.20260603.1,
+ * workerd source at the pinned version (v1.20260926.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
@@ -136,6 +142,25 @@ export const WS_ATTACHMENT_LIMIT_BYTES = 16_384;
 // metadata and matches the proven on-demand facet transfer envelope.
 export const MAX_RPC_SAFE_PAYLOAD_BYTES = 28 * 1024 * 1024;
 
+// ── A one-shot's module map [#13] ───────────────────────────────────────
+//
+// The largest one-shot module map (its closure's raw bytes) the session DO
+// builds and hands to the Worker Loader. What limits it is the DO, not the
+// loader (whose documented limits are concurrency only): the map is built,
+// serialized and passed on from the DO's 128 MB isolate.
+//
+// Measured on a throwaway (2026-09-26; session DO max memoryUsageBytes from
+// GraphQL durableObjectsPeriodicGroups, one launch per minute; a package of
+// 256 KiB distinct modules required whole, verify/release/do-headroom.md),
+// with the map serialized one side module at a time:
+//   4 MiB 64 MB, 8 MiB 81 MB, 12 MiB 97 MB, 16 MiB 110 MB, 20 MiB 126 MB,
+//   24 MiB 145 MB, 28 MiB 164 MB, over an idle 40-55 MB.
+// That is about 4.5 MB of DO per MiB of map. 18 MiB, about 118 MB, is the
+// largest size that leaves about 10 MB of the 128 MB for the rest of the
+// session's work. (Before the single-copy build it was 6-7 MB per MiB: 24 MiB
+// reset the DO.)
+export const ONE_SHOT_MODULE_MAP_MAX_BYTES = 18 * 1024 * 1024;
+
 // ── Supervisor heap budget [C'.1] ───────────────────────────────────────
 //
 // Three distinct memory regimes, not one shared pool:
@@ -165,6 +190,12 @@ export const MAX_RPC_SAFE_PAYLOAD_BYTES = 28 * 1024 * 1024;
 // percentOfCeiling accordingly.
 export const SUPERVISOR_HEAP_CEILING_BYTES = 64 * 1024 * 1024;
 
+// A process facet's own writes its store could not hold (N18: the session's
+// storage is full) are kept in its heap instead, so a write-then-read still
+// 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;
+
 // 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/oom-classify.ts

@@ -127,11 +127,12 @@ export function classifyMessage(msg: string): OomCause {
   // 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';
+  // Dynamic Worker concurrency limit (Cloudflare platform): a Durable Object
+  // may have a fixed number of distinct Dynamic Workers with in-flight
+  // requests at once (fabric budgets.ts, DO_DYNAMIC_WORKER_LIMIT). Production
+  // words it "Dynamic worker concurrency limit exceeded: each request may
+  // have up to 10 concurrent dynamic worker invocations. …".
+  if (m.includes('dynamic worker concurrency limit exceeded')) return 'dynamic_worker_cap';
 
   // Memory exhaustion. workerd trace outcome `exceededMemory`; in-band it
   // arrives as a `broken.exceededMemory` actor break, a "…exceeded [its]
@@ -224,7 +225,7 @@ export 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
+ * Proteus originally hand-wrote in `cf-backend/src/lib/do-rpc.ts` 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
@@ -329,6 +330,7 @@ export function describeError(input: unknown): string {
   const suffix = cause !== 'unknown' ? ` [${cause}]`
     : isTransientDoReset(input) ? ' [transient-do-reset]'
     : isDoOverloaded(input) ? ' [do-overloaded]'
+    : classifyDoCall(input) === 'retryable_flag' ? ' [retryable]'
     : '';
   return `${name}${message}${suffix}`;
 }

package/src/tracing.ts

@@ -0,0 +1,129 @@
+/**
+ * tracing.ts — Workers custom spans, for modules that cannot import
+ * `cloudflare:workers`, as best-effort telemetry that never changes an
+ * outcome.
+ *
+ * The span API is `tracing` from `cloudflare:workers`
+ * (https://developers.cloudflare.com/workers/observability/traces/custom-spans/):
+ * `enterSpan(name, callback)` runs the callback in a span that is the active
+ * parent of every span and platform call made inside it — automatic RPC
+ * spans included — and ends it when the callback returns or its promise
+ * settles. A span records nothing unless the invocation was head-sampled
+ * (`observability.traces.head_sampling_rate`).
+ *
+ * `setAttributes` and `recordException` shipped on 2026-09-25
+ * (https://developers.cloudflare.com/changelog/post/2026-09-25-custom-span-apis/);
+ * a runtime from before then has `isTraced` and `setAttribute` only. So the
+ * code being traced never touches the runtime's span. It gets a
+ * {@link SpanRecorder}, which records only while the span is traced, uses
+ * whichever methods the runtime has, and swallows anything a span method
+ * throws.
+ *
+ * Core and fabric stay importable outside workerd, so they reach the API
+ * through this leaf: the Worker's composition root hands it over once, at
+ * module scope, with {@link adoptTracing}, exactly as it does `ctx.exports`
+ * (./composition.ts). With nothing adopted — unit tests, an embedder that
+ * never adopts — {@link traced} runs its callback with {@link untraced}.
+ */
+
+/** Attribute values a span holds; `undefined` entries are ignored. */
+export type SpanAttributes = Record<string, string | number | boolean | undefined>;
+
+/** The runtime's `Span`, as any Workers runtime with `tracing` may have it. */
+export interface RuntimeSpan {
+  readonly isTraced: boolean;
+  setAttribute?(key: string, value?: string | number | boolean): unknown;
+  setAttributes?(attributes: SpanAttributes): unknown;
+  recordException?(
+    exception: string | { code?: string | number; name?: string; message?: string; stack?: string },
+  ): void;
+}
+
+/** The part of `cloudflare:workers`'s `tracing` Nimbus uses. */
+export interface Tracer {
+  enterSpan<T>(name: string, callback: (span: RuntimeSpan) => T): T;
+}
+
+/** What traced code records on its span. Never throws; records nothing unless the span is traced. */
+export interface SpanRecorder {
+  set(attributes: SpanAttributes): void;
+  /**
+   * Record `error` as an exception event. `code`, when given, replaces the
+   * error's own; `context` is prefixed to its message.
+   */
+  exception(error: unknown, code?: string, context?: string): void;
+}
+
+/** The recorder of a span that is not traced, or of no span at all. */
+export const untraced: SpanRecorder = Object.freeze({ set() {}, exception() {} });
+
+let tracer: Tracer | null = null;
+
+/** Hand this isolate's `tracing` over. The first adoption stands, like `adoptCtxExports`. */
+export function adoptTracing(value: Tracer): void {
+  tracer ??= value;
+}
+
+function recorderFor(span: RuntimeSpan): SpanRecorder {
+  try {
+    if (!span.isTraced) return untraced;
+  } catch {
+    return untraced;
+  }
+  return {
+    set(attributes) {
+      try {
+        if (typeof span.setAttributes === 'function') {
+          span.setAttributes(attributes);
+        } else if (typeof span.setAttribute === 'function') {
+          for (const [key, value] of Object.entries(attributes)) {
+            if (value !== undefined) span.setAttribute(key, value);
+          }
+        }
+      } catch { /* telemetry is best-effort */ }
+    },
+    exception(error, code, context = '') {
+      try {
+        if (typeof span.recordException !== 'function') return;
+        if (error instanceof Error) {
+          const own = 'code' in error ? error.code : undefined;
+          span.recordException({
+            code: code ?? (typeof own === 'string' || typeof own === 'number' ? own : undefined),
+            name: error.name,
+            message: context + error.message,
+            stack: error.stack,
+          });
+        } else {
+          span.recordException(code === undefined && !context
+            ? String(error)
+            : { code, message: context + String(error) });
+        }
+      } catch { /* telemetry is best-effort */ }
+    },
+  };
+}
+
+/**
+ * Run `fn` in a span named `name` carrying `attributes`, and record on it the
+ * exception `fn` throws or its promise rejects with. What `fn` returns or
+ * throws reaches the caller unchanged, whatever the span does.
+ */
+export function traced<T>(name: string, attributes: SpanAttributes, fn: (span: SpanRecorder) => T): T {
+  if (!tracer) return fn(untraced);
+  return tracer.enterSpan(name, (runtimeSpan) => {
+    const span = recorderFor(runtimeSpan);
+    span.set(attributes);
+    let result: T;
+    try {
+      result = fn(span);
+    } catch (error) {
+      span.exception(error);
+      throw error;
+    }
+    if (!(result instanceof Promise)) return result;
+    return result.catch((error: unknown) => {
+      span.exception(error);
+      throw error;
+    }) as T;
+  });
+}

package/src/w7-frame.ts

@@ -3,6 +3,7 @@
  * The format is internal: every producer and consumer deploys together.
  */
 
+import { crc32 } from './crc32.js';
 import { CHUNK_SIZE } from './limits.js';
 
 // The batch payload types live WITH the wire format that encodes them: every
@@ -246,7 +247,7 @@ export async function decodeWriteBatchStream(
     }
     const beginPayload = await buffer.readExact(beginEnvelope.length, 'batch-begin payload');
     const begin = parseBatchBegin(beginPayload);
-    const initialCheck = updateRecordCheck(CRC_SEED, beginEnvelope.header, beginPayload);
+    const initialCheck = updateRecordCheck(0, beginEnvelope.header, beginPayload);
     handedOff = true;
     return {
       batchId: begin.id,
@@ -343,7 +344,7 @@ async function* decodeRecords(
           throwIfAborted(options.signal);
           const data = await buffer.readExact(dataLength, 'file-chunk data');
           batchCheck = updateRecordCheck(batchCheck, envelope.header, headerPayload, data);
-          active.check = crc32Update(active.check, data);
+          active.check = crc32(data, active.check);
           active.nextChunkId++;
           active.receivedBytes += dataLength;
           summary.recordCount++;
@@ -406,7 +407,7 @@ async function* decodeRecords(
             inode,
             nextChunkId: 0,
             receivedBytes: 0,
-            check: CRC_SEED,
+            check: 0,
           };
           yield { type: 'file-begin', streamContentId: metadata.contentId, inode };
           break;
@@ -414,7 +415,7 @@ async function* decodeRecords(
         case RecordTag.FileEnd: {
           if (!active) throw new Error('w7-frame: file-end without active file');
           const metadata = parseFileEnd(payload);
-          const actualCheck = crc32Finish(active.check);
+          const actualCheck = active.check;
           if (metadata.contentId !== active.metadata.contentId) {
             throw new Error(`w7-frame: file-end content id mismatch for ${active.inode.path}`);
           }
@@ -443,7 +444,7 @@ async function* decodeRecords(
         case RecordTag.BatchEnd: {
           if (active) throw new Error(`w7-frame: batch-end while file ${active.inode.path} is active`);
           const actual = parseBatchEnd(payload);
-          const expected = { ...summary, check: crc32Finish(batchCheck) };
+          const expected = { ...summary, check: batchCheck };
           if (!sameSummary(actual, expected)) {
             throw new Error(
               `w7-frame: batch-end summary mismatch; expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`,
@@ -479,7 +480,7 @@ function* encodeRecords(
   files: EncoderFile[],
 ): Generator<Uint8Array[]> {
   const state: EncoderState = {
-    batchCheck: CRC_SEED,
+    batchCheck: 0,
     summary: {
       recordCount: 0,
       pathCount: 0,
@@ -514,7 +515,7 @@ function* encodeRecords(
       size: file.inode.size,
       chunkCount: file.inode.chunkCount,
     }, state);
-    let fileCheck = CRC_SEED;
+    let fileCheck = 0;
     for (const chunk of file.chunks) {
       const data = chunk.data;
       const contentBytes = new TextEncoder().encode(file.contentId);
@@ -528,19 +529,19 @@ function* encodeRecords(
       state.summary.recordCount++;
       state.summary.chunkCount++;
       state.summary.byteCount += data.byteLength;
-      fileCheck = crc32Update(fileCheck, data);
+      fileCheck = crc32(data, fileCheck);
       yield [concatBytes(header, prefix), data];
     }
     yield encodeMetadataRecord(RecordTag.FileEnd, {
       contentId: file.contentId,
       size: file.inode.size,
       chunkCount: file.inode.chunkCount,
-      check: crc32Finish(fileCheck),
+      check: fileCheck,
     }, state);
   }
   const end: W7BatchSummary = {
     ...state.summary,
-    check: crc32Finish(state.batchCheck),
+    check: state.batchCheck,
   };
   yield encodeMetadataRecord(RecordTag.BatchEnd, end);
 }
@@ -916,37 +917,10 @@ function readU32LE(bytes: Uint8Array, offset: number): number {
 
 function updateRecordCheck(seed: number, ...parts: Uint8Array[]): number {
   let check = seed;
-  for (const part of parts) check = crc32Update(check, part);
+  for (const part of parts) check = crc32(part, check);
   return check;
 }
 
-const CRC_SEED = 0xffff_ffff;
-let crcTable: Uint32Array | null = null;
-
-function crc32Update(check: number, bytes: Uint8Array): number {
-  crcTable ??= createCrcTable();
-  const table = crcTable;
-  let value = check;
-  for (const byte of bytes) value = table[(value ^ byte) & 0xff] ^ (value >>> 8);
-  return value >>> 0;
-}
-
-function crc32Finish(check: number): number {
-  return (check ^ 0xffff_ffff) >>> 0;
-}
-
-function createCrcTable(): Uint32Array {
-  const table = new Uint32Array(256);
-  for (let index = 0; index < table.length; index++) {
-    let value = index;
-    for (let bit = 0; bit < 8; bit++) {
-      value = (value & 1) !== 0 ? 0xedb8_8320 ^ (value >>> 1) : value >>> 1;
-    }
-    table[index] = value >>> 0;
-  }
-  return table;
-}
-
 function noopRetention(bytes: number): W7ChunkRetention {
   return { bytes, release() {} };
 }

package/src/weighted-credit-pool.ts

@@ -11,11 +11,6 @@ export interface WeightedCreditPoolStats {
   readonly current: number;
   readonly peak: number;
   readonly queued: number;
-  /**
-   * Credit held by owners that keep it for their whole lifetime rather than
-   * for one operation — the floor no waiter can ever expect to get back.
-   */
-  readonly resident: number;
 }
 
 export interface WeightedCreditPoolOptions {
@@ -34,8 +29,6 @@ export interface WeightedCreditPoolOptions {
 
 interface CreditWaiter {
   readonly bytes: number;
-  /** Whether the granted lease counts toward the resident floor. */
-  readonly resident: boolean;
   readonly resolve: (lease: ResizableCreditLease) => void;
   readonly reject: (error: Error) => void;
   readonly signal?: AbortSignal;
@@ -46,55 +39,27 @@ interface CreditWaiter {
 class CreditLane {
   private current = 0;
   private peak = 0;
-  private resident = 0;
   private readonly waiters: CreditWaiter[] = [];
 
   constructor(readonly capacity: number) {}
 
   get stats(): WeightedCreditPoolStats {
-    return {
-      current: this.current, peak: this.peak, queued: this.waiters.length, resident: this.resident,
-    };
+    return { current: this.current, peak: this.peak, queued: this.waiters.length };
   }
 
   tryAcquire(bytes: number): ResizableCreditLease | null {
     if (this.waiters.length > 0 || this.current + bytes > this.capacity) return null;
-    return this.grant(bytes, false);
-  }
-
-  /**
-   * The largest claim this lane can ever grant: capacity less what resident
-   * owners hold for their whole lifetime. A claim above it cannot be
-   * satisfied by waiting, because nothing it is waiting for will be
-   * released.
-   */
-  get grantableCeiling(): number {
-    return this.capacity - this.resident;
+    return this.grant(bytes);
   }
 
-  acquire(bytes: number, signal?: AbortSignal, resident = false): Promise<ResizableCreditLease> {
+  acquire(bytes: number, signal?: AbortSignal): Promise<ResizableCreditLease> {
     if (signal?.aborted) return Promise.reject(abortError(signal));
-    // Refuse a claim no amount of waiting can satisfy, rather than parking it
-    // in the FIFO forever. A parked claim is indistinguishable from a caller
-    // that stopped: no error, no timeout, and — because the queue refuses
-    // everyone behind it — no further progress anywhere in the isolate. That
-    // is what a real-vite launch looked like for four rounds of debugging.
-    if (bytes > this.grantableCeiling) {
-      return Promise.reject(new RangeError(
-        `weighted credit claim of ${bytes} bytes can never be granted: capacity is ${this.capacity} `
-        + `and ${this.resident} bytes are held by resident owners, leaving ${this.grantableCeiling}`,
-      ));
-    }
-    const immediate = resident ? null : this.tryAcquire(bytes);
+    const immediate = this.tryAcquire(bytes);
     if (immediate) return Promise.resolve(immediate);
-    if (resident && this.waiters.length === 0 && this.current + bytes <= this.capacity) {
-      return Promise.resolve(this.grant(bytes, true));
-    }
 
     return new Promise<ResizableCreditLease>((resolve, reject) => {
       const waiter: CreditWaiter = {
         bytes,
-        resident,
         resolve,
         reject,
         signal,
@@ -119,9 +84,8 @@ class CreditLane {
     });
   }
 
-  private grant(bytes: number, resident: boolean): ResizableCreditLease {
+  private grant(bytes: number): ResizableCreditLease {
     this.current += bytes;
-    if (resident) this.resident += bytes;
     this.peak = Math.max(this.peak, this.current);
     let leasedBytes = bytes;
     let released = false;
@@ -143,7 +107,6 @@ class CreditLane {
           );
         }
         this.current -= leasedBytes - nextBytes;
-        if (resident) this.resident -= leasedBytes - nextBytes;
         leasedBytes = nextBytes;
         this.drain();
       },
@@ -151,7 +114,6 @@ class CreditLane {
         if (released) return;
         released = true;
         this.current -= leasedBytes;
-        if (resident) this.resident -= leasedBytes;
         if (this.current < 0) {
           throw new Error('weighted credit accounting underflow');
         }
@@ -172,7 +134,7 @@ class CreditLane {
       if (this.current + waiter.bytes > this.capacity) return;
       this.waiters.shift();
       waiter.signal?.removeEventListener('abort', waiter.onAbort!);
-      waiter.resolve(this.grant(waiter.bytes, waiter.resident));
+      waiter.resolve(this.grant(waiter.bytes));
     }
   }
 }
@@ -233,7 +195,6 @@ export class WeightedCreditPool {
       current: general.current + small.current,
       peak: general.peak + small.peak,
       queued: general.queued + small.queued,
-      resident: general.resident + small.resident,
     };
   }
 
@@ -265,22 +226,6 @@ export class WeightedCreditPool {
     return this.general.acquire(bytes, signal);
   }
 
-  /**
-   * Take credit that will be held for the owner's whole lifetime rather than
-   * for one operation — the esbuild pool's wasm image is the case.
-   *
-   * Recorded as a floor so a later claim that could never fit around it is
-   * refused with both numbers instead of parking in the FIFO forever.
-   */
-  acquireResident(bytes: number, signal?: AbortSignal): Promise<ResizableCreditLease> {
-    try {
-      this.validateRequest(bytes);
-    } catch (error) {
-      return Promise.reject(error as Error);
-    }
-    return this.general.acquire(bytes, signal, true);
-  }
-
   private validateRequest(bytes: number): void {
     if (!Number.isSafeInteger(bytes) || bytes <= 0 || bytes > this.capacity) {
       throw new RangeError(