@selvajs/server 0.2.0-beta.2 → 0.2.0-beta.3

package/src/compute/__tests__/solve-pipeline.test.ts

@@ -13,25 +13,69 @@ import { gunzipSync } from 'node:zlib';
 import type { GrasshopperClient, InputParam, SolveScheduler } from '@selvajs/compute';
 
 // --- Mock @selvajs/compute -------------------------------------------------
+// The factory is hoisted above module top-level, so the RhinoComputeError
+// stand-in is declared INSIDE it. The pipeline classifies shed outcomes with
+// `err instanceof RhinoComputeError && err.code === ErrorCodes.QUEUE_*`, so the
+// mock must export a real class + the code constants. Tests import the mocked
+// `RhinoComputeError` below to construct instances the pipeline recognizes.
 vi.mock('@selvajs/compute', () => {
+	class RhinoComputeError extends Error {
+		code: string;
+		statusCode?: number;
+		context?: Record<string, unknown>;
+		constructor(
+			message: string,
+			code: string,
+			options?: { statusCode?: number; context?: Record<string, unknown> }
+		) {
+			super(message);
+			this.name = 'RhinoComputeError';
+			this.code = code;
+			this.statusCode = options?.statusCode;
+			this.context = options?.context;
+		}
+	}
 	return {
 		TreeBuilder: {
 			fromInputParams: (params: unknown[]) => ({ __tree: true, count: params.length })
 		},
 		// transform-input.ts (imported by the pipeline) calls processInput; return
 		// the raw shape as an InputParam so filtering/mapping runs end-to-end.
-		processInput: (raw: InputParam) => raw
+		processInput: (raw: InputParam) => raw,
+		// The L2 key module hashes over stableStringify — a deterministic sorted-key
+		// JSON is enough for the tests (real impl sorts recursively).
+		stableStringify: (value: unknown) => JSON.stringify(value),
+		RhinoComputeError,
+		ErrorCodes: { QUEUE_FULL: 'QUEUE_FULL', QUEUE_TIMEOUT: 'QUEUE_TIMEOUT' }
 	};
 });
 
+// The mocked class, typed loosely for constructing test errors. The `as` cast
+// keeps the 3-arg (message, code, options) signature the pipeline's mock uses.
+import { RhinoComputeError as MockRhinoComputeError } from '@selvajs/compute';
+const makeShedError = (
+	message: string,
+	code: 'QUEUE_FULL' | 'QUEUE_TIMEOUT' | 'UNKNOWN_ERROR',
+	options?: { statusCode?: number; context?: Record<string, unknown> }
+) =>
+	new (MockRhinoComputeError as unknown as new (
+		m: string,
+		c: string,
+		o?: { statusCode?: number; context?: Record<string, unknown> }
+	) => Error)(message, code, options);
+
 import {
 	runSolvePipeline,
 	COMPUTE_CONTRACT_VERSION,
 	COMPUTE_VERSION_HEADER,
+	deriveSolveCacheInputKey,
+	encodeSolveCacheEntry,
 	type SolvePipelineArgs,
+	type SolvePipelineCacheHook,
 	type PipelineInput,
 	type CachedClient
 } from '../index.js';
+import { gzipSync } from 'node:zlib';
 
 /**
  * A scripted solve stub. The pipeline only JSON-serializes and reads
@@ -196,6 +240,33 @@ describe('runSolvePipeline — failure outcomes', () => {
 		expect(outcome.kind).toBe('client_abort');
 	});
 
+	it('R3: a client disconnect while QUEUED forwards the signal and settles client_abort without a result', async () => {
+		// Models the queued-disconnect path the package fix (ISSUES 46) closes: the
+		// signal fires while the item waits in the FIFO, the scheduler settles it
+		// ABORTED (rejects with AbortError) and never runs compute. The pipeline's
+		// job — verified here — is to (a) hand the request signal to scheduler.solve
+		// so that prune can happen, and (b) classify the aborted-signal reject as
+		// client_abort (→ 499), never leaking a compute result.
+		const controller = new AbortController();
+		let seenSignal: AbortSignal | undefined;
+		const outcome = await runSolvePipeline(
+			baseArgs({
+				signal: controller.signal,
+				client: fakeClient(async (_d, _t, opts) => {
+					seenSignal = opts.signal;
+					// The disconnect arrives while queued: abort, then settle ABORTED —
+					// compute output is never produced (the loader throws, never returns).
+					controller.abort();
+					const e = new Error('aborted while queued');
+					e.name = 'AbortError';
+					throw e;
+				})
+			})
+		);
+		expect(seenSignal).toBe(controller.signal); // scheduler CAN observe the disconnect
+		expect(outcome.kind).toBe('client_abort'); // → 499, not a 500/compute_error
+	});
+
 	it('classifies any other throw as compute_error carrying the original error', async () => {
 		const boom = new TypeError('fetch failed');
 		const outcome = await runSolvePipeline(
@@ -219,6 +290,57 @@ describe('runSolvePipeline — failure outcomes', () => {
 		);
 		expect(outcome.kind).toBe('too_large');
 	});
+
+	it('classifies a QUEUE_FULL rejection as shed(queue_full) with a Retry-After hint', async () => {
+		const outcome = await runSolvePipeline(
+			baseArgs({
+				client: fakeClient(async () => {
+					throw makeShedError('queue full', 'QUEUE_FULL', {
+						statusCode: 503,
+						context: { queueDepth: 8, maxQueueDepth: 8 }
+					});
+				})
+			})
+		);
+		expect(outcome.kind).toBe('shed');
+		if (outcome.kind !== 'shed') return;
+		expect(outcome.reason).toBe('queue_full');
+		expect(outcome.retryAfterSeconds).toBeGreaterThan(0);
+		expect(outcome.message).toBeTruthy();
+	});
+
+	it('classifies a QUEUE_TIMEOUT rejection as shed(queue_timeout)', async () => {
+		const outcome = await runSolvePipeline(
+			baseArgs({
+				client: fakeClient(async () => {
+					throw makeShedError('queued too long', 'QUEUE_TIMEOUT', {
+						statusCode: 503,
+						context: { waitedMs: 5000, queueWaitMs: 3000 }
+					});
+				})
+			})
+		);
+		expect(outcome.kind).toBe('shed');
+		if (outcome.kind !== 'shed') return;
+		expect(outcome.reason).toBe('queue_timeout');
+		expect(outcome.retryAfterSeconds).toBeGreaterThan(0);
+	});
+
+	it('does NOT shed a RhinoComputeError with an unrelated code (stays compute_error)', async () => {
+		const boom = makeShedError('server exploded', 'UNKNOWN_ERROR', {
+			statusCode: 500
+		});
+		const outcome = await runSolvePipeline(
+			baseArgs({
+				client: fakeClient(async () => {
+					throw boom;
+				})
+			})
+		);
+		expect(outcome.kind).toBe('compute_error');
+		if (outcome.kind !== 'compute_error') return;
+		expect(outcome.error).toBe(boom);
+	});
 });
 
 describe('runSolvePipeline — Server-Timing', () => {
@@ -321,6 +443,51 @@ describe('runSolvePipeline — Server-Timing', () => {
 		expect(st).not.toContain('rhino_decode');
 	});
 
+	it('emits def_bytes=skipped when the byteRefOutcome shows load() never ran (pointer solve)', async () => {
+		const outcome = await runSolvePipeline(
+			baseArgs({
+				byteRefOutcome: { loaded: false, fromCache: false },
+				client: fakeClient(async () => ({ errors: [], warnings: [] }))
+			})
+		);
+		expect(outcome.kind).toBe('ok');
+		if (outcome.kind !== 'ok') return;
+		expect(outcome.envelope.headers['Server-Timing']).toContain('def_bytes;desc=skipped');
+	});
+
+	it('emits def_bytes=hit when bytes were served from the warm cache', async () => {
+		const outcome = await runSolvePipeline(
+			baseArgs({
+				byteRefOutcome: { loaded: true, fromCache: true },
+				client: fakeClient(async () => ({ errors: [], warnings: [] }))
+			})
+		);
+		expect(outcome.kind).toBe('ok');
+		if (outcome.kind !== 'ok') return;
+		expect(outcome.envelope.headers['Server-Timing']).toContain('def_bytes;desc=hit');
+	});
+
+	it('emits def_bytes=miss when the loader was called', async () => {
+		const outcome = await runSolvePipeline(
+			baseArgs({
+				byteRefOutcome: { loaded: true, fromCache: false },
+				client: fakeClient(async () => ({ errors: [], warnings: [] }))
+			})
+		);
+		expect(outcome.kind).toBe('ok');
+		if (outcome.kind !== 'ok') return;
+		expect(outcome.envelope.headers['Server-Timing']).toContain('def_bytes;desc=miss');
+	});
+
+	it('omits def_bytes entirely for a raw-bytes solve (no byteRefOutcome)', async () => {
+		const outcome = await runSolvePipeline(
+			baseArgs({ client: fakeClient(async () => ({ errors: [], warnings: [] })) })
+		);
+		expect(outcome.kind).toBe('ok');
+		if (outcome.kind !== 'ok') return;
+		expect(outcome.envelope.headers['Server-Timing']).not.toContain('def_bytes');
+	});
+
 	it('never attributes rhino timing to a Selva-cache hit (no compute call of ours)', async () => {
 		// Our request was served from the in-process cache while a concurrent
 		// request's compute call produced the only rhino timing in the window.
@@ -339,3 +506,155 @@ describe('runSolvePipeline — Server-Timing', () => {
 		expect(st).not.toContain('rhino_decode');
 	});
 });
+
+// ============================================================================
+// L2 durable solve cache hook (Phase 3.4)
+// ============================================================================
+
+describe('runSolvePipeline — L2 solve cache', () => {
+	const config = { computeServerId: 'srv-1' };
+
+	/** A hook backed by a Map, recording lookups/stores for assertions. */
+	function fakeHook(seed?: Map<string, Uint8Array>) {
+		const store = seed ?? new Map<string, Uint8Array>();
+		const lookups: string[] = [];
+		const stores: string[] = [];
+		const hook: SolvePipelineCacheHook = {
+			configSubset: config,
+			lookup: async (key) => {
+				lookups.push(key);
+				return store.get(key) ?? null;
+			},
+			store: (key, entry) => {
+				stores.push(key);
+				store.set(key, entry);
+			}
+		};
+		return { hook, store, lookups, stores };
+	}
+
+	it('a miss solves, then write-throughs the gzipped envelope and marks l2_cache;dur=0', async () => {
+		const result = { values: [{ id: 'out' }], errors: [], warnings: ['w'] };
+		let solves = 0;
+		const { hook, store, stores } = fakeHook();
+		const outcome = await runSolvePipeline(
+			baseArgs({
+				client: fakeClient(async () => {
+					solves += 1;
+					return result;
+				}),
+				acceptEncoding: 'gzip',
+				solveCache: hook
+			})
+		);
+		expect(outcome.kind).toBe('ok');
+		if (outcome.kind !== 'ok') return;
+		expect(solves).toBe(1);
+		expect(outcome.envelope.headers['Server-Timing']).toContain('l2_cache;dur=0');
+		// Write-through happened — one entry stored under the derived key.
+		expect(stores).toHaveLength(1);
+		expect(store.size).toBe(1);
+	});
+
+	it('a hit returns the stored envelope WITHOUT solving and marks l2_cache;dur=1', async () => {
+		const result = { values: [{ id: 'cached' }], errors: [], warnings: [] };
+		const serialized = JSON.stringify(result);
+		// Pre-seed the store at the key the pipeline will derive for these inputs.
+		const args = baseArgs({ acceptEncoding: 'gzip' });
+		const tree = { __tree: true, count: 1 }; // matches the mock TreeBuilder output
+		const inputKey = deriveSolveCacheInputKey(tree, config).hash;
+		const entry = encodeSolveCacheEntry(
+			{ errorCount: 0, warningCount: 0, serializedBytes: serialized.length, inputHash: inputKey },
+			new Uint8Array(gzipSync(Buffer.from(serialized)))
+		);
+		const seed = new Map([[inputKey, entry]]);
+		const { hook } = fakeHook(seed);
+
+		let solves = 0;
+		const outcome = await runSolvePipeline({
+			...args,
+			client: fakeClient(async () => {
+				solves += 1;
+				return { values: [], errors: [], warnings: [] };
+			}),
+			solveCache: hook
+		});
+		expect(outcome.kind).toBe('ok');
+		if (outcome.kind !== 'ok') return;
+		expect(solves).toBe(0); // never solved — served from L2
+		expect(outcome.envelope.encoding).toBe('gzip');
+		expect(gunzipSync(outcome.envelope.body as Uint8Array).toString()).toBe(serialized);
+		expect(outcome.envelope.headers['Server-Timing']).toContain('l2_cache;dur=1');
+	});
+
+	it('a hit for a non-gzip client gunzips the stored body back to JSON', async () => {
+		const result = { values: [{ id: 'x' }], errors: [], warnings: [] };
+		const serialized = JSON.stringify(result);
+		const tree = { __tree: true, count: 1 };
+		const inputKey = deriveSolveCacheInputKey(tree, config).hash;
+		const entry = encodeSolveCacheEntry(
+			{ errorCount: 0, warningCount: 0, serializedBytes: serialized.length, inputHash: inputKey },
+			new Uint8Array(gzipSync(Buffer.from(serialized)))
+		);
+		const { hook } = fakeHook(new Map([[inputKey, entry]]));
+		const outcome = await runSolvePipeline(baseArgs({ acceptEncoding: '', solveCache: hook }));
+		expect(outcome.kind).toBe('ok');
+		if (outcome.kind !== 'ok') return;
+		expect(outcome.envelope.encoding).toBeUndefined();
+		expect(outcome.envelope.body).toBe(serialized);
+	});
+
+	it('a stored entry whose inputHash mismatches is ignored (collision defense) and re-solves', async () => {
+		// Seed the derived key with an entry carrying a DIFFERENT inputHash — a
+		// (hypothetical) storage-key collision must not serve the wrong geometry.
+		const tree = { __tree: true, count: 1 };
+		const inputKey = deriveSolveCacheInputKey(tree, config).hash;
+		const wrong = encodeSolveCacheEntry(
+			{ errorCount: 0, warningCount: 0, serializedBytes: 2, inputHash: 'not-the-real-hash' },
+			new Uint8Array(gzipSync(Buffer.from('{}')))
+		);
+		const { hook } = fakeHook(new Map([[inputKey, wrong]]));
+		let solves = 0;
+		const outcome = await runSolvePipeline(
+			baseArgs({
+				client: fakeClient(async () => {
+					solves += 1;
+					return { values: [{ id: 'fresh' }], errors: [], warnings: [] };
+				}),
+				solveCache: hook
+			})
+		);
+		expect(outcome.kind).toBe('ok');
+		if (outcome.kind !== 'ok') return;
+		expect(solves).toBe(1); // fell through to a real solve
+	});
+
+	it('omits l2_cache from Server-Timing when no hook is passed', async () => {
+		const outcome = await runSolvePipeline(baseArgs());
+		expect(outcome.kind).toBe('ok');
+		if (outcome.kind !== 'ok') return;
+		expect(outcome.envelope.headers['Server-Timing']).not.toContain('l2_cache');
+	});
+
+	it('a lookup that rejects is treated as a miss (best-effort), then solves', async () => {
+		let solves = 0;
+		const hook: SolvePipelineCacheHook = {
+			configSubset: config,
+			lookup: async () => {
+				throw new Error('backend down');
+			},
+			store: () => {}
+		};
+		const outcome = await runSolvePipeline(
+			baseArgs({
+				client: fakeClient(async () => {
+					solves += 1;
+					return { values: [], errors: [], warnings: [] };
+				}),
+				solveCache: hook
+			})
+		);
+		expect(outcome.kind).toBe('ok');
+		expect(solves).toBe(1);
+	});
+});

package/src/compute/client-cache.ts

@@ -103,6 +103,18 @@ export interface ClientCacheConfig {
 	 * (`ComputeLimits.computeMaxConcurrentSolves`).
 	 */
 	maxConcurrentSolves: number;
+	/**
+	 * Backpressure — max solves that may WAIT in the FIFO queue (excludes the
+	 * in-flight `maxConcurrentSolves`). `0` = unbounded (`ComputeLimits.
+	 * computeMaxQueueDepth`); a full queue sheds new solves with `QUEUE_FULL`.
+	 */
+	maxQueueDepth: number;
+	/**
+	 * Backpressure — max ms a solve may sit queued before executing; `0` = no
+	 * deadline (`ComputeLimits.computeQueueWaitMs`). A too-long wait sheds with
+	 * `QUEUE_TIMEOUT`.
+	 */
+	queueWaitMs: number;
 	/** Concise cache/timing logs. When false, `onDebugLog` is never invoked. */
 	debug: boolean;
 	/** VERBOSE lib-level logging (full solve request/response incl. geometry). */
@@ -208,6 +220,11 @@ export function createClientCache(config: ClientCacheConfig): ClientCache {
 			// solve on this server through a single slot while the compute VM's
 			// other compute.geometry children idle (audit B6) — always pass it.
 			maxConcurrent: config.maxConcurrentSolves,
+			// Backpressure (audit B7). The scheduler treats undefined as
+			// unbounded/no-deadline, so map our `0`-means-off convention to undefined
+			// rather than passing 0 (which would shed EVERY queued solve).
+			maxQueueDepth: config.maxQueueDepth || undefined,
+			queueWaitMs: config.queueWaitMs || undefined,
 			timeoutMs: config.maxSolveDurationMs,
 			cache: { maxEntries: 20, ttlMs: 5 * 60_000 },
 			// Solve large definitions by server cache-key (pointer) instead of
@@ -241,14 +258,18 @@ export function createClientCache(config: ClientCacheConfig): ClientCache {
 								: '[Compute/def-cache] n/a — reuse disabled or non-reusable definition'
 					);
 				}
-				// Surface real GH errors when present. An errored solve is NEVER cached
-				// server-side (cachesolve only stores error-free solves).
+				// Surface real GH errors when present. Whether an errored solve is cached is
+				// config-gated by `cacheerroredsolves` (default false → errored solves are
+				// re-run each time; true → the error result is cached like any other, per R2).
 				if (!result.fromCache) {
 					const errs = (result.response as { errors?: unknown[] })?.errors;
 					const errCount = Array.isArray(errs) ? errs.length : 0;
 					if (errCount > 0) {
+						const cacheNote = config.cacheerroredsolves
+							? 'cached (cacheerroredsolves on)'
+							: 'not cached (cacheerroredsolves off) — re-run until fixed';
 						debugLog(
-							`[Compute/rhino-cache] ${errCount} GH error(s); not cacheable until fixed. First: ${JSON.stringify((errs as unknown[])[0])}`
+							`[Compute/rhino-cache] ${errCount} GH error(s); ${cacheNote}. First: ${JSON.stringify((errs as unknown[])[0])}`
 						);
 					}
 				}

package/src/compute/definition-byte-cache.ts

@@ -0,0 +1,168 @@
+/**
+ * In-process cache of `.gh` definition bytes, keyed by immutable **version id**.
+ *
+ * The solve path used to eagerly `storage.get(fileKey)` on every request — moving
+ * multi-MB definition bytes off disk/S3 into memory before the scheduler could
+ * decide it didn't need them (the compute server already holds the definition via
+ * the pointer/`reuseServerDefinitionCache` fast path). This cache turns that eager
+ * read into a lazy `DefinitionRef.load()`: the scheduler calls `load()` ONLY when
+ * an upload is unavoidable, and even then a warm entry serves the bytes without
+ * touching storage. A pointer-known re-solve therefore moves ZERO definition bytes.
+ *
+ * Keying discipline (the whole reason this module exists):
+ *   - The key is the **version id**, an immutable UUID — never a `fileKey`, which
+ *     a delete-latest-then-reupload can REUSE for different content (see the
+ *     monotonic-version-number fix). A reused key would serve one version's bytes
+ *     for another: silent cache poisoning with no diagnostic. Callers pass
+ *     `version.id`, and the returned `DefinitionRef.key` is that same id, so the
+ *     scheduler's own result/pointer cache keys on the same immutable identity.
+ *
+ * Eviction:
+ *   - LRU by **total byte budget**, not entry count — definitions range from tens
+ *     of KB to hundreds of MB, so an entry-count cap would either pin gigabytes or
+ *     evict uselessly. `COMPUTE_DEFINITION_BYTE_CACHE_MB` sets the budget; `0`
+ *     disables the cache (every `getOrLoad` calls `load` and caches nothing).
+ *   - No TTL: version ids are immutable, so a cached entry can never go stale.
+ *   - An entry larger than the whole budget is served but never retained (caching
+ *     it would immediately evict everything including itself).
+ */
+
+/**
+ * Per-`getOrLoad` outcome, observable AFTER the scheduler has (or hasn't) called
+ * `load()`. Lets the solve pipeline emit a `def_bytes` Server-Timing verdict:
+ *   - `load` never invoked  → the scheduler served a pointer-known solve without
+ *     bytes (`skipped`);
+ *   - `load` invoked, `fromCache` true  → warm byte-cache entry (`hit`);
+ *   - `load` invoked, `fromCache` false → fell through to the loader (`miss`).
+ */
+export interface ByteRefOutcome {
+	/** True once `load()` has been called at least once on this ref. */
+	loaded: boolean;
+	/** When `loaded`, whether the bytes came from a warm cache entry. */
+	fromCache: boolean;
+}
+
+/** A definition reference shaped for `@selvajs/compute`'s `DefinitionRef`. */
+export interface ByteCacheRef {
+	/** Immutable identity (a version UUID). Keys the scheduler's caches too. */
+	key: string;
+	/** Materialize the bytes — served from cache when warm, else via the loader. */
+	load: () => Promise<Uint8Array>;
+	/** Mutable outcome of this ref's `load()` (see {@link ByteRefOutcome}). */
+	outcome: ByteRefOutcome;
+}
+
+/** Hit/miss/eviction counters for observability (Server-Timing, admin debug). */
+export interface ByteCacheStats {
+	/** `load()` served from a warm entry (no loader call). */
+	hits: number;
+	/** `load()` fell through to the loader (cold key, or caching disabled). */
+	misses: number;
+	/** Entries dropped by the byte-budget LRU. */
+	evictions: number;
+	/** Current retained entry count. */
+	entries: number;
+	/** Current retained bytes. */
+	bytes: number;
+}
+
+export interface DefinitionByteCache {
+	/**
+	 * Return a `DefinitionRef` whose `load()` serves `versionId`'s bytes from the
+	 * cache when warm, otherwise calls `load` (and caches the result). The
+	 * `DefinitionRef` is cheap to build and moves no bytes until `load()` runs —
+	 * so handing it to the scheduler for a pointer-known solve costs nothing.
+	 */
+	getOrLoad(versionId: string, load: () => Promise<Uint8Array>): ByteCacheRef;
+	/** Snapshot of the counters (see {@link ByteCacheStats}). */
+	stats(): ByteCacheStats;
+	/** Drop everything (test seam / eviction on definition delete if ever needed). */
+	clear(): void;
+}
+
+interface Entry {
+	bytes: Uint8Array;
+}
+
+/**
+ * Build a definition-byte cache with a total-byte LRU budget.
+ *
+ * @param maxBytes total retained-byte budget; `0` (or negative) disables caching
+ *   entirely — every `load()` calls the loader and nothing is retained.
+ */
+export function createDefinitionByteCache(maxBytes: number): DefinitionByteCache {
+	const budget = Math.max(0, Math.floor(maxBytes));
+	// Map preserves insertion order → iteration order IS LRU order; re-inserting
+	// on access moves an entry to the most-recently-used (last) position.
+	const cache = new Map<string, Entry>();
+	let retainedBytes = 0;
+	const stats = { hits: 0, misses: 0, evictions: 0 };
+
+	function touch(key: string, entry: Entry): void {
+		cache.delete(key);
+		cache.set(key, entry);
+	}
+
+	function evictToFit(): void {
+		// Evict least-recently-used (first in insertion order) until within budget.
+		while (retainedBytes > budget && cache.size > 0) {
+			const oldestKey = cache.keys().next().value as string;
+			const oldest = cache.get(oldestKey)!;
+			cache.delete(oldestKey);
+			retainedBytes -= oldest.bytes.byteLength;
+			stats.evictions += 1;
+		}
+	}
+
+	function store(key: string, bytes: Uint8Array): void {
+		if (budget === 0) return;
+		// An entry bigger than the whole budget is never retained — caching it would
+		// evict everything (including itself) on the next `evictToFit`. Serve it
+		// through, cache nothing.
+		if (bytes.byteLength > budget) return;
+		const existing = cache.get(key);
+		if (existing) retainedBytes -= existing.bytes.byteLength;
+		cache.set(key, { bytes });
+		retainedBytes += bytes.byteLength;
+		evictToFit();
+	}
+
+	return {
+		getOrLoad(versionId, load) {
+			const outcome: ByteRefOutcome = { loaded: false, fromCache: false };
+			return {
+				key: versionId,
+				outcome,
+				load: async () => {
+					const hit = cache.get(versionId);
+					if (hit) {
+						touch(versionId, hit);
+						stats.hits += 1;
+						outcome.loaded = true;
+						outcome.fromCache = true;
+						return hit.bytes;
+					}
+					stats.misses += 1;
+					outcome.loaded = true;
+					outcome.fromCache = false;
+					const bytes = await load();
+					store(versionId, bytes);
+					return bytes;
+				}
+			};
+		},
+		stats() {
+			return {
+				hits: stats.hits,
+				misses: stats.misses,
+				evictions: stats.evictions,
+				entries: cache.size,
+				bytes: retainedBytes
+			};
+		},
+		clear() {
+			cache.clear();
+			retainedBytes = 0;
+		}
+	};
+}

package/src/compute/index.ts

@@ -3,11 +3,44 @@
 export {
 	resolveComputeLimits,
 	readPositiveInt,
+	readNonNegativeInt,
 	readBool,
 	type ComputeLimits,
 	type EnvRecord
 } from './limits.js';
 
+export {
+	createDefinitionByteCache,
+	type DefinitionByteCache,
+	type ByteCacheRef,
+	type ByteCacheStats
+} from './definition-byte-cache.js';
+
+export {
+	createMemorySolveResultCache,
+	type MemorySolveResultCache,
+	type SolveCacheStats
+} from './memory-solve-cache.js';
+
+export {
+	deriveSolveCacheInputKey,
+	type SolveCacheConfigSubset,
+	type SolveCacheInputKey
+} from './solve-cache-key.js';
+
+export {
+	encodeSolveCacheEntry,
+	decodeSolveCacheEntry,
+	gunzipEntryBody,
+	type EnvelopeHeader,
+	type DecodedSolveCacheEntry
+} from './solve-cache-envelope.js';
+
+export {
+	createSolveCacheSingleFlight,
+	type SolveCacheSingleFlight
+} from './solve-cache-single-flight.js';
+
 export {
 	createComputeRateLimiter,
 	type ComputeRateLimiter,
@@ -41,6 +74,7 @@ export {
 	COMPUTE_CONTRACT_VERSION,
 	COMPUTE_VERSION_HEADER,
 	type SolvePipelineArgs,
+	type SolvePipelineCacheHook,
 	type SolveOutcome,
 	type SolveEnvelope,
 	type SolvePhaseMetrics,