@warlock.js/ai 4.3.0 → 4.5.0

package/esm/vcr/errors.mjs

@@ -0,0 +1,37 @@
+import { AIError } from "../errors/ai-error.mjs";
+
+//#region ../@warlock.js/ai/src/vcr/errors.ts
+/**
+* Thrown when a `vcr(model, { mode: "replay" })` call finds no cassette
+* entry matching the request hash.
+*
+* **The whole point of deterministic tests.** VCR in `replay` mode never
+* falls back to a live provider call on a miss — that would silently
+* re-introduce network/non-determinism into a test that asked for the
+* opposite. Instead it throws this error so the run fails loud, telling
+* the developer to re-record the cassette (run once in `record`/`auto`).
+*
+* Extends {@link AIError} directly (not `ProviderError`) — a cassette miss
+* is a harness/config failure, not a provider failure.
+*
+* @example
+* try {
+*   await vcrModel.complete(messages);
+* } catch (error) {
+*   if (error instanceof VcrCassetteMissError) {
+*     console.error("Re-record the cassette:", error.path);
+*   }
+* }
+*/
+var VcrCassetteMissError = class extends AIError {
+	constructor(message, options) {
+		super("VCR_CASSETTE_MISS", message, options);
+		this.name = "VcrCassetteMissError";
+		this.requestHash = options?.requestHash;
+		this.path = options?.path;
+	}
+};
+
+//#endregion
+export { VcrCassetteMissError };
+//# sourceMappingURL=errors.mjs.map

package/esm/vcr/errors.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/vcr/errors.ts"],"sourcesContent":["import { AIError } from \"../errors/ai-error\";\nimport type { AIErrorOptions } from \"../errors/ai-error\";\n\n/**\n * Payload for {@link VcrCassetteMissError}. Carries the looked-up request\n * hash and the cassette path so a failing CI run names exactly which call\n * was not recorded.\n */\nexport type VcrCassetteMissErrorOptions = AIErrorOptions & {\n  /** The normalized request hash that found no matching cassette entry. */\n  requestHash?: string;\n  /** Cassette file path the lookup ran against. */\n  path?: string;\n};\n\n/**\n * Thrown when a `vcr(model, { mode: \"replay\" })` call finds no cassette\n * entry matching the request hash.\n *\n * **The whole point of deterministic tests.** VCR in `replay` mode never\n * falls back to a live provider call on a miss — that would silently\n * re-introduce network/non-determinism into a test that asked for the\n * opposite. Instead it throws this error so the run fails loud, telling\n * the developer to re-record the cassette (run once in `record`/`auto`).\n *\n * Extends {@link AIError} directly (not `ProviderError`) — a cassette miss\n * is a harness/config failure, not a provider failure.\n *\n * @example\n * try {\n *   await vcrModel.complete(messages);\n * } catch (error) {\n *   if (error instanceof VcrCassetteMissError) {\n *     console.error(\"Re-record the cassette:\", error.path);\n *   }\n * }\n */\nexport class VcrCassetteMissError extends AIError {\n  public readonly requestHash?: string;\n  public readonly path?: string;\n\n  public constructor(message: string, options?: VcrCassetteMissErrorOptions) {\n    super(\"VCR_CASSETTE_MISS\", message, options);\n    this.name = \"VcrCassetteMissError\";\n    this.requestHash = options?.requestHash;\n    this.path = options?.path;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;AAqCA,IAAa,uBAAb,cAA0C,QAAQ;CAIhD,AAAO,YAAY,SAAiB,SAAuC;EACzE,MAAM,qBAAqB,SAAS,OAAO;EAC3C,KAAK,OAAO;EACZ,KAAK,cAAc,SAAS;EAC5B,KAAK,OAAO,SAAS;CACvB;AACF"}

package/esm/vcr/hash-request.d.mts

@@ -0,0 +1,28 @@
+import { Message } from "../contracts/conversation-message.type.mjs";
+import { ModelCallOptions } from "../contracts/model.contract.mjs";
+
+//#region ../@warlock.js/ai/src/vcr/hash-request.d.ts
+/**
+ * Default `ModelCallOptions` fields folded into the request hash. These are
+ * the inputs that materially change the model's output; everything else
+ * (notably `signal` and unknown provider keys) is excluded so an otherwise
+ * identical logical call still matches its recording.
+ */
+declare const DEFAULT_HASH_OPTIONS: readonly string[];
+/**
+ * Compute the stable VCR request hash for a model call.
+ *
+ * The hash covers the full `messages` array plus the picked, normalized
+ * `options` subset (see {@link DEFAULT_HASH_OPTIONS}). Inputs are
+ * canonicalized (recursive key sort) before serialization so property order
+ * never affects the result. `signal` and unknown provider keys are excluded.
+ *
+ * @example
+ * const a = hashRequest(messages, { temperature: 0.2 });
+ * const b = hashRequest(messages, { temperature: 0.2, signal });
+ * // a === b — signal is excluded.
+ */
+declare function hashRequest(messages: Message[], options?: ModelCallOptions, hashOptions?: readonly string[]): string;
+//#endregion
+export { DEFAULT_HASH_OPTIONS, hashRequest };
+//# sourceMappingURL=hash-request.d.mts.map

package/esm/vcr/hash-request.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash-request.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/vcr/hash-request.ts"],"mappings":";;;;;;AAUA;;;;cAAa,oBAAA;AAiJb;;;;;;;;;;AAGuD;;;AAHvD,iBAAgB,WAAA,CACd,QAAA,EAAU,OAAA,IACV,OAAA,GAAU,gBAAgB,EAC1B,WAAA"}

package/esm/vcr/hash-request.mjs

@@ -0,0 +1,118 @@
+//#region ../@warlock.js/ai/src/vcr/hash-request.ts
+/**
+* Default `ModelCallOptions` fields folded into the request hash. These are
+* the inputs that materially change the model's output; everything else
+* (notably `signal` and unknown provider keys) is excluded so an otherwise
+* identical logical call still matches its recording.
+*/
+const DEFAULT_HASH_OPTIONS = [
+	"temperature",
+	"maxTokens",
+	"responseSchema",
+	"tools",
+	"reasoning"
+];
+/**
+* Reduce a tool to the parts the model actually conditions on: its name,
+* description, and the *shape* of its input schema. Two tools that differ
+* only by object identity (a fresh schema instance per import) hash
+* identically; a real contract change (renamed field, new description)
+* invalidates the recording.
+*
+* The input schema is fingerprinted structurally — a Standard Schema is an
+* opaque object, so we serialize its enumerable own keys rather than
+* attempting to read its internals.
+*/
+function fingerprintTool(tool) {
+	return {
+		name: tool.name,
+		description: tool.description,
+		input: tool.input ? schemaShape(tool.input) : void 0
+	};
+}
+/**
+* Produce a stable, JSON-safe fingerprint of an arbitrary schema object.
+* Records only the structural skeleton (own enumerable keys, recursively)
+* so harmless instance differences don't perturb the hash while a genuine
+* structural change does.
+*/
+function schemaShape(value, depth = 0) {
+	if (depth > 6 || value === null || typeof value !== "object") return typeof value;
+	if (Array.isArray(value)) return value.map((item) => schemaShape(item, depth + 1));
+	const out = {};
+	for (const key of Object.keys(value).sort()) out[key] = schemaShape(value[key], depth + 1);
+	return out;
+}
+/**
+* Pick the hashable subset of `options`, normalizing `tools` into their
+* name+description+schema-shape fingerprint. `signal` and any field not in
+* `hashOptions` are dropped.
+*/
+function pickOptions(options, hashOptions) {
+	if (!options) return {};
+	const picked = {};
+	for (const key of hashOptions) {
+		const value = options[key];
+		if (value === void 0) continue;
+		if (key === "tools" && Array.isArray(value)) {
+			picked[key] = value.map(fingerprintTool);
+			continue;
+		}
+		picked[key] = value;
+	}
+	return picked;
+}
+/**
+* Recursively sort object keys so two logically-equal payloads serialize to
+* byte-identical JSON regardless of property insertion order.
+*/
+function canonicalize(value) {
+	if (value === null || typeof value !== "object") return value;
+	if (Array.isArray(value)) return value.map(canonicalize);
+	const out = {};
+	for (const key of Object.keys(value).sort()) out[key] = canonicalize(value[key]);
+	return out;
+}
+/**
+* Non-cryptographic 53-bit string hash (FNV-style, cyrb53). Deterministic
+* across runs and platforms; collision-resistant enough for a per-cassette
+* keyspace. Returned as a base-36 string.
+*/
+function hashString(input) {
+	let h1 = 3735928559;
+	let h2 = 1103547991;
+	for (let i = 0; i < input.length; i++) {
+		const ch = input.charCodeAt(i);
+		h1 = Math.imul(h1 ^ ch, 2654435761);
+		h2 = Math.imul(h2 ^ ch, 1597334677);
+	}
+	h1 = Math.imul(h1 ^ h1 >>> 16, 2246822507);
+	h1 ^= Math.imul(h2 ^ h2 >>> 13, 3266489909);
+	h2 = Math.imul(h2 ^ h2 >>> 16, 2246822507);
+	h2 ^= Math.imul(h1 ^ h1 >>> 13, 3266489909);
+	return (4294967296 * (2097151 & h2) + (h1 >>> 0)).toString(36);
+}
+/**
+* Compute the stable VCR request hash for a model call.
+*
+* The hash covers the full `messages` array plus the picked, normalized
+* `options` subset (see {@link DEFAULT_HASH_OPTIONS}). Inputs are
+* canonicalized (recursive key sort) before serialization so property order
+* never affects the result. `signal` and unknown provider keys are excluded.
+*
+* @example
+* const a = hashRequest(messages, { temperature: 0.2 });
+* const b = hashRequest(messages, { temperature: 0.2, signal });
+* // a === b — signal is excluded.
+*/
+function hashRequest(messages, options, hashOptions = DEFAULT_HASH_OPTIONS) {
+	const payload = canonicalize({
+		messages,
+		options: pickOptions(options, hashOptions)
+	});
+	return hashString(JSON.stringify(payload));
+}
+
+//#endregion
+export { DEFAULT_HASH_OPTIONS, hashRequest };
+//# sourceMappingURL=hash-request.mjs.map

package/esm/vcr/hash-request.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash-request.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/vcr/hash-request.ts"],"sourcesContent":["import type { Message } from \"../contracts/conversation-message.type\";\nimport type { ModelCallOptions } from \"../contracts/model.contract\";\nimport type { ToolConfig } from \"../contracts/tool.contract\";\n\n/**\n * Default `ModelCallOptions` fields folded into the request hash. These are\n * the inputs that materially change the model's output; everything else\n * (notably `signal` and unknown provider keys) is excluded so an otherwise\n * identical logical call still matches its recording.\n */\nexport const DEFAULT_HASH_OPTIONS: readonly string[] = [\n  \"temperature\",\n  \"maxTokens\",\n  \"responseSchema\",\n  \"tools\",\n  \"reasoning\",\n];\n\n/**\n * Reduce a tool to the parts the model actually conditions on: its name,\n * description, and the *shape* of its input schema. Two tools that differ\n * only by object identity (a fresh schema instance per import) hash\n * identically; a real contract change (renamed field, new description)\n * invalidates the recording.\n *\n * The input schema is fingerprinted structurally — a Standard Schema is an\n * opaque object, so we serialize its enumerable own keys rather than\n * attempting to read its internals.\n */\nfunction fingerprintTool(tool: ToolConfig<unknown, unknown>): unknown {\n  return {\n    name: tool.name,\n    description: tool.description,\n    input: tool.input ? schemaShape(tool.input) : undefined,\n  };\n}\n\n/**\n * Produce a stable, JSON-safe fingerprint of an arbitrary schema object.\n * Records only the structural skeleton (own enumerable keys, recursively)\n * so harmless instance differences don't perturb the hash while a genuine\n * structural change does.\n */\nfunction schemaShape(value: unknown, depth = 0): unknown {\n  if (depth > 6 || value === null || typeof value !== \"object\") {\n    return typeof value;\n  }\n\n  if (Array.isArray(value)) {\n    return value.map((item) => schemaShape(item, depth + 1));\n  }\n\n  const out: Record<string, unknown> = {};\n\n  for (const key of Object.keys(value as Record<string, unknown>).sort()) {\n    out[key] = schemaShape((value as Record<string, unknown>)[key], depth + 1);\n  }\n\n  return out;\n}\n\n/**\n * Pick the hashable subset of `options`, normalizing `tools` into their\n * name+description+schema-shape fingerprint. `signal` and any field not in\n * `hashOptions` are dropped.\n */\nfunction pickOptions(\n  options: ModelCallOptions | undefined,\n  hashOptions: readonly string[],\n): Record<string, unknown> {\n  if (!options) {\n    return {};\n  }\n\n  const picked: Record<string, unknown> = {};\n\n  for (const key of hashOptions) {\n    const value = options[key];\n\n    if (value === undefined) {\n      continue;\n    }\n\n    if (key === \"tools\" && Array.isArray(value)) {\n      picked[key] = (value as ToolConfig<unknown, unknown>[]).map(fingerprintTool);\n      continue;\n    }\n\n    picked[key] = value;\n  }\n\n  return picked;\n}\n\n/**\n * Recursively sort object keys so two logically-equal payloads serialize to\n * byte-identical JSON regardless of property insertion order.\n */\nfunction canonicalize(value: unknown): unknown {\n  if (value === null || typeof value !== \"object\") {\n    return value;\n  }\n\n  if (Array.isArray(value)) {\n    return value.map(canonicalize);\n  }\n\n  const out: Record<string, unknown> = {};\n\n  for (const key of Object.keys(value as Record<string, unknown>).sort()) {\n    out[key] = canonicalize((value as Record<string, unknown>)[key]);\n  }\n\n  return out;\n}\n\n/**\n * Non-cryptographic 53-bit string hash (FNV-style, cyrb53). Deterministic\n * across runs and platforms; collision-resistant enough for a per-cassette\n * keyspace. Returned as a base-36 string.\n */\nfunction hashString(input: string): string {\n  let h1 = 0xdeadbeef;\n  let h2 = 0x41c6ce57;\n\n  for (let i = 0; i < input.length; i++) {\n    const ch = input.charCodeAt(i);\n\n    h1 = Math.imul(h1 ^ ch, 2654435761);\n    h2 = Math.imul(h2 ^ ch, 1597334677);\n  }\n\n  h1 = Math.imul(h1 ^ (h1 >>> 16), 2246822507);\n  h1 ^= Math.imul(h2 ^ (h2 >>> 13), 3266489909);\n  h2 = Math.imul(h2 ^ (h2 >>> 16), 2246822507);\n  h2 ^= Math.imul(h1 ^ (h1 >>> 13), 3266489909);\n\n  const combined = 4294967296 * (2097151 & h2) + (h1 >>> 0);\n\n  return combined.toString(36);\n}\n\n/**\n * Compute the stable VCR request hash for a model call.\n *\n * The hash covers the full `messages` array plus the picked, normalized\n * `options` subset (see {@link DEFAULT_HASH_OPTIONS}). Inputs are\n * canonicalized (recursive key sort) before serialization so property order\n * never affects the result. `signal` and unknown provider keys are excluded.\n *\n * @example\n * const a = hashRequest(messages, { temperature: 0.2 });\n * const b = hashRequest(messages, { temperature: 0.2, signal });\n * // a === b — signal is excluded.\n */\nexport function hashRequest(\n  messages: Message[],\n  options?: ModelCallOptions,\n  hashOptions: readonly string[] = DEFAULT_HASH_OPTIONS,\n): string {\n  const payload = canonicalize({\n    messages,\n    options: pickOptions(options, hashOptions),\n  });\n\n  return hashString(JSON.stringify(payload));\n}\n"],"mappings":";;;;;;;AAUA,MAAa,uBAA0C;CACrD;CACA;CACA;CACA;CACA;AACF;;;;;;;;;;;;AAaA,SAAS,gBAAgB,MAA6C;CACpE,OAAO;EACL,MAAM,KAAK;EACX,aAAa,KAAK;EAClB,OAAO,KAAK,QAAQ,YAAY,KAAK,KAAK,IAAI;CAChD;AACF;;;;;;;AAQA,SAAS,YAAY,OAAgB,QAAQ,GAAY;CACvD,IAAI,QAAQ,KAAK,UAAU,QAAQ,OAAO,UAAU,UAClD,OAAO,OAAO;CAGhB,IAAI,MAAM,QAAQ,KAAK,GACrB,OAAO,MAAM,KAAK,SAAS,YAAY,MAAM,QAAQ,CAAC,CAAC;CAGzD,MAAM,MAA+B,CAAC;CAEtC,KAAK,MAAM,OAAO,OAAO,KAAK,KAAgC,CAAC,CAAC,KAAK,GACnE,IAAI,OAAO,YAAa,MAAkC,MAAM,QAAQ,CAAC;CAG3E,OAAO;AACT;;;;;;AAOA,SAAS,YACP,SACA,aACyB;CACzB,IAAI,CAAC,SACH,OAAO,CAAC;CAGV,MAAM,SAAkC,CAAC;CAEzC,KAAK,MAAM,OAAO,aAAa;EAC7B,MAAM,QAAQ,QAAQ;EAEtB,IAAI,UAAU,QACZ;EAGF,IAAI,QAAQ,WAAW,MAAM,QAAQ,KAAK,GAAG;GAC3C,OAAO,OAAQ,MAAyC,IAAI,eAAe;GAC3E;EACF;EAEA,OAAO,OAAO;CAChB;CAEA,OAAO;AACT;;;;;AAMA,SAAS,aAAa,OAAyB;CAC7C,IAAI,UAAU,QAAQ,OAAO,UAAU,UACrC,OAAO;CAGT,IAAI,MAAM,QAAQ,KAAK,GACrB,OAAO,MAAM,IAAI,YAAY;CAG/B,MAAM,MAA+B,CAAC;CAEtC,KAAK,MAAM,OAAO,OAAO,KAAK,KAAgC,CAAC,CAAC,KAAK,GACnE,IAAI,OAAO,aAAc,MAAkC,IAAI;CAGjE,OAAO;AACT;;;;;;AAOA,SAAS,WAAW,OAAuB;CACzC,IAAI,KAAK;CACT,IAAI,KAAK;CAET,KAAK,IAAI,IAAI,GAAG,IAAI,MAAM,QAAQ,KAAK;EACrC,MAAM,KAAK,MAAM,WAAW,CAAC;EAE7B,KAAK,KAAK,KAAK,KAAK,IAAI,UAAU;EAClC,KAAK,KAAK,KAAK,KAAK,IAAI,UAAU;CACpC;CAEA,KAAK,KAAK,KAAK,KAAM,OAAO,IAAK,UAAU;CAC3C,MAAM,KAAK,KAAK,KAAM,OAAO,IAAK,UAAU;CAC5C,KAAK,KAAK,KAAK,KAAM,OAAO,IAAK,UAAU;CAC3C,MAAM,KAAK,KAAK,KAAM,OAAO,IAAK,UAAU;CAI5C,QAFiB,cAAc,UAAU,OAAO,OAAO,GAExC,CAAC,SAAS,EAAE;AAC7B;;;;;;;;;;;;;;AAeA,SAAgB,YACd,UACA,SACA,cAAiC,sBACzB;CACR,MAAM,UAAU,aAAa;EAC3B;EACA,SAAS,YAAY,SAAS,WAAW;CAC3C,CAAC;CAED,OAAO,WAAW,KAAK,UAAU,OAAO,CAAC;AAC3C"}

package/esm/vcr/index.d.mts

@@ -0,0 +1,4 @@
+import { Cassette, CassetteEntry, VcrMode, VcrModel, VcrOptions } from "./vcr.type.mjs";
+import { vcr } from "./vcr.mjs";
+import { VcrCassetteMissError, VcrCassetteMissErrorOptions } from "./errors.mjs";
+import { DEFAULT_HASH_OPTIONS, hashRequest } from "./hash-request.mjs";

package/esm/vcr/index.mjs

@@ -0,0 +1,5 @@
+import { VcrCassetteMissError } from "./errors.mjs";
+import { DEFAULT_HASH_OPTIONS, hashRequest } from "./hash-request.mjs";
+import { vcr } from "./vcr.mjs";
+
+export {  };

package/esm/vcr/vcr.d.mts

@@ -0,0 +1,32 @@
+import { ModelContract } from "../contracts/model.contract.mjs";
+import { VcrModel, VcrOptions } from "./vcr.type.mjs";
+
+//#region ../@warlock.js/ai/src/vcr/vcr.d.ts
+/**
+ * Wrap any `ModelContract` in a record/replay decorator backed by a JSON
+ * cassette on disk.
+ *
+ * **What it does.** Intercepts only `complete()`/`stream()` — the single
+ * seam every agent trip funnels through — and delegates `name`, `provider`,
+ * `capabilities`, and `pricing` to the inner model untouched. On a call it
+ * computes a stable hash over `{ messages, picked options }` and, depending
+ * on `mode`:
+ *
+ * - **`record`** — always calls the inner model and appends a cassette entry.
+ * - **`replay`** — returns the matching entry (or re-yields its chunks /
+ *   re-throws its error); a miss throws `VcrCassetteMissError`, never a live
+ *   call.
+ * - **`auto`** (default) — replays a hit, records a miss.
+ *
+ * Composes *below* `fallbackModel` and works with any adapter because it
+ * depends only on `ModelContract`. Call `save()` to flush new entries.
+ *
+ * @example
+ * const model = vcr(liveModel, { path: "./cassettes/support.json" });
+ * const response = await model.complete(messages);
+ * await model.save(); // first run records; later runs replay deterministically.
+ */
+declare function vcr(model: ModelContract, options: VcrOptions): VcrModel;
+//#endregion
+export { vcr };
+//# sourceMappingURL=vcr.d.mts.map

package/esm/vcr/vcr.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vcr.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/vcr/vcr.ts"],"mappings":";;;;;;AA8UA;;;;;;;;;;;;;;AAAwE;;;;;;;;iBAAxD,GAAA,CAAI,KAAA,EAAO,aAAA,EAAe,OAAA,EAAS,UAAA,GAAa,QAAA"}

package/esm/vcr/vcr.mjs

@@ -0,0 +1,248 @@
+import { redact } from "../security/redact.mjs";
+import { emptyCassette, loadCassette, saveCassette } from "./cassette-io.mjs";
+import { VcrCassetteMissError } from "./errors.mjs";
+import { DEFAULT_HASH_OPTIONS, hashRequest } from "./hash-request.mjs";
+
+//#region ../@warlock.js/ai/src/vcr/vcr.ts
+/**
+* Internal decorator that wraps an inner `ModelContract`, intercepting only
+* `complete()`/`stream()` and delegating every identity getter to the inner
+* model. Drives the record/replay state machine over a single in-memory
+* {@link Cassette}.
+*
+* **Why a class.** It holds mutable per-instance state (the loaded cassette,
+* the dirty flag, the load promise) behind a stable `ModelContract` surface;
+* the public API is the `vcr()` factory, never `new`.
+*/
+var Vcr = class {
+	constructor(inner, options) {
+		this.inner = inner;
+		this.dirty = false;
+		this.warnedVerbatim = false;
+		this.path = options.path;
+		this.mode = options.mode ?? "auto";
+		this.hashOptions = options.hashOptions ?? DEFAULT_HASH_OPTIONS;
+		this.recordRequest = options.recordRequest ?? "verbatim";
+		this.redactRequestHook = options.redactRequest;
+		this.redactResponseHook = options.redactResponse;
+		this.redactErrorHook = options.redactError;
+		this.loadedCassette = emptyCassette(inner.name, inner.provider);
+	}
+	/** Inner model identifier — delegated verbatim. */
+	get name() {
+		return this.inner.name;
+	}
+	/** Inner provider — delegated verbatim. */
+	get provider() {
+		return this.inner.provider;
+	}
+	/** Inner capability flags — delegated verbatim. */
+	get capabilities() {
+		return this.inner.capabilities;
+	}
+	/** Inner pricing — delegated verbatim so cost accounting is unchanged. */
+	get pricing() {
+		return this.inner.pricing;
+	}
+	/** Loaded/recorded cassette, exposed for assertions. */
+	get cassette() {
+		return this.loadedCassette;
+	}
+	/**
+	* Load the on-disk cassette exactly once. Pure `record` mode skips the
+	* read — it always writes fresh — but the in-memory cassette still starts
+	* empty so a record run never accidentally replays a stale entry.
+	*/
+	async ensureLoaded() {
+		if (this.loadPromise) return this.loadPromise;
+		this.loadPromise = this.mode === "record" ? Promise.resolve() : (async () => {
+			this.loadedCassette = await loadCassette(this.path, this.inner.name, this.inner.provider);
+		})();
+		return this.loadPromise;
+	}
+	/** Find a recorded entry whose hash matches the current request. */
+	findEntry(hash) {
+		return this.loadedCassette.entries.find((entry) => entry.requestHash === hash);
+	}
+	/** Re-throw a recorded error by reconstructing a plain `Error`. */
+	throwRecordedError(entry) {
+		const error = new Error(entry.error?.message ?? "Recorded error");
+		error.name = entry.error?.name ?? "Error";
+		throw error;
+	}
+	/**
+	* Non-streaming call. In `replay` a miss throws; in `auto`/`record` a miss
+	* calls the inner model and records the outcome (response or error).
+	*/
+	async complete(messages, options) {
+		await this.ensureLoaded();
+		const hash = hashRequest(messages, options, this.hashOptions);
+		if (this.mode !== "record") {
+			const entry = this.findEntry(hash);
+			if (entry) {
+				if (entry.error) this.throwRecordedError(entry);
+				if (entry.response) return entry.response;
+			}
+			if (this.mode === "replay") throw new VcrCassetteMissError(`No cassette entry for this request (model "${this.inner.name}", hash ${hash}).`, {
+				requestHash: hash,
+				path: this.path
+			});
+		}
+		try {
+			const response = await this.inner.complete(messages, options);
+			this.record({
+				requestHash: hash,
+				request: {
+					messages,
+					options
+				},
+				response
+			});
+			return response;
+		} catch (error) {
+			this.record({
+				requestHash: hash,
+				request: {
+					messages,
+					options
+				},
+				error: {
+					name: error.name,
+					message: error.message
+				}
+			});
+			throw error;
+		}
+	}
+	/**
+	* Streaming call. On replay the stored `chunks` are re-yielded in order
+	* (reproducing the `delta`/`tool-call`/`done` sequence) or the stored
+	* error is re-thrown. On record the inner stream is buffered into
+	* `chunks[]` while being re-emitted, then recorded once exhausted.
+	*/
+	async *stream(messages, options) {
+		await this.ensureLoaded();
+		const hash = hashRequest(messages, options, this.hashOptions);
+		if (this.mode !== "record") {
+			const entry = this.findEntry(hash);
+			if (entry) {
+				if (entry.error) this.throwRecordedError(entry);
+				if (entry.chunks) {
+					for (const chunk of entry.chunks) yield chunk;
+					return;
+				}
+			}
+			if (this.mode === "replay") throw new VcrCassetteMissError(`No cassette entry for this request (model "${this.inner.name}", hash ${hash}).`, {
+				requestHash: hash,
+				path: this.path
+			});
+		}
+		const chunks = [];
+		try {
+			for await (const chunk of this.inner.stream(messages, options)) {
+				chunks.push(chunk);
+				yield chunk;
+			}
+		} catch (error) {
+			this.record({
+				requestHash: hash,
+				request: {
+					messages,
+					options
+				},
+				error: {
+					name: error.name,
+					message: error.message
+				}
+			});
+			throw error;
+		}
+		this.record({
+			requestHash: hash,
+			request: {
+				messages,
+				options
+			},
+			chunks
+		});
+	}
+	/**
+	* Append an entry to the in-memory cassette and mark it dirty, applying
+	* the configured request/response/error redaction first (S2). Pure
+	* `replay` never reaches this path, so no replay run is ever dirtied.
+	*/
+	record(entry) {
+		this.loadedCassette.entries.push(this.applyRedaction(entry));
+		this.dirty = true;
+		this.maybeWarnVerbatim();
+	}
+	/**
+	* Apply the persisted-body privacy controls to an entry before it is
+	* stored. The request body follows `recordRequest`; response/error
+	* redactors are applied only when supplied. Replay matching is by the
+	* recomputed hash (kept verbatim), so none of this affects replay.
+	*/
+	applyRedaction(entry) {
+		const out = {
+			requestHash: entry.requestHash,
+			request: entry.request
+		};
+		if (this.recordRequest === "hash-only") out.request = { messages: [] };
+		else if (this.recordRequest === "redacted") out.request = this.redactRequestHook ? this.redactRequestHook(entry.request) : redact(entry.request);
+		if (entry.response) out.response = this.redactResponseHook ? this.redactResponseHook(entry.response) : entry.response;
+		if (entry.chunks) out.chunks = entry.chunks;
+		if (entry.error) out.error = this.redactErrorHook ? this.redactErrorHook(entry.error) : entry.error;
+		return out;
+	}
+	/**
+	* Warn once (outside tests) when the cassette is recording verbatim
+	* request bodies — they may carry prompts, tool args, and PII, so the
+	* file is not safe to commit until sanitized.
+	*/
+	maybeWarnVerbatim() {
+		if (this.warnedVerbatim || this.recordRequest !== "verbatim") return;
+		if (process.env.VITEST || process.env.NODE_ENV === "test") return;
+		this.warnedVerbatim = true;
+		console.warn(`[warlock-ai] VCR is recording verbatim request bodies to "${this.path}" — prompts, tool args, and any PII are stored unredacted. Sanitize before committing, or set recordRequest: "redacted" | "hash-only".`);
+	}
+	/**
+	* Flush newly recorded entries to `path`. No-op when nothing was recorded
+	* (pure replay, or a record/auto run that only ever hit cached entries).
+	*/
+	async save() {
+		if (!this.dirty) return;
+		await saveCassette(this.path, this.loadedCassette);
+		this.dirty = false;
+	}
+};
+/**
+* Wrap any `ModelContract` in a record/replay decorator backed by a JSON
+* cassette on disk.
+*
+* **What it does.** Intercepts only `complete()`/`stream()` — the single
+* seam every agent trip funnels through — and delegates `name`, `provider`,
+* `capabilities`, and `pricing` to the inner model untouched. On a call it
+* computes a stable hash over `{ messages, picked options }` and, depending
+* on `mode`:
+*
+* - **`record`** — always calls the inner model and appends a cassette entry.
+* - **`replay`** — returns the matching entry (or re-yields its chunks /
+*   re-throws its error); a miss throws `VcrCassetteMissError`, never a live
+*   call.
+* - **`auto`** (default) — replays a hit, records a miss.
+*
+* Composes *below* `fallbackModel` and works with any adapter because it
+* depends only on `ModelContract`. Call `save()` to flush new entries.
+*
+* @example
+* const model = vcr(liveModel, { path: "./cassettes/support.json" });
+* const response = await model.complete(messages);
+* await model.save(); // first run records; later runs replay deterministically.
+*/
+function vcr(model, options) {
+	return new Vcr(model, options);
+}
+
+//#endregion
+export { vcr };
+//# sourceMappingURL=vcr.mjs.map

package/esm/vcr/vcr.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"vcr.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/vcr/vcr.ts"],"sourcesContent":["import type { Message } from \"../contracts/conversation-message.type\";\nimport type {\n  ModelCallOptions,\n  ModelCapabilities,\n  ModelContract,\n  ModelResponse,\n  ModelStreamChunk,\n} from \"../contracts/model.contract\";\nimport type { ModelPricing } from \"../contracts/result/model-pricing.type\";\nimport { redact } from \"../security/redact\";\nimport { emptyCassette, loadCassette, saveCassette } from \"./cassette-io\";\nimport { VcrCassetteMissError } from \"./errors\";\nimport { DEFAULT_HASH_OPTIONS, hashRequest } from \"./hash-request\";\nimport type { Cassette, CassetteEntry, VcrMode, VcrModel, VcrOptions } from \"./vcr.type\";\n\n/**\n * Internal decorator that wraps an inner `ModelContract`, intercepting only\n * `complete()`/`stream()` and delegating every identity getter to the inner\n * model. Drives the record/replay state machine over a single in-memory\n * {@link Cassette}.\n *\n * **Why a class.** It holds mutable per-instance state (the loaded cassette,\n * the dirty flag, the load promise) behind a stable `ModelContract` surface;\n * the public API is the `vcr()` factory, never `new`.\n */\nclass Vcr implements VcrModel {\n  private readonly mode: VcrMode;\n  private readonly path: string;\n  private readonly hashOptions: readonly string[];\n\n  /** Loaded + newly recorded entries. Mutated in place as we record. */\n  private loadedCassette: Cassette;\n\n  /** Set when an entry is recorded so `save()` knows there's work to flush. */\n  private dirty = false;\n\n  /** One-shot lazy load of the on-disk cassette, shared across calls. */\n  private loadPromise: Promise<void> | undefined;\n\n  /** Persisted-body privacy controls (S2). */\n  private readonly recordRequest: NonNullable<VcrOptions[\"recordRequest\"]>;\n  private readonly redactRequestHook: VcrOptions[\"redactRequest\"];\n  private readonly redactResponseHook: VcrOptions[\"redactResponse\"];\n  private readonly redactErrorHook: VcrOptions[\"redactError\"];\n\n  /** Verbatim-recording warning fires at most once per instance. */\n  private warnedVerbatim = false;\n\n  public constructor(\n    private readonly inner: ModelContract,\n    options: VcrOptions,\n  ) {\n    this.path = options.path;\n    this.mode = options.mode ?? \"auto\";\n    this.hashOptions = options.hashOptions ?? DEFAULT_HASH_OPTIONS;\n    this.recordRequest = options.recordRequest ?? \"verbatim\";\n    this.redactRequestHook = options.redactRequest;\n    this.redactResponseHook = options.redactResponse;\n    this.redactErrorHook = options.redactError;\n    this.loadedCassette = emptyCassette(inner.name, inner.provider);\n  }\n\n  /** Inner model identifier — delegated verbatim. */\n  public get name(): string {\n    return this.inner.name;\n  }\n\n  /** Inner provider — delegated verbatim. */\n  public get provider(): string {\n    return this.inner.provider;\n  }\n\n  /** Inner capability flags — delegated verbatim. */\n  public get capabilities(): ModelCapabilities | undefined {\n    return this.inner.capabilities;\n  }\n\n  /** Inner pricing — delegated verbatim so cost accounting is unchanged. */\n  public get pricing(): ModelPricing | undefined {\n    return this.inner.pricing;\n  }\n\n  /** Loaded/recorded cassette, exposed for assertions. */\n  public get cassette(): Cassette {\n    return this.loadedCassette;\n  }\n\n  /**\n   * Load the on-disk cassette exactly once. Pure `record` mode skips the\n   * read — it always writes fresh — but the in-memory cassette still starts\n   * empty so a record run never accidentally replays a stale entry.\n   */\n  private async ensureLoaded(): Promise<void> {\n    if (this.loadPromise) {\n      return this.loadPromise;\n    }\n\n    this.loadPromise =\n      this.mode === \"record\"\n        ? Promise.resolve()\n        : (async () => {\n            this.loadedCassette = await loadCassette(\n              this.path,\n              this.inner.name,\n              this.inner.provider,\n            );\n          })();\n\n    return this.loadPromise;\n  }\n\n  /** Find a recorded entry whose hash matches the current request. */\n  private findEntry(hash: string): CassetteEntry | undefined {\n    return this.loadedCassette.entries.find((entry) => entry.requestHash === hash);\n  }\n\n  /** Re-throw a recorded error by reconstructing a plain `Error`. */\n  private throwRecordedError(entry: CassetteEntry): never {\n    const error = new Error(entry.error?.message ?? \"Recorded error\");\n\n    error.name = entry.error?.name ?? \"Error\";\n\n    throw error;\n  }\n\n  /**\n   * Non-streaming call. In `replay` a miss throws; in `auto`/`record` a miss\n   * calls the inner model and records the outcome (response or error).\n   */\n  public async complete(messages: Message[], options?: ModelCallOptions): Promise<ModelResponse> {\n    await this.ensureLoaded();\n\n    const hash = hashRequest(messages, options, this.hashOptions);\n\n    if (this.mode !== \"record\") {\n      const entry = this.findEntry(hash);\n\n      if (entry) {\n        if (entry.error) {\n          this.throwRecordedError(entry);\n        }\n\n        if (entry.response) {\n          return entry.response;\n        }\n      }\n\n      if (this.mode === \"replay\") {\n        throw new VcrCassetteMissError(\n          `No cassette entry for this request (model \"${this.inner.name}\", hash ${hash}).`,\n          { requestHash: hash, path: this.path },\n        );\n      }\n    }\n\n    try {\n      const response = await this.inner.complete(messages, options);\n\n      this.record({ requestHash: hash, request: { messages, options }, response });\n\n      return response;\n    } catch (error) {\n      this.record({\n        requestHash: hash,\n        request: { messages, options },\n        error: { name: (error as Error).name, message: (error as Error).message },\n      });\n\n      throw error;\n    }\n  }\n\n  /**\n   * Streaming call. On replay the stored `chunks` are re-yielded in order\n   * (reproducing the `delta`/`tool-call`/`done` sequence) or the stored\n   * error is re-thrown. On record the inner stream is buffered into\n   * `chunks[]` while being re-emitted, then recorded once exhausted.\n   */\n  public async *stream(\n    messages: Message[],\n    options?: ModelCallOptions,\n  ): AsyncIterable<ModelStreamChunk> {\n    await this.ensureLoaded();\n\n    const hash = hashRequest(messages, options, this.hashOptions);\n\n    if (this.mode !== \"record\") {\n      const entry = this.findEntry(hash);\n\n      if (entry) {\n        if (entry.error) {\n          this.throwRecordedError(entry);\n        }\n\n        if (entry.chunks) {\n          for (const chunk of entry.chunks) {\n            yield chunk;\n          }\n\n          return;\n        }\n      }\n\n      if (this.mode === \"replay\") {\n        throw new VcrCassetteMissError(\n          `No cassette entry for this request (model \"${this.inner.name}\", hash ${hash}).`,\n          { requestHash: hash, path: this.path },\n        );\n      }\n    }\n\n    const chunks: ModelStreamChunk[] = [];\n\n    try {\n      for await (const chunk of this.inner.stream(messages, options)) {\n        chunks.push(chunk);\n\n        yield chunk;\n      }\n    } catch (error) {\n      this.record({\n        requestHash: hash,\n        request: { messages, options },\n        error: { name: (error as Error).name, message: (error as Error).message },\n      });\n\n      throw error;\n    }\n\n    this.record({ requestHash: hash, request: { messages, options }, chunks });\n  }\n\n  /**\n   * Append an entry to the in-memory cassette and mark it dirty, applying\n   * the configured request/response/error redaction first (S2). Pure\n   * `replay` never reaches this path, so no replay run is ever dirtied.\n   */\n  private record(entry: CassetteEntry): void {\n    this.loadedCassette.entries.push(this.applyRedaction(entry));\n    this.dirty = true;\n    this.maybeWarnVerbatim();\n  }\n\n  /**\n   * Apply the persisted-body privacy controls to an entry before it is\n   * stored. The request body follows `recordRequest`; response/error\n   * redactors are applied only when supplied. Replay matching is by the\n   * recomputed hash (kept verbatim), so none of this affects replay.\n   */\n  private applyRedaction(entry: CassetteEntry): CassetteEntry {\n    const out: CassetteEntry = {\n      requestHash: entry.requestHash,\n      request: entry.request,\n    };\n\n    if (this.recordRequest === \"hash-only\") {\n      out.request = { messages: [] };\n    } else if (this.recordRequest === \"redacted\") {\n      out.request = this.redactRequestHook\n        ? this.redactRequestHook(entry.request)\n        : redact(entry.request);\n    }\n\n    if (entry.response) {\n      out.response = this.redactResponseHook\n        ? this.redactResponseHook(entry.response)\n        : entry.response;\n    }\n    if (entry.chunks) {\n      out.chunks = entry.chunks;\n    }\n    if (entry.error) {\n      out.error = this.redactErrorHook\n        ? this.redactErrorHook(entry.error)\n        : entry.error;\n    }\n\n    return out;\n  }\n\n  /**\n   * Warn once (outside tests) when the cassette is recording verbatim\n   * request bodies — they may carry prompts, tool args, and PII, so the\n   * file is not safe to commit until sanitized.\n   */\n  private maybeWarnVerbatim(): void {\n    if (this.warnedVerbatim || this.recordRequest !== \"verbatim\") return;\n    if (process.env.VITEST || process.env.NODE_ENV === \"test\") return;\n\n    this.warnedVerbatim = true;\n    console.warn(\n      `[warlock-ai] VCR is recording verbatim request bodies to \"${this.path}\" — prompts, tool args, and any PII are stored unredacted. ` +\n        'Sanitize before committing, or set recordRequest: \"redacted\" | \"hash-only\".',\n    );\n  }\n\n  /**\n   * Flush newly recorded entries to `path`. No-op when nothing was recorded\n   * (pure replay, or a record/auto run that only ever hit cached entries).\n   */\n  public async save(): Promise<void> {\n    if (!this.dirty) {\n      return;\n    }\n\n    await saveCassette(this.path, this.loadedCassette);\n    this.dirty = false;\n  }\n}\n\n/**\n * Wrap any `ModelContract` in a record/replay decorator backed by a JSON\n * cassette on disk.\n *\n * **What it does.** Intercepts only `complete()`/`stream()` — the single\n * seam every agent trip funnels through — and delegates `name`, `provider`,\n * `capabilities`, and `pricing` to the inner model untouched. On a call it\n * computes a stable hash over `{ messages, picked options }` and, depending\n * on `mode`:\n *\n * - **`record`** — always calls the inner model and appends a cassette entry.\n * - **`replay`** — returns the matching entry (or re-yields its chunks /\n *   re-throws its error); a miss throws `VcrCassetteMissError`, never a live\n *   call.\n * - **`auto`** (default) — replays a hit, records a miss.\n *\n * Composes *below* `fallbackModel` and works with any adapter because it\n * depends only on `ModelContract`. Call `save()` to flush new entries.\n *\n * @example\n * const model = vcr(liveModel, { path: \"./cassettes/support.json\" });\n * const response = await model.complete(messages);\n * await model.save(); // first run records; later runs replay deterministically.\n */\nexport function vcr(model: ModelContract, options: VcrOptions): VcrModel {\n  return new Vcr(model, options);\n}\n"],"mappings":"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"}

package/esm/vcr/vcr.type.d.mts

@@ -0,0 +1,118 @@
+import { Message } from "../contracts/conversation-message.type.mjs";
+import { ModelCallOptions, ModelContract, ModelResponse, ModelStreamChunk } from "../contracts/model.contract.mjs";
+
+//#region ../@warlock.js/ai/src/vcr/vcr.type.d.ts
+/**
+ * Record/replay mode for a {@link VcrModel}.
+ *
+ * - **`record`** — always call the inner model and append the result to
+ *   the cassette. Never replays. Use to (re)capture a fresh cassette.
+ * - **`replay`** — never call the inner model. A cassette hit returns the
+ *   stored response/chunks/error; a miss throws `VcrCassetteMissError`
+ *   (never a silent live call). Use in CI for deterministic, offline tests.
+ * - **`auto`** (default) — replay on a cassette hit, record on a miss.
+ *   The friendliest mode for local dev: records once, replays thereafter.
+ */
+type VcrMode = "record" | "replay" | "auto";
+/**
+ * A single recorded request → response pair on a {@link Cassette}.
+ *
+ * Exactly one of `response` / `chunks` / `error` is populated, mirroring
+ * the three outcomes of a model call: a non-streaming reply, a streamed
+ * chunk sequence, or a thrown provider error.
+ */
+type CassetteEntry = {
+  /** Stable hash of the normalized request (messages + hashed options). */requestHash: string;
+  /**
+   * What was sent — stored verbatim for human readability and so the
+   * cassette can be re-hashed if the hashing format ever changes.
+   */
+  request: {
+    messages: Message[];
+    options?: ModelCallOptions;
+  }; /** A non-streaming reply, recorded from `complete()`. */
+  response?: ModelResponse; /** A streaming reply, captured from `stream()` as the ordered chunk list. */
+  chunks?: ModelStreamChunk[]; /** A thrown provider error, replayed by re-throwing a reconstructed `Error`. */
+  error?: {
+    name: string;
+    message: string;
+  };
+};
+/**
+ * On-disk cassette format: the inner model identity plus every recorded
+ * {@link CassetteEntry}. Serialized as JSON to {@link VcrOptions.path}.
+ */
+type Cassette = {
+  /** Cassette schema version. Bump only on a breaking format change. */version: 1; /** Inner `model.name` at record time — informational. */
+  model: string; /** Inner `model.provider` at record time — informational. */
+  provider: string; /** Recorded request → response pairs, in capture order. */
+  entries: CassetteEntry[];
+};
+/**
+ * Options for {@link vcr}.
+ */
+type VcrOptions = {
+  /** Cassette file path (JSON). Read on construct, written on `save()`. */path: string; /** Record/replay behavior. Default `"auto"`. */
+  mode?: VcrMode;
+  /**
+   * Fields of `ModelCallOptions` to include in the request hash. Default
+   * `["temperature","maxTokens","responseSchema","tools","reasoning"]`.
+   * `signal` and unknown provider keys are always excluded so an
+   * otherwise-identical logical call still matches. `tools` are hashed by
+   * name + description + input-schema shape, not object identity.
+   */
+  hashOptions?: string[];
+  /**
+   * How the request BODY is persisted (S2). Replay matching is by the
+   * recomputed hash, never the stored body — so privacy modes don't break
+   * replay. Default `"verbatim"`.
+   *
+   * - `"verbatim"` — store the full request (prompts, tool args, options)
+   *   for human-readable diffs and re-hashing. Records a loud one-time
+   *   warning (outside tests) since the body may carry PII / secrets.
+   * - `"redacted"` — run the request through {@link redactRequest}, or —
+   *   without one — the key-based `redact()` (strips structured secrets
+   *   like API keys in options; free-text prompts need a custom hook).
+   * - `"hash-only"` — drop the request body entirely; keep only the hash
+   *   and the outcome. Maximum privacy; loses human readability and the
+   *   ability to re-hash.
+   */
+  recordRequest?: "verbatim" | "redacted" | "hash-only";
+  /**
+   * Custom request redactor for `recordRequest: "redacted"`. Receives the
+   * `{ messages, options }` about to be stored; return a sanitized copy.
+   * Overrides the default key-based `redact()`.
+   */
+  redactRequest?: (request: {
+    messages: Message[];
+    options?: ModelCallOptions;
+  }) => {
+    messages: Message[];
+    options?: ModelCallOptions;
+  };
+  /**
+   * Optional redactor for the recorded RESPONSE. Off by default — redacting
+   * the response changes what replay returns, so opt in only when a secret
+   * leaks into model output (e.g. an echoed token).
+   */
+  redactResponse?: (response: ModelResponse) => ModelResponse; /** Optional redactor for a recorded error's `{ name, message }`. */
+  redactError?: (error: {
+    name: string;
+    message: string;
+  }) => {
+    name: string;
+    message: string;
+  };
+};
+/**
+ * A `ModelContract` decorator returned by {@link vcr}. Delegates
+ * `name`/`provider`/`capabilities`/`pricing` to the inner model and
+ * intercepts only `complete()`/`stream()`.
+ */
+type VcrModel = ModelContract & {
+  /** Flush newly recorded entries to `path`. No-op in pure replay. */save(): Promise<void>; /** Recorded/loaded entries, exposed for assertions. */
+  readonly cassette: Cassette;
+};
+//#endregion
+export { Cassette, CassetteEntry, VcrMode, VcrModel, VcrOptions };
+//# sourceMappingURL=vcr.type.d.mts.map

package/esm/vcr/vcr.type.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vcr.type.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/vcr/vcr.type.ts"],"mappings":";;;;;;AAmBA;;;;AAAmB;AASnB;;;;KATY,OAAA;;;;;;;;KASA,aAAA;EASR,yEAPF,WAAA;EAUA;;;;EALA,OAAA;IACE,QAAA,EAAU,OAAA;IACV,OAAA,GAAU,gBAAA;EAAA,GASH;EANT,QAAA,GAAW,aAAA,EAcO;EAZlB,MAAA,GAAS,gBAAA,IAoBa;EAlBtB,KAAA;IACE,IAAA;IACA,OAAA;EAAA;AAAA;;AAgBoB;AAMxB;;KAdY,QAAA;EAkBH,sEAhBP,OAAA,KAgDY;EA9CZ,KAAA,UA+CuC;EA7CvC,QAAA,UAmD8C;EAjD9C,OAAA,EAAS,aAAa;AAAA;;;;KAMZ,UAAA;EA4BV,yEA1BA,IAAA,UAiCE;EA/BF,IAAA,GAAO,OAAA;EAgCL;;;;;;;EAxBF,WAAA;EA+B4B;;;;;;;;;;AAInB;AASX;;;;EA5BE,aAAA;EAgCmB;;;;;EA1BnB,aAAA,IAAiB,OAAA;IACf,QAAA,EAAU,OAAA;IACV,OAAA,GAAU,gBAAA;EAAA;IACJ,QAAA,EAAU,OAAA;IAAW,OAAA,GAAU,gBAAA;EAAA;;;;;;EAMvC,cAAA,IAAkB,QAAA,EAAU,aAAA,KAAkB,aAAA;EAE9C,WAAA,IAAe,KAAA;IAAS,IAAA;IAAc,OAAA;EAAA;IACpC,IAAA;IACA,OAAA;EAAA;AAAA;;;;;;KASQ,QAAA,GAAW,aAAA;sEAErB,IAAA,IAAQ,OAAA;WAEC,QAAA,EAAU,QAAA;AAAA"}