@nimbus-sh/worker 0.1.0

package/dist/observability/oom-classify.js

@@ -0,0 +1,118 @@
+/**
+ * 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.
+ */
+/**
+ * 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 function classifyError(input) {
+    const msg = readMessage(input);
+    if (msg.length === 0)
+        return 'unknown';
+    return classifyMessage(msg);
+}
+/**
+ * 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 function classifyMessage(msg) {
+    // Use lower-case match for forgiveness; SQLITE_NOMEM is canonically
+    // upper but stderr can be either.
+    const m = msg.toLowerCase();
+    // SQLITE_NOMEM signals
+    if (m.includes('sqlite_nomem'))
+        return 'sqlite_nomem';
+    if (m.includes('out of memory'))
+        return 'sqlite_nomem';
+    if (m.includes('database or disk is full'))
+        return 'sqlite_nomem';
+    // Structured-clone refusal — a 32 MiB-cap cousin
+    if (m.includes('cannot deserialize cloned data'))
+        return 'clone_refused';
+    if (m.includes('could not be cloned'))
+        return 'clone_refused';
+    // RPC timeout (Nimbus's TimeoutError from facet-pool)
+    if (m.includes('timeouterror'))
+        return 'rpc_timeout';
+    if (/\btimed?\s*out\b/.test(m))
+        return 'rpc_timeout';
+    // Subrequest cap (Cloudflare platform)
+    if (m.includes('too many subrequests'))
+        return 'subrequest_cap';
+    // Generic DO isolate condemnation / eviction
+    if (m.includes('isolate exceeded its memory limit'))
+        return 'oom';
+    if (m.includes('memory limit') && m.includes('reset'))
+        return 'oom';
+    if (m.includes('worker exceeded memory'))
+        return 'oom';
+    if (m.includes('exceeded cpu'))
+        return 'oom';
+    // Explicit eviction (per CF research §A.1.2)
+    if (m.includes('condemned'))
+        return 'condemnation';
+    if (m.includes('hard evict'))
+        return 'hard_evict';
+    return 'unknown';
+}
+function readMessage(input) {
+    if (input == null)
+        return '';
+    if (typeof input === 'string')
+        return input;
+    if (input instanceof Error)
+        return input.message ?? '';
+    // Some thrown values are plain objects with .message
+    if (typeof input === 'object') {
+        const m = input.message;
+        if (typeof m === 'string')
+            return m;
+    }
+    try {
+        return String(input);
+    }
+    catch {
+        return '';
+    }
+}

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

@@ -0,0 +1,192 @@
+/**
+ * oom-discriminator.ts — singleton ring buffer for OOM / failure
+ * forensics + last-known-RPC-frame + last-known-facet-id +
+ * session-recovery-event ring, plus snapshot/rehydrate hooks for DO
+ * storage persistence.
+ *
+ * W5 (Lever 5 / J.1.1) — original module. Pairs with oom-classify.ts.
+ * C'.2 — added the recovery_event ring.
+ *
+ * Why singleton-per-isolate
+ * ─────────────────────────
+ * Same pattern as src/diag-counters.ts (q.v.). The supervisor bundle
+ * is the consumer; all writers (sqlite-vfs, facet-pool, facet-manager,
+ * supervisor-rpc, npm-installer, nimbus-session) live in the same
+ * isolate. globalThis-keyed storage avoids threading a handle through
+ * ~10 sites for what is essentially a process-local diagnostic.
+ *
+ * Two distinct rings
+ * ──────────────────
+ * - failures: things that failed (the original W5 ring).
+ * - recoveryEvents: lifecycle transitions of the session (C'.2). Cold
+ *   isolate boot → 'cold' → 'hydrated' → 'active' → 'drained'. Plan §3
+ *   Track B' makes the transitions explicit; this ring records each
+ *   one so probes can assert "session reached 'hydrated' from SQL with
+ *   N keys, no data loss".
+ *
+ * Bounded-size guarantees
+ * ───────────────────────
+ *   - failures ring: 50 entries (RING_SIZE).
+ *   - recoveryEvents ring: 50 entries (RECOVERY_RING_SIZE).
+ *   - per-message cap: 200 chars (truncated at insert).
+ *   - per-RPC-frame: single slot, one object.
+ *   - per-facet-id: single slot, one object.
+ *
+ * Snapshot ≤40 KB even with both rings full. Verified by
+ * audit/probes/w5/functional/ring-persistence.mjs (failures) and
+ * audit/probes/c-prime/recovery-events/ (recovery — Phase 1 C'.2).
+ */
+import type { OomCause } from './oom-classify.js';
+export interface RpcFrame {
+    method: string;
+    payloadBytes: number;
+    atMs: number;
+}
+export interface FacetId {
+    codeId: string;
+    slotIndex: number;
+    atMs: number;
+}
+export interface DiagFailure {
+    /** ms epoch */
+    at: number;
+    /** Lifecycle stage (e.g. 'install', 'resolve', 'rpc', 'facet', 'ws'). */
+    phase: string;
+    /** Discriminated cause. See oom-classify.ts. */
+    cause: OomCause;
+    /** Best-effort RSS estimate in bytes (peak observed). */
+    rssEstimateBytes: number;
+    /** process.memoryUsage().heapUsed if available; 0 in DO contexts. */
+    heapUsedBytes: number;
+    /** SqliteVFS LRU hot bytes at time of failure. */
+    lruBytes: number;
+    /** Sum of in-flight RPC payload bytes (best-effort). */
+    inFlightBytes: number;
+    /** Snapshot of the most recent RPC frame, if any. */
+    lastRpcFrame: RpcFrame | null;
+    /** Snapshot of the most recent facet dispatch, if any. */
+    lastFacetId: FacetId | null;
+    /** Optional facet exit code (when failure represents a facet termination). */
+    exitCode?: number;
+    /** Optional facet pid. */
+    pid?: number;
+    /** Free-form message; truncated to MESSAGE_CAP characters. */
+    message?: string;
+}
+/**
+ * Session lifecycle states for the C'.2 recovery_event ring.
+ *
+ * The state machine is owned by Track B' (plan §3.3). This module
+ * records transitions; it does not enforce them.
+ *
+ * State semantics:
+ * - 'cold'      : fresh DO instance, no in-memory session state yet.
+ * - 'hydrated'  : Phase R completed — SQL state read into in-memory cache.
+ * - 'active'    : Phase B+W+O completed — kernel/shell/terminal wired.
+ * - 'drained'   : webSocketError/Close fired; in-memory caches nulled,
+ *                 SQL state freshly persisted; awaiting next reconnect.
+ *
+ * Trigger labels: human-readable event that caused the transition.
+ * Examples: 'first-fetch', 'ws-upgrade', 'ws-close', 'ws-error',
+ * 'isolate-evicted', 'manual-test'.
+ */
+/** Session state union.
+ *
+ * The original four are the high-level lifecycle markers:
+ *   cold     — never inited
+ *   hydrated — re-init complete (warm path; Phase O skipped)
+ *   active   — live shell processing input
+ *   drained  — webSocketError/Close fired; SQL freshly persisted
+ *
+ * The four [B'.4] additions are the fine-grained phases of
+ * initSession itself, recorded as the function progresses:
+ *   rehydrate — Phase R: loading state from DO SQLite
+ *   build     — Phase B: constructing Kernel/Shell/registry
+ *   wire      — Phase W: attaching terminal, replaying scrollback
+ *   online    — Phase O: cold-start MOTD + starter hint (cold only;
+ *               on warm re-init this phase is skipped and the
+ *               initSession ends with 'hydrated' instead)
+ *
+ * The phase transitions are SUPPLEMENTAL to the high-level markers,
+ * not a replacement. Probes that look for the legacy `'hydrated'`
+ * marker continue to work; probes that want fine-grained debugging
+ * can grep for the phase states.
+ */
+export type SessionState = 'cold' | 'hydrated' | 'active' | 'drained' | 'rehydrate' | 'build' | 'wire' | 'online';
+export interface DiagRecoveryEvent {
+    /** ms epoch */
+    at: number;
+    /** Source state. */
+    fromState: SessionState;
+    /** Destination state. */
+    toState: SessionState;
+    /** Human-readable trigger ('ws-close', 'isolate-evicted', etc.). */
+    trigger: string;
+    /** _w9IsolateGen at the time of the event. Lets a probe detect the
+     *  difference between an in-isolate transition and a cross-isolate one
+     *  (the latter implies workerd recycled the DO). */
+    isolateGen: number;
+    /** True when the transition could not preserve state that should
+     *  have survived (e.g. SQL persist threw, snapshot was missing on
+     *  hydrate, etc.). Probes assert this stays false under non-OOM
+     *  scenarios. */
+    dataLoss: boolean;
+    /** Number of SQL keys/rows rehydrated on a hydrated transition.
+     *  Zero when the transition is one that doesn't read SQL. */
+    snapshotKeysRehydrated: number;
+    /** Optional free-form notes (200 char cap). */
+    notes?: string;
+}
+/** Append a failure to the ring. Newest first. Capped at RING_SIZE. */
+export declare function recordFailure(f: DiagFailure): void;
+/** Read a snapshot of the ring. Newest first. Caller-side mutations
+ *  do not affect the singleton. */
+export declare function getFailures(): DiagFailure[];
+/** Reset everything. Used by tests; safe in production but typically
+ *  unnecessary. */
+export declare function resetFailures(): void;
+/** Record the current RPC frame (called at every RPC entry). Bounded
+ *  to a single slot — the LATEST frame wins. */
+export declare function setLastRpcFrame(method: string, payloadBytes: number): void;
+export declare function getLastRpcFrame(): RpcFrame | null;
+/** Record the most recent facet dispatch. */
+export declare function setLastFacetId(codeId: string, slotIndex: number): void;
+export declare function getLastFacetId(): FacetId | null;
+/** Append a recovery event to the ring. Newest first. Capped at
+ *  RECOVERY_RING_SIZE. */
+export declare function recordRecoveryEvent(e: DiagRecoveryEvent): void;
+/** Read a snapshot of the recovery ring. Newest first. */
+export declare function getRecoveryEvents(): DiagRecoveryEvent[];
+/** Reset the recovery ring. Tests + manual operator use only. */
+export declare function resetRecoveryEvents(): void;
+/**
+ * Build a JSON-serializable snapshot suitable for ctx.storage.put.
+ * Bounded ≤ 40 KB even with both rings full of MESSAGE_CAP-truncated
+ * messages. Schema version embedded so a future shape change can
+ * cleanly reject old snapshots.
+ *
+ * Schema versions:
+ *   v = 1  →  {failures, lastRpcFrame, lastFacetId} (pre-C'.2)
+ *   v = 2  →  v1 + {recoveryEvents}                   (C'.2)
+ *
+ * Rehydrate accepts v=1 (treats recoveryEvents as empty) and v=2.
+ */
+export interface DiagSnapshot {
+    /** Schema version. Bump when shape changes. */
+    v: number;
+    failures: DiagFailure[];
+    recoveryEvents: DiagRecoveryEvent[];
+    lastRpcFrame: RpcFrame | null;
+    lastFacetId: FacetId | null;
+}
+export declare function snapshotForStorage(): DiagSnapshot;
+/**
+ * Restore from a snapshot. Garbage / null / wrong-shape input is
+ * silently ignored. Does NOT throw — constructor-time rehydration must
+ * never block DO startup.
+ *
+ * Accepts v=1 (pre-C'.2, no recoveryEvents field) and v=2. v=1
+ * snapshots rehydrate failures only; recoveryEvents starts empty.
+ */
+export declare function rehydrateFromStorage(blob: unknown): void;
+//# sourceMappingURL=oom-discriminator.d.ts.map

package/dist/observability/oom-discriminator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oom-discriminator.d.ts","sourceRoot":"","sources":["../../src/observability/oom-discriminator.ts"],"names":[],"mappings":"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"}

package/dist/observability/oom-discriminator.js

@@ -0,0 +1,233 @@
+/**
+ * oom-discriminator.ts — singleton ring buffer for OOM / failure
+ * forensics + last-known-RPC-frame + last-known-facet-id +
+ * session-recovery-event ring, plus snapshot/rehydrate hooks for DO
+ * storage persistence.
+ *
+ * W5 (Lever 5 / J.1.1) — original module. Pairs with oom-classify.ts.
+ * C'.2 — added the recovery_event ring.
+ *
+ * Why singleton-per-isolate
+ * ─────────────────────────
+ * Same pattern as src/diag-counters.ts (q.v.). The supervisor bundle
+ * is the consumer; all writers (sqlite-vfs, facet-pool, facet-manager,
+ * supervisor-rpc, npm-installer, nimbus-session) live in the same
+ * isolate. globalThis-keyed storage avoids threading a handle through
+ * ~10 sites for what is essentially a process-local diagnostic.
+ *
+ * Two distinct rings
+ * ──────────────────
+ * - failures: things that failed (the original W5 ring).
+ * - recoveryEvents: lifecycle transitions of the session (C'.2). Cold
+ *   isolate boot → 'cold' → 'hydrated' → 'active' → 'drained'. Plan §3
+ *   Track B' makes the transitions explicit; this ring records each
+ *   one so probes can assert "session reached 'hydrated' from SQL with
+ *   N keys, no data loss".
+ *
+ * Bounded-size guarantees
+ * ───────────────────────
+ *   - failures ring: 50 entries (RING_SIZE).
+ *   - recoveryEvents ring: 50 entries (RECOVERY_RING_SIZE).
+ *   - per-message cap: 200 chars (truncated at insert).
+ *   - per-RPC-frame: single slot, one object.
+ *   - per-facet-id: single slot, one object.
+ *
+ * Snapshot ≤40 KB even with both rings full. Verified by
+ * audit/probes/w5/functional/ring-persistence.mjs (failures) and
+ * audit/probes/c-prime/recovery-events/ (recovery — Phase 1 C'.2).
+ */
+const KEY = '__NIMBUS_W5_OOM_DISC__';
+const RING_SIZE = 50;
+const RECOVERY_RING_SIZE = 50;
+const MESSAGE_CAP = 200;
+function getState() {
+    const g = globalThis;
+    if (!g[KEY]) {
+        g[KEY] = {
+            failures: [],
+            recoveryEvents: [],
+            lastRpcFrame: null,
+            lastFacetId: null,
+        };
+    }
+    // Defensive: older snapshots predating C'.2 have no recoveryEvents
+    // field. The rehydrate path adds the field on read; this guard is a
+    // belt-and-braces second line so any legacy state object on
+    // globalThis (e.g. from an in-process restart that beat the new
+    // module load) doesn't make the ring methods crash.
+    const s = g[KEY];
+    if (!Array.isArray(s.recoveryEvents))
+        s.recoveryEvents = [];
+    return s;
+}
+/** Append a failure to the ring. Newest first. Capped at RING_SIZE. */
+export function recordFailure(f) {
+    const s = getState();
+    // Defensive copy + message cap.
+    const entry = {
+        at: Number(f.at) || Date.now(),
+        phase: String(f.phase ?? 'unknown'),
+        cause: f.cause ?? 'unknown',
+        rssEstimateBytes: Number(f.rssEstimateBytes) || 0,
+        heapUsedBytes: Number(f.heapUsedBytes) || 0,
+        lruBytes: Number(f.lruBytes) || 0,
+        inFlightBytes: Number(f.inFlightBytes) || 0,
+        lastRpcFrame: f.lastRpcFrame ?? s.lastRpcFrame,
+        lastFacetId: f.lastFacetId ?? s.lastFacetId,
+    };
+    if (typeof f.exitCode === 'number')
+        entry.exitCode = f.exitCode;
+    if (typeof f.pid === 'number')
+        entry.pid = f.pid;
+    if (f.message) {
+        const m = String(f.message);
+        entry.message = m.length > MESSAGE_CAP ? m.slice(0, MESSAGE_CAP) : m;
+    }
+    s.failures.unshift(entry);
+    if (s.failures.length > RING_SIZE)
+        s.failures.length = RING_SIZE;
+}
+/** Read a snapshot of the ring. Newest first. Caller-side mutations
+ *  do not affect the singleton. */
+export function getFailures() {
+    return getState().failures.slice(0);
+}
+/** Reset everything. Used by tests; safe in production but typically
+ *  unnecessary. */
+export function resetFailures() {
+    const s = getState();
+    s.failures.length = 0;
+    s.lastRpcFrame = null;
+    s.lastFacetId = null;
+}
+/** Record the current RPC frame (called at every RPC entry). Bounded
+ *  to a single slot — the LATEST frame wins. */
+export function setLastRpcFrame(method, payloadBytes) {
+    const s = getState();
+    s.lastRpcFrame = {
+        method: String(method),
+        payloadBytes: Number(payloadBytes) || 0,
+        atMs: Date.now(),
+    };
+}
+export function getLastRpcFrame() {
+    return getState().lastRpcFrame;
+}
+/** Record the most recent facet dispatch. */
+export function setLastFacetId(codeId, slotIndex) {
+    const s = getState();
+    s.lastFacetId = {
+        codeId: String(codeId),
+        slotIndex: Number(slotIndex) || 0,
+        atMs: Date.now(),
+    };
+}
+export function getLastFacetId() {
+    return getState().lastFacetId;
+}
+// ── C'.2 recovery_event ring ────────────────────────────────────────────
+//
+// Track B' transitions call recordRecoveryEvent() at every state change.
+// The ring is bounded at RECOVERY_RING_SIZE; the diag endpoint reads via
+// getRecoveryEvents() (newest first). Probes use this ring to assert
+// that recoveries are actually transparent — a green run shows entries
+// for every reconnection but every entry has dataLoss === false.
+/** Append a recovery event to the ring. Newest first. Capped at
+ *  RECOVERY_RING_SIZE. */
+export function recordRecoveryEvent(e) {
+    const s = getState();
+    // Defensive copy + notes cap. We intentionally do NOT validate the
+    // state-machine direction here (e.g. that 'drained' only follows
+    // 'active') — the state machine lives in Track B'; this ring is a
+    // recorder, not an enforcer. If a probe sees an impossible
+    // transition, that's a real bug in the state machine and the
+    // probe must fail.
+    const entry = {
+        at: Number(e.at) || Date.now(),
+        fromState: e.fromState,
+        toState: e.toState,
+        trigger: String(e.trigger ?? 'unknown'),
+        isolateGen: Number(e.isolateGen) || 0,
+        dataLoss: !!e.dataLoss,
+        snapshotKeysRehydrated: Number(e.snapshotKeysRehydrated) || 0,
+    };
+    if (e.notes) {
+        const n = String(e.notes);
+        entry.notes = n.length > MESSAGE_CAP ? n.slice(0, MESSAGE_CAP) : n;
+    }
+    s.recoveryEvents.unshift(entry);
+    if (s.recoveryEvents.length > RECOVERY_RING_SIZE) {
+        s.recoveryEvents.length = RECOVERY_RING_SIZE;
+    }
+}
+/** Read a snapshot of the recovery ring. Newest first. */
+export function getRecoveryEvents() {
+    return getState().recoveryEvents.slice(0);
+}
+/** Reset the recovery ring. Tests + manual operator use only. */
+export function resetRecoveryEvents() {
+    getState().recoveryEvents.length = 0;
+}
+export function snapshotForStorage() {
+    const s = getState();
+    return {
+        v: 2,
+        failures: s.failures.slice(0),
+        recoveryEvents: s.recoveryEvents.slice(0),
+        lastRpcFrame: s.lastRpcFrame,
+        lastFacetId: s.lastFacetId,
+    };
+}
+/**
+ * Restore from a snapshot. Garbage / null / wrong-shape input is
+ * silently ignored. Does NOT throw — constructor-time rehydration must
+ * never block DO startup.
+ *
+ * Accepts v=1 (pre-C'.2, no recoveryEvents field) and v=2. v=1
+ * snapshots rehydrate failures only; recoveryEvents starts empty.
+ */
+export function rehydrateFromStorage(blob) {
+    if (!blob || typeof blob !== 'object')
+        return;
+    const b = blob;
+    if (b.v !== 1 && b.v !== 2)
+        return;
+    if (!Array.isArray(b.failures))
+        return;
+    const s = getState();
+    s.failures.length = 0;
+    for (const f of b.failures) {
+        if (!f || typeof f !== 'object')
+            continue;
+        const entry = f;
+        if (typeof entry.at !== 'number' || typeof entry.phase !== 'string')
+            continue;
+        s.failures.push(entry);
+        if (s.failures.length >= RING_SIZE)
+            break;
+    }
+    // v >= 2: recoveryEvents (skipped for v=1 by the shape-check below).
+    s.recoveryEvents.length = 0;
+    if (b.v === 2 && Array.isArray(b.recoveryEvents)) {
+        for (const e of b.recoveryEvents) {
+            if (!e || typeof e !== 'object')
+                continue;
+            const entry = e;
+            if (typeof entry.at !== 'number'
+                || typeof entry.fromState !== 'string'
+                || typeof entry.toState !== 'string')
+                continue;
+            s.recoveryEvents.push(entry);
+            if (s.recoveryEvents.length >= RECOVERY_RING_SIZE)
+                break;
+        }
+    }
+    if (b.lastRpcFrame && typeof b.lastRpcFrame === 'object'
+        && typeof b.lastRpcFrame.method === 'string') {
+        s.lastRpcFrame = b.lastRpcFrame;
+    }
+    if (b.lastFacetId && typeof b.lastFacetId === 'object'
+        && typeof b.lastFacetId.codeId === 'string') {
+        s.lastFacetId = b.lastFacetId;
+    }
+}

package/dist/real-vite-bundle.generated.d.ts

@@ -0,0 +1,46 @@
+/**
+ * real-vite-bundle.generated.ts — AUTO-GENERATED by scripts/bundle-real-vite.mjs
+ * DO NOT EDIT.
+ *
+ * Bundled Vite 6.4.2 with native-binding stubs (rolldown,
+ * lightningcss, etc.). Consumed by src/cirrus-real.ts at facet spawn time.
+ *
+ * [sdk-phase-1] The large strings (REAL_VITE_BUNDLE, ROLLUP_WASM_BASE64)
+ * now ship via the ASSETS binding rather than inline. Use the async
+ * getters below. Constants + browser-runtime mjs files remain inline
+ * since they're small enough to not warrant a network round-trip.
+ */
+import { type AssetsFetcher } from './runtime/assets-loader.js';
+export declare const REAL_VITE_VERSION = "6.4.2";
+/** Asset path for the bundled Vite source. Use {@link getRealViteBundle}. */
+export declare const REAL_VITE_BUNDLE_PATH = "/_assets/real-vite-bundle.js";
+/** Asset path for the rollup wasm bytes. Use {@link getRollupWasmBase64}. */
+export declare const ROLLUP_WASM_PATH = "/_assets/rollup.wasm";
+/**
+ * Fetch the bundled Vite JS from the ASSETS binding. Cached per-isolate.
+ *
+ * @param env Object exposing the `ASSETS` binding (Fetcher).
+ * @returns The Vite bundle as a UTF-8 string.
+ * @throws {NimbusAssetLoadError} when the binding is missing or fetch fails.
+ */
+export declare function getRealViteBundle(env: {
+    ASSETS: AssetsFetcher;
+}): Promise<string>;
+/**
+ * Fetch the rollup wasm bytes + base64-encode for the synthetic-fs
+ * pre-seed. Cached per-isolate; the base64 string ends up the same on
+ * every call.
+ *
+ * @returns base64-encoded rollup wasm bytes.
+ */
+export declare function getRollupWasmBase64(env: {
+    ASSETS: AssetsFetcher;
+}): Promise<string>;
+/**
+ * Vite's browser-side HMR runtime. Served to the browser at
+ * /@vite/client and /@vite/env during dev. Unlike the server
+ * bundle, these are tiny ESM files that run in-page — keep inline.
+ */
+export declare const VITE_CLIENT_MJS: string;
+export declare const VITE_ENV_MJS: string;
+//# sourceMappingURL=real-vite-bundle.generated.d.ts.map

package/dist/real-vite-bundle.generated.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"real-vite-bundle.generated.d.ts","sourceRoot":"","sources":["../src/real-vite-bundle.generated.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAiC,KAAK,aAAa,EAAE,MAAM,4BAA4B,CAAC;AAE/F,eAAO,MAAM,iBAAiB,UAAU,CAAC;AAEzC,6EAA6E;AAC7E,eAAO,MAAM,qBAAqB,iCAAiC,CAAC;AAEpE,6EAA6E;AAC7E,eAAO,MAAM,gBAAgB,yBAAyB,CAAC;AAEvD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE;IAAE,MAAM,EAAE,aAAa,CAAA;CAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAEjF;AAED;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CAAC,GAAG,EAAE;IAAE,MAAM,EAAE,aAAa,CAAA;CAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAazF;AAED;;;;GAIG;AACH,eAAO,MAAM,eAAe,EAAE,MAAwniC,CAAC;AACvpiC,eAAO,MAAM,YAAY,EAAE,MAAgrB,CAAC"}