mirror-mind 0.0.1 → 0.33.0

package/ts/src/providers/cost.ts

@@ -0,0 +1,64 @@
+/**
+ * The one cost authority for model-in-the-loop spend (AI-09 / CV9.E2.S13),
+ * ported from `memory/intelligence/cost.py` for CV22.DS8.US1.
+ *
+ * Token counts arrive with every provider response; prices are a static table;
+ * cost is a pure function of the two. Keeping this in one place is deliberate --
+ * scattering cost math across call sites is exactly the failure the audit warns
+ * about.
+ *
+ * CR040 deliberately did NOT port this: consult always logs the real fetched
+ * generation cost, so a static estimate would have been dead code. The live
+ * search embedding has no fetched figure -- Python prices that ledger row from
+ * this table -- so the port becomes load-bearing the moment the live provider
+ * lands. Graded against `ts/test/goldens/cost.golden.json`.
+ *
+ * Prices are **estimated** published list prices (USD per 1K tokens) for the
+ * pinned models, and drift over time. Update this table whenever the model pins
+ * change (AI-06 / CV9.E2.S12), on both engines in the same commit. An unknown
+ * model yields `null` -- never a silent `0` -- so unpriced spend stays visibly
+ * unpriced rather than looking free.
+ */
+
+export interface ModelPrice {
+  /** USD per 1K prompt tokens. */
+  readonly promptPer1k: number;
+  /** USD per 1K completion tokens. */
+  readonly completionPer1k: number;
+}
+
+/** Estimated OpenRouter list prices (USD / 1K tokens). Verify on every pin change. */
+export const MODEL_PRICES: Readonly<Record<string, ModelPrice>> = {
+  // Extraction pin -- google/gemini-2.5-flash-lite: ~$0.10/M in, ~$0.40/M out.
+  "google/gemini-2.5-flash-lite": { promptPer1k: 0.0001, completionPer1k: 0.0004 },
+  // Embedding pin -- openai/text-embedding-3-small: ~$0.02/M, no completion side.
+  "openai/text-embedding-3-small": { promptPer1k: 0.00002, completionPer1k: 0.0 },
+};
+
+/**
+ * Estimate the USD cost of one call from its model and token usage.
+ *
+ * Returns `null` when the model is not in the price table or when prompt usage
+ * is missing -- both mean the cost is genuinely unknown, and `null` keeps it out
+ * of any sum rather than understating spend as `0`. Missing completion tokens
+ * are treated as zero completion (some providers omit the field on empty
+ * completions, and every embedding call omits it by nature).
+ *
+ * `undefined` is folded into Python's `None`: TS call sites carry
+ * `number | null | undefined`, and both absences must mean "unknown", never
+ * "zero tokens".
+ *
+ * The arithmetic mirrors Python's operation order exactly -- `(prompt / 1000) *
+ * price + (completion / 1000) * price` -- because the golden asserts bit-equal
+ * doubles, not an epsilon.
+ */
+export function computeCost(
+  model: string,
+  promptTokens: number | null | undefined,
+  completionTokens: number | null | undefined,
+): number | null {
+  const price = MODEL_PRICES[model];
+  if (price === undefined || promptTokens === null || promptTokens === undefined) return null;
+  const completion = completionTokens ?? 0;
+  return (promptTokens / 1000) * price.promptPer1k + (completion / 1000) * price.completionPer1k;
+}

package/ts/src/providers/credits.ts

@@ -0,0 +1,204 @@
+import { type ProviderConfig, resolveLlmTimeoutMs, resolveProviderConfig } from "./config.ts";
+import { createOpenRouterClient, LlmTransportError, type OpenRouterClient } from "./openrouter.ts";
+import { loadReplayFixture } from "./replay.ts";
+
+export interface CreditInfo {
+  totalCredits: number;
+  totalUsage: number;
+  balance: number;
+}
+
+export interface CreditProvider {
+  getCredits(): Promise<CreditInfo>;
+  fetchGenerationCost(generationId: string): Promise<number | null>;
+}
+
+export interface ReplayCreditFixture {
+  kind: "credits";
+  credits: CreditInfo;
+  generationCosts?: Record<string, number | null>;
+}
+
+export class ReplayCreditProvider implements CreditProvider {
+  private readonly fixture: ReplayCreditFixture;
+
+  constructor(fixture: ReplayCreditFixture) {
+    this.fixture = fixture;
+  }
+
+  async getCredits(): Promise<CreditInfo> {
+    return this.fixture.credits;
+  }
+
+  async fetchGenerationCost(generationId: string): Promise<number | null> {
+    return this.fixture.generationCosts?.[generationId] ?? null;
+  }
+}
+
+export async function loadReplayCreditProvider(path: string): Promise<ReplayCreditProvider> {
+  const fixture = await loadReplayFixture(path);
+  assertReplayCreditFixture(fixture);
+  return new ReplayCreditProvider(fixture);
+}
+
+export function assertReplayCreditFixture(value: unknown): asserts value is ReplayCreditFixture {
+  if (!isRecord(value) || value.kind !== "credits") {
+    throw new Error("credits replay fixture must declare kind='credits'");
+  }
+  if (!isCreditInfo(value.credits)) {
+    throw new Error("credits replay fixture must include numeric credits");
+  }
+  if (value.generationCosts !== undefined && !isRecord(value.generationCosts)) {
+    throw new Error("credits replay fixture generationCosts must be an object");
+  }
+}
+
+function isCreditInfo(value: unknown): value is CreditInfo {
+  return (
+    isRecord(value) &&
+    typeof value.totalCredits === "number" &&
+    typeof value.totalUsage === "number" &&
+    typeof value.balance === "number"
+  );
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+// --- Live credits and generation cost (CV22.DS8.US3) ------------------------
+
+/** Python's `fetch_generation_cost(retries=4)`: attempts 0..4, five in all. */
+const GENERATION_COST_ATTEMPTS = 5;
+
+export interface LiveCreditProviderOptions {
+  env?: Record<string, string | undefined>;
+  /** Injectable for tests; no test in this repo may reach the network. */
+  createClient?: (config: ProviderConfig) => OpenRouterClient;
+  /** Injectable for tests so the generation poll does not really sleep. */
+  sleep?: (ms: number) => Promise<void>;
+}
+
+/**
+ * The live credit provider, mirroring Python's `get_credits` and
+ * `fetch_generation_cost`.
+ *
+ * Both are plain `urlopen` GETs in Python, and both are load-bearing for
+ * `consult`: the balance bar after every answer, and the real cost of the call
+ * that the ledger prefers over the static estimate.
+ *
+ * Two properties are worth stating because they are easy to get wrong:
+ *
+ * 1. **The generation poll is not a transport retry.** OpenRouter exposes
+ *    usage a few seconds after the completion, so Python asks up to five
+ *    times with 1/2/3/4s between attempts and swallows every error. Each
+ *    attempt is therefore sent with `maxRetries: 0` -- letting the transport
+ *    retry inside the poll would multiply the two budgets into ~15 requests
+ *    for a number that is optional by design.
+ * 2. **Failure is `null`, never a throw.** Python returns None and the caller
+ *    prints no cost line. A cost lookup must not be able to fail a command
+ *    that already succeeded and was already paid for.
+ */
+export class LiveCreditProvider implements CreditProvider {
+  private readonly env: Record<string, string | undefined>;
+  private readonly createClient: (config: ProviderConfig) => OpenRouterClient;
+  private readonly sleep: (ms: number) => Promise<void>;
+  private client: OpenRouterClient | null = null;
+
+  constructor(options: LiveCreditProviderOptions = {}) {
+    this.env = options.env ?? process.env;
+    this.createClient = options.createClient ?? ((config) => createOpenRouterClient(config));
+    this.sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  }
+
+  async getCredits(): Promise<CreditInfo> {
+    const body = await this.resolveClient().getJson("/credits", {
+      timeoutMs: this.readTimeoutMs(),
+      // Python makes exactly one request here and lets the error surface.
+      maxRetries: 0,
+    });
+    const data = isRecord(body) && isRecord(body.data) ? body.data : null;
+    if (!data) {
+      // Python indexes `["data"]` unguarded: a response without it is a
+      // KeyError, not a zero balance. Reporting R$ 0.00 for a malformed
+      // response would read as "you are out of credits".
+      throw new LlmTransportError("malformed_output", "credits response carried no data object");
+    }
+    const totalCredits = readAmount(data.total_credits, "total_credits");
+    const totalUsage = readAmount(data.total_usage, "total_usage");
+    return { totalCredits, totalUsage, balance: totalCredits - totalUsage };
+  }
+
+  async fetchGenerationCost(generationId: string): Promise<number | null> {
+    // The id comes back from the provider and goes into a URL. Same provider,
+    // so the realistic risk is small -- but it is still untrusted input
+    // crossing into a request line, and Python would simply have built a
+    // broken URL and returned None (CV22.DS8.US3 plan review, security).
+    if (!isWellFormedGenerationId(generationId)) return null;
+    const path = `/generation?id=${encodeURIComponent(generationId)}`;
+
+    for (let attempt = 0; attempt < GENERATION_COST_ATTEMPTS; attempt += 1) {
+      // Python: `if attempt > 0: time.sleep(attempt)` -- 1s, 2s, 3s, 4s.
+      if (attempt > 0) await this.sleep(attempt * 1000);
+      const cost = await this.readGenerationCost(path);
+      if (cost !== null) return cost;
+    }
+    return null;
+  }
+
+  /** One poll attempt. Every failure is swallowed, exactly as Python's is. */
+  private async readGenerationCost(path: string): Promise<number | null> {
+    try {
+      const body = await this.resolveClient().getJson(path, {
+        timeoutMs: this.readTimeoutMs(),
+        maxRetries: 0,
+      });
+      const data = isRecord(body) && isRecord(body.data) ? body.data : {};
+      const cost = data.total_cost;
+      // Python: `if cost is not None: return float(cost)`. A genuine zero is a
+      // real answer, so truthiness would turn free calls into "unknown".
+      if (cost === null || cost === undefined) return null;
+      const parsed = Number(cost);
+      // `float(cost)` raises inside Python's try for a non-numeric string, so
+      // the loop simply continues.
+      return Number.isFinite(parsed) ? parsed : null;
+    } catch {
+      return null;
+    }
+  }
+
+  private resolveClient(): OpenRouterClient {
+    this.client ??= this.createClient(resolveProviderConfig("openrouter", { env: this.env }));
+    return this.client;
+  }
+
+  /**
+   * Python bounds neither GET. TypeScript bounds both at the embedding tier --
+   * the tier Python itself uses for its other cheap GET (`/models`) -- so a
+   * hung connection cannot park an interactive command. Recorded in
+   * `docs/project/decisions.md`.
+   */
+  private readTimeoutMs(): number {
+    return resolveLlmTimeoutMs("embedding", { env: this.env });
+  }
+}
+
+/**
+ * Python's `data.get("total_credits", 0)` followed by a subtraction: an absent
+ * field is zero, a present non-numeric field is a TypeError.
+ */
+function readAmount(value: unknown, field: string): number {
+  if (value === undefined || value === null) return 0;
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    throw new LlmTransportError(
+      "malformed_output",
+      `credits response carried a non-numeric ${field}`,
+    );
+  }
+  return value;
+}
+
+/** Non-empty, and nothing that would have to be escaped out of a request line. */
+function isWellFormedGenerationId(generationId: string): boolean {
+  return generationId.length > 0 && !/\s/.test(generationId);
+}

package/ts/src/providers/embedding.ts

@@ -0,0 +1,321 @@
+import {
+  type ProviderConfig,
+  ProviderConfigError,
+  resolveEmbeddingModel,
+  resolveLlmMaxRetries,
+  resolveLlmTimeoutMs,
+  resolveProviderConfig,
+} from "./config.ts";
+import { createOpenRouterClient, LlmTransportError, type OpenRouterClient } from "./openrouter.ts";
+import { loadReplayFixture } from "./replay.ts";
+
+/**
+ * One embedding call's outcome: the vector, plus what it cost to get it.
+ *
+ * The usage travels with the vector rather than through a side channel so the
+ * ledger row can be priced the way Python prices it (`build_llm_logger` reads
+ * `response.usage.prompt_tokens`). `null` means the provider did not report
+ * usage -- genuinely unknown, never zero. This mirrors `LlmProvider.complete`,
+ * which has always returned tokens alongside content.
+ */
+export interface EmbeddingResult {
+  vector: readonly number[];
+  promptTokens: number | null;
+}
+
+export interface EmbeddingProvider {
+  embed(text: string): Promise<EmbeddingResult>;
+}
+
+// Mirrors Python's EMBEDDING_DIMENSIONS / MEMORY_EMBEDDING_ATTEMPTS /
+// MEMORY_EMBEDDING_RETRY_BACKOFF exactly (CV9.E2.S1, AI-06 pin family).
+export const EMBEDDING_DIMENSIONS = 1536;
+export const DEFAULT_EMBEDDING_ATTEMPTS = 3;
+export const DEFAULT_EMBEDDING_RETRY_BACKOFF_MS = 500;
+
+export class EmbeddingError extends Error {
+  readonly permanent: boolean;
+  constructor(message: string, options: { permanent?: boolean } = {}) {
+    super(message);
+    this.name = "EmbeddingError";
+    this.permanent = options.permanent ?? false;
+  }
+}
+
+export interface EmbeddingAttemptInfo {
+  text: string;
+  vector: readonly number[] | null;
+  latencyMs: number;
+  /** Usage for this round-trip, when the provider reported any (CV22.DS8.US1). */
+  promptTokens: number | null;
+}
+
+export interface GenerateEmbeddingSafelyOptions {
+  attempts?: number;
+  backoffMs?: number;
+  expectedDimensions?: number;
+  /** Injectable for fast, deterministic tests -- no real backoff wait. */
+  sleep?: (ms: number) => Promise<void>;
+  /** Fires once per real API round-trip (not for the empty-input guard,
+   * matching Python not logging before any call is attempted). Callers wire
+   * this to logLlmCall for ledger observability (AI-09/D-003). */
+  onAttempt?: (info: EmbeddingAttemptInfo) => void;
+}
+
+const defaultSleep = (ms: number): Promise<void> =>
+  new Promise((resolve) => setTimeout(resolve, ms));
+
+/**
+ * Generate an embedding with Python's exact three-way failure taxonomy
+ * (`generate_embedding`, CV9.E2.S1):
+ *
+ * - empty/whitespace input -> permanent `EmbeddingError`, before any provider
+ *   call (no doomed spend);
+ * - a well-formed call that resolves to an empty vector -> TRANSIENT, retried
+ *   up to `attempts` with backoff;
+ * - a resolved vector of the wrong length -> PERMANENT, fails immediately
+ *   with a `MEMORY_EMBEDDING_MODEL` diagnostic, never retried (a config error
+ *   must never be mislabeled "failed after N attempts");
+ * - the provider call REJECTS -> TERMINAL, wrapped once, NOT retried at this
+ *   layer. The underlying client/SDK is expected to have already retried
+ *   transient transport failures itself (AI-01 philosophy); retrying here too
+ *   would double the retry budget for exactly the failures already covered.
+ *   This is the one branch most likely to be inverted by accident -- it is
+ *   deliberately NOT the same as the empty-response transient case above.
+ *
+ * No fake or zero vector is ever returned: every path yields a validated
+ * embedding or throws.
+ */
+export async function generateEmbeddingSafely(
+  provider: EmbeddingProvider,
+  text: string,
+  options: GenerateEmbeddingSafelyOptions = {},
+): Promise<readonly number[]> {
+  const attempts = options.attempts ?? DEFAULT_EMBEDDING_ATTEMPTS;
+  const backoffMs = options.backoffMs ?? DEFAULT_EMBEDDING_RETRY_BACKOFF_MS;
+  const expectedDimensions = options.expectedDimensions ?? EMBEDDING_DIMENSIONS;
+  const sleep = options.sleep ?? defaultSleep;
+
+  if (!text?.trim()) {
+    throw new EmbeddingError("Cannot embed empty text.", { permanent: true });
+  }
+
+  let lastError: EmbeddingError | undefined;
+  for (let attempt = 1; attempt <= attempts; attempt += 1) {
+    const t0 = Date.now();
+    let result: EmbeddingResult;
+    try {
+      result = await provider.embed(text);
+    } catch (error) {
+      // A missing/invalid key is a CONFIGURATION failure, not a call: Python
+      // raises before its attempt loop, so no `llm_calls` row exists for it.
+      // Firing onAttempt here would give TS an unpriced row where Python has
+      // none -- invisible in every replay test, because replay always has a
+      // "key" (CV22.DS8.US1 plan review, engineer).
+      if (error instanceof ProviderConfigError) throw error;
+      // Provider/transport exception: terminal at this layer, not retried.
+      options.onAttempt?.({ text, vector: null, latencyMs: Date.now() - t0, promptTokens: null });
+      const detail = error instanceof Error ? error.message : String(error);
+      throw new EmbeddingError(`Embedding provider call failed: ${detail}`);
+    }
+    const { vector, promptTokens } = result;
+    if (!vector || vector.length === 0) {
+      // Well-formed call, empty payload: transient, retry within budget.
+      options.onAttempt?.({ text, vector: null, latencyMs: Date.now() - t0, promptTokens });
+      lastError = new EmbeddingError("Empty embedding payload received");
+      if (attempt < attempts) await sleep(backoffMs * attempt);
+      continue;
+    }
+    if (vector.length !== expectedDimensions) {
+      options.onAttempt?.({ text, vector: null, latencyMs: Date.now() - t0, promptTokens });
+      throw new EmbeddingError(
+        `Embedding dimension mismatch: expected ${expectedDimensions}, got ${vector.length}. ` +
+          "Check MEMORY_EMBEDDING_MODEL -- a model whose vectors are not " +
+          `${expectedDimensions}-dim cannot be stored in this corpus.`,
+        { permanent: true },
+      );
+    }
+    options.onAttempt?.({ text, vector, latencyMs: Date.now() - t0, promptTokens });
+    return vector;
+  }
+  throw new EmbeddingError(
+    `No embedding generated after ${attempts} attempts: ${lastError?.message}`,
+  );
+}
+
+/** Provenance for a vector produced by the currently configured embedding pin
+ * (CV9.E2.S17, AI-07 shape-guard companion). Records the *configured* model,
+ * matching Python's own comment: equals the generation model unless the pin
+ * is hot-swapped mid-process. */
+export function embeddingProvenance(): { embedding_model: string; embedding_dimensions: number } {
+  return { embedding_model: resolveEmbeddingModel(), embedding_dimensions: EMBEDDING_DIMENSIONS };
+}
+
+/**
+ * Merge current embedding provenance into a metadata JSON string. Foreign
+ * keys are preserved; provenance keys are authoritative (a re-embed must be
+ * able to overwrite a stale model). Never throws on malformed or non-object
+ * existing metadata -- falls back to a fresh object, so a bad metadata value
+ * can never fail a memory write (mirrors Python's add_embedding_provenance).
+ */
+export function addEmbeddingProvenance(metadata: string | null | undefined): string {
+  let base: Record<string, unknown> = {};
+  if (metadata) {
+    try {
+      const parsed: unknown = JSON.parse(metadata);
+      if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+        base = parsed as Record<string, unknown>;
+      }
+    } catch {
+      base = {};
+    }
+  }
+  return JSON.stringify({ ...base, ...embeddingProvenance() });
+}
+
+export interface ReplayEmbeddingFixture {
+  kind: "embedding";
+  request?: {
+    model?: string;
+    input_sha256?: string;
+  };
+  response: {
+    embedding: readonly number[];
+    /** Optional; DS5-era fixtures predate usage and stay valid without it. */
+    usage?: { prompt_tokens?: number };
+  };
+}
+
+export class ReplayEmbeddingProvider implements EmbeddingProvider {
+  private readonly fixture: ReplayEmbeddingFixture;
+
+  constructor(fixture: ReplayEmbeddingFixture) {
+    this.fixture = fixture;
+  }
+
+  async embed(_text: string): Promise<EmbeddingResult> {
+    // Fixtures may pin usage; most predate it. `null` is the honest answer --
+    // a replayed call cost nothing, so pricing it would be a fiction.
+    return {
+      vector: this.fixture.response.embedding,
+      promptTokens: this.fixture.response.usage?.prompt_tokens ?? null,
+    };
+  }
+}
+
+export interface LiveEmbeddingProviderOptions {
+  env?: Record<string, string | undefined>;
+  /** Injectable for tests; no test in this repo may reach the network. */
+  createClient?: (config: ProviderConfig) => OpenRouterClient;
+}
+
+/**
+ * The live embedding provider (CV22.DS8.US1).
+ *
+ * Two properties are load-bearing and easy to get backwards:
+ *
+ * 1. **Config resolves lazily**, on the first `embed()`. Resolving in the
+ *    constructor would throw outside `searchMemoriesWithStatus`'s try block,
+ *    crashing `memories --search` for an install with no key instead of
+ *    degrading to lexical-only the way Python does.
+ * 2. **An empty payload returns an EMPTY VECTOR, it does not throw.** Python's
+ *    `_extract_embedding` treats "no data"/"empty payload" as transient and
+ *    lets `generate_embedding` retry; at the `generateEmbeddingSafely` layer a
+ *    thrown error is TERMINAL. Throwing here would silently convert a
+ *    retryable emptiness into a hard failure -- the exact taxonomy inversion
+ *    the AI-18 contract exists to prevent.
+ *
+ * Dimension is deliberately NOT checked here: `generateEmbeddingSafely` owns
+ * the permanent mismatch diagnostic (AI-07), and duplicating it would give the
+ * corpus two places to disagree about what fits in it.
+ */
+export class LiveEmbeddingProvider implements EmbeddingProvider {
+  private readonly env: Record<string, string | undefined>;
+  private readonly createClient: (config: ProviderConfig) => OpenRouterClient;
+  private client: OpenRouterClient | null = null;
+
+  constructor(options: LiveEmbeddingProviderOptions = {}) {
+    this.env = options.env ?? process.env;
+    this.createClient = options.createClient ?? ((config) => createOpenRouterClient(config));
+  }
+
+  async embed(text: string): Promise<EmbeddingResult> {
+    const client = this.resolveClient();
+    const body = await client.postJson(
+      "/embeddings",
+      { input: text, model: resolveEmbeddingModel({ env: this.env }) },
+      {
+        timeoutMs: resolveLlmTimeoutMs("embedding", { env: this.env }),
+        maxRetries: resolveLlmMaxRetries({ env: this.env }),
+      },
+    );
+    return interpretEmbeddingResponse(body);
+  }
+
+  private resolveClient(): OpenRouterClient {
+    // Throws ProviderConfigError when the key is absent -- inside embed(), so
+    // the caller's degraded path can catch it.
+    this.client ??= this.createClient(resolveProviderConfig("openrouter", { env: this.env }));
+    return this.client;
+  }
+}
+
+/** Mirrors Python's `_extract_embedding` branch for branch. */
+function interpretEmbeddingResponse(body: unknown): EmbeddingResult {
+  if (!isRecord(body)) {
+    throw new LlmTransportError("malformed_output", "embedding response was not an object");
+  }
+  const promptTokens = readPromptTokens(body.usage);
+  const data = body.data;
+  // No `data` at all, or an empty list: transient (Python: "No embedding data
+  // received"). Reported as an empty vector so the retry budget applies.
+  if (data === undefined || data === null || (Array.isArray(data) && data.length === 0)) {
+    return { vector: [], promptTokens };
+  }
+  if (!Array.isArray(data) || !isRecord(data[0])) {
+    throw new LlmTransportError("malformed_output", "embedding response data was not a list");
+  }
+  const payload = data[0].embedding;
+  if (payload === undefined || payload === null || (Array.isArray(payload) && payload.length === 0))
+    return { vector: [], promptTokens };
+  if (!Array.isArray(payload)) {
+    throw new LlmTransportError("malformed_output", "embedding payload was not a list");
+  }
+  if (!payload.every((value) => typeof value === "number" && Number.isFinite(value))) {
+    // A NaN or a string in the vector would be written to the corpus as a BLOB
+    // and poison every future cosine against it.
+    throw new LlmTransportError("malformed_output", "embedding payload was not finite numbers");
+  }
+  return { vector: payload as readonly number[], promptTokens };
+}
+
+function readPromptTokens(usage: unknown): number | null {
+  if (!isRecord(usage)) return null;
+  const raw = usage.prompt_tokens;
+  return typeof raw === "number" && Number.isInteger(raw) ? raw : null;
+}
+
+export async function loadReplayEmbeddingProvider(path: string): Promise<ReplayEmbeddingProvider> {
+  const fixture = await loadReplayFixture(path);
+  assertReplayEmbeddingFixture(fixture);
+  return new ReplayEmbeddingProvider(fixture);
+}
+
+export function assertReplayEmbeddingFixture(
+  value: unknown,
+): asserts value is ReplayEmbeddingFixture {
+  if (!isRecord(value) || value.kind !== "embedding") {
+    throw new Error("embedding replay fixture must declare kind='embedding'");
+  }
+  const response = value.response;
+  if (!isRecord(response) || !Array.isArray(response.embedding)) {
+    throw new Error("embedding replay fixture must include response.embedding[]");
+  }
+  if (!response.embedding.every((item) => typeof item === "number" && Number.isFinite(item))) {
+    throw new Error("embedding replay fixture response.embedding must contain only finite numbers");
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}