@nimbus-sh/core 0.1.0

package/src/observability/oom-discriminator.ts

@@ -0,0 +1,405 @@
+/**
+ * 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/observability/diag-counters.ts. 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. Module scope provides one process-local diagnostic without
+ * threading a handle through each writer.
+ *
+ * Two distinct rings
+ * ──────────────────
+ * - failures: things that failed (the original W5 ring).
+ * - recoveryEvents: lifecycle transitions of the session. Cold isolate
+ *   boot → 'cold' → 'hydrated' → 'active' → 'drained'.
+ *
+ * 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 size stays bounded even with both rings full.
+ */
+
+import { isOomCause, type OomCause } from './oom-classify.js';
+
+const RING_SIZE = 50;
+const RECOVERY_RING_SIZE = 50;
+const MESSAGE_CAP = 200;
+
+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.
+ *
+ * This module records state-machine 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 or a snapshot was missing). */
+  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;
+}
+
+interface RingState {
+  failures: DiagFailure[];
+  recoveryEvents: DiagRecoveryEvent[];
+  lastRpcFrame: RpcFrame | null;
+  lastFacetId: FacetId | null;
+}
+
+const state: RingState = {
+  failures: [],
+  recoveryEvents: [],
+  lastRpcFrame: null,
+  lastFacetId: null,
+};
+
+function getState(): RingState {
+  return state;
+}
+
+/** Append a failure to the ring. Newest first. Capped at RING_SIZE. */
+export function recordFailure(f: DiagFailure): void {
+  const s = getState();
+  // Defensive copy + message cap.
+  const entry: DiagFailure = {
+    at: Number(f.at) || Date.now(),
+    phase: String(f.phase ?? 'unknown'),
+    cause: f.cause,
+    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(): DiagFailure[] {
+  return getState().failures.slice(0);
+}
+
+/** Record the current RPC frame (called at every RPC entry). Bounded
+ *  to a single slot — the LATEST frame wins. */
+export function setLastRpcFrame(method: string, payloadBytes: number): void {
+  const s = getState();
+  s.lastRpcFrame = {
+    method: String(method),
+    payloadBytes: Number(payloadBytes) || 0,
+    atMs: Date.now(),
+  };
+}
+
+export function getLastRpcFrame(): RpcFrame | null {
+  return getState().lastRpcFrame;
+}
+
+/** Record the most recent facet dispatch. */
+export function setLastFacetId(codeId: string, slotIndex: number): void {
+  const s = getState();
+  s.lastFacetId = {
+    codeId: String(codeId),
+    slotIndex: Number(slotIndex) || 0,
+    atMs: Date.now(),
+  };
+}
+
+export function getLastFacetId(): FacetId | null {
+  return getState().lastFacetId;
+}
+
+// ── C'.2 recovery_event ring ────────────────────────────────────────────
+//
+// The ring is bounded at RECOVERY_RING_SIZE; the diag endpoint reads via
+// getRecoveryEvents() (newest first).
+
+/** Append a recovery event to the ring. Newest first. Capped at
+ *  RECOVERY_RING_SIZE. */
+export function recordRecoveryEvent(e: DiagRecoveryEvent): void {
+  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 elsewhere; 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: DiagRecoveryEvent = {
+    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(): DiagRecoveryEvent[] {
+  return getState().recoveryEvents.slice(0);
+}
+
+/** Reset the recovery ring. Tests + manual operator use only. */
+export function resetRecoveryEvents(): void {
+  getState().recoveryEvents.length = 0;
+}
+
+/**
+ * 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 version 2 includes both failure and recovery-event rings.
+ */
+export interface DiagSnapshot {
+  /** Schema version. Bump when shape changes. */
+  v: 2;
+  failures: DiagFailure[];
+  recoveryEvents: DiagRecoveryEvent[];
+  lastRpcFrame: RpcFrame | null;
+  lastFacetId: FacetId | null;
+}
+
+export function snapshotForStorage(): DiagSnapshot {
+  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.
+ *
+ * Only the current v2 schema is accepted.
+ */
+export function rehydrateFromStorage(blob: unknown): void {
+  if (!isRecord(blob) || blob.v !== 2) return;
+  const b = blob;
+  if (!Array.isArray(b.failures)) return;
+
+  const s = getState();
+  s.failures.length = 0;
+  for (const f of b.failures) {
+    const entry = parseFailure(f);
+    if (!entry) continue;
+    s.failures.push(entry);
+    if (s.failures.length >= RING_SIZE) break;
+  }
+  s.recoveryEvents.length = 0;
+  if (Array.isArray(b.recoveryEvents)) {
+    for (const e of b.recoveryEvents) {
+      const entry = parseRecoveryEvent(e);
+      if (!entry) continue;
+      s.recoveryEvents.push(entry);
+      if (s.recoveryEvents.length >= RECOVERY_RING_SIZE) break;
+    }
+  }
+  const lastRpcFrame = parseRpcFrame(b.lastRpcFrame);
+  if (lastRpcFrame) s.lastRpcFrame = lastRpcFrame;
+  const lastFacetId = parseFacetId(b.lastFacetId);
+  if (lastFacetId) s.lastFacetId = lastFacetId;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+function parseRpcFrame(value: unknown): RpcFrame | null {
+  if (!isRecord(value)
+      || typeof value.method !== 'string'
+      || typeof value.payloadBytes !== 'number'
+      || typeof value.atMs !== 'number') return null;
+  return { method: value.method, payloadBytes: value.payloadBytes, atMs: value.atMs };
+}
+
+function parseFacetId(value: unknown): FacetId | null {
+  if (!isRecord(value)
+      || typeof value.codeId !== 'string'
+      || typeof value.slotIndex !== 'number'
+      || typeof value.atMs !== 'number') return null;
+  return { codeId: value.codeId, slotIndex: value.slotIndex, atMs: value.atMs };
+}
+
+function parseFailure(value: unknown): DiagFailure | null {
+  if (!isRecord(value)
+      || typeof value.at !== 'number'
+      || typeof value.phase !== 'string'
+      || !isOomCause(value.cause)
+      || typeof value.rssEstimateBytes !== 'number'
+      || typeof value.heapUsedBytes !== 'number'
+      || typeof value.lruBytes !== 'number'
+      || typeof value.inFlightBytes !== 'number') return null;
+  const entry: DiagFailure = {
+    at: value.at,
+    phase: value.phase,
+    cause: value.cause,
+    rssEstimateBytes: value.rssEstimateBytes,
+    heapUsedBytes: value.heapUsedBytes,
+    lruBytes: value.lruBytes,
+    inFlightBytes: value.inFlightBytes,
+    lastRpcFrame: parseRpcFrame(value.lastRpcFrame),
+    lastFacetId: parseFacetId(value.lastFacetId),
+  };
+  if (typeof value.exitCode === 'number') entry.exitCode = value.exitCode;
+  if (typeof value.pid === 'number') entry.pid = value.pid;
+  if (typeof value.message === 'string') entry.message = value.message.slice(0, MESSAGE_CAP);
+  return entry;
+}
+
+const SESSION_STATES: readonly SessionState[] = [
+  'cold', 'hydrated', 'active', 'drained',
+  'rehydrate', 'build', 'wire', 'online',
+];
+
+function isSessionState(value: unknown): value is SessionState {
+  return SESSION_STATES.some((state) => state === value);
+}
+
+function parseRecoveryEvent(value: unknown): DiagRecoveryEvent | null {
+  if (!isRecord(value)
+      || typeof value.at !== 'number'
+      || !isSessionState(value.fromState)
+      || !isSessionState(value.toState)
+      || typeof value.trigger !== 'string'
+      || typeof value.isolateGen !== 'number'
+      || typeof value.dataLoss !== 'boolean'
+      || typeof value.snapshotKeysRehydrated !== 'number') return null;
+  const entry: DiagRecoveryEvent = {
+    at: value.at,
+    fromState: value.fromState,
+    toState: value.toState,
+    trigger: value.trigger,
+    isolateGen: value.isolateGen,
+    dataLoss: value.dataLoss,
+    snapshotKeysRehydrated: value.snapshotKeysRehydrated,
+  };
+  if (typeof value.notes === 'string') entry.notes = value.notes.slice(0, MESSAGE_CAP);
+  return entry;
+}

package/src/runtime/assets-loader.ts

@@ -0,0 +1,189 @@
+/**
+ * runtime/assets-loader.ts — Lazy fetch of large static blobs from the
+ * ASSETS binding.
+ *
+ * Background: the Worker bundle ships ~9.8 MB of generated TypeScript
+ * blobs (cirrus-npm-cjs, cirrus-plugin-react, real-vite-bundle, ...).
+ * Inlining them at module-load doubles cold-start parse time and
+ * inflates deploy uploads. The ASSETS binding lets us serve them as
+ * static files (cached at the edge), fetched on first use, kept in a
+ * per-isolate cache for subsequent calls.
+ *
+ * Same pattern as `esbuild-wasm-bytes.ts` (proven in production —
+ * see esbuild-wasm-bundle.generated.ts header for history). We
+ * generalize it here so future asset promotions are one-line.
+ *
+ * @example a bundle script writes the big string to
+ * `public/_assets/cirrus-plugin-react.bundle.js` and emits a thin
+ * `.generated.ts` that re-exports {@link loadAssetText} bound to that
+ * path:
+ *
+ * ```ts
+ * // src/cirrus-plugin-react.generated.ts (post-promotion)
+ * import { loadAssetText } from './runtime/assets-loader.js';
+ * export const CIRRUS_PLUGIN_REACT_VERSION = "4.3.4";
+ * export const CIRRUS_PLUGIN_REACT_BUNDLE_PATH = '/_assets/cirrus-plugin-react.bundle.js';
+ * export async function getCirrusPluginReactBundle(env: { ASSETS: Fetcher }): Promise<string> {
+ *   return loadAssetText(env.ASSETS, CIRRUS_PLUGIN_REACT_BUNDLE_PATH);
+ * }
+ * ```
+ *
+ * Cache discipline: keyed by `${path}` (no env or origin in the key)
+ * because ASSETS is content-addressed at the deploy level — a redeploy
+ * generates new asset bundles and the new isolate sees no stale cache.
+ * Within a single isolate's lifetime, the same path always returns the
+ * same content.
+ */
+
+import { disposeRpcResource } from '../_shared/rpc-dispose.js';
+
+/**
+ * Per-isolate cache. Keys are asset paths (e.g. `/_assets/foo.js`).
+ * Values are settled promises so concurrent callers share the same
+ * fetch.
+ */
+const __assetTextCache = new Map<string, Promise<string>>();
+const __assetBytesCache = new Map<string, Promise<Uint8Array>>();
+
+/**
+ * Asset fetch error. Thrown when ASSETS binding is missing or returns
+ * a non-200.
+ */
+export class NimbusAssetLoadError extends Error {
+  readonly code: 'E_ASSETS_BINDING_MISSING' | 'E_ASSET_NOT_FOUND' | 'E_ASSET_FETCH_FAILED';
+  readonly status?: number;
+  readonly path: string;
+  constructor(
+    message: string,
+    code: NimbusAssetLoadError['code'],
+    path: string,
+    status?: number,
+  ) {
+    super(message);
+    this.name = 'NimbusAssetLoadError';
+    this.code = code;
+    this.path = path;
+    this.status = status;
+  }
+}
+
+/** Minimal fetcher shape so callers don't need to import a Cloudflare type. */
+export interface AssetsFetcher {
+  fetch(input: RequestInfo, init?: RequestInit): Promise<Response>;
+}
+
+/**
+ * Load an asset's bytes by path. Subsequent calls in the same isolate
+ * return from cache.
+ *
+ * @param assets `env.ASSETS` binding.
+ * @param path Asset path (e.g. `/_assets/foo.bin`). Leading `/`
+ *             required.
+ * @throws {NimbusAssetLoadError} on binding missing or non-2xx.
+ */
+export function loadAssetBytes(
+  assets: AssetsFetcher | undefined,
+  path: string,
+): Promise<Uint8Array> {
+  if (!assets || typeof assets.fetch !== 'function') {
+    return Promise.reject(
+      new NimbusAssetLoadError(
+        `ASSETS binding missing — cannot load ${path}. Did you forget the assets.binding=ASSETS in wrangler.jsonc?`,
+        'E_ASSETS_BINDING_MISSING',
+        path,
+      ),
+    );
+  }
+  const cached = __assetBytesCache.get(path);
+  if (cached) return cached;
+  const promise = (async () => {
+    // ASSETS.fetch requires an absolute URL, but the origin is ignored
+    // — it just routes by pathname. Use a stable sentinel origin.
+    const url = `https://assets.invalid${path}`;
+    const r = await assets.fetch(url);
+    try {
+      if (r.status === 404) {
+        throw new NimbusAssetLoadError(
+          `Asset not found: ${path}`,
+          'E_ASSET_NOT_FOUND',
+          path,
+          404,
+        );
+      }
+      if (!r.ok) {
+        throw new NimbusAssetLoadError(
+          `Asset fetch failed: ${path} → ${r.status}`,
+          'E_ASSET_FETCH_FAILED',
+          path,
+          r.status,
+        );
+      }
+      const buf = await r.arrayBuffer();
+      return new Uint8Array(buf);
+    } finally {
+      disposeRpcResource(r);
+    }
+  })();
+  __assetBytesCache.set(path, promise);
+  // Evict on failure so subsequent calls retry.
+  promise.catch(() => __assetBytesCache.delete(path));
+  return promise;
+}
+
+/**
+ * Load an asset as a UTF-8 string. Same caching discipline as
+ * {@link loadAssetBytes}.
+ */
+export function loadAssetText(
+  assets: AssetsFetcher | undefined,
+  path: string,
+): Promise<string> {
+  if (!assets || typeof assets.fetch !== 'function') {
+    return Promise.reject(
+      new NimbusAssetLoadError(
+        `ASSETS binding missing — cannot load ${path}. Did you forget the assets.binding=ASSETS in wrangler.jsonc?`,
+        'E_ASSETS_BINDING_MISSING',
+        path,
+      ),
+    );
+  }
+  const cached = __assetTextCache.get(path);
+  if (cached) return cached;
+  const promise = (async () => {
+    const url = `https://assets.invalid${path}`;
+    const r = await assets.fetch(url);
+    try {
+      if (r.status === 404) {
+        throw new NimbusAssetLoadError(
+          `Asset not found: ${path}`,
+          'E_ASSET_NOT_FOUND',
+          path,
+          404,
+        );
+      }
+      if (!r.ok) {
+        throw new NimbusAssetLoadError(
+          `Asset fetch failed: ${path} → ${r.status}`,
+          'E_ASSET_FETCH_FAILED',
+          path,
+          r.status,
+        );
+      }
+      return await r.text();
+    } finally {
+      disposeRpcResource(r);
+    }
+  })();
+  __assetTextCache.set(path, promise);
+  promise.catch(() => __assetTextCache.delete(path));
+  return promise;
+}
+
+/**
+ * Test-only: drop the per-isolate cache. Real isolates never call this;
+ * the cache exists for the isolate's lifetime.
+ */
+export function _resetAssetsCacheForTests(): void {
+  __assetTextCache.clear();
+  __assetBytesCache.clear();
+}

package/src/runtime/barrel-detect.ts

@@ -0,0 +1,69 @@
+/**
+ * barrel-detect.ts — heuristic for "barrel" packages whose source tree
+ * is too large for esbuild's facet to bundle without OOM.
+ *
+ * Barrel packages ship one .js per icon/component (e.g. lucide-react
+ * with 1500 icons → 4000+ files). esbuild's bundler ingests the whole
+ * tree into a single ESM module, which routinely OOMs the 128 MiB
+ * facet isolate during JS heap allocation.
+ *
+ * Both the install-time pre-bundle path (npm-installer.prebundleUsedModules)
+ * and the on-demand path (vite-dev-server.serveModule) use this to
+ * route the package through `barrel-synthesizer.ts`: scan the user's
+ * source for static named imports, generate a tiny synthetic entry
+ * (`export { Home, FileText } from 'pkg'`), and bundle THAT through
+ * the standard facet path. esbuild's tree-shaking + the package's
+ * sideEffects:false produces a small per-app bundle without ever
+ * reaching for a third-party CDN (100% edge contract).
+ *
+ * Threshold rationale (1500 files):
+ *   lucide-react@0.460:    4069 files (synthesizes)
+ *   framer-motion@11.11:    ~250 files (bundles whole)
+ *   react-router-dom@6.26:  ~80  files (bundles whole)
+ *   react-dom@18.3:         ~150 files (bundles whole)
+ *
+ * The cap (5000) prevents pathological deep walks; we only need to
+ * know "clearly a barrel" vs. not.
+ */
+
+import type { CredentialedVfs } from '../vfs/sqlite-vfs.js';
+
+/** A package with more than this many files is treated as a barrel. */
+export const BARREL_PKG_FILE_THRESHOLD = 1500;
+
+/**
+ * Recursively count files under `pkgDir`, excluding nested node_modules
+ * (those are walked separately by the slice walker as transitive deps).
+ *
+ * Stops counting once we exceed `cap` to avoid pathological walks. Cost:
+ * VFS readdir is sync + in-memory inode lookup. For lucide-react
+ * (4069 files), measured at <2 ms in dev.
+ */
+export function countPackageFiles(vfs: CredentialedVfs, pkgDir: string, cap = 5000): number {
+  if (!vfs.exists(pkgDir) || !vfs.isDirectory(pkgDir)) return 0;
+  let count = 0;
+  const stack = [pkgDir];
+  while (stack.length > 0 && count <= cap) {
+    const dir = stack.pop()!;
+    let entries: { name: string; type: string }[];
+    try { entries = vfs.readdir(dir); } catch { continue; }
+    for (const e of entries) {
+      if (e.name === 'node_modules') continue;
+      const child = dir + '/' + e.name;
+      if (e.type === 'directory') stack.push(child);
+      else count++;
+    }
+  }
+  return count;
+}
+
+/**
+ * Convenience: derive top-level package name from a bare specifier
+ * (e.g. "lucide-react/icons/Cloud" → "lucide-react", "@radix-ui/react"
+ * → "@radix-ui/react"). Used by callers building the pkgDir path.
+ */
+export function packageNameFromSpecifier(specifier: string): string {
+  return specifier.startsWith('@')
+    ? specifier.split('/').slice(0, 2).join('/')
+    : specifier.split('/')[0];
+}