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

package/src/compute/solve-pipeline.ts

@@ -20,11 +20,29 @@
  * see {@link COMPUTE_CONTRACT_VERSION} and {@link COMPUTE_VERSION_HEADER}.
  */
 
-import { TreeBuilder, type GrasshopperComputeResponse, type InputParam } from '@selvajs/compute';
+import {
+	ErrorCodes,
+	RhinoComputeError,
+	TreeBuilder,
+	type GrasshopperComputeResponse,
+	type InputParam,
+	type SolveDefinition
+} from '@selvajs/compute';
 import type { SchemaInput } from '@selvajs/schemas';
-import { gzipSync } from 'node:zlib';
+import { gzip } from 'node:zlib';
+import { promisify } from 'node:util';
 import { transformInputParameter } from './transform-input.js';
 import type { CachedClient } from './client-cache.js';
+import type { ByteRefOutcome } from './definition-byte-cache.js';
+import { deriveSolveCacheInputKey, type SolveCacheConfigSubset } from './solve-cache-key.js';
+import {
+	decodeSolveCacheEntry,
+	encodeSolveCacheEntry,
+	gunzipEntryBody
+} from './solve-cache-envelope.js';
+
+/** Async gzip (audit B8) — off the event loop, unlike the old `gzipSync`. */
+const gzipAsync = promisify(gzip);
 
 // ============================================================================
 // Wire contract version (audit D5)
@@ -53,8 +71,20 @@ export type PipelineInput = SchemaInput & {
 };
 
 export interface SolvePipelineArgs {
-	/** The `.gh` bytes to solve (stored blob or remote fetch — resolved by the caller). */
-	definitionSource: Uint8Array;
+	/**
+	 * The definition to solve. Either raw `.gh` bytes (remote fetch, or a caller
+	 * that resolved them eagerly) or a `DefinitionRef` — an identity-keyed lazy
+	 * loader (from the definition-byte cache) whose bytes the scheduler
+	 * materializes ONLY when an upload is unavoidable. A pointer-known solve of a
+	 * `DefinitionRef` moves zero bytes.
+	 */
+	definitionSource: SolveDefinition;
+	/**
+	 * When `definitionSource` is a byte-cache `DefinitionRef`, its mutable outcome
+	 * so the pipeline can emit the `def_bytes` Server-Timing verdict (skipped =
+	 * `load` never ran, hit = warm cache, miss = loader). Omit for raw-bytes solves.
+	 */
+	byteRefOutcome?: ByteRefOutcome;
 	/** Persisted input params; only those with a `paramType` are sent to the solve. */
 	inputs: PipelineInput[];
 	/** User-chosen values keyed by input id; missing keys fall back to the schema default. */
@@ -86,6 +116,31 @@ export interface SolvePipelineArgs {
 	 * Server-Timing entries. The caller assembles these; the pipeline only echoes.
 	 */
 	prepMarks?: [string, number][];
+	/**
+	 * Optional durable L2 solve cache (H1). Present ONLY for live-channel solves
+	 * whose definition has a caching quota > 0 — its presence IS the channel gate
+	 * (zero policy conditionals in the pipeline). When set, the pipeline derives
+	 * the wide input key from the transformed tree + `configSubset`, checks
+	 * `lookup` before solving (a hit skips compute entirely, returning the stored
+	 * gzipped envelope), and write-throughs `store` on a successful solve.
+	 */
+	solveCache?: SolvePipelineCacheHook;
+}
+
+/**
+ * The app-supplied L2 hook. The app binds `lookup`/`store` to the org/definition/
+ * version scope and the definition's quota; the pipeline supplies the SHA-256
+ * `inputKey` (derived from the transformed tree + `configSubset`) and the opaque
+ * encoded entry bytes. Both are best-effort — `lookup` may miss/throw (treated as
+ * a miss), `store` is fire-and-forget.
+ */
+export interface SolvePipelineCacheHook {
+	/** Solve-affecting config folded into the key (R8) — model units, tolerances, server id. */
+	configSubset: SolveCacheConfigSubset;
+	/** Fetch a stored entry for `inputKey`, or `null` on miss. Must not reject fatally. */
+	lookup(inputKey: string): Promise<Uint8Array | null>;
+	/** Store the encoded entry for `inputKey`. Fire-and-forget; best-effort. */
+	store(inputKey: string, entry: Uint8Array): void;
 }
 
 /** Phase timings the pipeline measured; the caller uses them for debug logging. */
@@ -99,6 +154,12 @@ export interface SolvePhaseMetrics {
 	serializedBytes: number;
 	/** Gzipped length in bytes, or null when compression was skipped. */
 	compressedBytes: number | null;
+	/**
+	 * L2 durable-cache verdict: `true` = served from L2 (no solve ran), `false` =
+	 * L2 consulted and missed (solved), `null` = L2 not consulted (no hook — draft
+	 * or caching off). Drives the `l2_cache` Server-Timing entry.
+	 */
+	l2CacheHit: boolean | null;
 }
 
 /** A ready-to-send response: body + headers + the solve result + phase metrics. */
@@ -109,8 +170,13 @@ export interface SolveEnvelope {
 	encoding?: 'gzip';
 	/** Fully-assembled response headers (Content-Type/-Length/-Encoding, Vary, Server-Timing, version). */
 	headers: Record<string, string>;
-	/** The solved definition — the caller reads `errors`/`warnings` for its metric record. */
-	result: GrasshopperComputeResponse;
+	/**
+	 * The solved definition object, present only on a fresh (non-L2) solve. Absent
+	 * on an L2 hit — the pipeline serves the stored gzipped body without ever
+	 * materializing the object. The caller reads `errorCount`/`warningCount` off
+	 * the `ok` outcome for its metric record, not this field.
+	 */
+	result?: GrasshopperComputeResponse;
 	/** Phase timings, for the caller's optional debug breakdown. */
 	metrics: SolvePhaseMetrics;
 }
@@ -118,9 +184,10 @@ export interface SolveEnvelope {
 /**
  * Discriminated result. `ok` carries the envelope; every other variant names an
  * expected failure the transport maps to a status code (the app route maps
- * timeout→504, client_abort→499, too_large→413; `compute_error` re-surfaces the
- * original error for the generic 500/503 path). `durationMs` on the error
- * variants is the solve wall time up to the failure, for the metric record.
+ * timeout→504, client_abort→499, too_large→413, shed→503+Retry-After;
+ * `compute_error` re-surfaces the original error for the generic 500/503 path).
+ * `durationMs` on the error variants is the solve wall time up to the failure,
+ * for the metric record.
  */
 export type SolveOutcome =
 	| {
@@ -133,6 +200,19 @@ export type SolveOutcome =
 	| { kind: 'timeout'; durationMs: number; message: string }
 	| { kind: 'client_abort'; durationMs: number }
 	| { kind: 'too_large' }
+	/**
+	 * Scheduler backpressure shed the solve before it executed — the per-server
+	 * queue was full (`QUEUE_FULL`) or it sat queued past the wait deadline
+	 * (`QUEUE_TIMEOUT`). Retryable: the route maps this to 503 + `Retry-After`.
+	 * `retryAfterSeconds` is a suggested backoff hint for the client.
+	 */
+	| {
+			kind: 'shed';
+			durationMs: number;
+			reason: 'queue_full' | 'queue_timeout';
+			retryAfterSeconds: number;
+			message: string;
+	  }
 	| { kind: 'compute_error'; durationMs: number; error: unknown };
 
 // ============================================================================
@@ -155,6 +235,28 @@ export async function runSolvePipeline(args: SolvePipelineArgs): Promise<SolveOu
 	);
 	const treeBuildMs = performance.now() - treeBuildStart;
 
+	// --- L2 durable cache lookup (H1) ---------------------------------------
+	// Derive the wide key from the TRANSFORMED tree (R13) + config subset (R8),
+	// then check the injected hook. Present only for cacheable live solves — its
+	// presence is the channel gate. A hit skips the solve entirely and serves the
+	// stored gzipped envelope; the derived key is reused for the write-through on
+	// a miss. Lookup is best-effort: any rejection is swallowed to a miss.
+	let inputKey: string | null = null;
+	if (args.solveCache) {
+		inputKey = deriveSolveCacheInputKey(inputTree, args.solveCache.configSubset).hash;
+		let stored: Uint8Array | null = null;
+		try {
+			stored = await args.solveCache.lookup(inputKey);
+		} catch {
+			stored = null;
+		}
+		if (stored) {
+			const hit = buildEnvelopeFromCacheEntry(stored, inputKey, args);
+			if (hit) return hit;
+			// Corrupt/tampered entry → fall through and solve as a miss.
+		}
+	}
+
 	// --- solve --------------------------------------------------------------
 	// Snapshot the shared telemetry sequence counters. The holders live on the
 	// warm client and are written by every request on this server; with
@@ -184,6 +286,30 @@ export async function runSolvePipeline(args: SolvePipelineArgs): Promise<SolveOu
 				message: `Solve exceeded the ${Math.round(args.maxSolveDurationMs / 1000)}s deadline.`
 			};
 		}
+		// Scheduler backpressure (audit B7): a full queue or an over-deadline queue
+		// wait sheds the solve BEFORE compute runs. Classify these as `shed` (503 +
+		// Retry-After) rather than the generic 500 `compute_error` path — they're
+		// load signals, not failures, and the client should back off and retry.
+		if (err instanceof RhinoComputeError) {
+			if (err.code === ErrorCodes.QUEUE_FULL) {
+				return {
+					kind: 'shed',
+					durationMs,
+					reason: 'queue_full',
+					retryAfterSeconds: 1,
+					message: 'Compute server is at capacity. Retry shortly.'
+				};
+			}
+			if (err.code === ErrorCodes.QUEUE_TIMEOUT) {
+				return {
+					kind: 'shed',
+					durationMs,
+					reason: 'queue_timeout',
+					retryAfterSeconds: 1,
+					message: 'Compute request waited too long in the queue. Retry shortly.'
+				};
+			}
+		}
 		return { kind: 'compute_error', durationMs, error: err };
 	}
 	const solveMs = performance.now() - solveStart;
@@ -207,14 +333,41 @@ export async function runSolvePipeline(args: SolvePipelineArgs): Promise<SolveOu
 	// in Server-Timing, included in `total`). Buffered (not streamed) so
 	// Content-Length is known and a connection cut mid-transfer fails hard
 	// instead of truncating the JSON.
+	// gzip is async (audit B8) — a multi-MB `gzipSync` blocked the event loop for
+	// every other request on this instance. Two independent reasons to compress:
+	//   - the client advertised gzip AND the body clears the 1 KB break-even (tiny
+	//     bodies aren't worth compressing for the wire);
+	//   - an L2 write-through is pending — the entry stores compressed bytes so
+	//     every future hit is near-CPU-free, so we compress even a small body (it
+	//     will be cached), just not for the wire below the threshold.
+	const clientWantsGzip = /\bgzip\b/i.test(args.acceptEncoding);
+	const worthSendingGzip = clientWantsGzip && serialized.length > 1024;
+	const willCache = args.solveCache != null;
 	let compressed: Buffer | null = null;
 	let gzipMs = 0;
-	if (/\bgzip\b/i.test(args.acceptEncoding) && serialized.length > 1024) {
+	if (worthSendingGzip || willCache) {
 		const gzipStart = performance.now();
-		compressed = gzipSync(Buffer.from(serialized));
+		compressed = await gzipAsync(Buffer.from(serialized));
 		gzipMs = performance.now() - gzipStart;
 	}
 
+	// --- L2 write-through (H1) ----------------------------------------------
+	// On a cacheable solve with a compressed body, store the gzipped envelope so
+	// future hits are near-CPU-free. Fire-and-forget through the hook; the store
+	// itself is best-effort (may silently drop under quota/byte pressure).
+	if (args.solveCache && inputKey && compressed) {
+		const entry = encodeSolveCacheEntry(
+			{
+				errorCount: result.errors?.length ?? 0,
+				warningCount: result.warnings?.length ?? 0,
+				serializedBytes: serialized.length,
+				inputHash: inputKey
+			},
+			new Uint8Array(compressed)
+		);
+		args.solveCache.store(inputKey, entry);
+	}
+
 	const serverTotalMs = performance.now() - args.loadStartMs;
 
 	// --- per-request telemetry attribution (see snapshot above) -------------
@@ -228,6 +381,11 @@ export async function runSolvePipeline(args: SolvePipelineArgs): Promise<SolveOu
 			? client.rhinoTiming.last
 			: null;
 
+	// Send gzip to the client only when it's worth it for the wire — a body
+	// compressed solely to feed the L2 write-through (or one below the 1 KB
+	// break-even) goes out uncompressed.
+	const sendCompressed = compressed && worthSendingGzip ? compressed : null;
+
 	// --- Server-Timing envelope (the versioned wire contract) ---------------
 	const serverTiming = buildServerTiming({
 		defLoadMs: args.defLoadMs,
@@ -238,6 +396,9 @@ export async function runSolvePipeline(args: SolvePipelineArgs): Promise<SolveOu
 		serverTotalMs,
 		rhino,
 		settle,
+		byteRefOutcome: args.byteRefOutcome,
+		// L2 was consulted (hook present) and missed — otherwise not consulted.
+		l2CacheHit: args.solveCache ? false : null,
 		prepMarks: args.prepMarks ?? []
 	});
 
@@ -255,16 +416,23 @@ export async function runSolvePipeline(args: SolvePipelineArgs): Promise<SolveOu
 		gzipMs,
 		serverTotalMs,
 		serializedBytes: serialized.length,
-		compressedBytes: compressed?.byteLength ?? null
+		compressedBytes: sendCompressed?.byteLength ?? null,
+		l2CacheHit: args.solveCache ? false : null
 	};
 
 	let envelope: SolveEnvelope;
-	if (compressed) {
+	if (sendCompressed) {
 		// A downstream proxy's `encode gzip` skips already-encoded responses, so
 		// this never double-compresses. Vary is set on both branches.
 		headers['Content-Encoding'] = 'gzip';
-		headers['Content-Length'] = String(compressed.byteLength);
-		envelope = { body: new Uint8Array(compressed), encoding: 'gzip', headers, result, metrics };
+		headers['Content-Length'] = String(sendCompressed.byteLength);
+		envelope = {
+			body: new Uint8Array(sendCompressed),
+			encoding: 'gzip',
+			headers,
+			result,
+			metrics
+		};
 	} else {
 		headers['Content-Length'] = String(Buffer.byteLength(serialized));
 		envelope = { body: serialized, headers, result, metrics };
@@ -279,6 +447,84 @@ export async function runSolvePipeline(args: SolvePipelineArgs): Promise<SolveOu
 	};
 }
 
+// ============================================================================
+// L2 cache-hit envelope
+// ============================================================================
+
+/**
+ * Build the `ok` outcome from a stored L2 entry — the near-CPU-free hit path (no
+ * solve, no `JSON.stringify`, no gzip). Returns `null` when the entry is corrupt
+ * or its stored `inputHash` doesn't match the requesting key (defense-in-depth
+ * against a wide-hash collision), so the caller falls through and solves.
+ */
+function buildEnvelopeFromCacheEntry(
+	entryBytes: Uint8Array,
+	inputKey: string,
+	args: SolvePipelineArgs
+): (SolveOutcome & { kind: 'ok' }) | null {
+	const decoded = decodeSolveCacheEntry(entryBytes);
+	// A collision that produced the same storage key still can't serve the wrong
+	// geometry: the stored hash must match the requesting key's hash.
+	if (!decoded || decoded.header.inputHash !== inputKey) return null;
+
+	const { header, gzippedBody } = decoded;
+	const clientWantsGzip = /\bgzip\b/i.test(args.acceptEncoding);
+	const serverTotalMs = performance.now() - args.loadStartMs;
+
+	const serverTiming = buildServerTiming({
+		defLoadMs: args.defLoadMs,
+		treeBuildMs: 0,
+		solveMs: 0,
+		serializeMs: 0,
+		gzipMs: 0,
+		serverTotalMs,
+		rhino: null,
+		settle: null,
+		byteRefOutcome: args.byteRefOutcome,
+		l2CacheHit: true,
+		prepMarks: args.prepMarks ?? []
+	});
+
+	const headers: Record<string, string> = {
+		'Content-Type': 'application/json',
+		'Server-Timing': serverTiming,
+		[COMPUTE_VERSION_HEADER]: String(COMPUTE_CONTRACT_VERSION),
+		Vary: 'Accept-Encoding'
+	};
+
+	const metrics: SolvePhaseMetrics = {
+		treeBuildMs: 0,
+		solveMs: 0,
+		serializeMs: 0,
+		gzipMs: 0,
+		serverTotalMs,
+		serializedBytes: header.serializedBytes,
+		compressedBytes: clientWantsGzip ? gzippedBody.byteLength : null,
+		l2CacheHit: true
+	};
+
+	let envelope: SolveEnvelope;
+	if (clientWantsGzip) {
+		// Serve the stored compressed bytes verbatim — the whole point of R6.
+		headers['Content-Encoding'] = 'gzip';
+		headers['Content-Length'] = String(gzippedBody.byteLength);
+		envelope = { body: new Uint8Array(gzippedBody), encoding: 'gzip', headers, metrics };
+	} else {
+		// Rare non-gzip client: gunzip back to the JSON string for the response.
+		const json = gunzipEntryBody(gzippedBody);
+		headers['Content-Length'] = String(Buffer.byteLength(json));
+		envelope = { body: json, headers, metrics };
+	}
+
+	return {
+		kind: 'ok',
+		envelope,
+		solveMs: 0,
+		errorCount: header.errorCount,
+		warningCount: header.warningCount
+	};
+}
+
 // ============================================================================
 // Server-Timing assembly
 // ============================================================================
@@ -292,6 +538,9 @@ interface ServerTimingParts {
 	serverTotalMs: number;
 	rhino: CachedClient['rhinoTiming']['last'];
 	settle: CachedClient['solveMeta']['last'];
+	byteRefOutcome?: ByteRefOutcome;
+	/** L2 verdict: true=hit, false=miss (consulted), null=not consulted. */
+	l2CacheHit: boolean | null;
 	prepMarks: [string, number][];
 }
 
@@ -335,5 +584,20 @@ function buildServerTiming(parts: ServerTimingParts): string {
 		}
 	}
 
+	// Byte-cache verdict for `DefinitionRef` solves: skipped = the scheduler never
+	// materialized bytes (pointer-known solve — the whole point of this path), hit
+	// = warm byte cache, miss = fell through to storage. Absent for raw-bytes solves.
+	const byteRef = parts.byteRefOutcome;
+	if (byteRef) {
+		const verdict = !byteRef.loaded ? 'skipped' : byteRef.fromCache ? 'hit' : 'miss';
+		header += `, def_bytes;desc=${verdict}`;
+	}
+
+	// Durable L2 verdict (H1): 1 = hit (no solve ran), 0 = miss (consulted then
+	// solved). Absent when the L2 wasn't consulted (draft channel / caching off).
+	if (parts.l2CacheHit !== null) {
+		header += `, l2_cache;dur=${parts.l2CacheHit ? 1 : 0}`;
+	}
+
 	return header;
 }

package/src/definitions/__tests__/definition-service.test.ts

@@ -0,0 +1,131 @@
+/**
+ * Tests for `DefinitionService.uploadVersion` version-number allocation (caching
+ * Phase 1.5). The root-cause fix: the next version number comes from the store's
+ * monotonic `reserveNextVersionNumber` counter — NOT max(existing)+1, which
+ * reused a number (and its `fileKey`) after delete-latest and let a stale storage
+ * blob serve the old version's bytes for new content.
+ *
+ * These run against fakes that record the store/storage calls, so they pin the
+ * SERVICE's contract (reserve → derive fileKey from the reserved number). That a
+ * real provider's counter is truly monotonic across delete-then-reupload is
+ * covered by the definition-store conformance suite (both providers).
+ */
+
+import { describe, it, expect } from 'vitest';
+import type {
+	IDataProvider,
+	IStorageProvider,
+	RequestContext,
+	DefinitionRecord,
+	DefinitionVersion,
+	UISchema
+} from '@selvajs/platform';
+import { DefinitionService } from '../definition-service.js';
+
+const CTX = { userId: 'u-1' } as RequestContext;
+const SCHEMA = {} as UISchema;
+
+function fakeRecord(guid: string, nextVersionNumber: number): DefinitionRecord {
+	const now = new Date().toISOString();
+	return {
+		guid,
+		projectId: 'p-1',
+		ownerId: 'u-1',
+		createdBy: 'u-1',
+		updatedBy: 'u-1',
+		displayName: 'Def',
+		status: 'draft',
+		solveCount: 0,
+		nextVersionNumber,
+		liveVersionId: 'v-existing',
+		draftVersionId: 'v-existing',
+		createdAt: now,
+		updatedAt: now,
+		deletedAt: null
+	};
+}
+
+/**
+ * A minimal data provider whose `definitions` store hands out the reserved
+ * number and records the version row it was told to create. Only the methods
+ * `uploadVersion` touches are implemented.
+ */
+function fakeDeps(record: DefinitionRecord) {
+	let counter = record.nextVersionNumber;
+	const created: DefinitionVersion[] = [];
+	const puts: string[] = [];
+
+	const data = {
+		definitions: {
+			get: async () => record,
+			reserveNextVersionNumber: async () => counter++, // monotonic, never reused
+			createVersion: async (_ctx: RequestContext, v: DefinitionVersion) => {
+				created.push(v);
+			},
+			setDraftVersion: async () => {}
+		}
+	} as unknown as IDataProvider;
+
+	const storage = {
+		put: async (key: string) => {
+			puts.push(key);
+		}
+	} as unknown as IStorageProvider;
+
+	return { data, storage, created, puts };
+}
+
+describe('DefinitionService.uploadVersion — version-number allocation', () => {
+	it('reserves the next number from the record counter and derives the fileKey from it', async () => {
+		const record = fakeRecord('11111111-1111-1111-1111-111111111111', 3);
+		const { data, storage, created, puts } = fakeDeps(record);
+		const svc = new DefinitionService(data, storage);
+
+		const version = await svc.uploadVersion(
+			CTX,
+			record.guid,
+			new Uint8Array([1, 2, 3]),
+			'gh',
+			'model.gh',
+			SCHEMA
+		);
+
+		expect(version.versionNumber).toBe(3);
+		// fileKey encodes the reserved number — so a fresh number ⇒ fresh key.
+		expect(version.fileKey).toContain('v3');
+		expect(puts).toEqual([version.fileKey]);
+		expect(created).toHaveLength(1);
+		expect(created[0].versionNumber).toBe(3);
+	});
+
+	it('two consecutive uploads mint distinct numbers and distinct fileKeys', async () => {
+		const record = fakeRecord('22222222-2222-2222-2222-222222222222', 5);
+		const { data, storage } = fakeDeps(record);
+		const svc = new DefinitionService(data, storage);
+
+		const a = await svc.uploadVersion(CTX, record.guid, new Uint8Array([1]), 'gh', 'a.gh', SCHEMA);
+		const b = await svc.uploadVersion(CTX, record.guid, new Uint8Array([2]), 'gh', 'b.gh', SCHEMA);
+
+		expect(a.versionNumber).toBe(5);
+		expect(b.versionNumber).toBe(6);
+		expect(a.fileKey).not.toBe(b.fileKey);
+	});
+
+	it('does NOT derive the number from the version list (no listVersions call)', async () => {
+		// The old bug read the version list; the fix must not. A deps object with no
+		// listVersions still works — reserveNextVersionNumber is the only source.
+		const record = fakeRecord('33333333-3333-3333-3333-333333333333', 9);
+		const { data, storage } = fakeDeps(record);
+		const svc = new DefinitionService(data, storage);
+
+		const version = await svc.uploadVersion(
+			CTX,
+			record.guid,
+			new Uint8Array([1]),
+			'gh',
+			'a.gh',
+			SCHEMA
+		);
+		expect(version.versionNumber).toBe(9);
+	});
+});

package/src/definitions/definition-service.ts

@@ -52,7 +52,7 @@ export interface CreateDefinitionRecord {
  *   blob and is filtered out of list endpoints by default.
  *
  *   uploadVersion — append-only:
- *     1. Resolve next versionNumber from the version list
+ *     1. Reserve next versionNumber from the record's monotonic counter
  *     2. Upload blob to versions/v{N}.{ext}
  *     3. Insert DefinitionVersion row
  *     4. Advance draft pointer (live unchanged)
@@ -90,6 +90,8 @@ export class DefinitionService {
 			computeServerId: input.computeServerId,
 			status: 'pending',
 			solveCount: 0,
+			// v1 is created below with versionNumber 1, so the next upload reserves 2.
+			nextVersionNumber: 2,
 			liveVersionId: null,
 			draftVersionId: null,
 			createdAt: now,
@@ -150,9 +152,11 @@ export class DefinitionService {
 		const existing = await this.data.definitions.get(ctx, guid);
 		if (!existing) throw new ProviderError(`Definition not found: ${guid}`, 404);
 
-		// Highest existing versionNumber + 1; covers gaps from deletions.
-		const versions = await this.data.definitions.listVersions(ctx, guid, { limit: 1 });
-		const next = (versions.items[0]?.versionNumber ?? 0) + 1;
+		// Reserve the next version number from the record's monotonic counter — NOT
+		// max(existing)+1, which reused a number after delete-latest and collided
+		// the `fileKey` (stale blob served for new content). The counter only ever
+		// advances, so a delete-then-reupload gets a fresh number and fresh key.
+		const next = await this.data.definitions.reserveNextVersionNumber(ctx, guid);
 
 		const versionId = randomUUID();
 		const fileKey = definitionPaths.version(guid, next, ext);