@nimbus-sh/core 0.1.0

package/dist/_shared/ai-egress.d.ts

@@ -0,0 +1,73 @@
+/**
+ * _shared/ai-egress.ts — how the OS recognises a request as the session's own
+ * inference, wherever in the sandbox it was made.
+ *
+ * The problem this solves
+ * ──────────────────────
+ * Nimbus serves an OpenAI-compatible endpoint on session loopback
+ * (session/ai.ts) and advertises it as OPENAI_BASE_URL. Tools that follow that
+ * convention find it with no configuration. Plenty of tools do not: they hold a
+ * baked-in vendor base URL and only read the *key* from the environment, so the
+ * gateway is invisible to them and the seeded key is worse than useless — it
+ * tells them a provider is configured when the endpoint they will call is not
+ * reachable.
+ *
+ * Which vendor the OS names therefore matters as much as the mediation itself.
+ * A tool that reads a vendor key also holds that vendor's model catalogue, and
+ * this session runs Cloudflare Workers AI: every model it can serve is a
+ * `@cf/…` id. So the key is seeded as CLOUDFLARE_API_KEY, the interface for the
+ * account the session actually has. The tool then picks a model that exists
+ * here and addresses Cloudflare's host, and mediation makes that request land
+ * on the session's own gateway. Naming a vendor whose catalogue the session
+ * cannot serve would deliver the request and then fail on the model id, which
+ * is not a working capability.
+ *
+ * The mediation
+ * ─────────────
+ * The seeded key is a session capability token, and any request leaving the
+ * sandbox that presents it is inference this session owns. Those requests are
+ * served by the session's own gateway rather than sent to the network; the
+ * supervisor substitutes the real Cloudflare credential at the boundary, so the
+ * token is all the sandbox ever holds. The tool is not configured, adapted or
+ * special-cased anywhere — it makes the request it always makes, and the OS
+ * answers it. Same shape as a transparent proxy or /etc/resolv.conf.
+ *
+ * Why match on the credential and not on the destination
+ * ─────────────────────────────────────────────────────
+ * A list of AI vendor hostnames would need maintaining forever and would still
+ * hijack traffic that is not ours — a user's own OpenAI key, sent to OpenAI,
+ * would be captured by a host match. Matching the token instead makes the
+ * fallback correct by construction: a request carrying anything other than this
+ * session's token is not ours, is not touched, and reaches the real provider.
+ *
+ * The mediators live where egress happens — the facet's patched global fetch
+ * (runtime/node-shims.ts) and the shell's curl (substrate/lifo/commands/net) —
+ * and both decide with `requestCarriesSessionAiToken` over these constants, so
+ * the policy has one definition.
+ */
+/**
+ * Env var holding the session's AI capability token.
+ *
+ * Carried under its own name as well as CLOUDFLARE_API_KEY because
+ * CLOUDFLARE_API_KEY is the user's to overwrite: someone who exports a real
+ * Cloudflare token must still reach their own account. Mediation compares
+ * against THIS variable, never against whatever the vendor variable holds.
+ */
+export declare const NIMBUS_AI_TOKEN_ENV = "NIMBUS_AI_TOKEN";
+/**
+ * Headers an API credential is carried in, lowercased: `Authorization: Bearer`
+ * for OpenAI-shaped clients, `x-api-key` for Anthropic-shaped ones.
+ */
+export declare const NIMBUS_AI_CREDENTIAL_HEADERS: readonly ["authorization", "x-api-key"];
+/**
+ * Mint a session's token. Shaped like an OpenAI secret key because tools
+ * validate that shape before they will even attempt a request, and unguessable
+ * so that a string which merely *mentions* Nimbus can never be mistaken for it.
+ */
+export declare function mintSessionAiToken(): string;
+/**
+ * True when `headers` present `token`. False for an empty token, so a session
+ * that never seeded one mediates nothing.
+ */
+export declare function requestCarriesSessionAiToken(headers: Headers, token: string): boolean;
+//# sourceMappingURL=ai-egress.d.ts.map

package/dist/_shared/ai-egress.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-egress.d.ts","sourceRoot":"","sources":["../../src/_shared/ai-egress.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,oBAAoB,CAAC;AAErD;;;GAGG;AACH,eAAO,MAAM,4BAA4B,yCAA0C,CAAC;AAEpF;;;;GAIG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AAQD;;;GAGG;AACH,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAOrF"}

package/dist/_shared/ai-egress.js

@@ -0,0 +1,88 @@
+/**
+ * _shared/ai-egress.ts — how the OS recognises a request as the session's own
+ * inference, wherever in the sandbox it was made.
+ *
+ * The problem this solves
+ * ──────────────────────
+ * Nimbus serves an OpenAI-compatible endpoint on session loopback
+ * (session/ai.ts) and advertises it as OPENAI_BASE_URL. Tools that follow that
+ * convention find it with no configuration. Plenty of tools do not: they hold a
+ * baked-in vendor base URL and only read the *key* from the environment, so the
+ * gateway is invisible to them and the seeded key is worse than useless — it
+ * tells them a provider is configured when the endpoint they will call is not
+ * reachable.
+ *
+ * Which vendor the OS names therefore matters as much as the mediation itself.
+ * A tool that reads a vendor key also holds that vendor's model catalogue, and
+ * this session runs Cloudflare Workers AI: every model it can serve is a
+ * `@cf/…` id. So the key is seeded as CLOUDFLARE_API_KEY, the interface for the
+ * account the session actually has. The tool then picks a model that exists
+ * here and addresses Cloudflare's host, and mediation makes that request land
+ * on the session's own gateway. Naming a vendor whose catalogue the session
+ * cannot serve would deliver the request and then fail on the model id, which
+ * is not a working capability.
+ *
+ * The mediation
+ * ─────────────
+ * The seeded key is a session capability token, and any request leaving the
+ * sandbox that presents it is inference this session owns. Those requests are
+ * served by the session's own gateway rather than sent to the network; the
+ * supervisor substitutes the real Cloudflare credential at the boundary, so the
+ * token is all the sandbox ever holds. The tool is not configured, adapted or
+ * special-cased anywhere — it makes the request it always makes, and the OS
+ * answers it. Same shape as a transparent proxy or /etc/resolv.conf.
+ *
+ * Why match on the credential and not on the destination
+ * ─────────────────────────────────────────────────────
+ * A list of AI vendor hostnames would need maintaining forever and would still
+ * hijack traffic that is not ours — a user's own OpenAI key, sent to OpenAI,
+ * would be captured by a host match. Matching the token instead makes the
+ * fallback correct by construction: a request carrying anything other than this
+ * session's token is not ours, is not touched, and reaches the real provider.
+ *
+ * The mediators live where egress happens — the facet's patched global fetch
+ * (runtime/node-shims.ts) and the shell's curl (substrate/lifo/commands/net) —
+ * and both decide with `requestCarriesSessionAiToken` over these constants, so
+ * the policy has one definition.
+ */
+/**
+ * Env var holding the session's AI capability token.
+ *
+ * Carried under its own name as well as CLOUDFLARE_API_KEY because
+ * CLOUDFLARE_API_KEY is the user's to overwrite: someone who exports a real
+ * Cloudflare token must still reach their own account. Mediation compares
+ * against THIS variable, never against whatever the vendor variable holds.
+ */
+export const NIMBUS_AI_TOKEN_ENV = 'NIMBUS_AI_TOKEN';
+/**
+ * Headers an API credential is carried in, lowercased: `Authorization: Bearer`
+ * for OpenAI-shaped clients, `x-api-key` for Anthropic-shaped ones.
+ */
+export const NIMBUS_AI_CREDENTIAL_HEADERS = ['authorization', 'x-api-key'];
+/**
+ * Mint a session's token. Shaped like an OpenAI secret key because tools
+ * validate that shape before they will even attempt a request, and unguessable
+ * so that a string which merely *mentions* Nimbus can never be mistaken for it.
+ */
+export function mintSessionAiToken() {
+    return `sk-nimbus-${crypto.randomUUID().replace(/-/g, '')}`;
+}
+/** The credential a request presents, with any `Bearer ` prefix removed. */
+function presentedCredential(value) {
+    const trimmed = value.trim();
+    return /^bearer\s+/i.test(trimmed) ? trimmed.replace(/^bearer\s+/i, '') : trimmed;
+}
+/**
+ * True when `headers` present `token`. False for an empty token, so a session
+ * that never seeded one mediates nothing.
+ */
+export function requestCarriesSessionAiToken(headers, token) {
+    if (!token)
+        return false;
+    for (const name of NIMBUS_AI_CREDENTIAL_HEADERS) {
+        const raw = headers.get(name);
+        if (raw && presentedCredential(raw) === token)
+            return true;
+    }
+    return false;
+}

package/dist/_shared/byte-stream.d.ts

@@ -0,0 +1,59 @@
+/**
+ * _shared/byte-stream.ts — bounded byte streaming between the VFS and a
+ * command's output.
+ *
+ * Every coreutil that copies file content (`cat`, `head -c`, `dd`) needs the
+ * same three properties, and getting any of them wrong produces silently
+ * wrong bytes:
+ *
+ *   1. Bounded memory. Content moves one chunk at a time, so a 25 MB file
+ *      never becomes a 25 MB buffer — which matters because facet↔supervisor
+ *      RPC payloads are capped (MAX_RPC_SAFE_PAYLOAD_BYTES).
+ *   2. A real write offset. The sink advances; it does not restate the file.
+ *   3. Chunk boundaries that do not corrupt text. A UTF-8 sequence split
+ *      across two chunks must decode as one character, not two replacements,
+ *      so text sinks get a streaming decoder rather than per-chunk decodes.
+ */
+/**
+ * A command's output destination.
+ *
+ * `writeBytes` is present on sinks that store bytes verbatim (files). Sinks
+ * that are inherently textual — the terminal, shell pipes — omit it and
+ * receive decoded text instead. This is a real capability difference, not a
+ * fallback: a terminal has no way to hold a byte that is not text.
+ */
+export interface ByteSink {
+    write(text: string): void;
+    writeBytes?(bytes: Uint8Array): void;
+}
+/** Reads at most `length` bytes at `offset`; an empty result means EOF. */
+export type RangeReader = (offset: number, length: number) => Uint8Array;
+/** Bytes moved per read. Comfortably under any RPC payload ceiling. */
+export declare const STREAM_CHUNK_BYTES: number;
+/**
+ * Feeds bytes to a {@link ByteSink}, decoding across chunk boundaries when the
+ * sink is textual. Callers must `end()` so a trailing partial UTF-8 sequence
+ * is flushed.
+ */
+export declare class SinkWriter {
+    private readonly sink;
+    private readonly decoder;
+    private written;
+    constructor(sink: ByteSink);
+    get bytesWritten(): number;
+    write(bytes: Uint8Array): void;
+    end(): void;
+}
+/**
+ * Copies bytes from `read` into `sink` in {@link STREAM_CHUNK_BYTES} chunks.
+ *
+ * Stops at `length` bytes when given one, otherwise at the first short read
+ * (EOF). Returns the number of bytes copied. Does not call `sink.end()` —
+ * callers that write more than one range share a single writer.
+ */
+export declare function streamRange(read: RangeReader, writer: SinkWriter, options?: {
+    offset?: number;
+    length?: number;
+    signal?: AbortSignal;
+}): number;
+//# sourceMappingURL=byte-stream.d.ts.map

package/dist/_shared/byte-stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"byte-stream.d.ts","sourceRoot":"","sources":["../../src/_shared/byte-stream.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH;;;;;;;GAOG;AACH,MAAM,WAAW,QAAQ;IACvB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,UAAU,CAAC,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;CACtC;AAED,2EAA2E;AAC3E,MAAM,MAAM,WAAW,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,UAAU,CAAC;AAEzE,uEAAuE;AACvE,eAAO,MAAM,kBAAkB,QAAY,CAAC;AAE5C;;;;GAIG;AACH,qBAAa,UAAU;IAIT,OAAO,CAAC,QAAQ,CAAC,IAAI;IAHjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;IAC7C,OAAO,CAAC,OAAO,CAAK;gBAES,IAAI,EAAE,QAAQ;IAI3C,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED,KAAK,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;IAO9B,GAAG,IAAI,IAAI;CAKZ;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,WAAW,EACjB,MAAM,EAAE,UAAU,EAClB,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAAO,GACvE,MAAM,CAkBR"}

package/dist/_shared/byte-stream.js

@@ -0,0 +1,77 @@
+/**
+ * _shared/byte-stream.ts — bounded byte streaming between the VFS and a
+ * command's output.
+ *
+ * Every coreutil that copies file content (`cat`, `head -c`, `dd`) needs the
+ * same three properties, and getting any of them wrong produces silently
+ * wrong bytes:
+ *
+ *   1. Bounded memory. Content moves one chunk at a time, so a 25 MB file
+ *      never becomes a 25 MB buffer — which matters because facet↔supervisor
+ *      RPC payloads are capped (MAX_RPC_SAFE_PAYLOAD_BYTES).
+ *   2. A real write offset. The sink advances; it does not restate the file.
+ *   3. Chunk boundaries that do not corrupt text. A UTF-8 sequence split
+ *      across two chunks must decode as one character, not two replacements,
+ *      so text sinks get a streaming decoder rather than per-chunk decodes.
+ */
+/** Bytes moved per read. Comfortably under any RPC payload ceiling. */
+export const STREAM_CHUNK_BYTES = 64 * 1024;
+/**
+ * Feeds bytes to a {@link ByteSink}, decoding across chunk boundaries when the
+ * sink is textual. Callers must `end()` so a trailing partial UTF-8 sequence
+ * is flushed.
+ */
+export class SinkWriter {
+    sink;
+    decoder;
+    written = 0;
+    constructor(sink) {
+        this.sink = sink;
+        this.decoder = sink.writeBytes ? null : new TextDecoder('utf-8');
+    }
+    get bytesWritten() {
+        return this.written;
+    }
+    write(bytes) {
+        if (bytes.length === 0)
+            return;
+        this.written += bytes.length;
+        if (this.decoder)
+            this.sink.write(this.decoder.decode(bytes, { stream: true }));
+        else
+            this.sink.writeBytes(bytes);
+    }
+    end() {
+        if (!this.decoder)
+            return;
+        const tail = this.decoder.decode();
+        if (tail)
+            this.sink.write(tail);
+    }
+}
+/**
+ * Copies bytes from `read` into `sink` in {@link STREAM_CHUNK_BYTES} chunks.
+ *
+ * Stops at `length` bytes when given one, otherwise at the first short read
+ * (EOF). Returns the number of bytes copied. Does not call `sink.end()` —
+ * callers that write more than one range share a single writer.
+ */
+export function streamRange(read, writer, options = {}) {
+    const { offset = 0, length, signal } = options;
+    let position = offset;
+    let copied = 0;
+    while (length === undefined || copied < length) {
+        if (signal?.aborted)
+            break;
+        const want = length === undefined
+            ? STREAM_CHUNK_BYTES
+            : Math.min(STREAM_CHUNK_BYTES, length - copied);
+        const chunk = read(position, want);
+        if (chunk.length === 0)
+            break;
+        writer.write(chunk);
+        position += chunk.length;
+        copied += chunk.length;
+    }
+    return copied;
+}

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,145 @@
+/**
+ * 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 metrics support: hit/miss counters lived in
+ * src/observability/diag-counters.ts but only tracked the RPC-call
+ * boundary, not per-tier. Those flat counters have since been removed.
+ *
+ * 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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;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,161 @@
+/**
+ * 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 metrics support: hit/miss counters lived in
+ * src/observability/diag-counters.ts but only tracked the RPC-call
+ * boundary, not per-tier. Those flat counters have since been removed.
+ *
+ * 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();
+}