@selvajs/server 0.2.0-beta.1 → 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
@@ -49,8 +93,8 @@ function fakeClient(solve: SolveStub): CachedClient {
 	return {
 		client: {} as GrasshopperClient,
 		scheduler: { solve } as unknown as SolveScheduler,
-		rhinoTiming: { last: null },
-		solveMeta: { last: null }
+		rhinoTiming: { last: null, seq: 0 },
+		solveMeta: { last: null, seq: 0 }
 	};
 }
 
@@ -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', () => {
@@ -246,11 +368,15 @@ describe('runSolvePipeline — Server-Timing', () => {
 	});
 
 	it('splits solve into rhino_* + compute_link when the client reported server timing', async () => {
-		// The real onServerTiming callback fires DURING the solve, after the
-		// pipeline has reset the holder — so populate it inside the solve stub, not
-		// before the call (which the pipeline's pre-solve reset would wipe).
+		// The real callbacks fire DURING the solve: onServerTiming per compute
+		// call, onSettle per settle — each bumps its seq. Mimic both so the
+		// pipeline's attribution guard (exactly one write since the snapshot,
+		// settle not fromCache) sees this request's own telemetry.
 		const client: CachedClient = fakeClient(async () => {
+			client.rhinoTiming.seq += 1;
 			client.rhinoTiming.last = { decode: 5, solve: 20, encode: 3 };
+			client.solveMeta.seq += 1;
+			client.solveMeta.last = { fromCache: false, definitionReuploaded: false };
 			return { errors: [], warnings: [] };
 		});
 		const outcome = await runSolvePipeline(baseArgs({ client }));
@@ -264,9 +390,8 @@ describe('runSolvePipeline — Server-Timing', () => {
 	});
 
 	it('surfaces selva_cache + def_reupload verdicts as 0/1 flags', async () => {
-		// Populate during the solve (the onSettle callback's real timing), not
-		// before — the pipeline resets solveMeta before it runs.
 		const client: CachedClient = fakeClient(async () => {
+			client.solveMeta.seq += 1;
 			client.solveMeta.last = { fromCache: true, definitionReuploaded: false };
 			return { errors: [], warnings: [] };
 		});
@@ -278,17 +403,258 @@ describe('runSolvePipeline — Server-Timing', () => {
 		expect(st).toContain('def_reupload;dur=0');
 	});
 
-	it('resets stale telemetry holders before solving', async () => {
-		// A warm client carrying a previous request's timing must not leak it into
-		// this solve's Server-Timing when the current solve reports nothing.
+	it('does not attribute stale telemetry a previous request left on the warm client', async () => {
+		// The holders are shared per-server. Data written before this solve's
+		// snapshot (seq unchanged during the solve) must not leak into this
+		// request's Server-Timing.
 		const client = fakeClient(async () => ({ errors: [], warnings: [] }));
-		client.rhinoTiming.last = { decode: 99, solve: 99, encode: 99 };
-		client.solveMeta.last = { fromCache: true };
+		client.rhinoTiming = { last: { decode: 99, solve: 99, encode: 99 }, seq: 3 };
+		client.solveMeta = { last: { fromCache: true }, seq: 5 };
 		const outcome = await runSolvePipeline(baseArgs({ client }));
 		expect(outcome.kind).toBe('ok');
 		if (outcome.kind !== 'ok') return;
-		// Holders were reset to null before solve; the stub never repopulated them.
 		expect(outcome.envelope.headers['Server-Timing']).not.toContain('rhino_decode');
 		expect(outcome.envelope.headers['Server-Timing']).not.toContain('selva_cache');
 	});
+
+	it('drops telemetry when a concurrent request also settled in the window (audit B6)', async () => {
+		// With maxConcurrentSolves > 1 two solves can interleave. More than one
+		// settle since this request's snapshot makes the shared slots ambiguous —
+		// the pipeline must omit the segments rather than report another
+		// request's cache verdict / rhino timing as ours.
+		const client: CachedClient = fakeClient(async () => {
+			// Our own solve's callbacks…
+			client.rhinoTiming.seq += 1;
+			client.rhinoTiming.last = { decode: 5, solve: 20, encode: 3 };
+			client.solveMeta.seq += 1;
+			client.solveMeta.last = { fromCache: false, definitionReuploaded: false };
+			// …then a concurrent request settles before we read.
+			client.rhinoTiming.seq += 1;
+			client.rhinoTiming.last = { decode: 1, solve: 1, encode: 1 };
+			client.solveMeta.seq += 1;
+			client.solveMeta.last = { fromCache: true };
+			return { errors: [], warnings: [] };
+		});
+		const outcome = await runSolvePipeline(baseArgs({ client }));
+		expect(outcome.kind).toBe('ok');
+		if (outcome.kind !== 'ok') return;
+		const st = outcome.envelope.headers['Server-Timing'];
+		expect(st).not.toContain('selva_cache');
+		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.
+		const client: CachedClient = fakeClient(async () => {
+			client.rhinoTiming.seq += 1; // the OTHER request's compute call
+			client.rhinoTiming.last = { decode: 7, solve: 70, encode: 7 };
+			client.solveMeta.seq += 1; // our own settle — a cache hit
+			client.solveMeta.last = { fromCache: true };
+			return { errors: [], warnings: [] };
+		});
+		const outcome = await runSolvePipeline(baseArgs({ client }));
+		expect(outcome.kind).toBe('ok');
+		if (outcome.kind !== 'ok') return;
+		const st = outcome.envelope.headers['Server-Timing'];
+		expect(st).toContain('selva_cache;dur=1');
+		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/__tests__/transform-input.test.ts

@@ -59,11 +59,18 @@ describe('transformInputParameter — number / integer', () => {
 		expect(out.default).toBe(3);
 	});
 
-	it('forces stepSize to 1 for integers', () => {
+	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 });
 	});
 });

package/src/compute/client-cache.ts

@@ -59,21 +59,28 @@ export interface CachedClient {
 	client: GrasshopperClient;
 	scheduler: SolveScheduler;
 	/**
-	 * Last decode/solve/encode reported by the compute server (Server-Timing).
-	 * Written by onServerTiming, read right after scheduler.solve resolves to split
-	 * the solve wall time into on-compute-server work vs. the compute↔web-server
-	 * link. Queue-mode schedulers serialize solves, so this correlates with the
-	 * request that just resolved; a Selva-cache hit leaves it null (no compute
-	 * call). Debug aid — a concurrent burst may misattribute one request's timing.
+	 * 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 };
+	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. Same read-after-solve pattern and
-	 * concurrency caveat as rhinoTiming.
+	 * 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 };
+	solveMeta: {
+		last: { fromCache: boolean; definitionReuploaded?: boolean } | null;
+		seq: number;
+	};
 }
 
 /**
@@ -90,6 +97,24 @@ export interface ClientCacheConfig {
 	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). */
@@ -136,9 +161,10 @@ export function createClientCache(config: ClientCacheConfig): ClientCache {
 
 	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.
-		const rhinoTiming: CachedClient['rhinoTiming'] = { last: null };
-		const solveMeta: CachedClient['solveMeta'] = { last: null };
+		// 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,
@@ -160,6 +186,7 @@ export function createClientCache(config: ClientCacheConfig): ClientCache {
 				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
@@ -189,6 +216,15 @@ export function createClientCache(config: ClientCacheConfig): ClientCache {
 		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
@@ -199,6 +235,9 @@ export function createClientCache(config: ClientCacheConfig): ClientCache {
 			// 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 = {
@@ -219,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])}`
 						);
 					}
 				}