@rulvar/testing 1.30.0 → 1.32.0

package/dist/index.d.ts

@@ -130,6 +130,29 @@ 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;
+  /**
+  * 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;
@@ -167,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[];
@@ -179,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;
@@ -199,14 +228,23 @@ interface VcrCassette {
 * 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
+* 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).
+* 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
+* 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).
 */
 declare function readCassette(path: string): VcrCassette;
 /**
@@ -214,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
@@ -230,6 +274,22 @@ declare function readCassette(path: string): VcrCassette;
 * 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). 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

@@ -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
@@ -336,67 +336,227 @@ 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 },
-						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;
 	}
 };
+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":
+			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`;
+			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 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);
+			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
@@ -404,14 +564,23 @@ var VcrMissError = class extends Error {
 * 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
+* 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).
+* 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
+* 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).
 */
 function readCassette(path) {
 	const numbered = readFileSync(path, "utf8").split("\n").map((text, index) => ({
@@ -444,9 +613,18 @@ function readCassette(path) {
 			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 (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);
+			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;
 		})
 	};
@@ -456,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
@@ -472,6 +656,22 @@ function readCassette(path) {
 * 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). 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);
@@ -490,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();
@@ -505,11 +706,23 @@ function replay(options) {
 			});
 			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);
+		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 },
+			...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.30.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.30.0"
+    "@rulvar/core": "1.32.0"
   },
   "devDependencies": {
     "@types/node": "^22.20.0",