@nhtio/adk 1.20260607.2 → 1.20260609.0

package/batteries/vector/cloudflare.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"cloudflare.cjs","names":["#opts","#baseUrl","#authHeaders","#req","#base","#headers","#settle","#index","#dims","#metrics","#projectMeta","#project"],"sources":["../../../src/batteries/vector/cloudflare/index.ts"],"sourcesContent":["/**\n * @module @nhtio/adk/batteries/vector/cloudflare\n *\n * Managed Cloudflare Vectorize V2 vector-store adapter over REST (pure fetch, no driver).\n * A logical collection maps to a Vectorize **index**. Supported dimensions: 32–1536.\n *\n * Upserter: POST /{name}/upsert via `multipart/form-data` with field name `vectors`\n * (content-type `application/x-ndjson`). Each line: `{\"id\":\"..\",\"values\":[..],\"metadata\":{..}}`.\n * Query/get/delete use JSON bodies. Eventual consistency is handled by settle-polling.\n *\n * Native filtering: Vectorize requires pre-created metadata indexes and lacks `$and`/`$or`.\n * For guaranteed cross-adapter parity, **over-fetch + JS evaluateFilter** (topK cap 100).\n *\n * Scores: returned as-is from Vectorize, then re-computed locally (cosineSim/dotProd/euclideanDist)\n * to guarantee the [0,1] contract.\n *\n * Document: stored under the reserved metadata key `__document`; extracted on read.\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_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\n// Cloudflare Vectorize V2 REST endpoint base\nconst BASE_URL = 'https://api.cloudflare.com/client/v4/accounts'\n\n// Over-fetch constant for JS filtering (Vectorize native filtering needs metadata indexes + lacks\n// $and/$or). Cloudflare caps topK at 50 when returnValues=true or returnMetadata=all (which we\n// need to recompute scores + filter locally), so 50 is the ceiling.\nconst OVERFETCH = 50\n\nconst mapMetricToCF = (metric: DistanceMetric): string => {\n  if (metric === 'cosine') return 'cosine'\n  if (metric === 'euclidean') return 'euclidean'\n  if (metric === 'dot') return 'dot-product'\n  throw new E_VECTOR_STORE_COLLECTION_FAILED([\n    'createCollection',\n    `Metric \"${metric}\" is not supported by Cloudflare Vectorize; use \"cosine\", \"euclidean\", or \"dot\"`,\n  ])\n}\n\n// Score computation helpers (copied from couchbase/index.ts)\nconst cosineSim = (a: number[], b: number[]): number => {\n  let dot = 0\n  let normA = 0\n  let normB = 0\n  a.forEach((av, i) => {\n    const bv = b[i]\n    dot += av * bv\n    normA += av * av\n    normB += bv * bv\n  })\n  const denom = Math.sqrt(normA) * Math.sqrt(normB)\n  return denom === 0 ? 0 : dot / denom\n}\n\nconst dotProd = (a: number[], b: number[]): number => {\n  let s = 0\n  a.forEach((av, i) => {\n    s += av * b[i]\n  })\n  return s\n}\n\nconst euclideanDist = (a: number[], b: number[]): number => {\n  let s = 0\n  a.forEach((av, i) => {\n    const d = av - b[i]\n    s += d * d\n  })\n  return Math.sqrt(s)\n}\n\nconst computeScore = (vec: number[], query: number[], metric: DistanceMetric): number => {\n  if (metric === 'cosine') {\n    const raw = cosineSim(vec, query)\n    return normalizeScore(raw, 'cosine', 'similarity')\n  } else if (metric === 'dot') {\n    const raw = dotProd(vec, query)\n    return normalizeScore(raw, 'dot', 'similarity')\n  } else if (metric === 'euclidean') {\n    const raw = euclideanDist(vec, query)\n    return normalizeScore(raw, 'euclidean', 'distance')\n  } else {\n    // Fallback\n    const raw = cosineSim(vec, query)\n    return normalizeScore(raw, 'cosine', 'similarity')\n  }\n}\n\nexport interface CloudflareVectorizeVectorStoreOptions extends BaseVectorStoreOptions {\n  connection: {\n    accountId: string\n    apiKey: string\n    indexNamePrefix?: string\n  }\n}\n\nexport class CloudflareVectorizeVectorStore extends BaseVectorStore {\n  readonly capabilities: VectorStoreCapabilities = {\n    transactions: false,\n    namedVectors: false,\n    rename: false,\n    rawSql: false,\n    builtInEncoding: false,\n    consistency: { configurable: false, default: 'strong', modes: ['strong'] },\n  }\n\n  #baseUrl: string | null = null\n  #authHeaders: Record<string, string> | null = null\n  #dims: Map<string, number> = new Map()\n  #metrics: Map<string, DistanceMetric> = new Map()\n\n  get #opts(): CloudflareVectorizeVectorStoreOptions {\n    return this.options as CloudflareVectorizeVectorStoreOptions\n  }\n\n  static isAvailable(): boolean {\n    return typeof process !== 'undefined' && typeof fetch !== 'undefined'\n  }\n\n  isAvailable(): boolean {\n    return typeof process !== 'undefined' && typeof fetch !== 'undefined'\n  }\n\n  #base(): string {\n    if (!this.#baseUrl) {\n      this.#baseUrl = `${BASE_URL}/${this.#opts.connection.accountId}/vectorize/v2/indexes`\n    }\n    return this.#baseUrl\n  }\n\n  #headers(): Record<string, string> {\n    if (!this.#authHeaders) {\n      this.#authHeaders = { Authorization: `Bearer ${this.#opts.connection.apiKey}` }\n    }\n    return this.#authHeaders\n  }\n\n  // Map a logical collection name to its physical Vectorize index name (with optional prefix).\n  #index(collection: string): string {\n    const prefix = this.#opts.connection.indexNamePrefix ?? ''\n    return `${prefix}${collection}`\n  }\n\n  async #req<T = any>(\n    method: string,\n    path: string,\n    { json, form }: { json?: any; form?: FormData } = {}\n  ): Promise<T> {\n    const url = this.#base() + path\n    const headers: Record<string, string> = { ...this.#headers() }\n    let body: BodyInit | undefined\n    if (form) {\n      body = form\n    } else if (json !== undefined) {\n      body = JSON.stringify(json)\n      headers['Content-Type'] = 'application/json'\n    }\n    const res = await fetch(url, { method, headers, body })\n    const payload: any = await res.json().catch(() => ({}))\n    if (!res.ok || !payload.success) {\n      const msg = payload.errors?.[0]?.message || payload.messages?.[0] || `HTTP ${res.status}`\n      throw new Error(msg)\n    }\n    return payload.result\n  }\n\n  // Settle-poll after writes/deletes against the QUERY index (the surface reads go through).\n  //\n  // Vectorize is aggressively eventually-consistent: a fresh index takes ~20s before its first\n  // write is queryable, and the query index FLAPS — a just-written id can appear then vanish (or a\n  // just-deleted id reappear) across consecutive polls for several seconds. A single converged poll\n  // is therefore not enough. We require STABILITY: `STABLE` consecutive polls that all satisfy the\n  // present/absent condition before returning, so the subsequent read-after-write is reliable.\n  async #settle(\n    collection: string,\n    opts: { present?: string[]; absent?: string[] }\n  ): Promise<void> {\n    const present = opts.present ?? []\n    const absent = opts.absent ?? []\n    if (present.length === 0 && absent.length === 0) return\n\n    const physicalIndex = this.#index(collection)\n    const dims = this.#dims.get(collection) ?? this.#opts.dimensions ?? 32\n    const probeVec = new Array(dims).fill(0)\n    probeVec[0] = 1\n\n    const STABLE = 3 // consecutive satisfying polls required to declare settled\n    const deadline = Date.now() + 60_000\n    let streak = 0\n    while (Date.now() < deadline) {\n      let ok = true\n      try {\n        const res = await this.#req<{ matches: any[] }>('POST', `/${physicalIndex}/query`, {\n          json: { vector: probeVec, topK: 50, returnValues: false, returnMetadata: 'none' },\n        })\n        const seen = new Set((res.matches ?? []).map((m: any) => m.id))\n        if (present.length > 0 && !present.every((id) => seen.has(id))) ok = false\n        if (absent.length > 0 && !absent.every((id) => !seen.has(id))) ok = false\n      } catch {\n        ok = false\n      }\n      streak = ok ? streak + 1 : 0\n      if (streak >= STABLE) return\n      await new Promise((r) => setTimeout(r, 500))\n    }\n  }\n\n  async connect(): Promise<void> {\n    // HTTP is stateless; the base URL + auth headers are built lazily and cached on first use.\n  }\n\n  async close(): Promise<void> {\n    this.#baseUrl = null\n    this.#authHeaders = null\n  }\n\n  async createCollection(spec: CollectionSpec, ifNotExists: boolean): Promise<void> {\n    const collection = spec.collection\n    const physicalIndex = this.#index(collection)\n    const dims = spec.vector.dimensions\n    const metric = spec.vector.metric\n\n    // Validate dimensions (32–1536)\n    if (dims < 32 || dims > 1536) {\n      throw new E_VECTOR_STORE_COLLECTION_FAILED([\n        'createCollection',\n        `Dimensions must be 32–1536; got ${dims}`,\n      ])\n    }\n\n    this.#dims.set(collection, dims)\n    this.#metrics.set(collection, metric)\n\n    if (ifNotExists) {\n      if (await this.hasCollection(collection)) return\n    }\n\n    try {\n      await this.connect()\n      const body: any = {\n        name: physicalIndex,\n        config: {\n          dimensions: dims,\n          metric: mapMetricToCF(metric),\n        },\n      }\n      await this.#req('POST', '', { json: body })\n    } catch (err: any) {\n      const msg = String(err)\n      if (ifNotExists && msg.toLowerCase().includes('already exists')) {\n        return\n      }\n      // If NOT ifNotExists and exists, best-effort clear (Vectorize has no bulk-clear;\n      // per-test isolation uses prefix so fresh index is effectively empty).\n      if (!ifNotExists && msg.toLowerCase().includes('already exists')) {\n        try {\n          await this.dropCollection(collection, true)\n          await this.createCollection(spec, false)\n          return\n        } catch {\n          // Fall through to rethrow original\n        }\n      }\n      throw new E_VECTOR_STORE_COLLECTION_FAILED(['createCollection', msg])\n    }\n  }\n\n  async dropCollection(collection: string, ifExists: boolean): Promise<void> {\n    const physicalIndex = this.#index(collection)\n\n    if (ifExists) {\n      if (!(await this.hasCollection(collection))) return\n    } else if (!(await this.hasCollection(collection))) {\n      return\n    }\n\n    try {\n      await this.connect()\n      await this.#req('DELETE', `/${physicalIndex}`)\n      // Clear local state\n      this.#dims.delete(collection)\n      this.#metrics.delete(collection)\n    } catch (err: any) {\n      const msg = String(err)\n      if (ifExists && (msg.includes('not found') || msg.includes('404'))) {\n        return\n      }\n      throw new E_VECTOR_STORE_COLLECTION_FAILED(['dropCollection', msg])\n    }\n  }\n\n  async hasCollection(collection: string): Promise<boolean> {\n    await this.connect()\n    const physicalIndex = this.#index(collection)\n    try {\n      const res: any = await this.#req('GET', `/${physicalIndex}`)\n      return !!res\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', 'cloudflare'])\n  }\n\n  async executeUpsert(plan: UpsertPlan): Promise<void> {\n    if (plan.records.length === 0) return\n    validateRecords(plan.records)\n\n    const collection = plan.collection\n    const physicalIndex = this.#index(collection)\n    const dims = this.#dims.get(collection) ?? this.#opts.dimensions\n\n    try {\n      await this.connect()\n\n      const ndjsonLines: string[] = []\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 (dims !== undefined && vector.length !== dims) {\n          throw new E_VECTOR_STORE_DIMENSION_MISMATCH([dims, vector.length])\n        }\n        const meta: any = { ...(r.metadata ?? {}) }\n        if (r.document) meta.__document = r.document\n        ndjsonLines.push(JSON.stringify({ id: r.id, values: vector, metadata: meta }))\n      }\n\n      const ndjson = ndjsonLines.join('\\n')\n\n      // Build FormData for multipart upload\n      const fd = new FormData()\n      fd.append('vectors', new Blob([ndjson], { type: 'application/x-ndjson' }), 'vectors.ndjson')\n\n      await this.#req('POST', `/${physicalIndex}/upsert`, { form: fd })\n\n      // Settle until all ids are visible\n      await this.#settle(collection, { present: plan.records.map((r) => r.id) })\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    await this.connect()\n    const collection = plan.collection\n    const physicalIndex = this.#index(collection)\n    const metric = this.#metrics.get(collection) ?? this.#opts.metric ?? 'cosine'\n    const offset = plan.offset ?? 0\n    const dims = this.#dims.get(collection) ?? this.#opts.dimensions ?? 32\n\n    let queryVector: number[] | undefined\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        try {\n          const res: any = await this.#req('POST', `/${physicalIndex}/get_by_ids`, {\n            json: { ids: [plan.near.id] },\n          })\n          const match = Array.isArray(res) ? res[0] : res?.result?.[0]\n          if (!match || !match.values) {\n            throw new E_VECTOR_STORE_SEARCH_FAILED(['Referenced id not found: ' + plan.near.id])\n          }\n          queryVector = match.values\n        } catch (err: any) {\n          const msg = String(err)\n          if (msg.includes('not found') || msg.includes('404')) {\n            throw new E_VECTOR_STORE_SEARCH_FAILED(['Referenced id not found: ' + plan.near.id])\n          }\n          throw new E_VECTOR_STORE_SEARCH_FAILED([msg])\n        }\n      }\n    }\n\n    if (queryVector) {\n      // Similarity search: query with over-fetch, JS-filter, recompute scores\n      const res: any = await this.#req('POST', `/${physicalIndex}/query`, {\n        json: {\n          vector: queryVector,\n          topK: OVERFETCH,\n          filter: undefined, // no native filter for parity\n          returnValues: true,\n          returnMetadata: 'all',\n        },\n      })\n      let rawMatches = res.matches ?? []\n\n      // Filter by JS-evaluateFilter\n      if (plan.filter) {\n        rawMatches = rawMatches.filter((m: any) => {\n          const meta = this.#projectMeta(m.metadata)\n          return evaluateFilter(plan.filter!, meta)\n        })\n      }\n\n      // Slice offset+topK\n      rawMatches = rawMatches.slice(offset, offset + plan.topK)\n\n      // Re-compute scores and project\n      const out: VectorMatch[] = []\n      for (const m of rawMatches) {\n        const projected = this.#project(m, plan, undefined, metric, queryVector)\n        if (projected) out.push(projected)\n      }\n      return out\n    } else {\n      // Filter-scan: query with arbitrary probe vector, over-fetch, JS-filter\n      const probeVec = new Array(dims).fill(0)\n      probeVec[0] = 1\n\n      const res: any = await this.#req('POST', `/${physicalIndex}/query`, {\n        json: {\n          vector: probeVec,\n          topK: OVERFETCH,\n          filter: undefined,\n          returnValues: false,\n          returnMetadata: 'all',\n        },\n      })\n      let rawMatches = res.matches ?? []\n\n      // JS-filter\n      if (plan.filter) {\n        rawMatches = rawMatches.filter((m: any) => {\n          const meta = this.#projectMeta(m.metadata)\n          return evaluateFilter(plan.filter!, meta)\n        })\n      }\n\n      // Slice\n      rawMatches = rawMatches.slice(offset, offset + plan.topK)\n\n      // Project without score\n      const out: VectorMatch[] = []\n      for (const m of rawMatches) {\n        const projected = this.#project(m, plan, undefined, metric, undefined)\n        if (projected) out.push(projected)\n      }\n      return out\n    }\n  }\n\n  #projectMeta(metadata: any): VectorMetadata {\n    if (!metadata || typeof metadata !== 'object') return {}\n    const out: VectorMetadata = {}\n    for (const key in metadata) {\n      if (key !== '__document') out[key] = metadata[key]\n    }\n    return out\n  }\n\n  #project(\n    match: any,\n    plan: SearchPlan,\n    score: number | undefined,\n    metric: DistanceMetric,\n    queryVector: number[] | undefined\n  ): VectorMatch | null {\n    const proj = plan.projection\n    const out: VectorMatch = {}\n\n    if (proj.id) out.id = match.id\n\n    if (proj.document) {\n      const meta = match.metadata ?? {}\n      if (typeof meta.__document === 'string') {\n        out.document = meta.__document\n      }\n    }\n\n    if (proj.metadata) {\n      out.metadata = this.#projectMeta(match.metadata)\n    }\n\n    if (proj.vector) {\n      out.vector = match.values\n    }\n\n    if (typeof score === 'number') {\n      out.score = score\n    } else if (queryVector && match.values) {\n      // Recompute score for the [0,1] contract\n      out.score = computeScore(match.values, queryVector, metric)\n    }\n\n    // If nothing was projected, return null to filter out\n    if (Object.keys(out).length === 0) return null\n    return out\n  }\n\n  async executeDelete(plan: DeletePlan): Promise<void> {\n    const collection = plan.collection\n    const physicalIndex = this.#index(collection)\n\n    try {\n      await this.connect()\n\n      if (plan.ids && plan.ids.length > 0) {\n        await this.#req('POST', `/${physicalIndex}/delete_by_ids`, {\n          json: { ids: plan.ids },\n        })\n        await this.#settle(collection, { absent: plan.ids })\n      } else if (plan.filter) {\n        // Enumerate all, JS-filter, delete matched\n        const dims = this.#dims.get(collection) ?? this.#opts.dimensions ?? 32\n        const probeVec = new Array(dims).fill(0)\n        probeVec[0] = 1\n\n        const res: any = await this.#req('POST', `/${physicalIndex}/query`, {\n          json: {\n            vector: probeVec,\n            topK: OVERFETCH,\n            returnValues: true,\n            returnMetadata: 'all',\n          },\n        })\n        const targets: string[] = []\n        for (const m of res.matches ?? []) {\n          const meta = this.#projectMeta(m.metadata)\n          if (evaluateFilter(plan.filter!, meta)) {\n            targets.push(m.id)\n          }\n        }\n\n        if (targets.length > 0) {\n          await this.#req('POST', `/${physicalIndex}/delete_by_ids`, {\n            json: { ids: targets },\n          })\n          await this.#settle(collection, { absent: targets })\n        }\n      } else {\n        // Delete all: enumerate all ids then delete\n        const dims = this.#dims.get(collection) ?? this.#opts.dimensions ?? 32\n        const probeVec = new Array(dims).fill(0)\n        probeVec[0] = 1\n\n        const res: any = await this.#req('POST', `/${physicalIndex}/query`, {\n          json: {\n            vector: probeVec,\n            topK: OVERFETCH,\n            returnValues: true,\n            returnMetadata: 'all',\n          },\n        })\n\n        const allIds = (res.matches ?? []).map((m: any) => m.id)\n        if (allIds.length > 0) {\n          await this.#req('POST', `/${physicalIndex}/delete_by_ids`, {\n            json: { ids: allIds },\n          })\n          await this.#settle(collection, { absent: allIds })\n        }\n      }\n    } catch (err: any) {\n      throw new E_VECTOR_STORE_DELETE_FAILED([String(err)])\n    }\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"cloudflare.cjs","names":["#opts","#baseUrl","#authHeaders","#req","#base","#headers","#settle","#index","#dims","#metrics","#projectMeta","#project"],"sources":["../../../src/batteries/vector/cloudflare/index.ts"],"sourcesContent":["/**\n * @module @nhtio/adk/batteries/vector/cloudflare\n *\n * Managed Cloudflare Vectorize V2 vector-store adapter over REST (pure fetch, no driver).\n * A logical collection maps to a Vectorize **index**. Supported dimensions: 32–1536.\n *\n * Upserter: POST /{name}/upsert via `multipart/form-data` with field name `vectors`\n * (content-type `application/x-ndjson`). Each line: `{\"id\":\"..\",\"values\":[..],\"metadata\":{..}}`.\n * Query/get/delete use JSON bodies. Eventual consistency is handled by settle-polling.\n *\n * Native filtering: Vectorize requires pre-created metadata indexes and lacks `$and`/`$or`.\n * For guaranteed cross-adapter parity, **over-fetch + JS evaluateFilter** (topK cap 100).\n *\n * Scores: returned as-is from Vectorize, then re-computed locally (cosineSim/dotProd/euclideanDist)\n * to guarantee the [0,1] contract.\n *\n * Document: stored under the reserved metadata key `__document`; extracted on read.\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_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\n// Cloudflare Vectorize V2 REST endpoint base\nconst BASE_URL = 'https://api.cloudflare.com/client/v4/accounts'\n\n// Over-fetch constant for JS filtering (Vectorize native filtering needs metadata indexes + lacks\n// $and/$or). Cloudflare caps topK at 50 when returnValues=true or returnMetadata=all (which we\n// need to recompute scores + filter locally), so 50 is the ceiling.\nconst OVERFETCH = 50\n\nconst mapMetricToCF = (metric: DistanceMetric): string => {\n  if (metric === 'cosine') return 'cosine'\n  if (metric === 'euclidean') return 'euclidean'\n  if (metric === 'dot') return 'dot-product'\n  throw new E_VECTOR_STORE_COLLECTION_FAILED([\n    'createCollection',\n    `Metric \"${metric}\" is not supported by Cloudflare Vectorize; use \"cosine\", \"euclidean\", or \"dot\"`,\n  ])\n}\n\n// Score computation helpers (copied from couchbase/index.ts)\nconst cosineSim = (a: number[], b: number[]): number => {\n  let dot = 0\n  let normA = 0\n  let normB = 0\n  a.forEach((av, i) => {\n    const bv = b[i]\n    dot += av * bv\n    normA += av * av\n    normB += bv * bv\n  })\n  const denom = Math.sqrt(normA) * Math.sqrt(normB)\n  return denom === 0 ? 0 : dot / denom\n}\n\nconst dotProd = (a: number[], b: number[]): number => {\n  let s = 0\n  a.forEach((av, i) => {\n    s += av * b[i]\n  })\n  return s\n}\n\nconst euclideanDist = (a: number[], b: number[]): number => {\n  let s = 0\n  a.forEach((av, i) => {\n    const d = av - b[i]\n    s += d * d\n  })\n  return Math.sqrt(s)\n}\n\nconst computeScore = (vec: number[], query: number[], metric: DistanceMetric): number => {\n  if (metric === 'cosine') {\n    const raw = cosineSim(vec, query)\n    return normalizeScore(raw, 'cosine', 'similarity')\n  } else if (metric === 'dot') {\n    const raw = dotProd(vec, query)\n    return normalizeScore(raw, 'dot', 'similarity')\n  } else if (metric === 'euclidean') {\n    const raw = euclideanDist(vec, query)\n    return normalizeScore(raw, 'euclidean', 'distance')\n  } else {\n    // Fallback\n    const raw = cosineSim(vec, query)\n    return normalizeScore(raw, 'cosine', 'similarity')\n  }\n}\n\nexport interface CloudflareVectorizeVectorStoreOptions extends BaseVectorStoreOptions {\n  /** Connection and authentication parameters for the backend. */\n  connection: {\n    accountId: string\n    apiKey: string\n    indexNamePrefix?: string\n  }\n}\n\nexport class CloudflareVectorizeVectorStore extends BaseVectorStore {\n  readonly capabilities: VectorStoreCapabilities = {\n    transactions: false,\n    namedVectors: false,\n    rename: false,\n    rawSql: false,\n    builtInEncoding: false,\n    consistency: { configurable: false, default: 'strong', modes: ['strong'] },\n  }\n\n  #baseUrl: string | null = null\n  #authHeaders: Record<string, string> | null = null\n  #dims: Map<string, number> = new Map()\n  #metrics: Map<string, DistanceMetric> = new Map()\n\n  get #opts(): CloudflareVectorizeVectorStoreOptions {\n    return this.options as CloudflareVectorizeVectorStoreOptions\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' && typeof fetch !== 'undefined'\n  }\n\n  isAvailable(): boolean {\n    return typeof process !== 'undefined' && typeof fetch !== 'undefined'\n  }\n\n  #base(): string {\n    if (!this.#baseUrl) {\n      this.#baseUrl = `${BASE_URL}/${this.#opts.connection.accountId}/vectorize/v2/indexes`\n    }\n    return this.#baseUrl\n  }\n\n  #headers(): Record<string, string> {\n    if (!this.#authHeaders) {\n      this.#authHeaders = { Authorization: `Bearer ${this.#opts.connection.apiKey}` }\n    }\n    return this.#authHeaders\n  }\n\n  // Map a logical collection name to its physical Vectorize index name (with optional prefix).\n  #index(collection: string): string {\n    const prefix = this.#opts.connection.indexNamePrefix ?? ''\n    return `${prefix}${collection}`\n  }\n\n  async #req<T = any>(\n    method: string,\n    path: string,\n    { json, form }: { json?: any; form?: FormData } = {}\n  ): Promise<T> {\n    const url = this.#base() + path\n    const headers: Record<string, string> = { ...this.#headers() }\n    let body: BodyInit | undefined\n    if (form) {\n      body = form\n    } else if (json !== undefined) {\n      body = JSON.stringify(json)\n      headers['Content-Type'] = 'application/json'\n    }\n    const res = await fetch(url, { method, headers, body })\n    const payload: any = await res.json().catch(() => ({}))\n    if (!res.ok || !payload.success) {\n      const msg = payload.errors?.[0]?.message || payload.messages?.[0] || `HTTP ${res.status}`\n      throw new Error(msg)\n    }\n    return payload.result\n  }\n\n  // Settle-poll after writes/deletes against the QUERY index (the surface reads go through).\n  //\n  // Vectorize is aggressively eventually-consistent: a fresh index takes ~20s before its first\n  // write is queryable, and the query index FLAPS — a just-written id can appear then vanish (or a\n  // just-deleted id reappear) across consecutive polls for several seconds. A single converged poll\n  // is therefore not enough. We require STABILITY: `STABLE` consecutive polls that all satisfy the\n  // present/absent condition before returning, so the subsequent read-after-write is reliable.\n  async #settle(\n    collection: string,\n    opts: { present?: string[]; absent?: string[] }\n  ): Promise<void> {\n    const present = opts.present ?? []\n    const absent = opts.absent ?? []\n    if (present.length === 0 && absent.length === 0) return\n\n    const physicalIndex = this.#index(collection)\n    const dims = this.#dims.get(collection) ?? this.#opts.dimensions ?? 32\n    const probeVec = new Array(dims).fill(0)\n    probeVec[0] = 1\n\n    const STABLE = 3 // consecutive satisfying polls required to declare settled\n    const deadline = Date.now() + 60_000\n    let streak = 0\n    while (Date.now() < deadline) {\n      let ok = true\n      try {\n        const res = await this.#req<{ matches: any[] }>('POST', `/${physicalIndex}/query`, {\n          json: { vector: probeVec, topK: 50, returnValues: false, returnMetadata: 'none' },\n        })\n        const seen = new Set((res.matches ?? []).map((m: any) => m.id))\n        if (present.length > 0 && !present.every((id) => seen.has(id))) ok = false\n        if (absent.length > 0 && !absent.every((id) => !seen.has(id))) ok = false\n      } catch {\n        ok = false\n      }\n      streak = ok ? streak + 1 : 0\n      if (streak >= STABLE) return\n      await new Promise((r) => setTimeout(r, 500))\n    }\n  }\n\n  async connect(): Promise<void> {\n    // HTTP is stateless; the base URL + auth headers are built lazily and cached on first use.\n  }\n\n  async close(): Promise<void> {\n    this.#baseUrl = null\n    this.#authHeaders = null\n  }\n\n  async createCollection(spec: CollectionSpec, ifNotExists: boolean): Promise<void> {\n    const collection = spec.collection\n    const physicalIndex = this.#index(collection)\n    const dims = spec.vector.dimensions\n    const metric = spec.vector.metric\n\n    // Validate dimensions (32–1536)\n    if (dims < 32 || dims > 1536) {\n      throw new E_VECTOR_STORE_COLLECTION_FAILED([\n        'createCollection',\n        `Dimensions must be 32–1536; got ${dims}`,\n      ])\n    }\n\n    this.#dims.set(collection, dims)\n    this.#metrics.set(collection, metric)\n\n    if (ifNotExists) {\n      if (await this.hasCollection(collection)) return\n    }\n\n    try {\n      await this.connect()\n      const body: any = {\n        name: physicalIndex,\n        config: {\n          dimensions: dims,\n          metric: mapMetricToCF(metric),\n        },\n      }\n      await this.#req('POST', '', { json: body })\n    } catch (err: any) {\n      const msg = String(err)\n      if (ifNotExists && msg.toLowerCase().includes('already exists')) {\n        return\n      }\n      // If NOT ifNotExists and exists, best-effort clear (Vectorize has no bulk-clear;\n      // per-test isolation uses prefix so fresh index is effectively empty).\n      if (!ifNotExists && msg.toLowerCase().includes('already exists')) {\n        try {\n          await this.dropCollection(collection, true)\n          await this.createCollection(spec, false)\n          return\n        } catch {\n          // Fall through to rethrow original\n        }\n      }\n      throw new E_VECTOR_STORE_COLLECTION_FAILED(['createCollection', msg])\n    }\n  }\n\n  async dropCollection(collection: string, ifExists: boolean): Promise<void> {\n    const physicalIndex = this.#index(collection)\n\n    if (ifExists) {\n      if (!(await this.hasCollection(collection))) return\n    } else if (!(await this.hasCollection(collection))) {\n      return\n    }\n\n    try {\n      await this.connect()\n      await this.#req('DELETE', `/${physicalIndex}`)\n      // Clear local state\n      this.#dims.delete(collection)\n      this.#metrics.delete(collection)\n    } catch (err: any) {\n      const msg = String(err)\n      if (ifExists && (msg.includes('not found') || msg.includes('404'))) {\n        return\n      }\n      throw new E_VECTOR_STORE_COLLECTION_FAILED(['dropCollection', msg])\n    }\n  }\n\n  async hasCollection(collection: string): Promise<boolean> {\n    await this.connect()\n    const physicalIndex = this.#index(collection)\n    try {\n      const res: any = await this.#req('GET', `/${physicalIndex}`)\n      return !!res\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', 'cloudflare'])\n  }\n\n  async executeUpsert(plan: UpsertPlan): Promise<void> {\n    if (plan.records.length === 0) return\n    validateRecords(plan.records)\n\n    const collection = plan.collection\n    const physicalIndex = this.#index(collection)\n    const dims = this.#dims.get(collection) ?? this.#opts.dimensions\n\n    try {\n      await this.connect()\n\n      const ndjsonLines: string[] = []\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 (dims !== undefined && vector.length !== dims) {\n          throw new E_VECTOR_STORE_DIMENSION_MISMATCH([dims, vector.length])\n        }\n        const meta: any = { ...(r.metadata ?? {}) }\n        if (r.document) meta.__document = r.document\n        ndjsonLines.push(JSON.stringify({ id: r.id, values: vector, metadata: meta }))\n      }\n\n      const ndjson = ndjsonLines.join('\\n')\n\n      // Build FormData for multipart upload\n      const fd = new FormData()\n      fd.append('vectors', new Blob([ndjson], { type: 'application/x-ndjson' }), 'vectors.ndjson')\n\n      await this.#req('POST', `/${physicalIndex}/upsert`, { form: fd })\n\n      // Settle until all ids are visible\n      await this.#settle(collection, { present: plan.records.map((r) => r.id) })\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    await this.connect()\n    const collection = plan.collection\n    const physicalIndex = this.#index(collection)\n    const metric = this.#metrics.get(collection) ?? this.#opts.metric ?? 'cosine'\n    const offset = plan.offset ?? 0\n    const dims = this.#dims.get(collection) ?? this.#opts.dimensions ?? 32\n\n    let queryVector: number[] | undefined\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        try {\n          const res: any = await this.#req('POST', `/${physicalIndex}/get_by_ids`, {\n            json: { ids: [plan.near.id] },\n          })\n          const match = Array.isArray(res) ? res[0] : res?.result?.[0]\n          if (!match || !match.values) {\n            throw new E_VECTOR_STORE_SEARCH_FAILED(['Referenced id not found: ' + plan.near.id])\n          }\n          queryVector = match.values\n        } catch (err: any) {\n          const msg = String(err)\n          if (msg.includes('not found') || msg.includes('404')) {\n            throw new E_VECTOR_STORE_SEARCH_FAILED(['Referenced id not found: ' + plan.near.id])\n          }\n          throw new E_VECTOR_STORE_SEARCH_FAILED([msg])\n        }\n      }\n    }\n\n    if (queryVector) {\n      // Similarity search: query with over-fetch, JS-filter, recompute scores\n      const res: any = await this.#req('POST', `/${physicalIndex}/query`, {\n        json: {\n          vector: queryVector,\n          topK: OVERFETCH,\n          filter: undefined, // no native filter for parity\n          returnValues: true,\n          returnMetadata: 'all',\n        },\n      })\n      let rawMatches = res.matches ?? []\n\n      // Filter by JS-evaluateFilter\n      if (plan.filter) {\n        rawMatches = rawMatches.filter((m: any) => {\n          const meta = this.#projectMeta(m.metadata)\n          return evaluateFilter(plan.filter!, meta)\n        })\n      }\n\n      // Slice offset+topK\n      rawMatches = rawMatches.slice(offset, offset + plan.topK)\n\n      // Re-compute scores and project\n      const out: VectorMatch[] = []\n      for (const m of rawMatches) {\n        const projected = this.#project(m, plan, undefined, metric, queryVector)\n        if (projected) out.push(projected)\n      }\n      return out\n    } else {\n      // Filter-scan: query with arbitrary probe vector, over-fetch, JS-filter\n      const probeVec = new Array(dims).fill(0)\n      probeVec[0] = 1\n\n      const res: any = await this.#req('POST', `/${physicalIndex}/query`, {\n        json: {\n          vector: probeVec,\n          topK: OVERFETCH,\n          filter: undefined,\n          returnValues: false,\n          returnMetadata: 'all',\n        },\n      })\n      let rawMatches = res.matches ?? []\n\n      // JS-filter\n      if (plan.filter) {\n        rawMatches = rawMatches.filter((m: any) => {\n          const meta = this.#projectMeta(m.metadata)\n          return evaluateFilter(plan.filter!, meta)\n        })\n      }\n\n      // Slice\n      rawMatches = rawMatches.slice(offset, offset + plan.topK)\n\n      // Project without score\n      const out: VectorMatch[] = []\n      for (const m of rawMatches) {\n        const projected = this.#project(m, plan, undefined, metric, undefined)\n        if (projected) out.push(projected)\n      }\n      return out\n    }\n  }\n\n  #projectMeta(metadata: any): VectorMetadata {\n    if (!metadata || typeof metadata !== 'object') return {}\n    const out: VectorMetadata = {}\n    for (const key in metadata) {\n      if (key !== '__document') out[key] = metadata[key]\n    }\n    return out\n  }\n\n  #project(\n    match: any,\n    plan: SearchPlan,\n    score: number | undefined,\n    metric: DistanceMetric,\n    queryVector: number[] | undefined\n  ): VectorMatch | null {\n    const proj = plan.projection\n    const out: VectorMatch = {}\n\n    if (proj.id) out.id = match.id\n\n    if (proj.document) {\n      const meta = match.metadata ?? {}\n      if (typeof meta.__document === 'string') {\n        out.document = meta.__document\n      }\n    }\n\n    if (proj.metadata) {\n      out.metadata = this.#projectMeta(match.metadata)\n    }\n\n    if (proj.vector) {\n      out.vector = match.values\n    }\n\n    if (typeof score === 'number') {\n      out.score = score\n    } else if (queryVector && match.values) {\n      // Recompute score for the [0,1] contract\n      out.score = computeScore(match.values, queryVector, metric)\n    }\n\n    // If nothing was projected, return null to filter out\n    if (Object.keys(out).length === 0) return null\n    return out\n  }\n\n  async executeDelete(plan: DeletePlan): Promise<void> {\n    const collection = plan.collection\n    const physicalIndex = this.#index(collection)\n\n    try {\n      await this.connect()\n\n      if (plan.ids && plan.ids.length > 0) {\n        await this.#req('POST', `/${physicalIndex}/delete_by_ids`, {\n          json: { ids: plan.ids },\n        })\n        await this.#settle(collection, { absent: plan.ids })\n      } else if (plan.filter) {\n        // Enumerate all, JS-filter, delete matched\n        const dims = this.#dims.get(collection) ?? this.#opts.dimensions ?? 32\n        const probeVec = new Array(dims).fill(0)\n        probeVec[0] = 1\n\n        const res: any = await this.#req('POST', `/${physicalIndex}/query`, {\n          json: {\n            vector: probeVec,\n            topK: OVERFETCH,\n            returnValues: true,\n            returnMetadata: 'all',\n          },\n        })\n        const targets: string[] = []\n        for (const m of res.matches ?? []) {\n          const meta = this.#projectMeta(m.metadata)\n          if (evaluateFilter(plan.filter!, meta)) {\n            targets.push(m.id)\n          }\n        }\n\n        if (targets.length > 0) {\n          await this.#req('POST', `/${physicalIndex}/delete_by_ids`, {\n            json: { ids: targets },\n          })\n          await this.#settle(collection, { absent: targets })\n        }\n      } else {\n        // Delete all: enumerate all ids then delete\n        const dims = this.#dims.get(collection) ?? this.#opts.dimensions ?? 32\n        const probeVec = new Array(dims).fill(0)\n        probeVec[0] = 1\n\n        const res: any = await this.#req('POST', `/${physicalIndex}/query`, {\n          json: {\n            vector: probeVec,\n            topK: OVERFETCH,\n            returnValues: true,\n            returnMetadata: 'all',\n          },\n        })\n\n        const allIds = (res.matches ?? []).map((m: any) => m.id)\n        if (allIds.length > 0) {\n          await this.#req('POST', `/${physicalIndex}/delete_by_ids`, {\n            json: { ids: allIds },\n          })\n          await this.#settle(collection, { absent: allIds })\n        }\n      }\n    } catch (err: any) {\n      throw new E_VECTOR_STORE_DELETE_FAILED([String(err)])\n    }\n  }\n}\n"],"mappings":"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"}

package/batteries/vector/cloudflare.mjs

@@ -1,4 +1,4 @@
-import { s as isInstanceOf } from "../../tool_registry-D1pSSlsd.mjs";
+import { s as isInstanceOf } from "../../tool_registry-791Vrjtf.mjs";
 import "../../guards.mjs";
 import { evaluateFilter } from "./filters.mjs";
 import { normalizeScore } from "./helpers.mjs";
@@ -86,6 +86,7 @@ var CloudflareVectorizeVectorStore = class extends BaseVectorStore {
 	get #opts() {
 		return this.options;
 	}
+	/** Static availability probe: whether this adapter's runtime driver can load in the current environment. */
 	static isAvailable() {
 		return typeof process !== "undefined" && typeof fetch !== "undefined";
 	}

package/batteries/vector/cloudflare.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"cloudflare.mjs","names":["#opts","#baseUrl","#authHeaders","#req","#base","#headers","#settle","#index","#dims","#metrics","#projectMeta","#project"],"sources":["../../../src/batteries/vector/cloudflare/index.ts"],"sourcesContent":["/**\n * @module @nhtio/adk/batteries/vector/cloudflare\n *\n * Managed Cloudflare Vectorize V2 vector-store adapter over REST (pure fetch, no driver).\n * A logical collection maps to a Vectorize **index**. Supported dimensions: 32–1536.\n *\n * Upserter: POST /{name}/upsert via `multipart/form-data` with field name `vectors`\n * (content-type `application/x-ndjson`). Each line: `{\"id\":\"..\",\"values\":[..],\"metadata\":{..}}`.\n * Query/get/delete use JSON bodies. Eventual consistency is handled by settle-polling.\n *\n * Native filtering: Vectorize requires pre-created metadata indexes and lacks `$and`/`$or`.\n * For guaranteed cross-adapter parity, **over-fetch + JS evaluateFilter** (topK cap 100).\n *\n * Scores: returned as-is from Vectorize, then re-computed locally (cosineSim/dotProd/euclideanDist)\n * to guarantee the [0,1] contract.\n *\n * Document: stored under the reserved metadata key `__document`; extracted on read.\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_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\n// Cloudflare Vectorize V2 REST endpoint base\nconst BASE_URL = 'https://api.cloudflare.com/client/v4/accounts'\n\n// Over-fetch constant for JS filtering (Vectorize native filtering needs metadata indexes + lacks\n// $and/$or). Cloudflare caps topK at 50 when returnValues=true or returnMetadata=all (which we\n// need to recompute scores + filter locally), so 50 is the ceiling.\nconst OVERFETCH = 50\n\nconst mapMetricToCF = (metric: DistanceMetric): string => {\n  if (metric === 'cosine') return 'cosine'\n  if (metric === 'euclidean') return 'euclidean'\n  if (metric === 'dot') return 'dot-product'\n  throw new E_VECTOR_STORE_COLLECTION_FAILED([\n    'createCollection',\n    `Metric \"${metric}\" is not supported by Cloudflare Vectorize; use \"cosine\", \"euclidean\", or \"dot\"`,\n  ])\n}\n\n// Score computation helpers (copied from couchbase/index.ts)\nconst cosineSim = (a: number[], b: number[]): number => {\n  let dot = 0\n  let normA = 0\n  let normB = 0\n  a.forEach((av, i) => {\n    const bv = b[i]\n    dot += av * bv\n    normA += av * av\n    normB += bv * bv\n  })\n  const denom = Math.sqrt(normA) * Math.sqrt(normB)\n  return denom === 0 ? 0 : dot / denom\n}\n\nconst dotProd = (a: number[], b: number[]): number => {\n  let s = 0\n  a.forEach((av, i) => {\n    s += av * b[i]\n  })\n  return s\n}\n\nconst euclideanDist = (a: number[], b: number[]): number => {\n  let s = 0\n  a.forEach((av, i) => {\n    const d = av - b[i]\n    s += d * d\n  })\n  return Math.sqrt(s)\n}\n\nconst computeScore = (vec: number[], query: number[], metric: DistanceMetric): number => {\n  if (metric === 'cosine') {\n    const raw = cosineSim(vec, query)\n    return normalizeScore(raw, 'cosine', 'similarity')\n  } else if (metric === 'dot') {\n    const raw = dotProd(vec, query)\n    return normalizeScore(raw, 'dot', 'similarity')\n  } else if (metric === 'euclidean') {\n    const raw = euclideanDist(vec, query)\n    return normalizeScore(raw, 'euclidean', 'distance')\n  } else {\n    // Fallback\n    const raw = cosineSim(vec, query)\n    return normalizeScore(raw, 'cosine', 'similarity')\n  }\n}\n\nexport interface CloudflareVectorizeVectorStoreOptions extends BaseVectorStoreOptions {\n  connection: {\n    accountId: string\n    apiKey: string\n    indexNamePrefix?: string\n  }\n}\n\nexport class CloudflareVectorizeVectorStore extends BaseVectorStore {\n  readonly capabilities: VectorStoreCapabilities = {\n    transactions: false,\n    namedVectors: false,\n    rename: false,\n    rawSql: false,\n    builtInEncoding: false,\n    consistency: { configurable: false, default: 'strong', modes: ['strong'] },\n  }\n\n  #baseUrl: string | null = null\n  #authHeaders: Record<string, string> | null = null\n  #dims: Map<string, number> = new Map()\n  #metrics: Map<string, DistanceMetric> = new Map()\n\n  get #opts(): CloudflareVectorizeVectorStoreOptions {\n    return this.options as CloudflareVectorizeVectorStoreOptions\n  }\n\n  static isAvailable(): boolean {\n    return typeof process !== 'undefined' && typeof fetch !== 'undefined'\n  }\n\n  isAvailable(): boolean {\n    return typeof process !== 'undefined' && typeof fetch !== 'undefined'\n  }\n\n  #base(): string {\n    if (!this.#baseUrl) {\n      this.#baseUrl = `${BASE_URL}/${this.#opts.connection.accountId}/vectorize/v2/indexes`\n    }\n    return this.#baseUrl\n  }\n\n  #headers(): Record<string, string> {\n    if (!this.#authHeaders) {\n      this.#authHeaders = { Authorization: `Bearer ${this.#opts.connection.apiKey}` }\n    }\n    return this.#authHeaders\n  }\n\n  // Map a logical collection name to its physical Vectorize index name (with optional prefix).\n  #index(collection: string): string {\n    const prefix = this.#opts.connection.indexNamePrefix ?? ''\n    return `${prefix}${collection}`\n  }\n\n  async #req<T = any>(\n    method: string,\n    path: string,\n    { json, form }: { json?: any; form?: FormData } = {}\n  ): Promise<T> {\n    const url = this.#base() + path\n    const headers: Record<string, string> = { ...this.#headers() }\n    let body: BodyInit | undefined\n    if (form) {\n      body = form\n    } else if (json !== undefined) {\n      body = JSON.stringify(json)\n      headers['Content-Type'] = 'application/json'\n    }\n    const res = await fetch(url, { method, headers, body })\n    const payload: any = await res.json().catch(() => ({}))\n    if (!res.ok || !payload.success) {\n      const msg = payload.errors?.[0]?.message || payload.messages?.[0] || `HTTP ${res.status}`\n      throw new Error(msg)\n    }\n    return payload.result\n  }\n\n  // Settle-poll after writes/deletes against the QUERY index (the surface reads go through).\n  //\n  // Vectorize is aggressively eventually-consistent: a fresh index takes ~20s before its first\n  // write is queryable, and the query index FLAPS — a just-written id can appear then vanish (or a\n  // just-deleted id reappear) across consecutive polls for several seconds. A single converged poll\n  // is therefore not enough. We require STABILITY: `STABLE` consecutive polls that all satisfy the\n  // present/absent condition before returning, so the subsequent read-after-write is reliable.\n  async #settle(\n    collection: string,\n    opts: { present?: string[]; absent?: string[] }\n  ): Promise<void> {\n    const present = opts.present ?? []\n    const absent = opts.absent ?? []\n    if (present.length === 0 && absent.length === 0) return\n\n    const physicalIndex = this.#index(collection)\n    const dims = this.#dims.get(collection) ?? this.#opts.dimensions ?? 32\n    const probeVec = new Array(dims).fill(0)\n    probeVec[0] = 1\n\n    const STABLE = 3 // consecutive satisfying polls required to declare settled\n    const deadline = Date.now() + 60_000\n    let streak = 0\n    while (Date.now() < deadline) {\n      let ok = true\n      try {\n        const res = await this.#req<{ matches: any[] }>('POST', `/${physicalIndex}/query`, {\n          json: { vector: probeVec, topK: 50, returnValues: false, returnMetadata: 'none' },\n        })\n        const seen = new Set((res.matches ?? []).map((m: any) => m.id))\n        if (present.length > 0 && !present.every((id) => seen.has(id))) ok = false\n        if (absent.length > 0 && !absent.every((id) => !seen.has(id))) ok = false\n      } catch {\n        ok = false\n      }\n      streak = ok ? streak + 1 : 0\n      if (streak >= STABLE) return\n      await new Promise((r) => setTimeout(r, 500))\n    }\n  }\n\n  async connect(): Promise<void> {\n    // HTTP is stateless; the base URL + auth headers are built lazily and cached on first use.\n  }\n\n  async close(): Promise<void> {\n    this.#baseUrl = null\n    this.#authHeaders = null\n  }\n\n  async createCollection(spec: CollectionSpec, ifNotExists: boolean): Promise<void> {\n    const collection = spec.collection\n    const physicalIndex = this.#index(collection)\n    const dims = spec.vector.dimensions\n    const metric = spec.vector.metric\n\n    // Validate dimensions (32–1536)\n    if (dims < 32 || dims > 1536) {\n      throw new E_VECTOR_STORE_COLLECTION_FAILED([\n        'createCollection',\n        `Dimensions must be 32–1536; got ${dims}`,\n      ])\n    }\n\n    this.#dims.set(collection, dims)\n    this.#metrics.set(collection, metric)\n\n    if (ifNotExists) {\n      if (await this.hasCollection(collection)) return\n    }\n\n    try {\n      await this.connect()\n      const body: any = {\n        name: physicalIndex,\n        config: {\n          dimensions: dims,\n          metric: mapMetricToCF(metric),\n        },\n      }\n      await this.#req('POST', '', { json: body })\n    } catch (err: any) {\n      const msg = String(err)\n      if (ifNotExists && msg.toLowerCase().includes('already exists')) {\n        return\n      }\n      // If NOT ifNotExists and exists, best-effort clear (Vectorize has no bulk-clear;\n      // per-test isolation uses prefix so fresh index is effectively empty).\n      if (!ifNotExists && msg.toLowerCase().includes('already exists')) {\n        try {\n          await this.dropCollection(collection, true)\n          await this.createCollection(spec, false)\n          return\n        } catch {\n          // Fall through to rethrow original\n        }\n      }\n      throw new E_VECTOR_STORE_COLLECTION_FAILED(['createCollection', msg])\n    }\n  }\n\n  async dropCollection(collection: string, ifExists: boolean): Promise<void> {\n    const physicalIndex = this.#index(collection)\n\n    if (ifExists) {\n      if (!(await this.hasCollection(collection))) return\n    } else if (!(await this.hasCollection(collection))) {\n      return\n    }\n\n    try {\n      await this.connect()\n      await this.#req('DELETE', `/${physicalIndex}`)\n      // Clear local state\n      this.#dims.delete(collection)\n      this.#metrics.delete(collection)\n    } catch (err: any) {\n      const msg = String(err)\n      if (ifExists && (msg.includes('not found') || msg.includes('404'))) {\n        return\n      }\n      throw new E_VECTOR_STORE_COLLECTION_FAILED(['dropCollection', msg])\n    }\n  }\n\n  async hasCollection(collection: string): Promise<boolean> {\n    await this.connect()\n    const physicalIndex = this.#index(collection)\n    try {\n      const res: any = await this.#req('GET', `/${physicalIndex}`)\n      return !!res\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', 'cloudflare'])\n  }\n\n  async executeUpsert(plan: UpsertPlan): Promise<void> {\n    if (plan.records.length === 0) return\n    validateRecords(plan.records)\n\n    const collection = plan.collection\n    const physicalIndex = this.#index(collection)\n    const dims = this.#dims.get(collection) ?? this.#opts.dimensions\n\n    try {\n      await this.connect()\n\n      const ndjsonLines: string[] = []\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 (dims !== undefined && vector.length !== dims) {\n          throw new E_VECTOR_STORE_DIMENSION_MISMATCH([dims, vector.length])\n        }\n        const meta: any = { ...(r.metadata ?? {}) }\n        if (r.document) meta.__document = r.document\n        ndjsonLines.push(JSON.stringify({ id: r.id, values: vector, metadata: meta }))\n      }\n\n      const ndjson = ndjsonLines.join('\\n')\n\n      // Build FormData for multipart upload\n      const fd = new FormData()\n      fd.append('vectors', new Blob([ndjson], { type: 'application/x-ndjson' }), 'vectors.ndjson')\n\n      await this.#req('POST', `/${physicalIndex}/upsert`, { form: fd })\n\n      // Settle until all ids are visible\n      await this.#settle(collection, { present: plan.records.map((r) => r.id) })\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    await this.connect()\n    const collection = plan.collection\n    const physicalIndex = this.#index(collection)\n    const metric = this.#metrics.get(collection) ?? this.#opts.metric ?? 'cosine'\n    const offset = plan.offset ?? 0\n    const dims = this.#dims.get(collection) ?? this.#opts.dimensions ?? 32\n\n    let queryVector: number[] | undefined\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        try {\n          const res: any = await this.#req('POST', `/${physicalIndex}/get_by_ids`, {\n            json: { ids: [plan.near.id] },\n          })\n          const match = Array.isArray(res) ? res[0] : res?.result?.[0]\n          if (!match || !match.values) {\n            throw new E_VECTOR_STORE_SEARCH_FAILED(['Referenced id not found: ' + plan.near.id])\n          }\n          queryVector = match.values\n        } catch (err: any) {\n          const msg = String(err)\n          if (msg.includes('not found') || msg.includes('404')) {\n            throw new E_VECTOR_STORE_SEARCH_FAILED(['Referenced id not found: ' + plan.near.id])\n          }\n          throw new E_VECTOR_STORE_SEARCH_FAILED([msg])\n        }\n      }\n    }\n\n    if (queryVector) {\n      // Similarity search: query with over-fetch, JS-filter, recompute scores\n      const res: any = await this.#req('POST', `/${physicalIndex}/query`, {\n        json: {\n          vector: queryVector,\n          topK: OVERFETCH,\n          filter: undefined, // no native filter for parity\n          returnValues: true,\n          returnMetadata: 'all',\n        },\n      })\n      let rawMatches = res.matches ?? []\n\n      // Filter by JS-evaluateFilter\n      if (plan.filter) {\n        rawMatches = rawMatches.filter((m: any) => {\n          const meta = this.#projectMeta(m.metadata)\n          return evaluateFilter(plan.filter!, meta)\n        })\n      }\n\n      // Slice offset+topK\n      rawMatches = rawMatches.slice(offset, offset + plan.topK)\n\n      // Re-compute scores and project\n      const out: VectorMatch[] = []\n      for (const m of rawMatches) {\n        const projected = this.#project(m, plan, undefined, metric, queryVector)\n        if (projected) out.push(projected)\n      }\n      return out\n    } else {\n      // Filter-scan: query with arbitrary probe vector, over-fetch, JS-filter\n      const probeVec = new Array(dims).fill(0)\n      probeVec[0] = 1\n\n      const res: any = await this.#req('POST', `/${physicalIndex}/query`, {\n        json: {\n          vector: probeVec,\n          topK: OVERFETCH,\n          filter: undefined,\n          returnValues: false,\n          returnMetadata: 'all',\n        },\n      })\n      let rawMatches = res.matches ?? []\n\n      // JS-filter\n      if (plan.filter) {\n        rawMatches = rawMatches.filter((m: any) => {\n          const meta = this.#projectMeta(m.metadata)\n          return evaluateFilter(plan.filter!, meta)\n        })\n      }\n\n      // Slice\n      rawMatches = rawMatches.slice(offset, offset + plan.topK)\n\n      // Project without score\n      const out: VectorMatch[] = []\n      for (const m of rawMatches) {\n        const projected = this.#project(m, plan, undefined, metric, undefined)\n        if (projected) out.push(projected)\n      }\n      return out\n    }\n  }\n\n  #projectMeta(metadata: any): VectorMetadata {\n    if (!metadata || typeof metadata !== 'object') return {}\n    const out: VectorMetadata = {}\n    for (const key in metadata) {\n      if (key !== '__document') out[key] = metadata[key]\n    }\n    return out\n  }\n\n  #project(\n    match: any,\n    plan: SearchPlan,\n    score: number | undefined,\n    metric: DistanceMetric,\n    queryVector: number[] | undefined\n  ): VectorMatch | null {\n    const proj = plan.projection\n    const out: VectorMatch = {}\n\n    if (proj.id) out.id = match.id\n\n    if (proj.document) {\n      const meta = match.metadata ?? {}\n      if (typeof meta.__document === 'string') {\n        out.document = meta.__document\n      }\n    }\n\n    if (proj.metadata) {\n      out.metadata = this.#projectMeta(match.metadata)\n    }\n\n    if (proj.vector) {\n      out.vector = match.values\n    }\n\n    if (typeof score === 'number') {\n      out.score = score\n    } else if (queryVector && match.values) {\n      // Recompute score for the [0,1] contract\n      out.score = computeScore(match.values, queryVector, metric)\n    }\n\n    // If nothing was projected, return null to filter out\n    if (Object.keys(out).length === 0) return null\n    return out\n  }\n\n  async executeDelete(plan: DeletePlan): Promise<void> {\n    const collection = plan.collection\n    const physicalIndex = this.#index(collection)\n\n    try {\n      await this.connect()\n\n      if (plan.ids && plan.ids.length > 0) {\n        await this.#req('POST', `/${physicalIndex}/delete_by_ids`, {\n          json: { ids: plan.ids },\n        })\n        await this.#settle(collection, { absent: plan.ids })\n      } else if (plan.filter) {\n        // Enumerate all, JS-filter, delete matched\n        const dims = this.#dims.get(collection) ?? this.#opts.dimensions ?? 32\n        const probeVec = new Array(dims).fill(0)\n        probeVec[0] = 1\n\n        const res: any = await this.#req('POST', `/${physicalIndex}/query`, {\n          json: {\n            vector: probeVec,\n            topK: OVERFETCH,\n            returnValues: true,\n            returnMetadata: 'all',\n          },\n        })\n        const targets: string[] = []\n        for (const m of res.matches ?? []) {\n          const meta = this.#projectMeta(m.metadata)\n          if (evaluateFilter(plan.filter!, meta)) {\n            targets.push(m.id)\n          }\n        }\n\n        if (targets.length > 0) {\n          await this.#req('POST', `/${physicalIndex}/delete_by_ids`, {\n            json: { ids: targets },\n          })\n          await this.#settle(collection, { absent: targets })\n        }\n      } else {\n        // Delete all: enumerate all ids then delete\n        const dims = this.#dims.get(collection) ?? this.#opts.dimensions ?? 32\n        const probeVec = new Array(dims).fill(0)\n        probeVec[0] = 1\n\n        const res: any = await this.#req('POST', `/${physicalIndex}/query`, {\n          json: {\n            vector: probeVec,\n            topK: OVERFETCH,\n            returnValues: true,\n            returnMetadata: 'all',\n          },\n        })\n\n        const allIds = (res.matches ?? []).map((m: any) => m.id)\n        if (allIds.length > 0) {\n          await this.#req('POST', `/${physicalIndex}/delete_by_ids`, {\n            json: { ids: allIds },\n          })\n          await this.#settle(collection, { absent: allIds })\n        }\n      }\n    } catch (err: any) {\n      throw new E_VECTOR_STORE_DELETE_FAILED([String(err)])\n    }\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"cloudflare.mjs","names":["#opts","#baseUrl","#authHeaders","#req","#base","#headers","#settle","#index","#dims","#metrics","#projectMeta","#project"],"sources":["../../../src/batteries/vector/cloudflare/index.ts"],"sourcesContent":["/**\n * @module @nhtio/adk/batteries/vector/cloudflare\n *\n * Managed Cloudflare Vectorize V2 vector-store adapter over REST (pure fetch, no driver).\n * A logical collection maps to a Vectorize **index**. Supported dimensions: 32–1536.\n *\n * Upserter: POST /{name}/upsert via `multipart/form-data` with field name `vectors`\n * (content-type `application/x-ndjson`). Each line: `{\"id\":\"..\",\"values\":[..],\"metadata\":{..}}`.\n * Query/get/delete use JSON bodies. Eventual consistency is handled by settle-polling.\n *\n * Native filtering: Vectorize requires pre-created metadata indexes and lacks `$and`/`$or`.\n * For guaranteed cross-adapter parity, **over-fetch + JS evaluateFilter** (topK cap 100).\n *\n * Scores: returned as-is from Vectorize, then re-computed locally (cosineSim/dotProd/euclideanDist)\n * to guarantee the [0,1] contract.\n *\n * Document: stored under the reserved metadata key `__document`; extracted on read.\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_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\n// Cloudflare Vectorize V2 REST endpoint base\nconst BASE_URL = 'https://api.cloudflare.com/client/v4/accounts'\n\n// Over-fetch constant for JS filtering (Vectorize native filtering needs metadata indexes + lacks\n// $and/$or). Cloudflare caps topK at 50 when returnValues=true or returnMetadata=all (which we\n// need to recompute scores + filter locally), so 50 is the ceiling.\nconst OVERFETCH = 50\n\nconst mapMetricToCF = (metric: DistanceMetric): string => {\n  if (metric === 'cosine') return 'cosine'\n  if (metric === 'euclidean') return 'euclidean'\n  if (metric === 'dot') return 'dot-product'\n  throw new E_VECTOR_STORE_COLLECTION_FAILED([\n    'createCollection',\n    `Metric \"${metric}\" is not supported by Cloudflare Vectorize; use \"cosine\", \"euclidean\", or \"dot\"`,\n  ])\n}\n\n// Score computation helpers (copied from couchbase/index.ts)\nconst cosineSim = (a: number[], b: number[]): number => {\n  let dot = 0\n  let normA = 0\n  let normB = 0\n  a.forEach((av, i) => {\n    const bv = b[i]\n    dot += av * bv\n    normA += av * av\n    normB += bv * bv\n  })\n  const denom = Math.sqrt(normA) * Math.sqrt(normB)\n  return denom === 0 ? 0 : dot / denom\n}\n\nconst dotProd = (a: number[], b: number[]): number => {\n  let s = 0\n  a.forEach((av, i) => {\n    s += av * b[i]\n  })\n  return s\n}\n\nconst euclideanDist = (a: number[], b: number[]): number => {\n  let s = 0\n  a.forEach((av, i) => {\n    const d = av - b[i]\n    s += d * d\n  })\n  return Math.sqrt(s)\n}\n\nconst computeScore = (vec: number[], query: number[], metric: DistanceMetric): number => {\n  if (metric === 'cosine') {\n    const raw = cosineSim(vec, query)\n    return normalizeScore(raw, 'cosine', 'similarity')\n  } else if (metric === 'dot') {\n    const raw = dotProd(vec, query)\n    return normalizeScore(raw, 'dot', 'similarity')\n  } else if (metric === 'euclidean') {\n    const raw = euclideanDist(vec, query)\n    return normalizeScore(raw, 'euclidean', 'distance')\n  } else {\n    // Fallback\n    const raw = cosineSim(vec, query)\n    return normalizeScore(raw, 'cosine', 'similarity')\n  }\n}\n\nexport interface CloudflareVectorizeVectorStoreOptions extends BaseVectorStoreOptions {\n  /** Connection and authentication parameters for the backend. */\n  connection: {\n    accountId: string\n    apiKey: string\n    indexNamePrefix?: string\n  }\n}\n\nexport class CloudflareVectorizeVectorStore extends BaseVectorStore {\n  readonly capabilities: VectorStoreCapabilities = {\n    transactions: false,\n    namedVectors: false,\n    rename: false,\n    rawSql: false,\n    builtInEncoding: false,\n    consistency: { configurable: false, default: 'strong', modes: ['strong'] },\n  }\n\n  #baseUrl: string | null = null\n  #authHeaders: Record<string, string> | null = null\n  #dims: Map<string, number> = new Map()\n  #metrics: Map<string, DistanceMetric> = new Map()\n\n  get #opts(): CloudflareVectorizeVectorStoreOptions {\n    return this.options as CloudflareVectorizeVectorStoreOptions\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' && typeof fetch !== 'undefined'\n  }\n\n  isAvailable(): boolean {\n    return typeof process !== 'undefined' && typeof fetch !== 'undefined'\n  }\n\n  #base(): string {\n    if (!this.#baseUrl) {\n      this.#baseUrl = `${BASE_URL}/${this.#opts.connection.accountId}/vectorize/v2/indexes`\n    }\n    return this.#baseUrl\n  }\n\n  #headers(): Record<string, string> {\n    if (!this.#authHeaders) {\n      this.#authHeaders = { Authorization: `Bearer ${this.#opts.connection.apiKey}` }\n    }\n    return this.#authHeaders\n  }\n\n  // Map a logical collection name to its physical Vectorize index name (with optional prefix).\n  #index(collection: string): string {\n    const prefix = this.#opts.connection.indexNamePrefix ?? ''\n    return `${prefix}${collection}`\n  }\n\n  async #req<T = any>(\n    method: string,\n    path: string,\n    { json, form }: { json?: any; form?: FormData } = {}\n  ): Promise<T> {\n    const url = this.#base() + path\n    const headers: Record<string, string> = { ...this.#headers() }\n    let body: BodyInit | undefined\n    if (form) {\n      body = form\n    } else if (json !== undefined) {\n      body = JSON.stringify(json)\n      headers['Content-Type'] = 'application/json'\n    }\n    const res = await fetch(url, { method, headers, body })\n    const payload: any = await res.json().catch(() => ({}))\n    if (!res.ok || !payload.success) {\n      const msg = payload.errors?.[0]?.message || payload.messages?.[0] || `HTTP ${res.status}`\n      throw new Error(msg)\n    }\n    return payload.result\n  }\n\n  // Settle-poll after writes/deletes against the QUERY index (the surface reads go through).\n  //\n  // Vectorize is aggressively eventually-consistent: a fresh index takes ~20s before its first\n  // write is queryable, and the query index FLAPS — a just-written id can appear then vanish (or a\n  // just-deleted id reappear) across consecutive polls for several seconds. A single converged poll\n  // is therefore not enough. We require STABILITY: `STABLE` consecutive polls that all satisfy the\n  // present/absent condition before returning, so the subsequent read-after-write is reliable.\n  async #settle(\n    collection: string,\n    opts: { present?: string[]; absent?: string[] }\n  ): Promise<void> {\n    const present = opts.present ?? []\n    const absent = opts.absent ?? []\n    if (present.length === 0 && absent.length === 0) return\n\n    const physicalIndex = this.#index(collection)\n    const dims = this.#dims.get(collection) ?? this.#opts.dimensions ?? 32\n    const probeVec = new Array(dims).fill(0)\n    probeVec[0] = 1\n\n    const STABLE = 3 // consecutive satisfying polls required to declare settled\n    const deadline = Date.now() + 60_000\n    let streak = 0\n    while (Date.now() < deadline) {\n      let ok = true\n      try {\n        const res = await this.#req<{ matches: any[] }>('POST', `/${physicalIndex}/query`, {\n          json: { vector: probeVec, topK: 50, returnValues: false, returnMetadata: 'none' },\n        })\n        const seen = new Set((res.matches ?? []).map((m: any) => m.id))\n        if (present.length > 0 && !present.every((id) => seen.has(id))) ok = false\n        if (absent.length > 0 && !absent.every((id) => !seen.has(id))) ok = false\n      } catch {\n        ok = false\n      }\n      streak = ok ? streak + 1 : 0\n      if (streak >= STABLE) return\n      await new Promise((r) => setTimeout(r, 500))\n    }\n  }\n\n  async connect(): Promise<void> {\n    // HTTP is stateless; the base URL + auth headers are built lazily and cached on first use.\n  }\n\n  async close(): Promise<void> {\n    this.#baseUrl = null\n    this.#authHeaders = null\n  }\n\n  async createCollection(spec: CollectionSpec, ifNotExists: boolean): Promise<void> {\n    const collection = spec.collection\n    const physicalIndex = this.#index(collection)\n    const dims = spec.vector.dimensions\n    const metric = spec.vector.metric\n\n    // Validate dimensions (32–1536)\n    if (dims < 32 || dims > 1536) {\n      throw new E_VECTOR_STORE_COLLECTION_FAILED([\n        'createCollection',\n        `Dimensions must be 32–1536; got ${dims}`,\n      ])\n    }\n\n    this.#dims.set(collection, dims)\n    this.#metrics.set(collection, metric)\n\n    if (ifNotExists) {\n      if (await this.hasCollection(collection)) return\n    }\n\n    try {\n      await this.connect()\n      const body: any = {\n        name: physicalIndex,\n        config: {\n          dimensions: dims,\n          metric: mapMetricToCF(metric),\n        },\n      }\n      await this.#req('POST', '', { json: body })\n    } catch (err: any) {\n      const msg = String(err)\n      if (ifNotExists && msg.toLowerCase().includes('already exists')) {\n        return\n      }\n      // If NOT ifNotExists and exists, best-effort clear (Vectorize has no bulk-clear;\n      // per-test isolation uses prefix so fresh index is effectively empty).\n      if (!ifNotExists && msg.toLowerCase().includes('already exists')) {\n        try {\n          await this.dropCollection(collection, true)\n          await this.createCollection(spec, false)\n          return\n        } catch {\n          // Fall through to rethrow original\n        }\n      }\n      throw new E_VECTOR_STORE_COLLECTION_FAILED(['createCollection', msg])\n    }\n  }\n\n  async dropCollection(collection: string, ifExists: boolean): Promise<void> {\n    const physicalIndex = this.#index(collection)\n\n    if (ifExists) {\n      if (!(await this.hasCollection(collection))) return\n    } else if (!(await this.hasCollection(collection))) {\n      return\n    }\n\n    try {\n      await this.connect()\n      await this.#req('DELETE', `/${physicalIndex}`)\n      // Clear local state\n      this.#dims.delete(collection)\n      this.#metrics.delete(collection)\n    } catch (err: any) {\n      const msg = String(err)\n      if (ifExists && (msg.includes('not found') || msg.includes('404'))) {\n        return\n      }\n      throw new E_VECTOR_STORE_COLLECTION_FAILED(['dropCollection', msg])\n    }\n  }\n\n  async hasCollection(collection: string): Promise<boolean> {\n    await this.connect()\n    const physicalIndex = this.#index(collection)\n    try {\n      const res: any = await this.#req('GET', `/${physicalIndex}`)\n      return !!res\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', 'cloudflare'])\n  }\n\n  async executeUpsert(plan: UpsertPlan): Promise<void> {\n    if (plan.records.length === 0) return\n    validateRecords(plan.records)\n\n    const collection = plan.collection\n    const physicalIndex = this.#index(collection)\n    const dims = this.#dims.get(collection) ?? this.#opts.dimensions\n\n    try {\n      await this.connect()\n\n      const ndjsonLines: string[] = []\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 (dims !== undefined && vector.length !== dims) {\n          throw new E_VECTOR_STORE_DIMENSION_MISMATCH([dims, vector.length])\n        }\n        const meta: any = { ...(r.metadata ?? {}) }\n        if (r.document) meta.__document = r.document\n        ndjsonLines.push(JSON.stringify({ id: r.id, values: vector, metadata: meta }))\n      }\n\n      const ndjson = ndjsonLines.join('\\n')\n\n      // Build FormData for multipart upload\n      const fd = new FormData()\n      fd.append('vectors', new Blob([ndjson], { type: 'application/x-ndjson' }), 'vectors.ndjson')\n\n      await this.#req('POST', `/${physicalIndex}/upsert`, { form: fd })\n\n      // Settle until all ids are visible\n      await this.#settle(collection, { present: plan.records.map((r) => r.id) })\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    await this.connect()\n    const collection = plan.collection\n    const physicalIndex = this.#index(collection)\n    const metric = this.#metrics.get(collection) ?? this.#opts.metric ?? 'cosine'\n    const offset = plan.offset ?? 0\n    const dims = this.#dims.get(collection) ?? this.#opts.dimensions ?? 32\n\n    let queryVector: number[] | undefined\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        try {\n          const res: any = await this.#req('POST', `/${physicalIndex}/get_by_ids`, {\n            json: { ids: [plan.near.id] },\n          })\n          const match = Array.isArray(res) ? res[0] : res?.result?.[0]\n          if (!match || !match.values) {\n            throw new E_VECTOR_STORE_SEARCH_FAILED(['Referenced id not found: ' + plan.near.id])\n          }\n          queryVector = match.values\n        } catch (err: any) {\n          const msg = String(err)\n          if (msg.includes('not found') || msg.includes('404')) {\n            throw new E_VECTOR_STORE_SEARCH_FAILED(['Referenced id not found: ' + plan.near.id])\n          }\n          throw new E_VECTOR_STORE_SEARCH_FAILED([msg])\n        }\n      }\n    }\n\n    if (queryVector) {\n      // Similarity search: query with over-fetch, JS-filter, recompute scores\n      const res: any = await this.#req('POST', `/${physicalIndex}/query`, {\n        json: {\n          vector: queryVector,\n          topK: OVERFETCH,\n          filter: undefined, // no native filter for parity\n          returnValues: true,\n          returnMetadata: 'all',\n        },\n      })\n      let rawMatches = res.matches ?? []\n\n      // Filter by JS-evaluateFilter\n      if (plan.filter) {\n        rawMatches = rawMatches.filter((m: any) => {\n          const meta = this.#projectMeta(m.metadata)\n          return evaluateFilter(plan.filter!, meta)\n        })\n      }\n\n      // Slice offset+topK\n      rawMatches = rawMatches.slice(offset, offset + plan.topK)\n\n      // Re-compute scores and project\n      const out: VectorMatch[] = []\n      for (const m of rawMatches) {\n        const projected = this.#project(m, plan, undefined, metric, queryVector)\n        if (projected) out.push(projected)\n      }\n      return out\n    } else {\n      // Filter-scan: query with arbitrary probe vector, over-fetch, JS-filter\n      const probeVec = new Array(dims).fill(0)\n      probeVec[0] = 1\n\n      const res: any = await this.#req('POST', `/${physicalIndex}/query`, {\n        json: {\n          vector: probeVec,\n          topK: OVERFETCH,\n          filter: undefined,\n          returnValues: false,\n          returnMetadata: 'all',\n        },\n      })\n      let rawMatches = res.matches ?? []\n\n      // JS-filter\n      if (plan.filter) {\n        rawMatches = rawMatches.filter((m: any) => {\n          const meta = this.#projectMeta(m.metadata)\n          return evaluateFilter(plan.filter!, meta)\n        })\n      }\n\n      // Slice\n      rawMatches = rawMatches.slice(offset, offset + plan.topK)\n\n      // Project without score\n      const out: VectorMatch[] = []\n      for (const m of rawMatches) {\n        const projected = this.#project(m, plan, undefined, metric, undefined)\n        if (projected) out.push(projected)\n      }\n      return out\n    }\n  }\n\n  #projectMeta(metadata: any): VectorMetadata {\n    if (!metadata || typeof metadata !== 'object') return {}\n    const out: VectorMetadata = {}\n    for (const key in metadata) {\n      if (key !== '__document') out[key] = metadata[key]\n    }\n    return out\n  }\n\n  #project(\n    match: any,\n    plan: SearchPlan,\n    score: number | undefined,\n    metric: DistanceMetric,\n    queryVector: number[] | undefined\n  ): VectorMatch | null {\n    const proj = plan.projection\n    const out: VectorMatch = {}\n\n    if (proj.id) out.id = match.id\n\n    if (proj.document) {\n      const meta = match.metadata ?? {}\n      if (typeof meta.__document === 'string') {\n        out.document = meta.__document\n      }\n    }\n\n    if (proj.metadata) {\n      out.metadata = this.#projectMeta(match.metadata)\n    }\n\n    if (proj.vector) {\n      out.vector = match.values\n    }\n\n    if (typeof score === 'number') {\n      out.score = score\n    } else if (queryVector && match.values) {\n      // Recompute score for the [0,1] contract\n      out.score = computeScore(match.values, queryVector, metric)\n    }\n\n    // If nothing was projected, return null to filter out\n    if (Object.keys(out).length === 0) return null\n    return out\n  }\n\n  async executeDelete(plan: DeletePlan): Promise<void> {\n    const collection = plan.collection\n    const physicalIndex = this.#index(collection)\n\n    try {\n      await this.connect()\n\n      if (plan.ids && plan.ids.length > 0) {\n        await this.#req('POST', `/${physicalIndex}/delete_by_ids`, {\n          json: { ids: plan.ids },\n        })\n        await this.#settle(collection, { absent: plan.ids })\n      } else if (plan.filter) {\n        // Enumerate all, JS-filter, delete matched\n        const dims = this.#dims.get(collection) ?? this.#opts.dimensions ?? 32\n        const probeVec = new Array(dims).fill(0)\n        probeVec[0] = 1\n\n        const res: any = await this.#req('POST', `/${physicalIndex}/query`, {\n          json: {\n            vector: probeVec,\n            topK: OVERFETCH,\n            returnValues: true,\n            returnMetadata: 'all',\n          },\n        })\n        const targets: string[] = []\n        for (const m of res.matches ?? []) {\n          const meta = this.#projectMeta(m.metadata)\n          if (evaluateFilter(plan.filter!, meta)) {\n            targets.push(m.id)\n          }\n        }\n\n        if (targets.length > 0) {\n          await this.#req('POST', `/${physicalIndex}/delete_by_ids`, {\n            json: { ids: targets },\n          })\n          await this.#settle(collection, { absent: targets })\n        }\n      } else {\n        // Delete all: enumerate all ids then delete\n        const dims = this.#dims.get(collection) ?? this.#opts.dimensions ?? 32\n        const probeVec = new Array(dims).fill(0)\n        probeVec[0] = 1\n\n        const res: any = await this.#req('POST', `/${physicalIndex}/query`, {\n          json: {\n            vector: probeVec,\n            topK: OVERFETCH,\n            returnValues: true,\n            returnMetadata: 'all',\n          },\n        })\n\n        const allIds = (res.matches ?? []).map((m: any) => m.id)\n        if (allIds.length > 0) {\n          await this.#req('POST', `/${physicalIndex}/delete_by_ids`, {\n            json: { ids: allIds },\n          })\n          await this.#settle(collection, { absent: allIds })\n        }\n      }\n    } catch (err: any) {\n      throw new E_VECTOR_STORE_DELETE_FAILED([String(err)])\n    }\n  }\n}\n"],"mappings":"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"}

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

@@ -7,8 +7,30 @@
  * @module @nhtio/adk/batteries/vector/conformance
  */
 import type { CallableVectorStore } from "../contract";
+/** A deterministic stub encoder producing a 3-dim vector from simple text features. */
 export declare const stubEncoder: (texts: string[], _kind: "query" | "document") => Promise<number[][]>;
+/**
+ * A dimension-padding encoder factory: wraps {@link stubEncoder} and zero-extends to `dim`. Used by
+ * backends that enforce a minimum dimension (e.g. Cloudflare Vectorize requires 32–1536).
+ */
 export declare const paddedStubEncoder: (dim: number) => (texts: string[], kind: "query" | "document") => Promise<number[][]>;
+/**
+ * Drive a vector-store adapter through the shared contract suite.
+ *
+ * @remarks
+ * `makeStore` must return an already-connected store whose `'docs'` collection is created at the
+ * matching dimension; it is re-invoked per test so retries are self-contained. `dim` defaults to 3
+ * — pass a larger value for backends with a dimension floor (the harness pads every test vector to
+ * `dim`). `opts.retry` / `opts.timeout` are forwarded to every `it()` (defaults: retry 0, 5s) and
+ * exist for aggressively eventually-consistent managed backends whose read-after-write can flap for
+ * seconds — a retried attempt re-runs `makeStore()` against an index that has had more time to
+ * settle, without weakening any assertion.
+ *
+ * @param label - Human-readable label for the suite (the adapter name).
+ * @param makeStore - Factory returning a fresh, connected store with the `'docs'` collection.
+ * @param dim - Vector dimensionality the harness pads to (default 3).
+ * @param opts - Per-`it` retry/timeout overrides.
+ */
 export declare const runVectorStoreConformance: (label: string, makeStore: () => Promise<CallableVectorStore>, dim?: number, opts?: {
     retry?: number;
     timeout?: number;

package/batteries/vector/conformance.cjs

@@ -10,11 +10,16 @@ let vitest = require("vitest");
 *
 * @module @nhtio/adk/batteries/vector/conformance
 */
+/** A deterministic stub encoder producing a 3-dim vector from simple text features. */
 var stubEncoder = async (texts, _kind) => texts.map((tx) => [
 	tx.length,
 	tx.includes("cat") ? 1 : 0,
 	tx.includes("dog") ? 1 : 0
 ]);
+/**
+* A dimension-padding encoder factory: wraps {@link stubEncoder} and zero-extends to `dim`. Used by
+* backends that enforce a minimum dimension (e.g. Cloudflare Vectorize requires 32–1536).
+*/
 var paddedStubEncoder = (dim) => async (texts, kind) => {
 	return (await stubEncoder(texts, kind)).map((v) => padVector(v, dim));
 };
@@ -23,6 +28,23 @@ var padVector = (v, dim) => {
 	if (v.length > dim) return v.slice(0, dim);
 	return [...v, ...new Array(dim - v.length).fill(0)];
 };
+/**
+* Drive a vector-store adapter through the shared contract suite.
+*
+* @remarks
+* `makeStore` must return an already-connected store whose `'docs'` collection is created at the
+* matching dimension; it is re-invoked per test so retries are self-contained. `dim` defaults to 3
+* — pass a larger value for backends with a dimension floor (the harness pads every test vector to
+* `dim`). `opts.retry` / `opts.timeout` are forwarded to every `it()` (defaults: retry 0, 5s) and
+* exist for aggressively eventually-consistent managed backends whose read-after-write can flap for
+* seconds — a retried attempt re-runs `makeStore()` against an index that has had more time to
+* settle, without weakening any assertion.
+*
+* @param label - Human-readable label for the suite (the adapter name).
+* @param makeStore - Factory returning a fresh, connected store with the `'docs'` collection.
+* @param dim - Vector dimensionality the harness pads to (default 3).
+* @param opts - Per-`it` retry/timeout overrides.
+*/
 var runVectorStoreConformance = (label, makeStore, dim = 3, opts = {}) => {
 	const p = (v) => padVector(v, dim);
 	const io = {

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`) — it imports `vitest`, an\n * optional peer you install to run the suite; it is never pulled in by the battery barrel.\n *\n * @module @nhtio/adk/batteries/vector/conformance\n */\n\nimport { describe, expect, it } from 'vitest'\nimport type { CallableVectorStore } from '../contract'\n\n// A deterministic stub encoder: 3-dim vector from 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// A dimension-padding encoder factory: wraps the 3-feature stub and zero-extends to `dim`.\n// Used by backends that enforce a minimum dimension (e.g. Cloudflare Vectorize requires 32–1536).\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// makeStore: () => Promise<CallableVectorStore> | CallableVectorStore  (already connected +\n// collection 'docs' created with the matching dimension). `dim` defaults to 3 — pass a larger\n// value for backends with a dimension floor (the harness pads every test vector to `dim`, and the\n// store's collection must be created at the same `dim`).\n//\n// `opts.retry` / `opts.timeout` are forwarded to every `it()`. Both default to vitest's defaults\n// (retry 0), so existing callers are unchanged. They exist for aggressively eventually-consistent\n// managed backends (e.g. Cloudflare Vectorize) whose read-after-write can flap for seconds: a\n// retried attempt re-runs `makeStore()` (re-clearing state) against an index that's had more time\n// to settle, turning transient-consistency flake into deterministic green without weakening any\n// assertion. Each `it` re-derives its store via makeStore, so retries are self-contained.\nexport const runVectorStoreConformance = (\n  label: string,\n  makeStore: () => Promise<CallableVectorStore>,\n  dim = 3,\n  opts: { retry?: number; timeout?: number } = {}\n): void => {\n  const p = (v: number[]): number[] => padVector(v, dim)\n  const io = { retry: opts.retry ?? 0, timeout: opts.timeout ?? 5000 }\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}\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`) — it imports `vitest`, an\n * optional peer you install to run the suite; it is never pulled in by the battery barrel.\n *\n * @module @nhtio/adk/batteries/vector/conformance\n */\n\nimport { describe, expect, it } from 'vitest'\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 */\nexport const runVectorStoreConformance = (\n  label: string,\n  makeStore: () => Promise<CallableVectorStore>,\n  dim = 3,\n  opts: { retry?: number; timeout?: number } = {}\n): void => {\n  const p = (v: number[]): number[] => padVector(v, dim)\n  const io = { retry: opts.retry ?? 0, timeout: opts.timeout ?? 5000 }\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}\n"],"mappings":"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"}

package/batteries/vector/conformance.mjs

@@ -8,11 +8,16 @@ import { describe, expect, it } from "vitest";
 *
 * @module @nhtio/adk/batteries/vector/conformance
 */
+/** A deterministic stub encoder producing a 3-dim vector from simple text features. */
 var stubEncoder = async (texts, _kind) => texts.map((tx) => [
 	tx.length,
 	tx.includes("cat") ? 1 : 0,
 	tx.includes("dog") ? 1 : 0
 ]);
+/**
+* A dimension-padding encoder factory: wraps {@link stubEncoder} and zero-extends to `dim`. Used by
+* backends that enforce a minimum dimension (e.g. Cloudflare Vectorize requires 32–1536).
+*/
 var paddedStubEncoder = (dim) => async (texts, kind) => {
 	return (await stubEncoder(texts, kind)).map((v) => padVector(v, dim));
 };
@@ -21,6 +26,23 @@ var padVector = (v, dim) => {
 	if (v.length > dim) return v.slice(0, dim);
 	return [...v, ...new Array(dim - v.length).fill(0)];
 };
+/**
+* Drive a vector-store adapter through the shared contract suite.
+*
+* @remarks
+* `makeStore` must return an already-connected store whose `'docs'` collection is created at the
+* matching dimension; it is re-invoked per test so retries are self-contained. `dim` defaults to 3
+* — pass a larger value for backends with a dimension floor (the harness pads every test vector to
+* `dim`). `opts.retry` / `opts.timeout` are forwarded to every `it()` (defaults: retry 0, 5s) and
+* exist for aggressively eventually-consistent managed backends whose read-after-write can flap for
+* seconds — a retried attempt re-runs `makeStore()` against an index that has had more time to
+* settle, without weakening any assertion.
+*
+* @param label - Human-readable label for the suite (the adapter name).
+* @param makeStore - Factory returning a fresh, connected store with the `'docs'` collection.
+* @param dim - Vector dimensionality the harness pads to (default 3).
+* @param opts - Per-`it` retry/timeout overrides.
+*/
 var runVectorStoreConformance = (label, makeStore, dim = 3, opts = {}) => {
 	const p = (v) => padVector(v, dim);
 	const io = {

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`) — it imports `vitest`, an\n * optional peer you install to run the suite; it is never pulled in by the battery barrel.\n *\n * @module @nhtio/adk/batteries/vector/conformance\n */\n\nimport { describe, expect, it } from 'vitest'\nimport type { CallableVectorStore } from '../contract'\n\n// A deterministic stub encoder: 3-dim vector from 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// A dimension-padding encoder factory: wraps the 3-feature stub and zero-extends to `dim`.\n// Used by backends that enforce a minimum dimension (e.g. Cloudflare Vectorize requires 32–1536).\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// makeStore: () => Promise<CallableVectorStore> | CallableVectorStore  (already connected +\n// collection 'docs' created with the matching dimension). `dim` defaults to 3 — pass a larger\n// value for backends with a dimension floor (the harness pads every test vector to `dim`, and the\n// store's collection must be created at the same `dim`).\n//\n// `opts.retry` / `opts.timeout` are forwarded to every `it()`. Both default to vitest's defaults\n// (retry 0), so existing callers are unchanged. They exist for aggressively eventually-consistent\n// managed backends (e.g. Cloudflare Vectorize) whose read-after-write can flap for seconds: a\n// retried attempt re-runs `makeStore()` (re-clearing state) against an index that's had more time\n// to settle, turning transient-consistency flake into deterministic green without weakening any\n// assertion. Each `it` re-derives its store via makeStore, so retries are self-contained.\nexport const runVectorStoreConformance = (\n  label: string,\n  makeStore: () => Promise<CallableVectorStore>,\n  dim = 3,\n  opts: { retry?: number; timeout?: number } = {}\n): void => {\n  const p = (v: number[]): number[] => padVector(v, dim)\n  const io = { retry: opts.retry ?? 0, timeout: opts.timeout ?? 5000 }\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}\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`) — it imports `vitest`, an\n * optional peer you install to run the suite; it is never pulled in by the battery barrel.\n *\n * @module @nhtio/adk/batteries/vector/conformance\n */\n\nimport { describe, expect, it } from 'vitest'\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 */\nexport const runVectorStoreConformance = (\n  label: string,\n  makeStore: () => Promise<CallableVectorStore>,\n  dim = 3,\n  opts: { retry?: number; timeout?: number } = {}\n): void => {\n  const p = (v: number[]): number[] => padVector(v, dim)\n  const io = { retry: opts.retry ?? 0, timeout: opts.timeout ?? 5000 }\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}\n"],"mappings":"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"}

package/batteries/vector/contract.cjs

@@ -7,25 +7,47 @@ const require_batteries_vector_schema = require("./schema.cjs");
 /**
 * @module @nhtio/adk/batteries/vector/contract
 */
+/**
+* Abstract base shared by every bundled vector adapter. It implements the cross-cutting surface
+* (`query`/`schema`/`transaction`/`asCallable`/`encode`) on top of the small set of backend-specific
+* abstract methods each adapter fills in (`connect`, `executeSearch`, `createCollection`, …). Concrete
+* adapters inherit the doc comments below unless they override them.
+*/
 var BaseVectorStore = class {
+	/** Construction options (connection details and the optional encoder), held for later use. */
 	options;
 	constructor(options) {
 		this.options = options;
 	}
+	/**
+	* Encode text to vectors via the configured encoder. Throws {@link E_VECTOR_STORE_ENCODER_REQUIRED}
+	* when the backend has no built-in encoding and no encoder was supplied.
+	*/
 	async encode(texts, kind) {
 		if (this.capabilities.builtInEncoding) throw new require_batteries_vector_exceptions.E_VECTOR_STORE_ENCODER_REQUIRED(["contract"]);
 		if (!this.options.encoder) throw new require_batteries_vector_exceptions.E_VECTOR_STORE_ENCODER_REQUIRED([this.constructor.name]);
 		return this.options.encoder(texts, kind);
 	}
+	/**
+	* Run `fn` inside a backend transaction. The base implementation rejects with
+	* {@link E_VECTOR_STORE_TRANSACTIONS_UNSUPPORTED}; adapters whose backend supports transactions
+	* override this.
+	*/
 	async transaction(_fn) {
 		throw new require_batteries_vector_exceptions.E_VECTOR_STORE_TRANSACTIONS_UNSUPPORTED([this.constructor.name]);
 	}
+	/** Schema builder bound to this store, for creating/dropping/migrating collections. */
 	get schema() {
 		return new require_batteries_vector_schema.VectorSchemaBuilder(this);
 	}
+	/** Open a {@link VectorQueryBuilder} scoped to `collection` (default top-K of 10). */
 	query(collection) {
 		return new require_batteries_vector_builder.VectorQueryBuilder(this, collection, 10);
 	}
+	/**
+	* Wrap this store in a callable proxy so `store('collection')` is shorthand for
+	* `store.query('collection')`, while all other methods/properties pass through unchanged.
+	*/
 	asCallable() {
 		const self = this;
 		const fn = ((collection) => self.query(collection));