@rulvar/testing 1.30.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;
@@ -199,14 +209,22 @@ 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) 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;
 /**
@@ -230,6 +248,16 @@ 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).
 */
 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
@@ -367,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),
@@ -397,6 +398,135 @@ var VcrMissError = class extends Error {
 		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
@@ -404,14 +534,22 @@ 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) 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 +582,17 @@ 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 (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;
 		})
 	};
@@ -472,6 +618,16 @@ 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).
 */
 function replay(options) {
 	const { header, rows } = readCassette(options.cassette);
@@ -505,11 +661,16 @@ 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);
 		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)?.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.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.30.0"
+    "@rulvar/core": "1.31.0"
   },
   "devDependencies": {
     "@types/node": "^22.20.0",