@openparachute/vault 0.7.2 → 0.7.3-rc.10

package/src/contract-honest-queries.test.ts

@@ -248,6 +248,48 @@ describe("contract: honest queries — warnings channel (#550)", () => {
   });
 });
 
+describe("contract: truncation-honesty warning (V1.3)", () => {
+  it("a structured non-cursor list that hits its limit carries a `truncated` warning", async () => {
+    for (let i = 0; i < 3; i++) await store.createNote(`note ${i}`);
+    const res = await getNotes("limit=2");
+    expect(res.status).toBe(200);
+    const body: any[] = await res.json();
+    expect(body.length).toBe(2); // the limit itself is unaffected — warning only
+    const warnings = decodeWarningsHeader(res);
+    expect(warnings).not.toBeNull();
+    const truncated = warnings!.find((w) => w.code === "truncated");
+    expect(truncated).toBeDefined();
+    expect(truncated.limit).toBe(2);
+  });
+
+  it("an under-limit list carries no `truncated` warning", async () => {
+    await store.createNote("only one");
+    const res = await getNotes("limit=50");
+    expect(res.status).toBe(200);
+    const warnings = decodeWarningsHeader(res);
+    expect(warnings?.some((w) => w.code === "truncated") ?? false).toBe(false);
+  });
+
+  it("cursor mode never carries a `truncated` warning — `next_cursor` is already the honest signal", async () => {
+    for (let i = 0; i < 3; i++) await store.createNote(`note ${i}`);
+    const res = await getNotes("limit=2&cursor=");
+    expect(res.status).toBe(200);
+    const body: any = await res.json();
+    expect(body.notes.length).toBe(2);
+    expect(typeof body.next_cursor).toBe("string");
+    expect((body.warnings ?? []).some((w: any) => w.code === "truncated")).toBe(false);
+  });
+
+  it("MCP query-notes mirrors the same truncated warning on a limit-hit non-cursor list", async () => {
+    for (let i = 0; i < 3; i++) await store.createNote(`mcp note ${i}`);
+    const tools = generateMcpTools(store);
+    const query = tools.find((t) => t.name === "query-notes")!;
+    const result = (await query.execute({ limit: 2 })) as any;
+    expect(result.warnings).toBeDefined();
+    expect(result.warnings.some((w: any) => w.code === "truncated" && w.limit === 2)).toBe(true);
+  });
+});
+
 describe("contract: honest queries — cursor bootstrap (#550, the P1)", () => {
   it("an empty cursor (`?cursor=`) engages the {notes, next_cursor} envelope on the VERY FIRST call, and the returned next_cursor sees only notes written after it", async () => {
     const n1 = await store.createNote("existing note");
@@ -410,3 +452,49 @@ describe("contract: honest queries — find-path hydration (#550, additive)", ()
     ]);
   });
 });
+
+describe("contract: metadata always present on the wire (V1.1)", () => {
+  it("GET /api/notes?id= on a metadata-less note carries `metadata: {}`, not an absent key", async () => {
+    const note = await store.createNote("No metadata here");
+    const res = await getNotes(`id=${note.id}`);
+    expect(res.status).toBe(200);
+    const body: any = await res.json();
+    expect(body).toHaveProperty("metadata");
+    expect(body.metadata).toEqual({});
+    // `tags` has always been unconditionally present — confirm it still is.
+    expect(body.tags).toEqual([]);
+  });
+
+  it("GET /api/notes (list) carries `metadata: {}` on metadata-less entries", async () => {
+    await store.createNote("List entry, no metadata");
+    const res = await getNotes("");
+    expect(res.status).toBe(200);
+    const body: any = await res.json();
+    expect(Array.isArray(body)).toBe(true);
+    expect(body.length).toBeGreaterThan(0);
+    for (const entry of body) {
+      expect(entry).toHaveProperty("metadata");
+      expect(entry.metadata).toEqual({});
+    }
+  });
+
+  it("GET /api/notes?search= carries `metadata: {}` on metadata-less results", async () => {
+    await store.createNote("Findable via search, no metadata");
+    const res = await getNotes("search=Findable");
+    expect(res.status).toBe(200);
+    const body: any = await res.json();
+    expect(Array.isArray(body)).toBe(true);
+    expect(body.length).toBeGreaterThan(0);
+    for (const entry of body) {
+      expect(entry).toHaveProperty("metadata");
+      expect(entry.metadata).toEqual({});
+    }
+  });
+
+  it("a note WITH real metadata is unaffected — the fix only changes the empty case", async () => {
+    const note = await store.createNote("Has metadata", { metadata: { source: "import" } });
+    const res = await getNotes(`id=${note.id}`);
+    const body: any = await res.json();
+    expect(body.metadata).toEqual({ source: "import" });
+  });
+});

package/src/contract-search.test.ts

@@ -305,6 +305,32 @@ describe("contract: search — escaping edge cases, tag-scope, warnings (#551)",
     expect(warnings!.some((w: any) => w.code === "ignored_param" && w.param === "search_mode")).toBe(true);
   });
 
+  it("offset alongside search is a no-op that surfaces an ignored_param warning, results unchanged (V1.2)", async () => {
+    await store.createNote("findable one", { tags: ["probe"] });
+    await store.createNote("findable two", { tags: ["probe"] });
+
+    const plain = await search("search=findable&tag=probe");
+    const withOffset = await search("search=findable&tag=probe&offset=1");
+    expect(withOffset.status).toBe(200);
+
+    const plainBody = await bodyOf(plain);
+    const offsetBody = await bodyOf(withOffset);
+    // Page 1 either way — offset has no effect on FTS5 relevance ordering.
+    expect(offsetBody.map((n: any) => n.id).sort()).toEqual(plainBody.map((n: any) => n.id).sort());
+
+    const warnings = decodeWarningsHeader(withOffset);
+    expect(warnings).not.toBeNull();
+    expect(warnings!.some((w: any) => w.code === "ignored_param" && w.param === "offset")).toBe(true);
+
+    // No search → no warning (offset only means nothing UNDER search; the
+    // structured-query path honors it for real).
+    const structuredNoWarning = await search("tag=probe&offset=1");
+    const structuredWarnings = decodeWarningsHeader(structuredNoWarning);
+    expect(
+      structuredWarnings?.some((w: any) => w.code === "ignored_param" && w.param === "offset") ?? false,
+    ).toBe(false);
+  });
+
   it("an unrecognized search_mode value is a structured 400 invalid_query", async () => {
     const res = await search("search=widgets&search_mode=bogus");
     expect(res.status).toBe(400);
@@ -460,6 +486,21 @@ describe("contract: search — MCP parity (#551)", () => {
     expect(result.warnings.some((w: any) => w.code === "ignored_param" && w.param === "search_mode")).toBe(true);
   });
 
+  it("query-notes: offset alongside search is a no-op that surfaces an ignored_param warning (V1.2)", async () => {
+    await store.createNote("mcp findable", { tags: ["probe"] });
+    const tools = generateMcpTools(store);
+    const query = tools.find((t) => t.name === "query-notes")!;
+    const result = (await query.execute({ search: "findable", offset: 5 })) as any;
+    expect(result.warnings).toBeDefined();
+    expect(result.warnings.some((w: any) => w.code === "ignored_param" && w.param === "offset")).toBe(true);
+
+    // Structured query (no search) — offset is honored for real, no warning.
+    const structured = (await query.execute({ tag: "probe", offset: 0 })) as any;
+    expect(
+      (structured.warnings ?? []).some((w: any) => w.code === "ignored_param" && w.param === "offset"),
+    ).toBe(false);
+  });
+
   it("query-notes: search_mode:\"advanced\" + malformed syntax throws a structured invalid_search_syntax error", async () => {
     const tools = generateMcpTools(store);
     const query = tools.find((t) => t.name === "query-notes")!;

package/src/embedding/capability.test.ts

@@ -0,0 +1,33 @@
+import { describe, test, expect } from "bun:test";
+import { resolveEmbeddingCapability } from "./capability.ts";
+import type { EmbeddingProvider, EmbedInput, EmbedResult, ProviderAvailability } from "../../core/src/embedding/provider.ts";
+
+class FakeProvider implements EmbeddingProvider {
+  readonly name = "fake";
+  readonly model = "fake-model";
+  readonly dims = 4;
+  constructor(private ok: boolean, private reason?: string) {}
+  async embed(_input: EmbedInput): Promise<EmbedResult> {
+    return { vectors: [], model: this.model, dims: this.dims };
+  }
+  async available(): Promise<ProviderAvailability> {
+    return this.ok ? { ok: true } : { ok: false, reason: this.reason };
+  }
+}
+
+describe("resolveEmbeddingCapability", () => {
+  test("enabled:true with provider/model when the provider is available", async () => {
+    const cap = await resolveEmbeddingCapability(new FakeProvider(true));
+    expect(cap).toEqual({ enabled: true, provider: "fake", model: "fake-model" });
+  });
+
+  test("enabled:false with no provider/model when unavailable", async () => {
+    const cap = await resolveEmbeddingCapability(new FakeProvider(false, "not ready"));
+    expect(cap).toEqual({ enabled: false });
+  });
+
+  test("enabled:false when no provider at all (EMBEDDINGS_ENABLED=false, M1) — no available() call needed", async () => {
+    const cap = await resolveEmbeddingCapability(undefined);
+    expect(cap).toEqual({ enabled: false });
+  });
+});

package/src/embedding/capability.ts

@@ -0,0 +1,34 @@
+/**
+ * Embedding capability flag (semantic search MVP — EXPERIMENTAL).
+ * Mirrors `src/transcription/capability.ts` exactly: the vault landing
+ * (`GET /vault/<name>/api/vault`) surfaces an `embeddings` capability so a
+ * surface (or Adam's Claude) can tell, before ever calling `query-notes
+ * { semantic: true }`, whether meaning-based search is actually possible
+ * on this vault right now — `enabled` is true only when a provider is
+ * configured AND its `available()` probe passes.
+ */
+
+import type { EmbeddingProvider } from "../../core/src/embedding/provider.ts";
+
+export interface EmbeddingCapability {
+  /** True when a provider is configured AND available. `query-notes { semantic: true }` throws `semantic_unavailable` when false. */
+  enabled: boolean;
+  /** The active provider's name (e.g. "onnx-transformers", "external-api"). Omitted when disabled. */
+  provider?: string;
+  /** The active provider's model (e.g. "bge-small-en-v1.5", "bge-m3"). Omitted when disabled. */
+  model?: string;
+}
+
+/**
+ * `provider` is `undefined` when `EMBEDDINGS_ENABLED=false` (the off
+ * switch — see `select.ts`'s `buildEmbeddingProvider`) — resolves to
+ * `{enabled: false}` directly, no `available()` probe to call.
+ */
+export async function resolveEmbeddingCapability(
+  provider: EmbeddingProvider | undefined,
+): Promise<EmbeddingCapability> {
+  if (!provider) return { enabled: false };
+  const avail = await provider.available();
+  if (!avail.ok) return { enabled: false };
+  return { enabled: true, provider: provider.name, model: provider.model };
+}

package/src/embedding/external-api.test.ts

@@ -0,0 +1,154 @@
+import { describe, test, expect } from "bun:test";
+import { ExternalApiEmbeddingProvider } from "./external-api.ts";
+import { EmbeddingError } from "../../core/src/embedding/provider.ts";
+
+function jsonResponse(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json" } });
+}
+
+function recordingFetch(response: Response | (() => Response | Promise<Response>)): {
+  fetchImpl: typeof fetch;
+  calls: Array<{ url: string; init: RequestInit | undefined }>;
+} {
+  const calls: Array<{ url: string; init: RequestInit | undefined }> = [];
+  const fetchImpl = (async (url: RequestInfo | URL, init?: RequestInit) => {
+    calls.push({ url: String(url), init });
+    return typeof response === "function" ? await response() : response;
+  }) as typeof fetch;
+  return { fetchImpl, calls };
+}
+
+describe("ExternalApiEmbeddingProvider.available", () => {
+  test("ok:true when a URL is configured", async () => {
+    const p = new ExternalApiEmbeddingProvider({ url: "http://localhost:11434/v1", model: "bge-m3" });
+    expect(await p.available()).toEqual({ ok: true });
+  });
+
+  test("ok:false with a reason when no URL is configured", async () => {
+    const p = new ExternalApiEmbeddingProvider({ model: "bge-m3" });
+    const avail = await p.available();
+    expect(avail.ok).toBe(false);
+    expect(avail.reason).toBeTruthy();
+  });
+
+  test("ok:false for an empty/whitespace URL", async () => {
+    const p = new ExternalApiEmbeddingProvider({ url: "   ", model: "bge-m3" });
+    expect((await p.available()).ok).toBe(false);
+  });
+
+  test("name is stable 'external-api'", () => {
+    expect(new ExternalApiEmbeddingProvider({ url: "http://x", model: "bge-m3" }).name).toBe("external-api");
+  });
+});
+
+describe("ExternalApiEmbeddingProvider.embed — happy path", () => {
+  test("POSTs { model, input } to {url}/embeddings and returns ordered vectors", async () => {
+    const { fetchImpl, calls } = recordingFetch(
+      jsonResponse({
+        data: [
+          { embedding: [1, 2, 3], index: 0 },
+          { embedding: [4, 5, 6], index: 1 },
+        ],
+        model: "bge-m3",
+      }),
+    );
+    const p = new ExternalApiEmbeddingProvider({ url: "http://localhost:11434/v1", model: "bge-m3", fetchImpl });
+    const result = await p.embed({ texts: ["hello", "world"] });
+
+    expect(calls.length).toBe(1);
+    expect(calls[0].url).toBe("http://localhost:11434/v1/embeddings");
+    const body = JSON.parse(calls[0].init!.body as string);
+    expect(body).toEqual({ model: "bge-m3", input: ["hello", "world"] });
+
+    expect(result.vectors.length).toBe(2);
+    expect(Array.from(result.vectors[0])).toEqual([1, 2, 3]);
+    expect(Array.from(result.vectors[1])).toEqual([4, 5, 6]);
+    expect(result.model).toBe("bge-m3");
+    expect(result.dims).toBe(3);
+  });
+
+  test("reorders by `index` even if the API returns rows out of order", async () => {
+    const { fetchImpl } = recordingFetch(
+      jsonResponse({
+        data: [
+          { embedding: [4, 5, 6], index: 1 },
+          { embedding: [1, 2, 3], index: 0 },
+        ],
+      }),
+    );
+    const p = new ExternalApiEmbeddingProvider({ url: "http://x", model: "m", fetchImpl });
+    const result = await p.embed({ texts: ["a", "b"] });
+    expect(Array.from(result.vectors[0])).toEqual([1, 2, 3]);
+    expect(Array.from(result.vectors[1])).toEqual([4, 5, 6]);
+  });
+
+  test("sends a Bearer header when an apiKey is configured", async () => {
+    const { fetchImpl, calls } = recordingFetch(jsonResponse({ data: [{ embedding: [1], index: 0 }] }));
+    const p = new ExternalApiEmbeddingProvider({ url: "http://x", model: "m", apiKey: "secret-key", fetchImpl });
+    await p.embed({ texts: ["a"] });
+    expect((calls[0].init!.headers as Record<string, string>)["Authorization"]).toBe("Bearer secret-key");
+  });
+
+  test("no Authorization header when no apiKey is configured", async () => {
+    const { fetchImpl, calls } = recordingFetch(jsonResponse({ data: [{ embedding: [1], index: 0 }] }));
+    const p = new ExternalApiEmbeddingProvider({ url: "http://x", model: "m", fetchImpl });
+    await p.embed({ texts: ["a"] });
+    expect((calls[0].init!.headers as Record<string, string>)["Authorization"]).toBeUndefined();
+  });
+
+  test("empty texts array short-circuits with no fetch call", async () => {
+    const { fetchImpl, calls } = recordingFetch(jsonResponse({ data: [] }));
+    const p = new ExternalApiEmbeddingProvider({ url: "http://x", model: "m", fetchImpl });
+    const result = await p.embed({ texts: [] });
+    expect(calls.length).toBe(0);
+    expect(result.vectors).toEqual([]);
+  });
+});
+
+describe("ExternalApiEmbeddingProvider.embed — error mapping", () => {
+  test("throws missing_provider (non-retriable) when no URL is configured", async () => {
+    const p = new ExternalApiEmbeddingProvider({ model: "m" });
+    let caught: unknown;
+    try {
+      await p.embed({ texts: ["x"] });
+    } catch (e) {
+      caught = e;
+    }
+    expect(caught).toBeInstanceOf(EmbeddingError);
+    expect((caught as EmbeddingError).code).toBe("missing_provider");
+    expect((caught as EmbeddingError).retriable).toBe(false);
+  });
+
+  test("4xx is non-retriable", async () => {
+    const { fetchImpl } = recordingFetch(jsonResponse({ error: "bad request" }, 400));
+    const p = new ExternalApiEmbeddingProvider({ url: "http://x", model: "m", fetchImpl });
+    let caught: unknown;
+    try {
+      await p.embed({ texts: ["a"] });
+    } catch (e) {
+      caught = e;
+    }
+    expect(caught).toBeInstanceOf(EmbeddingError);
+    expect((caught as EmbeddingError).retriable).toBe(false);
+    expect((caught as EmbeddingError).httpStatus).toBe(400);
+  });
+
+  test("5xx is retriable", async () => {
+    const { fetchImpl } = recordingFetch(new Response("upstream hiccup", { status: 503 }));
+    const p = new ExternalApiEmbeddingProvider({ url: "http://x", model: "m", fetchImpl });
+    let caught: unknown;
+    try {
+      await p.embed({ texts: ["a"] });
+    } catch (e) {
+      caught = e;
+    }
+    expect(caught).toBeInstanceOf(EmbeddingError);
+    expect((caught as EmbeddingError).retriable).toBe(true);
+  });
+
+  test("a vector-count mismatch throws (defensive — never silently mis-align)", async () => {
+    const { fetchImpl } = recordingFetch(jsonResponse({ data: [{ embedding: [1], index: 0 }] }));
+    const p = new ExternalApiEmbeddingProvider({ url: "http://x", model: "m", fetchImpl });
+    await expect(p.embed({ texts: ["a", "b"] })).rejects.toThrow();
+  });
+});

package/src/embedding/external-api.ts

@@ -0,0 +1,144 @@
+/**
+ * `external-api` — the config-upgrade self-host embedding provider
+ * (semantic search MVP — two-tier self-host shape, Aaron-ratified).
+ *
+ * Speaks the OpenAI-compatible `POST {url}/embeddings` shape:
+ * `{ model, input: string[] }` → `{ data: [{ embedding, index }, ...], model }`.
+ * This one tiny client covers Ollama (the recommended quality tier — `ollama
+ * pull bge-m3`, fully local + private), LM Studio, OpenAI itself, or any
+ * hosted endpoint speaking the same contract — an `EMBEDDING_API_URL` /
+ * `EMBEDDING_API_KEY` / `EMBEDDING_MODEL` env trio, mirroring the existing
+ * `PARACHUTE_GITHUB_*` bring-your-own pattern in `.env`.
+ *
+ * Structurally a sibling of `scribe-http.ts` (same AbortController+timeout
+ * shape, same "no URL configured → available()=false, cheap, no network
+ * probe" contract, same 4xx-terminal/5xx-retriable error mapping) — the
+ * embedding seam clones the transcription seam's provider shape, not just
+ * its interface.
+ *
+ * Config wins over the bundled floor (`onnx-transformers.ts`) when
+ * `EMBEDDING_API_URL` is set — see `src/embedding/select.ts`.
+ */
+
+import {
+  EmbeddingError,
+  type EmbeddingProvider,
+  type EmbedInput,
+  type EmbedResult,
+  type ProviderAvailability,
+} from "../../core/src/embedding/provider.ts";
+
+const DEFAULT_TIMEOUT_MS = 120_000;
+
+export interface ExternalApiEmbeddingProviderOpts {
+  /** Base URL (e.g. `http://localhost:11434/v1`, `https://api.openai.com/v1`). `undefined`/empty → unavailable, non-retriable on embed(). Trailing slash trimmed. */
+  url?: string;
+  /** Bearer token, when the endpoint needs one (OpenAI does; a bare local Ollama typically doesn't). */
+  apiKey?: string;
+  /** Model identifier the endpoint should embed with (e.g. "bge-m3"). */
+  model: string;
+  /** Per-request timeout (ms). Default 120s. */
+  timeoutMs?: number;
+  /** Injection seam for tests; production omits it and uses global `fetch`. */
+  fetchImpl?: typeof fetch;
+}
+
+interface OpenAiEmbeddingRow {
+  embedding: number[];
+  index: number;
+}
+
+interface OpenAiEmbeddingResponse {
+  data: OpenAiEmbeddingRow[];
+  model?: string;
+}
+
+export class ExternalApiEmbeddingProvider implements EmbeddingProvider {
+  readonly name = "external-api";
+  readonly model: string;
+  /** Best-known dims — refined on the first successful embed() call (the model's own response is the ground truth). */
+  dims: number;
+
+  private readonly url: string | undefined;
+  private readonly apiKey: string | undefined;
+  private readonly timeoutMs: number;
+  private readonly fetchImpl: typeof fetch;
+
+  constructor(opts: ExternalApiEmbeddingProviderOpts) {
+    this.url = opts.url?.trim() ? opts.url.trim().replace(/\/$/, "") : undefined;
+    this.apiKey = opts.apiKey;
+    this.model = opts.model;
+    this.dims = 0; // unknown until the first embed() response — see `dims` doc.
+    this.timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.fetchImpl = opts.fetchImpl ?? fetch;
+  }
+
+  /**
+   * Availability is purely "is a URL configured" — no network round-trip
+   * (mirrors `ScribeHttpProvider.available()`; the capability flag reads
+   * this on every `GET /api/vault`, so it must stay cheap).
+   */
+  async available(): Promise<ProviderAvailability> {
+    if (!this.url) {
+      return {
+        ok: false,
+        reason:
+          "no embedding API URL configured (set EMBEDDING_API_URL/EMBEDDING_API_KEY/EMBEDDING_MODEL, e.g. for a local Ollama: EMBEDDING_API_URL=http://localhost:11434/v1)",
+      };
+    }
+    return { ok: true };
+  }
+
+  async embed(input: EmbedInput): Promise<EmbedResult> {
+    if (!this.url) {
+      throw new EmbeddingError("no embedding API URL configured", {
+        code: "missing_provider",
+        retriable: false,
+      });
+    }
+    if (input.texts.length === 0) {
+      return { vectors: [], model: this.model, dims: this.dims };
+    }
+
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      const headers: Record<string, string> = { "Content-Type": "application/json" };
+      if (this.apiKey) headers["Authorization"] = `Bearer ${this.apiKey}`;
+
+      const resp = await this.fetchImpl(`${this.url}/embeddings`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({ model: this.model, input: input.texts }),
+        signal: controller.signal,
+      });
+      if (!resp.ok) {
+        const body = await resp.text().catch(() => "");
+        const retriable = resp.status >= 500;
+        throw new EmbeddingError(`embedding API returned ${resp.status}: ${body.slice(0, 500)}`, {
+          code: "external_api_error",
+          httpStatus: resp.status,
+          retriable,
+        });
+      }
+      const parsed = (await resp.json()) as OpenAiEmbeddingResponse;
+      if (!Array.isArray(parsed.data)) {
+        throw new Error("embedding API response missing `data` array");
+      }
+      // The API contract guarantees `index` order matches input order, but
+      // don't trust it blindly — sort defensively so `vectors[i]` always
+      // corresponds to `input.texts[i]`.
+      const sorted = [...parsed.data].sort((a, b) => a.index - b.index);
+      const vectors = sorted.map((row) => new Float32Array(row.embedding));
+      if (vectors.length !== input.texts.length) {
+        throw new Error(
+          `embedding API returned ${vectors.length} vector(s) for ${input.texts.length} input text(s)`,
+        );
+      }
+      if (vectors[0]) this.dims = vectors[0].length;
+      return { vectors, model: this.model, dims: this.dims };
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+}

package/src/embedding/onnx-transformers.test.ts

@@ -0,0 +1,113 @@
+import { describe, test, expect } from "bun:test";
+import { OnnxTransformersEmbeddingProvider } from "./onnx-transformers.ts";
+import { EmbeddingError } from "../../core/src/embedding/provider.ts";
+
+/**
+ * The real `@huggingface/transformers` pipeline is mocked so no model
+ * download / ONNX runtime call happens in the test suite (same convention
+ * as `onnx-asr.test.ts` mocking its subprocess) — the bun+onnxruntime
+ * end-to-end verdict is verified manually (see this module's doc comment)
+ * and documented in the PR, not re-run on every `bun test`.
+ */
+function fakeLoader(vectorFor: (text: string) => number[]) {
+  return async (_modelId: string) => {
+    return async (text: string, _opts: unknown) => ({ data: new Float32Array(vectorFor(text)) });
+  };
+}
+
+function throwingLoader(message: string) {
+  return async (_modelId: string): Promise<never> => {
+    throw new Error(message);
+  };
+}
+
+describe("OnnxTransformersEmbeddingProvider.available", () => {
+  test("optimistic ok:true before any real load attempt", async () => {
+    const p = new OnnxTransformersEmbeddingProvider({ pipelineLoader: fakeLoader(() => [1, 0]) });
+    expect(await p.available()).toEqual({ ok: true });
+  });
+
+  test("ok:false, non-retriable, once the pipeline load has actually failed", async () => {
+    const p = new OnnxTransformersEmbeddingProvider({ pipelineLoader: throwingLoader("simulated ORT failure") });
+    let caught: unknown;
+    try {
+      await p.embed({ texts: ["x"] });
+    } catch (e) {
+      caught = e;
+    }
+    expect(caught).toBeInstanceOf(EmbeddingError);
+    expect((caught as EmbeddingError).retriable).toBe(false);
+
+    const avail = await p.available();
+    expect(avail.ok).toBe(false);
+    expect(avail.reason).toContain("simulated ORT failure");
+  });
+
+  test("name/model are stable", () => {
+    const p = new OnnxTransformersEmbeddingProvider();
+    expect(p.name).toBe("onnx-transformers");
+    expect(p.model).toBe("Xenova/bge-small-en-v1.5");
+    expect(p.dims).toBe(384);
+  });
+});
+
+describe("OnnxTransformersEmbeddingProvider.embed", () => {
+  test("embeds each text and returns vectors in the same order", async () => {
+    const p = new OnnxTransformersEmbeddingProvider({
+      pipelineLoader: fakeLoader((text) => (text === "a" ? [1, 0, 0] : [0, 1, 0])),
+    });
+    const result = await p.embed({ texts: ["a", "b"] });
+    expect(Array.from(result.vectors[0])).toEqual([1, 0, 0]);
+    expect(Array.from(result.vectors[1])).toEqual([0, 1, 0]);
+    expect(result.model).toBe("Xenova/bge-small-en-v1.5");
+    expect(result.dims).toBe(3);
+  });
+
+  test("empty texts array short-circuits without loading the pipeline", async () => {
+    let loaded = false;
+    const p = new OnnxTransformersEmbeddingProvider({
+      pipelineLoader: async () => {
+        loaded = true;
+        return async () => ({ data: new Float32Array([1]) });
+      },
+    });
+    const result = await p.embed({ texts: [] });
+    expect(result.vectors).toEqual([]);
+    expect(loaded).toBe(false);
+  });
+
+  test("loads the pipeline only ONCE across multiple embed() calls (lazy singleton)", async () => {
+    let loadCount = 0;
+    const p = new OnnxTransformersEmbeddingProvider({
+      pipelineLoader: async () => {
+        loadCount++;
+        return async () => ({ data: new Float32Array([1, 0]) });
+      },
+    });
+    await p.embed({ texts: ["a"] });
+    await p.embed({ texts: ["b"] });
+    await p.embed({ texts: ["c"] });
+    expect(loadCount).toBe(1);
+  });
+
+  test("a broken provider stays broken — doesn't retry a doomed load on every call", async () => {
+    let attempts = 0;
+    const p = new OnnxTransformersEmbeddingProvider({
+      pipelineLoader: async () => {
+        attempts++;
+        throw new Error("always fails");
+      },
+    });
+    await expect(p.embed({ texts: ["a"] })).rejects.toThrow(EmbeddingError);
+    await expect(p.embed({ texts: ["b"] })).rejects.toThrow(EmbeddingError);
+    expect(attempts).toBe(1);
+  });
+
+  test("accepts a plain number[] `data` shape (not just Float32Array) from the pipeline", async () => {
+    const p = new OnnxTransformersEmbeddingProvider({
+      pipelineLoader: async () => async () => ({ data: [1, 2, 3] as unknown as Float32Array }),
+    });
+    const result = await p.embed({ texts: ["x"] });
+    expect(Array.from(result.vectors[0])).toEqual([1, 2, 3]);
+  });
+});