@nimbus-sh/platform 0.1.0

package/dist/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 './limits.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/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 './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/heavy-alloc-coord.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"heavy-alloc-coord.d.ts","sourceRoot":"","sources":["../src/heavy-alloc-coord.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAOH,OAAO,EAEL,KAAK,oBAAoB,EACzB,KAAK,yBAAyB,EAC/B,MAAM,2BAA2B,CAAC;AAEnC,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/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 './limits.js';
+import { WeightedCreditPool, } from './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/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @nimbus-sh/platform — the measured Cloudflare platform truths Nimbus is
+ * built on: limits tables, the error taxonomy for isolates that die without
+ * throwing, the supervisor budget machinery, and wire-format primitives.
+ *
+ * A zero-dependency leaf: core, fabric, and the worker all consume this
+ * package; nothing here imports from any of them.
+ */
+export * from './diag-counters.js';
+export * from './heap-estimate.js';
+export * from './heavy-alloc-coord.js';
+export * from './install-phase.js';
+export * from './limits.js';
+export * from './oom-classify.js';
+export * from './oom-discriminator.js';
+export * from './rpc-dispose.js';
+export * from './w7-frame.js';
+export * from './weighted-credit-pool.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,cAAc,oBAAoB,CAAC;AACnC,cAAc,oBAAoB,CAAC;AACnC,cAAc,wBAAwB,CAAC;AACvC,cAAc,oBAAoB,CAAC;AACnC,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,wBAAwB,CAAC;AACvC,cAAc,kBAAkB,CAAC;AACjC,cAAc,eAAe,CAAC;AAC9B,cAAc,2BAA2B,CAAC"}

package/dist/index.js

@@ -0,0 +1,18 @@
+/**
+ * @nimbus-sh/platform — the measured Cloudflare platform truths Nimbus is
+ * built on: limits tables, the error taxonomy for isolates that die without
+ * throwing, the supervisor budget machinery, and wire-format primitives.
+ *
+ * A zero-dependency leaf: core, fabric, and the worker all consume this
+ * package; nothing here imports from any of them.
+ */
+export * from './diag-counters.js';
+export * from './heap-estimate.js';
+export * from './heavy-alloc-coord.js';
+export * from './install-phase.js';
+export * from './limits.js';
+export * from './oom-classify.js';
+export * from './oom-discriminator.js';
+export * from './rpc-dispose.js';
+export * from './w7-frame.js';
+export * from './weighted-credit-pool.js';

package/dist/install-phase.d.ts

@@ -0,0 +1,47 @@
+/**
+ * _shared/install-phase.ts — single source of truth for the npm-install
+ * state-machine phase enum.
+ *
+ * History: CLN-1 (2026-05-11) — consolidated from two diverged copies.
+ *   - `npm/installer.ts:93-95` was the progress-event variant. Included
+ *     'lock-check' (a real progress event emitted while parsing
+ *     package-lock.json) but lacked 'idle'.
+ *   - `observability/diag-counters.ts:33-35` was the counter-state variant.
+ *     Included 'idle' (the resting state when no install is in flight)
+ *     but lacked 'lock-check'. The diag-counter's `setInstallPhase()`
+ *     was actually called with 'idle' (installer.ts:184,201) — passing
+ *     a value not declared in installer.ts's local type. The type check
+ *     fell through to diag-counters' type because installer.ts imports
+ *     setInstallPhase from there; the local `InstallPhase` definition
+ *     in installer.ts was only used by `InstallProgress.phase`.
+ *
+ * Going forward both consumers import from this module; any new phase
+ * value added here is automatically available everywhere.
+ *
+ * Phase semantics (chronological order for a single install run):
+ *
+ *   idle         resting state, no install in flight
+ *     ↓
+ *   lock-check   parsing existing package-lock.json (if present)
+ *     ↓
+ *   resolve      walking the dep tree, fetching packuments
+ *     ↓
+ *   hoist        hoisting peer-deps + flattening node_modules
+ *     ↓
+ *   diff         comparing target tree against current install state
+ *     ↓
+ *   fetch        downloading missing tarballs
+ *     ↓
+ *   write        extracting tarballs into the VFS
+ *     ↓
+ *   link-bins    creating bin/ symlinks
+ *     ↓
+ *   bundle       (post-install) pre-bundling for esbuild fast path
+ *     ↓
+ *   done         install complete; about to return to 'idle'
+ *
+ * The phase strings are surfaced via /api/_diag/install-pipeline and
+ * displayed in the install-progress UI; treat them as a public API.
+ */
+export type InstallPhase = 'idle' | 'lock-check' | 'resolve' | 'hoist' | 'diff' | 'fetch' | 'write' | 'link-bins' | 'bundle' | 'done';
+//# sourceMappingURL=install-phase.d.ts.map

package/dist/install-phase.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install-phase.d.ts","sourceRoot":"","sources":["../src/install-phase.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,MAAM,MAAM,YAAY,GACpB,MAAM,GACN,YAAY,GACZ,SAAS,GACT,OAAO,GACP,MAAM,GACN,OAAO,GACP,OAAO,GACP,WAAW,GACX,QAAQ,GACR,MAAM,CAAC"}

package/dist/install-phase.js

@@ -0,0 +1 @@
+export {};

package/dist/limits.d.ts

@@ -0,0 +1,83 @@
+/**
+ * limits.ts — the measured Cloudflare platform limits Nimbus is built
+ * against.
+ *
+ * Every constant here is a fact about the platform — a hard ceiling, or a
+ * measured envelope proven safe against one — rather than a Nimbus policy
+ * choice. Policy constants (versions, defaults, feature bounds) live in
+ * `@nimbus-sh/core/constants.js`; this table is what they are derived from.
+ */
+/**
+ * The storage/wire chunk quantum: bytes per content chunk in the SQLite
+ * VFS schema, and therefore the unit every transaction bound and streamed
+ * write frame is denominated in. SQLite's per-ROW value cap is 2 MB (key
+ * length included, measured single-value ceiling 2,199,981 B), so 64 KiB
+ * keeps a chunk row far under it while amortizing per-row overhead.
+ */
+export declare const CHUNK_SIZE = 65536;
+export declare const MAX_TX_BLOB_BYTES: number;
+export declare const MAX_TX_LOGICAL_ROWS = 256;
+export declare const MAX_TX_SQL_EXECS = 64;
+/**
+ * Storage per SQLite-backed Durable Object: 10 decimal GB documented
+ * (Workers Paid), shared by the root object, every facet beneath it, and
+ * every clone — a copy-on-write clone consumes its FULL logical bytes with
+ * no CoW credit. Probed window: 10.58e9 logical bytes fit, 11.6e9 failed —
+ * 10 GiB (10,737,418,240) falls INSIDE that window and is not a number to
+ * design to. At the wall, ordinary writes fail catchably as SQLITE_FULL
+ * ('database or disk is full') while reads and DELETEs keep working, so the
+ * recovery is to drain; a facet CLONE over the wall is an uncatchable reset
+ * that empties the destination, so clone admission is decided BEFORE the
+ * clone, with reserve.
+ */
+export declare const DO_STORAGE_LIMIT_BYTES = 10000000000;
+/**
+ * Maximum SQL statement text per exec. Documented "100 KB"; read as binary
+ * KiB because the value is SQLite's compile-time SQLITE_MAX_SQL_LENGTH
+ * rather than a billing quantity (unverified reading — reached by generated
+ * statements, a batched multi-VALUES insert being the realistic breach).
+ */
+export declare const SQLITE_MAX_STATEMENT_BYTES: number;
+/**
+ * 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 declare const SQLITE_MAX_BOUND_PARAMETERS = 100;
+/**
+ * Maximum bytes of one string, BLOB, or table ROW — the bound is per ROW,
+ * key length included, not per value. The measured single-value ceiling is
+ * 2,199,981 bytes, ABOVE this constant: budgeting each value against the
+ * row bound is conservative and correct, budgeting a row against the value
+ * ceiling is not. Writes over it fail; reads and deletes keep working.
+ */
+export declare const SQLITE_MAX_ROW_BYTES = 2000000;
+/**
+ * A `blockConcurrencyWhile()` callback still pending this long is
+ * cancelled and the Durable Object is RESET — every event queued behind
+ * the gate dies with it. Proven by probe (reset observed at 31 s against a
+ * 31 s-busy neighbour; cold activations track a busy neighbour 1:1), and
+ * partyserver runs `onStart()` inside the gate, so ordinary traffic can
+ * reach this. Anything on that path must be bounded well below this;
+ * fabric defers async reconciliation off the gate entirely (`onColdStart`).
+ */
+export declare const BLOCK_CONCURRENCY_CANCEL_MS = 30000;
+/**
+ * Bytes one hibernatable WebSocket attachment may serialize to. Verified in
+ * workerd source at the pinned version (v1.20260603.1,
+ * src/workerd/api/web-socket.h: `MAX_ATTACHMENT_SIZE = 1024 * 16`). The
+ * bound is on the SERIALIZED bytes — workerd re-serializes on every
+ * `serializeAttachment` call to check it — not on UTF-8 JSON text, so a
+ * JSON-length measurement is an approximation and only the platform's own
+ * refusal ("A WebSocket 'attachment' cannot be larger than 16384 bytes.")
+ * is the ceiling.
+ */
+export declare const WS_ATTACHMENT_LIMIT_BYTES = 16384;
+export declare const MAX_RPC_SAFE_PAYLOAD_BYTES: number;
+export declare const SUPERVISOR_HEAP_CEILING_BYTES: number;
+export declare const SUPERVISOR_IN_FLIGHT_ALLOCATION_BUDGET_BYTES: number;
+export declare const SUPERVISOR_READ_RESERVE_BYTES: number;
+export declare const MAX_GLOBAL_WRITE_STREAM_CREDIT_BYTES: number;
+export declare const PRE_BUNDLE_SLICE_CAP_BYTES: number;
+export declare const PRE_BUNDLE_CONCURRENCY = 1;
+//# sourceMappingURL=limits.d.ts.map

package/dist/limits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"limits.d.ts","sourceRoot":"","sources":["../src/limits.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AASH;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,QAAS,CAAC;AAEjC,eAAO,MAAM,iBAAiB,QAAkB,CAAC;AACjD,eAAO,MAAM,mBAAmB,MAAM,CAAC;AACvC,eAAO,MAAM,gBAAgB,KAAK,CAAC;AAInC;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,sBAAsB,cAAiB,CAAC;AAErD;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,QAAa,CAAC;AAErD;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,MAAM,CAAC;AAE/C;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,UAAY,CAAC;AAI9C;;;;;;;;GAQG;AACH,eAAO,MAAM,2BAA2B,QAAS,CAAC;AAIlD;;;;;;;;;GASG;AACH,eAAO,MAAM,yBAAyB,QAAS,CAAC;AAOhD,eAAO,MAAM,0BAA0B,QAAmB,CAAC;AA6B3D,eAAO,MAAM,6BAA6B,QAAmB,CAAC;AAO9D,eAAO,MAAM,4CAA4C,QAAmB,CAAC;AAY7E,eAAO,MAAM,6BAA6B,QAAc,CAAC;AAKzD,eAAO,MAAM,oCAAoC,QAAkB,CAAC;AAQpE,eAAO,MAAM,0BAA0B,QAA6B,CAAC;AACrE,eAAO,MAAM,sBAAsB,IAAI,CAAC"}