@nimbus-sh/worker 0.1.0

package/README.md

@@ -0,0 +1,219 @@
+# @nimbus-sh/worker
+
+The Nimbus runtime — Durable Object + router + facet machinery — packaged
+for embedding in any Cloudflare Workers project.
+
+## Install
+
+```bash
+npm install @nimbus-sh/worker
+# or
+bun add @nimbus-sh/worker
+```
+
+## Quickstart
+
+`src/index.ts`:
+
+```ts
+import {
+  NimbusSession,
+  SupervisorRPC,
+  NimbusAssetsRPC,
+  NimbusLoaderRPC,
+  NimbusLoadedWorker,
+  NimbusLoadedEntrypoint,
+  NimbusDurableObjectNamespace,
+  NimbusDOStub,
+  CirrusHmrRPC,
+  createNimbusHandler,
+} from '@nimbus-sh/worker';
+
+// Re-export the DO + every RPC class so wrangler's `class_name` lookup +
+// `enable_ctx_exports` find them in your Worker's main-module exports.
+export {
+  NimbusSession,
+  SupervisorRPC,
+  NimbusAssetsRPC,
+  NimbusLoaderRPC,
+  NimbusLoadedWorker,
+  NimbusLoadedEntrypoint,
+  NimbusDurableObjectNamespace,
+  NimbusDOStub,
+  CirrusHmrRPC,
+};
+
+export default createNimbusHandler();
+```
+
+`wrangler.jsonc` (use `@nimbus-sh/config` to generate, or adapt
+`apps/dogfood/wrangler.jsonc`):
+
+```jsonc
+{
+  "name": "my-nimbus",
+  "main": "src/index.ts",
+  "compatibility_date": "2026-04-01",
+  "compatibility_flags": ["nodejs_compat"],
+  "placement": { "mode": "smart" },
+  "assets": {
+    "directory": "node_modules/@nimbus-sh/worker/public",
+    "binding": "ASSETS",
+    "run_worker_first": ["/s/*", "/new"]
+  },
+  "alias": {
+    "@lifo-sh/ui": "./node_modules/@nimbus-sh/worker/dist/stubs/lifo-ui.js",
+    "clean-git-ref": "clean-git-ref/lib/index.js",
+    "is-git-ref-name-valid": "is-git-ref-name-valid/index.js",
+    "crc-32": "crc-32",
+    "sha.js": "sha.js",
+    "pako": "pako", "pify": "pify", "diff": "diff", "diff3": "diff3",
+    "ignore": "ignore", "readable-stream": "readable-stream",
+    "simple-get": "simple-get", "minimisted": "minimisted"
+  },
+  "durable_objects": {
+    "bindings": [{ "name": "NIMBUS_SESSION", "class_name": "NimbusSession" }]
+  },
+  "migrations": [
+    { "tag": "nimbus-v1", "new_sqlite_classes": ["NimbusSession"] }
+  ],
+  "worker_loaders": [{ "binding": "LOADER" }],
+  "r2_buckets": [
+    { "binding": "NPM_TARBALL_CACHE",    "bucket_name": "my-nimbus-npm-cache" },
+    { "binding": "NPM_PACKUMENT_CACHE",  "bucket_name": "my-nimbus-npm-packument-cache" },
+    { "binding": "NIMBUS_RUNTIME_CACHE", "bucket_name": "nimbus-runtime-cache-public" }
+  ]
+}
+```
+
+Then:
+
+```bash
+wrangler secret put JWT_SECRET     # 32+ hex chars
+wrangler deploy
+```
+
+`JWT_SECRET` is required for token-enforced deployments. Legacy-public
+single-tenant demos can set `NIMBUS_LEGACY_PUBLIC=1` and rely on URL
+possession instead.
+
+## Composable API
+
+`createNimbusHandler(options)` accepts:
+
+```ts
+{
+  auth?: { mode?: 'auto' | 'enforce' | 'legacy'; legacyPublic?: boolean };
+  hooks?: {
+    onSessionStart?: (ctx) => void | Promise<void>;
+    onSessionEnd?:   (ctx) => void | Promise<void>;  // reserved v0.2
+  };
+  routes?: (request, env, ctx) => Response | null | Promise<Response | null>;
+}
+```
+
+### Custom routes
+
+Routes that return non-`null` short-circuit Nimbus's router. Use them
+for a token-mint endpoint, `/healthz`, SDK smoke tests, or backend
+sandbox jobs.
+
+```ts
+import { issueNimbusToken } from '@nimbus-sh/sdk/token';
+
+export default createNimbusHandler({
+  routes: async (req, env) => {
+    if (new URL(req.url).pathname === '/api/auth/mint' && req.method === 'POST') {
+      const { tenant, sub } = await req.json();
+      const token = await issueNimbusToken(env, { tn: tenant, sub });
+      return Response.json({ token });
+    }
+    return null;
+  },
+});
+```
+
+Programmatic sandbox route:
+
+```ts
+import { Nimbus } from '@nimbus-sh/sdk/sandbox';
+
+export default createNimbusHandler({
+  routes: async (req, env) => {
+    const url = new URL(req.url);
+    if (url.pathname === '/api/run-python') {
+      const nimbus = Nimbus.fromEnv(env, {
+        endpoint: url.origin,
+        sandboxes: {
+          default: {
+            root: '/home/user',
+            runtimes: { preinstall: ['python'], onDemand: true },
+          },
+        },
+      });
+      const box = nimbus.sandbox('api-job-1', { tenant: 'api', subject: 'python' });
+      const result = await box.runCode('print(2 + 2)', {
+        language: 'python',
+        install: 'ifMissing',
+      });
+      return Response.json(result);
+    }
+    return null;
+  },
+});
+```
+
+For long-running app servers, start an explicit long-running process and
+expose the virtual port:
+
+```ts
+await box.files.write('/home/user/app/server.js', serverSource);
+await box.startProcess('node --watch /home/user/app/server.js');
+const port = await box.ports.expose(3000);
+```
+
+### Hooks
+
+```ts
+export default createNimbusHandler({
+  hooks: {
+    onSessionStart: ({ sessionId, tenantSegment, request }) => {
+      console.log(`[${tenantSegment}] session ${sessionId} attached from ${request.headers.get('cf-connecting-ip')}`);
+    },
+  },
+});
+```
+
+### Auth modes
+
+| Mode | Meaning |
+|---|---|
+| `'auto'` (default) | Verify token when `JWT_SECRET` is set AND `NIMBUS_LEGACY_PUBLIC` is unset. Otherwise legacy-public. |
+| `'enforce'` | Always verify token; fail closed if `JWT_SECRET` is missing. |
+| `'legacy'` | Never verify; all requests route to the single `legacy:public:_` tenant. Use only for single-tenant demos. |
+
+## Subpath exports
+
+| Subpath | What |
+|---|---|
+| `@nimbus-sh/worker` | `NimbusSession`, `SupervisorRPC` + other RPC classes, `createNimbusHandler`, auth types. |
+| `@nimbus-sh/worker/router` | `createNimbusHandler`, hooks types. |
+| `@nimbus-sh/worker/auth` | HS256 JWT issue/verify, typed errors. |
+
+## Required bindings
+
+Every binding is load-bearing — see `apps/dogfood/wrangler.jsonc` or
+`@nimbus-sh/config` for the canonical set:
+
+- `NIMBUS_SESSION` (Durable Object) — per-session SQLite state
+- `LOADER` (Worker Loader) — dynamic-isolate spawning for npm + vite + facets
+- `NPM_TARBALL_CACHE` + `NPM_PACKUMENT_CACHE` + `NIMBUS_RUNTIME_CACHE` (R2)
+- `ASSETS` — serves the xterm shell + lazy-loaded WASM/JS blobs
+- `JWT_SECRET` (secret) — HS256 signing key for token-enforced deployments
+
+## Status
+
+v0.1 — first public release. SemVer not yet stable; expect breaking
+changes through v0.x. Issues + PRs welcome.
+
+MIT. © Ashish Kumar Singh + contributors.

package/dist/_shared/bytes.d.ts

@@ -0,0 +1,18 @@
+/**
+ * _shared/bytes.ts — Singleton TextEncoder / TextDecoder.
+ *
+ * TextEncoder and TextDecoder for UTF-8 are stateless per the WHATWG
+ * Encoding spec, so a module-scope singleton is safe and saves the
+ * repeated allocation (which shows up in flame graphs of hot paths
+ * like sqlite-vfs writeFile and the WebSocket terminal frame decoder).
+ *
+ * Use these everywhere instead of `new TextEncoder()` / `new TextDecoder()`
+ * in the supervisor isolate. Facet-isolate code-strings (e.g. inside
+ * generateGitNetworkFacetCode) cannot import this module and must keep
+ * their inline allocations — those copies are justified.
+ */
+/** Shared UTF-8 encoder. Stateless; safe to share across all callers. */
+export declare const enc: TextEncoder;
+/** Shared UTF-8 decoder. Stateless; safe to share across all callers. */
+export declare const dec: TextDecoder;
+//# sourceMappingURL=bytes.d.ts.map

package/dist/_shared/bytes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bytes.d.ts","sourceRoot":"","sources":["../../src/_shared/bytes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,yEAAyE;AACzE,eAAO,MAAM,GAAG,aAAoB,CAAC;AAErC,yEAAyE;AACzE,eAAO,MAAM,GAAG,aAAoB,CAAC"}

package/dist/_shared/bytes.js

@@ -0,0 +1,17 @@
+/**
+ * _shared/bytes.ts — Singleton TextEncoder / TextDecoder.
+ *
+ * TextEncoder and TextDecoder for UTF-8 are stateless per the WHATWG
+ * Encoding spec, so a module-scope singleton is safe and saves the
+ * repeated allocation (which shows up in flame graphs of hot paths
+ * like sqlite-vfs writeFile and the WebSocket terminal frame decoder).
+ *
+ * Use these everywhere instead of `new TextEncoder()` / `new TextDecoder()`
+ * in the supervisor isolate. Facet-isolate code-strings (e.g. inside
+ * generateGitNetworkFacetCode) cannot import this module and must keep
+ * their inline allocations — those copies are justified.
+ */
+/** Shared UTF-8 encoder. Stateless; safe to share across all callers. */
+export const enc = new TextEncoder();
+/** Shared UTF-8 decoder. Stateless; safe to share across all callers. */
+export const dec = new TextDecoder();

package/dist/_shared/cache-stats.d.ts

@@ -0,0 +1,146 @@
+/**
+ * cache-stats.ts — Per-tier hit/miss/bytes counters for the npm cache stack.
+ *
+ * Purpose
+ * ───────
+ * The supervisor (and its facets) make cache lookups at four tiers:
+ *
+ *   L1 — per-DO SQLite (NpmCache)                    ~1 ms / file
+ *   L2 — caches.default (per-colo)                   ~50-500 µs hit
+ *   L3 — R2 (cross-tenant global)                    ~30-100 ms regional
+ *   L4 — registry.npmjs.org origin                   ~100-300 ms cross-region
+ *
+ * Pre-cache-observability wave: hit/miss counters lived in
+ * src/observability/diag-counters.ts but only tracked the RPC-call
+ * boundary (`r2.tarballHit`, `r2.packumentMiss`), not per-tier. From
+ * prod we couldn't tell whether L2 hit-rate was 90% or 30%.
+ *
+ * This module adds per-tier × per-kind counters. SAME singleton-per-
+ * isolate pattern as diag-counters.ts so any supervisor code path can
+ * write to it and `/api/_diag/cache` reads it back.
+ *
+ * Why a separate module instead of extending diag-counters.ts:
+ *   - Avoids touching diag-counters.ts (other waves may extend that
+ *     file's R2 race counters; keeping these orthogonal makes rebases
+ *     trivial).
+ *   - The new shape (Tier × Kind grid) is structurally different from
+ *     diag-counters' flat r2.* shape. Mixing them in one type would
+ *     create awkward conditional types.
+ *   - The new counters are exposed at /api/_diag/cache; diag-counters
+ *     is exposed at /api/_diag/memory. Separate endpoints, separate
+ *     modules.
+ *
+ * Lives in src/_shared/ so anyone (supervisor + future facet code) can
+ * import it without crossing the npm/, runtime/, facets/ boundaries
+ * that have wave-owners.
+ */
+/**
+ * Tier in the cache stack. Each tier is checked in order from L1 (warmest,
+ * fastest) down to L4 (coldest, slowest origin). Cache writes typically
+ * "fill" lower numbers from higher numbers — an L4 fetch may writeback
+ * to L3 and L2, an L3 hit may writeback to L2, etc.
+ */
+export type CacheTier = 'L1' | 'L2' | 'L3' | 'L4';
+/**
+ * Kind of content cached. Each kind has its own size profile and eviction
+ * policy:
+ *
+ *   tarball   — gzipped tar bytes, immutable forever, 30 MiB cap on L3
+ *   packument — registry metadata JSON, TTL-bounded (60 min post-P6),
+ *               unbounded size in practice (~10 KB - 1 MB typical)
+ *   asset     — non-package binaries cached cross-tenant (esbuild.wasm,
+ *               rolldown.wasm, etc.). Immutable forever, low churn.
+ */
+export type CacheKind = 'tarball' | 'packument' | 'asset';
+/**
+ * Per-(tier, kind) cell. A hit happened when we asked the tier "do you
+ * have <key>?" and it said yes (and returned bytes). A miss happened when
+ * we asked and it said no.
+ *
+ * `bytes` accumulates the size of HIT payloads only — misses have no
+ * bytes by definition. This means:
+ *
+ *   bytes / hits = average hit payload size
+ *
+ * which is the metric operators care about for capacity planning.
+ */
+export interface CacheCell {
+    hits: number;
+    misses: number;
+    /** Cumulative bytes returned on hits. Does NOT include miss "size" (0). */
+    bytes: number;
+}
+export interface CacheStatsSnapshot {
+    /** Tier × Kind grid. Each cell tracks hits, misses, bytes-on-hit. */
+    byTier: Record<CacheTier, Record<CacheKind, CacheCell>>;
+    /**
+     * Wall-clock ms at module load (when this isolate first received a
+     * request that imported this module). Stable across requests within
+     * the same isolate; resets on DO reboot (itself a useful signal).
+     */
+    startedAt: number;
+    /**
+     * Wall-clock ms at the most recent `reset()` call. Equals startedAt
+     * if reset() has never been called.
+     */
+    lastResetAt: number;
+    /**
+     * Derived hit-rate per (tier, kind), 0..1. Computed as
+     * hits / (hits + misses). NaN-safe: returns 0 when (hits + misses)
+     * is 0 so JSON serialisation stays clean. Mirrors the byTier shape
+     * exactly so consumers can ZIP the two structures with the same key
+     * paths.
+     */
+    hitRate: Record<CacheTier, Record<CacheKind, number>>;
+}
+/**
+ * Record a cache HIT at the given tier for the given kind.
+ *
+ * `bytes` is the size of the payload returned by the hit, in bytes.
+ * For packuments this is the JSON text length; for tarballs it's the
+ * gzipped tar byte length; for assets it's the asset bytes. The caller
+ * already has the size (post-fetch); passing it here is cheap.
+ *
+ * Pass 0 if the hit returned an empty payload (shouldn't happen in
+ * practice but the API tolerates it).
+ */
+export declare function recordHit(tier: CacheTier, kind: CacheKind, bytes: number): void;
+/**
+ * Record a cache MISS at the given tier for the given kind.
+ *
+ * Misses don't carry payload bytes. A miss at tier N typically means
+ * the caller will fall through to tier N+1; that downstream call will
+ * record its OWN hit or miss. So a single fetch flow naturally records
+ * a chain of misses ending in one hit at the tier that served the data.
+ *
+ * Example: cold fetch of `react@18.3.1` tarball records:
+ *
+ *   recordMiss('L1', 'tarball');
+ *   recordMiss('L2', 'tarball');
+ *   recordMiss('L3', 'tarball');
+ *   recordHit('L4', 'tarball', 12345);  // bytes from registry response
+ *
+ * After the writeback path runs, the same key from a subsequent fetch
+ * would record:
+ *
+ *   recordMiss('L1', 'tarball');
+ *   recordHit('L2', 'tarball', 12345);
+ */
+export declare function recordMiss(tier: CacheTier, kind: CacheKind): void;
+/**
+ * Return a snapshot of current counters + derived hit-rates.
+ *
+ * The returned object is a fresh copy — caller-side mutations don't
+ * affect the singleton. Mirrors readDiagCounters() in diag-counters.ts.
+ */
+export declare function snapshot(): CacheStatsSnapshot;
+/**
+ * Zero all counters. Sets lastResetAt to now. Used by the
+ * `/api/_diag/cache/reset` endpoint to start a fresh measurement window.
+ *
+ * Does NOT clear startedAt — that remains the original module-load time
+ * so operators can tell "this isolate has been up for X but counters
+ * were reset at Y" (the gap is intentional vs an isolate reboot).
+ */
+export declare function reset(): void;
+//# sourceMappingURL=cache-stats.d.ts.map

package/dist/_shared/cache-stats.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache-stats.d.ts","sourceRoot":"","sources":["../../src/_shared/cache-stats.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAElD;;;;;;;;;GASG;AACH,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,WAAW,GAAG,OAAO,CAAC;AAE1D;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,kBAAkB;IACjC,qEAAqE;IACrE,MAAM,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC;IACxD;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;;OAMG;IACH,OAAO,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,CAAC;CACvD;AAyCD;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAO/E;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,SAAS,GAAG,IAAI,CAGjE;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,IAAI,kBAAkB,CAqB7C;AAED;;;;;;;GAOG;AACH,wBAAgB,KAAK,IAAI,IAAI,CAS5B"}

package/dist/_shared/cache-stats.js

@@ -0,0 +1,162 @@
+/**
+ * cache-stats.ts — Per-tier hit/miss/bytes counters for the npm cache stack.
+ *
+ * Purpose
+ * ───────
+ * The supervisor (and its facets) make cache lookups at four tiers:
+ *
+ *   L1 — per-DO SQLite (NpmCache)                    ~1 ms / file
+ *   L2 — caches.default (per-colo)                   ~50-500 µs hit
+ *   L3 — R2 (cross-tenant global)                    ~30-100 ms regional
+ *   L4 — registry.npmjs.org origin                   ~100-300 ms cross-region
+ *
+ * Pre-cache-observability wave: hit/miss counters lived in
+ * src/observability/diag-counters.ts but only tracked the RPC-call
+ * boundary (`r2.tarballHit`, `r2.packumentMiss`), not per-tier. From
+ * prod we couldn't tell whether L2 hit-rate was 90% or 30%.
+ *
+ * This module adds per-tier × per-kind counters. SAME singleton-per-
+ * isolate pattern as diag-counters.ts so any supervisor code path can
+ * write to it and `/api/_diag/cache` reads it back.
+ *
+ * Why a separate module instead of extending diag-counters.ts:
+ *   - Avoids touching diag-counters.ts (other waves may extend that
+ *     file's R2 race counters; keeping these orthogonal makes rebases
+ *     trivial).
+ *   - The new shape (Tier × Kind grid) is structurally different from
+ *     diag-counters' flat r2.* shape. Mixing them in one type would
+ *     create awkward conditional types.
+ *   - The new counters are exposed at /api/_diag/cache; diag-counters
+ *     is exposed at /api/_diag/memory. Separate endpoints, separate
+ *     modules.
+ *
+ * Lives in src/_shared/ so anyone (supervisor + future facet code) can
+ * import it without crossing the npm/, runtime/, facets/ boundaries
+ * that have wave-owners.
+ */
+const TIERS = ['L1', 'L2', 'L3', 'L4'];
+const KINDS = ['tarball', 'packument', 'asset'];
+function makeEmptyGrid() {
+    const grid = {};
+    for (const tier of TIERS) {
+        grid[tier] = {};
+        for (const kind of KINDS) {
+            grid[tier][kind] = { hits: 0, misses: 0, bytes: 0 };
+        }
+    }
+    return grid;
+}
+/**
+ * Module-scoped singleton. Lives for the lifetime of the isolate.
+ *
+ * Workerd may evict the isolate at any time (memory pressure, idle
+ * shutdown, code update); when that happens, counters reset to zero
+ * on the next request — itself diagnostic signal: counters all-zero
+ * immediately after a request means we just woke up from cold.
+ *
+ * startedAt lazy-init: workerd returns 0 for `Date.now()` at
+ * module-evaluation time because IO is gated until the first request.
+ * Initialize lazily on the first hit/miss/snapshot so the timestamp
+ * reflects actual module-first-touched-by-request time, not the
+ * sentinel 0 value.
+ */
+const _grid = makeEmptyGrid();
+let _startedAt = 0;
+let _lastResetAt = 0;
+function _ensureStartedAt() {
+    if (_startedAt === 0) {
+        const now = Date.now();
+        _startedAt = now;
+        _lastResetAt = now;
+    }
+}
+/**
+ * Record a cache HIT at the given tier for the given kind.
+ *
+ * `bytes` is the size of the payload returned by the hit, in bytes.
+ * For packuments this is the JSON text length; for tarballs it's the
+ * gzipped tar byte length; for assets it's the asset bytes. The caller
+ * already has the size (post-fetch); passing it here is cheap.
+ *
+ * Pass 0 if the hit returned an empty payload (shouldn't happen in
+ * practice but the API tolerates it).
+ */
+export function recordHit(tier, kind, bytes) {
+    _ensureStartedAt();
+    const cell = _grid[tier][kind];
+    cell.hits++;
+    // Negative bytes is meaningless; coerce to 0. We trust the caller for
+    // accuracy but defend against accidental -1 sentinels.
+    cell.bytes += bytes > 0 ? bytes : 0;
+}
+/**
+ * Record a cache MISS at the given tier for the given kind.
+ *
+ * Misses don't carry payload bytes. A miss at tier N typically means
+ * the caller will fall through to tier N+1; that downstream call will
+ * record its OWN hit or miss. So a single fetch flow naturally records
+ * a chain of misses ending in one hit at the tier that served the data.
+ *
+ * Example: cold fetch of `react@18.3.1` tarball records:
+ *
+ *   recordMiss('L1', 'tarball');
+ *   recordMiss('L2', 'tarball');
+ *   recordMiss('L3', 'tarball');
+ *   recordHit('L4', 'tarball', 12345);  // bytes from registry response
+ *
+ * After the writeback path runs, the same key from a subsequent fetch
+ * would record:
+ *
+ *   recordMiss('L1', 'tarball');
+ *   recordHit('L2', 'tarball', 12345);
+ */
+export function recordMiss(tier, kind) {
+    _ensureStartedAt();
+    _grid[tier][kind].misses++;
+}
+/**
+ * Return a snapshot of current counters + derived hit-rates.
+ *
+ * The returned object is a fresh copy — caller-side mutations don't
+ * affect the singleton. Mirrors readDiagCounters() in diag-counters.ts.
+ */
+export function snapshot() {
+    _ensureStartedAt();
+    // Deep copy so caller mutations don't leak back into the singleton.
+    const byTier = {};
+    const hitRate = {};
+    for (const tier of TIERS) {
+        byTier[tier] = {};
+        hitRate[tier] = {};
+        for (const kind of KINDS) {
+            const c = _grid[tier][kind];
+            byTier[tier][kind] = { hits: c.hits, misses: c.misses, bytes: c.bytes };
+            const lookups = c.hits + c.misses;
+            hitRate[tier][kind] = lookups === 0 ? 0 : c.hits / lookups;
+        }
+    }
+    return {
+        byTier,
+        startedAt: _startedAt,
+        lastResetAt: _lastResetAt,
+        hitRate,
+    };
+}
+/**
+ * Zero all counters. Sets lastResetAt to now. Used by the
+ * `/api/_diag/cache/reset` endpoint to start a fresh measurement window.
+ *
+ * Does NOT clear startedAt — that remains the original module-load time
+ * so operators can tell "this isolate has been up for X but counters
+ * were reset at Y" (the gap is intentional vs an isolate reboot).
+ */
+export function reset() {
+    for (const tier of TIERS) {
+        for (const kind of KINDS) {
+            _grid[tier][kind].hits = 0;
+            _grid[tier][kind].misses = 0;
+            _grid[tier][kind].bytes = 0;
+        }
+    }
+    _lastResetAt = Date.now();
+}

package/dist/_shared/exports-resolver.d.ts

@@ -0,0 +1,76 @@
+/**
+ * exports-resolver.ts — Single source of truth for `package.json#exports` /
+ * `package.json#imports` resolution per the Node.js spec.
+ *
+ * Used in three contexts:
+ *
+ *   1. Install-time supervisor (TS) — `src/npm-resolver.ts` re-exports the
+ *      typed functions for tree resolution.
+ *
+ *   2. NimbusLoaderPool isolates (JS string) — `src/parallel/pre-bundle-preamble.ts`
+ *      embeds `getExportsResolverJS()` as part of the pool preamble so the
+ *      pre-bundle facet uses identical resolution semantics to the supervisor.
+ *
+ *   3. User-shell `node` runtime (JS string) — `src/node-shims.ts` embeds
+ *      the same JS source so `require()` from inside a user's `node` script
+ *      sees the same exports map as the install pipeline.
+ *
+ * Audit reference: audit/sections/03-resolver-gaps.md §3.1, §3.2.
+ *
+ * Spec features supported:
+ *   - String shorthand:                "exports": "./dist/index.mjs"
+ *   - Subpath maps:                    { ".": "...", "./client": "..." }
+ *   - Conditional maps (top-level):    { "import": "...", "require": "..." }
+ *   - Nested conditions:               { ".": { "node": { "default": "..." } } }
+ *   - Subpath wildcards:               { "./*": "./dist/*.js" }
+ *   - Array fallbacks:                 [ "./esm.js", "./cjs.js" ]
+ *   - `imports` field (`#name`):       same shape, same impl (re-uses resolveExports)
+ *   - Null-target enforcement:         { "./private/*": null } — returns null, blocks fallback
+ *
+ * Caller-controlled `conditions` lets the same impl serve:
+ *   - install/ESM/browser  →  ['import', 'module', 'browser', 'default']
+ *   - runtime CJS          →  ['require', 'node', 'default']
+ */
+/** Default conditions for ESM/install/browser resolution. */
+export declare const DEFAULT_ESM_CONDITIONS: string[];
+/** Default conditions for CJS runtime resolution (user-shell node). */
+export declare const DEFAULT_CJS_CONDITIONS: string[];
+/**
+ * Resolve `package.json#exports` (or `#imports`) per Node spec.
+ *
+ * @param exportsField  Raw value from package.json#exports or #imports
+ * @param subpath       '.' for root, './foo' for subpath, '#name' for imports
+ * @param conditions    Active conditions, in priority order
+ * @returns             Relative path target string, or null if not found / forbidden
+ */
+export declare function resolveExports(exportsField: any, subpath?: string, conditions?: string[]): string | null;
+/**
+ * Resolve a package's entry-point file relative to its directory.
+ * Priority: exports → module → main → null.
+ * For non-root subpaths without an `exports` field, returns the subpath
+ * itself (caller probes filesystem with extension-list).
+ */
+export declare function resolvePackageEntry(pkg: {
+    exports?: any;
+    module?: string;
+    main?: string;
+}, subpath?: string, conditions?: string[]): string | null;
+/**
+ * Returns the resolver source as plain JavaScript (no TypeScript syntax),
+ * suitable for embedding into a generated worker preamble or shim string.
+ *
+ * The emitted source declares three top-level functions in scope:
+ *   - resolveExports(exports, subpath, conditions)
+ *   - resolveConditionValue(target, conditions)        (helper)
+ *   - resolvePackageEntry(pkg, subpath, conditions)
+ *
+ * It also declares two arrays:
+ *   - DEFAULT_ESM_CONDITIONS
+ *   - DEFAULT_CJS_CONDITIONS
+ *
+ * This source must be byte-equivalent to the TS impl above (modulo type
+ * annotations and `export` keywords). Keep them in sync — there is one
+ * verification probe in audit/probes that compares parity.
+ */
+export declare function getExportsResolverJS(): string;
+//# sourceMappingURL=exports-resolver.d.ts.map

package/dist/_shared/exports-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"exports-resolver.d.ts","sourceRoot":"","sources":["../../src/_shared/exports-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,6DAA6D;AAC7D,eAAO,MAAM,sBAAsB,UAA6C,CAAC;AAEjF,uEAAuE;AACvE,eAAO,MAAM,sBAAsB,UAAiC,CAAC;AAErE;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,YAAY,EAAE,GAAG,EACjB,OAAO,GAAE,MAAY,EACrB,UAAU,GAAE,MAAM,EAA2B,GAC5C,MAAM,GAAG,IAAI,CAkEf;AAwCD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE;IAAE,OAAO,CAAC,EAAE,GAAG,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,EACtD,OAAO,GAAE,MAAY,EACrB,UAAU,GAAE,MAAM,EAA2B,GAC5C,MAAM,GAAG,IAAI,CAqBf;AAID;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,CAiG7C"}