@rulvar/testing 1.3.1 → 1.4.0

package/README.md

@@ -0,0 +1,27 @@
+# @rulvar/testing
+
+The rulvar test harness: `createTestEngine` and the deterministic
+`FakeAdapter` for fast typed unit tests, VCR cassettes with secret
+redaction, replay-strict runs that fail on any unexpected live call, and
+matchers for Vitest and Jest. Also exports `record`, `replay`, and
+`replayRun`.
+
+Part of [rulvar](https://rulvar.com), an embeddable TypeScript engine
+for durable, budget-bounded multi-agent LLM workflows, where a completed
+LLM call is never paid for twice. Full documentation:
+[docs.rulvar.com](https://docs.rulvar.com).
+
+## Install
+
+```bash
+pnpm add -D @rulvar/testing
+```
+
+## Documentation
+
+- [Testing](https://docs.rulvar.com/guide/testing)
+- [API reference](https://docs.rulvar.com/api/%40rulvar/testing/)
+
+## License
+
+[Apache-2.0](https://github.com/o-stepper/rulvar/blob/main/LICENSE)

package/dist/index.d.ts

@@ -29,46 +29,57 @@ declare function replayRun<A, R>(wf: Workflow<A, R>, args: A, options: ReplayRun
 //#endregion
 //#region src/cassettes/build-fixtures.d.ts
 /** One cassette fixture file: id, provenance note, and the journal. */
+/** @internal */
 interface CassetteFixture {
   id: string;
   note: string;
   entries: JournalEntry[];
 }
+/** @internal */
 declare function buildM2CassetteFixtures(): CassetteFixture[];
 /**
 * The frozen v1 journal: a
 * round-1 JSONL file with kinds agent, step, rand, external, approval and
 * the legacy `v: 1` field (no hashVersion member). Returned as raw
 * JSON-ready objects, one per line.
+* @internal
 */
 declare function buildFrozenV1JournalRaw(): Array<Record<string, unknown>>;
 /**
 * v2 golden identity fixtures: worked examples per spawn kind (M2-T12).
 * The keys freeze the hashVersion 2 profile; the v1 members freeze the
 * effort-insensitive projection and the incomparable domain.
+* @internal
 */
 declare function buildV2GoldenIdentity(): Record<string, unknown>;
 //#endregion
 //#region src/cassettes/record-live.d.ts
+/** @internal */
 declare function recordLiveCassettes(): Promise<CassetteFixture[]>;
 //#endregion
 //#region src/cassettes/m6-orchestrator.d.ts
+/** @internal */
 declare const M6_ORCH_RUN_ID = "m6-orchestrator-crash";
+/** @internal */
 declare const M6_ORCH_GOAL = "m6 cassette: gather two facts";
+/** @internal */
 declare const M6_ORCH_PROFILES: {
   worker: {
     description: string;
   };
 };
 /** Extracts spawn handles from the tool results the model saw. */
+/** @internal */
 declare function handlesInRequest(req: ChatRequest): number[];
 /** Fixes wall clock and spans; everything else is deterministic already. */
+/** @internal */
 declare function normalizeM6Entries(entries: readonly JournalEntry[]): JournalEntry[];
 /**
 * Phase 1: record the pre-crash journal. The transcripts store carries
 * the boundary checkpoint the resume restores from; the recorder keeps
 * it in memory because the cassette pins only journal bytes (checkpoint
 * blobs are engine-internal at-least-once state).
+* @internal
 */
 declare function recordOrchestratorCrash(): Promise<{
   entries: JournalEntry[]; /** Boundary checkpoint blobs by ref, base64: the resume restores from them. */

package/dist/index.js

@@ -209,7 +209,7 @@ var FakeAdapter = class {
 */
 function createTestEngine(options) {
 	const fake = new FakeAdapter({ agents: options.agents });
-	const store = new InMemoryStore();
+	const store = new InMemoryStore({ quiet: true });
 	const profiles = { ...options.profiles };
 	for (const key of Object.keys(options.agents)) if (key !== "*" && profiles[key] === void 0) profiles[key] = {};
 	const engine = createEngine({
@@ -609,6 +609,7 @@ const PROMPTS = {
 	crossCheck: "cross-check the citations",
 	assessTone: "assess the tone"
 };
+/** @internal */
 function buildM2CassetteFixtures() {
 	const fixtures = [];
 	{
@@ -867,6 +868,7 @@ function buildM2CassetteFixtures() {
 * round-1 JSONL file with kinds agent, step, rand, external, approval and
 * the legacy `v: 1` field (no hashVersion member). Returned as raw
 * JSON-ready objects, one per line.
+* @internal
 */
 function buildFrozenV1JournalRaw() {
 	const j = new FixtureJournal();
@@ -934,6 +936,7 @@ const WORKED_EXAMPLE_INPUT = {
 * v2 golden identity fixtures: worked examples per spawn kind (M2-T12).
 * The keys freeze the hashVersion 2 profile; the v1 members freeze the
 * effort-insensitive projection and the incomparable domain.
+* @internal
 */
 function buildV2GoldenIdentity() {
 	return {
@@ -1602,6 +1605,7 @@ async function recordDoubleAbandonIdempotent() {
 	})).applied) throw new Error("double-abandon: the second abandon must fold noop");
 	return normalizeEntries(await store.load("record"));
 }
+/** @internal */
 async function recordLiveCassettes() {
 	const fixtures = [];
 	fixtures.push({
@@ -1709,13 +1713,17 @@ async function recordLiveCassettes() {
 }
 //#endregion
 //#region src/cassettes/m6-orchestrator.ts
+/** @internal */
 const M6_ORCH_RUN_ID = "m6-orchestrator-crash";
+/** @internal */
 const M6_ORCH_GOAL = "m6 cassette: gather two facts";
+/** @internal */
 const M6_ORCH_PROFILES = { worker: { description: "does one task" } };
 function agentTypeOf(call) {
 	return (call.req.providerOptions?.rulvar)?.agentType ?? "";
 }
 /** Extracts spawn handles from the tool results the model saw. */
+/** @internal */
 function handlesInRequest(req) {
 	const handles = [];
 	for (const msg of req.messages) for (const part of msg.parts) if (part.type === "tool-result") {
@@ -1725,6 +1733,7 @@ function handlesInRequest(req) {
 	return handles;
 }
 /** Fixes wall clock and spans; everything else is deterministic already. */
+/** @internal */
 function normalizeM6Entries(entries) {
 	return entries.map((entry) => ({
 		...entry,
@@ -1738,6 +1747,7 @@ function normalizeM6Entries(entries) {
 * the boundary checkpoint the resume restores from; the recorder keeps
 * it in memory because the cassette pins only journal bytes (checkpoint
 * blobs are engine-internal at-least-once state).
+* @internal
 */
 async function recordOrchestratorCrash() {
 	let orchestratorTurn = 0;
@@ -1918,7 +1928,9 @@ function readCassette(path) {
 * matching live adapter in `adapters` (a development convenience only).
 */
 function replay(options) {
-	const { rows } = readCassette(options.cassette);
+	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`);
 	const byAdapter = /* @__PURE__ */ new Map();
 	for (const row of rows) {
 		const forAdapter = byAdapter.get(row.adapterId) ?? /* @__PURE__ */ new Map();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rulvar/testing",
-  "version": "1.3.1",
+  "version": "1.4.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.3.1"
+    "@rulvar/core": "1.4.0"
   },
   "devDependencies": {
     "@types/node": "^22.20.0",