@rulvar/testing 1.28.0 → 1.29.0

package/dist/index.d.ts

@@ -161,9 +161,14 @@ declare function defaultRedact(value: string): string;
 */
 declare function requestHash(req: ChatRequest): string;
 /**
-* Wraps live adapters for recording: every completed stream appends one
-* redacted row to the cassette JSONL. The wrapped adapters are drop-in:
-* same ids, providers, caps, and event streams.
+* Wraps live adapters for recording: every stream that completes with
+* exactly one terminal event (finish or error) appends one redacted
+* row to the cassette JSONL. A stream that ends without a terminal
+* (a requested abort or a truncated read), throws, or violates the
+* adapter contract (a second terminal, data after the terminal)
+* appends nothing, so a cassette row is always the record of one
+* completed exchange (v1.28.0 review P2). The wrapped adapters are
+* drop-in: same ids, providers, caps, and event streams.
 */
 declare function record(options: {
   adapters: ProviderAdapter[];
@@ -179,7 +184,15 @@ interface VcrCassette {
   header: VcrHeader;
   rows: VcrRow[];
 }
-/** Parses a cassette file (one header line plus one JSON row per line). */
+/**
+* Parses a cassette file (one header line plus one JSON row per line).
+* The header must declare cassette format `v: 1`: the format version
+* gates parsing itself, while hashVersion (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.
+* Parse and shape failures throw a typed ConfigError naming the
+* cassette path and line (v1.28.0 review P3).
+*/
 declare function readCassette(path: string): VcrCassette;
 /**
 * Builds replay adapters from a cassette. `onMiss: 'throw'` is the

package/dist/index.js

@@ -326,9 +326,14 @@ function headerLine() {
 	});
 }
 /**
-* Wraps live adapters for recording: every completed stream appends one
-* redacted row to the cassette JSONL. The wrapped adapters are drop-in:
-* same ids, providers, caps, and event streams.
+* Wraps live adapters for recording: every stream that completes with
+* exactly one terminal event (finish or error) appends one redacted
+* row to the cassette JSONL. A stream that ends without a terminal
+* (a requested abort or a truncated read), throws, or violates the
+* adapter contract (a second terminal, data after the terminal)
+* appends nothing, so a cassette row is always the record of one
+* completed exchange (v1.28.0 review P2). The wrapped adapters are
+* drop-in: same ids, providers, caps, and event streams.
 */
 function record(options) {
 	const redact = options.redact ? (value) => defaultRedact(options.redact ? options.redact(value) : value) : defaultRedact;
@@ -341,8 +346,12 @@ function record(options) {
 		async *stream(req, signal) {
 			const events = [];
 			let thrown = false;
+			let terminals = 0;
+			let postTerminal = false;
 			try {
 				for await (const event of adapter.stream(req, signal)) {
+					if (terminals > 0) postTerminal = true;
+					if (event.type === "finish" || event.type === "error") terminals += 1;
 					events.push(event);
 					yield event;
 				}
@@ -350,7 +359,7 @@ function record(options) {
 				thrown = true;
 				throw error;
 			} finally {
-				if (!thrown) {
+				if (!thrown && terminals === 1 && !postTerminal) {
 					const row = {
 						adapterId: adapter.id,
 						...adapter.provider === void 0 ? {} : { provider: adapter.provider },
@@ -375,14 +384,38 @@ var VcrMissError = class extends Error {
 		this.requestHash = hash;
 	}
 };
-/** Parses a cassette file (one header line plus one JSON row per line). */
+/**
+* Parses a cassette file (one header line plus one JSON row per line).
+* The header must declare cassette format `v: 1`: the format version
+* gates parsing itself, while hashVersion (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.
+* Parse and shape failures throw a typed ConfigError naming the
+* cassette path and line (v1.28.0 review P3).
+*/
 function readCassette(path) {
-	const lines = readFileSync(path, "utf8").split("\n").filter((line) => line.trim() !== "");
-	const header = JSON.parse(lines[0] ?? "{}");
-	if (header.kind !== "rulvar-vcr") throw new ConfigError(`${path} is not a rulvar VCR cassette`);
+	const numbered = readFileSync(path, "utf8").split("\n").map((text, index) => ({
+		text,
+		lineNo: index + 1
+	})).filter(({ text }) => text.trim() !== "");
+	const parse = (line) => {
+		try {
+			return JSON.parse(line.text);
+		} catch {
+			throw new ConfigError(`${path}:${String(line.lineNo)} is not valid JSON; the cassette is corrupt or truncated`);
+		}
+	};
+	const first = numbered[0];
+	const headerRaw = first === void 0 ? {} : parse(first);
+	if (headerRaw.kind !== "rulvar-vcr") throw new ConfigError(`${path} is not a rulvar VCR cassette`);
+	if (headerRaw.v !== 1) throw new ConfigError(`${path} declares cassette format v ${String(headerRaw.v)}; this build reads format v 1 only, so record the cassette again on a matching engine`);
 	return {
-		header,
-		rows: lines.slice(1).map((line) => JSON.parse(line))
+		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)`);
+			return row;
+		})
 	};
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rulvar/testing",
-  "version": "1.28.0",
+  "version": "1.29.0",
   "description": "Rulvar test harness: createTestEngine, FakeAdapter, VCR cassettes, replay-strict runs, matchers.",
   "type": "module",
   "license": "Apache-2.0",
@@ -26,7 +26,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@rulvar/core": "1.28.0"
+    "@rulvar/core": "1.29.0"
   },
   "devDependencies": {
     "@types/node": "^22.20.0",