@nimbus-sh/worker 0.1.0

package/dist/observability/heap-estimate.d.ts

@@ -0,0 +1,166 @@
+/**
+ * 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 KNOWN supervisor heap
+ * allocation sources from runtime counters that ARE accurate
+ * (diag-counters.ts singleton + SqliteVFS.getStats()). Every byte has a
+ * named contributor; a regression in any one component is locatable.
+ *
+ * The estimator is INTENTIONALLY conservative: each component reports a
+ * peak-or-current value, and the total may overestimate (in-flight bytes
+ * are counted before they're freed; LRU bytes are the cap, not always
+ * the current footprint). Better to over-report than under-report when
+ * the alternative is the zero-everywhere status quo.
+ *
+ * Eviction-label taxonomy
+ * ───────────────────────
+ * Workerd (per docs/research/cf-internal-dossier.md §9.2 metrics.h:300)
+ * 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 type { DiagCounters } from './diag-counters.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.
+ *
+ * Source: cloudflare/ew/edgeworker metrics.c++:1778-1790 + metrics.h:300.
+ * Cross-cited in docs/research/cf-internal-dossier.md §9.2.
+ */
+export declare const WORKERD_EVICTION_LABELS: readonly ["lru", "condemned", "inactive", "dynamic_worker", "dynamic_worker_banned"];
+export type WorkerdEvictionLabel = typeof WORKERD_EVICTION_LABELS[number];
+/**
+ * Supervisor heap snapshot. Components are PEAK-OR-CURRENT bytes from
+ * runtime counters; the estimator never calls process.memoryUsage().
+ */
+export interface HeapEstimate {
+    /** Sum of all components below. Always equals breakdown sum. */
+    estimatedBytes: number;
+    /** SUPERVISOR_HEAP_CEILING_BYTES (constant — 64 MiB by design). */
+    ceilingBytes: number;
+    /** estimatedBytes / ceilingBytes × 100, one decimal place. */
+    percentOfCeiling: number;
+    /** Per-source byte attribution. */
+    breakdown: HeapBreakdown;
+}
+export interface HeapBreakdown {
+    /** Static module bundle + runtime baseline. Constant per build. */
+    supervisorBaselineBytes: number;
+    /** SqliteVFS LRU cache hot-byte count (sqlite-vfs.ts cache.hotBytes). */
+    vfsLruBytes: number;
+    /** SqliteVFS in-flight write payload bytes (peak observed). */
+    vfsInFlightBytes: number;
+    /** Resolver in-flight packument bytes (rough cap = live stubs × last
+     *  packument size). Post A'.1 the resolver runs in a facet and this
+     *  is always 0; the slot is preserved so a regression that
+     *  re-introduces supervisor-side resolution is locatable. */
+    resolverInFlightBytes: number;
+    /** Pre-bundle slice bytes resident in supervisor heap (peak across
+     *  in-flight pool slots × SLICE_CAP_BYTES). Drops to 0 once
+     *  A'.2/A'.3 stream the slice through ReadableStream-over-RPC. */
+    preBundleSliceBytes: number;
+    /** esbuild-wasm bytes resident in supervisor. Phase 2 A'.5 moved
+     *  these to env.ASSETS; the slot is 0 by construction now. */
+    esbuildResidentBytes: number;
+    /**
+     * In-flight supervisor RPC payload bytes (Phase 2 A'.2).
+     *
+     * Sum of bytes claimed by RPC handlers in src/supervisor-rpc.ts
+     * between RPC entry and exit — writeBatch / writeBatchStream /
+     * putRegistryEntries / R2 cache RPC return values. Tracked by
+     * `inFlightRpcPayloadBytes` in src/diag-counters.ts; bumped at
+     * RPC entry, debited in `finally`.
+     *
+     * At idle this is 0. Under load it should stay bounded by the
+     * largest single in-flight RPC's payload (~few MiB for writeBatch).
+     * Persistent non-zero readings here mean an RPC handler isn't
+     * decrementing on its failure path — a leak worth fixing.
+     */
+    streamingBuffersBytes: number;
+}
+/**
+ * Inputs the estimator needs from the SqliteVFS layer. Kept narrow
+ * (just the two fields we actually consume) to avoid a circular import
+ * between observability/ and the VFS module.
+ */
+export interface VfsHeapInputs {
+    /** SqliteVFS.getStats().cache.hotBytes — actual LRU memory in use. */
+    cacheHotBytes: number;
+    /** Current sum of in-flight write payloads (or 0 if none). */
+    inFlightWriteBytes: number;
+}
+/**
+ * Maximum SqliteVFS LRU footprint (architectural cap). Used as the
+ * upper bound for the LRU contribution when the SqliteVFS hasn't been
+ * instantiated yet (cacheHotBytes = 0 from the inputs).
+ *
+ * Defensive — the live cacheHotBytes is the source of truth once the
+ * VFS exists. This value is NOT used in production; the estimator
+ * receives the live count via VfsHeapInputs.
+ */
+export declare const VFS_LRU_MAX_BYTES: number;
+/**
+ * Estimate resolver in-flight bytes from diag-counters.
+ *
+ * The resolver in-supervisor path (pre-A'.1) holds packument JSON in
+ * memory while parsing. We don't have a "current in-flight bytes"
+ * counter directly, but we DO have:
+ *   - inFlightPackumentFetches (live count of awaited fetches)
+ *   - lastPackumentBytes (size of the most recent packument)
+ *
+ * Average packument size on real registries is dominated by the largest
+ * outliers (lucide-react, framer-motion at ~5 MiB each) so using
+ * lastPackumentBytes as a per-fetch upper bound is a reasonable proxy.
+ *
+ * Caller can also pass an explicit `cumulativeBytesDecoded` snapshot
+ * (resolverPath = 'in-supervisor') for a different estimation strategy
+ * — but right now the most useful signal is "is the resolver currently
+ * holding bytes in supervisor heap or has it moved to a facet?".
+ *
+ * After A'.1 lands and resolverPath becomes hard-pinned to 'in-facet',
+ * this contribution drops to 0 by construction.
+ */
+export declare function estimateResolverInFlightBytes(c: DiagCounters): number;
+/**
+ * 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 declare function estimatePreBundleSliceBytes(c: DiagCounters): number;
+/**
+ * Build a heap estimate from runtime counters + VFS inputs.
+ *
+ * Pure function — no I/O, microsecond cost. Called from the
+ * /api/_diag/memory request handler.
+ */
+export declare function estimateSupervisorHeap(c: DiagCounters, vfs: VfsHeapInputs): HeapEstimate;
+//# sourceMappingURL=heap-estimate.d.ts.map

package/dist/observability/heap-estimate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"heap-estimate.d.ts","sourceRoot":"","sources":["../../src/observability/heap-estimate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB,sFAM1B,CAAC;AAEX,MAAM,MAAM,oBAAoB,GAAG,OAAO,uBAAuB,CAAC,MAAM,CAAC,CAAC;AAE1E;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,gEAAgE;IAChE,cAAc,EAAE,MAAM,CAAC;IACvB,mEAAmE;IACnE,YAAY,EAAE,MAAM,CAAC;IACrB,8DAA8D;IAC9D,gBAAgB,EAAE,MAAM,CAAC;IACzB,mCAAmC;IACnC,SAAS,EAAE,aAAa,CAAC;CAC1B;AAED,MAAM,WAAW,aAAa;IAC5B,mEAAmE;IACnE,uBAAuB,EAAE,MAAM,CAAC;IAChC,yEAAyE;IACzE,WAAW,EAAE,MAAM,CAAC;IACpB,+DAA+D;IAC/D,gBAAgB,EAAE,MAAM,CAAC;IACzB;;;iEAG6D;IAC7D,qBAAqB,EAAE,MAAM,CAAC;IAC9B;;sEAEkE;IAClE,mBAAmB,EAAE,MAAM,CAAC;IAC5B;kEAC8D;IAC9D,oBAAoB,EAAE,MAAM,CAAC;IAC7B;;;;;;;;;;;;;OAaG;IACH,qBAAqB,EAAE,MAAM,CAAC;CAC/B;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,sEAAsE;IACtE,aAAa,EAAE,MAAM,CAAC;IACtB,8DAA8D;IAC9D,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAyCD;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,QAA+B,CAAC;AAE9D;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,6BAA6B,CAAC,CAAC,EAAE,YAAY,GAAG,MAAM,CAQrE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,2BAA2B,CAAC,CAAC,EAAE,YAAY,GAAG,MAAM,CAWnE;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,CAAC,EAAE,YAAY,EACf,GAAG,EAAE,aAAa,GACjB,YAAY,CA8Bd"}

package/dist/observability/heap-estimate.js

@@ -0,0 +1,192 @@
+/**
+ * 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 KNOWN supervisor heap
+ * allocation sources from runtime counters that ARE accurate
+ * (diag-counters.ts singleton + SqliteVFS.getStats()). Every byte has a
+ * named contributor; a regression in any one component is locatable.
+ *
+ * The estimator is INTENTIONALLY conservative: each component reports a
+ * peak-or-current value, and the total may overestimate (in-flight bytes
+ * are counted before they're freed; LRU bytes are the cap, not always
+ * the current footprint). Better to over-report than under-report when
+ * the alternative is the zero-everywhere status quo.
+ *
+ * Eviction-label taxonomy
+ * ───────────────────────
+ * Workerd (per docs/research/cf-internal-dossier.md §9.2 metrics.h:300)
+ * 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 { CHUNK_SIZE, LRU_MAX_ENTRIES, SUPERVISOR_HEAP_CEILING_BYTES } from '../constants.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.
+ *
+ * Source: cloudflare/ew/edgeworker metrics.c++:1778-1790 + metrics.h:300.
+ * Cross-cited in docs/research/cf-internal-dossier.md §9.2.
+ */
+export const WORKERD_EVICTION_LABELS = [
+    'lru',
+    'condemned',
+    'inactive',
+    'dynamic_worker',
+    'dynamic_worker_banned',
+];
+// ── 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;
+/**
+ * esbuild-wasm bytes resident in supervisor heap.
+ *
+ * Pre-A'.5: 16 MiB module-scope cache in src/esbuild-wasm-bytes.ts —
+ * the decoded ArrayBuffer was held for the lifetime of the supervisor
+ * isolate so multiple pool constructions amortised the base64 decode.
+ *
+ * Post-A'.5: 0. The bytes live in env.ASSETS; src/esbuild-wasm-bytes.ts
+ * fetches on demand and the supervisor releases its reference after
+ * the LOADER hand-off. There IS a transient ~12 MiB pulse during pool
+ * construction, but it's not resident — by the time anyone polls the
+ * estimator we're back to zero. The constant captures the resident
+ * floor; transient bytes don't show up here.
+ */
+const ESBUILD_RESIDENT_BYTES = 0;
+/**
+ * Maximum SqliteVFS LRU footprint (architectural cap). Used as the
+ * upper bound for the LRU contribution when the SqliteVFS hasn't been
+ * instantiated yet (cacheHotBytes = 0 from the inputs).
+ *
+ * Defensive — the live cacheHotBytes is the source of truth once the
+ * VFS exists. This value is NOT used in production; the estimator
+ * receives the live count via VfsHeapInputs.
+ */
+export const VFS_LRU_MAX_BYTES = LRU_MAX_ENTRIES * CHUNK_SIZE;
+/**
+ * Estimate resolver in-flight bytes from diag-counters.
+ *
+ * The resolver in-supervisor path (pre-A'.1) holds packument JSON in
+ * memory while parsing. We don't have a "current in-flight bytes"
+ * counter directly, but we DO have:
+ *   - inFlightPackumentFetches (live count of awaited fetches)
+ *   - lastPackumentBytes (size of the most recent packument)
+ *
+ * Average packument size on real registries is dominated by the largest
+ * outliers (lucide-react, framer-motion at ~5 MiB each) so using
+ * lastPackumentBytes as a per-fetch upper bound is a reasonable proxy.
+ *
+ * Caller can also pass an explicit `cumulativeBytesDecoded` snapshot
+ * (resolverPath = 'in-supervisor') for a different estimation strategy
+ * — but right now the most useful signal is "is the resolver currently
+ * holding bytes in supervisor heap or has it moved to a facet?".
+ *
+ * After A'.1 lands and resolverPath becomes hard-pinned to 'in-facet',
+ * this contribution drops to 0 by construction.
+ */
+export function estimateResolverInFlightBytes(c) {
+    if (c.resolverPath === 'in-facet')
+        return 0;
+    if (c.inFlightPackumentFetches === 0)
+        return 0;
+    // Conservative: each in-flight fetch counted at the size of the
+    // most recent packument. This OVER-estimates when the in-flight
+    // packuments are smaller than lastPackumentBytes (which they
+    // probably are — lastPackumentBytes is a worst-of-recent value).
+    return c.inFlightPackumentFetches * c.lastPackumentBytes;
+}
+/**
+ * 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. The 28 MiB constant must stay in lockstep with
+    // PRE_BUNDLE_CONCURRENCY × SLICE_CAP_BYTES in npm-installer.ts.
+    const SLICE_CAP_BYTES = 28 * 1024 * 1024;
+    const PRE_BUNDLE_CONCURRENCY = 1;
+    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) * SLICE_CAP_BYTES;
+}
+/**
+ * Build a heap estimate from runtime counters + VFS inputs.
+ *
+ * Pure function — no I/O, microsecond cost. Called from the
+ * /api/_diag/memory request handler.
+ */
+export function estimateSupervisorHeap(c, vfs) {
+    const breakdown = {
+        supervisorBaselineBytes: SUPERVISOR_BASELINE_BYTES,
+        vfsLruBytes: vfs.cacheHotBytes,
+        vfsInFlightBytes: vfs.inFlightWriteBytes,
+        resolverInFlightBytes: estimateResolverInFlightBytes(c),
+        preBundleSliceBytes: estimatePreBundleSliceBytes(c),
+        esbuildResidentBytes: ESBUILD_RESIDENT_BYTES,
+        streamingBuffersBytes: c.inFlightRpcPayloadBytes,
+    };
+    const estimatedBytes = breakdown.supervisorBaselineBytes +
+        breakdown.vfsLruBytes +
+        breakdown.vfsInFlightBytes +
+        breakdown.resolverInFlightBytes +
+        breakdown.preBundleSliceBytes +
+        breakdown.esbuildResidentBytes +
+        breakdown.streamingBuffersBytes;
+    const percentOfCeiling = Math.round((estimatedBytes / SUPERVISOR_HEAP_CEILING_BYTES) * 1000) / 10;
+    return {
+        estimatedBytes,
+        ceilingBytes: SUPERVISOR_HEAP_CEILING_BYTES,
+        percentOfCeiling,
+        breakdown,
+    };
+}

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

@@ -0,0 +1,95 @@
+/**
+ * heavy-alloc-coord.ts — supervisor-local back-pressure between the
+ * fire-and-forget pre-bundle phase and other heap-heavy supervisor work
+ * (today: `npm run dev` booting cirrus-real).
+ *
+ * Why this exists
+ * ───────────────
+ * Pre-bundle dispatches up to PRE_BUNDLE_CONCURRENCY facets in parallel.
+ * Each holds ~28 MiB slice while the facet RPC is in flight. The Mini-PRD
+ * "DO shared isolate issues" reports DO resets at <128 MiB when the
+ * isolate is shared with another DO; our 128 MiB headroom calculation
+ * is therefore aspirational. Concurrent allocations in the supervisor —
+ * notably cirrus-real's user-vite-config bundle + plugin-react +
+ * extraSyntheticFiles — can push a shared isolate over the cap mid
+ * pre-bundle, causing a reset that surfaces as the user seeing the boot
+ * banner reprint several times.
+ *
+ * Mechanism
+ * ─────────
+ * A single-bit gate. Heavy-alloc owners (cirrus-real boot today) call
+ * `acquireHeavyAlloc()` before allocating, releasing via the returned
+ * `release()` once steady-state. Pre-bundle's runSlot awaits
+ * `waitForLowAllocPressure()` between iterations — no-op when the gate
+ * is open, otherwise a short sleep loop until released.
+ *
+ * Idempotent / re-entrant: multiple acquires increment a refcount.
+ * `release()` is a one-shot (returned by acquire) so callers can't
+ * accidentally double-decrement.
+ *
+ * Why globalThis vs. dependency injection
+ * ───────────────────────────────────────
+ * Pre-bundle runs in the supervisor isolate, called from npm-installer
+ * which is constructed by NimbusSession's command handler. cirrus-real
+ * is constructed by a different command handler in the same session.
+ * Both share the supervisor's globalThis. Threading an explicit handle
+ * from the session through every command path would touch ~10 sites
+ * for a one-bit signal. globalThis-keyed singletons are already the
+ * pattern for `__NIMBUS_*` symbols in the codebase.
+ *
+ * Lifetime: the coordinator is process-local, lasts as long as the
+ * supervisor isolate. After a DO restart it's re-created — that's
+ * acceptable since pre-bundle would also re-dispatch from scratch.
+ */
+/**
+ * W5 Lever 8: a registered observer (typically a SqliteVFS) that
+ * receives shrink/restore signals when the heavy-alloc refcount
+ * transitions 0↔≥1. Kept as a duck-typed pair of callbacks so we
+ * don't pull SqliteVFS as a static import (preserves layering: this
+ * module is consumed by both the supervisor and tests, and shouldn't
+ * acquire a heavy dependency).
+ */
+interface AllocObserver {
+    /** Called when refcount transitions 0 → 1 (heavy-alloc phase entered). */
+    onAcquire?: () => void;
+    /** Called when refcount transitions ≥1 → 0 (phase exited). */
+    onRelease?: () => void;
+}
+/**
+ * W5 Lever 8 hook. Register an observer that fires when the heavy-
+ * alloc refcount transitions 0 → 1 (acquire) and ≥1 → 0 (release).
+ * Returns an unsubscribe function. Idempotent: registering the same
+ * observer twice is a no-op (Set semantics).
+ *
+ * Wire from NimbusSession constructor: register an observer whose
+ * onAcquire calls vfs.shrinkForInstall() and onRelease calls
+ * vfs.restoreAfterInstall(). This decouples SqliteVFS from
+ * heavy-alloc-coord while keeping the observer pattern simple.
+ */
+export declare function registerAllocObserver(o: AllocObserver): () => void;
+/** True if any heavy-alloc owner has the gate open. */
+export declare function isHeavyAllocActive(): boolean;
+/**
+ * Mark a heavy-alloc phase as active. Returns a one-shot release fn —
+ * call it once the phase is complete. Safe to discard the release
+ * (refcount can drift up if a caller forgets — only blocks pre-bundle,
+ * never blocks user work — but please don't).
+ */
+export declare function acquireHeavyAlloc(): () => void;
+/**
+ * Wait until the gate is open. Polls every `pollMs` (default 200 ms)
+ * up to `maxWaitMs` (default 30 s). Returns whether the gate opened
+ * within the window — callers can decide to continue regardless.
+ *
+ * Why polling vs. a Promise: heavy-alloc events (cirrus boot) happen
+ * once per session at most. The few hundred-ms granularity is fine,
+ * and a poll loop avoids carrying an event-emitter or extra Promise
+ * chain through the coordinator. Pre-bundle wall time is dominated by
+ * facet RPC; a 200 ms idle here is invisible.
+ */
+export declare function waitForLowAllocPressure(opts?: {
+    pollMs?: number;
+    maxWaitMs?: number;
+}): Promise<boolean>;
+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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAIH;;;;;;;GAOG;AACH,UAAU,aAAa;IACrB,0EAA0E;IAC1E,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;IACvB,8DAA8D;IAC9D,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;CACxB;AAoBD;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,aAAa,GAAG,MAAM,IAAI,CAIlE;AAwBD,uDAAuD;AACvD,wBAAgB,kBAAkB,IAAI,OAAO,CAE5C;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,IAAI,CAe9C;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,uBAAuB,CAAC,IAAI,CAAC,EAAE;IACnD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,OAAO,CAAC,OAAO,CAAC,CASnB"}

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

@@ -0,0 +1,149 @@
+/**
+ * heavy-alloc-coord.ts — supervisor-local back-pressure between the
+ * fire-and-forget pre-bundle phase and other heap-heavy supervisor work
+ * (today: `npm run dev` booting cirrus-real).
+ *
+ * Why this exists
+ * ───────────────
+ * Pre-bundle dispatches up to PRE_BUNDLE_CONCURRENCY facets in parallel.
+ * Each holds ~28 MiB slice while the facet RPC is in flight. The Mini-PRD
+ * "DO shared isolate issues" reports DO resets at <128 MiB when the
+ * isolate is shared with another DO; our 128 MiB headroom calculation
+ * is therefore aspirational. Concurrent allocations in the supervisor —
+ * notably cirrus-real's user-vite-config bundle + plugin-react +
+ * extraSyntheticFiles — can push a shared isolate over the cap mid
+ * pre-bundle, causing a reset that surfaces as the user seeing the boot
+ * banner reprint several times.
+ *
+ * Mechanism
+ * ─────────
+ * A single-bit gate. Heavy-alloc owners (cirrus-real boot today) call
+ * `acquireHeavyAlloc()` before allocating, releasing via the returned
+ * `release()` once steady-state. Pre-bundle's runSlot awaits
+ * `waitForLowAllocPressure()` between iterations — no-op when the gate
+ * is open, otherwise a short sleep loop until released.
+ *
+ * Idempotent / re-entrant: multiple acquires increment a refcount.
+ * `release()` is a one-shot (returned by acquire) so callers can't
+ * accidentally double-decrement.
+ *
+ * Why globalThis vs. dependency injection
+ * ───────────────────────────────────────
+ * Pre-bundle runs in the supervisor isolate, called from npm-installer
+ * which is constructed by NimbusSession's command handler. cirrus-real
+ * is constructed by a different command handler in the same session.
+ * Both share the supervisor's globalThis. Threading an explicit handle
+ * from the session through every command path would touch ~10 sites
+ * for a one-bit signal. globalThis-keyed singletons are already the
+ * pattern for `__NIMBUS_*` symbols in the codebase.
+ *
+ * Lifetime: the coordinator is process-local, lasts as long as the
+ * supervisor isolate. After a DO restart it's re-created — that's
+ * acceptable since pre-bundle would also re-dispatch from scratch.
+ */
+const KEY = '__NIMBUS_HEAVY_ALLOC_COORD__';
+function getCoord() {
+    const g = globalThis;
+    if (!g[KEY]) {
+        g[KEY] = { count: 0, observers: new Set() };
+    }
+    // Defensive: older entries (pre-W5) lack observers — add it.
+    const c = g[KEY];
+    if (!c.observers)
+        c.observers = new Set();
+    return c;
+}
+/**
+ * W5 Lever 8 hook. Register an observer that fires when the heavy-
+ * alloc refcount transitions 0 → 1 (acquire) and ≥1 → 0 (release).
+ * Returns an unsubscribe function. Idempotent: registering the same
+ * observer twice is a no-op (Set semantics).
+ *
+ * Wire from NimbusSession constructor: register an observer whose
+ * onAcquire calls vfs.shrinkForInstall() and onRelease calls
+ * vfs.restoreAfterInstall(). This decouples SqliteVFS from
+ * heavy-alloc-coord while keeping the observer pattern simple.
+ */
+export function registerAllocObserver(o) {
+    const c = getCoord();
+    c.observers.add(o);
+    return () => { c.observers.delete(o); };
+}
+function fireOnAcquire() {
+    const c = getCoord();
+    for (const o of c.observers) {
+        try {
+            o.onAcquire?.();
+        }
+        catch (e) {
+            // 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:', e?.message);
+        }
+    }
+}
+function fireOnRelease() {
+    const c = getCoord();
+    for (const o of c.observers) {
+        try {
+            o.onRelease?.();
+        }
+        catch (e) {
+            // eslint-disable-next-line no-console
+            console.error('[heavy-alloc-coord] observer.onRelease threw:', e?.message);
+        }
+    }
+}
+/** True if any heavy-alloc owner has the gate open. */
+export function isHeavyAllocActive() {
+    return getCoord().count > 0;
+}
+/**
+ * Mark a heavy-alloc phase as active. Returns a one-shot release fn —
+ * call it once the phase is complete. Safe to discard the release
+ * (refcount can drift up if a caller forgets — only blocks pre-bundle,
+ * never blocks user work — but please don't).
+ */
+export function acquireHeavyAlloc() {
+    const coord = getCoord();
+    const wasZero = coord.count === 0;
+    coord.count++;
+    // W5 Lever 8: fire onAcquire on the 0→1 edge so SqliteVFS can
+    // shrinkForInstall(). Subsequent nested acquires don't re-fire.
+    if (wasZero)
+        fireOnAcquire();
+    let released = false;
+    return () => {
+        if (released)
+            return;
+        released = true;
+        if (coord.count > 0)
+            coord.count--;
+        // Fire onRelease on the ≥1→0 edge so SqliteVFS restoreAfterInstall().
+        if (coord.count === 0)
+            fireOnRelease();
+    };
+}
+/**
+ * Wait until the gate is open. Polls every `pollMs` (default 200 ms)
+ * up to `maxWaitMs` (default 30 s). Returns whether the gate opened
+ * within the window — callers can decide to continue regardless.
+ *
+ * Why polling vs. a Promise: heavy-alloc events (cirrus boot) happen
+ * once per session at most. The few hundred-ms granularity is fine,
+ * and a poll loop avoids carrying an event-emitter or extra Promise
+ * chain through the coordinator. Pre-bundle wall time is dominated by
+ * facet RPC; a 200 ms idle here is invisible.
+ */
+export async function waitForLowAllocPressure(opts) {
+    const pollMs = opts?.pollMs ?? 200;
+    const maxWaitMs = opts?.maxWaitMs ?? 30_000;
+    const start = Date.now();
+    while (isHeavyAllocActive()) {
+        if (Date.now() - start > maxWaitMs)
+            return false;
+        await new Promise((r) => setTimeout(r, pollMs));
+    }
+    return true;
+}

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

@@ -0,0 +1,56 @@
+/**
+ * oom-classify.ts — discriminator for OOM-like errors at Nimbus
+ * boundaries. Tagged W5 (Lever 5 / J.1.1 in CF-INTERNAL-OPTIMIZATION-
+ * RESEARCH.md).
+ *
+ * Why this exists
+ * ───────────────
+ * Nimbus has at least four 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. Generic isolate OOM (`Durable Object's isolate exceeded its
+ *      memory limit and was reset` per ~sha/DOGE Recommendations).
+ *   3. Structured-clone refusal (`Cannot deserialize cloned data`)
+ *      between supervisor ↔ facet RPC (32 MiB cap).
+ *   4. 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.
+ *
+ * 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.
+ */
+export type OomCause = 'sqlite_nomem' | 'oom' | 'clone_refused' | 'rpc_timeout' | 'subrequest_cap' | 'condemnation' | 'hard_evict' | 'unknown';
+/**
+ * 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;
+//# 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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,MAAM,MAAM,QAAQ,GAChB,cAAc,GACd,KAAK,GACL,eAAe,GACf,aAAa,GACb,gBAAgB,GAChB,cAAc,GACd,YAAY,GACZ,SAAS,CAAC;AAEd;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,QAAQ,CAItD;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ,CAgCrD"}