@nhtio/adk 1.20260925.0 → 1.20260928.0

package/batteries/vector/conformance.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"conformance.cjs","names":[],"sources":["../../../src/batteries/vector/conformance/index.ts"],"sourcesContent":["/**\n * Shared conformance suite for vector-store adapters. Drive any adapter through\n * {@link runVectorStoreConformance} to verify it honours the same contract all shipped adapters do.\n * Public, deep-import-only (`@nhtio/adk/batteries/vector/conformance`). The suite has no test-runner\n * dependency: callers invoke it and await the returned promise from any test framework.\n *\n * @module @nhtio/adk/batteries/vector/conformance\n */\n\nimport type { CallableVectorStore } from '../contract'\n\n/** A deterministic stub encoder producing a 3-dim vector from simple text features. */\nexport const stubEncoder = async (\n  texts: string[],\n  _kind: 'query' | 'document'\n): Promise<number[][]> =>\n  texts.map((tx) => [tx.length, tx.includes('cat') ? 1 : 0, tx.includes('dog') ? 1 : 0])\n\n/**\n * A dimension-padding encoder factory: wraps {@link stubEncoder} and zero-extends to `dim`. Used by\n * backends that enforce a minimum dimension (e.g. Cloudflare Vectorize requires 32–1536).\n */\nexport const paddedStubEncoder =\n  (dim: number) =>\n  async (texts: string[], kind: 'query' | 'document'): Promise<number[][]> => {\n    const base = await stubEncoder(texts, kind)\n    return base.map((v) => padVector(v, dim))\n  }\n\n// Zero-extend (or truncate) a vector to exactly `dim` entries. dim===3 (the default) returns the\n// vector unchanged, so existing callers are byte-for-byte identical.\nconst padVector = (v: number[], dim: number): number[] => {\n  if (v.length === dim) return v\n  if (v.length > dim) return v.slice(0, dim)\n  return [...v, ...new Array(dim - v.length).fill(0)]\n}\n\n/**\n * Drive a vector-store adapter through the shared contract suite.\n *\n * @remarks\n * `makeStore` must return an already-connected store whose `'docs'` collection is created at the\n * matching dimension; it is re-invoked per test so retries are self-contained. `dim` defaults to 3\n * — pass a larger value for backends with a dimension floor (the harness pads every test vector to\n * `dim`). `opts.retry` / `opts.timeout` are forwarded to every `it()` (defaults: retry 0, 5s) and\n * exist for aggressively eventually-consistent managed backends whose read-after-write can flap for\n * seconds — a retried attempt re-runs `makeStore()` against an index that has had more time to\n * settle, without weakening any assertion.\n *\n * @param label - Human-readable label for the suite (the adapter name).\n * @param makeStore - Factory returning a fresh, connected store with the `'docs'` collection.\n * @param dim - Vector dimensionality the harness pads to (default 3).\n * @param opts - Per-`it` retry/timeout overrides.\n */\nconst assert: (condition: boolean, message: string) => asserts condition = (condition, message) => {\n  if (!condition) throw new Error(message)\n}\nconst equal = (actual: unknown, expected: unknown): boolean => {\n  if (actual === expected) return true\n  if (\n    actual === null ||\n    expected === null ||\n    typeof actual !== 'object' ||\n    typeof expected !== 'object'\n  )\n    return false\n  if (Array.isArray(actual) !== Array.isArray(expected)) return false\n  const actualRecord = actual as Record<string, unknown>\n  const expectedRecord = expected as Record<string, unknown>\n  const keysA = Object.keys(actualRecord)\n  const keysB = Object.keys(expectedRecord)\n  if (keysA.length !== keysB.length) return false\n  return keysA.every(\n    (key) => Object.hasOwn(expectedRecord, key) && equal(actualRecord[key], expectedRecord[key])\n  )\n}\nconst match = (actual: unknown, expected: unknown): boolean => {\n  if (expected === null || typeof expected !== 'object') return equal(actual, expected)\n  if (actual === null || typeof actual !== 'object') return false\n  return Object.entries(expected).every(([key, value]) =>\n    match((actual as Record<string, unknown>)[key], value)\n  )\n}\nconst expectValue = (actual: unknown) => ({\n  toBe: (expected: unknown) =>\n    assert(equal(actual, expected), `expected ${String(actual)} to be ${String(expected)}`),\n  toEqual: (expected: unknown) => assert(equal(actual, expected), 'values were not equal'),\n  toMatchObject: (expected: unknown) =>\n    assert(match(actual, expected), 'value did not match expected object'),\n  toBeDefined: () => assert(actual !== undefined, 'value was undefined'),\n  toBeUndefined: () => assert(actual === undefined, 'value was defined'),\n  toHaveLength: (length: number) =>\n    assert((actual as { length: number }).length === length, 'unexpected length'),\n  rejects: {\n    toThrow: async () => {\n      try {\n        await (actual as Promise<unknown>)\n      } catch {\n        return\n      }\n      throw new Error('expected promise to reject')\n    },\n  },\n})\n\n/**\n * Run the framework-free vector-store conformance suite against a consumer implementation.\n *\n * Each check creates a fresh store through `makeStore`; the returned promise rejects when any\n * contract assertion fails. Consumers can await this function from any test runner without\n * importing a test framework from the conformance module.\n *\n * @param label - Human-readable name used to identify the implementation under test.\n * @param makeStore - Factory returning a fresh, connected store with the `docs` collection.\n * @param dim - Vector dimensionality used by the suite (defaults to 3).\n * @param opts - Retry count and per-attempt timeout in milliseconds for eventually consistent stores.\n */\nexport const runVectorStoreConformance = async (\n  label: string,\n  makeStore: () => Promise<CallableVectorStore>,\n  dim = 3,\n  opts: { retry?: number; timeout?: number } = {}\n): Promise<void> => {\n  const p = (v: number[]): number[] => padVector(v, dim)\n  const pending: Array<() => Promise<void>> = []\n  const retry = opts.retry ?? 0\n  const timeout = opts.timeout ?? 5000\n  const runCase = async (test: () => Promise<void>): Promise<void> => {\n    let last: unknown\n    for (let attempt = 0; attempt <= retry; attempt++) {\n      let timedOut = false\n      const operation = Promise.resolve().then(test)\n      let timer: ReturnType<typeof setTimeout> | undefined\n      const deadline = new Promise<never>((_, reject) => {\n        timer = setTimeout(() => {\n          timedOut = true\n          reject(new Error(`conformance check timed out after ${timeout}ms`))\n        }, timeout)\n      })\n      try {\n        await Promise.race([operation, deadline])\n        return\n      } catch (error) {\n        // A timeout cannot cancel an arbitrary backend operation. Drain it before retrying so a\n        // late write/read from this attempt cannot race the fresh store made by the next attempt.\n        if (timedOut) {\n          last = error\n          break\n        }\n        last = error\n      } finally {\n        if (timer !== undefined) clearTimeout(timer)\n      }\n    }\n    throw last\n  }\n  const it = (_name: string, _io: unknown, test: () => Promise<void>) => {\n    pending.push(() => runCase(test))\n  }\n  const describe = (_name: string, suite: () => void) => suite()\n  const expect = expectValue\n  const io = undefined\n  describe('conformance: ' + label, () => {\n    it('upserts vectors and searches by nearVector with [0,1] score', io, async () => {\n      const vs = await makeStore()\n      await vs('docs').upsert([\n        { id: '1', vector: p([3, 1, 0]), metadata: { kind: 'animal' } },\n        { id: '2', vector: p([3, 0, 1]), metadata: { kind: 'animal' } },\n      ])\n      const res = await vs('docs')\n        .nearVector(p([3, 1, 0]))\n        .select('id', 'score')\n        .limit(2)\n      expect(res.length).toBe(2)\n      expect(res[0].id).toBeDefined()\n      expect(typeof res[0].score).toBe('number')\n      expect(res[0].score! >= 0 && res[0].score! <= 1).toBe(true)\n    })\n    it('encodes text on upsert+nearText when an encoder is configured', io, async () => {\n      const vs = await makeStore()\n      await vs('docs').upsert([{ id: 'c', document: 'cat', metadata: {} }])\n      const res = await vs('docs').nearText('cat').select('id').limit(1)\n      expect(res.length).toBe(1)\n      expect(res[0].id).toBe('c')\n    })\n    it('requires .select() on reads', io, async () => {\n      const vs = await makeStore()\n      await expect(\n        (async () => {\n          await vs('docs').nearVector(p([1, 1, 1]))\n        })()\n      ).rejects.toThrow()\n    })\n    it('filter-scan (no near) returns rows without score', io, async () => {\n      const vs = await makeStore()\n      await vs('docs').upsert([{ id: '1', vector: p([1, 0, 0]), metadata: { kind: 'x' } }])\n      const res = await vs('docs').where('kind', 'x').select('id', 'metadata').limit(10)\n      expect(res.length).toBe(1)\n      expect(res[0].score).toBeUndefined()\n    })\n    it('nested filter A AND (B OR C) selects the right subset', io, async () => {\n      const vs = await makeStore()\n      // Every record carries all three fields so the test probes nested AND/OR routing, not\n      // backend-specific missing-field semantics (e.g. Chroma's $or excludes records missing a\n      // referenced key, where the JS evaluator treats that clause as merely false).\n      await vs('docs').upsert([\n        { id: 'a', vector: p([1, 0, 0]), metadata: { kind: 'doc', year: 2024, pinned: false } }, // kept (year arm)\n        { id: 'b', vector: p([0, 1, 0]), metadata: { kind: 'doc', year: 2010, pinned: false } }, // dropped (neither arm)\n        { id: 'c', vector: p([0, 0, 1]), metadata: { kind: 'doc', year: 2010, pinned: true } }, // kept (pinned arm)\n        { id: 'd', vector: p([1, 1, 0]), metadata: { kind: 'other', year: 2024, pinned: true } }, // dropped (kind mismatch)\n      ])\n      // kind = 'doc' AND (year >= 2024 OR pinned = true)\n      const res = await vs('docs')\n        .where('kind', 'doc')\n        .andWhere((qb) => qb.where('year', '>=', 2024).orWhere('pinned', true))\n        .select('id')\n        .limit(10)\n      expect(res.map((r) => r.id).sort()).toEqual(['a', 'c'])\n    })\n    it('projection: vector excluded unless selected', io, async () => {\n      const vs = await makeStore()\n      await vs('docs').upsert([{ id: '1', vector: p([1, 0, 0]) }])\n      const noVec = await vs('docs')\n        .nearVector(p([1, 0, 0]))\n        .select('id')\n        .limit(1)\n      expect(noVec[0].vector).toBeUndefined()\n      const withVec = await vs('docs')\n        .nearVector(p([1, 0, 0]))\n        .select('id', 'vector')\n        .limit(1)\n      expect(Array.isArray(withVec[0].vector)).toBe(true)\n    })\n    it('deletes by id', io, async () => {\n      const vs = await makeStore()\n      await vs('docs').upsert([\n        { id: '1', vector: p([1, 0, 0]) },\n        { id: '2', vector: p([0, 1, 0]) },\n      ])\n      await vs('docs').whereIn('id', ['1']).delete()\n      const all = await vs('docs').select('id').limit(10)\n      expect(all.length).toBe(1)\n    })\n    it('throws transaction-unsupported when capabilities.transactions is false', io, async () => {\n      const vs = await makeStore()\n      if (!vs.capabilities.transactions) {\n        await expect(vs.transaction(async () => {})).rejects.toThrow()\n      }\n    })\n  })\n  for (const fn of pending) {\n    await fn()\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"conformance.cjs","names":[],"sources":["../../../src/batteries/vector/conformance/index.ts"],"sourcesContent":["/**\n * Shared conformance suite for vector-store adapters. Drive any adapter through\n * {@link runVectorStoreConformance} to verify it honours the same contract all shipped adapters do.\n * Public, deep-import-only (`@nhtio/adk/batteries/vector/conformance`). The suite has no test-runner\n * dependency: callers invoke it and await the returned promise from any test framework.\n *\n * @module @nhtio/adk/batteries/vector/conformance\n */\n\nimport type { CallableVectorStore } from '../contract'\n\n/** A deterministic stub encoder producing a 3-dim vector from simple text features. */\nexport const stubEncoder = async (\n  texts: string[],\n  _kind: 'query' | 'document'\n): Promise<number[][]> =>\n  texts.map((tx) => [tx.length, tx.includes('cat') ? 1 : 0, tx.includes('dog') ? 1 : 0])\n\n/**\n * A dimension-padding encoder factory: wraps {@link stubEncoder} and zero-extends to `dim`. Used by\n * backends that enforce a minimum dimension (e.g. Cloudflare Vectorize requires 32–1536).\n */\nexport const paddedStubEncoder =\n  (dim: number) =>\n  async (texts: string[], kind: 'query' | 'document'): Promise<number[][]> => {\n    const base = await stubEncoder(texts, kind)\n    return base.map((v) => padVector(v, dim))\n  }\n\n// Zero-extend (or truncate) a vector to exactly `dim` entries. dim===3 (the default) returns the\n// vector unchanged, so existing callers are byte-for-byte identical.\nconst padVector = (v: number[], dim: number): number[] => {\n  if (v.length === dim) return v\n  if (v.length > dim) return v.slice(0, dim)\n  return [...v, ...new Array(dim - v.length).fill(0)]\n}\n\n/**\n * Drive a vector-store adapter through the shared contract suite.\n *\n * @remarks\n * `makeStore` must return an already-connected store whose `'docs'` collection is created at the\n * matching dimension; it is re-invoked per test so retries are self-contained. `dim` defaults to 3\n * — pass a larger value for backends with a dimension floor (the harness pads every test vector to\n * `dim`). `opts.retry` / `opts.timeout` are forwarded to every `it()` (defaults: retry 0, 5s) and\n * exist for aggressively eventually-consistent managed backends whose read-after-write can flap for\n * seconds — a retried attempt re-runs `makeStore()` against an index that has had more time to\n * settle, without weakening any assertion.\n *\n * @param label - Human-readable label for the suite (the adapter name).\n * @param makeStore - Factory returning a fresh, connected store with the `'docs'` collection.\n * @param dim - Vector dimensionality the harness pads to (default 3).\n * @param opts - Per-`it` retry/timeout overrides.\n */\nconst assert: (condition: boolean, message: string) => asserts condition = (condition, message) => {\n  if (!condition) throw new Error(message)\n}\nconst equal = (actual: unknown, expected: unknown): boolean => {\n  if (actual === expected) return true\n  if (\n    actual === null ||\n    expected === null ||\n    typeof actual !== 'object' ||\n    typeof expected !== 'object'\n  )\n    return false\n  if (Array.isArray(actual) !== Array.isArray(expected)) return false\n  const actualRecord = actual as Record<string, unknown>\n  const expectedRecord = expected as Record<string, unknown>\n  const keysA = Object.keys(actualRecord)\n  const keysB = Object.keys(expectedRecord)\n  if (keysA.length !== keysB.length) return false\n  return keysA.every(\n    (key) => Object.hasOwn(expectedRecord, key) && equal(actualRecord[key], expectedRecord[key])\n  )\n}\nconst match = (actual: unknown, expected: unknown): boolean => {\n  if (expected === null || typeof expected !== 'object') return equal(actual, expected)\n  if (actual === null || typeof actual !== 'object') return false\n  return Object.entries(expected).every(([key, value]) =>\n    match((actual as Record<string, unknown>)[key], value)\n  )\n}\nconst expectValue = (actual: unknown) => ({\n  toBe: (expected: unknown) =>\n    assert(equal(actual, expected), `expected ${String(actual)} to be ${String(expected)}`),\n  toEqual: (expected: unknown) => assert(equal(actual, expected), 'values were not equal'),\n  toMatchObject: (expected: unknown) =>\n    assert(match(actual, expected), 'value did not match expected object'),\n  toBeDefined: () => assert(actual !== undefined, 'value was undefined'),\n  toBeUndefined: () => assert(actual === undefined, 'value was defined'),\n  toHaveLength: (length: number) =>\n    assert((actual as { length: number }).length === length, 'unexpected length'),\n  rejects: {\n    toThrow: async () => {\n      try {\n        await (actual as Promise<unknown>)\n      } catch {\n        return\n      }\n      throw new Error('expected promise to reject')\n    },\n  },\n})\n\n/**\n * Run the framework-free vector-store conformance suite against a consumer implementation.\n *\n * Each check creates a fresh store through `makeStore`; the returned promise rejects when any\n * contract assertion fails. Consumers can await this function from any test runner without\n * importing a test framework from the conformance module.\n *\n * @param label - Human-readable name used to identify the implementation under test.\n * @param makeStore - Factory returning a fresh, connected store with the `docs` collection.\n * @param dim - Vector dimensionality used by the suite (defaults to 3).\n * @param opts - Retry count and per-attempt timeout in milliseconds for eventually consistent stores.\n */\nexport const runVectorStoreConformance = async (\n  label: string,\n  makeStore: () => Promise<CallableVectorStore>,\n  dim = 3,\n  opts: { retry?: number; timeout?: number } = {}\n): Promise<void> => {\n  const p = (v: number[]): number[] => padVector(v, dim)\n  const pending: Array<() => Promise<void>> = []\n  const retry = opts.retry ?? 0\n  const timeout = opts.timeout ?? 5000\n  const runCase = async (test: () => Promise<void>): Promise<void> => {\n    let last: unknown\n    for (let attempt = 0; attempt <= retry; attempt++) {\n      let timedOut = false\n      const operation = Promise.resolve().then(test)\n      let timer: ReturnType<typeof setTimeout> | undefined\n      const deadline = new Promise<never>((_, reject) => {\n        timer = setTimeout(() => {\n          timedOut = true\n          reject(new Error(`conformance check timed out after ${timeout}ms`))\n        }, timeout)\n      })\n      try {\n        await Promise.race([operation, deadline])\n        return\n      } catch (error) {\n        // A timeout cannot cancel an arbitrary backend operation. Drain it before retrying so a\n        // late write/read from this attempt cannot race the fresh store made by the next attempt.\n        if (timedOut) {\n          last = error\n          break\n        }\n        last = error\n      } finally {\n        if (timer !== undefined) clearTimeout(timer)\n      }\n    }\n    throw last\n  }\n  const it = (_name: string, _io: unknown, test: () => Promise<void>) => {\n    pending.push(() => runCase(test))\n  }\n  const describe = (_name: string, suite: () => void) => suite()\n  const expect = expectValue\n  const io = undefined\n  describe('conformance: ' + label, () => {\n    it('upserts vectors and searches by nearVector with [0,1] score', io, async () => {\n      const vs = await makeStore()\n      await vs('docs').upsert([\n        { id: '1', vector: p([3, 1, 0]), metadata: { kind: 'animal' } },\n        { id: '2', vector: p([3, 0, 1]), metadata: { kind: 'animal' } },\n      ])\n      const res = await vs('docs')\n        .nearVector(p([3, 1, 0]))\n        .select('id', 'score')\n        .limit(2)\n      expect(res.length).toBe(2)\n      expect(res[0].id).toBeDefined()\n      expect(typeof res[0].score).toBe('number')\n      expect(res[0].score! >= 0 && res[0].score! <= 1).toBe(true)\n    })\n    it('encodes text on upsert+nearText when an encoder is configured', io, async () => {\n      const vs = await makeStore()\n      await vs('docs').upsert([{ id: 'c', document: 'cat', metadata: {} }])\n      const res = await vs('docs').nearText('cat').select('id').limit(1)\n      expect(res.length).toBe(1)\n      expect(res[0].id).toBe('c')\n    })\n    it('requires .select() on reads', io, async () => {\n      const vs = await makeStore()\n      await expect(\n        (async () => {\n          await vs('docs').nearVector(p([1, 1, 1]))\n        })()\n      ).rejects.toThrow()\n    })\n    it('filter-scan (no near) returns rows without score', io, async () => {\n      const vs = await makeStore()\n      await vs('docs').upsert([{ id: '1', vector: p([1, 0, 0]), metadata: { kind: 'x' } }])\n      const res = await vs('docs').where('kind', 'x').select('id', 'metadata').limit(10)\n      expect(res.length).toBe(1)\n      expect(res[0].score).toBeUndefined()\n    })\n    it('nested filter A AND (B OR C) selects the right subset', io, async () => {\n      const vs = await makeStore()\n      // Every record carries all three fields so the test probes nested AND/OR routing, not\n      // backend-specific missing-field semantics (e.g. Chroma's $or excludes records missing a\n      // referenced key, where the JS evaluator treats that clause as merely false).\n      await vs('docs').upsert([\n        { id: 'a', vector: p([1, 0, 0]), metadata: { kind: 'doc', year: 2024, pinned: false } }, // kept (year arm)\n        { id: 'b', vector: p([0, 1, 0]), metadata: { kind: 'doc', year: 2010, pinned: false } }, // dropped (neither arm)\n        { id: 'c', vector: p([0, 0, 1]), metadata: { kind: 'doc', year: 2010, pinned: true } }, // kept (pinned arm)\n        { id: 'd', vector: p([1, 1, 0]), metadata: { kind: 'other', year: 2024, pinned: true } }, // dropped (kind mismatch)\n      ])\n      // kind = 'doc' AND (year >= 2024 OR pinned = true)\n      const res = await vs('docs')\n        .where('kind', 'doc')\n        .andWhere((qb) => qb.where('year', '>=', 2024).orWhere('pinned', true))\n        .select('id')\n        .limit(10)\n      expect(res.map((r) => r.id).sort()).toEqual(['a', 'c'])\n    })\n    it('projection: vector excluded unless selected', io, async () => {\n      const vs = await makeStore()\n      await vs('docs').upsert([{ id: '1', vector: p([1, 0, 0]) }])\n      const noVec = await vs('docs')\n        .nearVector(p([1, 0, 0]))\n        .select('id')\n        .limit(1)\n      expect(noVec[0].vector).toBeUndefined()\n      const withVec = await vs('docs')\n        .nearVector(p([1, 0, 0]))\n        .select('id', 'vector')\n        .limit(1)\n      expect(Array.isArray(withVec[0].vector)).toBe(true)\n    })\n    it('deletes by id', io, async () => {\n      const vs = await makeStore()\n      await vs('docs').upsert([\n        { id: '1', vector: p([1, 0, 0]) },\n        { id: '2', vector: p([0, 1, 0]) },\n      ])\n      await vs('docs').whereIn('id', ['1']).delete()\n      const all = await vs('docs').select('id').limit(10)\n      expect(all.length).toBe(1)\n    })\n    it('throws transaction-unsupported when capabilities.transactions is false', io, async () => {\n      const vs = await makeStore()\n      if (!vs.capabilities.transactions) {\n        await expect(vs.transaction(async () => {})).rejects.toThrow()\n      }\n    })\n    it('renameCollection: honours capabilities.rename', io, async () => {\n      const vs = await makeStore()\n      if (vs.capabilities.rename) {\n        await vs.schema.dropCollectionIfExists('docs_renamed')\n        let bodyFailed = false\n        let bodyError: unknown\n        try {\n          await vs('docs').upsert([\n            { id: '1', vector: p([3, 1, 0]) },\n            { id: '2', vector: p([3, 0, 1]) },\n          ])\n          await vs.schema.renameCollection('docs', 'docs_renamed')\n          expect(await vs.schema.hasCollection('docs')).toBe(false)\n          expect(await vs.schema.hasCollection('docs_renamed')).toBe(true)\n          const res = await vs('docs_renamed')\n            .nearVector(p([3, 1, 0]))\n            .select('id', 'score')\n            .limit(2)\n          expect(res.length).toBe(2)\n          expect(res[0].id).toBe('1')\n          expect(typeof res[0].score).toBe('number')\n          expect(res[0].score! >= 0 && res[0].score! <= 1).toBe(true)\n          await vs('docs_renamed').upsert([{ id: '3', vector: p([1, 1, 1]) }])\n          const all = await vs('docs_renamed').select('id').limit(10)\n          expect(all.map((r) => r.id).sort()).toEqual(['1', '2', '3'])\n        } catch (e) {\n          bodyFailed = true\n          bodyError = e\n        }\n        // A cleanup failure here must never mask a real failure from the try block above: only\n        // swallow it when the body already failed (there's nothing left to mask); otherwise let it\n        // propagate, since a passing body followed by a broken cleanup is itself a real failure.\n        try {\n          await vs.schema.dropCollectionIfExists('docs_renamed')\n        } catch (cleanupErr) {\n          if (!bodyFailed) throw cleanupErr\n        }\n        if (bodyFailed) throw bodyError\n      } else {\n        await expect(vs.schema.renameCollection('docs', 'docs_renamed')).rejects.toThrow()\n      }\n    })\n  })\n  for (const fn of pending) {\n    await fn()\n  }\n}\n"],"mappings":";;;;AAYA,IAAa,cAAc,OACzB,OACA,UAEA,MAAM,KAAK,OAAO;CAAC,GAAG;CAAQ,GAAG,SAAS,KAAK,IAAI,IAAI;CAAG,GAAG,SAAS,KAAK,IAAI,IAAI;AAAC,CAAC;;;;;AAMvF,IAAa,qBACV,QACD,OAAO,OAAiB,SAAoD;CAE1E,QAAO,MADY,YAAY,OAAO,IAAI,GAC9B,KAAK,MAAM,UAAU,GAAG,GAAG,CAAC;AAC1C;AAIF,IAAM,aAAa,GAAa,QAA0B;CACxD,IAAI,EAAE,WAAW,KAAK,OAAO;CAC7B,IAAI,EAAE,SAAS,KAAK,OAAO,EAAE,MAAM,GAAG,GAAG;CACzC,OAAO,CAAC,GAAG,GAAG,GAAG,IAAI,MAAM,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC;AACpD;;;;;;;;;;;;;;;;;;AAmBA,IAAM,UAAsE,WAAW,YAAY;CACjG,IAAI,CAAC,WAAW,MAAM,IAAI,MAAM,OAAO;AACzC;AACA,IAAM,SAAS,QAAiB,aAA+B;CAC7D,IAAI,WAAW,UAAU,OAAO;CAChC,IACE,WAAW,QACX,aAAa,QACb,OAAO,WAAW,YAClB,OAAO,aAAa,UAEpB,OAAO;CACT,IAAI,MAAM,QAAQ,MAAM,MAAM,MAAM,QAAQ,QAAQ,GAAG,OAAO;CAC9D,MAAM,eAAe;CACrB,MAAM,iBAAiB;CACvB,MAAM,QAAQ,OAAO,KAAK,YAAY;CACtC,MAAM,QAAQ,OAAO,KAAK,cAAc;CACxC,IAAI,MAAM,WAAW,MAAM,QAAQ,OAAO;CAC1C,OAAO,MAAM,OACV,QAAQ,OAAO,OAAO,gBAAgB,GAAG,KAAK,MAAM,aAAa,MAAM,eAAe,IAAI,CAC7F;AACF;AACA,IAAM,SAAS,QAAiB,aAA+B;CAC7D,IAAI,aAAa,QAAQ,OAAO,aAAa,UAAU,OAAO,MAAM,QAAQ,QAAQ;CACpF,IAAI,WAAW,QAAQ,OAAO,WAAW,UAAU,OAAO;CAC1D,OAAO,OAAO,QAAQ,QAAQ,EAAE,OAAO,CAAC,KAAK,WAC3C,MAAO,OAAmC,MAAM,KAAK,CACvD;AACF;AACA,IAAM,eAAe,YAAqB;CACxC,OAAO,aACL,OAAO,MAAM,QAAQ,QAAQ,GAAG,YAAY,OAAO,MAAM,EAAE,SAAS,OAAO,QAAQ,GAAG;CACxF,UAAU,aAAsB,OAAO,MAAM,QAAQ,QAAQ,GAAG,uBAAuB;CACvF,gBAAgB,aACd,OAAO,MAAM,QAAQ,QAAQ,GAAG,qCAAqC;CACvE,mBAAmB,OAAO,WAAW,KAAA,GAAW,qBAAqB;CACrE,qBAAqB,OAAO,WAAW,KAAA,GAAW,mBAAmB;CACrE,eAAe,WACb,OAAQ,OAA8B,WAAW,QAAQ,mBAAmB;CAC9E,SAAS,EACP,SAAS,YAAY;EACnB,IAAI;GACF,MAAO;EACT,QAAQ;GACN;EACF;EACA,MAAM,IAAI,MAAM,4BAA4B;CAC9C,EACF;AACF;;;;;;;;;;;;;AAcA,IAAa,4BAA4B,OACvC,OACA,WACA,MAAM,GACN,OAA6C,CAAC,MAC5B;CAClB,MAAM,KAAK,MAA0B,UAAU,GAAG,GAAG;CACrD,MAAM,UAAsC,CAAC;CAC7C,MAAM,QAAQ,KAAK,SAAS;CAC5B,MAAM,UAAU,KAAK,WAAW;CAChC,MAAM,UAAU,OAAO,SAA6C;EAClE,IAAI;EACJ,KAAK,IAAI,UAAU,GAAG,WAAW,OAAO,WAAW;GACjD,IAAI,WAAW;GACf,MAAM,YAAY,QAAQ,QAAQ,EAAE,KAAK,IAAI;GAC7C,IAAI;GACJ,MAAM,WAAW,IAAI,SAAgB,GAAG,WAAW;IACjD,QAAQ,iBAAiB;KACvB,WAAW;KACX,uBAAO,IAAI,MAAM,qCAAqC,QAAQ,GAAG,CAAC;IACpE,GAAG,OAAO;GACZ,CAAC;GACD,IAAI;IACF,MAAM,QAAQ,KAAK,CAAC,WAAW,QAAQ,CAAC;IACxC;GACF,SAAS,OAAO;IAGd,IAAI,UAAU;KACZ,OAAO;KACP;IACF;IACA,OAAO;GACT,UAAU;IACR,IAAI,UAAU,KAAA,GAAW,aAAa,KAAK;GAC7C;EACF;EACA,MAAM;CACR;CACA,MAAM,MAAM,OAAe,KAAc,SAA8B;EACrE,QAAQ,WAAW,QAAQ,IAAI,CAAC;CAClC;CACA,MAAM,YAAY,OAAe,UAAsB,MAAM;CAC7D,MAAM,SAAS;CACf,MAAM,KAAK,KAAA;CACX,SAAS,kBAAkB,aAAa;EACtC,GAAG,+DAA+D,IAAI,YAAY;GAChF,MAAM,KAAK,MAAM,UAAU;GAC3B,MAAM,GAAG,MAAM,EAAE,OAAO,CACtB;IAAE,IAAI;IAAK,QAAQ,EAAE;KAAC;KAAG;KAAG;IAAC,CAAC;IAAG,UAAU,EAAE,MAAM,SAAS;GAAE,GAC9D;IAAE,IAAI;IAAK,QAAQ,EAAE;KAAC;KAAG;KAAG;IAAC,CAAC;IAAG,UAAU,EAAE,MAAM,SAAS;GAAE,CAChE,CAAC;GACD,MAAM,MAAM,MAAM,GAAG,MAAM,EACxB,WAAW,EAAE;IAAC;IAAG;IAAG;GAAC,CAAC,CAAC,EACvB,OAAO,MAAM,OAAO,EACpB,MAAM,CAAC;GACV,OAAO,IAAI,MAAM,EAAE,KAAK,CAAC;GACzB,OAAO,IAAI,GAAG,EAAE,EAAE,YAAY;GAC9B,OAAO,OAAO,IAAI,GAAG,KAAK,EAAE,KAAK,QAAQ;GACzC,OAAO,IAAI,GAAG,SAAU,KAAK,IAAI,GAAG,SAAU,CAAC,EAAE,KAAK,IAAI;EAC5D,CAAC;EACD,GAAG,iEAAiE,IAAI,YAAY;GAClF,MAAM,KAAK,MAAM,UAAU;GAC3B,MAAM,GAAG,MAAM,EAAE,OAAO,CAAC;IAAE,IAAI;IAAK,UAAU;IAAO,UAAU,CAAC;GAAE,CAAC,CAAC;GACpE,MAAM,MAAM,MAAM,GAAG,MAAM,EAAE,SAAS,KAAK,EAAE,OAAO,IAAI,EAAE,MAAM,CAAC;GACjE,OAAO,IAAI,MAAM,EAAE,KAAK,CAAC;GACzB,OAAO,IAAI,GAAG,EAAE,EAAE,KAAK,GAAG;EAC5B,CAAC;EACD,GAAG,+BAA+B,IAAI,YAAY;GAChD,MAAM,KAAK,MAAM,UAAU;GAC3B,MAAM,QACH,YAAY;IACX,MAAM,GAAG,MAAM,EAAE,WAAW,EAAE;KAAC;KAAG;KAAG;IAAC,CAAC,CAAC;GAC1C,GAAG,CACL,EAAE,QAAQ,QAAQ;EACpB,CAAC;EACD,GAAG,oDAAoD,IAAI,YAAY;GACrE,MAAM,KAAK,MAAM,UAAU;GAC3B,MAAM,GAAG,MAAM,EAAE,OAAO,CAAC;IAAE,IAAI;IAAK,QAAQ,EAAE;KAAC;KAAG;KAAG;IAAC,CAAC;IAAG,UAAU,EAAE,MAAM,IAAI;GAAE,CAAC,CAAC;GACpF,MAAM,MAAM,MAAM,GAAG,MAAM,EAAE,MAAM,QAAQ,GAAG,EAAE,OAAO,MAAM,UAAU,EAAE,MAAM,EAAE;GACjF,OAAO,IAAI,MAAM,EAAE,KAAK,CAAC;GACzB,OAAO,IAAI,GAAG,KAAK,EAAE,cAAc;EACrC,CAAC;EACD,GAAG,yDAAyD,IAAI,YAAY;GAC1E,MAAM,KAAK,MAAM,UAAU;GAI3B,MAAM,GAAG,MAAM,EAAE,OAAO;IACtB;KAAE,IAAI;KAAK,QAAQ,EAAE;MAAC;MAAG;MAAG;KAAC,CAAC;KAAG,UAAU;MAAE,MAAM;MAAO,MAAM;MAAM,QAAQ;KAAM;IAAE;IACtF;KAAE,IAAI;KAAK,QAAQ,EAAE;MAAC;MAAG;MAAG;KAAC,CAAC;KAAG,UAAU;MAAE,MAAM;MAAO,MAAM;MAAM,QAAQ;KAAM;IAAE;IACtF;KAAE,IAAI;KAAK,QAAQ,EAAE;MAAC;MAAG;MAAG;KAAC,CAAC;KAAG,UAAU;MAAE,MAAM;MAAO,MAAM;MAAM,QAAQ;KAAK;IAAE;IACrF;KAAE,IAAI;KAAK,QAAQ,EAAE;MAAC;MAAG;MAAG;KAAC,CAAC;KAAG,UAAU;MAAE,MAAM;MAAS,MAAM;MAAM,QAAQ;KAAK;IAAE;GACzF,CAAC;GAOD,QAAO,MALW,GAAG,MAAM,EACxB,MAAM,QAAQ,KAAK,EACnB,UAAU,OAAO,GAAG,MAAM,QAAQ,MAAM,IAAI,EAAE,QAAQ,UAAU,IAAI,CAAC,EACrE,OAAO,IAAI,EACX,MAAM,EAAE,GACA,KAAK,MAAM,EAAE,EAAE,EAAE,KAAK,CAAC,EAAE,QAAQ,CAAC,KAAK,GAAG,CAAC;EACxD,CAAC;EACD,GAAG,+CAA+C,IAAI,YAAY;GAChE,MAAM,KAAK,MAAM,UAAU;GAC3B,MAAM,GAAG,MAAM,EAAE,OAAO,CAAC;IAAE,IAAI;IAAK,QAAQ,EAAE;KAAC;KAAG;KAAG;IAAC,CAAC;GAAE,CAAC,CAAC;GAK3D,QAAO,MAJa,GAAG,MAAM,EAC1B,WAAW,EAAE;IAAC;IAAG;IAAG;GAAC,CAAC,CAAC,EACvB,OAAO,IAAI,EACX,MAAM,CAAC,GACG,GAAG,MAAM,EAAE,cAAc;GACtC,MAAM,UAAU,MAAM,GAAG,MAAM,EAC5B,WAAW,EAAE;IAAC;IAAG;IAAG;GAAC,CAAC,CAAC,EACvB,OAAO,MAAM,QAAQ,EACrB,MAAM,CAAC;GACV,OAAO,MAAM,QAAQ,QAAQ,GAAG,MAAM,CAAC,EAAE,KAAK,IAAI;EACpD,CAAC;EACD,GAAG,iBAAiB,IAAI,YAAY;GAClC,MAAM,KAAK,MAAM,UAAU;GAC3B,MAAM,GAAG,MAAM,EAAE,OAAO,CACtB;IAAE,IAAI;IAAK,QAAQ,EAAE;KAAC;KAAG;KAAG;IAAC,CAAC;GAAE,GAChC;IAAE,IAAI;IAAK,QAAQ,EAAE;KAAC;KAAG;KAAG;IAAC,CAAC;GAAE,CAClC,CAAC;GACD,MAAM,GAAG,MAAM,EAAE,QAAQ,MAAM,CAAC,GAAG,CAAC,EAAE,OAAO;GAE7C,QAAO,MADW,GAAG,MAAM,EAAE,OAAO,IAAI,EAAE,MAAM,EAAE,GACvC,MAAM,EAAE,KAAK,CAAC;EAC3B,CAAC;EACD,GAAG,0EAA0E,IAAI,YAAY;GAC3F,MAAM,KAAK,MAAM,UAAU;GAC3B,IAAI,CAAC,GAAG,aAAa,cACnB,MAAM,OAAO,GAAG,YAAY,YAAY,CAAC,CAAC,CAAC,EAAE,QAAQ,QAAQ;EAEjE,CAAC;EACD,GAAG,iDAAiD,IAAI,YAAY;GAClE,MAAM,KAAK,MAAM,UAAU;GAC3B,IAAI,GAAG,aAAa,QAAQ;IAC1B,MAAM,GAAG,OAAO,uBAAuB,cAAc;IACrD,IAAI,aAAa;IACjB,IAAI;IACJ,IAAI;KACF,MAAM,GAAG,MAAM,EAAE,OAAO,CACtB;MAAE,IAAI;MAAK,QAAQ,EAAE;OAAC;OAAG;OAAG;MAAC,CAAC;KAAE,GAChC;MAAE,IAAI;MAAK,QAAQ,EAAE;OAAC;OAAG;OAAG;MAAC,CAAC;KAAE,CAClC,CAAC;KACD,MAAM,GAAG,OAAO,iBAAiB,QAAQ,cAAc;KACvD,OAAO,MAAM,GAAG,OAAO,cAAc,MAAM,CAAC,EAAE,KAAK,KAAK;KACxD,OAAO,MAAM,GAAG,OAAO,cAAc,cAAc,CAAC,EAAE,KAAK,IAAI;KAC/D,MAAM,MAAM,MAAM,GAAG,cAAc,EAChC,WAAW,EAAE;MAAC;MAAG;MAAG;KAAC,CAAC,CAAC,EACvB,OAAO,MAAM,OAAO,EACpB,MAAM,CAAC;KACV,OAAO,IAAI,MAAM,EAAE,KAAK,CAAC;KACzB,OAAO,IAAI,GAAG,EAAE,EAAE,KAAK,GAAG;KAC1B,OAAO,OAAO,IAAI,GAAG,KAAK,EAAE,KAAK,QAAQ;KACzC,OAAO,IAAI,GAAG,SAAU,KAAK,IAAI,GAAG,SAAU,CAAC,EAAE,KAAK,IAAI;KAC1D,MAAM,GAAG,cAAc,EAAE,OAAO,CAAC;MAAE,IAAI;MAAK,QAAQ,EAAE;OAAC;OAAG;OAAG;MAAC,CAAC;KAAE,CAAC,CAAC;KAEnE,QAAO,MADW,GAAG,cAAc,EAAE,OAAO,IAAI,EAAE,MAAM,EAAE,GAC/C,KAAK,MAAM,EAAE,EAAE,EAAE,KAAK,CAAC,EAAE,QAAQ;MAAC;MAAK;MAAK;KAAG,CAAC;IAC7D,SAAS,GAAG;KACV,aAAa;KACb,YAAY;IACd;IAIA,IAAI;KACF,MAAM,GAAG,OAAO,uBAAuB,cAAc;IACvD,SAAS,YAAY;KACnB,IAAI,CAAC,YAAY,MAAM;IACzB;IACA,IAAI,YAAY,MAAM;GACxB,OACE,MAAM,OAAO,GAAG,OAAO,iBAAiB,QAAQ,cAAc,CAAC,EAAE,QAAQ,QAAQ;EAErF,CAAC;CACH,CAAC;CACD,KAAK,MAAM,MAAM,SACf,MAAM,GAAG;AAEb"}

package/batteries/vector/conformance.mjs

@@ -289,6 +289,65 @@ var runVectorStoreConformance = async (label, makeStore, dim = 3, opts = {}) =>
 			const vs = await makeStore();
 			if (!vs.capabilities.transactions) await expect(vs.transaction(async () => {})).rejects.toThrow();
 		});
+		it("renameCollection: honours capabilities.rename", io, async () => {
+			const vs = await makeStore();
+			if (vs.capabilities.rename) {
+				await vs.schema.dropCollectionIfExists("docs_renamed");
+				let bodyFailed = false;
+				let bodyError;
+				try {
+					await vs("docs").upsert([{
+						id: "1",
+						vector: p([
+							3,
+							1,
+							0
+						])
+					}, {
+						id: "2",
+						vector: p([
+							3,
+							0,
+							1
+						])
+					}]);
+					await vs.schema.renameCollection("docs", "docs_renamed");
+					expect(await vs.schema.hasCollection("docs")).toBe(false);
+					expect(await vs.schema.hasCollection("docs_renamed")).toBe(true);
+					const res = await vs("docs_renamed").nearVector(p([
+						3,
+						1,
+						0
+					])).select("id", "score").limit(2);
+					expect(res.length).toBe(2);
+					expect(res[0].id).toBe("1");
+					expect(typeof res[0].score).toBe("number");
+					expect(res[0].score >= 0 && res[0].score <= 1).toBe(true);
+					await vs("docs_renamed").upsert([{
+						id: "3",
+						vector: p([
+							1,
+							1,
+							1
+						])
+					}]);
+					expect((await vs("docs_renamed").select("id").limit(10)).map((r) => r.id).sort()).toEqual([
+						"1",
+						"2",
+						"3"
+					]);
+				} catch (e) {
+					bodyFailed = true;
+					bodyError = e;
+				}
+				try {
+					await vs.schema.dropCollectionIfExists("docs_renamed");
+				} catch (cleanupErr) {
+					if (!bodyFailed) throw cleanupErr;
+				}
+				if (bodyFailed) throw bodyError;
+			} else await expect(vs.schema.renameCollection("docs", "docs_renamed")).rejects.toThrow();
+		});
 	});
 	for (const fn of pending) await fn();
 };

package/batteries/vector/conformance.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"conformance.mjs","names":[],"sources":["../../../src/batteries/vector/conformance/index.ts"],"sourcesContent":["/**\n * Shared conformance suite for vector-store adapters. Drive any adapter through\n * {@link runVectorStoreConformance} to verify it honours the same contract all shipped adapters do.\n * Public, deep-import-only (`@nhtio/adk/batteries/vector/conformance`). The suite has no test-runner\n * dependency: callers invoke it and await the returned promise from any test framework.\n *\n * @module @nhtio/adk/batteries/vector/conformance\n */\n\nimport type { CallableVectorStore } from '../contract'\n\n/** A deterministic stub encoder producing a 3-dim vector from simple text features. */\nexport const stubEncoder = async (\n  texts: string[],\n  _kind: 'query' | 'document'\n): Promise<number[][]> =>\n  texts.map((tx) => [tx.length, tx.includes('cat') ? 1 : 0, tx.includes('dog') ? 1 : 0])\n\n/**\n * A dimension-padding encoder factory: wraps {@link stubEncoder} and zero-extends to `dim`. Used by\n * backends that enforce a minimum dimension (e.g. Cloudflare Vectorize requires 32–1536).\n */\nexport const paddedStubEncoder =\n  (dim: number) =>\n  async (texts: string[], kind: 'query' | 'document'): Promise<number[][]> => {\n    const base = await stubEncoder(texts, kind)\n    return base.map((v) => padVector(v, dim))\n  }\n\n// Zero-extend (or truncate) a vector to exactly `dim` entries. dim===3 (the default) returns the\n// vector unchanged, so existing callers are byte-for-byte identical.\nconst padVector = (v: number[], dim: number): number[] => {\n  if (v.length === dim) return v\n  if (v.length > dim) return v.slice(0, dim)\n  return [...v, ...new Array(dim - v.length).fill(0)]\n}\n\n/**\n * Drive a vector-store adapter through the shared contract suite.\n *\n * @remarks\n * `makeStore` must return an already-connected store whose `'docs'` collection is created at the\n * matching dimension; it is re-invoked per test so retries are self-contained. `dim` defaults to 3\n * — pass a larger value for backends with a dimension floor (the harness pads every test vector to\n * `dim`). `opts.retry` / `opts.timeout` are forwarded to every `it()` (defaults: retry 0, 5s) and\n * exist for aggressively eventually-consistent managed backends whose read-after-write can flap for\n * seconds — a retried attempt re-runs `makeStore()` against an index that has had more time to\n * settle, without weakening any assertion.\n *\n * @param label - Human-readable label for the suite (the adapter name).\n * @param makeStore - Factory returning a fresh, connected store with the `'docs'` collection.\n * @param dim - Vector dimensionality the harness pads to (default 3).\n * @param opts - Per-`it` retry/timeout overrides.\n */\nconst assert: (condition: boolean, message: string) => asserts condition = (condition, message) => {\n  if (!condition) throw new Error(message)\n}\nconst equal = (actual: unknown, expected: unknown): boolean => {\n  if (actual === expected) return true\n  if (\n    actual === null ||\n    expected === null ||\n    typeof actual !== 'object' ||\n    typeof expected !== 'object'\n  )\n    return false\n  if (Array.isArray(actual) !== Array.isArray(expected)) return false\n  const actualRecord = actual as Record<string, unknown>\n  const expectedRecord = expected as Record<string, unknown>\n  const keysA = Object.keys(actualRecord)\n  const keysB = Object.keys(expectedRecord)\n  if (keysA.length !== keysB.length) return false\n  return keysA.every(\n    (key) => Object.hasOwn(expectedRecord, key) && equal(actualRecord[key], expectedRecord[key])\n  )\n}\nconst match = (actual: unknown, expected: unknown): boolean => {\n  if (expected === null || typeof expected !== 'object') return equal(actual, expected)\n  if (actual === null || typeof actual !== 'object') return false\n  return Object.entries(expected).every(([key, value]) =>\n    match((actual as Record<string, unknown>)[key], value)\n  )\n}\nconst expectValue = (actual: unknown) => ({\n  toBe: (expected: unknown) =>\n    assert(equal(actual, expected), `expected ${String(actual)} to be ${String(expected)}`),\n  toEqual: (expected: unknown) => assert(equal(actual, expected), 'values were not equal'),\n  toMatchObject: (expected: unknown) =>\n    assert(match(actual, expected), 'value did not match expected object'),\n  toBeDefined: () => assert(actual !== undefined, 'value was undefined'),\n  toBeUndefined: () => assert(actual === undefined, 'value was defined'),\n  toHaveLength: (length: number) =>\n    assert((actual as { length: number }).length === length, 'unexpected length'),\n  rejects: {\n    toThrow: async () => {\n      try {\n        await (actual as Promise<unknown>)\n      } catch {\n        return\n      }\n      throw new Error('expected promise to reject')\n    },\n  },\n})\n\n/**\n * Run the framework-free vector-store conformance suite against a consumer implementation.\n *\n * Each check creates a fresh store through `makeStore`; the returned promise rejects when any\n * contract assertion fails. Consumers can await this function from any test runner without\n * importing a test framework from the conformance module.\n *\n * @param label - Human-readable name used to identify the implementation under test.\n * @param makeStore - Factory returning a fresh, connected store with the `docs` collection.\n * @param dim - Vector dimensionality used by the suite (defaults to 3).\n * @param opts - Retry count and per-attempt timeout in milliseconds for eventually consistent stores.\n */\nexport const runVectorStoreConformance = async (\n  label: string,\n  makeStore: () => Promise<CallableVectorStore>,\n  dim = 3,\n  opts: { retry?: number; timeout?: number } = {}\n): Promise<void> => {\n  const p = (v: number[]): number[] => padVector(v, dim)\n  const pending: Array<() => Promise<void>> = []\n  const retry = opts.retry ?? 0\n  const timeout = opts.timeout ?? 5000\n  const runCase = async (test: () => Promise<void>): Promise<void> => {\n    let last: unknown\n    for (let attempt = 0; attempt <= retry; attempt++) {\n      let timedOut = false\n      const operation = Promise.resolve().then(test)\n      let timer: ReturnType<typeof setTimeout> | undefined\n      const deadline = new Promise<never>((_, reject) => {\n        timer = setTimeout(() => {\n          timedOut = true\n          reject(new Error(`conformance check timed out after ${timeout}ms`))\n        }, timeout)\n      })\n      try {\n        await Promise.race([operation, deadline])\n        return\n      } catch (error) {\n        // A timeout cannot cancel an arbitrary backend operation. Drain it before retrying so a\n        // late write/read from this attempt cannot race the fresh store made by the next attempt.\n        if (timedOut) {\n          last = error\n          break\n        }\n        last = error\n      } finally {\n        if (timer !== undefined) clearTimeout(timer)\n      }\n    }\n    throw last\n  }\n  const it = (_name: string, _io: unknown, test: () => Promise<void>) => {\n    pending.push(() => runCase(test))\n  }\n  const describe = (_name: string, suite: () => void) => suite()\n  const expect = expectValue\n  const io = undefined\n  describe('conformance: ' + label, () => {\n    it('upserts vectors and searches by nearVector with [0,1] score', io, async () => {\n      const vs = await makeStore()\n      await vs('docs').upsert([\n        { id: '1', vector: p([3, 1, 0]), metadata: { kind: 'animal' } },\n        { id: '2', vector: p([3, 0, 1]), metadata: { kind: 'animal' } },\n      ])\n      const res = await vs('docs')\n        .nearVector(p([3, 1, 0]))\n        .select('id', 'score')\n        .limit(2)\n      expect(res.length).toBe(2)\n      expect(res[0].id).toBeDefined()\n      expect(typeof res[0].score).toBe('number')\n      expect(res[0].score! >= 0 && res[0].score! <= 1).toBe(true)\n    })\n    it('encodes text on upsert+nearText when an encoder is configured', io, async () => {\n      const vs = await makeStore()\n      await vs('docs').upsert([{ id: 'c', document: 'cat', metadata: {} }])\n      const res = await vs('docs').nearText('cat').select('id').limit(1)\n      expect(res.length).toBe(1)\n      expect(res[0].id).toBe('c')\n    })\n    it('requires .select() on reads', io, async () => {\n      const vs = await makeStore()\n      await expect(\n        (async () => {\n          await vs('docs').nearVector(p([1, 1, 1]))\n        })()\n      ).rejects.toThrow()\n    })\n    it('filter-scan (no near) returns rows without score', io, async () => {\n      const vs = await makeStore()\n      await vs('docs').upsert([{ id: '1', vector: p([1, 0, 0]), metadata: { kind: 'x' } }])\n      const res = await vs('docs').where('kind', 'x').select('id', 'metadata').limit(10)\n      expect(res.length).toBe(1)\n      expect(res[0].score).toBeUndefined()\n    })\n    it('nested filter A AND (B OR C) selects the right subset', io, async () => {\n      const vs = await makeStore()\n      // Every record carries all three fields so the test probes nested AND/OR routing, not\n      // backend-specific missing-field semantics (e.g. Chroma's $or excludes records missing a\n      // referenced key, where the JS evaluator treats that clause as merely false).\n      await vs('docs').upsert([\n        { id: 'a', vector: p([1, 0, 0]), metadata: { kind: 'doc', year: 2024, pinned: false } }, // kept (year arm)\n        { id: 'b', vector: p([0, 1, 0]), metadata: { kind: 'doc', year: 2010, pinned: false } }, // dropped (neither arm)\n        { id: 'c', vector: p([0, 0, 1]), metadata: { kind: 'doc', year: 2010, pinned: true } }, // kept (pinned arm)\n        { id: 'd', vector: p([1, 1, 0]), metadata: { kind: 'other', year: 2024, pinned: true } }, // dropped (kind mismatch)\n      ])\n      // kind = 'doc' AND (year >= 2024 OR pinned = true)\n      const res = await vs('docs')\n        .where('kind', 'doc')\n        .andWhere((qb) => qb.where('year', '>=', 2024).orWhere('pinned', true))\n        .select('id')\n        .limit(10)\n      expect(res.map((r) => r.id).sort()).toEqual(['a', 'c'])\n    })\n    it('projection: vector excluded unless selected', io, async () => {\n      const vs = await makeStore()\n      await vs('docs').upsert([{ id: '1', vector: p([1, 0, 0]) }])\n      const noVec = await vs('docs')\n        .nearVector(p([1, 0, 0]))\n        .select('id')\n        .limit(1)\n      expect(noVec[0].vector).toBeUndefined()\n      const withVec = await vs('docs')\n        .nearVector(p([1, 0, 0]))\n        .select('id', 'vector')\n        .limit(1)\n      expect(Array.isArray(withVec[0].vector)).toBe(true)\n    })\n    it('deletes by id', io, async () => {\n      const vs = await makeStore()\n      await vs('docs').upsert([\n        { id: '1', vector: p([1, 0, 0]) },\n        { id: '2', vector: p([0, 1, 0]) },\n      ])\n      await vs('docs').whereIn('id', ['1']).delete()\n      const all = await vs('docs').select('id').limit(10)\n      expect(all.length).toBe(1)\n    })\n    it('throws transaction-unsupported when capabilities.transactions is false', io, async () => {\n      const vs = await makeStore()\n      if (!vs.capabilities.transactions) {\n        await expect(vs.transaction(async () => {})).rejects.toThrow()\n      }\n    })\n  })\n  for (const fn of pending) {\n    await fn()\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"conformance.mjs","names":[],"sources":["../../../src/batteries/vector/conformance/index.ts"],"sourcesContent":["/**\n * Shared conformance suite for vector-store adapters. Drive any adapter through\n * {@link runVectorStoreConformance} to verify it honours the same contract all shipped adapters do.\n * Public, deep-import-only (`@nhtio/adk/batteries/vector/conformance`). The suite has no test-runner\n * dependency: callers invoke it and await the returned promise from any test framework.\n *\n * @module @nhtio/adk/batteries/vector/conformance\n */\n\nimport type { CallableVectorStore } from '../contract'\n\n/** A deterministic stub encoder producing a 3-dim vector from simple text features. */\nexport const stubEncoder = async (\n  texts: string[],\n  _kind: 'query' | 'document'\n): Promise<number[][]> =>\n  texts.map((tx) => [tx.length, tx.includes('cat') ? 1 : 0, tx.includes('dog') ? 1 : 0])\n\n/**\n * A dimension-padding encoder factory: wraps {@link stubEncoder} and zero-extends to `dim`. Used by\n * backends that enforce a minimum dimension (e.g. Cloudflare Vectorize requires 32–1536).\n */\nexport const paddedStubEncoder =\n  (dim: number) =>\n  async (texts: string[], kind: 'query' | 'document'): Promise<number[][]> => {\n    const base = await stubEncoder(texts, kind)\n    return base.map((v) => padVector(v, dim))\n  }\n\n// Zero-extend (or truncate) a vector to exactly `dim` entries. dim===3 (the default) returns the\n// vector unchanged, so existing callers are byte-for-byte identical.\nconst padVector = (v: number[], dim: number): number[] => {\n  if (v.length === dim) return v\n  if (v.length > dim) return v.slice(0, dim)\n  return [...v, ...new Array(dim - v.length).fill(0)]\n}\n\n/**\n * Drive a vector-store adapter through the shared contract suite.\n *\n * @remarks\n * `makeStore` must return an already-connected store whose `'docs'` collection is created at the\n * matching dimension; it is re-invoked per test so retries are self-contained. `dim` defaults to 3\n * — pass a larger value for backends with a dimension floor (the harness pads every test vector to\n * `dim`). `opts.retry` / `opts.timeout` are forwarded to every `it()` (defaults: retry 0, 5s) and\n * exist for aggressively eventually-consistent managed backends whose read-after-write can flap for\n * seconds — a retried attempt re-runs `makeStore()` against an index that has had more time to\n * settle, without weakening any assertion.\n *\n * @param label - Human-readable label for the suite (the adapter name).\n * @param makeStore - Factory returning a fresh, connected store with the `'docs'` collection.\n * @param dim - Vector dimensionality the harness pads to (default 3).\n * @param opts - Per-`it` retry/timeout overrides.\n */\nconst assert: (condition: boolean, message: string) => asserts condition = (condition, message) => {\n  if (!condition) throw new Error(message)\n}\nconst equal = (actual: unknown, expected: unknown): boolean => {\n  if (actual === expected) return true\n  if (\n    actual === null ||\n    expected === null ||\n    typeof actual !== 'object' ||\n    typeof expected !== 'object'\n  )\n    return false\n  if (Array.isArray(actual) !== Array.isArray(expected)) return false\n  const actualRecord = actual as Record<string, unknown>\n  const expectedRecord = expected as Record<string, unknown>\n  const keysA = Object.keys(actualRecord)\n  const keysB = Object.keys(expectedRecord)\n  if (keysA.length !== keysB.length) return false\n  return keysA.every(\n    (key) => Object.hasOwn(expectedRecord, key) && equal(actualRecord[key], expectedRecord[key])\n  )\n}\nconst match = (actual: unknown, expected: unknown): boolean => {\n  if (expected === null || typeof expected !== 'object') return equal(actual, expected)\n  if (actual === null || typeof actual !== 'object') return false\n  return Object.entries(expected).every(([key, value]) =>\n    match((actual as Record<string, unknown>)[key], value)\n  )\n}\nconst expectValue = (actual: unknown) => ({\n  toBe: (expected: unknown) =>\n    assert(equal(actual, expected), `expected ${String(actual)} to be ${String(expected)}`),\n  toEqual: (expected: unknown) => assert(equal(actual, expected), 'values were not equal'),\n  toMatchObject: (expected: unknown) =>\n    assert(match(actual, expected), 'value did not match expected object'),\n  toBeDefined: () => assert(actual !== undefined, 'value was undefined'),\n  toBeUndefined: () => assert(actual === undefined, 'value was defined'),\n  toHaveLength: (length: number) =>\n    assert((actual as { length: number }).length === length, 'unexpected length'),\n  rejects: {\n    toThrow: async () => {\n      try {\n        await (actual as Promise<unknown>)\n      } catch {\n        return\n      }\n      throw new Error('expected promise to reject')\n    },\n  },\n})\n\n/**\n * Run the framework-free vector-store conformance suite against a consumer implementation.\n *\n * Each check creates a fresh store through `makeStore`; the returned promise rejects when any\n * contract assertion fails. Consumers can await this function from any test runner without\n * importing a test framework from the conformance module.\n *\n * @param label - Human-readable name used to identify the implementation under test.\n * @param makeStore - Factory returning a fresh, connected store with the `docs` collection.\n * @param dim - Vector dimensionality used by the suite (defaults to 3).\n * @param opts - Retry count and per-attempt timeout in milliseconds for eventually consistent stores.\n */\nexport const runVectorStoreConformance = async (\n  label: string,\n  makeStore: () => Promise<CallableVectorStore>,\n  dim = 3,\n  opts: { retry?: number; timeout?: number } = {}\n): Promise<void> => {\n  const p = (v: number[]): number[] => padVector(v, dim)\n  const pending: Array<() => Promise<void>> = []\n  const retry = opts.retry ?? 0\n  const timeout = opts.timeout ?? 5000\n  const runCase = async (test: () => Promise<void>): Promise<void> => {\n    let last: unknown\n    for (let attempt = 0; attempt <= retry; attempt++) {\n      let timedOut = false\n      const operation = Promise.resolve().then(test)\n      let timer: ReturnType<typeof setTimeout> | undefined\n      const deadline = new Promise<never>((_, reject) => {\n        timer = setTimeout(() => {\n          timedOut = true\n          reject(new Error(`conformance check timed out after ${timeout}ms`))\n        }, timeout)\n      })\n      try {\n        await Promise.race([operation, deadline])\n        return\n      } catch (error) {\n        // A timeout cannot cancel an arbitrary backend operation. Drain it before retrying so a\n        // late write/read from this attempt cannot race the fresh store made by the next attempt.\n        if (timedOut) {\n          last = error\n          break\n        }\n        last = error\n      } finally {\n        if (timer !== undefined) clearTimeout(timer)\n      }\n    }\n    throw last\n  }\n  const it = (_name: string, _io: unknown, test: () => Promise<void>) => {\n    pending.push(() => runCase(test))\n  }\n  const describe = (_name: string, suite: () => void) => suite()\n  const expect = expectValue\n  const io = undefined\n  describe('conformance: ' + label, () => {\n    it('upserts vectors and searches by nearVector with [0,1] score', io, async () => {\n      const vs = await makeStore()\n      await vs('docs').upsert([\n        { id: '1', vector: p([3, 1, 0]), metadata: { kind: 'animal' } },\n        { id: '2', vector: p([3, 0, 1]), metadata: { kind: 'animal' } },\n      ])\n      const res = await vs('docs')\n        .nearVector(p([3, 1, 0]))\n        .select('id', 'score')\n        .limit(2)\n      expect(res.length).toBe(2)\n      expect(res[0].id).toBeDefined()\n      expect(typeof res[0].score).toBe('number')\n      expect(res[0].score! >= 0 && res[0].score! <= 1).toBe(true)\n    })\n    it('encodes text on upsert+nearText when an encoder is configured', io, async () => {\n      const vs = await makeStore()\n      await vs('docs').upsert([{ id: 'c', document: 'cat', metadata: {} }])\n      const res = await vs('docs').nearText('cat').select('id').limit(1)\n      expect(res.length).toBe(1)\n      expect(res[0].id).toBe('c')\n    })\n    it('requires .select() on reads', io, async () => {\n      const vs = await makeStore()\n      await expect(\n        (async () => {\n          await vs('docs').nearVector(p([1, 1, 1]))\n        })()\n      ).rejects.toThrow()\n    })\n    it('filter-scan (no near) returns rows without score', io, async () => {\n      const vs = await makeStore()\n      await vs('docs').upsert([{ id: '1', vector: p([1, 0, 0]), metadata: { kind: 'x' } }])\n      const res = await vs('docs').where('kind', 'x').select('id', 'metadata').limit(10)\n      expect(res.length).toBe(1)\n      expect(res[0].score).toBeUndefined()\n    })\n    it('nested filter A AND (B OR C) selects the right subset', io, async () => {\n      const vs = await makeStore()\n      // Every record carries all three fields so the test probes nested AND/OR routing, not\n      // backend-specific missing-field semantics (e.g. Chroma's $or excludes records missing a\n      // referenced key, where the JS evaluator treats that clause as merely false).\n      await vs('docs').upsert([\n        { id: 'a', vector: p([1, 0, 0]), metadata: { kind: 'doc', year: 2024, pinned: false } }, // kept (year arm)\n        { id: 'b', vector: p([0, 1, 0]), metadata: { kind: 'doc', year: 2010, pinned: false } }, // dropped (neither arm)\n        { id: 'c', vector: p([0, 0, 1]), metadata: { kind: 'doc', year: 2010, pinned: true } }, // kept (pinned arm)\n        { id: 'd', vector: p([1, 1, 0]), metadata: { kind: 'other', year: 2024, pinned: true } }, // dropped (kind mismatch)\n      ])\n      // kind = 'doc' AND (year >= 2024 OR pinned = true)\n      const res = await vs('docs')\n        .where('kind', 'doc')\n        .andWhere((qb) => qb.where('year', '>=', 2024).orWhere('pinned', true))\n        .select('id')\n        .limit(10)\n      expect(res.map((r) => r.id).sort()).toEqual(['a', 'c'])\n    })\n    it('projection: vector excluded unless selected', io, async () => {\n      const vs = await makeStore()\n      await vs('docs').upsert([{ id: '1', vector: p([1, 0, 0]) }])\n      const noVec = await vs('docs')\n        .nearVector(p([1, 0, 0]))\n        .select('id')\n        .limit(1)\n      expect(noVec[0].vector).toBeUndefined()\n      const withVec = await vs('docs')\n        .nearVector(p([1, 0, 0]))\n        .select('id', 'vector')\n        .limit(1)\n      expect(Array.isArray(withVec[0].vector)).toBe(true)\n    })\n    it('deletes by id', io, async () => {\n      const vs = await makeStore()\n      await vs('docs').upsert([\n        { id: '1', vector: p([1, 0, 0]) },\n        { id: '2', vector: p([0, 1, 0]) },\n      ])\n      await vs('docs').whereIn('id', ['1']).delete()\n      const all = await vs('docs').select('id').limit(10)\n      expect(all.length).toBe(1)\n    })\n    it('throws transaction-unsupported when capabilities.transactions is false', io, async () => {\n      const vs = await makeStore()\n      if (!vs.capabilities.transactions) {\n        await expect(vs.transaction(async () => {})).rejects.toThrow()\n      }\n    })\n    it('renameCollection: honours capabilities.rename', io, async () => {\n      const vs = await makeStore()\n      if (vs.capabilities.rename) {\n        await vs.schema.dropCollectionIfExists('docs_renamed')\n        let bodyFailed = false\n        let bodyError: unknown\n        try {\n          await vs('docs').upsert([\n            { id: '1', vector: p([3, 1, 0]) },\n            { id: '2', vector: p([3, 0, 1]) },\n          ])\n          await vs.schema.renameCollection('docs', 'docs_renamed')\n          expect(await vs.schema.hasCollection('docs')).toBe(false)\n          expect(await vs.schema.hasCollection('docs_renamed')).toBe(true)\n          const res = await vs('docs_renamed')\n            .nearVector(p([3, 1, 0]))\n            .select('id', 'score')\n            .limit(2)\n          expect(res.length).toBe(2)\n          expect(res[0].id).toBe('1')\n          expect(typeof res[0].score).toBe('number')\n          expect(res[0].score! >= 0 && res[0].score! <= 1).toBe(true)\n          await vs('docs_renamed').upsert([{ id: '3', vector: p([1, 1, 1]) }])\n          const all = await vs('docs_renamed').select('id').limit(10)\n          expect(all.map((r) => r.id).sort()).toEqual(['1', '2', '3'])\n        } catch (e) {\n          bodyFailed = true\n          bodyError = e\n        }\n        // A cleanup failure here must never mask a real failure from the try block above: only\n        // swallow it when the body already failed (there's nothing left to mask); otherwise let it\n        // propagate, since a passing body followed by a broken cleanup is itself a real failure.\n        try {\n          await vs.schema.dropCollectionIfExists('docs_renamed')\n        } catch (cleanupErr) {\n          if (!bodyFailed) throw cleanupErr\n        }\n        if (bodyFailed) throw bodyError\n      } else {\n        await expect(vs.schema.renameCollection('docs', 'docs_renamed')).rejects.toThrow()\n      }\n    })\n  })\n  for (const fn of pending) {\n    await fn()\n  }\n}\n"],"mappings":"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"}

package/batteries/vector/lancedb.cjs

@@ -39,7 +39,7 @@ var LanceDBVectorStore = class extends require_batteries_vector_contract.BaseVec
 	capabilities = {
 		transactions: false,
 		namedVectors: false,
-		rename: true,
+		rename: false,
 		rawSql: false,
 		builtInEncoding: false,
 		consistency: {

package/batteries/vector/lancedb.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"lancedb.cjs","names":["#opts","#db","#ensure","#dims","#parseMeta","#project"],"sources":["../../../src/batteries/vector/lancedb/index.ts"],"sourcesContent":["/**\n * @module @nhtio/adk/batteries/vector/lancedb\n *\n * Embedded LanceDB adapter (no server — file-based, like sqlite_vec/duckdb). Each collection\n * is a Lance table with an explicit Arrow schema (`id` Utf8, `vec` FixedSizeList<Float32>,\n * `document` Utf8, `metadata` Utf8-JSON). KNN uses `table.search(vector).distanceType(...)`;\n * metadata is filtered with the neutral filter tree's JS reference evaluator for exact\n * cross-adapter parity. Upsert is a merge-insert on `id`.\n *\n * Drivers: `@lancedb/lancedb` + `apache-arrow` (prebuilt binary; no native compile).\n */\n\nimport { evaluateFilter } from '../filters'\nimport { normalizeScore } from '../helpers'\nimport { BaseVectorStore } from '../contract'\nimport { validateRecords } from '../validation'\nimport { isInstanceOf } from '@nhtio/adk/guards'\nimport {\n  E_VECTOR_STORE_DRIVER_UNAVAILABLE,\n  E_VECTOR_STORE_CONNECTION_FAILED,\n  E_VECTOR_STORE_COLLECTION_FAILED,\n  E_VECTOR_STORE_UPSERT_FAILED,\n  E_VECTOR_STORE_SEARCH_FAILED,\n  E_VECTOR_STORE_DELETE_FAILED,\n  E_VECTOR_STORE_DIMENSION_MISMATCH,\n  E_VECTOR_STORE_UNSUPPORTED_OPERATION,\n} from '../exceptions'\nimport type { SearchPlan, UpsertPlan, DeletePlan, CollectionSpec } from '../plan'\nimport type {\n  VectorMatch,\n  VectorStoreCapabilities,\n  BaseVectorStoreOptions,\n  VectorMetadata,\n  DistanceMetric,\n} from '../types'\n\nexport interface LanceDBVectorStoreOptions extends BaseVectorStoreOptions {\n  /** Connection and authentication parameters for the backend. */\n  connection: { uri: string }\n}\n\nconst getLanceDB = async () => {\n  try {\n    return await import('@lancedb/lancedb')\n  } catch {\n    throw new E_VECTOR_STORE_DRIVER_UNAVAILABLE(['@lancedb/lancedb'])\n  }\n}\n\nconst getArrow = async () => {\n  try {\n    return await import('apache-arrow')\n  } catch {\n    throw new E_VECTOR_STORE_DRIVER_UNAVAILABLE(['apache-arrow'])\n  }\n}\n\nconst lanceMetric = (metric: DistanceMetric): string =>\n  metric === 'euclidean' ? 'l2' : metric === 'dot' ? 'dot' : 'cosine'\n\n// LanceDB SQL string literal (single-quoted, escape embedded quotes).\nconst lit = (value: string): string => `'${value.replace(/'/g, \"''\")}'`\n\nexport class LanceDBVectorStore extends BaseVectorStore {\n  readonly capabilities: VectorStoreCapabilities = {\n    transactions: false,\n    namedVectors: false,\n    rename: true,\n    rawSql: false,\n    builtInEncoding: false,\n    // Embedded and synchronous: a write is visible on resolve. The option is a no-op.\n    consistency: { configurable: false, default: 'strong', modes: ['strong'] },\n  }\n\n  #db: any | null = null\n  #dims: Map<string, number> = new Map()\n\n  get #opts(): LanceDBVectorStoreOptions {\n    return this.options as LanceDBVectorStoreOptions\n  }\n\n  /** Static availability probe: whether this adapter's runtime driver can load in the current environment. */\n  static isAvailable(): boolean {\n    return typeof process !== 'undefined'\n  }\n  isAvailable(): boolean {\n    return typeof process !== 'undefined'\n  }\n\n  async connect(): Promise<void> {\n    if (this.#db) return\n    const lancedb = await getLanceDB()\n    const uri = this.#opts.connection?.uri\n    if (!uri) {\n      throw new E_VECTOR_STORE_CONNECTION_FAILED([\n        'LanceDB requires connection.uri (a directory path)',\n      ])\n    }\n    try {\n      this.#db = await lancedb.connect(uri)\n    } catch (err) {\n      throw new E_VECTOR_STORE_CONNECTION_FAILED([String(err)])\n    }\n  }\n\n  async close(): Promise<void> {\n    this.#db = null\n  }\n\n  async #ensure(): Promise<any> {\n    if (!this.#db) await this.connect()\n    return this.#db!\n  }\n\n  async createCollection(spec: CollectionSpec, ifNotExists: boolean): Promise<void> {\n    const db = await this.#ensure()\n    this.#dims.set(spec.collection, spec.vector.dimensions)\n    if (ifNotExists && (await this.hasCollection(spec.collection))) return\n    const arrow = await getArrow()\n    const schema = new arrow.Schema([\n      new arrow.Field('id', new arrow.Utf8(), false),\n      new arrow.Field(\n        'vec',\n        new arrow.FixedSizeList(\n          spec.vector.dimensions,\n          new arrow.Field('item', new arrow.Float32(), true)\n        ),\n        false\n      ),\n      new arrow.Field('document', new arrow.Utf8(), true),\n      new arrow.Field('metadata', new arrow.Utf8(), true),\n    ])\n    try {\n      await db.createEmptyTable(spec.collection, schema, { mode: 'overwrite' })\n    } catch (err) {\n      throw new E_VECTOR_STORE_COLLECTION_FAILED(['createCollection', String(err)])\n    }\n  }\n\n  async dropCollection(collection: string, ifExists: boolean): Promise<void> {\n    const db = await this.#ensure()\n    if (ifExists && !(await this.hasCollection(collection))) return\n    try {\n      await db.dropTable(collection)\n      this.#dims.delete(collection)\n    } catch (err) {\n      const msg = String(err)\n      if (ifExists && msg.includes('not found')) return\n      throw new E_VECTOR_STORE_COLLECTION_FAILED(['dropCollection', msg])\n    }\n  }\n\n  async hasCollection(collection: string): Promise<boolean> {\n    const db = await this.#ensure()\n    try {\n      const names = await db.tableNames()\n      return names.includes(collection)\n    } catch {\n      return false\n    }\n  }\n\n  async renameCollection(_from: string, _to: string): Promise<void> {\n    throw new E_VECTOR_STORE_UNSUPPORTED_OPERATION(['renameCollection', 'lancedb'])\n  }\n\n  async executeUpsert(plan: UpsertPlan): Promise<void> {\n    if (plan.records.length === 0) return\n    validateRecords(plan.records)\n    const db = await this.#ensure()\n    const expected = this.#opts.dimensions ?? this.#dims.get(plan.collection)\n    try {\n      const rows: any[] = []\n      for (const r of plan.records) {\n        let vector = r.vector\n        if (!vector && r.document) {\n          const [v] = await this.encode([r.document], 'document')\n          vector = v\n        }\n        if (!vector) {\n          throw new E_VECTOR_STORE_UPSERT_FAILED(['Record missing vector and document'])\n        }\n        if (expected !== undefined && vector.length !== expected) {\n          throw new E_VECTOR_STORE_DIMENSION_MISMATCH([expected, vector.length])\n        }\n        rows.push({\n          id: r.id,\n          vec: vector,\n          document: r.document ?? '',\n          metadata: r.metadata ? JSON.stringify(r.metadata) : '{}',\n        })\n      }\n      const tbl = await db.openTable(plan.collection)\n      // Merge-insert on id = upsert (update matched, insert unmatched).\n      await tbl.mergeInsert('id').whenMatchedUpdateAll().whenNotMatchedInsertAll().execute(rows)\n    } catch (err) {\n      if (\n        isInstanceOf(err, 'E_VECTOR_STORE_DIMENSION_MISMATCH', E_VECTOR_STORE_DIMENSION_MISMATCH) ||\n        isInstanceOf(err, 'E_VECTOR_STORE_UPSERT_FAILED', E_VECTOR_STORE_UPSERT_FAILED)\n      ) {\n        throw err\n      }\n      throw new E_VECTOR_STORE_UPSERT_FAILED([String(err)])\n    }\n  }\n\n  async executeSearch(plan: SearchPlan): Promise<VectorMatch[]> {\n    const db = await this.#ensure()\n    const metric = this.#opts.metric ?? 'cosine'\n    let queryVector: number[] | undefined\n    let tbl: any\n    try {\n      tbl = await db.openTable(plan.collection)\n    } catch (err) {\n      throw new E_VECTOR_STORE_SEARCH_FAILED([String(err)])\n    }\n\n    if (plan.near) {\n      if ('vector' in plan.near) {\n        queryVector = plan.near.vector\n      } else if ('serverText' in plan.near) {\n        const [v] = await this.encode([plan.near.serverText], 'query')\n        queryVector = v\n      } else if ('id' in plan.near) {\n        const rows = await tbl\n          .query()\n          .where(`id = ${lit(plan.near.id)}`)\n          .limit(1)\n          .toArray()\n        if (rows.length === 0) {\n          throw new E_VECTOR_STORE_SEARCH_FAILED(['Referenced id not found: ' + plan.near.id])\n        }\n        queryVector = Array.from(rows[0].vec as ArrayLike<number>)\n      }\n    }\n\n    const offset = plan.offset ?? 0\n    try {\n      if (queryVector) {\n        // Over-fetch then JS-filter for exact cross-adapter filter semantics.\n        const k = plan.filter ? 1000 : plan.topK + offset\n        const rows = await tbl\n          .search(queryVector)\n          .distanceType(lanceMetric(metric))\n          .limit(k)\n          .toArray()\n        const filtered = plan.filter\n          ? rows.filter((row: any) => evaluateFilter(plan.filter!, this.#parseMeta(row.metadata)))\n          : rows\n        return filtered\n          .slice(offset, offset + plan.topK)\n          .map((row: any) => this.#project(row, plan, metric, true))\n      } else {\n        const rows = await tbl\n          .query()\n          .limit(plan.filter ? 100000 : plan.topK + offset)\n          .toArray()\n        const filtered = plan.filter\n          ? rows.filter((row: any) => evaluateFilter(plan.filter!, this.#parseMeta(row.metadata)))\n          : rows\n        return filtered\n          .slice(offset, offset + plan.topK)\n          .map((row: any) => this.#project(row, plan, metric, false))\n      }\n    } catch (err) {\n      throw new E_VECTOR_STORE_SEARCH_FAILED([String(err)])\n    }\n  }\n\n  #parseMeta(val: unknown): VectorMetadata {\n    if (typeof val === 'string') {\n      try {\n        return JSON.parse(val) as VectorMetadata\n      } catch {\n        return {}\n      }\n    }\n    if (val && typeof val === 'object') return val as VectorMetadata\n    return {}\n  }\n\n  #project(row: any, plan: SearchPlan, metric: string, isKnn: boolean): VectorMatch {\n    const proj = plan.projection\n    const out: VectorMatch = {}\n    if (proj.id) out.id = row.id as string\n    if (proj.vector && row.vec) out.vector = Array.from(row.vec as ArrayLike<number>)\n    if (proj.document) out.document = (row.document ?? undefined) as string | undefined\n    if (proj.metadata) out.metadata = this.#parseMeta(row.metadata)\n    if (isKnn && row._distance !== undefined && row._distance !== null) {\n      out.score = normalizeScore(Number(row._distance), metric as DistanceMetric, 'distance')\n    }\n    return out\n  }\n\n  async executeDelete(plan: DeletePlan): Promise<void> {\n    const db = await this.#ensure()\n    try {\n      const tbl = await db.openTable(plan.collection)\n      if (plan.ids && plan.ids.length > 0) {\n        const list = plan.ids.map((id) => lit(id)).join(', ')\n        await tbl.delete(`id IN (${list})`)\n      } else if (plan.filter) {\n        const rows = await tbl.query().limit(100000).toArray()\n        const targets: string[] = rows\n          .filter((row: any) => evaluateFilter(plan.filter!, this.#parseMeta(row.metadata)))\n          .map((row: any) => row.id as string)\n        if (targets.length > 0) {\n          const list = targets.map((id) => lit(id)).join(', ')\n          await tbl.delete(`id IN (${list})`)\n        }\n      } else {\n        await tbl.delete('true')\n      }\n    } catch (err) {\n      throw new E_VECTOR_STORE_DELETE_FAILED([String(err)])\n    }\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"lancedb.cjs","names":["#opts","#db","#ensure","#dims","#parseMeta","#project"],"sources":["../../../src/batteries/vector/lancedb/index.ts"],"sourcesContent":["/**\n * @module @nhtio/adk/batteries/vector/lancedb\n *\n * Embedded LanceDB adapter (no server — file-based, like sqlite_vec/duckdb). Each collection\n * is a Lance table with an explicit Arrow schema (`id` Utf8, `vec` FixedSizeList<Float32>,\n * `document` Utf8, `metadata` Utf8-JSON). KNN uses `table.search(vector).distanceType(...)`;\n * metadata is filtered with the neutral filter tree's JS reference evaluator for exact\n * cross-adapter parity. Upsert is a merge-insert on `id`.\n *\n * Drivers: `@lancedb/lancedb` + `apache-arrow` (prebuilt binary; no native compile).\n */\n\nimport { evaluateFilter } from '../filters'\nimport { normalizeScore } from '../helpers'\nimport { BaseVectorStore } from '../contract'\nimport { validateRecords } from '../validation'\nimport { isInstanceOf } from '@nhtio/adk/guards'\nimport {\n  E_VECTOR_STORE_DRIVER_UNAVAILABLE,\n  E_VECTOR_STORE_CONNECTION_FAILED,\n  E_VECTOR_STORE_COLLECTION_FAILED,\n  E_VECTOR_STORE_UPSERT_FAILED,\n  E_VECTOR_STORE_SEARCH_FAILED,\n  E_VECTOR_STORE_DELETE_FAILED,\n  E_VECTOR_STORE_DIMENSION_MISMATCH,\n  E_VECTOR_STORE_UNSUPPORTED_OPERATION,\n} from '../exceptions'\nimport type { SearchPlan, UpsertPlan, DeletePlan, CollectionSpec } from '../plan'\nimport type {\n  VectorMatch,\n  VectorStoreCapabilities,\n  BaseVectorStoreOptions,\n  VectorMetadata,\n  DistanceMetric,\n} from '../types'\n\nexport interface LanceDBVectorStoreOptions extends BaseVectorStoreOptions {\n  /** Connection and authentication parameters for the backend. */\n  connection: { uri: string }\n}\n\nconst getLanceDB = async () => {\n  try {\n    return await import('@lancedb/lancedb')\n  } catch {\n    throw new E_VECTOR_STORE_DRIVER_UNAVAILABLE(['@lancedb/lancedb'])\n  }\n}\n\nconst getArrow = async () => {\n  try {\n    return await import('apache-arrow')\n  } catch {\n    throw new E_VECTOR_STORE_DRIVER_UNAVAILABLE(['apache-arrow'])\n  }\n}\n\nconst lanceMetric = (metric: DistanceMetric): string =>\n  metric === 'euclidean' ? 'l2' : metric === 'dot' ? 'dot' : 'cosine'\n\n// LanceDB SQL string literal (single-quoted, escape embedded quotes).\nconst lit = (value: string): string => `'${value.replace(/'/g, \"''\")}'`\n\nexport class LanceDBVectorStore extends BaseVectorStore {\n  readonly capabilities: VectorStoreCapabilities = {\n    transactions: false,\n    namedVectors: false,\n    // Probed against @lancedb/lancedb 0.30.0 (local directory database): connection.renameTable\n    // rejects with \"LanceDBError: not supported: rename_table is not supported in LanceDB OSS\".\n    rename: false,\n    rawSql: false,\n    builtInEncoding: false,\n    // Embedded and synchronous: a write is visible on resolve. The option is a no-op.\n    consistency: { configurable: false, default: 'strong', modes: ['strong'] },\n  }\n\n  #db: any | null = null\n  #dims: Map<string, number> = new Map()\n\n  get #opts(): LanceDBVectorStoreOptions {\n    return this.options as LanceDBVectorStoreOptions\n  }\n\n  /** Static availability probe: whether this adapter's runtime driver can load in the current environment. */\n  static isAvailable(): boolean {\n    return typeof process !== 'undefined'\n  }\n  isAvailable(): boolean {\n    return typeof process !== 'undefined'\n  }\n\n  async connect(): Promise<void> {\n    if (this.#db) return\n    const lancedb = await getLanceDB()\n    const uri = this.#opts.connection?.uri\n    if (!uri) {\n      throw new E_VECTOR_STORE_CONNECTION_FAILED([\n        'LanceDB requires connection.uri (a directory path)',\n      ])\n    }\n    try {\n      this.#db = await lancedb.connect(uri)\n    } catch (err) {\n      throw new E_VECTOR_STORE_CONNECTION_FAILED([String(err)])\n    }\n  }\n\n  async close(): Promise<void> {\n    this.#db = null\n  }\n\n  async #ensure(): Promise<any> {\n    if (!this.#db) await this.connect()\n    return this.#db!\n  }\n\n  async createCollection(spec: CollectionSpec, ifNotExists: boolean): Promise<void> {\n    const db = await this.#ensure()\n    this.#dims.set(spec.collection, spec.vector.dimensions)\n    if (ifNotExists && (await this.hasCollection(spec.collection))) return\n    const arrow = await getArrow()\n    const schema = new arrow.Schema([\n      new arrow.Field('id', new arrow.Utf8(), false),\n      new arrow.Field(\n        'vec',\n        new arrow.FixedSizeList(\n          spec.vector.dimensions,\n          new arrow.Field('item', new arrow.Float32(), true)\n        ),\n        false\n      ),\n      new arrow.Field('document', new arrow.Utf8(), true),\n      new arrow.Field('metadata', new arrow.Utf8(), true),\n    ])\n    try {\n      await db.createEmptyTable(spec.collection, schema, { mode: 'overwrite' })\n    } catch (err) {\n      throw new E_VECTOR_STORE_COLLECTION_FAILED(['createCollection', String(err)])\n    }\n  }\n\n  async dropCollection(collection: string, ifExists: boolean): Promise<void> {\n    const db = await this.#ensure()\n    if (ifExists && !(await this.hasCollection(collection))) return\n    try {\n      await db.dropTable(collection)\n      this.#dims.delete(collection)\n    } catch (err) {\n      const msg = String(err)\n      if (ifExists && msg.includes('not found')) return\n      throw new E_VECTOR_STORE_COLLECTION_FAILED(['dropCollection', msg])\n    }\n  }\n\n  async hasCollection(collection: string): Promise<boolean> {\n    const db = await this.#ensure()\n    try {\n      const names = await db.tableNames()\n      return names.includes(collection)\n    } catch {\n      return false\n    }\n  }\n\n  async renameCollection(_from: string, _to: string): Promise<void> {\n    throw new E_VECTOR_STORE_UNSUPPORTED_OPERATION(['renameCollection', 'lancedb'])\n  }\n\n  async executeUpsert(plan: UpsertPlan): Promise<void> {\n    if (plan.records.length === 0) return\n    validateRecords(plan.records)\n    const db = await this.#ensure()\n    const expected = this.#opts.dimensions ?? this.#dims.get(plan.collection)\n    try {\n      const rows: any[] = []\n      for (const r of plan.records) {\n        let vector = r.vector\n        if (!vector && r.document) {\n          const [v] = await this.encode([r.document], 'document')\n          vector = v\n        }\n        if (!vector) {\n          throw new E_VECTOR_STORE_UPSERT_FAILED(['Record missing vector and document'])\n        }\n        if (expected !== undefined && vector.length !== expected) {\n          throw new E_VECTOR_STORE_DIMENSION_MISMATCH([expected, vector.length])\n        }\n        rows.push({\n          id: r.id,\n          vec: vector,\n          document: r.document ?? '',\n          metadata: r.metadata ? JSON.stringify(r.metadata) : '{}',\n        })\n      }\n      const tbl = await db.openTable(plan.collection)\n      // Merge-insert on id = upsert (update matched, insert unmatched).\n      await tbl.mergeInsert('id').whenMatchedUpdateAll().whenNotMatchedInsertAll().execute(rows)\n    } catch (err) {\n      if (\n        isInstanceOf(err, 'E_VECTOR_STORE_DIMENSION_MISMATCH', E_VECTOR_STORE_DIMENSION_MISMATCH) ||\n        isInstanceOf(err, 'E_VECTOR_STORE_UPSERT_FAILED', E_VECTOR_STORE_UPSERT_FAILED)\n      ) {\n        throw err\n      }\n      throw new E_VECTOR_STORE_UPSERT_FAILED([String(err)])\n    }\n  }\n\n  async executeSearch(plan: SearchPlan): Promise<VectorMatch[]> {\n    const db = await this.#ensure()\n    const metric = this.#opts.metric ?? 'cosine'\n    let queryVector: number[] | undefined\n    let tbl: any\n    try {\n      tbl = await db.openTable(plan.collection)\n    } catch (err) {\n      throw new E_VECTOR_STORE_SEARCH_FAILED([String(err)])\n    }\n\n    if (plan.near) {\n      if ('vector' in plan.near) {\n        queryVector = plan.near.vector\n      } else if ('serverText' in plan.near) {\n        const [v] = await this.encode([plan.near.serverText], 'query')\n        queryVector = v\n      } else if ('id' in plan.near) {\n        const rows = await tbl\n          .query()\n          .where(`id = ${lit(plan.near.id)}`)\n          .limit(1)\n          .toArray()\n        if (rows.length === 0) {\n          throw new E_VECTOR_STORE_SEARCH_FAILED(['Referenced id not found: ' + plan.near.id])\n        }\n        queryVector = Array.from(rows[0].vec as ArrayLike<number>)\n      }\n    }\n\n    const offset = plan.offset ?? 0\n    try {\n      if (queryVector) {\n        // Over-fetch then JS-filter for exact cross-adapter filter semantics.\n        const k = plan.filter ? 1000 : plan.topK + offset\n        const rows = await tbl\n          .search(queryVector)\n          .distanceType(lanceMetric(metric))\n          .limit(k)\n          .toArray()\n        const filtered = plan.filter\n          ? rows.filter((row: any) => evaluateFilter(plan.filter!, this.#parseMeta(row.metadata)))\n          : rows\n        return filtered\n          .slice(offset, offset + plan.topK)\n          .map((row: any) => this.#project(row, plan, metric, true))\n      } else {\n        const rows = await tbl\n          .query()\n          .limit(plan.filter ? 100000 : plan.topK + offset)\n          .toArray()\n        const filtered = plan.filter\n          ? rows.filter((row: any) => evaluateFilter(plan.filter!, this.#parseMeta(row.metadata)))\n          : rows\n        return filtered\n          .slice(offset, offset + plan.topK)\n          .map((row: any) => this.#project(row, plan, metric, false))\n      }\n    } catch (err) {\n      throw new E_VECTOR_STORE_SEARCH_FAILED([String(err)])\n    }\n  }\n\n  #parseMeta(val: unknown): VectorMetadata {\n    if (typeof val === 'string') {\n      try {\n        return JSON.parse(val) as VectorMetadata\n      } catch {\n        return {}\n      }\n    }\n    if (val && typeof val === 'object') return val as VectorMetadata\n    return {}\n  }\n\n  #project(row: any, plan: SearchPlan, metric: string, isKnn: boolean): VectorMatch {\n    const proj = plan.projection\n    const out: VectorMatch = {}\n    if (proj.id) out.id = row.id as string\n    if (proj.vector && row.vec) out.vector = Array.from(row.vec as ArrayLike<number>)\n    if (proj.document) out.document = (row.document ?? undefined) as string | undefined\n    if (proj.metadata) out.metadata = this.#parseMeta(row.metadata)\n    if (isKnn && row._distance !== undefined && row._distance !== null) {\n      out.score = normalizeScore(Number(row._distance), metric as DistanceMetric, 'distance')\n    }\n    return out\n  }\n\n  async executeDelete(plan: DeletePlan): Promise<void> {\n    const db = await this.#ensure()\n    try {\n      const tbl = await db.openTable(plan.collection)\n      if (plan.ids && plan.ids.length > 0) {\n        const list = plan.ids.map((id) => lit(id)).join(', ')\n        await tbl.delete(`id IN (${list})`)\n      } else if (plan.filter) {\n        const rows = await tbl.query().limit(100000).toArray()\n        const targets: string[] = rows\n          .filter((row: any) => evaluateFilter(plan.filter!, this.#parseMeta(row.metadata)))\n          .map((row: any) => row.id as string)\n        if (targets.length > 0) {\n          const list = targets.map((id) => lit(id)).join(', ')\n          await tbl.delete(`id IN (${list})`)\n        }\n      } else {\n        await tbl.delete('true')\n      }\n    } catch (err) {\n      throw new E_VECTOR_STORE_DELETE_FAILED([String(err)])\n    }\n  }\n}\n"],"mappings":"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"}

package/batteries/vector/lancedb.mjs

@@ -37,7 +37,7 @@ var LanceDBVectorStore = class extends BaseVectorStore {
 	capabilities = {
 		transactions: false,
 		namedVectors: false,
-		rename: true,
+		rename: false,
 		rawSql: false,
 		builtInEncoding: false,
 		consistency: {

package/batteries/vector/lancedb.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"lancedb.mjs","names":["#opts","#db","#ensure","#dims","#parseMeta","#project"],"sources":["../../../src/batteries/vector/lancedb/index.ts"],"sourcesContent":["/**\n * @module @nhtio/adk/batteries/vector/lancedb\n *\n * Embedded LanceDB adapter (no server — file-based, like sqlite_vec/duckdb). Each collection\n * is a Lance table with an explicit Arrow schema (`id` Utf8, `vec` FixedSizeList<Float32>,\n * `document` Utf8, `metadata` Utf8-JSON). KNN uses `table.search(vector).distanceType(...)`;\n * metadata is filtered with the neutral filter tree's JS reference evaluator for exact\n * cross-adapter parity. Upsert is a merge-insert on `id`.\n *\n * Drivers: `@lancedb/lancedb` + `apache-arrow` (prebuilt binary; no native compile).\n */\n\nimport { evaluateFilter } from '../filters'\nimport { normalizeScore } from '../helpers'\nimport { BaseVectorStore } from '../contract'\nimport { validateRecords } from '../validation'\nimport { isInstanceOf } from '@nhtio/adk/guards'\nimport {\n  E_VECTOR_STORE_DRIVER_UNAVAILABLE,\n  E_VECTOR_STORE_CONNECTION_FAILED,\n  E_VECTOR_STORE_COLLECTION_FAILED,\n  E_VECTOR_STORE_UPSERT_FAILED,\n  E_VECTOR_STORE_SEARCH_FAILED,\n  E_VECTOR_STORE_DELETE_FAILED,\n  E_VECTOR_STORE_DIMENSION_MISMATCH,\n  E_VECTOR_STORE_UNSUPPORTED_OPERATION,\n} from '../exceptions'\nimport type { SearchPlan, UpsertPlan, DeletePlan, CollectionSpec } from '../plan'\nimport type {\n  VectorMatch,\n  VectorStoreCapabilities,\n  BaseVectorStoreOptions,\n  VectorMetadata,\n  DistanceMetric,\n} from '../types'\n\nexport interface LanceDBVectorStoreOptions extends BaseVectorStoreOptions {\n  /** Connection and authentication parameters for the backend. */\n  connection: { uri: string }\n}\n\nconst getLanceDB = async () => {\n  try {\n    return await import('@lancedb/lancedb')\n  } catch {\n    throw new E_VECTOR_STORE_DRIVER_UNAVAILABLE(['@lancedb/lancedb'])\n  }\n}\n\nconst getArrow = async () => {\n  try {\n    return await import('apache-arrow')\n  } catch {\n    throw new E_VECTOR_STORE_DRIVER_UNAVAILABLE(['apache-arrow'])\n  }\n}\n\nconst lanceMetric = (metric: DistanceMetric): string =>\n  metric === 'euclidean' ? 'l2' : metric === 'dot' ? 'dot' : 'cosine'\n\n// LanceDB SQL string literal (single-quoted, escape embedded quotes).\nconst lit = (value: string): string => `'${value.replace(/'/g, \"''\")}'`\n\nexport class LanceDBVectorStore extends BaseVectorStore {\n  readonly capabilities: VectorStoreCapabilities = {\n    transactions: false,\n    namedVectors: false,\n    rename: true,\n    rawSql: false,\n    builtInEncoding: false,\n    // Embedded and synchronous: a write is visible on resolve. The option is a no-op.\n    consistency: { configurable: false, default: 'strong', modes: ['strong'] },\n  }\n\n  #db: any | null = null\n  #dims: Map<string, number> = new Map()\n\n  get #opts(): LanceDBVectorStoreOptions {\n    return this.options as LanceDBVectorStoreOptions\n  }\n\n  /** Static availability probe: whether this adapter's runtime driver can load in the current environment. */\n  static isAvailable(): boolean {\n    return typeof process !== 'undefined'\n  }\n  isAvailable(): boolean {\n    return typeof process !== 'undefined'\n  }\n\n  async connect(): Promise<void> {\n    if (this.#db) return\n    const lancedb = await getLanceDB()\n    const uri = this.#opts.connection?.uri\n    if (!uri) {\n      throw new E_VECTOR_STORE_CONNECTION_FAILED([\n        'LanceDB requires connection.uri (a directory path)',\n      ])\n    }\n    try {\n      this.#db = await lancedb.connect(uri)\n    } catch (err) {\n      throw new E_VECTOR_STORE_CONNECTION_FAILED([String(err)])\n    }\n  }\n\n  async close(): Promise<void> {\n    this.#db = null\n  }\n\n  async #ensure(): Promise<any> {\n    if (!this.#db) await this.connect()\n    return this.#db!\n  }\n\n  async createCollection(spec: CollectionSpec, ifNotExists: boolean): Promise<void> {\n    const db = await this.#ensure()\n    this.#dims.set(spec.collection, spec.vector.dimensions)\n    if (ifNotExists && (await this.hasCollection(spec.collection))) return\n    const arrow = await getArrow()\n    const schema = new arrow.Schema([\n      new arrow.Field('id', new arrow.Utf8(), false),\n      new arrow.Field(\n        'vec',\n        new arrow.FixedSizeList(\n          spec.vector.dimensions,\n          new arrow.Field('item', new arrow.Float32(), true)\n        ),\n        false\n      ),\n      new arrow.Field('document', new arrow.Utf8(), true),\n      new arrow.Field('metadata', new arrow.Utf8(), true),\n    ])\n    try {\n      await db.createEmptyTable(spec.collection, schema, { mode: 'overwrite' })\n    } catch (err) {\n      throw new E_VECTOR_STORE_COLLECTION_FAILED(['createCollection', String(err)])\n    }\n  }\n\n  async dropCollection(collection: string, ifExists: boolean): Promise<void> {\n    const db = await this.#ensure()\n    if (ifExists && !(await this.hasCollection(collection))) return\n    try {\n      await db.dropTable(collection)\n      this.#dims.delete(collection)\n    } catch (err) {\n      const msg = String(err)\n      if (ifExists && msg.includes('not found')) return\n      throw new E_VECTOR_STORE_COLLECTION_FAILED(['dropCollection', msg])\n    }\n  }\n\n  async hasCollection(collection: string): Promise<boolean> {\n    const db = await this.#ensure()\n    try {\n      const names = await db.tableNames()\n      return names.includes(collection)\n    } catch {\n      return false\n    }\n  }\n\n  async renameCollection(_from: string, _to: string): Promise<void> {\n    throw new E_VECTOR_STORE_UNSUPPORTED_OPERATION(['renameCollection', 'lancedb'])\n  }\n\n  async executeUpsert(plan: UpsertPlan): Promise<void> {\n    if (plan.records.length === 0) return\n    validateRecords(plan.records)\n    const db = await this.#ensure()\n    const expected = this.#opts.dimensions ?? this.#dims.get(plan.collection)\n    try {\n      const rows: any[] = []\n      for (const r of plan.records) {\n        let vector = r.vector\n        if (!vector && r.document) {\n          const [v] = await this.encode([r.document], 'document')\n          vector = v\n        }\n        if (!vector) {\n          throw new E_VECTOR_STORE_UPSERT_FAILED(['Record missing vector and document'])\n        }\n        if (expected !== undefined && vector.length !== expected) {\n          throw new E_VECTOR_STORE_DIMENSION_MISMATCH([expected, vector.length])\n        }\n        rows.push({\n          id: r.id,\n          vec: vector,\n          document: r.document ?? '',\n          metadata: r.metadata ? JSON.stringify(r.metadata) : '{}',\n        })\n      }\n      const tbl = await db.openTable(plan.collection)\n      // Merge-insert on id = upsert (update matched, insert unmatched).\n      await tbl.mergeInsert('id').whenMatchedUpdateAll().whenNotMatchedInsertAll().execute(rows)\n    } catch (err) {\n      if (\n        isInstanceOf(err, 'E_VECTOR_STORE_DIMENSION_MISMATCH', E_VECTOR_STORE_DIMENSION_MISMATCH) ||\n        isInstanceOf(err, 'E_VECTOR_STORE_UPSERT_FAILED', E_VECTOR_STORE_UPSERT_FAILED)\n      ) {\n        throw err\n      }\n      throw new E_VECTOR_STORE_UPSERT_FAILED([String(err)])\n    }\n  }\n\n  async executeSearch(plan: SearchPlan): Promise<VectorMatch[]> {\n    const db = await this.#ensure()\n    const metric = this.#opts.metric ?? 'cosine'\n    let queryVector: number[] | undefined\n    let tbl: any\n    try {\n      tbl = await db.openTable(plan.collection)\n    } catch (err) {\n      throw new E_VECTOR_STORE_SEARCH_FAILED([String(err)])\n    }\n\n    if (plan.near) {\n      if ('vector' in plan.near) {\n        queryVector = plan.near.vector\n      } else if ('serverText' in plan.near) {\n        const [v] = await this.encode([plan.near.serverText], 'query')\n        queryVector = v\n      } else if ('id' in plan.near) {\n        const rows = await tbl\n          .query()\n          .where(`id = ${lit(plan.near.id)}`)\n          .limit(1)\n          .toArray()\n        if (rows.length === 0) {\n          throw new E_VECTOR_STORE_SEARCH_FAILED(['Referenced id not found: ' + plan.near.id])\n        }\n        queryVector = Array.from(rows[0].vec as ArrayLike<number>)\n      }\n    }\n\n    const offset = plan.offset ?? 0\n    try {\n      if (queryVector) {\n        // Over-fetch then JS-filter for exact cross-adapter filter semantics.\n        const k = plan.filter ? 1000 : plan.topK + offset\n        const rows = await tbl\n          .search(queryVector)\n          .distanceType(lanceMetric(metric))\n          .limit(k)\n          .toArray()\n        const filtered = plan.filter\n          ? rows.filter((row: any) => evaluateFilter(plan.filter!, this.#parseMeta(row.metadata)))\n          : rows\n        return filtered\n          .slice(offset, offset + plan.topK)\n          .map((row: any) => this.#project(row, plan, metric, true))\n      } else {\n        const rows = await tbl\n          .query()\n          .limit(plan.filter ? 100000 : plan.topK + offset)\n          .toArray()\n        const filtered = plan.filter\n          ? rows.filter((row: any) => evaluateFilter(plan.filter!, this.#parseMeta(row.metadata)))\n          : rows\n        return filtered\n          .slice(offset, offset + plan.topK)\n          .map((row: any) => this.#project(row, plan, metric, false))\n      }\n    } catch (err) {\n      throw new E_VECTOR_STORE_SEARCH_FAILED([String(err)])\n    }\n  }\n\n  #parseMeta(val: unknown): VectorMetadata {\n    if (typeof val === 'string') {\n      try {\n        return JSON.parse(val) as VectorMetadata\n      } catch {\n        return {}\n      }\n    }\n    if (val && typeof val === 'object') return val as VectorMetadata\n    return {}\n  }\n\n  #project(row: any, plan: SearchPlan, metric: string, isKnn: boolean): VectorMatch {\n    const proj = plan.projection\n    const out: VectorMatch = {}\n    if (proj.id) out.id = row.id as string\n    if (proj.vector && row.vec) out.vector = Array.from(row.vec as ArrayLike<number>)\n    if (proj.document) out.document = (row.document ?? undefined) as string | undefined\n    if (proj.metadata) out.metadata = this.#parseMeta(row.metadata)\n    if (isKnn && row._distance !== undefined && row._distance !== null) {\n      out.score = normalizeScore(Number(row._distance), metric as DistanceMetric, 'distance')\n    }\n    return out\n  }\n\n  async executeDelete(plan: DeletePlan): Promise<void> {\n    const db = await this.#ensure()\n    try {\n      const tbl = await db.openTable(plan.collection)\n      if (plan.ids && plan.ids.length > 0) {\n        const list = plan.ids.map((id) => lit(id)).join(', ')\n        await tbl.delete(`id IN (${list})`)\n      } else if (plan.filter) {\n        const rows = await tbl.query().limit(100000).toArray()\n        const targets: string[] = rows\n          .filter((row: any) => evaluateFilter(plan.filter!, this.#parseMeta(row.metadata)))\n          .map((row: any) => row.id as string)\n        if (targets.length > 0) {\n          const list = targets.map((id) => lit(id)).join(', ')\n          await tbl.delete(`id IN (${list})`)\n        }\n      } else {\n        await tbl.delete('true')\n      }\n    } catch (err) {\n      throw new E_VECTOR_STORE_DELETE_FAILED([String(err)])\n    }\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"lancedb.mjs","names":["#opts","#db","#ensure","#dims","#parseMeta","#project"],"sources":["../../../src/batteries/vector/lancedb/index.ts"],"sourcesContent":["/**\n * @module @nhtio/adk/batteries/vector/lancedb\n *\n * Embedded LanceDB adapter (no server — file-based, like sqlite_vec/duckdb). Each collection\n * is a Lance table with an explicit Arrow schema (`id` Utf8, `vec` FixedSizeList<Float32>,\n * `document` Utf8, `metadata` Utf8-JSON). KNN uses `table.search(vector).distanceType(...)`;\n * metadata is filtered with the neutral filter tree's JS reference evaluator for exact\n * cross-adapter parity. Upsert is a merge-insert on `id`.\n *\n * Drivers: `@lancedb/lancedb` + `apache-arrow` (prebuilt binary; no native compile).\n */\n\nimport { evaluateFilter } from '../filters'\nimport { normalizeScore } from '../helpers'\nimport { BaseVectorStore } from '../contract'\nimport { validateRecords } from '../validation'\nimport { isInstanceOf } from '@nhtio/adk/guards'\nimport {\n  E_VECTOR_STORE_DRIVER_UNAVAILABLE,\n  E_VECTOR_STORE_CONNECTION_FAILED,\n  E_VECTOR_STORE_COLLECTION_FAILED,\n  E_VECTOR_STORE_UPSERT_FAILED,\n  E_VECTOR_STORE_SEARCH_FAILED,\n  E_VECTOR_STORE_DELETE_FAILED,\n  E_VECTOR_STORE_DIMENSION_MISMATCH,\n  E_VECTOR_STORE_UNSUPPORTED_OPERATION,\n} from '../exceptions'\nimport type { SearchPlan, UpsertPlan, DeletePlan, CollectionSpec } from '../plan'\nimport type {\n  VectorMatch,\n  VectorStoreCapabilities,\n  BaseVectorStoreOptions,\n  VectorMetadata,\n  DistanceMetric,\n} from '../types'\n\nexport interface LanceDBVectorStoreOptions extends BaseVectorStoreOptions {\n  /** Connection and authentication parameters for the backend. */\n  connection: { uri: string }\n}\n\nconst getLanceDB = async () => {\n  try {\n    return await import('@lancedb/lancedb')\n  } catch {\n    throw new E_VECTOR_STORE_DRIVER_UNAVAILABLE(['@lancedb/lancedb'])\n  }\n}\n\nconst getArrow = async () => {\n  try {\n    return await import('apache-arrow')\n  } catch {\n    throw new E_VECTOR_STORE_DRIVER_UNAVAILABLE(['apache-arrow'])\n  }\n}\n\nconst lanceMetric = (metric: DistanceMetric): string =>\n  metric === 'euclidean' ? 'l2' : metric === 'dot' ? 'dot' : 'cosine'\n\n// LanceDB SQL string literal (single-quoted, escape embedded quotes).\nconst lit = (value: string): string => `'${value.replace(/'/g, \"''\")}'`\n\nexport class LanceDBVectorStore extends BaseVectorStore {\n  readonly capabilities: VectorStoreCapabilities = {\n    transactions: false,\n    namedVectors: false,\n    // Probed against @lancedb/lancedb 0.30.0 (local directory database): connection.renameTable\n    // rejects with \"LanceDBError: not supported: rename_table is not supported in LanceDB OSS\".\n    rename: false,\n    rawSql: false,\n    builtInEncoding: false,\n    // Embedded and synchronous: a write is visible on resolve. The option is a no-op.\n    consistency: { configurable: false, default: 'strong', modes: ['strong'] },\n  }\n\n  #db: any | null = null\n  #dims: Map<string, number> = new Map()\n\n  get #opts(): LanceDBVectorStoreOptions {\n    return this.options as LanceDBVectorStoreOptions\n  }\n\n  /** Static availability probe: whether this adapter's runtime driver can load in the current environment. */\n  static isAvailable(): boolean {\n    return typeof process !== 'undefined'\n  }\n  isAvailable(): boolean {\n    return typeof process !== 'undefined'\n  }\n\n  async connect(): Promise<void> {\n    if (this.#db) return\n    const lancedb = await getLanceDB()\n    const uri = this.#opts.connection?.uri\n    if (!uri) {\n      throw new E_VECTOR_STORE_CONNECTION_FAILED([\n        'LanceDB requires connection.uri (a directory path)',\n      ])\n    }\n    try {\n      this.#db = await lancedb.connect(uri)\n    } catch (err) {\n      throw new E_VECTOR_STORE_CONNECTION_FAILED([String(err)])\n    }\n  }\n\n  async close(): Promise<void> {\n    this.#db = null\n  }\n\n  async #ensure(): Promise<any> {\n    if (!this.#db) await this.connect()\n    return this.#db!\n  }\n\n  async createCollection(spec: CollectionSpec, ifNotExists: boolean): Promise<void> {\n    const db = await this.#ensure()\n    this.#dims.set(spec.collection, spec.vector.dimensions)\n    if (ifNotExists && (await this.hasCollection(spec.collection))) return\n    const arrow = await getArrow()\n    const schema = new arrow.Schema([\n      new arrow.Field('id', new arrow.Utf8(), false),\n      new arrow.Field(\n        'vec',\n        new arrow.FixedSizeList(\n          spec.vector.dimensions,\n          new arrow.Field('item', new arrow.Float32(), true)\n        ),\n        false\n      ),\n      new arrow.Field('document', new arrow.Utf8(), true),\n      new arrow.Field('metadata', new arrow.Utf8(), true),\n    ])\n    try {\n      await db.createEmptyTable(spec.collection, schema, { mode: 'overwrite' })\n    } catch (err) {\n      throw new E_VECTOR_STORE_COLLECTION_FAILED(['createCollection', String(err)])\n    }\n  }\n\n  async dropCollection(collection: string, ifExists: boolean): Promise<void> {\n    const db = await this.#ensure()\n    if (ifExists && !(await this.hasCollection(collection))) return\n    try {\n      await db.dropTable(collection)\n      this.#dims.delete(collection)\n    } catch (err) {\n      const msg = String(err)\n      if (ifExists && msg.includes('not found')) return\n      throw new E_VECTOR_STORE_COLLECTION_FAILED(['dropCollection', msg])\n    }\n  }\n\n  async hasCollection(collection: string): Promise<boolean> {\n    const db = await this.#ensure()\n    try {\n      const names = await db.tableNames()\n      return names.includes(collection)\n    } catch {\n      return false\n    }\n  }\n\n  async renameCollection(_from: string, _to: string): Promise<void> {\n    throw new E_VECTOR_STORE_UNSUPPORTED_OPERATION(['renameCollection', 'lancedb'])\n  }\n\n  async executeUpsert(plan: UpsertPlan): Promise<void> {\n    if (plan.records.length === 0) return\n    validateRecords(plan.records)\n    const db = await this.#ensure()\n    const expected = this.#opts.dimensions ?? this.#dims.get(plan.collection)\n    try {\n      const rows: any[] = []\n      for (const r of plan.records) {\n        let vector = r.vector\n        if (!vector && r.document) {\n          const [v] = await this.encode([r.document], 'document')\n          vector = v\n        }\n        if (!vector) {\n          throw new E_VECTOR_STORE_UPSERT_FAILED(['Record missing vector and document'])\n        }\n        if (expected !== undefined && vector.length !== expected) {\n          throw new E_VECTOR_STORE_DIMENSION_MISMATCH([expected, vector.length])\n        }\n        rows.push({\n          id: r.id,\n          vec: vector,\n          document: r.document ?? '',\n          metadata: r.metadata ? JSON.stringify(r.metadata) : '{}',\n        })\n      }\n      const tbl = await db.openTable(plan.collection)\n      // Merge-insert on id = upsert (update matched, insert unmatched).\n      await tbl.mergeInsert('id').whenMatchedUpdateAll().whenNotMatchedInsertAll().execute(rows)\n    } catch (err) {\n      if (\n        isInstanceOf(err, 'E_VECTOR_STORE_DIMENSION_MISMATCH', E_VECTOR_STORE_DIMENSION_MISMATCH) ||\n        isInstanceOf(err, 'E_VECTOR_STORE_UPSERT_FAILED', E_VECTOR_STORE_UPSERT_FAILED)\n      ) {\n        throw err\n      }\n      throw new E_VECTOR_STORE_UPSERT_FAILED([String(err)])\n    }\n  }\n\n  async executeSearch(plan: SearchPlan): Promise<VectorMatch[]> {\n    const db = await this.#ensure()\n    const metric = this.#opts.metric ?? 'cosine'\n    let queryVector: number[] | undefined\n    let tbl: any\n    try {\n      tbl = await db.openTable(plan.collection)\n    } catch (err) {\n      throw new E_VECTOR_STORE_SEARCH_FAILED([String(err)])\n    }\n\n    if (plan.near) {\n      if ('vector' in plan.near) {\n        queryVector = plan.near.vector\n      } else if ('serverText' in plan.near) {\n        const [v] = await this.encode([plan.near.serverText], 'query')\n        queryVector = v\n      } else if ('id' in plan.near) {\n        const rows = await tbl\n          .query()\n          .where(`id = ${lit(plan.near.id)}`)\n          .limit(1)\n          .toArray()\n        if (rows.length === 0) {\n          throw new E_VECTOR_STORE_SEARCH_FAILED(['Referenced id not found: ' + plan.near.id])\n        }\n        queryVector = Array.from(rows[0].vec as ArrayLike<number>)\n      }\n    }\n\n    const offset = plan.offset ?? 0\n    try {\n      if (queryVector) {\n        // Over-fetch then JS-filter for exact cross-adapter filter semantics.\n        const k = plan.filter ? 1000 : plan.topK + offset\n        const rows = await tbl\n          .search(queryVector)\n          .distanceType(lanceMetric(metric))\n          .limit(k)\n          .toArray()\n        const filtered = plan.filter\n          ? rows.filter((row: any) => evaluateFilter(plan.filter!, this.#parseMeta(row.metadata)))\n          : rows\n        return filtered\n          .slice(offset, offset + plan.topK)\n          .map((row: any) => this.#project(row, plan, metric, true))\n      } else {\n        const rows = await tbl\n          .query()\n          .limit(plan.filter ? 100000 : plan.topK + offset)\n          .toArray()\n        const filtered = plan.filter\n          ? rows.filter((row: any) => evaluateFilter(plan.filter!, this.#parseMeta(row.metadata)))\n          : rows\n        return filtered\n          .slice(offset, offset + plan.topK)\n          .map((row: any) => this.#project(row, plan, metric, false))\n      }\n    } catch (err) {\n      throw new E_VECTOR_STORE_SEARCH_FAILED([String(err)])\n    }\n  }\n\n  #parseMeta(val: unknown): VectorMetadata {\n    if (typeof val === 'string') {\n      try {\n        return JSON.parse(val) as VectorMetadata\n      } catch {\n        return {}\n      }\n    }\n    if (val && typeof val === 'object') return val as VectorMetadata\n    return {}\n  }\n\n  #project(row: any, plan: SearchPlan, metric: string, isKnn: boolean): VectorMatch {\n    const proj = plan.projection\n    const out: VectorMatch = {}\n    if (proj.id) out.id = row.id as string\n    if (proj.vector && row.vec) out.vector = Array.from(row.vec as ArrayLike<number>)\n    if (proj.document) out.document = (row.document ?? undefined) as string | undefined\n    if (proj.metadata) out.metadata = this.#parseMeta(row.metadata)\n    if (isKnn && row._distance !== undefined && row._distance !== null) {\n      out.score = normalizeScore(Number(row._distance), metric as DistanceMetric, 'distance')\n    }\n    return out\n  }\n\n  async executeDelete(plan: DeletePlan): Promise<void> {\n    const db = await this.#ensure()\n    try {\n      const tbl = await db.openTable(plan.collection)\n      if (plan.ids && plan.ids.length > 0) {\n        const list = plan.ids.map((id) => lit(id)).join(', ')\n        await tbl.delete(`id IN (${list})`)\n      } else if (plan.filter) {\n        const rows = await tbl.query().limit(100000).toArray()\n        const targets: string[] = rows\n          .filter((row: any) => evaluateFilter(plan.filter!, this.#parseMeta(row.metadata)))\n          .map((row: any) => row.id as string)\n        if (targets.length > 0) {\n          const list = targets.map((id) => lit(id)).join(', ')\n          await tbl.delete(`id IN (${list})`)\n        }\n      } else {\n        await tbl.delete('true')\n      }\n    } catch (err) {\n      throw new E_VECTOR_STORE_DELETE_FAILED([String(err)])\n    }\n  }\n}\n"],"mappings":"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"}

package/batteries/vector/retrievable.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 require("../../chunk-Cek0wNdY.cjs");
-const require_retrievable = require("../../retrievable-ReauMJxJ.cjs");
+const require_retrievable = require("../../retrievable-Bq-O3k6r.cjs");
 require("../../index.cjs");
 //#region src/batteries/vector/retrievable_glue.ts
 /**

package/batteries/vector/retrievable.mjs

@@ -1,4 +1,4 @@
-import { t as Retrievable } from "../../retrievable-mFgC1aty.mjs";
+import { t as Retrievable } from "../../retrievable-CXTAUuuv.mjs";
 import "../../index.mjs";
 //#region src/batteries/vector/retrievable_glue.ts
 /**

package/batteries/vector/sqlite_vec/index.d.ts

@@ -25,7 +25,7 @@ export declare class SqliteVecVectorStore extends BaseVectorStore {
     createCollection(spec: CollectionSpec, ifNotExists: boolean): Promise<void>;
     dropCollection(collection: string, ifExists: boolean): Promise<void>;
     hasCollection(collection: string): Promise<boolean>;
-    renameCollection(from: string, to: string): Promise<void>;
+    renameCollection(_from: string, _to: string): Promise<void>;
     executeUpsert(plan: UpsertPlan): Promise<void>;
     executeSearch(plan: SearchPlan): Promise<VectorMatch[]>;
     executeDelete(plan: DeletePlan): Promise<void>;

package/batteries/vector/sqlite_vec.cjs

@@ -9,11 +9,12 @@ const require_batteries_vector_validation = require("./validation.cjs");
 /**
 * @module @nhtio/adk/batteries/vector/sqlite_vec
 */
+var ident = (name) => `"${name.replace(/"/g, "\"\"")}"`;
 var SqliteVecVectorStore = class extends require_batteries_vector_contract.BaseVectorStore {
 	capabilities = {
 		transactions: true,
 		namedVectors: false,
-		rename: true,
+		rename: false,
 		rawSql: true,
 		builtInEncoding: false,
 		consistency: {
@@ -82,8 +83,8 @@ var SqliteVecVectorStore = class extends require_batteries_vector_contract.BaseV
 		await this.connect();
 		const { collection, vector } = spec;
 		const dims = vector.dimensions;
-		const tbl = `"${collection}"`;
-		const metaTbl = `"${collection}__meta"`;
+		const tbl = ident(collection);
+		const metaTbl = ident(collection + "__meta");
 		const { db } = this;
 		const exists = await this.hasCollection(collection);
 		if (!ifNotExists && exists) throw new require_batteries_vector_exceptions.E_VECTOR_STORE_COLLECTION_FAILED(["create", "collection exists"]);
@@ -97,8 +98,8 @@ var SqliteVecVectorStore = class extends require_batteries_vector_contract.BaseV
 	}
 	async dropCollection(collection, ifExists) {
 		await this.connect();
-		const tbl = `"${collection}"`;
-		const metaTbl = `"${collection}__meta"`;
+		const tbl = ident(collection);
+		const metaTbl = ident(collection + "__meta");
 		if (!await this.hasCollection(collection)) {
 			if (!ifExists) throw new require_batteries_vector_exceptions.E_VECTOR_STORE_COLLECTION_FAILED(["drop", "collection does not exist"]);
 			return;
@@ -121,22 +122,8 @@ var SqliteVecVectorStore = class extends require_batteries_vector_contract.BaseV
 			return false;
 		}
 	}
-	async renameCollection(from, to) {
-		await this.connect();
-		if (!await this.hasCollection(from)) throw new require_batteries_vector_exceptions.E_VECTOR_STORE_COLLECTION_FAILED(["rename", "source collection does not exist"]);
-		if (await this.hasCollection(to)) throw new require_batteries_vector_exceptions.E_VECTOR_STORE_COLLECTION_FAILED(["rename", "target collection already exists"]);
-		const { db } = this;
-		try {
-			db.exec(`ALTER TABLE "${from}" RENAME TO "${to}"`);
-			db.exec(`ALTER TABLE "${from}__meta" RENAME TO "${to}__meta"`);
-			const dims = this.#_dims.get(from);
-			if (dims !== void 0) {
-				this.#_dims.set(to, dims);
-				this.#_dims.delete(from);
-			}
-		} catch (e) {
-			throw new require_batteries_vector_exceptions.E_VECTOR_STORE_COLLECTION_FAILED(["rename", e?.message ?? String(e)]);
-		}
+	async renameCollection(_from, _to) {
+		throw new require_batteries_vector_exceptions.E_VECTOR_STORE_UNSUPPORTED_OPERATION(["renameCollection", "sqlite_vec"]);
 	}
 	async executeUpsert(plan) {
 		await this.connect();
@@ -159,11 +146,13 @@ var SqliteVecVectorStore = class extends require_batteries_vector_contract.BaseV
 				metadata: r.metadata
 			});
 		}
-		const stmtMetaInsert = db.prepare(`INSERT INTO "${collection}__meta" (id, document, metadata) VALUES (?, ?, ?)`);
-		const stmtMetaUpdate = db.prepare(`UPDATE "${collection}__meta" SET document = ?, metadata = ? WHERE id = ?`);
-		const stmtRowid = db.prepare(`SELECT rowid FROM "${collection}__meta" WHERE id = ?`);
-		const stmtVecDelete = db.prepare(`DELETE FROM "${collection}" WHERE rowid = ?`);
-		const stmtVecInsert = db.prepare(`INSERT INTO "${collection}" (rowid, embedding) VALUES (?, ?)`);
+		const metaTbl = ident(collection + "__meta");
+		const tbl = ident(collection);
+		const stmtMetaInsert = db.prepare(`INSERT INTO ${metaTbl} (id, document, metadata) VALUES (?, ?, ?)`);
+		const stmtMetaUpdate = db.prepare(`UPDATE ${metaTbl} SET document = ?, metadata = ? WHERE id = ?`);
+		const stmtRowid = db.prepare(`SELECT rowid FROM ${metaTbl} WHERE id = ?`);
+		const stmtVecDelete = db.prepare(`DELETE FROM ${tbl} WHERE rowid = ?`);
+		const stmtVecInsert = db.prepare(`INSERT INTO ${tbl} (rowid, embedding) VALUES (?, ?)`);
 		const txn = db.transaction(() => {
 			for (const r of resolvedRows) {
 				const buf = new Float32Array(r.vector);
@@ -191,8 +180,8 @@ var SqliteVecVectorStore = class extends require_batteries_vector_contract.BaseV
 		await this.connect();
 		const { db } = this;
 		const collection = plan.collection;
-		const tbl = `"${collection}"`;
-		const metaTbl = `"${collection}__meta"`;
+		const tbl = ident(collection);
+		const metaTbl = ident(collection + "__meta");
 		const near = plan.near;
 		const limit = (plan.offset ?? 0) + plan.topK;
 		try {
@@ -270,8 +259,8 @@ var SqliteVecVectorStore = class extends require_batteries_vector_contract.BaseV
 	async executeDelete(plan) {
 		await this.connect();
 		const collection = plan.collection;
-		const metaTbl = `"${collection}__meta"`;
-		const tbl = `"${collection}"`;
+		const metaTbl = ident(collection + "__meta");
+		const tbl = ident(collection);
 		const { db } = this;
 		try {
 			if (plan.ids && plan.ids.length > 0) {