@rulvar/testing 1.29.0 → 1.31.0

package/dist/index.d.ts

@@ -130,6 +130,16 @@ declare function runLiveSmoke(adapter: Pick<ProviderAdapter, "stream">, req: Cha
 interface VcrRow {
   adapterId: string;
   provider?: string;
+  /**
+  * The recording adapter's declared usageSemantics snapshot (v1.30.0
+  * review P2): replay restores it on the rebuilt adapter, so the
+  * fresh journal of a replayed run carries the same provenance stamp
+  * the recorded run got. Absent when the recording adapter declared
+  * none, and in every cassette recorded before v1.31.0, whose
+  * replays therefore stamp nothing (documented historical laxity; an
+  * unstamped entry reads as recorded before the stamp existed).
+  */
+  usageSemantics?: string;
   requestHash: string;
   /** Redacted canonical request, for humans and drift review. */
   request: unknown;
@@ -175,10 +185,18 @@ declare function record(options: {
   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;
@@ -187,9 +205,24 @@ interface VcrCassette {
 /**
 * 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 (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.
+* 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, an optional nonempty usageSemantics) 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
+* required payload and Usage numeric invariants, and caps must carry
+* every ModelCaps field (with the optional pricing table checked
+* when present). Unknown extra FIELDS are tolerated for forward
+* compatibility. Event stream SEMANTICS (one trailing terminal per
+* row) and adapter consistency across rows (provider,
+* usageSemantics, caps agreement) are deliberately not checked at
+* read time; `replay` enforces them before serving anything (v1.29.0
+* review P3), so reading never blocks inspecting a well formed file.
 * Parse and shape failures throw a typed ConfigError naming the
 * cassette path and line (v1.28.0 review P3).
 */
@@ -198,6 +231,33 @@ 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.
+*
+* The rebuilt adapter restores the recorded provider and
+* usageSemantics declarations (v1.30.0 review P2), so the fresh
+* journal of a replayed run carries the same provenance stamp the
+* recorded run got instead of silently reading like an entry from
+* before the stamp existed. All rows of one adapter must agree on
+* 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).
 */
 declare function replay(options: {
   cassette: string;

package/dist/index.js

@@ -1,5 +1,5 @@
 import { a as fakeWireError, i as fakeToolCalls, n as FAKE_MODEL_REF, r as FakeAdapter, t as FAKE_MODEL } from "./fake-adapter-3T_w-IOY.js";
-import { CURRENT_HASH_VERSION, ConfigError, InMemoryStore, JournalMissError, createEngine, hashWorkflowBody } from "@rulvar/core";
+import { CURRENT_HASH_VERSION, ConfigError, InMemoryStore, JournalMissError, createEngine, hashWorkflowBody, usageViolations } from "@rulvar/core";
 import { createHash } from "node:crypto";
 import { appendFileSync, existsSync, readFileSync, writeFileSync } from "node:fs";
 //#region src/test-engine.ts
@@ -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,
@@ -351,7 +355,7 @@ function record(options) {
 			try {
 				for await (const event of adapter.stream(req, signal)) {
 					if (terminals > 0) postTerminal = true;
-					if (event.type === "finish" || event.type === "error") terminals += 1;
+					if (isTerminalEvent(event)) terminals += 1;
 					events.push(event);
 					yield event;
 				}
@@ -363,6 +367,7 @@ function record(options) {
 					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),
@@ -375,21 +380,174 @@ 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;
 	}
 };
+function isPlainObject(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+const EFFORTS = [
+	"low",
+	"medium",
+	"high",
+	"xhigh",
+	"max"
+];
+const FINISH_REASONS = [
+	"stop",
+	"tool-calls",
+	"max-tokens",
+	"context-window-exceeded",
+	"refusal"
+];
+const USAGE_COUNT_FIELDS = [
+	"inputTokens",
+	"outputTokens",
+	"cacheReadTokens",
+	"cacheWriteTokens",
+	"reasoningTokens"
+];
+/**
+* First shape violation of a recorded caps snapshot, or undefined. The
+* checks mirror what ModelCaps declares (v1.30.0 review P3): before
+* this shipped an empty object passed as a snapshot and the failure
+* surfaced later as an unrelated router or pricing defect.
+*/
+function capsShapeIssue(caps) {
+	if (caps.structuredOutput !== "native" && caps.structuredOutput !== "forced-tool" && caps.structuredOutput !== "prompt") return "caps.structuredOutput must be 'native', 'forced-tool', or 'prompt'";
+	for (const field of ["supportsTemperature", "supportsParallelTools"]) if (typeof caps[field] !== "boolean") return `caps.${field} must be a boolean`;
+	const efforts = caps.reasoningEfforts;
+	if (!Array.isArray(efforts) || efforts.some((entry) => typeof entry !== "string" || !EFFORTS.includes(entry))) return "caps.reasoningEfforts must be an array of canonical efforts";
+	for (const field of ["contextWindow", "maxOutputTokens"]) {
+		const value = caps[field];
+		if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0) return `caps.${field} must be a positive safe integer`;
+	}
+	if (caps.pricing !== void 0) {
+		const pricing = caps.pricing;
+		if (!isPlainObject(pricing)) return "caps.pricing must be an object when present";
+		for (const field of ["inputUsdPerMTok", "outputUsdPerMTok"]) {
+			const value = pricing[field];
+			if (typeof value !== "number" || !Number.isFinite(value) || value < 0) return `caps.pricing.${field} must be a nonnegative finite number`;
+		}
+		for (const field of [
+			"cacheReadUsdPerMTok",
+			"cacheWriteUsdPerMTok",
+			"cacheWrite1hUsdPerMTok"
+		]) {
+			const value = pricing[field];
+			if (value !== void 0 && (typeof value !== "number" || !Number.isFinite(value) || value < 0)) return `caps.pricing.${field} must be a nonnegative finite number when present`;
+		}
+		const tiers = pricing.tiers;
+		if (tiers !== void 0) {
+			if (!Array.isArray(tiers)) return "caps.pricing.tiers must be an array when present";
+			for (const [index, tier] of tiers.entries()) {
+				const path = `caps.pricing.tiers[${String(index)}]`;
+				if (!isPlainObject(tier)) return `${path} must be an object`;
+				const above = tier.aboveInputTokens;
+				if (typeof above !== "number" || !Number.isSafeInteger(above) || above < 0) return `${path}.aboveInputTokens must be a nonnegative safe integer`;
+				for (const field of ["inputMultiplier", "outputMultiplier"]) {
+					const value = tier[field];
+					if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) return `${path}.${field} must be a positive finite number`;
+				}
+			}
+		}
+	}
+}
+/**
+* First shape violation of one recorded event, or undefined. Every
+* element must be a member of the canonical ChatEvent vocabulary with
+* its required payload (v1.30.0 review P3): before this shipped a
+* null element crashed replay with a raw TypeError and a bare
+* `{ type: 'finish' }` reached the engine, which then died on the
+* missing usage instead of refusing the cassette at its boundary.
+* Unknown extra FIELDS on a known event stay tolerated; an unknown
+* event TYPE is refused, because replay would feed it to an engine
+* whose vocabulary provably does not include it (the cassette format
+* version, not leniency here, is the growth path).
+*/
+function eventShapeIssue(event, index) {
+	const at = `events[${String(index)}]`;
+	if (!isPlainObject(event)) return `${at} must be an object (a canonical ChatEvent)`;
+	const type = event.type;
+	switch (type) {
+		case "text-delta":
+		case "reasoning-delta": return typeof event.text === "string" ? void 0 : `${at}.text must be a string`;
+		case "tool-call-start":
+			if (typeof event.id !== "string" || event.id === "") return `${at}.id must be a nonempty string`;
+			return typeof event.name === "string" && event.name !== "" ? void 0 : `${at}.name must be a nonempty string`;
+		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 "usage": {
+			const usage = event.usage;
+			if (!isPlainObject(usage)) return `${at}.usage must be an object`;
+			for (const field of USAGE_COUNT_FIELDS) {
+				const value = usage[field];
+				if (value !== void 0 && (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0)) return `${at}.usage.${field} must be a nonnegative safe integer when present`;
+			}
+			return;
+		}
+		case "finish": {
+			const finish = event.finish;
+			if (!isPlainObject(finish)) return `${at}.finish must be an object (a typed FinishInfo)`;
+			const reason = finish.reason;
+			if (typeof reason !== "string" || !FINISH_REASONS.includes(reason)) return `${at}.finish.reason must be a canonical finish reason`;
+			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 usage = event.usage;
+			if (!isPlainObject(usage)) return `${at}.usage must be an object (the full Usage of the exchange)`;
+			const violations = usageViolations(usage);
+			return violations.length === 0 ? void 0 : `${at}.usage violates the Usage invariant: ${violations.join("; ")}`;
+		}
+		case "error": {
+			const error = event.error;
+			if (!isPlainObject(error)) return `${at}.error must be an object (a WireError)`;
+			if (typeof error.code !== "string" || error.code === "") return `${at}.error.code must be a nonempty string`;
+			if (typeof error.message !== "string") return `${at}.error.message must be a string`;
+			return typeof error.retryable === "boolean" ? void 0 : `${at}.error.retryable must be a boolean`;
+		}
+		default: return `${at}.type must be a canonical ChatEvent type; got ${typeof type === "string" ? `'${type}'` : String(type)}`;
+	}
+}
 /**
 * 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 (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.
+* 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, an optional nonempty usageSemantics) 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
+* required payload and Usage numeric invariants, and caps must carry
+* every ModelCaps field (with the optional pricing table checked
+* when present). Unknown extra FIELDS are tolerated for forward
+* compatibility. Event stream SEMANTICS (one trailing terminal per
+* row) and adapter consistency across rows (provider,
+* usageSemantics, caps agreement) are deliberately not checked at
+* read time; `replay` enforces them before serving anything (v1.29.0
+* review P3), so reading never blocks inspecting a well formed file.
 * Parse and shape failures throw a typed ConfigError naming the
 * cassette path and line (v1.28.0 review P3).
 */
@@ -409,11 +567,32 @@ function readCassette(path) {
 	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: headerRaw,
 		rows: numbered.slice(1).map((line) => {
-			const row = parse(line);
-			if (typeof row !== "object" || row === null || typeof row.adapterId !== "string" || typeof row.requestHash !== "string" || !Array.isArray(row.events)) throw new ConfigError(`${path}:${String(line.lineNo)} is not a VCR row (adapterId, requestHash, and events are required)`);
+			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 (row.usageSemantics !== void 0 && (typeof row.usageSemantics !== "string" || row.usageSemantics === "")) reject("usageSemantics, when present, must be a nonempty string");
+			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);
+			if (capsIssue !== void 0) reject(capsIssue);
+			if (!Array.isArray(row.events)) reject("events must be an array");
+			const events = row.events;
+			for (const [index, event] of events.entries()) {
+				const eventIssue = eventShapeIssue(event, index);
+				if (eventIssue !== void 0) reject(eventIssue);
+			}
 			return row;
 		})
 	};
@@ -422,44 +601,104 @@ function readCassette(path) {
 * 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.
+*
+* The rebuilt adapter restores the recorded provider and
+* usageSemantics declarations (v1.30.0 review P2), so the fresh
+* journal of a replayed run carries the same provenance stamp the
+* recorded run got instead of silently reading like an entry from
+* before the stamp existed. All rows of one adapter must agree on
+* 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).
 */
 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`);
+		}
+		for (const field of ["provider", "usageSemantics"]) {
+			const values = [...new Set(recordedRows.map((row) => row[field]))];
+			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);
+		const cursors = /* @__PURE__ */ new Map();
 		return {
 			id: adapterId,
 			...someRow?.provider === void 0 ? {} : { provider: someRow.provider },
+			...someRow?.usageSemantics === void 0 ? {} : { usageSemantics: someRow.usageSemantics },
 			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.29.0",
+  "version": "1.31.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.29.0"
+    "@rulvar/core": "1.31.0"
   },
   "devDependencies": {
     "@types/node": "^22.20.0",