@workglow/test-contract 0.6.1

package/dist/vector-storage/types.d.ts

@@ -0,0 +1,87 @@
+/**
+ * @license
+ * Copyright 2026 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { AnyVectorStorage } from "@workglow/storage";
+/**
+ * The schema every backend's own vector suite already declares, hoisted here so
+ * they stop declaring it separately. An `id`, the embedding, and a `metadata`
+ * object — the shape a filter is applied to.
+ */
+export declare const VectorItemSchema: {
+    readonly type: "object";
+    readonly properties: {
+        readonly id: {
+            readonly type: "string";
+        };
+        readonly vector: {
+            readonly type: "array";
+            readonly format: "TypedArray";
+            readonly title: "Typed Array";
+            readonly description: "A typed array (Float32Array, Int8Array, etc.)";
+        };
+        readonly metadata: {
+            readonly type: "object";
+            readonly format: "metadata";
+            readonly additionalProperties: true;
+        };
+    };
+    readonly required: readonly ["id", "vector", "metadata"];
+    readonly additionalProperties: false;
+};
+export declare const VectorItemPrimaryKeyNames: readonly ["id"];
+/** Four, so a unit vector's cosine score is exactly the coordinate it points along. */
+export declare const VECTOR_DIMENSIONS = 4;
+export declare const EAST: Float32Array<ArrayBuffer>;
+export declare const NORTH: Float32Array<ArrayBuffer>;
+export declare const NORTHEAST: Float32Array<ArrayBuffer>;
+/**
+ * Closed union of vector-storage contract assertions an adapter can mark as
+ * known failing. A typo in `expectedFailures` becomes a TS error rather than a
+ * silently-ignored entry.
+ */
+export type VectorStorageContractAssertion = "similarityRanking" | "vectorRoundTrip" | "searchOptions" | "metadataFilter" | "similaritySearchEvent" | "legacyEncoding" | "dimensionValidation";
+export interface VectorStorageCapabilities {
+    /** Whether `options.filter` narrows by metadata. */
+    readonly supportsMetadataFilter: boolean;
+    /** Whether `options.scoreThreshold` drops rows below the score. */
+    readonly supportsScoreThreshold: boolean;
+    /**
+     * Whether a write whose vector is the wrong length is refused.
+     *
+     * A backend that stores the vector opaquely cannot check it, and one that
+     * declares this must refuse BEFORE writing — a row of the wrong width that
+     * lands is worse than one that never validates, because the search that
+     * trips over it is arbitrarily far away.
+     */
+    readonly supportsDimensionValidation: boolean;
+}
+export interface VectorStorageContractOpts {
+    readonly name: string;
+    readonly skip?: boolean;
+    readonly timeout?: number;
+    readonly capabilities: VectorStorageCapabilities;
+    /** A fresh, empty store of {@link VectorItemSchema} at {@link VECTOR_DIMENSIONS}. */
+    readonly createStorage: () => Promise<AnyVectorStorage>;
+    /**
+     * Releases whatever the factory allocated that the storage does not own —
+     * typically a connection handle. Called from every `afterEach`, passed the
+     * instance the factory returned.
+     */
+    readonly releaseStorage?: (storage: AnyVectorStorage) => void | Promise<void>;
+    /**
+     * Writes a row past this class's writer, in the column's stored form.
+     *
+     * Only a backend that has a stored form to write can supply it, and it is
+     * what the {@link VectorStorageContractAssertion} `legacyEncoding` block
+     * needs: the decode has to accept a row that never round-tripped through the
+     * current writer, and a test that inserts through the writer cannot ask that.
+     */
+    readonly writeRawRow?: (storage: AnyVectorStorage, row: {
+        readonly id: string;
+        readonly vector: readonly number[];
+        readonly metadata: unknown;
+    }) => Promise<void> | void;
+    readonly expectedFailures?: ReadonlyArray<VectorStorageContractAssertion>;
+}

package/dist/vector-storage.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @license
+ * Copyright 2026 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+/**
+ * Conformance suite for `IVectorStorage` — vector round trip, similarity
+ * ranking, metadata filtering and dimension validation.
+ */
+export * from "./vector-storage/runVectorStorageContract";
+export * from "./vector-storage/types";
+export * from "./vector-storage/assertions/dimensionValidation";
+export * from "./vector-storage/assertions/legacyEncoding";
+export * from "./vector-storage/assertions/metadataFilter";
+export * from "./vector-storage/assertions/searchOptions";
+export * from "./vector-storage/assertions/shared";
+export * from "./vector-storage/assertions/similarityRanking";
+export * from "./vector-storage/assertions/similaritySearchEvent";
+export * from "./vector-storage/assertions/vectorRoundTrip";

package/dist/vector-storage.js

@@ -0,0 +1,412 @@
+// src/vector-storage/runVectorStorageContract.ts
+import { describe as describe8 } from "vitest";
+
+// src/vector-storage/assertions/dimensionValidation.ts
+import { StorageValidationError } from "@workglow/storage";
+import { afterEach as afterEach2, beforeEach as beforeEach2, describe, expect } from "vitest";
+
+// src/vector-storage/types.ts
+import { TypedArraySchema } from "@workglow/util/schema";
+var VectorItemSchema = {
+  type: "object",
+  properties: {
+    id: { type: "string" },
+    vector: TypedArraySchema(),
+    metadata: { type: "object", format: "metadata", additionalProperties: true }
+  },
+  required: ["id", "vector", "metadata"],
+  additionalProperties: false
+};
+var VectorItemPrimaryKeyNames = ["id"];
+var VECTOR_DIMENSIONS = 4;
+var EAST = new Float32Array([1, 0, 0, 0]);
+var NORTH = new Float32Array([0, 1, 0, 0]);
+var NORTHEAST = new Float32Array([Math.SQRT1_2, Math.SQRT1_2, 0, 0]);
+
+// src/vector-storage/assertions/shared.ts
+import { afterEach, beforeEach, it as it2 } from "vitest";
+
+// src/creditExhaustedSkip.ts
+import { it as vitestIt } from "vitest";
+var BILLING_CODES = new Set([
+  "insufficient_quota",
+  "billing_hard_limit_reached",
+  "insufficient_credits",
+  "insufficient_balance"
+]);
+var CREDIT_MESSAGE = /insufficient credits|not enough credits|no credits remaining|out of credits|insufficient[\s_-]balance|balance is (?:too low|insufficient)|exceeded[\s\S]{0,80}credits|monthly included credits|payment required|exceeded your current quota|check your plan and billing|billing_hard_limit/i;
+var HTTP_402_MESSAGE = /\bHTTP\/?\d?(?:\.\d)?\s*402\b|\bstatus(?:\s*code)?\s*[:=]\s*402\b|\berror code:?\s*402\b|(?:^|:\s+)402\s+[a-z]/im;
+function isCreditExhaustedError(err) {
+  const seen = new Set;
+  let current = err;
+  while (current !== undefined && current !== null && !seen.has(current)) {
+    seen.add(current);
+    if (matchesCreditExhaustion(current))
+      return true;
+    current = causeOf(current);
+  }
+  return false;
+}
+function matchesCreditExhaustion(err) {
+  if (typeof err === "string")
+    return messageLooksLikeCreditExhaustion(err);
+  if (!err || typeof err !== "object")
+    return false;
+  const rec = err;
+  const status = numericStatus(rec);
+  if (status === 402)
+    return true;
+  const code = stringish(rec.code) ?? stringish(nested(rec.error, "code"));
+  const type = stringish(rec.type) ?? stringish(nested(rec.error, "type"));
+  if (code && BILLING_CODES.has(code))
+    return true;
+  if (type && BILLING_CODES.has(type))
+    return true;
+  const message = [
+    stringish(rec.message),
+    stringish(nested(rec.error, "message")),
+    stringifyUnknown(err)
+  ].filter((part) => typeof part === "string").join(`
+`);
+  return messageLooksLikeCreditExhaustion(message);
+}
+function messageLooksLikeCreditExhaustion(message) {
+  return CREDIT_MESSAGE.test(message) || HTTP_402_MESSAGE.test(message);
+}
+function numericStatus(rec) {
+  for (const key of ["status", "statusCode"]) {
+    const value = rec[key];
+    if (typeof value === "number" && Number.isFinite(value))
+      return value;
+  }
+  const nestedStatus = nested(rec.error, "status");
+  if (typeof nestedStatus === "number" && Number.isFinite(nestedStatus))
+    return nestedStatus;
+  return;
+}
+function nested(value, key) {
+  if (!value || typeof value !== "object")
+    return;
+  return value[key];
+}
+function stringish(value) {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function stringifyUnknown(err) {
+  if (err instanceof Error)
+    return err.message;
+  return String(err);
+}
+function causeOf(err) {
+  if (!err || typeof err !== "object")
+    return;
+  return err.cause;
+}
+function creditSkipNote(err) {
+  const message = err instanceof Error ? err.message : String(err);
+  return `skipped: provider out of credits (${message})`;
+}
+var SKIP_OVERRIDE_ENV = "WORKGLOW_CREDIT_EXHAUSTED_SKIP";
+function isTruthyFlag(value) {
+  return !/^(?:0|false|off|no)$/i.test(value.trim());
+}
+function creditExhaustionSkipsTest(env = process.env) {
+  const override = env[SKIP_OVERRIDE_ENV];
+  if (override !== undefined && override.trim() !== "")
+    return isTruthyFlag(override);
+  for (const key of ["CI", "GITHUB_ACTIONS"]) {
+    const value = env[key];
+    if (value !== undefined && value.trim() !== "" && isTruthyFlag(value))
+      return true;
+  }
+  return false;
+}
+function reportLocalCreditFailure(err) {
+  const message = err instanceof Error ? err.message : String(err);
+  console.error(`provider out of credits (${message})
+` + `  Failing because this is not CI. Top the account up, or set ${SKIP_OVERRIDE_ENV}=1 to skip instead.`);
+}
+async function runWithCreditSkip(ctx, fn) {
+  try {
+    return await fn();
+  } catch (err) {
+    if (isCreditExhaustedError(err)) {
+      if (!creditExhaustionSkipsTest()) {
+        reportLocalCreditFailure(err);
+        throw err;
+      }
+      ctx.skip(creditSkipNote(err));
+      return;
+    }
+    throw err;
+  }
+}
+function wrapTestBodyForCreditSkip(fn) {
+  return async function wrapped(...args) {
+    try {
+      return await fn.apply(this, args);
+    } catch (err) {
+      if (!isCreditExhaustedError(err))
+        throw err;
+      if (!creditExhaustionSkipsTest()) {
+        reportLocalCreditFailure(err);
+        throw err;
+      }
+      const ctx = args[0];
+      if (ctx && typeof ctx.skip === "function") {
+        ctx.skip(creditSkipNote(err));
+        return;
+      }
+      console.warn(creditSkipNote(err));
+      return;
+    }
+  };
+}
+function wrapCallable(fn) {
+  return new Proxy(fn, {
+    apply(target, thisArg, argArray) {
+      const wrapped = argArray.map((arg) => typeof arg === "function" ? wrapTestBodyForCreditSkip(arg) : arg);
+      const result = Reflect.apply(target, thisArg, wrapped);
+      return typeof result === "function" ? wrapCallable(result) : result;
+    },
+    get(target, prop, receiver) {
+      const value = Reflect.get(target, prop, receiver);
+      if (typeof value === "function") {
+        return wrapCallable(value.bind(target));
+      }
+      return value;
+    }
+  });
+}
+var it = wrapCallable(vitestIt);
+
+// src/itExpectFail.ts
+var itExpectFail = (name, fn, timeout) => {
+  const native = it.fails;
+  if (typeof native === "function") {
+    native(name, fn, timeout);
+    return;
+  }
+  it(`${name} [expected-fail]`, async () => {
+    let passed = false;
+    try {
+      await fn();
+      passed = true;
+    } catch (err) {
+      if (isCreditExhaustedError(err))
+        throw err;
+    }
+    if (passed) {
+      throw new Error(`Test "${name}" was marked as expected-fail but passed. Remove its name from opts.expectedFailures.`);
+    }
+  }, timeout);
+};
+
+// src/vector-storage/assertions/shared.ts
+function itFor(opts, assertion) {
+  return new Set(opts.expectedFailures ?? []).has(assertion) ? itExpectFail : it2;
+}
+function seededStore(opts) {
+  let storage;
+  beforeEach(async () => {
+    storage = await opts.createStorage();
+    await storage.setupDatabase?.();
+    await storage.putBulk([
+      { id: "east", vector: EAST, metadata: { region: "e" } },
+      { id: "north", vector: NORTH, metadata: { region: "n" } },
+      { id: "northeast", vector: NORTHEAST, metadata: { region: "ne" } }
+    ]);
+  });
+  afterEach(async () => {
+    await storage.deleteAll();
+    storage.destroy?.();
+    await opts.releaseStorage?.(storage);
+  });
+  return () => storage;
+}
+
+// src/vector-storage/assertions/dimensionValidation.ts
+var SHORT = new Float32Array([1, 2, 3]);
+var LONG = new Float32Array([1, 2, 3, 4, 5]);
+function dimensionValidationBlock(opts) {
+  describe.skipIf(!opts.capabilities.supportsDimensionValidation)("dimensionValidation", () => {
+    const itImpl = itFor(opts, "dimensionValidation");
+    let storage;
+    beforeEach2(async () => {
+      storage = await opts.createStorage();
+      await storage.setupDatabase?.();
+    });
+    afterEach2(async () => {
+      await storage.deleteAll();
+      storage.destroy?.();
+      await opts.releaseStorage?.(storage);
+    });
+    itImpl("declares the width it was built with", async () => {
+      expect(storage.getVectorDimensions()).toBe(VECTOR_DIMENSIONS);
+    }, opts.timeout);
+    for (const [label, vector] of [
+      ["one entry short", SHORT],
+      ["one entry long", LONG]
+    ]) {
+      itImpl(`refuses a put whose vector is ${label}, and writes nothing`, async () => {
+        await expect(storage.put({ id: "x", vector, metadata: {} })).rejects.toBeInstanceOf(StorageValidationError);
+        expect(await storage.getAll() ?? []).toHaveLength(0);
+      }, opts.timeout);
+      itImpl(`refuses a search whose query vector is ${label}`, async () => {
+        await expect(storage.similaritySearch(vector)).rejects.toBeInstanceOf(StorageValidationError);
+      }, opts.timeout);
+      itImpl(`refuses a putBulk containing a vector that is ${label}, and writes nothing`, async () => {
+        await expect(storage.putBulk([
+          { id: "good", vector: EAST, metadata: {} },
+          { id: "bad", vector, metadata: {} }
+        ])).rejects.toBeInstanceOf(StorageValidationError);
+        expect(await storage.getAll() ?? []).toHaveLength(0);
+      }, opts.timeout);
+    }
+  });
+}
+
+// src/vector-storage/assertions/legacyEncoding.ts
+import { describe as describe2, expect as expect2 } from "vitest";
+function legacyEncodingBlock(opts) {
+  describe2.skipIf(opts.writeRawRow === undefined)("legacyEncoding", () => {
+    const store = seededStore(opts);
+    itFor(opts, "legacyEncoding")("searches a row that never round-tripped through this writer", async () => {
+      await opts.writeRawRow?.(store(), {
+        id: "legacy",
+        vector: [...NORTH],
+        metadata: { region: "legacy" }
+      });
+      const hits = await store().similaritySearch(NORTH, { topK: 2 });
+      expect2(hits.map((hit) => hit.id)).toContain("legacy");
+      const legacy = hits.find((hit) => hit.id === "legacy");
+      expect2([...legacy.vector]).toEqual([...NORTH]);
+    }, opts.timeout);
+  });
+}
+
+// src/vector-storage/assertions/metadataFilter.ts
+import { describe as describe3, expect as expect3 } from "vitest";
+function metadataFilterBlock(opts) {
+  describe3.skipIf(!opts.capabilities.supportsMetadataFilter)("metadataFilter", () => {
+    const store = seededStore(opts);
+    const itImpl = itFor(opts, "metadataFilter");
+    itImpl("returns only the rows the filter matches", async () => {
+      const hits = await store().similaritySearch(EAST, { filter: { region: "n" } });
+      expect3(hits.map((hit) => hit.id)).toEqual(["north"]);
+    }, opts.timeout);
+    itImpl("finds a match the ranking would not have reached", async () => {
+      const hits = await store().similaritySearch(EAST, {
+        filter: { region: "n" },
+        topK: 1
+      });
+      expect3(hits.map((hit) => hit.id)).toEqual(["north"]);
+    }, opts.timeout);
+    itImpl("returns nothing when the filter matches nothing", async () => {
+      expect3(await store().similaritySearch(EAST, { filter: { region: "nowhere" } })).toHaveLength(0);
+    }, opts.timeout);
+  });
+}
+
+// src/vector-storage/assertions/searchOptions.ts
+import { describe as describe4, expect as expect4 } from "vitest";
+function searchOptionsBlock(opts) {
+  describe4("searchOptions", () => {
+    const store = seededStore(opts);
+    const itImpl = itFor(opts, "searchOptions");
+    itImpl("truncates to topK, keeping the most similar", async () => {
+      const hits = await store().similaritySearch(EAST, { topK: 2 });
+      expect4(hits.map((hit) => hit.id)).toEqual(["east", "northeast"]);
+    }, opts.timeout);
+    itImpl("returns everything when topK exceeds the row count", async () => {
+      expect4(await store().similaritySearch(EAST, { topK: 10 })).toHaveLength(3);
+    }, opts.timeout);
+    describe4.skipIf(!opts.capabilities.supportsScoreThreshold)("scoreThreshold", () => {
+      itImpl("drops rows scoring below the threshold", async () => {
+        const hits = await store().similaritySearch(EAST, { scoreThreshold: 0.9 });
+        expect4(hits.map((hit) => hit.id)).toEqual(["east"]);
+      }, opts.timeout);
+      itImpl("keeps a row scoring exactly the threshold", async () => {
+        const hits = await store().similaritySearch(EAST, { scoreThreshold: 0 });
+        expect4(hits.map((hit) => hit.id)).toEqual(["east", "northeast", "north"]);
+      }, opts.timeout);
+    });
+  });
+}
+
+// src/vector-storage/assertions/similarityRanking.ts
+import { describe as describe5, expect as expect5 } from "vitest";
+function similarityRankingBlock(opts) {
+  describe5("similarityRanking", () => {
+    const store = seededStore(opts);
+    itFor(opts, "similarityRanking")("returns the stored rows ranked by similarity, with the scores that ordered them", async () => {
+      const hits = await store().similaritySearch(EAST);
+      expect5(hits.map((hit) => hit.id)).toEqual(["east", "northeast", "north"]);
+      expect5(hits[0].score).toBeCloseTo(1, 5);
+      expect5(hits[1].score).toBeCloseTo(Math.SQRT1_2, 5);
+      expect5(hits[2].score).toBeCloseTo(0, 5);
+    }, opts.timeout);
+  });
+}
+
+// src/vector-storage/assertions/similaritySearchEvent.ts
+import { describe as describe6, expect as expect6 } from "vitest";
+function similaritySearchEventBlock(opts) {
+  describe6("similaritySearchEvent", () => {
+    const store = seededStore(opts);
+    itFor(opts, "similaritySearchEvent")("fires with the results the caller was handed", async () => {
+      let seen;
+      store().on("similaritySearch", (_query, results) => {
+        seen = results;
+      });
+      await store().similaritySearch(EAST, { topK: 1 });
+      expect6(seen?.map((hit) => hit.id)).toEqual(["east"]);
+    }, opts.timeout);
+  });
+}
+
+// src/vector-storage/assertions/vectorRoundTrip.ts
+import { describe as describe7, expect as expect7 } from "vitest";
+function vectorRoundTripBlock(opts) {
+  describe7("vectorRoundTrip", () => {
+    const store = seededStore(opts);
+    itFor(opts, "vectorRoundTrip")("hands back the vector as a TypedArray with the values that were written", async () => {
+      const [hit] = await store().similaritySearch(EAST, { topK: 1 });
+      expect7(ArrayBuffer.isView(hit.vector)).toBe(true);
+      expect7([...hit.vector]).toEqual([...EAST]);
+    }, opts.timeout);
+  });
+}
+
+// src/vector-storage/runVectorStorageContract.ts
+function runVectorStorageContract(opts) {
+  describe8.skipIf(opts.skip)(`Vector storage contract: ${opts.name}`, () => {
+    similarityRankingBlock(opts);
+    vectorRoundTripBlock(opts);
+    searchOptionsBlock(opts);
+    metadataFilterBlock(opts);
+    similaritySearchEventBlock(opts);
+    legacyEncodingBlock(opts);
+    dimensionValidationBlock(opts);
+  });
+}
+export {
+  EAST,
+  NORTH,
+  NORTHEAST,
+  VECTOR_DIMENSIONS,
+  VectorItemPrimaryKeyNames,
+  VectorItemSchema,
+  dimensionValidationBlock,
+  itFor,
+  legacyEncodingBlock,
+  metadataFilterBlock,
+  runVectorStorageContract,
+  searchOptionsBlock,
+  seededStore,
+  similarityRankingBlock,
+  similaritySearchEventBlock,
+  vectorRoundTripBlock
+};
+
+//# debugId=DFF5A9885C0171A264756E2164756E21

package/dist/vector-storage.js.map

@@ -0,0 +1,21 @@
+{
+  "version": 3,
+  "sources": ["../src/vector-storage/runVectorStorageContract.ts", "../src/vector-storage/assertions/dimensionValidation.ts", "../src/vector-storage/types.ts", "../src/vector-storage/assertions/shared.ts", "../src/creditExhaustedSkip.ts", "../src/itExpectFail.ts", "../src/vector-storage/assertions/legacyEncoding.ts", "../src/vector-storage/assertions/metadataFilter.ts", "../src/vector-storage/assertions/searchOptions.ts", "../src/vector-storage/assertions/similarityRanking.ts", "../src/vector-storage/assertions/similaritySearchEvent.ts", "../src/vector-storage/assertions/vectorRoundTrip.ts"],
+  "sourcesContent": [
+    "/**\n * @license\n * Copyright 2026 Steven Roussey <sroussey@gmail.com>\n * SPDX-License-Identifier: Apache-2.0\n */\n\nimport { describe } from \"vitest\";\nimport { dimensionValidationBlock } from \"./assertions/dimensionValidation\";\nimport { legacyEncodingBlock } from \"./assertions/legacyEncoding\";\nimport { metadataFilterBlock } from \"./assertions/metadataFilter\";\nimport { searchOptionsBlock } from \"./assertions/searchOptions\";\nimport { similarityRankingBlock } from \"./assertions/similarityRanking\";\nimport { similaritySearchEventBlock } from \"./assertions/similaritySearchEvent\";\nimport { vectorRoundTripBlock } from \"./assertions/vectorRoundTrip\";\nimport type { VectorStorageContractOpts } from \"./types\";\n\n/**\n * The conformance suite for {@link IVectorStorage}, in the shape\n * `runTabularStorageContract` already has.\n *\n * Eight classes implement the interface and each had its own hand-written file,\n * no two checking the same things — which is how a release shipped in which\n * every single query failed on one backend: its sibling suite only ever wrote\n * and read back, so nothing there issued a search. The fix added seven cases,\n * all against that one backend, and the other seven implementations gained\n * nothing.\n */\nexport function runVectorStorageContract(opts: VectorStorageContractOpts): void {\n  describe.skipIf(opts.skip)(`Vector storage contract: ${opts.name}`, () => {\n    similarityRankingBlock(opts);\n    vectorRoundTripBlock(opts);\n    searchOptionsBlock(opts);\n    metadataFilterBlock(opts);\n    similaritySearchEventBlock(opts);\n    legacyEncodingBlock(opts);\n    dimensionValidationBlock(opts);\n  });\n}\n\nexport {\n  EAST,\n  NORTH,\n  NORTHEAST,\n  VECTOR_DIMENSIONS,\n  VectorItemPrimaryKeyNames,\n  VectorItemSchema,\n} from \"./types\";\nexport type {\n  VectorStorageCapabilities,\n  VectorStorageContractAssertion,\n  VectorStorageContractOpts,\n} from \"./types\";\n",
+    "/**\n * @license\n * Copyright 2026 Steven Roussey <sroussey@gmail.com>\n * SPDX-License-Identifier: Apache-2.0\n */\n\nimport type { AnyVectorStorage } from \"@workglow/storage\";\nimport { StorageValidationError } from \"@workglow/storage\";\nimport { afterEach, beforeEach, describe, expect } from \"vitest\";\nimport type { VectorStorageContractOpts } from \"../types\";\nimport { EAST, VECTOR_DIMENSIONS } from \"../types\";\nimport { itFor } from \"./shared\";\n\nconst SHORT = new Float32Array([1, 2, 3]);\nconst LONG = new Float32Array([1, 2, 3, 4, 5]);\n\n/**\n * A vector of the wrong width is refused, and refused BEFORE the row lands.\n *\n * The store's width is fixed at construction and every row has to have it, so a\n * row of another width is not a bad read waiting to happen — it is a bad read\n * arbitrarily far away, surfacing in whichever query first reaches it, with\n * nothing left to say where it came from. Rejecting late is barely better than\n * not rejecting: the assertion below reads the table back, because a throw\n * after the insert satisfies `rejects` and still leaves the row.\n */\nexport function dimensionValidationBlock(opts: VectorStorageContractOpts): void {\n  describe.skipIf(!opts.capabilities.supportsDimensionValidation)(\"dimensionValidation\", () => {\n    const itImpl = itFor(opts, \"dimensionValidation\");\n    let storage: AnyVectorStorage;\n\n    beforeEach(async () => {\n      storage = await opts.createStorage();\n      await storage.setupDatabase?.();\n    });\n\n    afterEach(async () => {\n      await storage.deleteAll();\n      storage.destroy?.();\n      await opts.releaseStorage?.(storage);\n    });\n\n    itImpl(\n      \"declares the width it was built with\",\n      async () => {\n        expect(storage.getVectorDimensions()).toBe(VECTOR_DIMENSIONS);\n      },\n      opts.timeout\n    );\n\n    for (const [label, vector] of [\n      [\"one entry short\", SHORT],\n      [\"one entry long\", LONG],\n    ] as const) {\n      itImpl(\n        `refuses a put whose vector is ${label}, and writes nothing`,\n        async () => {\n          await expect(storage.put({ id: \"x\", vector, metadata: {} })).rejects.toBeInstanceOf(\n            StorageValidationError\n          );\n          expect((await storage.getAll()) ?? []).toHaveLength(0);\n        },\n        opts.timeout\n      );\n\n      itImpl(\n        `refuses a search whose query vector is ${label}`,\n        async () => {\n          // The query side is the same rule and a different code path: a\n          // wrong-width query either throws or is quietly coerced by the\n          // engine into a search that returns confident nonsense.\n          await expect(storage.similaritySearch(vector)).rejects.toBeInstanceOf(\n            StorageValidationError\n          );\n        },\n        opts.timeout\n      );\n\n      itImpl(\n        `refuses a putBulk containing a vector that is ${label}, and writes nothing`,\n        async () => {\n          // Not even the good row: a bulk write that half-lands leaves the\n          // caller with no way to know which half.\n          await expect(\n            storage.putBulk([\n              { id: \"good\", vector: EAST, metadata: {} },\n              { id: \"bad\", vector, metadata: {} },\n            ])\n          ).rejects.toBeInstanceOf(StorageValidationError);\n          expect((await storage.getAll()) ?? []).toHaveLength(0);\n        },\n        opts.timeout\n      );\n    }\n  });\n}\n",
+    "/**\n * @license\n * Copyright 2026 Steven Roussey <sroussey@gmail.com>\n * SPDX-License-Identifier: Apache-2.0\n */\n\nimport type { AnyVectorStorage } from \"@workglow/storage\";\nimport type { DataPortSchemaObject } from \"@workglow/util/schema\";\nimport { TypedArraySchema } from \"@workglow/util/schema\";\n\n/**\n * The schema every backend's own vector suite already declares, hoisted here so\n * they stop declaring it separately. An `id`, the embedding, and a `metadata`\n * object — the shape a filter is applied to.\n */\nexport const VectorItemSchema = {\n  type: \"object\",\n  properties: {\n    id: { type: \"string\" },\n    vector: TypedArraySchema(),\n    metadata: { type: \"object\", format: \"metadata\", additionalProperties: true },\n  },\n  required: [\"id\", \"vector\", \"metadata\"],\n  additionalProperties: false,\n} as const satisfies DataPortSchemaObject;\n\nexport const VectorItemPrimaryKeyNames = [\"id\"] as const;\n\n/** Four, so a unit vector's cosine score is exactly the coordinate it points along. */\nexport const VECTOR_DIMENSIONS = 4;\n\nexport const EAST = new Float32Array([1, 0, 0, 0]);\nexport const NORTH = new Float32Array([0, 1, 0, 0]);\nexport const NORTHEAST = new Float32Array([Math.SQRT1_2, Math.SQRT1_2, 0, 0]);\n\n/**\n * Closed union of vector-storage contract assertions an adapter can mark as\n * known failing. A typo in `expectedFailures` becomes a TS error rather than a\n * silently-ignored entry.\n */\nexport type VectorStorageContractAssertion =\n  | \"similarityRanking\"\n  | \"vectorRoundTrip\"\n  | \"searchOptions\"\n  | \"metadataFilter\"\n  | \"similaritySearchEvent\"\n  | \"legacyEncoding\"\n  | \"dimensionValidation\";\n\nexport interface VectorStorageCapabilities {\n  /** Whether `options.filter` narrows by metadata. */\n  readonly supportsMetadataFilter: boolean;\n  /** Whether `options.scoreThreshold` drops rows below the score. */\n  readonly supportsScoreThreshold: boolean;\n  /**\n   * Whether a write whose vector is the wrong length is refused.\n   *\n   * A backend that stores the vector opaquely cannot check it, and one that\n   * declares this must refuse BEFORE writing — a row of the wrong width that\n   * lands is worse than one that never validates, because the search that\n   * trips over it is arbitrarily far away.\n   */\n  readonly supportsDimensionValidation: boolean;\n}\n\nexport interface VectorStorageContractOpts {\n  readonly name: string;\n  readonly skip?: boolean;\n  readonly timeout?: number;\n  readonly capabilities: VectorStorageCapabilities;\n  /** A fresh, empty store of {@link VectorItemSchema} at {@link VECTOR_DIMENSIONS}. */\n  readonly createStorage: () => Promise<AnyVectorStorage>;\n  /**\n   * Releases whatever the factory allocated that the storage does not own —\n   * typically a connection handle. Called from every `afterEach`, passed the\n   * instance the factory returned.\n   */\n  readonly releaseStorage?: (storage: AnyVectorStorage) => void | Promise<void>;\n  /**\n   * Writes a row past this class's writer, in the column's stored form.\n   *\n   * Only a backend that has a stored form to write can supply it, and it is\n   * what the {@link VectorStorageContractAssertion} `legacyEncoding` block\n   * needs: the decode has to accept a row that never round-tripped through the\n   * current writer, and a test that inserts through the writer cannot ask that.\n   */\n  readonly writeRawRow?: (\n    storage: AnyVectorStorage,\n    row: { readonly id: string; readonly vector: readonly number[]; readonly metadata: unknown }\n  ) => Promise<void> | void;\n  readonly expectedFailures?: ReadonlyArray<VectorStorageContractAssertion>;\n}\n",
+    "/**\n * @license\n * Copyright 2026 Steven Roussey <sroussey@gmail.com>\n * SPDX-License-Identifier: Apache-2.0\n */\n\nimport type { AnyVectorStorage } from \"@workglow/storage\";\nimport { afterEach, beforeEach, it } from \"vitest\";\nimport { itExpectFail } from \"../../itExpectFail\";\nimport type { VectorStorageContractAssertion, VectorStorageContractOpts } from \"../types\";\nimport { EAST, NORTH, NORTHEAST } from \"../types\";\n\n/** A hit, as much of one as every assertion here needs to read. */\nexport interface Hit {\n  readonly id: string;\n  readonly score: number;\n  readonly vector: unknown;\n}\n\nexport function itFor(\n  opts: VectorStorageContractOpts,\n  assertion: VectorStorageContractAssertion\n): typeof it {\n  return new Set(opts.expectedFailures ?? []).has(assertion) ? (itExpectFail as typeof it) : it;\n}\n\n/**\n * The three-row fixture every block searches over: two axis-aligned unit\n * vectors and the bisector between them, so a cosine search from `EAST` has one\n * exact match, one at `SQRT1_2` and one orthogonal — three distinct scores in a\n * known order, which is what makes \"ranked by similarity\" checkable rather than\n * merely non-empty.\n */\nexport function seededStore(opts: VectorStorageContractOpts): () => AnyVectorStorage {\n  let storage: AnyVectorStorage;\n\n  beforeEach(async () => {\n    storage = await opts.createStorage();\n    await storage.setupDatabase?.();\n    await storage.putBulk([\n      { id: \"east\", vector: EAST, metadata: { region: \"e\" } },\n      { id: \"north\", vector: NORTH, metadata: { region: \"n\" } },\n      { id: \"northeast\", vector: NORTHEAST, metadata: { region: \"ne\" } },\n    ]);\n  });\n\n  afterEach(async () => {\n    await storage.deleteAll();\n    storage.destroy?.();\n    await opts.releaseStorage?.(storage);\n  });\n\n  return () => storage;\n}\n",
+    "/**\n * @license\n * Copyright 2026 Steven Roussey <sroussey@gmail.com>\n * SPDX-License-Identifier: Apache-2.0\n */\n\nimport { it as vitestIt } from \"vitest\";\n\n/**\n * Live provider tests treat \"the account is out of credits\" as a billing\n * condition rather than a product bug. A key being present is not the same as\n * the account being able to pay; HuggingFace / OpenRouter 402s, Anthropic's\n * credit-balance error, DeepSeek's `Insufficient Balance`, and OpenAI's\n * `insufficient_quota` are all billing.\n *\n * Rate limits (429 + `rate_limit_exceeded`) are NOT this: those are transient\n * and the existing retry policy handles them.\n *\n * Where it skips and where it fails is a deliberate split\n * ({@link creditExhaustionSkipsTest}): on CI it skips for every provider,\n * because a red build tells a reviewer nothing they can act on; locally it\n * fails, because the developer running the suite is the one who can top the\n * account up. `WORKGLOW_CREDIT_EXHAUSTED_SKIP=1` forces the skip locally\n * (and `=0` forces the failure on CI).\n */\n\nconst BILLING_CODES = new Set([\n  \"insufficient_quota\",\n  \"billing_hard_limit_reached\",\n  \"insufficient_credits\",\n  \"insufficient_balance\",\n]);\n\nconst CREDIT_MESSAGE =\n  /insufficient credits|not enough credits|no credits remaining|out of credits|insufficient[\\s_-]balance|balance is (?:too low|insufficient)|exceeded[\\s\\S]{0,80}credits|monthly included credits|payment required|exceeded your current quota|check your plan and billing|billing_hard_limit/i;\n\n/**\n * A 402 that survives only as text. `classifyProviderError` rebuilds the error\n * as a `PermanentJobError` carrying the message and no `cause`, so by the time\n * a live test sees a DeepSeek billing failure the numeric `status` is gone and\n * the OpenAI-SDK message shape (`402 Insufficient Balance`) is all that is\n * left. Anchored to an HTTP-shaped position — start of a line, or after a\n * summary line's colon — so prose that merely contains the number\n * (\"Item 402(c)\") is not scavenged as a status.\n */\nconst HTTP_402_MESSAGE =\n  /\\bHTTP\\/?\\d?(?:\\.\\d)?\\s*402\\b|\\bstatus(?:\\s*code)?\\s*[:=]\\s*402\\b|\\berror code:?\\s*402\\b|(?:^|:\\s+)402\\s+[a-z]/im;\n\nexport function isCreditExhaustedError(err: unknown): boolean {\n  const seen = new Set<unknown>();\n  let current: unknown = err;\n  while (current !== undefined && current !== null && !seen.has(current)) {\n    seen.add(current);\n    if (matchesCreditExhaustion(current)) return true;\n    current = causeOf(current);\n  }\n  return false;\n}\n\nfunction matchesCreditExhaustion(err: unknown): boolean {\n  if (typeof err === \"string\") return messageLooksLikeCreditExhaustion(err);\n\n  if (!err || typeof err !== \"object\") return false;\n\n  const rec = err as Record<string, unknown>;\n  const status = numericStatus(rec);\n  if (status === 402) return true;\n\n  const code = stringish(rec.code) ?? stringish(nested(rec.error, \"code\"));\n  const type = stringish(rec.type) ?? stringish(nested(rec.error, \"type\"));\n  if (code && BILLING_CODES.has(code)) return true;\n  if (type && BILLING_CODES.has(type)) return true;\n\n  const message = [\n    stringish(rec.message),\n    stringish(nested(rec.error, \"message\")),\n    stringifyUnknown(err),\n  ]\n    .filter((part): part is string => typeof part === \"string\")\n    .join(\"\\n\");\n  return messageLooksLikeCreditExhaustion(message);\n}\n\nfunction messageLooksLikeCreditExhaustion(message: string): boolean {\n  return CREDIT_MESSAGE.test(message) || HTTP_402_MESSAGE.test(message);\n}\n\nfunction numericStatus(rec: Record<string, unknown>): number | undefined {\n  for (const key of [\"status\", \"statusCode\"] as const) {\n    const value = rec[key];\n    if (typeof value === \"number\" && Number.isFinite(value)) return value;\n  }\n  const nestedStatus = nested(rec.error, \"status\");\n  if (typeof nestedStatus === \"number\" && Number.isFinite(nestedStatus)) return nestedStatus;\n  return undefined;\n}\n\nfunction nested(value: unknown, key: string): unknown {\n  if (!value || typeof value !== \"object\") return undefined;\n  return (value as Record<string, unknown>)[key];\n}\n\nfunction stringish(value: unknown): string | undefined {\n  return typeof value === \"string\" && value.length > 0 ? value : undefined;\n}\n\nfunction stringifyUnknown(err: unknown): string {\n  if (err instanceof Error) return err.message;\n  return String(err);\n}\n\nfunction causeOf(err: unknown): unknown {\n  if (!err || typeof err !== \"object\") return undefined;\n  return (err as { cause?: unknown }).cause;\n}\n\nexport function creditSkipNote(err: unknown): string {\n  const message = err instanceof Error ? err.message : String(err);\n  return `skipped: provider out of credits (${message})`;\n}\n\nconst SKIP_OVERRIDE_ENV = \"WORKGLOW_CREDIT_EXHAUSTED_SKIP\";\n\nfunction isTruthyFlag(value: string): boolean {\n  return !/^(?:0|false|off|no)$/i.test(value.trim());\n}\n\n/**\n * Whether a billing failure skips the test or fails it.\n *\n * CI skips: nobody watching a build can top an account up, and one exhausted\n * key would otherwise turn every provider suite red for a change that touched\n * none of them — so the leniency is provider-agnostic by construction, keyed on\n * the environment rather than on which vendor ran out.\n *\n * Locally it fails, loudly, because the developer running the suite IS the\n * person who can act on it — and a silently green local run is how an\n * exhausted account goes unnoticed until CI is the only thing exercising the\n * provider at all.\n *\n * `WORKGLOW_CREDIT_EXHAUSTED_SKIP` overrides in both directions.\n */\nexport function creditExhaustionSkipsTest(\n  env: Record<string, string | undefined> = process.env\n): boolean {\n  const override = env[SKIP_OVERRIDE_ENV];\n  if (override !== undefined && override.trim() !== \"\") return isTruthyFlag(override);\n  for (const key of [\"CI\", \"GITHUB_ACTIONS\"] as const) {\n    const value = env[key];\n    if (value !== undefined && value.trim() !== \"\" && isTruthyFlag(value)) return true;\n  }\n  return false;\n}\n\n/**\n * The local-failure path. Rethrows the provider's own error unchanged — its\n * identity and stack are what makes the failure diagnosable — after one line\n * saying why it was not skipped and how to skip it.\n */\nfunction reportLocalCreditFailure(err: unknown): void {\n  const message = err instanceof Error ? err.message : String(err);\n  console.error(\n    `provider out of credits (${message})\\n` +\n      `  Failing because this is not CI. Top the account up, or set ${SKIP_OVERRIDE_ENV}=1 to skip instead.`\n  );\n}\n\nexport async function runWithCreditSkip<T>(\n  ctx: { skip: (note?: string) => void },\n  fn: () => Promise<T> | T\n): Promise<T> {\n  try {\n    return await fn();\n  } catch (err) {\n    if (isCreditExhaustedError(err)) {\n      if (!creditExhaustionSkipsTest()) {\n        reportLocalCreditFailure(err);\n        throw err;\n      }\n      ctx.skip(creditSkipNote(err));\n      // vitest's skip() is `never` (throws). Mocks used in unit tests return.\n      return undefined as T;\n    }\n    throw err;\n  }\n}\n\n/**\n * Wraps one test body. This is the seam every conformance assertion actually\n * runs through (the exported {@link it} proxies each callback through it), so\n * the CI-skips / locally-fails policy is applied here rather than at each\n * call site.\n */\nexport function wrapTestBodyForCreditSkip(\n  fn: (...args: never[]) => unknown\n): (...args: never[]) => unknown {\n  return async function wrapped(this: unknown, ...args: never[]): Promise<unknown> {\n    try {\n      return await fn.apply(this, args);\n    } catch (err) {\n      if (!isCreditExhaustedError(err)) throw err;\n      if (!creditExhaustionSkipsTest()) {\n        reportLocalCreditFailure(err);\n        throw err;\n      }\n      const ctx = args[0] as { skip?: (note?: string) => void } | undefined;\n      if (ctx && typeof ctx.skip === \"function\") {\n        ctx.skip(creditSkipNote(err));\n        return undefined;\n      }\n      // bun:test has no TestContext.skip; passing is \"don't fail the test\".\n      console.warn(creditSkipNote(err));\n      return undefined;\n    }\n  };\n}\n\nfunction wrapCallable(fn: CallableFunction): CallableFunction {\n  return new Proxy(fn, {\n    apply(target, thisArg, argArray: unknown[]) {\n      const wrapped = argArray.map((arg) =>\n        typeof arg === \"function\" ? wrapTestBodyForCreditSkip(arg as never) : arg\n      );\n      const result = Reflect.apply(target, thisArg, wrapped);\n      return typeof result === \"function\" ? wrapCallable(result) : result;\n    },\n    get(target, prop, receiver) {\n      const value = Reflect.get(target, prop, receiver);\n      if (typeof value === \"function\") {\n        return wrapCallable((value as CallableFunction).bind(target));\n      }\n      return value;\n    },\n  });\n}\n\n/**\n * Drop-in `it` for live provider tests: a credit/billing error skips the test on\n * CI and fails it locally (see {@link creditExhaustionSkipsTest}).\n */\nexport const it = wrapCallable(vitestIt) as typeof vitestIt;\n",
+    "/**\n * @license\n * Copyright 2026 Steven Roussey <sroussey@gmail.com>\n * SPDX-License-Identifier: Apache-2.0\n */\n\nimport { isCreditExhaustedError, it } from \"./creditExhaustedSkip\";\n\ntype ItFn = (name: string, fn: () => Promise<void> | void, timeout?: number) => void;\n\n/**\n * Cross-runner polyfill for `it.fails`. Vitest exposes it natively; bun's\n * native `bun test` runner does not. Under bun we wrap the body in a\n * try/catch and assert that it threw — so a passing-when-expected-fail\n * test still surfaces as a CI failure (signalling \"remove from\n * expectedFailures\").\n */\nexport const itExpectFail: ItFn = (name, fn, timeout) => {\n  const native = (it as unknown as { fails?: ItFn }).fails;\n  if (typeof native === \"function\") {\n    native(name, fn, timeout);\n    return;\n  }\n  it(\n    `${name} [expected-fail]`,\n    async () => {\n      let passed = false;\n      try {\n        await fn();\n        passed = true;\n      } catch (err) {\n        // Billing exhaustion is not the adapter bug this marker records.\n        if (isCreditExhaustedError(err)) throw err;\n        // expected; the test was supposed to fail\n      }\n      if (passed) {\n        throw new Error(\n          `Test \"${name}\" was marked as expected-fail but passed. Remove its name from opts.expectedFailures.`\n        );\n      }\n    },\n    timeout\n  );\n};\n",
+    "/**\n * @license\n * Copyright 2026 Steven Roussey <sroussey@gmail.com>\n * SPDX-License-Identifier: Apache-2.0\n */\n\nimport { describe, expect } from \"vitest\";\nimport type { VectorStorageContractOpts } from \"../types\";\nimport { NORTH } from \"../types\";\nimport type { Hit } from \"./shared\";\nimport { itFor, seededStore } from \"./shared\";\n\n/**\n * A row written in the column's stored form — by an older release, or by\n * anything that is not this class's writer — is still searchable.\n *\n * This is the other half of the decode that broke: a search path may not assume\n * every row it reads was encoded by the writer it ships with. Only a backend\n * that has a stored form to write can be asked, so the block is skipped where\n * the adapter supplies no `writeRawRow`.\n */\nexport function legacyEncodingBlock(opts: VectorStorageContractOpts): void {\n  describe.skipIf(opts.writeRawRow === undefined)(\"legacyEncoding\", () => {\n    const store = seededStore(opts);\n\n    itFor(opts, \"legacyEncoding\")(\n      \"searches a row that never round-tripped through this writer\",\n      async () => {\n        await opts.writeRawRow?.(store(), {\n          id: \"legacy\",\n          vector: [...NORTH],\n          metadata: { region: \"legacy\" },\n        });\n\n        const hits = (await store().similaritySearch(NORTH, { topK: 2 })) as Hit[];\n\n        expect(hits.map((hit) => hit.id)).toContain(\"legacy\");\n        // And it decodes to the same thing a written row does, rather than\n        // merely not throwing.\n        const legacy = hits.find((hit) => hit.id === \"legacy\");\n        expect([...(legacy!.vector as Float32Array)]).toEqual([...NORTH]);\n      },\n      opts.timeout\n    );\n  });\n}\n",
+    "/**\n * @license\n * Copyright 2026 Steven Roussey <sroussey@gmail.com>\n * SPDX-License-Identifier: Apache-2.0\n */\n\nimport { describe, expect } from \"vitest\";\nimport type { VectorStorageContractOpts } from \"../types\";\nimport { EAST } from \"../types\";\nimport type { Hit } from \"./shared\";\nimport { itFor, seededStore } from \"./shared\";\n\n/**\n * A metadata filter narrows the search, and narrows it to what matches rather\n * than to what happens to be near.\n *\n * The case worth stating is the second one: filtering to a row that is NOT the\n * nearest. A backend that takes the top `k` and then filters returns nothing\n * there, while one that filters and then ranks returns the row — and the first\n * behaviour is a silently empty result for every scoped RAG query.\n */\nexport function metadataFilterBlock(opts: VectorStorageContractOpts): void {\n  describe.skipIf(!opts.capabilities.supportsMetadataFilter)(\"metadataFilter\", () => {\n    const store = seededStore(opts);\n    const itImpl = itFor(opts, \"metadataFilter\");\n\n    itImpl(\n      \"returns only the rows the filter matches\",\n      async () => {\n        const hits = (await store().similaritySearch(EAST, { filter: { region: \"n\" } })) as Hit[];\n        expect(hits.map((hit) => hit.id)).toEqual([\"north\"]);\n      },\n      opts.timeout\n    );\n\n    itImpl(\n      \"finds a match the ranking would not have reached\",\n      async () => {\n        // `north` is the LAST of the three by similarity to EAST. Asking for it\n        // with topK 1 separates \"filter, then rank\" from \"rank, then filter\".\n        const hits = (await store().similaritySearch(EAST, {\n          filter: { region: \"n\" },\n          topK: 1,\n        })) as Hit[];\n        expect(hits.map((hit) => hit.id)).toEqual([\"north\"]);\n      },\n      opts.timeout\n    );\n\n    itImpl(\n      \"returns nothing when the filter matches nothing\",\n      async () => {\n        expect(\n          await store().similaritySearch(EAST, { filter: { region: \"nowhere\" } })\n        ).toHaveLength(0);\n      },\n      opts.timeout\n    );\n  });\n}\n",
+    "/**\n * @license\n * Copyright 2026 Steven Roussey <sroussey@gmail.com>\n * SPDX-License-Identifier: Apache-2.0\n */\n\nimport { describe, expect } from \"vitest\";\nimport type { VectorStorageContractOpts } from \"../types\";\nimport { EAST } from \"../types\";\nimport type { Hit } from \"./shared\";\nimport { itFor, seededStore } from \"./shared\";\n\n/**\n * `topK` truncates and `scoreThreshold` filters — and they mean the same thing\n * on a backend that computes the scores in SQL as on one that scans in memory.\n *\n * That parity is not free: it has already had to be fixed once, when the two\n * paths disagreed about which side of the threshold an exact match fell on.\n * Stating it here is what makes the next backend inherit the answer instead of\n * rediscovering the question.\n */\nexport function searchOptionsBlock(opts: VectorStorageContractOpts): void {\n  describe(\"searchOptions\", () => {\n    const store = seededStore(opts);\n    const itImpl = itFor(opts, \"searchOptions\");\n\n    itImpl(\n      \"truncates to topK, keeping the most similar\",\n      async () => {\n        const hits = (await store().similaritySearch(EAST, { topK: 2 })) as Hit[];\n        expect(hits.map((hit) => hit.id)).toEqual([\"east\", \"northeast\"]);\n      },\n      opts.timeout\n    );\n\n    itImpl(\n      \"returns everything when topK exceeds the row count\",\n      async () => {\n        // A backend that pushes `topK` into a `LIMIT` and one that slices an\n        // array agree here; one that treats it as an exact count does not.\n        expect(await store().similaritySearch(EAST, { topK: 10 })).toHaveLength(3);\n      },\n      opts.timeout\n    );\n\n    describe.skipIf(!opts.capabilities.supportsScoreThreshold)(\"scoreThreshold\", () => {\n      itImpl(\n        \"drops rows scoring below the threshold\",\n        async () => {\n          const hits = (await store().similaritySearch(EAST, { scoreThreshold: 0.9 })) as Hit[];\n          expect(hits.map((hit) => hit.id)).toEqual([\"east\"]);\n        },\n        opts.timeout\n      );\n\n      itImpl(\n        \"keeps a row scoring exactly the threshold\",\n        async () => {\n          // Zero, because it is the one boundary every backend can hit\n          // exactly: `north` is orthogonal to `EAST`, so its score is 0 in\n          // float32 and in float64 alike. `Math.SQRT1_2` is not — it rounds\n          // down through a Float32Array, so a threshold set to it sits just\n          // above the score the store can produce, and the test would be\n          // measuring the rounding rather than the comparison.\n          //\n          // The boundary is where the SQL and in-memory paths drifted apart\n          // before, and either answer is defensible until one is written down.\n          const hits = (await store().similaritySearch(EAST, { scoreThreshold: 0 })) as Hit[];\n          expect(hits.map((hit) => hit.id)).toEqual([\"east\", \"northeast\", \"north\"]);\n        },\n        opts.timeout\n      );\n    });\n  });\n}\n",
+    "/**\n * @license\n * Copyright 2026 Steven Roussey <sroussey@gmail.com>\n * SPDX-License-Identifier: Apache-2.0\n */\n\nimport { describe, expect } from \"vitest\";\nimport type { VectorStorageContractOpts } from \"../types\";\nimport { EAST } from \"../types\";\nimport type { Hit } from \"./shared\";\nimport { itFor, seededStore } from \"./shared\";\n\n/**\n * A search returns the rows, most similar first.\n *\n * This is the assertion the tree did not have, and the one that cost: a release\n * shipped in which `similaritySearch` re-decoded a vector column the inherited\n * tabular read had already turned into a `Float32Array`, so `JSON.parse` threw\n * on the first row of every search. Writes, dimension validation and `getAll`\n * were all fine — a store that accepts writes and fails every query looks\n * healthy from anywhere except a query, and only one backend had a test that\n * issued one.\n */\nexport function similarityRankingBlock(opts: VectorStorageContractOpts): void {\n  describe(\"similarityRanking\", () => {\n    const store = seededStore(opts);\n\n    itFor(opts, \"similarityRanking\")(\n      \"returns the stored rows ranked by similarity, with the scores that ordered them\",\n      async () => {\n        const hits = (await store().similaritySearch(EAST)) as Hit[];\n\n        expect(hits.map((hit) => hit.id)).toEqual([\"east\", \"northeast\", \"north\"]);\n        // The order alone would hold for a backend that returned them in\n        // insertion order by luck. The scores are what say it measured.\n        expect(hits[0]!.score).toBeCloseTo(1, 5);\n        expect(hits[1]!.score).toBeCloseTo(Math.SQRT1_2, 5);\n        expect(hits[2]!.score).toBeCloseTo(0, 5);\n      },\n      opts.timeout\n    );\n  });\n}\n",
+    "/**\n * @license\n * Copyright 2026 Steven Roussey <sroussey@gmail.com>\n * SPDX-License-Identifier: Apache-2.0\n */\n\nimport { describe, expect } from \"vitest\";\nimport type { VectorStorageContractOpts } from \"../types\";\nimport { EAST } from \"../types\";\nimport type { Hit } from \"./shared\";\nimport { itFor, seededStore } from \"./shared\";\n\n/**\n * The `similaritySearch` event is the one thing `IVectorStorage` adds to the\n * tabular event surface, and it carries the results — not a count, and not the\n * rows before the options were applied.\n *\n * Telemetry and cache layers wrap these stores and read that payload as the\n * answer the caller got. An event that fires with the unfiltered set reports\n * work nobody received.\n */\nexport function similaritySearchEventBlock(opts: VectorStorageContractOpts): void {\n  describe(\"similaritySearchEvent\", () => {\n    const store = seededStore(opts);\n\n    itFor(opts, \"similaritySearchEvent\")(\n      \"fires with the results the caller was handed\",\n      async () => {\n        let seen: Hit[] | undefined;\n        // The vector extension of the event surface; the inherited `on` is\n        // typed to the tabular names, so the cast is at the call site.\n        (\n          store() as unknown as {\n            on: (name: string, fn: (query: unknown, results: Hit[]) => void) => void;\n          }\n        ).on(\"similaritySearch\", (_query, results) => {\n          seen = results;\n        });\n\n        await store().similaritySearch(EAST, { topK: 1 });\n\n        expect(seen?.map((hit) => hit.id)).toEqual([\"east\"]);\n      },\n      opts.timeout\n    );\n  });\n}\n",
+    "/**\n * @license\n * Copyright 2026 Steven Roussey <sroussey@gmail.com>\n * SPDX-License-Identifier: Apache-2.0\n */\n\nimport { describe, expect } from \"vitest\";\nimport type { VectorStorageContractOpts } from \"../types\";\nimport { EAST } from \"../types\";\nimport type { Hit } from \"./shared\";\nimport { itFor, seededStore } from \"./shared\";\n\n/**\n * A hit's vector comes back as the declared `TypedArray`, not as whatever the\n * column stores.\n *\n * The stored form is a backend's own business — JSON text, a native vector\n * type, a blob — and every one of them has a decode step on the search path\n * that the tabular read does not exercise. Handing back a string or a plain\n * array is a break for every caller doing arithmetic on the result, and it is\n * invisible to a test that only reads `id` and `score`.\n */\nexport function vectorRoundTripBlock(opts: VectorStorageContractOpts): void {\n  describe(\"vectorRoundTrip\", () => {\n    const store = seededStore(opts);\n\n    itFor(opts, \"vectorRoundTrip\")(\n      \"hands back the vector as a TypedArray with the values that were written\",\n      async () => {\n        const [hit] = (await store().similaritySearch(EAST, { topK: 1 })) as Hit[];\n\n        expect(ArrayBuffer.isView(hit!.vector)).toBe(true);\n        expect([...(hit!.vector as Float32Array)]).toEqual([...EAST]);\n      },\n      opts.timeout\n    );\n  });\n}\n"
+  ],
+  "mappings": "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",
+  "debugId": "DFF5A9885C0171A264756E2164756E21",
+  "names": []
+}

package/dist/web-search/assertions/capabilityAgreement.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @license
+ * Copyright 2026 Steven Roussey <sroussey@gmail.com>
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import type { WebSearchProviderConformanceOpts } from "../types";
+/**
+ * What a provider declares is what it is asked to do, and nothing else.
+ *
+ * `WebSearchCapabilities` is a promise made to the router: an option the record
+ * says the provider cannot serve must be refused BEFORE the vendor is reached,
+ * and an option it says the provider can serve must actually be attempted. Both
+ * halves fail quietly on their own. Under-declaring loses working behaviour to
+ * `"auto"` routing, which walks past the provider that could have served the
+ * request; over-declaring is worse, because the request is routed here and the
+ * adapter throws — or, in the failure this whole record exists to prevent,
+ * silently drops the option and reports a search that ran without it.
+ *
+ * Asserted by reading the record rather than by listing what each provider
+ * does. That is the only version of this test that stays true when a provider
+ * changes what it supports, which is the event it exists to catch.
+ */
+export declare function capabilityAgreementBlock(opts: WebSearchProviderConformanceOpts): void;