@rulvar/testing 1.28.0 → 1.30.0

package/dist/index.d.ts

@@ -161,30 +161,75 @@ declare function defaultRedact(value: string): string;
 */
 declare function requestHash(req: ChatRequest): string;
 /**
-* Wraps live adapters for recording: every completed stream appends one
-* redacted row to the cassette JSONL. The wrapped adapters are drop-in:
-* same ids, providers, caps, and event streams.
+* 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
+* (a requested abort or a truncated read), throws, or violates the
+* adapter contract (a second terminal, data after the terminal)
+* appends nothing, so a cassette row is always the record of one
+* completed exchange (v1.28.0 review P2). The wrapped adapters are
+* drop-in: same ids, providers, caps, and event streams.
 */
 declare function record(options: {
   adapters: ProviderAdapter[];
   cassette: string;
   redact?: RedactFn;
 }): ProviderAdapter[];
-/** Typed hermetic-miss error; onMiss: 'throw' raises it on any unrecorded request. */
+/**
+* Typed hermetic-miss error; onMiss: 'throw' raises it on any request
+* without a servable row. `recordedOccurrences` above zero means the
+* hash WAS recorded but every occurrence is already consumed (replay
+* serves each recorded exchange once, in file order); absent or zero
+* means the request was never recorded at all (v1.29.0 review P2).
+*/
 declare class VcrMissError extends Error {
   readonly requestHash: string;
-  constructor(adapterId: string, hash: string);
+  /** Rows recorded for this hash; absent or 0 = never recorded. */
+  readonly recordedOccurrences?: number;
+  constructor(adapterId: string, hash: string, recordedOccurrences?: number);
 }
 interface VcrCassette {
   header: VcrHeader;
   rows: VcrRow[];
 }
-/** Parses a cassette file (one header line plus one JSON row per line). */
+/**
+* Parses a cassette file (one header line plus one JSON row per line).
+* The header must declare cassette format `v: 1`: the format version
+* gates parsing itself, while hashVersion (whose support window is
+* checked by replay) only gates request identity and never
+* substitutes for it, so a future incompatible format refuses loudly
+* instead of being read as v1. Every documented header field (kind,
+* v, an integer hashVersion, a date-string recordedAt) and row field
+* (adapterId, model, requestHash, request, caps, events, an optional
+* string provider) is shape-checked here; unknown extra fields are
+* tolerated for forward compatibility. Event stream SEMANTICS (one
+* trailing terminal per row) are deliberately not checked at read
+* time; `replay` enforces them before serving anything (v1.29.0
+* review P3). Parse and shape failures throw a typed ConfigError
+* naming the cassette path and line (v1.28.0 review P3).
+*/
 declare function readCassette(path: string): VcrCassette;
 /**
 * Builds replay adapters from a cassette. `onMiss: 'throw'` is the
 * hermetic CI mode; `'passthrough'` forwards unrecorded requests to the
 * matching live adapter in `adapters` (a development convenience only).
+*
+* Repeated hashes replay in file order (v1.29.0 review P2): rows
+* sharing a `(adapterId, requestHash)` key form an ordered occurrence
+* list, and every `stream()` call consumes exactly one occurrence,
+* allocated synchronously inside the call itself, so two concurrent
+* identical requests can never be served the same recorded exchange.
+* 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
+* forwards to the live adapter exactly like a never-recorded request.
+*
+* Before serving anything, replay also enforces what `record` has
+* guaranteed since v1.29.0: every row's event stream ends with
+* exactly one terminal event (finish or error), and all caps
+* snapshots for one `(adapterId, model)` agree, since the replay
+* adapter can only report one caps truth per model. Violations throw
+* a typed ConfigError naming the cassette and row.
 */
 declare function replay(options: {
   cassette: string;

package/dist/index.js

@@ -317,6 +317,10 @@ function requestHash(req) {
 	};
 	return createHash("sha256").update(canonicalJson(withoutTelemetry), "utf8").digest("hex");
 }
+/** The terminal vocabulary of the adapter contract: finish or error. */
+function isTerminalEvent(event) {
+	return event.type === "finish" || event.type === "error";
+}
 function headerLine() {
 	return JSON.stringify({
 		v: 1,
@@ -326,9 +330,14 @@ function headerLine() {
 	});
 }
 /**
-* Wraps live adapters for recording: every completed stream appends one
-* redacted row to the cassette JSONL. The wrapped adapters are drop-in:
-* same ids, providers, caps, and event streams.
+* 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
+* (a requested abort or a truncated read), throws, or violates the
+* adapter contract (a second terminal, data after the terminal)
+* appends nothing, so a cassette row is always the record of one
+* completed exchange (v1.28.0 review P2). 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;
@@ -341,8 +350,12 @@ function record(options) {
 		async *stream(req, signal) {
 			const events = [];
 			let thrown = false;
+			let terminals = 0;
+			let postTerminal = false;
 			try {
 				for await (const event of adapter.stream(req, signal)) {
+					if (terminals > 0) postTerminal = true;
+					if (isTerminalEvent(event)) terminals += 1;
 					events.push(event);
 					yield event;
 				}
@@ -350,7 +363,7 @@ function record(options) {
 				thrown = true;
 				throw error;
 			} finally {
-				if (!thrown) {
+				if (!thrown && terminals === 1 && !postTerminal) {
 					const row = {
 						adapterId: adapter.id,
 						...adapter.provider === void 0 ? {} : { provider: adapter.provider },
@@ -366,67 +379,165 @@ function record(options) {
 		}
 	}));
 }
-/** Typed hermetic-miss error; onMiss: 'throw' raises it on any unrecorded request. */
+/**
+* Typed hermetic-miss error; onMiss: 'throw' raises it on any request
+* without a servable row. `recordedOccurrences` above zero means the
+* hash WAS recorded but every occurrence is already consumed (replay
+* serves each recorded exchange once, in file order); absent or zero
+* means the request was never recorded at all (v1.29.0 review P2).
+*/
 var VcrMissError = class extends Error {
 	requestHash;
-	constructor(adapterId, hash) {
-		super(`VCR miss: adapter '${adapterId}' received a request with no recorded row (hash ${hash.slice(0, 12)}); onMiss: 'throw' keeps cassette tests hermetic`);
+	/** Rows recorded for this hash; absent or 0 = never recorded. */
+	recordedOccurrences;
+	constructor(adapterId, hash, recordedOccurrences) {
+		super(recordedOccurrences !== void 0 && recordedOccurrences > 0 ? `VCR miss: adapter '${adapterId}' exhausted the ${String(recordedOccurrences)} recorded occurrence${recordedOccurrences === 1 ? "" : "s"} of request hash ${hash.slice(0, 12)}; a replay serves each recorded exchange once, in file order` : `VCR miss: adapter '${adapterId}' received a request with no recorded row (hash ${hash.slice(0, 12)}); onMiss: 'throw' keeps cassette tests hermetic`);
 		this.name = "VcrMissError";
 		this.requestHash = hash;
+		if (recordedOccurrences !== void 0) this.recordedOccurrences = recordedOccurrences;
 	}
 };
-/** Parses a cassette file (one header line plus one JSON row per line). */
+/**
+* Parses a cassette file (one header line plus one JSON row per line).
+* The header must declare cassette format `v: 1`: the format version
+* gates parsing itself, while hashVersion (whose support window is
+* checked by replay) only gates request identity and never
+* substitutes for it, so a future incompatible format refuses loudly
+* instead of being read as v1. Every documented header field (kind,
+* v, an integer hashVersion, a date-string recordedAt) and row field
+* (adapterId, model, requestHash, request, caps, events, an optional
+* string provider) is shape-checked here; unknown extra fields are
+* tolerated for forward compatibility. Event stream SEMANTICS (one
+* trailing terminal per row) are deliberately not checked at read
+* time; `replay` enforces them before serving anything (v1.29.0
+* review P3). Parse and shape failures throw a typed ConfigError
+* naming the cassette path and line (v1.28.0 review P3).
+*/
 function readCassette(path) {
-	const lines = readFileSync(path, "utf8").split("\n").filter((line) => line.trim() !== "");
-	const header = JSON.parse(lines[0] ?? "{}");
-	if (header.kind !== "rulvar-vcr") throw new ConfigError(`${path} is not a rulvar VCR cassette`);
+	const numbered = readFileSync(path, "utf8").split("\n").map((text, index) => ({
+		text,
+		lineNo: index + 1
+	})).filter(({ text }) => text.trim() !== "");
+	const parse = (line) => {
+		try {
+			return JSON.parse(line.text);
+		} catch {
+			throw new ConfigError(`${path}:${String(line.lineNo)} is not valid JSON; the cassette is corrupt or truncated`);
+		}
+	};
+	const first = numbered[0];
+	const headerRaw = first === void 0 ? {} : parse(first);
+	if (headerRaw.kind !== "rulvar-vcr") throw new ConfigError(`${path} is not a rulvar VCR cassette`);
+	if (headerRaw.v !== 1) throw new ConfigError(`${path} declares cassette format v ${String(headerRaw.v)}; this build reads format v 1 only, so record the cassette again on a matching engine`);
+	if (typeof headerRaw.hashVersion !== "number" || !Number.isSafeInteger(headerRaw.hashVersion)) throw new ConfigError(`${path} header hashVersion must be an integer (the identity profile version every recorded cassette carries); got ${String(headerRaw.hashVersion)}`);
+	if (typeof headerRaw.recordedAt !== "string" || Number.isNaN(Date.parse(headerRaw.recordedAt))) throw new ConfigError(`${path} header recordedAt must be a date string; got ${String(headerRaw.recordedAt)}`);
 	return {
-		header,
-		rows: lines.slice(1).map((line) => JSON.parse(line))
+		header: headerRaw,
+		rows: numbered.slice(1).map((line) => {
+			const parsed = parse(line);
+			const reject = (what) => {
+				throw new ConfigError(`${path}:${String(line.lineNo)} is not a VCR row: ${what}`);
+			};
+			if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) reject("each row is a JSON object");
+			const row = parsed;
+			if (typeof row.adapterId !== "string" || row.adapterId === "") reject("adapterId must be a nonempty string");
+			if (typeof row.requestHash !== "string" || row.requestHash === "") reject("requestHash must be a nonempty string");
+			if (typeof row.model !== "string" || row.model === "") reject("model must be a nonempty string");
+			if (row.provider !== void 0 && typeof row.provider !== "string") reject("provider, when present, must be a string");
+			if (typeof row.request !== "object" || row.request === null) reject("request must be an object (the redacted canonical request)");
+			if (typeof row.caps !== "object" || row.caps === null || Array.isArray(row.caps)) reject("caps must be an object (the model caps snapshot at record time)");
+			if (!Array.isArray(row.events)) reject("events must be an array");
+			return row;
+		})
 	};
 }
 /**
 * Builds replay adapters from a cassette. `onMiss: 'throw'` is the
 * hermetic CI mode; `'passthrough'` forwards unrecorded requests to the
 * matching live adapter in `adapters` (a development convenience only).
+*
+* Repeated hashes replay in file order (v1.29.0 review P2): rows
+* sharing a `(adapterId, requestHash)` key form an ordered occurrence
+* list, and every `stream()` call consumes exactly one occurrence,
+* allocated synchronously inside the call itself, so two concurrent
+* identical requests can never be served the same recorded exchange.
+* 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
+* forwards to the live adapter exactly like a never-recorded request.
+*
+* Before serving anything, replay also enforces what `record` has
+* guaranteed since v1.29.0: every row's event stream ends with
+* exactly one terminal event (finish or error), and all caps
+* snapshots for one `(adapterId, model)` agree, since the replay
+* adapter can only report one caps truth per model. Violations throw
+* a typed ConfigError naming the cassette and row.
 */
 function replay(options) {
 	const { header, rows } = readCassette(options.cassette);
 	const oldestSupported = CURRENT_HASH_VERSION - 1;
-	if (typeof header.hashVersion !== "number" || header.hashVersion < oldestSupported || header.hashVersion > CURRENT_HASH_VERSION) throw new ConfigError(`${options.cassette} was recorded under hashVersion ${String(header.hashVersion)}, outside the supported window [${oldestSupported}, ${CURRENT_HASH_VERSION}]; record the cassette again on a current engine`);
+	if (header.hashVersion < oldestSupported || header.hashVersion > CURRENT_HASH_VERSION) throw new ConfigError(`${options.cassette} was recorded under hashVersion ${String(header.hashVersion)}, outside the supported window [${oldestSupported}, ${CURRENT_HASH_VERSION}]; record the cassette again on a current engine`);
+	rows.forEach((row, index) => {
+		const terminals = row.events.filter((event) => isTerminalEvent(event)).length;
+		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();
-		forAdapter.set(row.requestHash, row);
+		const occurrences = forAdapter.get(row.requestHash) ?? [];
+		occurrences.push(row);
+		forAdapter.set(row.requestHash, occurrences);
 		byAdapter.set(row.adapterId, forAdapter);
 	}
 	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();
-		const passthrough = live.get(adapterId);
-		const someRow = [...recorded.values()][0];
+		const recordedRows = [...recorded.values()].flat();
+		const someRow = recordedRows[0];
 		const capsByModel = /* @__PURE__ */ new Map();
-		for (const row of recorded.values()) capsByModel.set(row.model, row.caps);
+		for (const row of recordedRows) {
+			const canonical = canonicalJson(row.caps);
+			const existing = capsByModel.get(row.model);
+			if (existing === void 0) capsByModel.set(row.model, {
+				caps: row.caps,
+				canonical
+			});
+			else if (existing.canonical !== canonical) throw new ConfigError(`${options.cassette} carries conflicting caps snapshots for adapter '${adapterId}' model '${row.model}'; a replay adapter reports one caps truth per model, so record the cassette again in one session`);
+		}
+		const passthrough = live.get(adapterId);
+		const cursors = /* @__PURE__ */ new Map();
 		return {
 			id: adapterId,
 			...someRow?.provider === void 0 ? {} : { provider: someRow.provider },
 			caps: (model) => {
-				const snapshot = capsByModel.get(model) ?? passthrough?.caps(model);
+				const snapshot = capsByModel.get(model)?.caps ?? passthrough?.caps(model);
 				if (snapshot === void 0) throw new ConfigError(`VCR replay adapter '${adapterId}' has no caps snapshot for model '${model}'`);
 				return snapshot;
 			},
-			async *stream(req, signal) {
+			stream(req, signal) {
 				const hash = requestHash(req);
-				const row = recorded.get(hash);
-				if (row !== void 0) {
-					for (const event of row.events) yield event;
-					return;
-				}
-				if (options.onMiss === "passthrough" && passthrough !== void 0) {
-					yield* passthrough.stream(req, signal);
-					return;
+				const occurrences = recorded.get(hash);
+				let row;
+				if (occurrences !== void 0) {
+					const cursor = cursors.get(hash) ?? 0;
+					if (cursor < occurrences.length) {
+						cursors.set(hash, cursor + 1);
+						row = occurrences[cursor];
+					}
 				}
-				throw new VcrMissError(adapterId, hash);
+				const recordedCount = occurrences?.length;
+				return (async function* () {
+					if (row !== void 0) {
+						for (const event of row.events) yield event;
+						return;
+					}
+					if (options.onMiss === "passthrough" && passthrough !== void 0) {
+						yield* passthrough.stream(req, signal);
+						return;
+					}
+					throw new VcrMissError(adapterId, hash, recordedCount);
+				})();
 			}
 		};
 	});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rulvar/testing",
-  "version": "1.28.0",
+  "version": "1.30.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.28.0"
+    "@rulvar/core": "1.30.0"
   },
   "devDependencies": {
     "@types/node": "^22.20.0",