@rulvar/testing 1.32.0 → 1.34.0

package/dist/index.d.ts

@@ -150,7 +150,14 @@ interface VcrRow {
   * it when every row of the group carries one; absent in cassettes
   * recorded before v1.32.0, whose same hash rows keep file order.
   * An aborted or failed call claims a number but appends no row, so
-  * gaps in the numbering are valid.
+  * gaps in the numbering are valid. An appending `record()` session
+  * seeds its counters past the numbers already on disk, so the
+  * numbering continues across sequential sessions; a duplicate
+  * number inside a fully numbered group refuses replay as ambiguous
+  * (v1.32.0 review P2). The numbering ends at
+  * `Number.MAX_SAFE_INTEGER`: a session refuses with a typed
+  * ConfigError to claim a number past it, before dispatching the
+  * provider and before touching the file (v1.33.0 review P3).
   */
   occurrence?: number;
   requestHash: string;
@@ -195,8 +202,26 @@ declare function requestHash(req: ChatRequest): string;
 * the `stream()` call itself and persists it on the completed row,
 * so replay can restore the caller to response association even when
 * concurrent identical calls completed out of order (v1.31.0 review
-* P2). The wrapped adapters are drop-in: same ids, providers, caps,
-* and event streams.
+* P2). A later `record()` call on the same cassette file is an
+* appending session: the existing file is read and validated first
+* (a target that was never a cassette, a header whose hashVersion is
+* not the one this build records under, and a file whose occurrence
+* numbering is already ambiguous all refuse with a typed
+* ConfigError), and every hash counter is seeded past the numbers
+* already on disk, so the numbering continues where the file left
+* off instead of restarting at zero (v1.32.0 review P2). One
+* recorder session may be active on a cassette at a time: two
+* concurrently constructed recorders seed identically and claim
+* colliding numbers, which replay refuses as ambiguous instead of
+* silently serving either order. The numbering ends at
+* `Number.MAX_SAFE_INTEGER`: a group that already numbers it refuses
+* the appending session at construction, and a session whose counter
+* would pass it refuses that call before dispatching the provider,
+* both with a typed ConfigError and without touching the file,
+* because the next float increment would stall at 2 ** 53 and
+* silently duplicate one unsafe number on every following row
+* (v1.33.0 review P3). The wrapped adapters are drop-in:
+* same ids, providers, caps, and event streams.
 */
 declare function record(options: {
   adapters: ProviderAdapter[];
@@ -262,7 +287,11 @@ declare function readCassette(path: string): VcrCassette;
 * identical calls whose live completions were appended out of order
 * still replay to the callers that made them (v1.31.0 review P2); a
 * group with any unnumbered row (recorded before v1.32.0) keeps file
-* order.
+* order. A duplicate occurrence inside a fully numbered group
+* refuses the whole cassette with a typed ConfigError naming the
+* adapter and hash: it means two recorder sessions wrote the file
+* concurrently, and serving either order would hand a caller the
+* wrong exchange (v1.32.0 review P2).
 * A call after the last occurrence is a miss: under `onMiss: 'throw'`
 * it raises a VcrMissError whose `recordedOccurrences` says the hash
 * WAS recorded but is exhausted, and under `'passthrough'` it

package/dist/index.js

@@ -330,6 +330,43 @@ function headerLine() {
 	});
 }
 /**
+* Groups rows by `(adapterId, requestHash)` and orders every fully
+* numbered group by its recorded occurrence numbers. Same hash rows
+* sit in the file in COMPLETION order; when every row of a group
+* carries the occurrence number claimed at stream call time, the
+* group is served in that order instead, so concurrent identical
+* calls that finished out of order still replay to the callers that
+* made them (v1.31.0 review P2). A group with any unnumbered row
+* (recorded before v1.32.0) keeps file order, and gaps in the
+* numbering (an aborted or failed call claims a number but appends
+* no row) are valid. A DUPLICATE number inside a fully numbered
+* group refuses the whole cassette: it means two recorder sessions
+* wrote the file concurrently (the documented contract is one active
+* recorder per cassette), and serving either order would silently
+* hand a caller the wrong exchange (v1.32.0 review P2). Both replay
+* and an appending record session group through here, so the refusal
+* fires before anything is served or appended.
+*/
+function groupRows(rows, cassette) {
+	const byAdapter = /* @__PURE__ */ new Map();
+	for (const row of rows) {
+		const forAdapter = byAdapter.get(row.adapterId) ?? /* @__PURE__ */ new Map();
+		const occurrences = forAdapter.get(row.requestHash) ?? [];
+		occurrences.push(row);
+		forAdapter.set(row.requestHash, occurrences);
+		byAdapter.set(row.adapterId, forAdapter);
+	}
+	for (const [adapterId, forAdapter] of byAdapter) for (const [hash, occurrences] of forAdapter) {
+		if (!occurrences.every((row) => row.occurrence !== void 0)) continue;
+		occurrences.sort((a, b) => (a.occurrence ?? 0) - (b.occurrence ?? 0));
+		for (let index = 1; index < occurrences.length; index += 1) {
+			const number = occurrences[index]?.occurrence;
+			if (number !== void 0 && number === occurrences[index - 1]?.occurrence) throw new ConfigError(`${cassette} records occurrence ${String(number)} twice for adapter '${adapterId}' hash ${hash.slice(0, 12)}; two recorder sessions likely wrote this cassette concurrently, so the replay order would be ambiguous; record the cassette again`);
+		}
+	}
+	return byAdapter;
+}
+/**
 * Wraps live adapters for recording: every stream that completes with
 * exactly one terminal event (finish or error) appends one redacted
 * row to the cassette JSONL. A stream that ends without a terminal
@@ -341,14 +378,46 @@ function headerLine() {
 * the `stream()` call itself and persists it on the completed row,
 * so replay can restore the caller to response association even when
 * concurrent identical calls completed out of order (v1.31.0 review
-* P2). The wrapped adapters are drop-in: same ids, providers, caps,
-* and event streams.
+* P2). A later `record()` call on the same cassette file is an
+* appending session: the existing file is read and validated first
+* (a target that was never a cassette, a header whose hashVersion is
+* not the one this build records under, and a file whose occurrence
+* numbering is already ambiguous all refuse with a typed
+* ConfigError), and every hash counter is seeded past the numbers
+* already on disk, so the numbering continues where the file left
+* off instead of restarting at zero (v1.32.0 review P2). One
+* recorder session may be active on a cassette at a time: two
+* concurrently constructed recorders seed identically and claim
+* colliding numbers, which replay refuses as ambiguous instead of
+* silently serving either order. The numbering ends at
+* `Number.MAX_SAFE_INTEGER`: a group that already numbers it refuses
+* the appending session at construction, and a session whose counter
+* would pass it refuses that call before dispatching the provider,
+* both with a typed ConfigError and without touching the file,
+* because the next float increment would stall at 2 ** 53 and
+* silently duplicate one unsafe number on every following row
+* (v1.33.0 review P3). The wrapped adapters are drop-in:
+* same ids, providers, caps, and event streams.
 */
 function record(options) {
 	const redact = options.redact ? (value) => defaultRedact(options.redact ? options.redact(value) : value) : defaultRedact;
-	if (!existsSync(options.cassette)) writeFileSync(options.cassette, `${headerLine()}\n`, "utf8");
+	const seeds = /* @__PURE__ */ new Map();
+	if (existsSync(options.cassette)) {
+		const existing = readCassette(options.cassette);
+		if (existing.header.hashVersion !== CURRENT_HASH_VERSION) throw new ConfigError(`${options.cassette} was recorded under hashVersion ${String(existing.header.hashVersion)} and this build records under ${String(CURRENT_HASH_VERSION)}; appending would mix two identity profiles under one header, so record the cassette again from scratch`);
+		for (const [adapterId, forAdapter] of groupRows(existing.rows, options.cassette)) {
+			const forSeeds = /* @__PURE__ */ new Map();
+			for (const [hash, rows] of forAdapter) {
+				let highest = -1;
+				for (const row of rows) if (row.occurrence !== void 0 && row.occurrence > highest) highest = row.occurrence;
+				if (highest >= Number.MAX_SAFE_INTEGER) throw new ConfigError(`${options.cassette} already numbers occurrence ${String(Number.MAX_SAFE_INTEGER)} for adapter '${adapterId}' hash ${hash.slice(0, 12)}; the numbering has reached the safe integer ceiling, so no further exchange for this request can be appended; record a fresh cassette instead`);
+				forSeeds.set(hash, highest + 1);
+			}
+			seeds.set(adapterId, forSeeds);
+		}
+	} else writeFileSync(options.cassette, `${headerLine()}\n`, "utf8");
 	return options.adapters.map((adapter) => {
-		const occurrences = /* @__PURE__ */ new Map();
+		const occurrences = new Map(seeds.get(adapter.id) ?? []);
 		return {
 			...adapter,
 			id: adapter.id,
@@ -357,6 +426,7 @@ function record(options) {
 			stream(req, signal) {
 				const hash = requestHash(req);
 				const occurrence = occurrences.get(hash) ?? 0;
+				if (!Number.isSafeInteger(occurrence)) throw new ConfigError(`${options.cassette} has no safe occurrence number left for adapter '${adapter.id}' hash ${hash.slice(0, 12)}; an earlier call in this session claimed ${String(Number.MAX_SAFE_INTEGER)}, so this exchange cannot be numbered; record a fresh cassette instead`);
 				occurrences.set(hash, occurrence + 1);
 				return (async function* () {
 					const events = [];
@@ -644,7 +714,11 @@ function readCassette(path) {
 * identical calls whose live completions were appended out of order
 * still replay to the callers that made them (v1.31.0 review P2); a
 * group with any unnumbered row (recorded before v1.32.0) keeps file
-* order.
+* order. A duplicate occurrence inside a fully numbered group
+* refuses the whole cassette with a typed ConfigError naming the
+* adapter and hash: it means two recorder sessions wrote the file
+* concurrently, and serving either order would hand a caller the
+* wrong exchange (v1.32.0 review P2).
 * A call after the last occurrence is a miss: under `onMiss: 'throw'`
 * it raises a VcrMissError whose `recordedOccurrences` says the hash
 * WAS recorded but is exhausted, and under `'passthrough'` it
@@ -682,15 +756,7 @@ function replay(options) {
 		const last = row.events[row.events.length - 1];
 		if (terminals !== 1 || last === void 0 || !isTerminalEvent(last)) throw new ConfigError(`${options.cassette} row ${String(index + 1)} (adapter '${row.adapterId}', hash ${row.requestHash.slice(0, 12)}) does not record one completed exchange: expected exactly one trailing terminal event (finish or error), found ${String(terminals)}; record the cassette again on a current engine`);
 	});
-	const byAdapter = /* @__PURE__ */ new Map();
-	for (const row of rows) {
-		const forAdapter = byAdapter.get(row.adapterId) ?? /* @__PURE__ */ new Map();
-		const occurrences = forAdapter.get(row.requestHash) ?? [];
-		occurrences.push(row);
-		forAdapter.set(row.requestHash, occurrences);
-		byAdapter.set(row.adapterId, forAdapter);
-	}
-	for (const forAdapter of byAdapter.values()) for (const occurrences of forAdapter.values()) if (occurrences.every((row) => row.occurrence !== void 0)) occurrences.sort((a, b) => (a.occurrence ?? 0) - (b.occurrence ?? 0));
+	const byAdapter = groupRows(rows, options.cassette);
 	const live = new Map((options.adapters ?? []).map((adapter) => [adapter.id, adapter]));
 	return [.../* @__PURE__ */ new Set([...byAdapter.keys(), ...live.keys()])].map((adapterId) => {
 		const recorded = byAdapter.get(adapterId) ?? /* @__PURE__ */ new Map();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rulvar/testing",
-  "version": "1.32.0",
+  "version": "1.34.0",
   "description": "Rulvar test harness: createTestEngine, FakeAdapter, VCR cassettes, replay-strict runs, matchers.",
   "type": "module",
   "license": "Apache-2.0",
@@ -26,7 +26,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@rulvar/core": "1.32.0"
+    "@rulvar/core": "1.34.0"
   },
   "devDependencies": {
     "@types/node": "^22.20.0",