@rulvar/testing 1.31.0 → 1.32.0

package/dist/index.d.ts

@@ -140,6 +140,19 @@ interface VcrRow {
   * unstamped entry reads as recorded before the stamp existed).
   */
   usageSemantics?: string;
+  /**
+  * Zero based per `(adapterId, requestHash)` call counter, claimed
+  * synchronously when the recorded `stream()` call was made
+  * (v1.31.0 review P2): rows are appended in COMPLETION order, so
+  * without this number two concurrent identical live calls that
+  * finish out of order would swap callers at replay, which hands
+  * occurrences out in caller order. Replay sorts same hash rows by
+  * 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.
+  */
+  occurrence?: number;
   requestHash: string;
   /** Redacted canonical request, for humans and drift review. */
   request: unknown;
@@ -177,8 +190,13 @@ declare function requestHash(req: ChatRequest): string;
 * (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.
+* completed exchange (v1.28.0 review P2). Every call also claims a
+* per `(adapterId, requestHash)` occurrence number synchronously in
+* 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.
 */
 declare function record(options: {
   adapters: ProviderAdapter[];
@@ -189,8 +207,9 @@ declare function record(options: {
 * 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).
+* serves each recorded exchange once, in recorded 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;
@@ -211,7 +230,8 @@ interface VcrCassette {
 * 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, an optional nonempty usageSemantics) is checked
+* string provider, an optional nonempty usageSemantics, an optional
+* nonnegative integer occurrence) is checked
 * here, and the nested structures are validated in depth (v1.30.0
 * review P3): the request must be a plain object, every event must
 * be a member of the canonical ChatEvent vocabulary with its
@@ -232,11 +252,17 @@ declare function readCassette(path: string): VcrCassette;
 * 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.
+* Repeated hashes replay as ordered occurrences (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. The list is sorted by the recorded `occurrence`
+* numbers when every row of the group carries one, so concurrent
+* 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.
 * 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
@@ -257,7 +283,13 @@ declare function readCassette(path: string): VcrCassette;
 * both declarations; a conflict refuses with a typed ConfigError
 * before anything is served. A cassette recorded before v1.31.0
 * stores no usageSemantics, so its replays stamp nothing (documented
-* historical laxity).
+* historical laxity). Under `onMiss: 'passthrough'` the recorded
+* declarations must also match the live adapter's, absent versus
+* present included, because a live served miss is journaled under
+* the wrapper's declarations; a mismatch refuses at construction
+* (v1.31.0 review P2). An adapter with no recorded rows keeps the
+* live adapter's own declarations, so the wrapper stays a metadata
+* preserving drop in.
 */
 declare function replay(options: {
   cassette: string;

package/dist/index.js

@@ -336,63 +336,78 @@ function headerLine() {
 * (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.
+* completed exchange (v1.28.0 review P2). Every call also claims a
+* per `(adapterId, requestHash)` occurrence number synchronously in
+* 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.
 */
 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");
-	return options.adapters.map((adapter) => ({
-		...adapter,
-		id: adapter.id,
-		...adapter.provider === void 0 ? {} : { provider: adapter.provider },
-		caps: (model) => adapter.caps(model),
-		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;
-				}
-			} catch (error) {
-				thrown = true;
-				throw error;
-			} finally {
-				if (!thrown && terminals === 1 && !postTerminal) {
-					const row = {
-						adapterId: adapter.id,
-						...adapter.provider === void 0 ? {} : { provider: adapter.provider },
-						...adapter.usageSemantics === void 0 ? {} : { usageSemantics: adapter.usageSemantics },
-						requestHash: requestHash(req),
-						request: walkStrings(JSON.parse(JSON.stringify(req)), redact),
-						events: walkStrings(JSON.parse(JSON.stringify(events)), redact),
-						caps: adapter.caps(req.model),
-						model: req.model
-					};
-					appendFileSync(options.cassette, `${JSON.stringify(row)}\n`, "utf8");
-				}
+	return options.adapters.map((adapter) => {
+		const occurrences = /* @__PURE__ */ new Map();
+		return {
+			...adapter,
+			id: adapter.id,
+			...adapter.provider === void 0 ? {} : { provider: adapter.provider },
+			caps: (model) => adapter.caps(model),
+			stream(req, signal) {
+				const hash = requestHash(req);
+				const occurrence = occurrences.get(hash) ?? 0;
+				occurrences.set(hash, occurrence + 1);
+				return (async function* () {
+					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;
+						}
+					} catch (error) {
+						thrown = true;
+						throw error;
+					} finally {
+						if (!thrown && terminals === 1 && !postTerminal) {
+							const row = {
+								adapterId: adapter.id,
+								...adapter.provider === void 0 ? {} : { provider: adapter.provider },
+								...adapter.usageSemantics === void 0 ? {} : { usageSemantics: adapter.usageSemantics },
+								occurrence,
+								requestHash: hash,
+								request: walkStrings(JSON.parse(JSON.stringify(req)), redact),
+								events: walkStrings(JSON.parse(JSON.stringify(events)), redact),
+								caps: adapter.caps(req.model),
+								model: req.model
+							};
+							appendFileSync(options.cassette, `${JSON.stringify(row)}\n`, "utf8");
+						}
+					}
+				})();
 			}
-		}
-	}));
+		};
+	});
 }
 /**
 * 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).
+* serves each recorded exchange once, in recorded order); absent or
+* zero means the request was never recorded at all (v1.29.0 review
+* P2).
 */
 var VcrMissError = class extends Error {
 	requestHash;
 	/** 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`);
+		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 recorded 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;
@@ -493,7 +508,9 @@ function eventShapeIssue(event, index) {
 		case "tool-call-delta":
 			if (typeof event.id !== "string" || event.id === "") return `${at}.id must be a nonempty string`;
 			return typeof event.argsTextDelta === "string" ? void 0 : `${at}.argsTextDelta must be a string`;
-		case "tool-call-end": return typeof event.id === "string" && event.id !== "" ? void 0 : `${at}.id must be a nonempty string`;
+		case "tool-call-end":
+			if (typeof event.id !== "string" || event.id === "") return `${at}.id must be a nonempty string`;
+			return Object.hasOwn(event, "args") ? void 0 : `${at}.args must be present (the arguments the call ended with)`;
 		case "usage": {
 			const usage = event.usage;
 			if (!isPlainObject(usage)) return `${at}.usage must be an object`;
@@ -511,7 +528,20 @@ function eventShapeIssue(event, index) {
 			if (reason === "refusal") {
 				const refusal = finish.refusal;
 				if (!isPlainObject(refusal) || typeof refusal.provider !== "string") return `${at}.finish.refusal must be an object naming the provider`;
+				const stopDetails = refusal.stopDetails;
+				if (stopDetails !== void 0) {
+					if (!isPlainObject(stopDetails)) return `${at}.finish.refusal.stopDetails must be an object when present`;
+					for (const field of [
+						"type",
+						"category",
+						"explanation"
+					]) {
+						const value = stopDetails[field];
+						if (value !== void 0 && typeof value !== "string") return `${at}.finish.refusal.stopDetails.${field} must be a string when present`;
+					}
+				}
 			}
+			if (event.providerMetadata !== void 0 && !isPlainObject(event.providerMetadata)) return `${at}.providerMetadata must be a plain object when present`;
 			const usage = event.usage;
 			if (!isPlainObject(usage)) return `${at}.usage must be an object (the full Usage of the exchange)`;
 			const violations = usageViolations(usage);
@@ -536,7 +566,8 @@ function eventShapeIssue(event, index) {
 * 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, an optional nonempty usageSemantics) is checked
+* string provider, an optional nonempty usageSemantics, an optional
+* nonnegative integer occurrence) is checked
 * here, and the nested structures are validated in depth (v1.30.0
 * review P3): the request must be a plain object, every event must
 * be a member of the canonical ChatEvent vocabulary with its
@@ -583,6 +614,7 @@ function readCassette(path) {
 			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 (row.usageSemantics !== void 0 && (typeof row.usageSemantics !== "string" || row.usageSemantics === "")) reject("usageSemantics, when present, must be a nonempty string");
+			if (row.occurrence !== void 0 && (typeof row.occurrence !== "number" || !Number.isSafeInteger(row.occurrence) || row.occurrence < 0)) reject("occurrence, when present, must be a nonnegative safe integer");
 			if (typeof row.request !== "object" || row.request === null || Array.isArray(row.request)) 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)");
 			const capsIssue = capsShapeIssue(row.caps);
@@ -602,11 +634,17 @@ function readCassette(path) {
 * 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.
+* Repeated hashes replay as ordered occurrences (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. The list is sorted by the recorded `occurrence`
+* numbers when every row of the group carries one, so concurrent
+* 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.
 * 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
@@ -627,7 +665,13 @@ function readCassette(path) {
 * both declarations; a conflict refuses with a typed ConfigError
 * before anything is served. A cassette recorded before v1.31.0
 * stores no usageSemantics, so its replays stamp nothing (documented
-* historical laxity).
+* historical laxity). Under `onMiss: 'passthrough'` the recorded
+* declarations must also match the live adapter's, absent versus
+* present included, because a live served miss is journaled under
+* the wrapper's declarations; a mismatch refuses at construction
+* (v1.31.0 review P2). An adapter with no recorded rows keeps the
+* live adapter's own declarations, so the wrapper stays a metadata
+* preserving drop in.
 */
 function replay(options) {
 	const { header, rows } = readCassette(options.cassette);
@@ -646,6 +690,7 @@ function replay(options) {
 		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 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();
@@ -666,11 +711,18 @@ function replay(options) {
 			if (values.length > 1) throw new ConfigError(`${options.cassette} carries conflicting ${field} values for adapter '${adapterId}' (${values.map((value) => value === void 0 ? "absent" : `'${value}'`).join(", ")}); a replay adapter reports one declaration per adapter, so record the cassette again in one session`);
 		}
 		const passthrough = live.get(adapterId);
+		if (someRow !== void 0 && passthrough !== void 0 && options.onMiss === "passthrough") {
+			for (const field of ["provider", "usageSemantics"]) if (someRow[field] !== passthrough[field]) {
+				const describe = (value) => value === void 0 ? "absent" : `'${value}'`;
+				throw new ConfigError(`${options.cassette} records ${field} ${describe(someRow[field])} for adapter '${adapterId}' but the live passthrough adapter declares ${describe(passthrough[field])}; the engine journals live served misses under the replay adapter declaration, so replay with a matching adapter or record the cassette again`);
+			}
+		}
+		const declared = someRow ?? passthrough;
 		const cursors = /* @__PURE__ */ new Map();
 		return {
 			id: adapterId,
-			...someRow?.provider === void 0 ? {} : { provider: someRow.provider },
-			...someRow?.usageSemantics === void 0 ? {} : { usageSemantics: someRow.usageSemantics },
+			...declared?.provider === void 0 ? {} : { provider: declared.provider },
+			...declared?.usageSemantics === void 0 ? {} : { usageSemantics: declared.usageSemantics },
 			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}'`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rulvar/testing",
-  "version": "1.31.0",
+  "version": "1.32.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.31.0"
+    "@rulvar/core": "1.32.0"
   },
   "devDependencies": {
     "@types/node": "^22.20.0",