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

package/src/compute/__tests__/transform-input.test.ts

@@ -1,162 +0,0 @@
-/**
- * Tests for `transformInputParameter` — the adapter that turns a persisted `SchemaInput`
- * (plus the user's chosen value) into the `@selvajs/compute` `InputParam` that
- * `TreeBuilder.fromInputParams` serializes for the solve.
- *
- * The adapter delegates to the package's `processInput`, so these assert the
- * package-aligned behavior: correct `paramType` for every type (not the old
- * coerce-everything-to-Text), and `default` carrying the user's value. Where a value/
- * default is absent, `processInput` leaves `default` undefined and `fromInputParams`
- * omits the input entirely — letting Grasshopper use its own internal default rather
- * than forcing `''`/`false`.
- */
-
-import { describe, it, expect } from 'vitest';
-import { transformInputParameter } from '../transform-input.js';
-import type { SchemaInput } from '@selvajs/schemas';
-
-type Input = SchemaInput & { minimum?: number; maximum?: number; stepSize?: number };
-
-function input(partial: Partial<Input>): Input {
-	return {
-		id: 'id-1',
-		nickname: 'Param',
-		paramType: 'text',
-		...partial
-	} as Input;
-}
-
-describe('transformInputParameter — identity fields', () => {
-	it('carries id, name, nickname, description through', () => {
-		const out = transformInputParameter(
-			input({ id: 'guid-x', nickname: 'Width', description: 'the width' }),
-			5
-		);
-		expect(out.id).toBe('guid-x');
-		expect(out.name).toBe('Width');
-		expect(out.nickname).toBe('Width');
-		expect(out.description).toBe('the width');
-	});
-
-	it('defaults a blank nickname to null and an absent description to empty string', () => {
-		const out = transformInputParameter(input({ nickname: '', description: undefined }), 'v');
-		expect(out.nickname).toBeNull();
-		expect(out.description).toBe('');
-	});
-});
-
-describe('transformInputParameter — number / integer', () => {
-	it('maps number with the user value winning over the schema default', () => {
-		const out = transformInputParameter(
-			input({ paramType: 'number', default: 1, minimum: 0, maximum: 10, stepSize: 0.5 }),
-			7
-		);
-		expect(out).toMatchObject({ paramType: 'Number', default: 7, minimum: 0, maximum: 10 });
-	});
-
-	it('falls back to the schema default when no value is supplied', () => {
-		const out = transformInputParameter(input({ paramType: 'number', default: 3 }), undefined);
-		expect(out.default).toBe(3);
-	});
-
-	it('honors a schema-authored stepSize verbatim for integers (compute ≥3.1.0-beta.5)', () => {
-		// The package used to force integer stepSize to 1; since beta.5 a
-		// server-authored stepSize wins and the 1-heuristic is only the fallback.
-		const out = transformInputParameter(
-			input({ paramType: 'integer', stepSize: 0.5, default: 2 }),
-			4
-		);
-		expect(out).toMatchObject({ paramType: 'Integer', stepSize: 0.5, default: 4 });
-	});
-
-	it('falls back to stepSize 1 for integers without an authored stepSize', () => {
-		const out = transformInputParameter(input({ paramType: 'integer', default: 2 }), 4);
-		expect(out).toMatchObject({ paramType: 'Integer', stepSize: 1, default: 4 });
-	});
-});
-
-describe('transformInputParameter — text', () => {
-	it('maps text and keeps the user value', () => {
-		const out = transformInputParameter(input({ paramType: 'text', default: 'd' }), 'hello');
-		expect(out).toMatchObject({ paramType: 'Text', default: 'hello' });
-	});
-
-	it('falls back to the schema default when no value is supplied', () => {
-		expect(
-			transformInputParameter(input({ paramType: 'text', default: 'd' }), undefined).default
-		).toBe('d');
-	});
-
-	it('leaves default undefined when neither value nor schema default exist (input is then omitted)', () => {
-		// processInput does not force ''. fromInputParams filters undefined defaults, so the
-		// param is simply not sent and Grasshopper uses its own internal default.
-		expect(
-			transformInputParameter(input({ paramType: 'text', default: undefined }), undefined).default
-		).toBeUndefined();
-	});
-});
-
-describe('transformInputParameter — boolean', () => {
-	it('maps boolean and preserves an explicit false (the bug-prone case)', () => {
-		const out = transformInputParameter(input({ paramType: 'boolean', default: true }), false);
-		expect(out).toMatchObject({ paramType: 'Boolean', default: false });
-	});
-
-	it('falls back to the schema default when no value is supplied', () => {
-		expect(
-			transformInputParameter(input({ paramType: 'boolean', default: true }), undefined).default
-		).toBe(true);
-	});
-
-	it('leaves default undefined when neither value nor schema default exist (input is then omitted)', () => {
-		expect(
-			transformInputParameter(input({ paramType: 'boolean', default: undefined }), undefined)
-				.default
-		).toBeUndefined();
-	});
-});
-
-describe('transformInputParameter — value-list / file / color / generic', () => {
-	// The regression that motivated the swap: these used to be silently coerced to Text.
-	// processInput now types them correctly. (The options map for ValueList isn't carried
-	// on SchemaInput, so `values` is empty and the selected value rides on `default` —
-	// which is exactly the string a contextual ValueList param consumes.)
-	it('maps valueList to ValueList, carrying the selected value', () => {
-		const out = transformInputParameter(input({ paramType: 'valueList', default: '0' }), '1');
-		expect(out).toMatchObject({ paramType: 'ValueList', default: '1' });
-	});
-
-	// Regression: processInput has no dynamicValueList handler, so without the explicit
-	// mapping it fell to the Geometry fallback with a null default — and fromInputParams
-	// then DROPPED the input, so the user's selection never reached the definition.
-	// The plugin's GetDynamicValueListParameter reuses the ValueList wire contract
-	// (TypeName "ValueList"), so ValueList is the correct target type.
-	it('maps dynamicValueList to ValueList, carrying the selected value', () => {
-		const out = transformInputParameter(
-			input({ paramType: 'dynamicValueList', default: '0' }),
-			'3.5'
-		);
-		expect(out).toMatchObject({ paramType: 'ValueList', default: '3.5' });
-	});
-
-	it('maps dynamicValueList checklist (array value) to ValueList, carrying all selections', () => {
-		const out = transformInputParameter(input({ paramType: 'dynamicValueList' }), ['a', 'b']);
-		expect(out.paramType).toBe('ValueList');
-		expect(out.default).toEqual(['a', 'b']);
-	});
-
-	it('maps file to File', () => {
-		const out = transformInputParameter(input({ paramType: 'file' }), { fileName: 'a.3dm' });
-		expect(out.paramType).toBe('File');
-	});
-
-	it('maps color to Color, carrying the value', () => {
-		const out = transformInputParameter(input({ paramType: 'color' }), '255,0,0');
-		expect(out).toMatchObject({ paramType: 'Color', default: '255,0,0' });
-	});
-
-	it('maps generic to the package fallback type (Geometry), not Text', () => {
-		const out = transformInputParameter(input({ paramType: 'generic', default: 'd' }), undefined);
-		expect(out.paramType).toBe('Geometry');
-	});
-});

package/src/compute/client-cache.ts

@@ -1,321 +0,0 @@
-import {
-	GrasshopperClient,
-	enableDebugLogging,
-	type GrasshopperComputeConfig,
-	type SolveScheduler
-} from '@selvajs/compute';
-
-// ============================================================================
-// Shared compute client cache
-// ============================================================================
-//
-// One warm `GrasshopperClient` (+ its `SolveScheduler`) per distinct compute
-// server, keyed by the server's **`id`** (ADR 0004 — a server's identity is its
-// `id`, never its URL). Definitions can pin different servers (the app's
-// `resolveServerForOrg` honors a per-definition pin → org default → global
-// default), so this is deliberately a per-server LRU, NOT a single shared
-// client — two definitions on two servers keep two warm clients; a churn of
-// one-off servers is bounded by `maxCachedClients`.
-//
-// Both hot paths share this cache:
-//   - the solve endpoint uses the entry's `scheduler`;
-//   - the definition-viewer render path uses the entry's `client` for `getIO`.
-// Sharing means a definition that was just solved renders from the same warm
-// client (and vice-versa) instead of re-handshaking Rhino.Compute per page load.
-//
-// Staleness: keyed on `id`, a rotated URL/apiKey keeps the SAME key with stale
-// connection details — so the config-write path MUST call `evict(id)` when a
-// server's config changes (ADR 0004 Consequences). That replaces the old
-// implicit "new key → LRU age-out" staleness the URL-keyed cache relied on.
-
-/**
- * Opaque identity of a compute server. Callers never construct the branded
- * string directly — they pass a resolved server config to `serverIdentity()`.
- * Keeping this opaque from day one (ADR 0004 D1) means "a server is now a pool
- * of URLs behind one id" stays an additive, non-breaking change.
- */
-export type ServerIdentity = string & { readonly __brand: 'ServerIdentity' };
-
-/** Minimal resolved-server shape the cache needs (a subset of the app's `ComputeServerConfig`). */
-export interface ResolvedServer {
-	/** Stable identity — the cache key. */
-	id: string;
-	/** Base URL of the Rhino.Compute instance (a resolution detail of `id`). */
-	serverUrl: string;
-	/** Sent as `RhinoComputeKey`. */
-	apiKey?: string;
-}
-
-/** Derive the opaque cache identity from a resolved server. Identity is the `id`. */
-export function serverIdentity(server: Pick<ResolvedServer, 'id'>): ServerIdentity {
-	return server.id as ServerIdentity;
-}
-
-/**
- * Per-request telemetry holders read by the caller right after a solve resolves
- * to build a Server-Timing header. Populated by the client/scheduler callbacks.
- */
-export interface CachedClient {
-	client: GrasshopperClient;
-	scheduler: SolveScheduler;
-	/**
-	 * Last decode/solve/encode reported by the compute server (Server-Timing),
-	 * written by onServerTiming. `seq` increments on every write. The scheduler
-	 * runs up to `maxConcurrentSolves` solves at once, so `last` alone can't be
-	 * trusted per-request: callers snapshot `seq` before their solve and
-	 * attribute `last` only when exactly one write happened since (necessarily
-	 * theirs — see the guard in `runSolvePipeline`), dropping the segment
-	 * otherwise instead of misattributing another request's timing.
-	 */
-	rhinoTiming: { last: { decode: number; solve: number; encode: number } | null; seq: number };
-	/**
-	 * Last solve's cache verdicts from the scheduler's onSettle: whether the
-	 * in-process response cache served it (no compute call) and whether the
-	 * definition had to be re-uploaded. `seq` increments on EVERY settle
-	 * (success or error); `last` is only written on success. Same
-	 * snapshot-and-attribute pattern as rhinoTiming — onSettle always fires
-	 * before the corresponding `scheduler.solve()` promise resolves, so at the
-	 * caller's read point its own settle is included in `seq`.
-	 */
-	solveMeta: {
-		last: { fromCache: boolean; definitionReuploaded?: boolean } | null;
-		seq: number;
-	};
-}
-
-/**
- * Config injected by the consuming app. Everything that used to be read from
- * `$env` / `computeLimits` in the app module is passed in, so this module stays
- * env-agnostic and testable.
- */
-export interface ClientCacheConfig {
-	/** Per-solve timeout forwarded to the scheduler (`ComputeLimits.maxSolveDurationMs`). */
-	maxSolveDurationMs: number;
-	/** Ask Rhino.Compute to cache solve results and return them on identical repeats. */
-	cachesolve: boolean;
-	/** Also cache solves that reported GH errors (only meaningful with `cachesolve`). */
-	cacheerroredsolves: boolean;
-	/** Reference large definitions by server cache key (pointer) instead of re-uploading. */
-	reuseServerDefinitionCache: boolean;
-	/**
-	 * Max in-flight solves per compute server (scheduler `maxConcurrent`; excess
-	 * FIFO-queues). Size to the server's `compute.geometry` child count
-	 * (`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). */
-	debugVerbose: boolean;
-	/** Max distinct warm clients before the LRU evicts the oldest. Default 16. */
-	maxCachedClients?: number;
-	/** Sink for the concise debug lines (the app wires `console.log`). */
-	onDebugLog?: (message: string) => void;
-}
-
-export interface ClientCache {
-	/**
-	 * Get (or create) the warm client + scheduler for a resolved compute server,
-	 * keyed by its `id`. `definitionGuid`, when present, is stamped as the
-	 * `X-Selva-Definition` header on this client's outbound solve/IO requests —
-	 * inert routing/telemetry metadata until a pool router exists (ADR 0004 D2).
-	 */
-	getClient(server: ResolvedServer, opts?: { definitionGuid?: string }): Promise<CachedClient>;
-	/**
-	 * Dispose and drop the warm client for `id` (or a `ServerIdentity`). Called by
-	 * the config-write path when a server's URL/key rotates so the next request
-	 * rebuilds against fresh connection details (ADR 0004 Consequences).
-	 */
-	evict(id: string | ServerIdentity): void;
-	/** Dispose every warm client. Test seam / shutdown hook. */
-	disposeAll(): void;
-}
-
-const DEFAULT_MAX_CACHED_CLIENTS = 16;
-
-/**
- * Build a per-server warm-client cache. Each cache owns its own LRU `Map` keyed
- * on server `id`.
- */
-export function createClientCache(config: ClientCacheConfig): ClientCache {
-	const maxCachedClients = config.maxCachedClients ?? DEFAULT_MAX_CACHED_CLIENTS;
-	const cache = new Map<string, CachedClient>();
-
-	if (config.debugVerbose) enableDebugLogging();
-
-	const debugLog = (message: string) => {
-		if (config.debug) config.onDebugLog?.(message);
-	};
-
-	async function build(server: ResolvedServer, definitionGuid?: string): Promise<CachedClient> {
-		// Holders for per-request results from the client/scheduler callbacks; the
-		// caller reads them right after each solve resolves to build Server-Timing,
-		// using the seq counters to detect (and drop) ambiguous concurrent writes.
-		const rhinoTiming: CachedClient['rhinoTiming'] = { last: null, seq: 0 };
-		const solveMeta: CachedClient['solveMeta'] = { last: null, seq: 0 };
-
-		const clientConfig: GrasshopperComputeConfig = {
-			serverUrl: server.serverUrl,
-			apiKey: server.apiKey,
-			// Lib-level debug is the verbose one (full payload logs); keep it on the
-			// verbose flag so the concise cache logs can run without the noise.
-			debug: config.debugVerbose,
-			// Ask Rhino.Compute to cache solve results and return them on identical
-			// repeats (same definition + inputs), skipping the solve.
-			cachesolve: config.cachesolve,
-			// Opt-in: also cache solves that reported GH errors.
-			cacheerroredsolves: config.cacheerroredsolves,
-			// DEBUG: the server's per-request timing breakdown, which exposes the two
-			// SERVER-side caches at once — definition cache (pointer reuse) via
-			// `decode`, solve cache (cachesolve) via `solve`. Flagged below so the
-			// contrast is obvious in the logs.
-			onServerTiming: (t) => {
-				const decode = t.decode ?? 0;
-				const solve = t.solve ?? 0;
-				const encode = t.encode ?? 0;
-				// Always recorded (cheap): the caller reads this after scheduler.solve.
-				rhinoTiming.seq += 1;
-				rhinoTiming.last = { decode, solve, encode };
-				if (!config.debug) return;
-				// Heuristic thresholds: a genuine parse/solve is many ms; a cache hit
-				// is sub-millisecond. Only meaningful relative to the first (cold) solve.
-				const defCache =
-					decode <= 1 ? 'HIT (definition reused, no re-upload/parse)' : 'miss (full parse)';
-				const solveCache =
-					config.cachesolve && solve <= 1
-						? 'HIT (cached result, solve skipped)'
-						: config.cachesolve
-							? 'miss (solved fresh)'
-							: 'off';
-				debugLog(
-					`[Compute/rhino-cache] decode=${decode}ms solve=${solve}ms encode=${encode}ms ` +
-						`| definition-cache: ${defCache} | solve-cache (cachesolve): ${solveCache}`
-				);
-			}
-		};
-
-		// `X-Selva-Definition` on the wire (ADR 0004 D2). Baked at client-create
-		// time because the scheduler has no per-request header hook — inert for a
-		// single-member "pool", useful in compute-side access logs immediately.
-		if (definitionGuid) {
-			clientConfig.headers = { 'X-Selva-Definition': definitionGuid };
-		}
-
-		const client = await GrasshopperClient.create(clientConfig);
-		const scheduler = client.createScheduler({
-			mode: 'queue',
-			// Queue mode defaults maxConcurrent to 1, which would serialize every
-			// 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
-			// re-uploading the full binary every solve. On a stale-pointer miss the
-			// client transparently re-uploads.
-			reuseServerDefinitionCache: config.reuseServerDefinitionCache,
-			// DEBUG: observe the in-process response cache. `fromCache === true` means
-			// this solve was served from the app's own cache — Rhino.Compute was never
-			// called. `false` means it went to the compute server.
-			onSettle: (_ctx, result) => {
-				// Count EVERY settle (success or error) so the caller's attribution
-				// guard sees all concurrent activity, not just successful writes.
-				solveMeta.seq += 1;
-				if (result.status !== 'success') return;
-				// Always recorded (cheap): the caller surfaces these on Server-Timing.
-				solveMeta.last = {
-					fromCache: result.fromCache === true,
-					definitionReuploaded: result.definitionReuploaded
-				};
-				if (!config.debug) return;
-				debugLog(
-					`[Compute/selva-cache] ${result.fromCache ? 'HIT  — served from cache (no compute call)' : 'miss — went to Rhino.Compute'} (${Math.round(result.durationMs)}ms)`
-				);
-				// Definition-cache verdict for a real compute call (not a cache HIT).
-				if (!result.fromCache) {
-					debugLog(
-						result.definitionReuploaded === true
-							? '[Compute/def-cache] miss — definition RE-UPLOADED (pointer was cold/stale)'
-							: result.definitionReuploaded === false
-								? '[Compute/def-cache] HIT  — definition reused from server cache (no upload)'
-								: '[Compute/def-cache] n/a — reuse disabled or non-reusable definition'
-					);
-				}
-				// 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); ${cacheNote}. First: ${JSON.stringify((errs as unknown[])[0])}`
-						);
-					}
-				}
-			}
-		});
-		return { client, scheduler, rhinoTiming, solveMeta };
-	}
-
-	return {
-		async getClient(server, opts): Promise<CachedClient> {
-			const key = server.id;
-			const existing = cache.get(key);
-			if (existing) {
-				// Refresh LRU position.
-				cache.delete(key);
-				cache.set(key, existing);
-				return existing;
-			}
-
-			const entry = await build(server, opts?.definitionGuid);
-
-			// Evict the least-recently-used entry before inserting when at capacity.
-			if (cache.size >= maxCachedClients) {
-				const oldestKey = cache.keys().next().value;
-				if (oldestKey !== undefined) {
-					cache.get(oldestKey)?.scheduler.dispose();
-					cache.delete(oldestKey);
-				}
-			}
-
-			cache.set(key, entry);
-			return entry;
-		},
-
-		evict(id): void {
-			const key = id as string;
-			const entry = cache.get(key);
-			if (entry) {
-				entry.scheduler.dispose();
-				cache.delete(key);
-			}
-		},
-
-		disposeAll(): void {
-			for (const entry of cache.values()) entry.scheduler.dispose();
-			cache.clear();
-		}
-	};
-}

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

@@ -1,168 +0,0 @@
-/**
- * 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;
-		}
-	};
-}