@nimbus-sh/core 0.1.0

package/dist/observability/heap-estimate.js

@@ -0,0 +1,185 @@
+/**
+ * heap-estimate.ts — deterministic supervisor-heap estimator [C'.1]
+ *
+ * Why this module exists
+ * ──────────────────────
+ * `process.memoryUsage()` returns 0 for every field inside a Durable
+ * Object class context (only dynamic-worker isolates under nodejs_compat
+ * get the real implementation). The previous `readNodeMem` /
+ * `sampleMemory` helpers in nimbus-session-diag.ts called it anyway and
+ * therefore reported zero forever — useless for verifying memory-
+ * containment work in plan §3 Track A'.
+ *
+ * Replacement: a deterministic estimator that sums the INSTRUMENTED
+ * supervisor heap allocation sources — runtime counters that ARE accurate
+ * (diag-counters.ts singleton + SqliteVFS.getStats()). Every byte it
+ * reports has a named contributor, so a regression in any one component
+ * is locatable.
+ *
+ * `estimatedBytes` is a LOWER BOUND, not a total
+ * ─────────────────────────────────────────────
+ * Within each instrumented component the estimator over-reports on
+ * purpose: components carry a peak-or-current value, in-flight bytes are
+ * counted before they are freed, and LRU bytes are the cap rather than the
+ * live footprint.
+ *
+ * Across components it can only sum what is instrumented. Allocation sites
+ * that neither bump a diag counter nor take a lease via
+ * `acquireSupervisorAllocation` are invisible to it, and it has no way to
+ * infer their size — so any site known to be uninstrumented is named in
+ * HEAP_BLIND_SPOTS rather than left silently absent.
+ *
+ * The prefetch-bundle path used to be exactly that gap, and a large one: the
+ * supervisor DO was reset three times under bundle construction while this
+ * estimator reported a 9.4 MiB baseline and 35 KB of LRU. Both of its sites
+ * are now instrumented where they allocate — the per-exec build leases the
+ * budget it spends (`prefetchBundleBytes`) and the cross-exec cache is bounded
+ * by bytes and reports its retained total (`prefetchCacheBytes`) — so they are
+ * components of the breakdown rather than caveats beside it.
+ *
+ * `blindSpots` is still returned alongside `estimatedBytes` because a list
+ * being empty is a claim that has to be re-earned as the system grows, not a
+ * property of the estimator. Closing a blind spot always means instrumenting
+ * it at its own allocation site and adding it to the breakdown — never
+ * estimating it from here.
+ *
+ * Eviction-label taxonomy
+ * ───────────────────────
+ * Workerd distinguishes five labelled eviction reasons:
+ *   - lru                       → memory pressure on the runtime process
+ *   - condemned                 → kill (operator / abuse pipeline)
+ *   - inactive                  → idle eviction (70-140 s of no traffic)
+ *   - dynamic_worker            → per-owner LRU cap (default 50)
+ *   - dynamic_worker_banned     → Dice abuse-detection ban
+ *
+ * Nimbus surfaces the labels here so any tool that reads
+ * /api/_diag/memory has a fixed, well-known taxonomy to count against.
+ * The actual count of evictions Nimbus has observed lives in the C'.2
+ * recovery_event ring, separate from this module.
+ */
+import { PRE_BUNDLE_CONCURRENCY, PRE_BUNDLE_SLICE_CAP_BYTES, SUPERVISOR_HEAP_CEILING_BYTES, } from '../constants.js';
+import { readSupervisorAllocationBudget, } from './heavy-alloc-coord.js';
+/**
+ * Five labelled workerd eviction reasons. Surfaced as a constant
+ * taxonomy in /api/_diag/memory so any consumer can count observed
+ * events against the well-known set.
+ *
+ */
+export const WORKERD_EVICTION_LABELS = [
+    'lru',
+    'condemned',
+    'inactive',
+    'dynamic_worker',
+    'dynamic_worker_banned',
+];
+/**
+ * Supervisor allocation sites known to be unaccounted for.
+ *
+ * Empty: both former entries were the prefetch-bundle path in
+ * facets/manager.ts, and both are now instrumented at their own allocation
+ * sites rather than described from here. `buildPrefetchBundle` takes an
+ * `acquireSupervisorAllocation` lease and reports
+ * `breakdown.prefetchBundleBytes`; `prefetchBundleCache` is bounded by
+ * PREFETCH_CACHE_MAX_BYTES instead of by entry count and reports its live
+ * retained total as `breakdown.prefetchCacheBytes`.
+ *
+ * An empty list says nothing is CURRENTLY known to be missing — it is not a
+ * proof of completeness, which no list can be. Adding an entry is how a newly
+ * discovered gap stays visible in /api/_diag/memory until it is closed the
+ * same way: instrumented where it allocates, then folded into HeapBreakdown.
+ */
+export const HEAP_BLIND_SPOTS = [];
+// ── Architectural constants for non-counter contributors ────────────────
+//
+// Each constant below has a comment explaining the source-of-truth and
+// when it is expected to change (typically: when a Track A' wave lands).
+// They are NOT runtime-measured because the underlying values aren't
+// observable from JS — they're properties of the worker bundle itself.
+/**
+ * Static supervisor baseline. The compiled worker bundle resident in V8
+ * isolate memory: module sources, class definitions, top-level imports,
+ * lookup tables.
+ *
+ * Phase 2 A'.5 dropped the 16 MiB esbuild-wasm base64 string from the
+ * generated module (it now lives in env.ASSETS), shrinking the worker
+ * bundle by ~21 MiB UTF-16-resident. Empirical baseline post-A'.5 is
+ * ~9 MiB (verified via the heap-estimator probe + bundle size).
+ *
+ * This is constant across a deploy. A bundle-size shrink (removing an
+ * unused dependency, splitting another big constant out to assets)
+ * would lower this further.
+ */
+const SUPERVISOR_BASELINE_BYTES = 9 * 1024 * 1024;
+/**
+ * Estimate pre-bundle slice bytes resident in the supervisor heap.
+ *
+ * Pre A'.2: the supervisor builds the slice in heap (up to
+ * SLICE_CAP_BYTES = 28 MiB per concurrent slot) before passing to the
+ * pre-bundle facet. With PRE_BUNDLE_CONCURRENCY = 1 the cap is 28 MiB.
+ *
+ * Diag counters track pre-bundle attempts/completions but not
+ * in-flight slice bytes specifically. Until A'.2 streams the slice,
+ * we treat the slice as PRESENT in supervisor heap iff the pre-bundle
+ * phase is active AND a slot is in flight (no completion yet for the
+ * current attempted count).
+ *
+ * After A'.2 lands the slice flows via ReadableStream-over-RPC and
+ * supervisor never holds the bytes — this contribution drops to 0.
+ */
+export function estimatePreBundleSliceBytes(c) {
+    // Conservative: if the most recent batch attempted >0 specs and the
+    // batch hasn't fully completed, assume one slice's worth of bytes
+    // are in flight.
+    const f = c.preBundleFacet;
+    const inFlight = f.attempted - f.bundlesCompleted - f.errors - f.skipped;
+    if (inFlight <= 0)
+        return 0;
+    return Math.min(inFlight, PRE_BUNDLE_CONCURRENCY) * PRE_BUNDLE_SLICE_CAP_BYTES;
+}
+/**
+ * Build a heap estimate from runtime counters + VFS inputs.
+ *
+ * Deterministic and I/O-free. Called from the /api/_diag/memory request
+ * handler; the allocation-budget snapshot is process-local state.
+ */
+export function estimateSupervisorHeap(c, vfs) {
+    const allocationBudget = readSupervisorAllocationBudget();
+    const preBundleSliceBytes = estimatePreBundleSliceBytes(c);
+    // The prefetch build holds a lease, so its bytes are already inside
+    // allocationBudget.current — naming it here moves it out of the
+    // unattributed remainder rather than adding to the total twice.
+    const transientAttributedBytes = vfs.inFlightWriteBytes +
+        preBundleSliceBytes +
+        c.inFlightRpcPayloadBytes +
+        c.prefetchBundleBytes;
+    const breakdown = {
+        supervisorBaselineBytes: SUPERVISOR_BASELINE_BYTES,
+        vfsLruBytes: vfs.cacheHotBytes,
+        vfsInFlightBytes: vfs.inFlightWriteBytes,
+        preBundleSliceBytes,
+        streamingBuffersBytes: c.inFlightRpcPayloadBytes,
+        prefetchBundleBytes: c.prefetchBundleBytes,
+        prefetchCacheBytes: c.prefetchCacheBytes,
+        unattributedReservationBytes: Math.max(0, allocationBudget.current - transientAttributedBytes),
+    };
+    const estimatedBytes = breakdown.supervisorBaselineBytes +
+        breakdown.vfsLruBytes +
+        breakdown.vfsInFlightBytes +
+        breakdown.preBundleSliceBytes +
+        breakdown.streamingBuffersBytes +
+        breakdown.prefetchBundleBytes +
+        breakdown.prefetchCacheBytes +
+        breakdown.unattributedReservationBytes;
+    const percentOfCeiling = Math.round((estimatedBytes / SUPERVISOR_HEAP_CEILING_BYTES) * 1000) / 10;
+    return {
+        estimatedBytes,
+        ceilingBytes: SUPERVISOR_HEAP_CEILING_BYTES,
+        percentOfCeiling,
+        breakdown,
+        blindSpots: HEAP_BLIND_SPOTS,
+        blindSpotCeilingBytes: HEAP_BLIND_SPOTS.some((s) => s.capBytes === null)
+            ? null
+            : HEAP_BLIND_SPOTS.reduce((sum, s) => sum + (s.capBytes ?? 0), 0),
+        allocationBudget,
+    };
+}

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

@@ -0,0 +1,93 @@
+/**
+ * Supervisor-local byte-budget back-pressure for transient allocations.
+ *
+ * A DO can share its isolate's 128 MiB platform ceiling with peer DOs, so
+ * independent "safe" allocations cannot each assume the full ceiling.
+ * Module scope gives every allocator in one supervisor isolate a single FIFO
+ * budget. Full-budget owners are exclusive; weighted owners may overlap only
+ * while their retained-byte claims fit together.
+ */
+import { type ResizableCreditLease, type WeightedCreditPoolOptions } from '../_shared/weighted-credit-pool.js';
+export interface SupervisorAllocationBudgetStats {
+    readonly capacity: number;
+    readonly current: number;
+    readonly peak: number;
+    readonly queued: number;
+}
+interface AllocationBudgetLifecycle {
+    onActive?: () => void;
+    onIdle?: () => void;
+}
+/**
+ * Reusable contract behind the supervisor singleton. A separate instance is
+ * useful in tests and keeps the invariant independent of Nimbus internals.
+ */
+export declare class SupervisorAllocationBudget {
+    readonly capacity: number;
+    private readonly lifecycle;
+    private readonly credits;
+    private active;
+    /**
+     * Leases that drive the disposable-cache lifecycle. Occupancy cannot stand
+     * in for this: a read holds credit too, and a read must not sacrifice the
+     * cache it is filling.
+     */
+    private lifecycleHolders;
+    constructor(capacity: number, lifecycle?: AllocationBudgetLifecycle, reserve?: WeightedCreditPoolOptions);
+    get stats(): SupervisorAllocationBudgetStats;
+    /**
+     * Reserve bytes and, while held, mark the budget active so observers can
+     * free heap headroom. For owners whose payload is what the headroom is for:
+     * installs, clones, pre-bundles, boot payloads, streamed writes.
+     */
+    acquire(bytes: number, signal?: AbortSignal): Promise<ResizableCreditLease>;
+    /**
+     * Reserve bytes WITHOUT driving the cache lifecycle, for owners that are
+     * filling the disposable cache rather than competing with it. Shrinking a
+     * chunk cache to serve a chunk read is circular: sequentially the budget
+     * empties between every read, so an occupancy-edged observer fires once per
+     * read and the cache is pinned at its shrunk floor for the whole workload,
+     * never warming. The byte credit is still taken — back-pressure is what
+     * stops a large read overlapping a large write.
+     */
+    acquireWithoutLifecycle(bytes: number, signal?: AbortSignal): Promise<ResizableCreditLease>;
+    private _acquire;
+}
+/**
+ * A registered observer (typically a SqliteVFS) receives shrink/restore
+ * signals when the shared budget transitions idle↔active.
+ */
+interface AllocObserver {
+    /** Called when budget occupancy transitions idle → active. */
+    onAcquire?: () => void;
+    /** Called when budget occupancy transitions active → idle. */
+    onRelease?: () => void;
+}
+/**
+ * Register an observer that fires when the shared allocation budget
+ * transitions idle → active and active → idle.
+ * Returns an unsubscribe function. Idempotent: registering the same
+ * observer twice is a no-op (Set semantics).
+ *
+ * NimbusSession uses this to shrink the disposable VFS LRU while transient
+ * payloads are admitted.
+ */
+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 for a filesystem READ. Takes the same byte credit as any
+ * other owner but does not shrink the disposable VFS cache, which reads are
+ * there to fill.
+ */
+export declare function acquireSupervisorReadAllocation(bytes: number, signal?: AbortSignal): Promise<ResizableCreditLease>;
+/**
+ * Reserve the full budget for an allocation whose retained size is not known
+ * accurately enough to overlap safely with other heavy work.
+ */
+export declare function acquireHeavyAlloc(signal?: AbortSignal): Promise<() => void>;
+export declare function readSupervisorAllocationBudget(): SupervisorAllocationBudgetStats;
+export {};
+//# sourceMappingURL=heavy-alloc-coord.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"heavy-alloc-coord.d.ts","sourceRoot":"","sources":["../../src/observability/heavy-alloc-coord.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAOH,OAAO,EAEL,KAAK,oBAAoB,EACzB,KAAK,yBAAyB,EAC/B,MAAM,oCAAoC,CAAC;AAE5C,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"}

package/dist/observability/heavy-alloc-coord.js

@@ -0,0 +1,181 @@
+/**
+ * Supervisor-local byte-budget back-pressure for transient allocations.
+ *
+ * A DO can share its isolate's 128 MiB platform ceiling with peer DOs, so
+ * independent "safe" allocations cannot each assume the full ceiling.
+ * Module scope gives every allocator in one supervisor isolate a single FIFO
+ * budget. Full-budget owners are exclusive; weighted owners may overlap only
+ * while their retained-byte claims fit together.
+ */
+import { CHUNK_SIZE, SUPERVISOR_IN_FLIGHT_ALLOCATION_BUDGET_BYTES, SUPERVISOR_READ_RESERVE_BYTES, } from '../constants.js';
+import { WeightedCreditPool, } from '../_shared/weighted-credit-pool.js';
+/**
+ * Reusable contract behind the supervisor singleton. A separate instance is
+ * useful in tests and keeps the invariant independent of Nimbus internals.
+ */
+export class SupervisorAllocationBudget {
+    capacity;
+    lifecycle;
+    credits;
+    active = false;
+    /**
+     * Leases that drive the disposable-cache lifecycle. Occupancy cannot stand
+     * in for this: a read holds credit too, and a read must not sacrifice the
+     * cache it is filling.
+     */
+    lifecycleHolders = 0;
+    constructor(capacity, lifecycle = {}, reserve = {}) {
+        this.capacity = capacity;
+        this.lifecycle = lifecycle;
+        this.credits = new WeightedCreditPool(capacity, reserve);
+    }
+    get stats() {
+        return {
+            capacity: this.capacity,
+            ...this.credits.stats,
+        };
+    }
+    /**
+     * Reserve bytes and, while held, mark the budget active so observers can
+     * free heap headroom. For owners whose payload is what the headroom is for:
+     * installs, clones, pre-bundles, boot payloads, streamed writes.
+     */
+    acquire(bytes, signal) {
+        return this._acquire(bytes, signal, true);
+    }
+    /**
+     * Reserve bytes WITHOUT driving the cache lifecycle, for owners that are
+     * filling the disposable cache rather than competing with it. Shrinking a
+     * chunk cache to serve a chunk read is circular: sequentially the budget
+     * empties between every read, so an occupancy-edged observer fires once per
+     * read and the cache is pinned at its shrunk floor for the whole workload,
+     * never warming. The byte credit is still taken — back-pressure is what
+     * stops a large read overlapping a large write.
+     */
+    acquireWithoutLifecycle(bytes, signal) {
+        return this._acquire(bytes, signal, false);
+    }
+    async _acquire(bytes, signal, drivesLifecycle) {
+        const credit = await this.credits.acquire(bytes, signal);
+        if (drivesLifecycle) {
+            this.lifecycleHolders++;
+            if (!this.active) {
+                this.active = true;
+                this.lifecycle.onActive?.();
+            }
+        }
+        let released = false;
+        return {
+            get bytes() {
+                return credit.bytes;
+            },
+            shrinkTo: (nextBytes) => {
+                credit.shrinkTo(nextBytes);
+            },
+            release: () => {
+                if (released)
+                    return;
+                released = true;
+                credit.release();
+                if (!drivesLifecycle)
+                    return;
+                this.lifecycleHolders--;
+                if (this.lifecycleHolders === 0 && this.active) {
+                    this.active = false;
+                    this.lifecycle.onIdle?.();
+                }
+            },
+        };
+    }
+}
+const coord = { observers: new Set(), active: false };
+function getCoord() {
+    return coord;
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * Register an observer that fires when the shared allocation budget
+ * transitions idle → active and active → idle.
+ * Returns an unsubscribe function. Idempotent: registering the same
+ * observer twice is a no-op (Set semantics).
+ *
+ * NimbusSession uses this to shrink the disposable VFS LRU while transient
+ * payloads are admitted.
+ */
+export function registerAllocObserver(o) {
+    const c = getCoord();
+    const isNew = !c.observers.has(o);
+    c.observers.add(o);
+    if (isNew && c.active) {
+        try {
+            o.onAcquire?.();
+        }
+        catch (error) {
+            // eslint-disable-next-line no-console
+            console.error('[heavy-alloc-coord] observer.onAcquire threw:', errorMessage(error));
+        }
+    }
+    return () => { c.observers.delete(o); };
+}
+function fireOnAcquire() {
+    const c = getCoord();
+    c.active = true;
+    for (const o of c.observers) {
+        try {
+            o.onAcquire?.();
+        }
+        catch (error) {
+            // Observer errors must NOT break the heavy-alloc protocol.
+            // Log and continue.
+            // eslint-disable-next-line no-console
+            console.error('[heavy-alloc-coord] observer.onAcquire threw:', errorMessage(error));
+        }
+    }
+}
+function fireOnRelease() {
+    const c = getCoord();
+    c.active = false;
+    for (const o of c.observers) {
+        try {
+            o.onRelease?.();
+        }
+        catch (error) {
+            // eslint-disable-next-line no-console
+            console.error('[heavy-alloc-coord] observer.onRelease threw:', errorMessage(error));
+        }
+    }
+}
+const supervisorAllocationBudget = new SupervisorAllocationBudget(SUPERVISOR_IN_FLIGHT_ALLOCATION_BUDGET_BYTES, {
+    onActive: fireOnAcquire,
+    onIdle: fireOnRelease,
+}, 
+// A chunk-sized read draws on this rather than queueing behind a
+// multi-megabyte owner for a wait unrelated to its own cost.
+{ smallRequestBytes: CHUNK_SIZE, reserve: SUPERVISOR_READ_RESERVE_BYTES });
+/**
+ * Reserve an exact number of supervisor-resident bytes.
+ */
+export function acquireSupervisorAllocation(bytes, signal) {
+    return supervisorAllocationBudget.acquire(bytes, signal);
+}
+/**
+ * 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
+ * there to fill.
+ */
+export function acquireSupervisorReadAllocation(bytes, signal) {
+    return supervisorAllocationBudget.acquireWithoutLifecycle(bytes, signal);
+}
+/**
+ * Reserve the full budget for an allocation whose retained size is not known
+ * accurately enough to overlap safely with other heavy work.
+ */
+export async function acquireHeavyAlloc(signal) {
+    const lease = await acquireSupervisorAllocation(SUPERVISOR_IN_FLIGHT_ALLOCATION_BUDGET_BYTES, signal);
+    return lease.release;
+}
+export function readSupervisorAllocationBudget() {
+    return supervisorAllocationBudget.stats;
+}

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

@@ -0,0 +1,138 @@
+/**
+ * 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", "oom", "cpu_exceeded", "clone_refused", "rpc_timeout", "subrequest_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;
+/**
+ * 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/observability/oom-classify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oom-classify.d.ts","sourceRoot":"","sources":["../../src/observability/oom-classify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AAEH,QAAA,MAAM,UAAU,6IAUN,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,CAoDrD;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;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAgBpD"}