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

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,

package/src/compute/limits.ts

@@ -38,6 +38,23 @@ export function readPositiveInt(env: EnvRecord, name: string, fallback: number):
 	return Math.floor(parsed);
 }
 
+/**
+ * Parse a non-negative integer env value — like {@link readPositiveInt} but `0`
+ * is a valid value (used by knobs where `0` means "disable", e.g. a cache
+ * budget). Returns `fallback` when absent, and warns + falls back when present
+ * but not a finite non-negative number.
+ */
+export function readNonNegativeInt(env: EnvRecord, name: string, fallback: number): number {
+	const raw = env[name];
+	if (!raw) return fallback;
+	const parsed = Number(raw);
+	if (!Number.isFinite(parsed) || parsed < 0) {
+		console.warn(`[selva] Invalid ${name}=${raw}, falling back to ${fallback}`);
+		return fallback;
+	}
+	return Math.floor(parsed);
+}
+
 /**
  * Parse a boolean env flag. Accepts `true/1/yes/on` (case-insensitive) as true
  * and `false/0/no/off` as false; any other / absent value falls back.
@@ -115,6 +132,61 @@ export interface ComputeLimits {
 	 * honoring the flag. Conservative default off.
 	 */
 	computeCacheErroredSolves: boolean;
+	/**
+	 * Max in-flight solves this app instance sends to ONE compute server
+	 * (forwarded as the SolveScheduler's `maxConcurrent`; excess solves FIFO-queue).
+	 * Size it to the server's `compute.geometry` child count — Rhino.Compute
+	 * spawns N children per VM precisely to run N solves concurrently, and a
+	 * lower value idles that capacity while users queue (audit B6: the scheduler's
+	 * queue-mode default is 1, which serialized ALL solves per server). Multiple
+	 * app instances each apply their own cap.
+	 */
+	computeMaxConcurrentSolves: number;
+	/**
+	 * Backpressure — max solves allowed to WAIT in the per-server FIFO queue (i.e.
+	 * excluding the `computeMaxConcurrentSolves` already in flight). A solve that
+	 * arrives to a full queue is shed immediately (scheduler `QUEUE_FULL`, mapped
+	 * to HTTP 503 + `Retry-After`) instead of piling up unbounded. `0` = unbounded
+	 * (the pre-shedding default): the queue grows without limit, matching prior
+	 * behavior. Size it to roughly 2–3× `computeMaxConcurrentSolves` once the
+	 * Rhino pool's real capacity is known — shedding fast beats a hung request.
+	 */
+	computeMaxQueueDepth: number;
+	/**
+	 * Backpressure — longest (ms) a solve may sit QUEUED before it starts
+	 * executing; still-waiting past this it's shed (scheduler `QUEUE_TIMEOUT` →
+	 * HTTP 503 + `Retry-After`) rather than burning compute on a stale request.
+	 * Bounds tail latency: the scheduler's `timeoutMs` clock starts at execution,
+	 * so without this a solve's total wait is unbounded and invisible. `0` = no
+	 * queue deadline (the default). A sensible tuned value is ≈ `maxSolveDurationMs`.
+	 */
+	computeQueueWaitMs: number;
+	/**
+	 * Total-byte budget (bytes) for the in-process definition-byte cache keyed on
+	 * immutable version id. A warm entry lets a solve skip `storage.get` entirely,
+	 * and a pointer-known solve never loads bytes at all. `0` disables the cache
+	 * (every solve re-reads storage). Sized as a total-byte LRU because definitions
+	 * span KB→hundreds of MB; env value is MB, converted here.
+	 */
+	computeDefinitionByteCacheBytes: number;
+	/**
+	 * Default per-definition entry quota for the durable L2 solve cache (H1), used
+	 * when a definition's `solveCacheLimit` is absent (inherit). A definition may
+	 * override this; `0` on the definition turns caching off for it. This global
+	 * default `0` means the L2 is effectively off until an operator sets a quota —
+	 * safe because the memory backend also ships only under
+	 * `SOLVE_CACHE_PROVIDER=memory`. Counts, not bytes: authors think in "how many
+	 * solves to remember"; the byte backstop below is the operator's memory guard.
+	 */
+	solveCacheDefaultMaxEntries: number;
+	/**
+	 * Global byte backstop (bytes) across ALL definitions' L2 entries, evicted
+	 * global-LRU regardless of per-definition counts. Entries range KB→100s of MB,
+	 * so a count quota alone can't bound memory. `0` disables the backstop (rely on
+	 * per-definition counts only — not recommended in the memory backend). Env value
+	 * is MB, converted here. On Redis this moves to `maxmemory allkeys-lru`.
+	 */
+	solveCacheMaxTotalBytes: number;
 }
 
 /**
@@ -142,6 +214,24 @@ export function resolveComputeLimits(env: EnvRecord): ComputeLimits {
 		definitionCacheTtlMs: readPositiveInt(env, 'DEFINITION_CACHE_TTL_MS', 5 * 60 * 1000),
 		computeReuseDefinitionCache: readBool(env, 'COMPUTE_REUSE_DEFINITION_CACHE', true),
 		computeServerCachesolve: readBool(env, 'COMPUTE_SERVER_CACHESOLVE', true),
-		computeCacheErroredSolves: readBool(env, 'COMPUTE_CACHE_ERRORED_SOLVES', false)
+		computeCacheErroredSolves: readBool(env, 'COMPUTE_CACHE_ERRORED_SOLVES', false),
+		// 4 matches rhino.compute's default --childcount; tune to the actual VM.
+		computeMaxConcurrentSolves: readPositiveInt(env, 'COMPUTE_MAX_CONCURRENT', 4),
+		// Both 0 (unbounded / no deadline) by default — nothing sheds until an
+		// operator who's measured their pool opts in. readNonNegativeInt so `0` is a
+		// valid "disabled" value, not treated as invalid.
+		computeMaxQueueDepth: readNonNegativeInt(env, 'COMPUTE_MAX_QUEUE_DEPTH', 0),
+		computeQueueWaitMs: readNonNegativeInt(env, 'COMPUTE_QUEUE_WAIT_MS', 0),
+		// Env is MB; 0 disables. Default 256 MB holds a handful of typical
+		// definitions warm without pinning gigabytes. readNonNegativeInt so `0`
+		// (disable) is honored rather than treated as invalid.
+		computeDefinitionByteCacheBytes:
+			readNonNegativeInt(env, 'COMPUTE_DEFINITION_BYTE_CACHE_MB', 256) * MB,
+		// L2 durable solve cache (H1). Default per-definition quota 0 = inherit-to-off
+		// until an operator opts in; the memory backend also only mounts under
+		// SOLVE_CACHE_PROVIDER=memory, so nothing caches by accident. Byte backstop
+		// 512 MB caps total heap use across all definitions (env is MB).
+		solveCacheDefaultMaxEntries: readNonNegativeInt(env, 'SOLVE_CACHE_DEFAULT_MAX_ENTRIES', 0),
+		solveCacheMaxTotalBytes: readNonNegativeInt(env, 'SOLVE_CACHE_MAX_TOTAL_MB', 512) * MB
 	};
 }

package/src/compute/rate-limit.ts

@@ -18,6 +18,10 @@
  *
  * The window + cap are injected (they live in `ComputeLimits`), so this module
  * reads no env of its own.
+ *
+ * Not compute-only despite the name: `peek` + `clear` make it usable for
+ * failure-counting flows too (login limiting keys by IP, records only failed
+ * attempts via `check`, and forgives on success via `clear`).
  */
 
 export interface RateLimitResult {
@@ -39,6 +43,14 @@ export interface ComputeRateLimiter {
 	 * Returns `{ allowed: false, retryAfter }` once the bucket is full.
 	 */
 	check(key: string): RateLimitResult;
+	/**
+	 * Check WITHOUT recording. For flows that only count selected outcomes —
+	 * e.g. login limiting, where `peek` gates the attempt and `check` records
+	 * only failures (a success calls `clear` instead).
+	 */
+	peek(key: string): RateLimitResult;
+	/** Drop `key`'s bucket — e.g. a successful login forgives prior failures. */
+	clear(key: string): void;
 	/** Test seam — wipes in-memory state. Production code never calls this. */
 	reset(): void;
 	/** The resolved config, exposed for time-based test assertions. */
@@ -76,6 +88,21 @@ export function createComputeRateLimiter(config: ComputeRateLimiterConfig): Comp
 			entry.count += 1;
 			return { allowed: true };
 		},
+		peek(key: string): RateLimitResult {
+			const now = Date.now();
+			const entry = buckets.get(key);
+
+			if (!entry || now > entry.resetAt) {
+				return { allowed: true };
+			}
+			if (entry.count >= maxPerWindow) {
+				return { allowed: false, retryAfter: Math.ceil((entry.resetAt - now) / 1000) };
+			}
+			return { allowed: true };
+		},
+		clear(key: string): void {
+			buckets.delete(key);
+		},
 		reset(): void {
 			buckets.clear();
 		}

package/src/compute/solve-cache-envelope.ts

@@ -0,0 +1,98 @@
+/**
+ * L2 cache entry format (R6). An entry is the gzipped response body plus a tiny
+ * metadata header, so a hit is near-CPU-free: no `JSON.stringify`, no re-solve —
+ * gzip clients get the stored bytes verbatim, and the header carries just enough
+ * to rebuild the `ok` outcome (error/warning counts for the metric, uncompressed
+ * length for the `Content-Length` on a gunzip fallback).
+ *
+ * Wire layout (opaque to the `ISolveResultCache` backend, which sees only bytes):
+ *
+ *   [ 4 bytes: header length N, big-endian uint32 ]
+ *   [ N bytes: UTF-8 JSON EnvelopeHeader ]
+ *   [ rest:    gzipped JSON response body ]
+ *
+ * The `algo` echo (M3) is already stripped at the source in the package's
+ * `runSolve`, so the body never carries the base64 definition — entries stay
+ * small without a strip step here.
+ */
+
+import { gunzipSync } from 'node:zlib';
+
+/** Metadata stored beside the gzipped body. Small; parsed on every hit. */
+export interface EnvelopeHeader {
+	/** Grasshopper runtime error count, for the solve metric. */
+	errorCount: number;
+	/** Grasshopper runtime warning count, for the solve metric. */
+	warningCount: number;
+	/** Uncompressed JSON body length in bytes (Content-Length for a gunzip fallback). */
+	serializedBytes: number;
+	/**
+	 * SHA-256 hex of the canonical input preimage (H2 defense-in-depth). A hit
+	 * verifies this equals the requesting key's hash before serving — a wide-hash
+	 * collision that produced the same storage key still can't serve the wrong
+	 * geometry.
+	 */
+	inputHash: string;
+}
+
+/**
+ * Encode a cache entry from the gzipped body + header. The body MUST already be
+ * gzipped (the pipeline gzips before storing so every hit serves compressed
+ * bytes; a rare non-gzip client gunzips on read).
+ */
+export function encodeSolveCacheEntry(header: EnvelopeHeader, gzippedBody: Uint8Array): Uint8Array {
+	const headerJson = Buffer.from(JSON.stringify(header), 'utf8');
+	const out = Buffer.allocUnsafe(4 + headerJson.byteLength + gzippedBody.byteLength);
+	out.writeUInt32BE(headerJson.byteLength, 0);
+	headerJson.copy(out, 4);
+	Buffer.from(gzippedBody.buffer, gzippedBody.byteOffset, gzippedBody.byteLength).copy(
+		out,
+		4 + headerJson.byteLength
+	);
+	return out;
+}
+
+/** A decoded entry: the parsed header + the still-gzipped body slice. */
+export interface DecodedSolveCacheEntry {
+	header: EnvelopeHeader;
+	gzippedBody: Uint8Array;
+}
+
+/**
+ * Decode a cache entry. Returns `null` on any malformed input (truncated, bad
+ * length prefix, non-JSON header) — a corrupt entry is treated as a miss, never
+ * an error, matching the best-effort cache contract.
+ */
+export function decodeSolveCacheEntry(bytes: Uint8Array): DecodedSolveCacheEntry | null {
+	if (bytes.byteLength < 4) return null;
+	const buf = Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+	const headerLen = buf.readUInt32BE(0);
+	const headerEnd = 4 + headerLen;
+	if (headerEnd > buf.byteLength) return null;
+	let header: EnvelopeHeader;
+	try {
+		header = JSON.parse(buf.toString('utf8', 4, headerEnd)) as EnvelopeHeader;
+	} catch {
+		return null;
+	}
+	if (
+		typeof header?.errorCount !== 'number' ||
+		typeof header?.warningCount !== 'number' ||
+		typeof header?.serializedBytes !== 'number' ||
+		typeof header?.inputHash !== 'string'
+	) {
+		return null;
+	}
+	// Slice (view, no copy) of the gzipped remainder.
+	const gzippedBody = new Uint8Array(
+		bytes.buffer,
+		bytes.byteOffset + headerEnd,
+		bytes.byteLength - headerEnd
+	);
+	return { header, gzippedBody };
+}
+
+/** Gunzip a stored body back to the JSON string, for a non-gzip client (rare). */
+export function gunzipEntryBody(gzippedBody: Uint8Array): string {
+	return gunzipSync(gzippedBody).toString('utf8');
+}

package/src/compute/solve-cache-key.ts

@@ -0,0 +1,85 @@
+/**
+ * Durable L2 cache-key derivation (H2 / R8 / R13).
+ *
+ * The in-process L1 cache keys on a 32-bit FNV hash — fine for a 20-entry Map,
+ * unsafe for a durable, cross-user cache where a collision serves user A's
+ * geometry to user B (CONTEXT.md L92–97 records exactly this bug shipping once).
+ * So the L2 key is a wide SHA-256 hash, and the entry stores the canonical
+ * preimage so a hit can compare it byte-for-byte (defense-in-depth).
+ *
+ * What goes into the key:
+ *   - The **transformed** input tree (R13) — the exact tree handed to the
+ *     scheduler, canonicalized with the package's exported `stableStringify` so
+ *     the L2 key parity-matches the L1 canonicalization path.
+ *   - A **config subset** (R8): everything OTHER than definition+inputs that
+ *     changes a solve's result — model units, tolerances, `dataversion`, the
+ *     compute contract version, and (when known) the Rhino server identity. A
+ *     durable key of `(versionId, inputHash)` alone would collide across
+ *     differing server configs or Rhino versions.
+ *
+ * `versionId`, `definitionId`, and `orgId` are NOT hashed in here — they're
+ * separate parts of the {@link SolveCacheKey} tuple so the backend can scope its
+ * keyspace (per-definition quota, per-org isolation) without unpacking the hash.
+ */
+
+import { createHash } from 'node:crypto';
+import { stableStringify } from '@selvajs/compute';
+import { COMPUTE_CONTRACT_VERSION } from './solve-pipeline.js';
+
+/**
+ * Solve-affecting configuration folded into the key alongside the input tree.
+ * Every field here is something that, if it changed, would legitimately change
+ * the solve output for the SAME definition + inputs. Assemble it from the app's
+ * resolved solve config; unset fields are simply absent from the canonical form.
+ */
+export interface SolveCacheConfigSubset {
+	/** Rhino model unit system, if the app pins one (else the definition/server default). */
+	modelUnits?: string;
+	/** Absolute tolerance, if pinned. */
+	absoluteTolerance?: number;
+	/** Angle tolerance, if pinned. */
+	angleTolerance?: number;
+	/** Grasshopper `dataversion` / data-tree schema version, if pinned. */
+	dataVersion?: number | string;
+	/**
+	 * Compute-server identity (id or URL). Folds in because two servers can run
+	 * different Rhino/plugin versions that yield different geometry for the same
+	 * inputs. Optional — omit for a single-pool deployment where it's constant.
+	 */
+	computeServerId?: string;
+}
+
+/** The canonical preimage + its SHA-256 digest. Store both in the L2 entry header. */
+export interface SolveCacheInputKey {
+	/** The canonical string that was hashed (for hit-time byte comparison). */
+	canonical: string;
+	/** SHA-256 hex of {@link canonical} — the `inputKey` part of the storage key. */
+	hash: string;
+}
+
+/**
+ * Derive the durable `inputKey` from the transformed input tree and the solve
+ * config subset. Deterministic and stable across processes/instances: the same
+ * tree + config always produce the same hash, which is what lets a shared cache
+ * hit across app instances.
+ *
+ * @param transformedTree the tree AFTER `transformInputParameter`/`TreeBuilder`
+ *   (R13) — the exact object handed to `scheduler.solve`.
+ * @param config solve-affecting config (R8); `COMPUTE_CONTRACT_VERSION` is folded
+ *   in automatically so a wire-contract bump invalidates old entries for free.
+ */
+export function deriveSolveCacheInputKey(
+	transformedTree: unknown,
+	config: SolveCacheConfigSubset
+): SolveCacheInputKey {
+	// stableStringify sorts keys deterministically — same content, same string,
+	// regardless of property insertion order. Tag each part so a value can't shift
+	// across the tree/config boundary and collide (e.g. tree "]" meeting config "[").
+	const canonical = stableStringify({
+		v: COMPUTE_CONTRACT_VERSION,
+		tree: transformedTree,
+		config
+	});
+	const hash = createHash('sha256').update(canonical).digest('hex');
+	return { canonical, hash };
+}

package/src/compute/solve-cache-single-flight.ts

@@ -0,0 +1,59 @@
+/**
+ * In-process single-flight (R4) — dogpile protection above the L2 cache.
+ *
+ * N identical live solves arriving while the first is still running would each
+ * enqueue and each hit Rhino (the scheduler has no in-flight coalescing, and
+ * Rhino's `cachesolve` still costs a round trip per repeat). The classic cold-key
+ * stampede: a hot public definition + a deploy = a thundering herd onto compute.
+ *
+ * This coalesces them: the first caller for a key runs the work; concurrent
+ * callers for the SAME key await the same promise and share its result. Once the
+ * work settles (resolve OR reject), the key is released so the next request runs
+ * fresh — the map never retains a settled entry, so it can't serve a stale
+ * result or leak memory.
+ *
+ * It sits ABOVE the `ISolveResultCache` interface (in-process, per app instance).
+ * A cross-instance lease (Redis `SET NX`) is a later backend capability; this is
+ * the free first slice that covers the common same-instance burst.
+ *
+ * Correctness note: the shared promise resolves to ONE value for all waiters, so
+ * the wrapped work must return an immutable / independently-serializable result
+ * (the solve pipeline returns a fresh envelope object — safe to share by
+ * reference here because the app serializes it per response).
+ */
+
+export interface SolveCacheSingleFlight {
+	/**
+	 * Run `work` under `key`, coalescing concurrent identical calls. The first
+	 * caller executes; overlapping callers for the same key await the same promise.
+	 * The key is freed as soon as the promise settles (success or failure).
+	 */
+	run<T>(key: string, work: () => Promise<T>): Promise<T>;
+	/** Number of keys currently in flight (observability / tests). */
+	inFlight(): number;
+}
+
+export function createSolveCacheSingleFlight(): SolveCacheSingleFlight {
+	const inflight = new Map<string, Promise<unknown>>();
+
+	return {
+		run<T>(key: string, work: () => Promise<T>): Promise<T> {
+			const existing = inflight.get(key);
+			if (existing) return existing as Promise<T>;
+
+			// `.finally` releases the key on both settle paths. Start the work inside
+			// the promise chain so a synchronous throw in `work` still rejects the
+			// shared promise (and still frees the key) rather than escaping.
+			const p = (async () => work())().finally(() => {
+				// Only delete if it's still OUR promise — a key freed and re-taken by a
+				// later caller must not be clobbered.
+				if (inflight.get(key) === p) inflight.delete(key);
+			});
+			inflight.set(key, p);
+			return p;
+		},
+		inFlight(): number {
+			return inflight.size;
+		}
+	};
+}