@nhtio/adk 1.20260607.2 → 1.20260609.0

package/batteries/vector/mariadb.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"mariadb.mjs","names":["#opts","#pool","#ensure","#query","#dims","#parseVec","#parseMeta","#project"],"sources":["../../../src/batteries/vector/mariadb/index.ts"],"sourcesContent":["/**\n * @module @nhtio/adk/batteries/vector/mariadb\n *\n * MariaDB adapter (native VECTOR type, 11.7+). Vectors live in a `VECTOR(N)` column written\n * with `VEC_FromText('[...]')` and read with `VEC_ToText(vec)`; KNN uses\n * `VEC_DISTANCE_COSINE` / `VEC_DISTANCE_EUCLIDEAN` ordered ascending. Metadata is a `JSON`\n * column. The neutral filter tree is evaluated with the JS reference evaluator for exact\n * cross-adapter parity. Each collection is a table.\n *\n * Driver: `mariadb` (pure JS, pooled).\n */\n\nimport { evaluateFilter } from '../filters'\nimport { normalizeScore } from '../helpers'\nimport { BaseVectorStore } from '../contract'\nimport { validateRecords } from '../validation'\nimport { isInstanceOf } from '@nhtio/adk/guards'\nimport {\n  E_VECTOR_STORE_DRIVER_UNAVAILABLE,\n  E_VECTOR_STORE_CONNECTION_FAILED,\n  E_VECTOR_STORE_COLLECTION_FAILED,\n  E_VECTOR_STORE_UPSERT_FAILED,\n  E_VECTOR_STORE_SEARCH_FAILED,\n  E_VECTOR_STORE_DELETE_FAILED,\n  E_VECTOR_STORE_DIMENSION_MISMATCH,\n  E_VECTOR_STORE_UNSUPPORTED_OPERATION,\n} from '../exceptions'\nimport type { SearchPlan, UpsertPlan, DeletePlan, CollectionSpec } from '../plan'\nimport type {\n  VectorMatch,\n  VectorStoreCapabilities,\n  BaseVectorStoreOptions,\n  VectorMetadata,\n  DistanceMetric,\n} from '../types'\n\nexport interface MariaDBVectorStoreOptions extends BaseVectorStoreOptions {\n  connection?: {\n    host?: string\n    port?: number\n    user?: string\n    password?: string\n    database?: string\n    connectionLimit?: number\n  }\n}\n\nconst getMariaDB = async () => {\n  try {\n    const mod = await import('mariadb')\n    return (mod as any).default ?? mod\n  } catch {\n    throw new E_VECTOR_STORE_DRIVER_UNAVAILABLE(['mariadb'])\n  }\n}\n\nconst distanceFn = (metric: DistanceMetric): string =>\n  metric === 'euclidean' ? 'VEC_DISTANCE_EUCLIDEAN' : 'VEC_DISTANCE_COSINE'\n\n// Backtick-quoted identifier.\nconst ident = (name: string): string => '`' + name.replace(/`/g, '``') + '`'\n\nexport class MariaDBVectorStore extends BaseVectorStore {\n  readonly capabilities: VectorStoreCapabilities = {\n    transactions: true,\n    namedVectors: false,\n    rename: true,\n    rawSql: true,\n    builtInEncoding: false,\n    // SQL backend, synchronous on commit: a write is visible on resolve. The option is a no-op.\n    consistency: { configurable: false, default: 'strong', modes: ['strong'] },\n  }\n\n  #pool: any | null = null\n  #dims: Map<string, number> = new Map()\n\n  get #opts(): MariaDBVectorStoreOptions {\n    return this.options as MariaDBVectorStoreOptions\n  }\n\n  static isAvailable(): boolean {\n    return typeof process !== 'undefined'\n  }\n  isAvailable(): boolean {\n    return typeof process !== 'undefined'\n  }\n\n  async connect(): Promise<void> {\n    if (this.#pool) return\n    const mariadb = await getMariaDB()\n    const c = this.#opts.connection || {}\n    try {\n      this.#pool = mariadb.createPool({\n        host: c.host ?? 'localhost',\n        port: c.port ?? 3306,\n        user: c.user ?? 'root',\n        password: c.password,\n        database: c.database,\n        connectionLimit: c.connectionLimit ?? 4,\n      })\n    } catch (err) {\n      throw new E_VECTOR_STORE_CONNECTION_FAILED([String(err)])\n    }\n  }\n\n  async close(): Promise<void> {\n    if (this.#pool) {\n      await this.#pool.end()\n      this.#pool = null\n    }\n  }\n\n  async #ensure(): Promise<any> {\n    if (!this.#pool) await this.connect()\n    return this.#pool!\n  }\n\n  async #query(sql: string, params?: unknown[]): Promise<any[]> {\n    const pool = await this.#ensure()\n    return await pool.query(sql, params)\n  }\n\n  // VEC_ToText returns \"[1,0,0]\"; parse into number[].\n  #parseVec(text: unknown): number[] {\n    if (typeof text !== 'string') return []\n    try {\n      return JSON.parse(text) as number[]\n    } catch {\n      return []\n    }\n  }\n\n  #parseMeta(val: unknown): VectorMetadata {\n    if (val === null || val === undefined) return {}\n    if (typeof val === 'string') {\n      try {\n        return JSON.parse(val) as VectorMetadata\n      } catch {\n        return {}\n      }\n    }\n    if (typeof val === 'object') return val as VectorMetadata\n    return {}\n  }\n\n  async createCollection(spec: CollectionSpec, ifNotExists: boolean): Promise<void> {\n    this.#dims.set(spec.collection, spec.vector.dimensions)\n    const ine = ifNotExists ? 'IF NOT EXISTS ' : ''\n    try {\n      await this.#query(\n        `CREATE TABLE ${ine}${ident(spec.collection)} (` +\n          `id VARCHAR(255) PRIMARY KEY, ` +\n          `vec VECTOR(${spec.vector.dimensions}) NOT NULL, ` +\n          `document TEXT, ` +\n          `metadata JSON, ` +\n          `VECTOR INDEX (vec))`\n      )\n    } catch (err) {\n      throw new E_VECTOR_STORE_COLLECTION_FAILED(['createCollection', String(err)])\n    }\n  }\n\n  async dropCollection(collection: string, ifExists: boolean): Promise<void> {\n    const ie = ifExists ? 'IF EXISTS ' : ''\n    try {\n      await this.#query(`DROP TABLE ${ie}${ident(collection)}`)\n      this.#dims.delete(collection)\n    } catch (err) {\n      throw new E_VECTOR_STORE_COLLECTION_FAILED(['dropCollection', String(err)])\n    }\n  }\n\n  async hasCollection(collection: string): Promise<boolean> {\n    const rows = await this.#query(\n      `SELECT 1 FROM information_schema.tables WHERE table_schema = DATABASE() AND table_name = ?`,\n      [collection]\n    )\n    return rows.length > 0\n  }\n\n  async renameCollection(from: string, to: string): Promise<void> {\n    try {\n      await this.#query(`RENAME TABLE ${ident(from)} TO ${ident(to)}`)\n      const d = this.#dims.get(from)\n      if (d !== undefined) {\n        this.#dims.set(to, d)\n        this.#dims.delete(from)\n      }\n    } catch (err) {\n      throw new E_VECTOR_STORE_UNSUPPORTED_OPERATION(['renameCollection', String(err)])\n    }\n  }\n\n  async executeUpsert(plan: UpsertPlan): Promise<void> {\n    if (plan.records.length === 0) return\n    validateRecords(plan.records)\n    const expected = this.#opts.dimensions ?? this.#dims.get(plan.collection)\n    try {\n      for (const r of plan.records) {\n        let vector = r.vector\n        if (!vector && r.document) {\n          const [v] = await this.encode([r.document], 'document')\n          vector = v\n        }\n        if (!vector) {\n          throw new E_VECTOR_STORE_UPSERT_FAILED(['Record missing vector and document'])\n        }\n        if (expected !== undefined && vector.length !== expected) {\n          throw new E_VECTOR_STORE_DIMENSION_MISMATCH([expected, vector.length])\n        }\n        const vecText = `[${vector.join(',')}]`\n        const meta = r.metadata ? JSON.stringify(r.metadata) : '{}'\n        await this.#query(\n          `INSERT INTO ${ident(plan.collection)} (id, vec, document, metadata) ` +\n            `VALUES (?, VEC_FromText(?), ?, ?) ` +\n            `ON DUPLICATE KEY UPDATE vec = VEC_FromText(?), document = ?, metadata = ?`,\n          [r.id, vecText, r.document ?? '', meta, vecText, r.document ?? '', meta]\n        )\n      }\n    } catch (err) {\n      if (\n        isInstanceOf(err, 'E_VECTOR_STORE_DIMENSION_MISMATCH', E_VECTOR_STORE_DIMENSION_MISMATCH) ||\n        isInstanceOf(err, 'E_VECTOR_STORE_UPSERT_FAILED', E_VECTOR_STORE_UPSERT_FAILED)\n      ) {\n        throw err\n      }\n      throw new E_VECTOR_STORE_UPSERT_FAILED([String(err)])\n    }\n  }\n\n  async executeSearch(plan: SearchPlan): Promise<VectorMatch[]> {\n    const metric = this.#opts.metric ?? 'cosine'\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        const rows = await this.#query(\n          `SELECT VEC_ToText(vec) vec FROM ${ident(plan.collection)} WHERE id = ?`,\n          [plan.near.id]\n        )\n        if (rows.length === 0) {\n          throw new E_VECTOR_STORE_SEARCH_FAILED(['Referenced id not found: ' + plan.near.id])\n        }\n        queryVector = this.#parseVec(rows[0].vec)\n      }\n    }\n\n    const offset = plan.offset ?? 0\n    try {\n      if (queryVector) {\n        const fn = distanceFn(metric)\n        const vecText = `[${queryVector.join(',')}]`\n        const rows = await this.#query(\n          `SELECT id, VEC_ToText(vec) vec, document, metadata, ` +\n            `${fn}(vec, VEC_FromText(?)) __dist FROM ${ident(plan.collection)}`,\n          [vecText]\n        )\n        const filtered = plan.filter\n          ? rows.filter((row) => evaluateFilter(plan.filter!, this.#parseMeta(row.metadata)))\n          : rows\n        filtered.sort((a, b) => Number(a.__dist) - Number(b.__dist))\n        return filtered\n          .slice(offset, offset + plan.topK)\n          .map((row) => this.#project(row, plan, metric, true))\n      } else {\n        const rows = await this.#query(\n          `SELECT id, VEC_ToText(vec) vec, document, metadata FROM ${ident(plan.collection)}`\n        )\n        const filtered = plan.filter\n          ? rows.filter((row) => evaluateFilter(plan.filter!, this.#parseMeta(row.metadata)))\n          : rows\n        return filtered\n          .slice(offset, offset + plan.topK)\n          .map((row) => this.#project(row, plan, metric, false))\n      }\n    } catch (err) {\n      throw new E_VECTOR_STORE_SEARCH_FAILED([String(err)])\n    }\n  }\n\n  #project(row: any, plan: SearchPlan, metric: string, isKnn: boolean): VectorMatch {\n    const proj = plan.projection\n    const out: VectorMatch = {}\n    if (proj.id) out.id = row.id as string\n    if (proj.vector) out.vector = this.#parseVec(row.vec)\n    if (proj.document) out.document = (row.document ?? undefined) as string | undefined\n    if (proj.metadata) out.metadata = this.#parseMeta(row.metadata)\n    if (isKnn && row.__dist !== undefined && row.__dist !== null) {\n      out.score = normalizeScore(Number(row.__dist), metric as DistanceMetric, 'distance')\n    }\n    return out\n  }\n\n  async executeDelete(plan: DeletePlan): Promise<void> {\n    try {\n      if (plan.ids && plan.ids.length > 0) {\n        const placeholders = plan.ids.map(() => '?').join(', ')\n        await this.#query(\n          `DELETE FROM ${ident(plan.collection)} WHERE id IN (${placeholders})`,\n          plan.ids\n        )\n      } else if (plan.filter) {\n        const rows = await this.#query(`SELECT id, metadata FROM ${ident(plan.collection)}`)\n        const targets = rows\n          .filter((row) => evaluateFilter(plan.filter!, this.#parseMeta(row.metadata)))\n          .map((row) => row.id as string)\n        if (targets.length > 0) {\n          const placeholders = targets.map(() => '?').join(', ')\n          await this.#query(\n            `DELETE FROM ${ident(plan.collection)} WHERE id IN (${placeholders})`,\n            targets\n          )\n        }\n      } else {\n        await this.#query(`DELETE FROM ${ident(plan.collection)}`)\n      }\n    } catch (err) {\n      throw new E_VECTOR_STORE_DELETE_FAILED([String(err)])\n    }\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"mariadb.mjs","names":["#opts","#pool","#ensure","#query","#dims","#parseVec","#parseMeta","#project"],"sources":["../../../src/batteries/vector/mariadb/index.ts"],"sourcesContent":["/**\n * @module @nhtio/adk/batteries/vector/mariadb\n *\n * MariaDB adapter (native VECTOR type, 11.7+). Vectors live in a `VECTOR(N)` column written\n * with `VEC_FromText('[...]')` and read with `VEC_ToText(vec)`; KNN uses\n * `VEC_DISTANCE_COSINE` / `VEC_DISTANCE_EUCLIDEAN` ordered ascending. Metadata is a `JSON`\n * column. The neutral filter tree is evaluated with the JS reference evaluator for exact\n * cross-adapter parity. Each collection is a table.\n *\n * Driver: `mariadb` (pure JS, pooled).\n */\n\nimport { evaluateFilter } from '../filters'\nimport { normalizeScore } from '../helpers'\nimport { BaseVectorStore } from '../contract'\nimport { validateRecords } from '../validation'\nimport { isInstanceOf } from '@nhtio/adk/guards'\nimport {\n  E_VECTOR_STORE_DRIVER_UNAVAILABLE,\n  E_VECTOR_STORE_CONNECTION_FAILED,\n  E_VECTOR_STORE_COLLECTION_FAILED,\n  E_VECTOR_STORE_UPSERT_FAILED,\n  E_VECTOR_STORE_SEARCH_FAILED,\n  E_VECTOR_STORE_DELETE_FAILED,\n  E_VECTOR_STORE_DIMENSION_MISMATCH,\n  E_VECTOR_STORE_UNSUPPORTED_OPERATION,\n} from '../exceptions'\nimport type { SearchPlan, UpsertPlan, DeletePlan, CollectionSpec } from '../plan'\nimport type {\n  VectorMatch,\n  VectorStoreCapabilities,\n  BaseVectorStoreOptions,\n  VectorMetadata,\n  DistanceMetric,\n} from '../types'\n\nexport interface MariaDBVectorStoreOptions extends BaseVectorStoreOptions {\n  /** Connection and authentication parameters for the backend. */\n  connection?: {\n    host?: string\n    port?: number\n    user?: string\n    password?: string\n    database?: string\n    connectionLimit?: number\n  }\n}\n\nconst getMariaDB = async () => {\n  try {\n    const mod = await import('mariadb')\n    return (mod as any).default ?? mod\n  } catch {\n    throw new E_VECTOR_STORE_DRIVER_UNAVAILABLE(['mariadb'])\n  }\n}\n\nconst distanceFn = (metric: DistanceMetric): string =>\n  metric === 'euclidean' ? 'VEC_DISTANCE_EUCLIDEAN' : 'VEC_DISTANCE_COSINE'\n\n// Backtick-quoted identifier.\nconst ident = (name: string): string => '`' + name.replace(/`/g, '``') + '`'\n\nexport class MariaDBVectorStore extends BaseVectorStore {\n  readonly capabilities: VectorStoreCapabilities = {\n    transactions: true,\n    namedVectors: false,\n    rename: true,\n    rawSql: true,\n    builtInEncoding: false,\n    // SQL backend, synchronous on commit: a write is visible on resolve. The option is a no-op.\n    consistency: { configurable: false, default: 'strong', modes: ['strong'] },\n  }\n\n  #pool: any | null = null\n  #dims: Map<string, number> = new Map()\n\n  get #opts(): MariaDBVectorStoreOptions {\n    return this.options as MariaDBVectorStoreOptions\n  }\n\n  /** Static availability probe: whether this adapter's runtime driver can load in the current environment. */\n  static isAvailable(): boolean {\n    return typeof process !== 'undefined'\n  }\n  isAvailable(): boolean {\n    return typeof process !== 'undefined'\n  }\n\n  async connect(): Promise<void> {\n    if (this.#pool) return\n    const mariadb = await getMariaDB()\n    const c = this.#opts.connection || {}\n    try {\n      this.#pool = mariadb.createPool({\n        host: c.host ?? 'localhost',\n        port: c.port ?? 3306,\n        user: c.user ?? 'root',\n        password: c.password,\n        database: c.database,\n        connectionLimit: c.connectionLimit ?? 4,\n      })\n    } catch (err) {\n      throw new E_VECTOR_STORE_CONNECTION_FAILED([String(err)])\n    }\n  }\n\n  async close(): Promise<void> {\n    if (this.#pool) {\n      await this.#pool.end()\n      this.#pool = null\n    }\n  }\n\n  async #ensure(): Promise<any> {\n    if (!this.#pool) await this.connect()\n    return this.#pool!\n  }\n\n  async #query(sql: string, params?: unknown[]): Promise<any[]> {\n    const pool = await this.#ensure()\n    return await pool.query(sql, params)\n  }\n\n  // VEC_ToText returns \"[1,0,0]\"; parse into number[].\n  #parseVec(text: unknown): number[] {\n    if (typeof text !== 'string') return []\n    try {\n      return JSON.parse(text) as number[]\n    } catch {\n      return []\n    }\n  }\n\n  #parseMeta(val: unknown): VectorMetadata {\n    if (val === null || val === undefined) return {}\n    if (typeof val === 'string') {\n      try {\n        return JSON.parse(val) as VectorMetadata\n      } catch {\n        return {}\n      }\n    }\n    if (typeof val === 'object') return val as VectorMetadata\n    return {}\n  }\n\n  async createCollection(spec: CollectionSpec, ifNotExists: boolean): Promise<void> {\n    this.#dims.set(spec.collection, spec.vector.dimensions)\n    const ine = ifNotExists ? 'IF NOT EXISTS ' : ''\n    try {\n      await this.#query(\n        `CREATE TABLE ${ine}${ident(spec.collection)} (` +\n          `id VARCHAR(255) PRIMARY KEY, ` +\n          `vec VECTOR(${spec.vector.dimensions}) NOT NULL, ` +\n          `document TEXT, ` +\n          `metadata JSON, ` +\n          `VECTOR INDEX (vec))`\n      )\n    } catch (err) {\n      throw new E_VECTOR_STORE_COLLECTION_FAILED(['createCollection', String(err)])\n    }\n  }\n\n  async dropCollection(collection: string, ifExists: boolean): Promise<void> {\n    const ie = ifExists ? 'IF EXISTS ' : ''\n    try {\n      await this.#query(`DROP TABLE ${ie}${ident(collection)}`)\n      this.#dims.delete(collection)\n    } catch (err) {\n      throw new E_VECTOR_STORE_COLLECTION_FAILED(['dropCollection', String(err)])\n    }\n  }\n\n  async hasCollection(collection: string): Promise<boolean> {\n    const rows = await this.#query(\n      `SELECT 1 FROM information_schema.tables WHERE table_schema = DATABASE() AND table_name = ?`,\n      [collection]\n    )\n    return rows.length > 0\n  }\n\n  async renameCollection(from: string, to: string): Promise<void> {\n    try {\n      await this.#query(`RENAME TABLE ${ident(from)} TO ${ident(to)}`)\n      const d = this.#dims.get(from)\n      if (d !== undefined) {\n        this.#dims.set(to, d)\n        this.#dims.delete(from)\n      }\n    } catch (err) {\n      throw new E_VECTOR_STORE_UNSUPPORTED_OPERATION(['renameCollection', String(err)])\n    }\n  }\n\n  async executeUpsert(plan: UpsertPlan): Promise<void> {\n    if (plan.records.length === 0) return\n    validateRecords(plan.records)\n    const expected = this.#opts.dimensions ?? this.#dims.get(plan.collection)\n    try {\n      for (const r of plan.records) {\n        let vector = r.vector\n        if (!vector && r.document) {\n          const [v] = await this.encode([r.document], 'document')\n          vector = v\n        }\n        if (!vector) {\n          throw new E_VECTOR_STORE_UPSERT_FAILED(['Record missing vector and document'])\n        }\n        if (expected !== undefined && vector.length !== expected) {\n          throw new E_VECTOR_STORE_DIMENSION_MISMATCH([expected, vector.length])\n        }\n        const vecText = `[${vector.join(',')}]`\n        const meta = r.metadata ? JSON.stringify(r.metadata) : '{}'\n        await this.#query(\n          `INSERT INTO ${ident(plan.collection)} (id, vec, document, metadata) ` +\n            `VALUES (?, VEC_FromText(?), ?, ?) ` +\n            `ON DUPLICATE KEY UPDATE vec = VEC_FromText(?), document = ?, metadata = ?`,\n          [r.id, vecText, r.document ?? '', meta, vecText, r.document ?? '', meta]\n        )\n      }\n    } catch (err) {\n      if (\n        isInstanceOf(err, 'E_VECTOR_STORE_DIMENSION_MISMATCH', E_VECTOR_STORE_DIMENSION_MISMATCH) ||\n        isInstanceOf(err, 'E_VECTOR_STORE_UPSERT_FAILED', E_VECTOR_STORE_UPSERT_FAILED)\n      ) {\n        throw err\n      }\n      throw new E_VECTOR_STORE_UPSERT_FAILED([String(err)])\n    }\n  }\n\n  async executeSearch(plan: SearchPlan): Promise<VectorMatch[]> {\n    const metric = this.#opts.metric ?? 'cosine'\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        const rows = await this.#query(\n          `SELECT VEC_ToText(vec) vec FROM ${ident(plan.collection)} WHERE id = ?`,\n          [plan.near.id]\n        )\n        if (rows.length === 0) {\n          throw new E_VECTOR_STORE_SEARCH_FAILED(['Referenced id not found: ' + plan.near.id])\n        }\n        queryVector = this.#parseVec(rows[0].vec)\n      }\n    }\n\n    const offset = plan.offset ?? 0\n    try {\n      if (queryVector) {\n        const fn = distanceFn(metric)\n        const vecText = `[${queryVector.join(',')}]`\n        const rows = await this.#query(\n          `SELECT id, VEC_ToText(vec) vec, document, metadata, ` +\n            `${fn}(vec, VEC_FromText(?)) __dist FROM ${ident(plan.collection)}`,\n          [vecText]\n        )\n        const filtered = plan.filter\n          ? rows.filter((row) => evaluateFilter(plan.filter!, this.#parseMeta(row.metadata)))\n          : rows\n        filtered.sort((a, b) => Number(a.__dist) - Number(b.__dist))\n        return filtered\n          .slice(offset, offset + plan.topK)\n          .map((row) => this.#project(row, plan, metric, true))\n      } else {\n        const rows = await this.#query(\n          `SELECT id, VEC_ToText(vec) vec, document, metadata FROM ${ident(plan.collection)}`\n        )\n        const filtered = plan.filter\n          ? rows.filter((row) => evaluateFilter(plan.filter!, this.#parseMeta(row.metadata)))\n          : rows\n        return filtered\n          .slice(offset, offset + plan.topK)\n          .map((row) => this.#project(row, plan, metric, false))\n      }\n    } catch (err) {\n      throw new E_VECTOR_STORE_SEARCH_FAILED([String(err)])\n    }\n  }\n\n  #project(row: any, plan: SearchPlan, metric: string, isKnn: boolean): VectorMatch {\n    const proj = plan.projection\n    const out: VectorMatch = {}\n    if (proj.id) out.id = row.id as string\n    if (proj.vector) out.vector = this.#parseVec(row.vec)\n    if (proj.document) out.document = (row.document ?? undefined) as string | undefined\n    if (proj.metadata) out.metadata = this.#parseMeta(row.metadata)\n    if (isKnn && row.__dist !== undefined && row.__dist !== null) {\n      out.score = normalizeScore(Number(row.__dist), metric as DistanceMetric, 'distance')\n    }\n    return out\n  }\n\n  async executeDelete(plan: DeletePlan): Promise<void> {\n    try {\n      if (plan.ids && plan.ids.length > 0) {\n        const placeholders = plan.ids.map(() => '?').join(', ')\n        await this.#query(\n          `DELETE FROM ${ident(plan.collection)} WHERE id IN (${placeholders})`,\n          plan.ids\n        )\n      } else if (plan.filter) {\n        const rows = await this.#query(`SELECT id, metadata FROM ${ident(plan.collection)}`)\n        const targets = rows\n          .filter((row) => evaluateFilter(plan.filter!, this.#parseMeta(row.metadata)))\n          .map((row) => row.id as string)\n        if (targets.length > 0) {\n          const placeholders = targets.map(() => '?').join(', ')\n          await this.#query(\n            `DELETE FROM ${ident(plan.collection)} WHERE id IN (${placeholders})`,\n            targets\n          )\n        }\n      } else {\n        await this.#query(`DELETE FROM ${ident(plan.collection)}`)\n      }\n    } catch (err) {\n      throw new E_VECTOR_STORE_DELETE_FAILED([String(err)])\n    }\n  }\n}\n"],"mappings":"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"}

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

@@ -14,6 +14,7 @@ import { BaseVectorStore } from "../contract";
 import type { SearchPlan, UpsertPlan, DeletePlan, CollectionSpec } from "../plan";
 import type { VectorMatch, VectorStoreCapabilities, BaseVectorStoreOptions } from "../types";
 export interface MeilisearchVectorStoreOptions extends BaseVectorStoreOptions {
+    /** Connection and authentication parameters for the backend. */
     connection?: {
         host?: string;
         apiKey?: string;
@@ -22,6 +23,7 @@ export interface MeilisearchVectorStoreOptions extends BaseVectorStoreOptions {
 export declare class MeilisearchVectorStore extends BaseVectorStore {
     #private;
     readonly capabilities: VectorStoreCapabilities;
+    /** Static availability probe: whether this adapter's runtime driver can load in the current environment. */
     static isAvailable(): boolean;
     isAvailable(): boolean;
     connect(): Promise<void>;

package/batteries/vector/meilisearch.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 require("../../chunk-Ble4zEEl.js");
-const require_tool_registry = require("../../tool_registry-DYUYqXvo.js");
+const require_tool_registry = require("../../tool_registry-CKJPze3j.js");
 require("../../guards.cjs");
 const require_batteries_vector_filters = require("./filters.cjs");
 const require_batteries_vector_exceptions = require("./exceptions.cjs");
@@ -45,6 +45,7 @@ var MeilisearchVectorStore = class extends require_batteries_vector_contract.Bas
 	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";
 	}

package/batteries/vector/meilisearch.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"meilisearch.cjs","names":["#opts","#client","#ensure","#wait","#dims","#unwrapVector","#project","#parseMeta"],"sources":["../../../src/batteries/vector/meilisearch/index.ts"],"sourcesContent":["/**\n * @module @nhtio/adk/batteries/vector/meilisearch\n *\n * Meilisearch adapter. Each collection is a Meilisearch index with a `userProvided` embedder\n * (BYO vectors under `_vectors.<embedder>`); KNN uses semantic search (`vector` +\n * `hybrid.semanticRatio = 1`). Metadata is stored as a JSON string field and filtered with the\n * neutral filter tree's JS reference evaluator for exact cross-adapter parity. Meilisearch\n * returns `_rankingScore` already normalized to [0,1] (higher = closer).\n *\n * Requires the `vectorStore` experimental feature, which the adapter enables on connect.\n * Driver: `meilisearch` (pure JS).\n */\n\nimport { evaluateFilter } from '../filters'\nimport { BaseVectorStore } from '../contract'\nimport { validateRecords } from '../validation'\nimport { isInstanceOf } from '@nhtio/adk/guards'\nimport {\n  E_VECTOR_STORE_DRIVER_UNAVAILABLE,\n  E_VECTOR_STORE_CONNECTION_FAILED,\n  E_VECTOR_STORE_COLLECTION_FAILED,\n  E_VECTOR_STORE_UPSERT_FAILED,\n  E_VECTOR_STORE_SEARCH_FAILED,\n  E_VECTOR_STORE_DELETE_FAILED,\n  E_VECTOR_STORE_DIMENSION_MISMATCH,\n  E_VECTOR_STORE_UNSUPPORTED_OPERATION,\n} from '../exceptions'\nimport type { SearchPlan, UpsertPlan, DeletePlan, CollectionSpec } from '../plan'\nimport type {\n  VectorMatch,\n  VectorStoreCapabilities,\n  BaseVectorStoreOptions,\n  VectorMetadata,\n} from '../types'\n\nconst EMBEDDER = 'default'\n\nexport interface MeilisearchVectorStoreOptions extends BaseVectorStoreOptions {\n  connection?: { host?: string; apiKey?: string }\n}\n\nconst getMeilisearch = async () => {\n  try {\n    const mod = await import('meilisearch')\n    return mod.Meilisearch\n  } catch {\n    throw new E_VECTOR_STORE_DRIVER_UNAVAILABLE(['meilisearch'])\n  }\n}\n\nexport class MeilisearchVectorStore extends BaseVectorStore {\n  readonly capabilities: VectorStoreCapabilities = {\n    transactions: false,\n    namedVectors: false,\n    rename: false,\n    rawSql: false,\n    builtInEncoding: false,\n    // Writes are awaited to task completion (waitForTask) before resolving — strongly\n    // consistent for the next search. The option is a no-op.\n    consistency: { configurable: false, default: 'strong', modes: ['strong'] },\n  }\n\n  #client: any | null = null\n  #dims: Map<string, number> = new Map()\n\n  get #opts(): MeilisearchVectorStoreOptions {\n    return this.options as MeilisearchVectorStoreOptions\n  }\n\n  static isAvailable(): boolean {\n    return typeof process !== 'undefined'\n  }\n  isAvailable(): boolean {\n    return typeof process !== 'undefined'\n  }\n\n  async connect(): Promise<void> {\n    if (this.#client) return\n    const Meilisearch = await getMeilisearch()\n    const c = this.#opts.connection || {}\n    const host = c.host ?? 'http://localhost:7700'\n    try {\n      this.#client = new Meilisearch({ host, apiKey: c.apiKey })\n      // Enable the vector store experimental feature (no-op / stable on newer versions).\n      await fetch(`${host.replace(/\\/$/, '')}/experimental-features`, {\n        method: 'PATCH',\n        headers: {\n          'Content-Type': 'application/json',\n          ...(c.apiKey ? { Authorization: `Bearer ${c.apiKey}` } : {}),\n        },\n        body: JSON.stringify({ vectorStore: true }),\n      }).catch(() => undefined)\n    } catch (err) {\n      throw new E_VECTOR_STORE_CONNECTION_FAILED([String(err)])\n    }\n  }\n\n  async close(): Promise<void> {\n    this.#client = null\n  }\n\n  async #ensure(): Promise<any> {\n    if (!this.#client) await this.connect()\n    return this.#client!\n  }\n\n  async #wait(task: any): Promise<void> {\n    const uid = task?.taskUid ?? task?.uid\n    if (uid === undefined) return\n    await this.#client.tasks.waitForTask(uid)\n  }\n\n  async createCollection(spec: CollectionSpec, ifNotExists: boolean): Promise<void> {\n    const client = await this.#ensure()\n    this.#dims.set(spec.collection, spec.vector.dimensions)\n    if (ifNotExists && (await this.hasCollection(spec.collection))) return\n    try {\n      await this.#wait(await client.createIndex(spec.collection, { primaryKey: 'id' }))\n      const idx = client.index(spec.collection)\n      await this.#wait(\n        await idx.updateEmbedders({\n          [EMBEDDER]: { source: 'userProvided', dimensions: spec.vector.dimensions },\n        })\n      )\n    } catch (err) {\n      throw new E_VECTOR_STORE_COLLECTION_FAILED(['createCollection', String(err)])\n    }\n  }\n\n  async dropCollection(collection: string, ifExists: boolean): Promise<void> {\n    const client = await this.#ensure()\n    if (ifExists && !(await this.hasCollection(collection))) return\n    try {\n      await this.#wait(await client.deleteIndex(collection))\n      this.#dims.delete(collection)\n    } catch (err) {\n      throw new E_VECTOR_STORE_COLLECTION_FAILED(['dropCollection', String(err)])\n    }\n  }\n\n  async hasCollection(collection: string): Promise<boolean> {\n    const client = await this.#ensure()\n    try {\n      await client.index(collection).getRawInfo()\n      return true\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', 'meilisearch'])\n  }\n\n  async executeUpsert(plan: UpsertPlan): Promise<void> {\n    if (plan.records.length === 0) return\n    validateRecords(plan.records)\n    const client = await this.#ensure()\n    const expected = this.#opts.dimensions ?? this.#dims.get(plan.collection)\n    try {\n      const docs: any[] = []\n      for (const r of plan.records) {\n        let vector = r.vector\n        if (!vector && r.document) {\n          const [v] = await this.encode([r.document], 'document')\n          vector = v\n        }\n        if (!vector) {\n          throw new E_VECTOR_STORE_UPSERT_FAILED(['Record missing vector and document'])\n        }\n        if (expected !== undefined && vector.length !== expected) {\n          throw new E_VECTOR_STORE_DIMENSION_MISMATCH([expected, vector.length])\n        }\n        docs.push({\n          id: r.id,\n          document: r.document ?? '',\n          metadata: r.metadata ? JSON.stringify(r.metadata) : '{}',\n          _vectors: { [EMBEDDER]: vector },\n        })\n      }\n      await this.#wait(await client.index(plan.collection).addDocuments(docs))\n    } catch (err) {\n      if (\n        isInstanceOf(err, 'E_VECTOR_STORE_DIMENSION_MISMATCH', E_VECTOR_STORE_DIMENSION_MISMATCH) ||\n        isInstanceOf(err, 'E_VECTOR_STORE_UPSERT_FAILED', E_VECTOR_STORE_UPSERT_FAILED)\n      ) {\n        throw err\n      }\n      throw new E_VECTOR_STORE_UPSERT_FAILED([String(err)])\n    }\n  }\n\n  async executeSearch(plan: SearchPlan): Promise<VectorMatch[]> {\n    const client = await this.#ensure()\n    const idx = client.index(plan.collection)\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 doc = await idx.getDocument(plan.near.id, { retrieveVectors: true })\n          queryVector = this.#unwrapVector(doc?._vectors?.[EMBEDDER])\n        } catch {\n          queryVector = undefined\n        }\n        if (!queryVector) {\n          throw new E_VECTOR_STORE_SEARCH_FAILED(['Referenced id not found: ' + plan.near.id])\n        }\n      }\n    }\n\n    const offset = plan.offset ?? 0\n    try {\n      const over = plan.filter ? 250 : plan.topK + offset\n      let hits: any[]\n      if (queryVector) {\n        const res = await idx.search('', {\n          vector: queryVector,\n          hybrid: { embedder: EMBEDDER, semanticRatio: 1.0 },\n          limit: Math.max(over, plan.topK + offset),\n          showRankingScore: true,\n          retrieveVectors: true,\n        })\n        hits = res.hits ?? []\n      } else {\n        const res = await idx.search('', {\n          limit: Math.max(over, plan.topK + offset),\n          retrieveVectors: true,\n        })\n        hits = res.hits ?? []\n      }\n      const mapped = hits.map((hit) => ({\n        match: this.#project(hit, plan, !!queryVector),\n        meta: this.#parseMeta(hit.metadata),\n      }))\n      const filtered = plan.filter\n        ? mapped.filter((m) => evaluateFilter(plan.filter!, m.meta))\n        : mapped\n      return filtered.slice(offset, offset + plan.topK).map((m) => m.match)\n    } catch (err) {\n      throw new E_VECTOR_STORE_SEARCH_FAILED([String(err)])\n    }\n  }\n\n  #unwrapVector(v: unknown): number[] | undefined {\n    // Meilisearch returns _vectors.default as { embeddings: number[][] } or number[][] or number[].\n    if (!v) return undefined\n    if (Array.isArray(v)) {\n      return Array.isArray(v[0]) ? (v[0] as number[]) : (v as number[])\n    }\n    const emb = (v as any).embeddings\n    if (Array.isArray(emb)) return Array.isArray(emb[0]) ? (emb[0] as number[]) : (emb as number[])\n    return undefined\n  }\n\n  #parseMeta(val: unknown): VectorMetadata {\n    if (typeof val === 'string') {\n      try {\n        return JSON.parse(val) as VectorMetadata\n      } catch {\n        return {}\n      }\n    }\n    if (val && typeof val === 'object') return val as VectorMetadata\n    return {}\n  }\n\n  #project(hit: any, plan: SearchPlan, isKnn: boolean): VectorMatch {\n    const proj = plan.projection\n    const out: VectorMatch = {}\n    if (proj.id) out.id = hit.id as string\n    if (proj.vector) {\n      const v = this.#unwrapVector(hit._vectors?.[EMBEDDER])\n      if (v) out.vector = v\n    }\n    if (proj.document) out.document = (hit.document ?? undefined) as string | undefined\n    if (proj.metadata) out.metadata = this.#parseMeta(hit.metadata)\n    if (isKnn && typeof hit._rankingScore === 'number') {\n      // Meilisearch _rankingScore is already in [0,1], higher = closer.\n      out.score = hit._rankingScore\n    }\n    return out\n  }\n\n  async executeDelete(plan: DeletePlan): Promise<void> {\n    const client = await this.#ensure()\n    const idx = client.index(plan.collection)\n    try {\n      if (plan.ids && plan.ids.length > 0) {\n        await this.#wait(await idx.deleteDocuments(plan.ids))\n      } else if (plan.filter) {\n        // Resolve ids via a scan + JS evaluator, then delete by id.\n        const res = await idx.search('', { limit: 1000 })\n        const targets = (res.hits ?? [])\n          .filter((hit: any) => evaluateFilter(plan.filter!, this.#parseMeta(hit.metadata)))\n          .map((hit: any) => hit.id as string)\n        if (targets.length > 0) await this.#wait(await idx.deleteDocuments(targets))\n      } else {\n        await this.#wait(await idx.deleteAllDocuments())\n      }\n    } catch (err) {\n      throw new E_VECTOR_STORE_DELETE_FAILED([String(err)])\n    }\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"meilisearch.cjs","names":["#opts","#client","#ensure","#wait","#dims","#unwrapVector","#project","#parseMeta"],"sources":["../../../src/batteries/vector/meilisearch/index.ts"],"sourcesContent":["/**\n * @module @nhtio/adk/batteries/vector/meilisearch\n *\n * Meilisearch adapter. Each collection is a Meilisearch index with a `userProvided` embedder\n * (BYO vectors under `_vectors.<embedder>`); KNN uses semantic search (`vector` +\n * `hybrid.semanticRatio = 1`). Metadata is stored as a JSON string field and filtered with the\n * neutral filter tree's JS reference evaluator for exact cross-adapter parity. Meilisearch\n * returns `_rankingScore` already normalized to [0,1] (higher = closer).\n *\n * Requires the `vectorStore` experimental feature, which the adapter enables on connect.\n * Driver: `meilisearch` (pure JS).\n */\n\nimport { evaluateFilter } from '../filters'\nimport { BaseVectorStore } from '../contract'\nimport { validateRecords } from '../validation'\nimport { isInstanceOf } from '@nhtio/adk/guards'\nimport {\n  E_VECTOR_STORE_DRIVER_UNAVAILABLE,\n  E_VECTOR_STORE_CONNECTION_FAILED,\n  E_VECTOR_STORE_COLLECTION_FAILED,\n  E_VECTOR_STORE_UPSERT_FAILED,\n  E_VECTOR_STORE_SEARCH_FAILED,\n  E_VECTOR_STORE_DELETE_FAILED,\n  E_VECTOR_STORE_DIMENSION_MISMATCH,\n  E_VECTOR_STORE_UNSUPPORTED_OPERATION,\n} from '../exceptions'\nimport type { SearchPlan, UpsertPlan, DeletePlan, CollectionSpec } from '../plan'\nimport type {\n  VectorMatch,\n  VectorStoreCapabilities,\n  BaseVectorStoreOptions,\n  VectorMetadata,\n} from '../types'\n\nconst EMBEDDER = 'default'\n\nexport interface MeilisearchVectorStoreOptions extends BaseVectorStoreOptions {\n  /** Connection and authentication parameters for the backend. */\n  connection?: { host?: string; apiKey?: string }\n}\n\nconst getMeilisearch = async () => {\n  try {\n    const mod = await import('meilisearch')\n    return mod.Meilisearch\n  } catch {\n    throw new E_VECTOR_STORE_DRIVER_UNAVAILABLE(['meilisearch'])\n  }\n}\n\nexport class MeilisearchVectorStore extends BaseVectorStore {\n  readonly capabilities: VectorStoreCapabilities = {\n    transactions: false,\n    namedVectors: false,\n    rename: false,\n    rawSql: false,\n    builtInEncoding: false,\n    // Writes are awaited to task completion (waitForTask) before resolving — strongly\n    // consistent for the next search. The option is a no-op.\n    consistency: { configurable: false, default: 'strong', modes: ['strong'] },\n  }\n\n  #client: any | null = null\n  #dims: Map<string, number> = new Map()\n\n  get #opts(): MeilisearchVectorStoreOptions {\n    return this.options as MeilisearchVectorStoreOptions\n  }\n\n  /** Static availability probe: whether this adapter's runtime driver can load in the current environment. */\n  static isAvailable(): boolean {\n    return typeof process !== 'undefined'\n  }\n  isAvailable(): boolean {\n    return typeof process !== 'undefined'\n  }\n\n  async connect(): Promise<void> {\n    if (this.#client) return\n    const Meilisearch = await getMeilisearch()\n    const c = this.#opts.connection || {}\n    const host = c.host ?? 'http://localhost:7700'\n    try {\n      this.#client = new Meilisearch({ host, apiKey: c.apiKey })\n      // Enable the vector store experimental feature (no-op / stable on newer versions).\n      await fetch(`${host.replace(/\\/$/, '')}/experimental-features`, {\n        method: 'PATCH',\n        headers: {\n          'Content-Type': 'application/json',\n          ...(c.apiKey ? { Authorization: `Bearer ${c.apiKey}` } : {}),\n        },\n        body: JSON.stringify({ vectorStore: true }),\n      }).catch(() => undefined)\n    } catch (err) {\n      throw new E_VECTOR_STORE_CONNECTION_FAILED([String(err)])\n    }\n  }\n\n  async close(): Promise<void> {\n    this.#client = null\n  }\n\n  async #ensure(): Promise<any> {\n    if (!this.#client) await this.connect()\n    return this.#client!\n  }\n\n  async #wait(task: any): Promise<void> {\n    const uid = task?.taskUid ?? task?.uid\n    if (uid === undefined) return\n    await this.#client.tasks.waitForTask(uid)\n  }\n\n  async createCollection(spec: CollectionSpec, ifNotExists: boolean): Promise<void> {\n    const client = await this.#ensure()\n    this.#dims.set(spec.collection, spec.vector.dimensions)\n    if (ifNotExists && (await this.hasCollection(spec.collection))) return\n    try {\n      await this.#wait(await client.createIndex(spec.collection, { primaryKey: 'id' }))\n      const idx = client.index(spec.collection)\n      await this.#wait(\n        await idx.updateEmbedders({\n          [EMBEDDER]: { source: 'userProvided', dimensions: spec.vector.dimensions },\n        })\n      )\n    } catch (err) {\n      throw new E_VECTOR_STORE_COLLECTION_FAILED(['createCollection', String(err)])\n    }\n  }\n\n  async dropCollection(collection: string, ifExists: boolean): Promise<void> {\n    const client = await this.#ensure()\n    if (ifExists && !(await this.hasCollection(collection))) return\n    try {\n      await this.#wait(await client.deleteIndex(collection))\n      this.#dims.delete(collection)\n    } catch (err) {\n      throw new E_VECTOR_STORE_COLLECTION_FAILED(['dropCollection', String(err)])\n    }\n  }\n\n  async hasCollection(collection: string): Promise<boolean> {\n    const client = await this.#ensure()\n    try {\n      await client.index(collection).getRawInfo()\n      return true\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', 'meilisearch'])\n  }\n\n  async executeUpsert(plan: UpsertPlan): Promise<void> {\n    if (plan.records.length === 0) return\n    validateRecords(plan.records)\n    const client = await this.#ensure()\n    const expected = this.#opts.dimensions ?? this.#dims.get(plan.collection)\n    try {\n      const docs: any[] = []\n      for (const r of plan.records) {\n        let vector = r.vector\n        if (!vector && r.document) {\n          const [v] = await this.encode([r.document], 'document')\n          vector = v\n        }\n        if (!vector) {\n          throw new E_VECTOR_STORE_UPSERT_FAILED(['Record missing vector and document'])\n        }\n        if (expected !== undefined && vector.length !== expected) {\n          throw new E_VECTOR_STORE_DIMENSION_MISMATCH([expected, vector.length])\n        }\n        docs.push({\n          id: r.id,\n          document: r.document ?? '',\n          metadata: r.metadata ? JSON.stringify(r.metadata) : '{}',\n          _vectors: { [EMBEDDER]: vector },\n        })\n      }\n      await this.#wait(await client.index(plan.collection).addDocuments(docs))\n    } catch (err) {\n      if (\n        isInstanceOf(err, 'E_VECTOR_STORE_DIMENSION_MISMATCH', E_VECTOR_STORE_DIMENSION_MISMATCH) ||\n        isInstanceOf(err, 'E_VECTOR_STORE_UPSERT_FAILED', E_VECTOR_STORE_UPSERT_FAILED)\n      ) {\n        throw err\n      }\n      throw new E_VECTOR_STORE_UPSERT_FAILED([String(err)])\n    }\n  }\n\n  async executeSearch(plan: SearchPlan): Promise<VectorMatch[]> {\n    const client = await this.#ensure()\n    const idx = client.index(plan.collection)\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 doc = await idx.getDocument(plan.near.id, { retrieveVectors: true })\n          queryVector = this.#unwrapVector(doc?._vectors?.[EMBEDDER])\n        } catch {\n          queryVector = undefined\n        }\n        if (!queryVector) {\n          throw new E_VECTOR_STORE_SEARCH_FAILED(['Referenced id not found: ' + plan.near.id])\n        }\n      }\n    }\n\n    const offset = plan.offset ?? 0\n    try {\n      const over = plan.filter ? 250 : plan.topK + offset\n      let hits: any[]\n      if (queryVector) {\n        const res = await idx.search('', {\n          vector: queryVector,\n          hybrid: { embedder: EMBEDDER, semanticRatio: 1.0 },\n          limit: Math.max(over, plan.topK + offset),\n          showRankingScore: true,\n          retrieveVectors: true,\n        })\n        hits = res.hits ?? []\n      } else {\n        const res = await idx.search('', {\n          limit: Math.max(over, plan.topK + offset),\n          retrieveVectors: true,\n        })\n        hits = res.hits ?? []\n      }\n      const mapped = hits.map((hit) => ({\n        match: this.#project(hit, plan, !!queryVector),\n        meta: this.#parseMeta(hit.metadata),\n      }))\n      const filtered = plan.filter\n        ? mapped.filter((m) => evaluateFilter(plan.filter!, m.meta))\n        : mapped\n      return filtered.slice(offset, offset + plan.topK).map((m) => m.match)\n    } catch (err) {\n      throw new E_VECTOR_STORE_SEARCH_FAILED([String(err)])\n    }\n  }\n\n  #unwrapVector(v: unknown): number[] | undefined {\n    // Meilisearch returns _vectors.default as { embeddings: number[][] } or number[][] or number[].\n    if (!v) return undefined\n    if (Array.isArray(v)) {\n      return Array.isArray(v[0]) ? (v[0] as number[]) : (v as number[])\n    }\n    const emb = (v as any).embeddings\n    if (Array.isArray(emb)) return Array.isArray(emb[0]) ? (emb[0] as number[]) : (emb as number[])\n    return undefined\n  }\n\n  #parseMeta(val: unknown): VectorMetadata {\n    if (typeof val === 'string') {\n      try {\n        return JSON.parse(val) as VectorMetadata\n      } catch {\n        return {}\n      }\n    }\n    if (val && typeof val === 'object') return val as VectorMetadata\n    return {}\n  }\n\n  #project(hit: any, plan: SearchPlan, isKnn: boolean): VectorMatch {\n    const proj = plan.projection\n    const out: VectorMatch = {}\n    if (proj.id) out.id = hit.id as string\n    if (proj.vector) {\n      const v = this.#unwrapVector(hit._vectors?.[EMBEDDER])\n      if (v) out.vector = v\n    }\n    if (proj.document) out.document = (hit.document ?? undefined) as string | undefined\n    if (proj.metadata) out.metadata = this.#parseMeta(hit.metadata)\n    if (isKnn && typeof hit._rankingScore === 'number') {\n      // Meilisearch _rankingScore is already in [0,1], higher = closer.\n      out.score = hit._rankingScore\n    }\n    return out\n  }\n\n  async executeDelete(plan: DeletePlan): Promise<void> {\n    const client = await this.#ensure()\n    const idx = client.index(plan.collection)\n    try {\n      if (plan.ids && plan.ids.length > 0) {\n        await this.#wait(await idx.deleteDocuments(plan.ids))\n      } else if (plan.filter) {\n        // Resolve ids via a scan + JS evaluator, then delete by id.\n        const res = await idx.search('', { limit: 1000 })\n        const targets = (res.hits ?? [])\n          .filter((hit: any) => evaluateFilter(plan.filter!, this.#parseMeta(hit.metadata)))\n          .map((hit: any) => hit.id as string)\n        if (targets.length > 0) await this.#wait(await idx.deleteDocuments(targets))\n      } else {\n        await this.#wait(await idx.deleteAllDocuments())\n      }\n    } catch (err) {\n      throw new E_VECTOR_STORE_DELETE_FAILED([String(err)])\n    }\n  }\n}\n"],"mappings":"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"}

package/batteries/vector/meilisearch.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 { E_VECTOR_STORE_COLLECTION_FAILED, E_VECTOR_STORE_CONNECTION_FAILED, E_VECTOR_STORE_DELETE_FAILED, E_VECTOR_STORE_DIMENSION_MISMATCH, E_VECTOR_STORE_DRIVER_UNAVAILABLE, E_VECTOR_STORE_SEARCH_FAILED, E_VECTOR_STORE_UNSUPPORTED_OPERATION, E_VECTOR_STORE_UPSERT_FAILED } from "./exceptions.mjs";
@@ -43,6 +43,7 @@ var MeilisearchVectorStore = 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";
 	}

package/batteries/vector/meilisearch.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"meilisearch.mjs","names":["#opts","#client","#ensure","#wait","#dims","#unwrapVector","#project","#parseMeta"],"sources":["../../../src/batteries/vector/meilisearch/index.ts"],"sourcesContent":["/**\n * @module @nhtio/adk/batteries/vector/meilisearch\n *\n * Meilisearch adapter. Each collection is a Meilisearch index with a `userProvided` embedder\n * (BYO vectors under `_vectors.<embedder>`); KNN uses semantic search (`vector` +\n * `hybrid.semanticRatio = 1`). Metadata is stored as a JSON string field and filtered with the\n * neutral filter tree's JS reference evaluator for exact cross-adapter parity. Meilisearch\n * returns `_rankingScore` already normalized to [0,1] (higher = closer).\n *\n * Requires the `vectorStore` experimental feature, which the adapter enables on connect.\n * Driver: `meilisearch` (pure JS).\n */\n\nimport { evaluateFilter } from '../filters'\nimport { BaseVectorStore } from '../contract'\nimport { validateRecords } from '../validation'\nimport { isInstanceOf } from '@nhtio/adk/guards'\nimport {\n  E_VECTOR_STORE_DRIVER_UNAVAILABLE,\n  E_VECTOR_STORE_CONNECTION_FAILED,\n  E_VECTOR_STORE_COLLECTION_FAILED,\n  E_VECTOR_STORE_UPSERT_FAILED,\n  E_VECTOR_STORE_SEARCH_FAILED,\n  E_VECTOR_STORE_DELETE_FAILED,\n  E_VECTOR_STORE_DIMENSION_MISMATCH,\n  E_VECTOR_STORE_UNSUPPORTED_OPERATION,\n} from '../exceptions'\nimport type { SearchPlan, UpsertPlan, DeletePlan, CollectionSpec } from '../plan'\nimport type {\n  VectorMatch,\n  VectorStoreCapabilities,\n  BaseVectorStoreOptions,\n  VectorMetadata,\n} from '../types'\n\nconst EMBEDDER = 'default'\n\nexport interface MeilisearchVectorStoreOptions extends BaseVectorStoreOptions {\n  connection?: { host?: string; apiKey?: string }\n}\n\nconst getMeilisearch = async () => {\n  try {\n    const mod = await import('meilisearch')\n    return mod.Meilisearch\n  } catch {\n    throw new E_VECTOR_STORE_DRIVER_UNAVAILABLE(['meilisearch'])\n  }\n}\n\nexport class MeilisearchVectorStore extends BaseVectorStore {\n  readonly capabilities: VectorStoreCapabilities = {\n    transactions: false,\n    namedVectors: false,\n    rename: false,\n    rawSql: false,\n    builtInEncoding: false,\n    // Writes are awaited to task completion (waitForTask) before resolving — strongly\n    // consistent for the next search. The option is a no-op.\n    consistency: { configurable: false, default: 'strong', modes: ['strong'] },\n  }\n\n  #client: any | null = null\n  #dims: Map<string, number> = new Map()\n\n  get #opts(): MeilisearchVectorStoreOptions {\n    return this.options as MeilisearchVectorStoreOptions\n  }\n\n  static isAvailable(): boolean {\n    return typeof process !== 'undefined'\n  }\n  isAvailable(): boolean {\n    return typeof process !== 'undefined'\n  }\n\n  async connect(): Promise<void> {\n    if (this.#client) return\n    const Meilisearch = await getMeilisearch()\n    const c = this.#opts.connection || {}\n    const host = c.host ?? 'http://localhost:7700'\n    try {\n      this.#client = new Meilisearch({ host, apiKey: c.apiKey })\n      // Enable the vector store experimental feature (no-op / stable on newer versions).\n      await fetch(`${host.replace(/\\/$/, '')}/experimental-features`, {\n        method: 'PATCH',\n        headers: {\n          'Content-Type': 'application/json',\n          ...(c.apiKey ? { Authorization: `Bearer ${c.apiKey}` } : {}),\n        },\n        body: JSON.stringify({ vectorStore: true }),\n      }).catch(() => undefined)\n    } catch (err) {\n      throw new E_VECTOR_STORE_CONNECTION_FAILED([String(err)])\n    }\n  }\n\n  async close(): Promise<void> {\n    this.#client = null\n  }\n\n  async #ensure(): Promise<any> {\n    if (!this.#client) await this.connect()\n    return this.#client!\n  }\n\n  async #wait(task: any): Promise<void> {\n    const uid = task?.taskUid ?? task?.uid\n    if (uid === undefined) return\n    await this.#client.tasks.waitForTask(uid)\n  }\n\n  async createCollection(spec: CollectionSpec, ifNotExists: boolean): Promise<void> {\n    const client = await this.#ensure()\n    this.#dims.set(spec.collection, spec.vector.dimensions)\n    if (ifNotExists && (await this.hasCollection(spec.collection))) return\n    try {\n      await this.#wait(await client.createIndex(spec.collection, { primaryKey: 'id' }))\n      const idx = client.index(spec.collection)\n      await this.#wait(\n        await idx.updateEmbedders({\n          [EMBEDDER]: { source: 'userProvided', dimensions: spec.vector.dimensions },\n        })\n      )\n    } catch (err) {\n      throw new E_VECTOR_STORE_COLLECTION_FAILED(['createCollection', String(err)])\n    }\n  }\n\n  async dropCollection(collection: string, ifExists: boolean): Promise<void> {\n    const client = await this.#ensure()\n    if (ifExists && !(await this.hasCollection(collection))) return\n    try {\n      await this.#wait(await client.deleteIndex(collection))\n      this.#dims.delete(collection)\n    } catch (err) {\n      throw new E_VECTOR_STORE_COLLECTION_FAILED(['dropCollection', String(err)])\n    }\n  }\n\n  async hasCollection(collection: string): Promise<boolean> {\n    const client = await this.#ensure()\n    try {\n      await client.index(collection).getRawInfo()\n      return true\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', 'meilisearch'])\n  }\n\n  async executeUpsert(plan: UpsertPlan): Promise<void> {\n    if (plan.records.length === 0) return\n    validateRecords(plan.records)\n    const client = await this.#ensure()\n    const expected = this.#opts.dimensions ?? this.#dims.get(plan.collection)\n    try {\n      const docs: any[] = []\n      for (const r of plan.records) {\n        let vector = r.vector\n        if (!vector && r.document) {\n          const [v] = await this.encode([r.document], 'document')\n          vector = v\n        }\n        if (!vector) {\n          throw new E_VECTOR_STORE_UPSERT_FAILED(['Record missing vector and document'])\n        }\n        if (expected !== undefined && vector.length !== expected) {\n          throw new E_VECTOR_STORE_DIMENSION_MISMATCH([expected, vector.length])\n        }\n        docs.push({\n          id: r.id,\n          document: r.document ?? '',\n          metadata: r.metadata ? JSON.stringify(r.metadata) : '{}',\n          _vectors: { [EMBEDDER]: vector },\n        })\n      }\n      await this.#wait(await client.index(plan.collection).addDocuments(docs))\n    } catch (err) {\n      if (\n        isInstanceOf(err, 'E_VECTOR_STORE_DIMENSION_MISMATCH', E_VECTOR_STORE_DIMENSION_MISMATCH) ||\n        isInstanceOf(err, 'E_VECTOR_STORE_UPSERT_FAILED', E_VECTOR_STORE_UPSERT_FAILED)\n      ) {\n        throw err\n      }\n      throw new E_VECTOR_STORE_UPSERT_FAILED([String(err)])\n    }\n  }\n\n  async executeSearch(plan: SearchPlan): Promise<VectorMatch[]> {\n    const client = await this.#ensure()\n    const idx = client.index(plan.collection)\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 doc = await idx.getDocument(plan.near.id, { retrieveVectors: true })\n          queryVector = this.#unwrapVector(doc?._vectors?.[EMBEDDER])\n        } catch {\n          queryVector = undefined\n        }\n        if (!queryVector) {\n          throw new E_VECTOR_STORE_SEARCH_FAILED(['Referenced id not found: ' + plan.near.id])\n        }\n      }\n    }\n\n    const offset = plan.offset ?? 0\n    try {\n      const over = plan.filter ? 250 : plan.topK + offset\n      let hits: any[]\n      if (queryVector) {\n        const res = await idx.search('', {\n          vector: queryVector,\n          hybrid: { embedder: EMBEDDER, semanticRatio: 1.0 },\n          limit: Math.max(over, plan.topK + offset),\n          showRankingScore: true,\n          retrieveVectors: true,\n        })\n        hits = res.hits ?? []\n      } else {\n        const res = await idx.search('', {\n          limit: Math.max(over, plan.topK + offset),\n          retrieveVectors: true,\n        })\n        hits = res.hits ?? []\n      }\n      const mapped = hits.map((hit) => ({\n        match: this.#project(hit, plan, !!queryVector),\n        meta: this.#parseMeta(hit.metadata),\n      }))\n      const filtered = plan.filter\n        ? mapped.filter((m) => evaluateFilter(plan.filter!, m.meta))\n        : mapped\n      return filtered.slice(offset, offset + plan.topK).map((m) => m.match)\n    } catch (err) {\n      throw new E_VECTOR_STORE_SEARCH_FAILED([String(err)])\n    }\n  }\n\n  #unwrapVector(v: unknown): number[] | undefined {\n    // Meilisearch returns _vectors.default as { embeddings: number[][] } or number[][] or number[].\n    if (!v) return undefined\n    if (Array.isArray(v)) {\n      return Array.isArray(v[0]) ? (v[0] as number[]) : (v as number[])\n    }\n    const emb = (v as any).embeddings\n    if (Array.isArray(emb)) return Array.isArray(emb[0]) ? (emb[0] as number[]) : (emb as number[])\n    return undefined\n  }\n\n  #parseMeta(val: unknown): VectorMetadata {\n    if (typeof val === 'string') {\n      try {\n        return JSON.parse(val) as VectorMetadata\n      } catch {\n        return {}\n      }\n    }\n    if (val && typeof val === 'object') return val as VectorMetadata\n    return {}\n  }\n\n  #project(hit: any, plan: SearchPlan, isKnn: boolean): VectorMatch {\n    const proj = plan.projection\n    const out: VectorMatch = {}\n    if (proj.id) out.id = hit.id as string\n    if (proj.vector) {\n      const v = this.#unwrapVector(hit._vectors?.[EMBEDDER])\n      if (v) out.vector = v\n    }\n    if (proj.document) out.document = (hit.document ?? undefined) as string | undefined\n    if (proj.metadata) out.metadata = this.#parseMeta(hit.metadata)\n    if (isKnn && typeof hit._rankingScore === 'number') {\n      // Meilisearch _rankingScore is already in [0,1], higher = closer.\n      out.score = hit._rankingScore\n    }\n    return out\n  }\n\n  async executeDelete(plan: DeletePlan): Promise<void> {\n    const client = await this.#ensure()\n    const idx = client.index(plan.collection)\n    try {\n      if (plan.ids && plan.ids.length > 0) {\n        await this.#wait(await idx.deleteDocuments(plan.ids))\n      } else if (plan.filter) {\n        // Resolve ids via a scan + JS evaluator, then delete by id.\n        const res = await idx.search('', { limit: 1000 })\n        const targets = (res.hits ?? [])\n          .filter((hit: any) => evaluateFilter(plan.filter!, this.#parseMeta(hit.metadata)))\n          .map((hit: any) => hit.id as string)\n        if (targets.length > 0) await this.#wait(await idx.deleteDocuments(targets))\n      } else {\n        await this.#wait(await idx.deleteAllDocuments())\n      }\n    } catch (err) {\n      throw new E_VECTOR_STORE_DELETE_FAILED([String(err)])\n    }\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"meilisearch.mjs","names":["#opts","#client","#ensure","#wait","#dims","#unwrapVector","#project","#parseMeta"],"sources":["../../../src/batteries/vector/meilisearch/index.ts"],"sourcesContent":["/**\n * @module @nhtio/adk/batteries/vector/meilisearch\n *\n * Meilisearch adapter. Each collection is a Meilisearch index with a `userProvided` embedder\n * (BYO vectors under `_vectors.<embedder>`); KNN uses semantic search (`vector` +\n * `hybrid.semanticRatio = 1`). Metadata is stored as a JSON string field and filtered with the\n * neutral filter tree's JS reference evaluator for exact cross-adapter parity. Meilisearch\n * returns `_rankingScore` already normalized to [0,1] (higher = closer).\n *\n * Requires the `vectorStore` experimental feature, which the adapter enables on connect.\n * Driver: `meilisearch` (pure JS).\n */\n\nimport { evaluateFilter } from '../filters'\nimport { BaseVectorStore } from '../contract'\nimport { validateRecords } from '../validation'\nimport { isInstanceOf } from '@nhtio/adk/guards'\nimport {\n  E_VECTOR_STORE_DRIVER_UNAVAILABLE,\n  E_VECTOR_STORE_CONNECTION_FAILED,\n  E_VECTOR_STORE_COLLECTION_FAILED,\n  E_VECTOR_STORE_UPSERT_FAILED,\n  E_VECTOR_STORE_SEARCH_FAILED,\n  E_VECTOR_STORE_DELETE_FAILED,\n  E_VECTOR_STORE_DIMENSION_MISMATCH,\n  E_VECTOR_STORE_UNSUPPORTED_OPERATION,\n} from '../exceptions'\nimport type { SearchPlan, UpsertPlan, DeletePlan, CollectionSpec } from '../plan'\nimport type {\n  VectorMatch,\n  VectorStoreCapabilities,\n  BaseVectorStoreOptions,\n  VectorMetadata,\n} from '../types'\n\nconst EMBEDDER = 'default'\n\nexport interface MeilisearchVectorStoreOptions extends BaseVectorStoreOptions {\n  /** Connection and authentication parameters for the backend. */\n  connection?: { host?: string; apiKey?: string }\n}\n\nconst getMeilisearch = async () => {\n  try {\n    const mod = await import('meilisearch')\n    return mod.Meilisearch\n  } catch {\n    throw new E_VECTOR_STORE_DRIVER_UNAVAILABLE(['meilisearch'])\n  }\n}\n\nexport class MeilisearchVectorStore extends BaseVectorStore {\n  readonly capabilities: VectorStoreCapabilities = {\n    transactions: false,\n    namedVectors: false,\n    rename: false,\n    rawSql: false,\n    builtInEncoding: false,\n    // Writes are awaited to task completion (waitForTask) before resolving — strongly\n    // consistent for the next search. The option is a no-op.\n    consistency: { configurable: false, default: 'strong', modes: ['strong'] },\n  }\n\n  #client: any | null = null\n  #dims: Map<string, number> = new Map()\n\n  get #opts(): MeilisearchVectorStoreOptions {\n    return this.options as MeilisearchVectorStoreOptions\n  }\n\n  /** Static availability probe: whether this adapter's runtime driver can load in the current environment. */\n  static isAvailable(): boolean {\n    return typeof process !== 'undefined'\n  }\n  isAvailable(): boolean {\n    return typeof process !== 'undefined'\n  }\n\n  async connect(): Promise<void> {\n    if (this.#client) return\n    const Meilisearch = await getMeilisearch()\n    const c = this.#opts.connection || {}\n    const host = c.host ?? 'http://localhost:7700'\n    try {\n      this.#client = new Meilisearch({ host, apiKey: c.apiKey })\n      // Enable the vector store experimental feature (no-op / stable on newer versions).\n      await fetch(`${host.replace(/\\/$/, '')}/experimental-features`, {\n        method: 'PATCH',\n        headers: {\n          'Content-Type': 'application/json',\n          ...(c.apiKey ? { Authorization: `Bearer ${c.apiKey}` } : {}),\n        },\n        body: JSON.stringify({ vectorStore: true }),\n      }).catch(() => undefined)\n    } catch (err) {\n      throw new E_VECTOR_STORE_CONNECTION_FAILED([String(err)])\n    }\n  }\n\n  async close(): Promise<void> {\n    this.#client = null\n  }\n\n  async #ensure(): Promise<any> {\n    if (!this.#client) await this.connect()\n    return this.#client!\n  }\n\n  async #wait(task: any): Promise<void> {\n    const uid = task?.taskUid ?? task?.uid\n    if (uid === undefined) return\n    await this.#client.tasks.waitForTask(uid)\n  }\n\n  async createCollection(spec: CollectionSpec, ifNotExists: boolean): Promise<void> {\n    const client = await this.#ensure()\n    this.#dims.set(spec.collection, spec.vector.dimensions)\n    if (ifNotExists && (await this.hasCollection(spec.collection))) return\n    try {\n      await this.#wait(await client.createIndex(spec.collection, { primaryKey: 'id' }))\n      const idx = client.index(spec.collection)\n      await this.#wait(\n        await idx.updateEmbedders({\n          [EMBEDDER]: { source: 'userProvided', dimensions: spec.vector.dimensions },\n        })\n      )\n    } catch (err) {\n      throw new E_VECTOR_STORE_COLLECTION_FAILED(['createCollection', String(err)])\n    }\n  }\n\n  async dropCollection(collection: string, ifExists: boolean): Promise<void> {\n    const client = await this.#ensure()\n    if (ifExists && !(await this.hasCollection(collection))) return\n    try {\n      await this.#wait(await client.deleteIndex(collection))\n      this.#dims.delete(collection)\n    } catch (err) {\n      throw new E_VECTOR_STORE_COLLECTION_FAILED(['dropCollection', String(err)])\n    }\n  }\n\n  async hasCollection(collection: string): Promise<boolean> {\n    const client = await this.#ensure()\n    try {\n      await client.index(collection).getRawInfo()\n      return true\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', 'meilisearch'])\n  }\n\n  async executeUpsert(plan: UpsertPlan): Promise<void> {\n    if (plan.records.length === 0) return\n    validateRecords(plan.records)\n    const client = await this.#ensure()\n    const expected = this.#opts.dimensions ?? this.#dims.get(plan.collection)\n    try {\n      const docs: any[] = []\n      for (const r of plan.records) {\n        let vector = r.vector\n        if (!vector && r.document) {\n          const [v] = await this.encode([r.document], 'document')\n          vector = v\n        }\n        if (!vector) {\n          throw new E_VECTOR_STORE_UPSERT_FAILED(['Record missing vector and document'])\n        }\n        if (expected !== undefined && vector.length !== expected) {\n          throw new E_VECTOR_STORE_DIMENSION_MISMATCH([expected, vector.length])\n        }\n        docs.push({\n          id: r.id,\n          document: r.document ?? '',\n          metadata: r.metadata ? JSON.stringify(r.metadata) : '{}',\n          _vectors: { [EMBEDDER]: vector },\n        })\n      }\n      await this.#wait(await client.index(plan.collection).addDocuments(docs))\n    } catch (err) {\n      if (\n        isInstanceOf(err, 'E_VECTOR_STORE_DIMENSION_MISMATCH', E_VECTOR_STORE_DIMENSION_MISMATCH) ||\n        isInstanceOf(err, 'E_VECTOR_STORE_UPSERT_FAILED', E_VECTOR_STORE_UPSERT_FAILED)\n      ) {\n        throw err\n      }\n      throw new E_VECTOR_STORE_UPSERT_FAILED([String(err)])\n    }\n  }\n\n  async executeSearch(plan: SearchPlan): Promise<VectorMatch[]> {\n    const client = await this.#ensure()\n    const idx = client.index(plan.collection)\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 doc = await idx.getDocument(plan.near.id, { retrieveVectors: true })\n          queryVector = this.#unwrapVector(doc?._vectors?.[EMBEDDER])\n        } catch {\n          queryVector = undefined\n        }\n        if (!queryVector) {\n          throw new E_VECTOR_STORE_SEARCH_FAILED(['Referenced id not found: ' + plan.near.id])\n        }\n      }\n    }\n\n    const offset = plan.offset ?? 0\n    try {\n      const over = plan.filter ? 250 : plan.topK + offset\n      let hits: any[]\n      if (queryVector) {\n        const res = await idx.search('', {\n          vector: queryVector,\n          hybrid: { embedder: EMBEDDER, semanticRatio: 1.0 },\n          limit: Math.max(over, plan.topK + offset),\n          showRankingScore: true,\n          retrieveVectors: true,\n        })\n        hits = res.hits ?? []\n      } else {\n        const res = await idx.search('', {\n          limit: Math.max(over, plan.topK + offset),\n          retrieveVectors: true,\n        })\n        hits = res.hits ?? []\n      }\n      const mapped = hits.map((hit) => ({\n        match: this.#project(hit, plan, !!queryVector),\n        meta: this.#parseMeta(hit.metadata),\n      }))\n      const filtered = plan.filter\n        ? mapped.filter((m) => evaluateFilter(plan.filter!, m.meta))\n        : mapped\n      return filtered.slice(offset, offset + plan.topK).map((m) => m.match)\n    } catch (err) {\n      throw new E_VECTOR_STORE_SEARCH_FAILED([String(err)])\n    }\n  }\n\n  #unwrapVector(v: unknown): number[] | undefined {\n    // Meilisearch returns _vectors.default as { embeddings: number[][] } or number[][] or number[].\n    if (!v) return undefined\n    if (Array.isArray(v)) {\n      return Array.isArray(v[0]) ? (v[0] as number[]) : (v as number[])\n    }\n    const emb = (v as any).embeddings\n    if (Array.isArray(emb)) return Array.isArray(emb[0]) ? (emb[0] as number[]) : (emb as number[])\n    return undefined\n  }\n\n  #parseMeta(val: unknown): VectorMetadata {\n    if (typeof val === 'string') {\n      try {\n        return JSON.parse(val) as VectorMetadata\n      } catch {\n        return {}\n      }\n    }\n    if (val && typeof val === 'object') return val as VectorMetadata\n    return {}\n  }\n\n  #project(hit: any, plan: SearchPlan, isKnn: boolean): VectorMatch {\n    const proj = plan.projection\n    const out: VectorMatch = {}\n    if (proj.id) out.id = hit.id as string\n    if (proj.vector) {\n      const v = this.#unwrapVector(hit._vectors?.[EMBEDDER])\n      if (v) out.vector = v\n    }\n    if (proj.document) out.document = (hit.document ?? undefined) as string | undefined\n    if (proj.metadata) out.metadata = this.#parseMeta(hit.metadata)\n    if (isKnn && typeof hit._rankingScore === 'number') {\n      // Meilisearch _rankingScore is already in [0,1], higher = closer.\n      out.score = hit._rankingScore\n    }\n    return out\n  }\n\n  async executeDelete(plan: DeletePlan): Promise<void> {\n    const client = await this.#ensure()\n    const idx = client.index(plan.collection)\n    try {\n      if (plan.ids && plan.ids.length > 0) {\n        await this.#wait(await idx.deleteDocuments(plan.ids))\n      } else if (plan.filter) {\n        // Resolve ids via a scan + JS evaluator, then delete by id.\n        const res = await idx.search('', { limit: 1000 })\n        const targets = (res.hits ?? [])\n          .filter((hit: any) => evaluateFilter(plan.filter!, this.#parseMeta(hit.metadata)))\n          .map((hit: any) => hit.id as string)\n        if (targets.length > 0) await this.#wait(await idx.deleteDocuments(targets))\n      } else {\n        await this.#wait(await idx.deleteAllDocuments())\n      }\n    } catch (err) {\n      throw new E_VECTOR_STORE_DELETE_FAILED([String(err)])\n    }\n  }\n}\n"],"mappings":"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"}

package/batteries/vector/migrate.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 require("../../chunk-Ble4zEEl.js");
-const require_tool_registry = require("../../tool_registry-DYUYqXvo.js");
+const require_tool_registry = require("../../tool_registry-CKJPze3j.js");
 require("../../guards.cjs");
 const require_batteries_vector_exceptions = require("./exceptions.cjs");
 //#region src/batteries/vector/migrate.ts
@@ -9,15 +9,25 @@ const require_batteries_vector_exceptions = require("./exceptions.cjs");
 *
 * @module @nhtio/adk/batteries/vector/migrate
 */
+/** Knex-style migration runner: applies pending migrations forward and rolls the last one back. */
 var VectorMigrator = class {
 	#migrations;
 	#ledger;
 	#schema;
+	/**
+	* @param opts - The migrations, ledger, and schema facade to run against.
+	*/
 	constructor(opts) {
 		this.#migrations = opts.migrations;
 		this.#ledger = opts.ledger;
 		this.#schema = opts.schema;
 	}
+	/**
+	* Apply every not-yet-applied migration in order, recording each in the ledger.
+	*
+	* @returns The names of the migrations applied during this run.
+	* @throws {@link @nhtio/adk/batteries!E_VECTOR_STORE_MIGRATION_FAILED} when a migration's `up` throws.
+	*/
 	async latest() {
 		const applied = await this.#ledger.applied();
 		const toApply = this.#migrations.filter((m) => !applied.includes(m.name));
@@ -32,6 +42,13 @@ var VectorMigrator = class {
 		}
 		return appliedThisRun;
 	}
+	/**
+	* Reverse the most recently applied migration and remove it from the ledger.
+	*
+	* @returns The name of the rolled-back migration, or `null` when nothing was applied.
+	* @throws {@link @nhtio/adk/batteries!E_VECTOR_STORE_MIGRATION_FAILED} when the migration module is missing or
+	*   its `down` throws.
+	*/
 	async rollback() {
 		const applied = await this.#ledger.applied();
 		if (applied.length === 0) return null;

package/batteries/vector/migrate.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"migrate.cjs","names":["#migrations","#ledger","#schema"],"sources":["../../../src/batteries/vector/migrate.ts"],"sourcesContent":["/**\n * Knex-style migration runner for the vector battery.\n *\n * @module @nhtio/adk/batteries/vector/migrate\n */\n\nimport { isError } from '@nhtio/adk/guards'\nimport { E_VECTOR_STORE_MIGRATION_FAILED } from './exceptions'\nimport type { VectorSchemaBuilder } from './schema'\n\n// The context passed to each migration's up/down.\nexport interface VectorMigrationContext {\n  schema: VectorSchemaBuilder\n}\n\n// A migration module shape.\nexport interface VectorMigration {\n  name: string\n  up: (ctx: VectorMigrationContext) => Promise<void>\n  down: (ctx: VectorMigrationContext) => Promise<void>\n}\n\n// The ledger persists which migrations have run. Backed by a MigrationLedger the store provides.\nexport interface MigrationLedger {\n  applied(): Promise<string[]>\n  record(name: string): Promise<void>\n  remove(name: string): Promise<void>\n}\n\nexport interface VectorMigrateOptions {\n  migrations: VectorMigration[]\n  ledger: MigrationLedger\n  schema: VectorSchemaBuilder\n}\n\nexport class VectorMigrator {\n  readonly #migrations: VectorMigration[]\n  readonly #ledger: MigrationLedger\n  readonly #schema: VectorSchemaBuilder\n\n  constructor(opts: VectorMigrateOptions) {\n    this.#migrations = opts.migrations\n    this.#ledger = opts.ledger\n    this.#schema = opts.schema\n  }\n\n  async latest(): Promise<string[]> {\n    const applied = await this.#ledger.applied()\n    const toApply = this.#migrations.filter((m) => !applied.includes(m.name))\n\n    const appliedThisRun: string[] = []\n\n    for (const migration of toApply) {\n      try {\n        await migration.up({ schema: this.#schema })\n        await this.#ledger.record(migration.name)\n        appliedThisRun.push(migration.name)\n      } catch (err) {\n        const msg = (value: unknown): string => (isError(value) ? value.message : String(value))\n        throw new E_VECTOR_STORE_MIGRATION_FAILED([migration.name, msg(err)])\n      }\n    }\n\n    return appliedThisRun\n  }\n\n  async rollback(): Promise<string | null> {\n    const applied = await this.#ledger.applied()\n\n    if (applied.length === 0) {\n      return null\n    }\n\n    const lastApplied = applied[applied.length - 1]\n    const migration = this.#migrations.find((m) => m.name === lastApplied)\n\n    if (!migration) {\n      throw new E_VECTOR_STORE_MIGRATION_FAILED([lastApplied, 'migration module not found'])\n    }\n\n    try {\n      await migration.down({ schema: this.#schema })\n      await this.#ledger.remove(lastApplied)\n      return lastApplied\n    } catch (err) {\n      const msg = (value: unknown): string => (isError(value) ? value.message : String(value))\n      throw new E_VECTOR_STORE_MIGRATION_FAILED([lastApplied, msg(err)])\n    }\n  }\n}\n"],"mappings":";;;;;;;;;;;AAmCA,IAAa,iBAAb,MAA4B;CAC1B;CACA;CACA;CAEA,YAAY,MAA4B;EACtC,KAAKA,cAAc,KAAK;EACxB,KAAKC,UAAU,KAAK;EACpB,KAAKC,UAAU,KAAK;CACtB;CAEA,MAAM,SAA4B;EAChC,MAAM,UAAU,MAAM,KAAKD,QAAQ,QAAQ;EAC3C,MAAM,UAAU,KAAKD,YAAY,QAAQ,MAAM,CAAC,QAAQ,SAAS,EAAE,IAAI,CAAC;EAExE,MAAM,iBAA2B,CAAC;EAElC,KAAK,MAAM,aAAa,SACtB,IAAI;GACF,MAAM,UAAU,GAAG,EAAE,QAAQ,KAAKE,QAAQ,CAAC;GAC3C,MAAM,KAAKD,QAAQ,OAAO,UAAU,IAAI;GACxC,eAAe,KAAK,UAAU,IAAI;EACpC,SAAS,KAAK;GACZ,MAAM,OAAO,UAA4B,sBAAA,QAAQ,KAAK,IAAI,MAAM,UAAU,OAAO,KAAK;GACtF,MAAM,IAAI,oCAAA,gCAAgC,CAAC,UAAU,MAAM,IAAI,GAAG,CAAC,CAAC;EACtE;EAGF,OAAO;CACT;CAEA,MAAM,WAAmC;EACvC,MAAM,UAAU,MAAM,KAAKA,QAAQ,QAAQ;EAE3C,IAAI,QAAQ,WAAW,GACrB,OAAO;EAGT,MAAM,cAAc,QAAQ,QAAQ,SAAS;EAC7C,MAAM,YAAY,KAAKD,YAAY,MAAM,MAAM,EAAE,SAAS,WAAW;EAErE,IAAI,CAAC,WACH,MAAM,IAAI,oCAAA,gCAAgC,CAAC,aAAa,4BAA4B,CAAC;EAGvF,IAAI;GACF,MAAM,UAAU,KAAK,EAAE,QAAQ,KAAKE,QAAQ,CAAC;GAC7C,MAAM,KAAKD,QAAQ,OAAO,WAAW;GACrC,OAAO;EACT,SAAS,KAAK;GACZ,MAAM,OAAO,UAA4B,sBAAA,QAAQ,KAAK,IAAI,MAAM,UAAU,OAAO,KAAK;GACtF,MAAM,IAAI,oCAAA,gCAAgC,CAAC,aAAa,IAAI,GAAG,CAAC,CAAC;EACnE;CACF;AACF"}
+{"version":3,"file":"migrate.cjs","names":["#migrations","#ledger","#schema"],"sources":["../../../src/batteries/vector/migrate.ts"],"sourcesContent":["/**\n * Knex-style migration runner for the vector battery.\n *\n * @module @nhtio/adk/batteries/vector/migrate\n */\n\nimport { isError } from '@nhtio/adk/guards'\nimport { E_VECTOR_STORE_MIGRATION_FAILED } from './exceptions'\nimport type { VectorSchemaBuilder } from './schema'\n\n/** The context passed to each migration's `up`/`down` — exposes the schema builder. */\nexport interface VectorMigrationContext {\n  /** Schema facade for performing collection DDL within the migration. */\n  schema: VectorSchemaBuilder\n}\n\n/** A single migration module: a name plus its forward (`up`) and reverse (`down`) steps. */\nexport interface VectorMigration {\n  /** Unique migration name, used as its ledger key. */\n  name: string\n  /** Apply the migration. */\n  up: (ctx: VectorMigrationContext) => Promise<void>\n  /** Reverse the migration. */\n  down: (ctx: VectorMigrationContext) => Promise<void>\n}\n\n/** Persistence for which migrations have run; backed by a store-provided implementation. */\nexport interface MigrationLedger {\n  /** Resolve the names of migrations already applied, in application order. */\n  applied(): Promise<string[]>\n  /** Record `name` as applied. */\n  record(name: string): Promise<void>\n  /** Remove `name` from the applied set (on rollback). */\n  remove(name: string): Promise<void>\n}\n\n/** Construction options for a {@link VectorMigrator}. */\nexport interface VectorMigrateOptions {\n  /** The ordered set of migration modules. */\n  migrations: VectorMigration[]\n  /** Ledger tracking which migrations have run. */\n  ledger: MigrationLedger\n  /** Schema facade handed to each migration. */\n  schema: VectorSchemaBuilder\n}\n\n/** Knex-style migration runner: applies pending migrations forward and rolls the last one back. */\nexport class VectorMigrator {\n  readonly #migrations: VectorMigration[]\n  readonly #ledger: MigrationLedger\n  readonly #schema: VectorSchemaBuilder\n\n  /**\n   * @param opts - The migrations, ledger, and schema facade to run against.\n   */\n  constructor(opts: VectorMigrateOptions) {\n    this.#migrations = opts.migrations\n    this.#ledger = opts.ledger\n    this.#schema = opts.schema\n  }\n\n  /**\n   * Apply every not-yet-applied migration in order, recording each in the ledger.\n   *\n   * @returns The names of the migrations applied during this run.\n   * @throws {@link @nhtio/adk/batteries!E_VECTOR_STORE_MIGRATION_FAILED} when a migration's `up` throws.\n   */\n  async latest(): Promise<string[]> {\n    const applied = await this.#ledger.applied()\n    const toApply = this.#migrations.filter((m) => !applied.includes(m.name))\n\n    const appliedThisRun: string[] = []\n\n    for (const migration of toApply) {\n      try {\n        await migration.up({ schema: this.#schema })\n        await this.#ledger.record(migration.name)\n        appliedThisRun.push(migration.name)\n      } catch (err) {\n        const msg = (value: unknown): string => (isError(value) ? value.message : String(value))\n        throw new E_VECTOR_STORE_MIGRATION_FAILED([migration.name, msg(err)])\n      }\n    }\n\n    return appliedThisRun\n  }\n\n  /**\n   * Reverse the most recently applied migration and remove it from the ledger.\n   *\n   * @returns The name of the rolled-back migration, or `null` when nothing was applied.\n   * @throws {@link @nhtio/adk/batteries!E_VECTOR_STORE_MIGRATION_FAILED} when the migration module is missing or\n   *   its `down` throws.\n   */\n  async rollback(): Promise<string | null> {\n    const applied = await this.#ledger.applied()\n\n    if (applied.length === 0) {\n      return null\n    }\n\n    const lastApplied = applied[applied.length - 1]\n    const migration = this.#migrations.find((m) => m.name === lastApplied)\n\n    if (!migration) {\n      throw new E_VECTOR_STORE_MIGRATION_FAILED([lastApplied, 'migration module not found'])\n    }\n\n    try {\n      await migration.down({ schema: this.#schema })\n      await this.#ledger.remove(lastApplied)\n      return lastApplied\n    } catch (err) {\n      const msg = (value: unknown): string => (isError(value) ? value.message : String(value))\n      throw new E_VECTOR_STORE_MIGRATION_FAILED([lastApplied, msg(err)])\n    }\n  }\n}\n"],"mappings":";;;;;;;;;;;;AA+CA,IAAa,iBAAb,MAA4B;CAC1B;CACA;CACA;;;;CAKA,YAAY,MAA4B;EACtC,KAAKA,cAAc,KAAK;EACxB,KAAKC,UAAU,KAAK;EACpB,KAAKC,UAAU,KAAK;CACtB;;;;;;;CAQA,MAAM,SAA4B;EAChC,MAAM,UAAU,MAAM,KAAKD,QAAQ,QAAQ;EAC3C,MAAM,UAAU,KAAKD,YAAY,QAAQ,MAAM,CAAC,QAAQ,SAAS,EAAE,IAAI,CAAC;EAExE,MAAM,iBAA2B,CAAC;EAElC,KAAK,MAAM,aAAa,SACtB,IAAI;GACF,MAAM,UAAU,GAAG,EAAE,QAAQ,KAAKE,QAAQ,CAAC;GAC3C,MAAM,KAAKD,QAAQ,OAAO,UAAU,IAAI;GACxC,eAAe,KAAK,UAAU,IAAI;EACpC,SAAS,KAAK;GACZ,MAAM,OAAO,UAA4B,sBAAA,QAAQ,KAAK,IAAI,MAAM,UAAU,OAAO,KAAK;GACtF,MAAM,IAAI,oCAAA,gCAAgC,CAAC,UAAU,MAAM,IAAI,GAAG,CAAC,CAAC;EACtE;EAGF,OAAO;CACT;;;;;;;;CASA,MAAM,WAAmC;EACvC,MAAM,UAAU,MAAM,KAAKA,QAAQ,QAAQ;EAE3C,IAAI,QAAQ,WAAW,GACrB,OAAO;EAGT,MAAM,cAAc,QAAQ,QAAQ,SAAS;EAC7C,MAAM,YAAY,KAAKD,YAAY,MAAM,MAAM,EAAE,SAAS,WAAW;EAErE,IAAI,CAAC,WACH,MAAM,IAAI,oCAAA,gCAAgC,CAAC,aAAa,4BAA4B,CAAC;EAGvF,IAAI;GACF,MAAM,UAAU,KAAK,EAAE,QAAQ,KAAKE,QAAQ,CAAC;GAC7C,MAAM,KAAKD,QAAQ,OAAO,WAAW;GACrC,OAAO;EACT,SAAS,KAAK;GACZ,MAAM,OAAO,UAA4B,sBAAA,QAAQ,KAAK,IAAI,MAAM,UAAU,OAAO,KAAK;GACtF,MAAM,IAAI,oCAAA,gCAAgC,CAAC,aAAa,IAAI,GAAG,CAAC,CAAC;EACnE;CACF;AACF"}

package/batteries/vector/migrate.d.ts

@@ -4,27 +4,58 @@
  * @module @nhtio/adk/batteries/vector/migrate
  */
 import type { VectorSchemaBuilder } from "./schema";
+/** The context passed to each migration's `up`/`down` — exposes the schema builder. */
 export interface VectorMigrationContext {
+    /** Schema facade for performing collection DDL within the migration. */
     schema: VectorSchemaBuilder;
 }
+/** A single migration module: a name plus its forward (`up`) and reverse (`down`) steps. */
 export interface VectorMigration {
+    /** Unique migration name, used as its ledger key. */
     name: string;
+    /** Apply the migration. */
     up: (ctx: VectorMigrationContext) => Promise<void>;
+    /** Reverse the migration. */
     down: (ctx: VectorMigrationContext) => Promise<void>;
 }
+/** Persistence for which migrations have run; backed by a store-provided implementation. */
 export interface MigrationLedger {
+    /** Resolve the names of migrations already applied, in application order. */
     applied(): Promise<string[]>;
+    /** Record `name` as applied. */
     record(name: string): Promise<void>;
+    /** Remove `name` from the applied set (on rollback). */
     remove(name: string): Promise<void>;
 }
+/** Construction options for a {@link VectorMigrator}. */
 export interface VectorMigrateOptions {
+    /** The ordered set of migration modules. */
     migrations: VectorMigration[];
+    /** Ledger tracking which migrations have run. */
     ledger: MigrationLedger;
+    /** Schema facade handed to each migration. */
     schema: VectorSchemaBuilder;
 }
+/** Knex-style migration runner: applies pending migrations forward and rolls the last one back. */
 export declare class VectorMigrator {
     #private;
+    /**
+     * @param opts - The migrations, ledger, and schema facade to run against.
+     */
     constructor(opts: VectorMigrateOptions);
+    /**
+     * Apply every not-yet-applied migration in order, recording each in the ledger.
+     *
+     * @returns The names of the migrations applied during this run.
+     * @throws {@link @nhtio/adk/batteries!E_VECTOR_STORE_MIGRATION_FAILED} when a migration's `up` throws.
+     */
     latest(): Promise<string[]>;
+    /**
+     * Reverse the most recently applied migration and remove it from the ledger.
+     *
+     * @returns The name of the rolled-back migration, or `null` when nothing was applied.
+     * @throws {@link @nhtio/adk/batteries!E_VECTOR_STORE_MIGRATION_FAILED} when the migration module is missing or
+     *   its `down` throws.
+     */
     rollback(): Promise<string | null>;
 }

package/batteries/vector/migrate.mjs

@@ -1,4 +1,4 @@
-import { o as isError } from "../../tool_registry-D1pSSlsd.mjs";
+import { o as isError } from "../../tool_registry-791Vrjtf.mjs";
 import "../../guards.mjs";
 import { E_VECTOR_STORE_MIGRATION_FAILED } from "./exceptions.mjs";
 //#region src/batteries/vector/migrate.ts
@@ -7,15 +7,25 @@ import { E_VECTOR_STORE_MIGRATION_FAILED } from "./exceptions.mjs";
 *
 * @module @nhtio/adk/batteries/vector/migrate
 */
+/** Knex-style migration runner: applies pending migrations forward and rolls the last one back. */
 var VectorMigrator = class {
 	#migrations;
 	#ledger;
 	#schema;
+	/**
+	* @param opts - The migrations, ledger, and schema facade to run against.
+	*/
 	constructor(opts) {
 		this.#migrations = opts.migrations;
 		this.#ledger = opts.ledger;
 		this.#schema = opts.schema;
 	}
+	/**
+	* Apply every not-yet-applied migration in order, recording each in the ledger.
+	*
+	* @returns The names of the migrations applied during this run.
+	* @throws {@link @nhtio/adk/batteries!E_VECTOR_STORE_MIGRATION_FAILED} when a migration's `up` throws.
+	*/
 	async latest() {
 		const applied = await this.#ledger.applied();
 		const toApply = this.#migrations.filter((m) => !applied.includes(m.name));
@@ -30,6 +40,13 @@ var VectorMigrator = class {
 		}
 		return appliedThisRun;
 	}
+	/**
+	* Reverse the most recently applied migration and remove it from the ledger.
+	*
+	* @returns The name of the rolled-back migration, or `null` when nothing was applied.
+	* @throws {@link @nhtio/adk/batteries!E_VECTOR_STORE_MIGRATION_FAILED} when the migration module is missing or
+	*   its `down` throws.
+	*/
 	async rollback() {
 		const applied = await this.#ledger.applied();
 		if (applied.length === 0) return null;

package/batteries/vector/migrate.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"migrate.mjs","names":["#migrations","#ledger","#schema"],"sources":["../../../src/batteries/vector/migrate.ts"],"sourcesContent":["/**\n * Knex-style migration runner for the vector battery.\n *\n * @module @nhtio/adk/batteries/vector/migrate\n */\n\nimport { isError } from '@nhtio/adk/guards'\nimport { E_VECTOR_STORE_MIGRATION_FAILED } from './exceptions'\nimport type { VectorSchemaBuilder } from './schema'\n\n// The context passed to each migration's up/down.\nexport interface VectorMigrationContext {\n  schema: VectorSchemaBuilder\n}\n\n// A migration module shape.\nexport interface VectorMigration {\n  name: string\n  up: (ctx: VectorMigrationContext) => Promise<void>\n  down: (ctx: VectorMigrationContext) => Promise<void>\n}\n\n// The ledger persists which migrations have run. Backed by a MigrationLedger the store provides.\nexport interface MigrationLedger {\n  applied(): Promise<string[]>\n  record(name: string): Promise<void>\n  remove(name: string): Promise<void>\n}\n\nexport interface VectorMigrateOptions {\n  migrations: VectorMigration[]\n  ledger: MigrationLedger\n  schema: VectorSchemaBuilder\n}\n\nexport class VectorMigrator {\n  readonly #migrations: VectorMigration[]\n  readonly #ledger: MigrationLedger\n  readonly #schema: VectorSchemaBuilder\n\n  constructor(opts: VectorMigrateOptions) {\n    this.#migrations = opts.migrations\n    this.#ledger = opts.ledger\n    this.#schema = opts.schema\n  }\n\n  async latest(): Promise<string[]> {\n    const applied = await this.#ledger.applied()\n    const toApply = this.#migrations.filter((m) => !applied.includes(m.name))\n\n    const appliedThisRun: string[] = []\n\n    for (const migration of toApply) {\n      try {\n        await migration.up({ schema: this.#schema })\n        await this.#ledger.record(migration.name)\n        appliedThisRun.push(migration.name)\n      } catch (err) {\n        const msg = (value: unknown): string => (isError(value) ? value.message : String(value))\n        throw new E_VECTOR_STORE_MIGRATION_FAILED([migration.name, msg(err)])\n      }\n    }\n\n    return appliedThisRun\n  }\n\n  async rollback(): Promise<string | null> {\n    const applied = await this.#ledger.applied()\n\n    if (applied.length === 0) {\n      return null\n    }\n\n    const lastApplied = applied[applied.length - 1]\n    const migration = this.#migrations.find((m) => m.name === lastApplied)\n\n    if (!migration) {\n      throw new E_VECTOR_STORE_MIGRATION_FAILED([lastApplied, 'migration module not found'])\n    }\n\n    try {\n      await migration.down({ schema: this.#schema })\n      await this.#ledger.remove(lastApplied)\n      return lastApplied\n    } catch (err) {\n      const msg = (value: unknown): string => (isError(value) ? value.message : String(value))\n      throw new E_VECTOR_STORE_MIGRATION_FAILED([lastApplied, msg(err)])\n    }\n  }\n}\n"],"mappings":";;;;;;;;;AAmCA,IAAa,iBAAb,MAA4B;CAC1B;CACA;CACA;CAEA,YAAY,MAA4B;EACtC,KAAKA,cAAc,KAAK;EACxB,KAAKC,UAAU,KAAK;EACpB,KAAKC,UAAU,KAAK;CACtB;CAEA,MAAM,SAA4B;EAChC,MAAM,UAAU,MAAM,KAAKD,QAAQ,QAAQ;EAC3C,MAAM,UAAU,KAAKD,YAAY,QAAQ,MAAM,CAAC,QAAQ,SAAS,EAAE,IAAI,CAAC;EAExE,MAAM,iBAA2B,CAAC;EAElC,KAAK,MAAM,aAAa,SACtB,IAAI;GACF,MAAM,UAAU,GAAG,EAAE,QAAQ,KAAKE,QAAQ,CAAC;GAC3C,MAAM,KAAKD,QAAQ,OAAO,UAAU,IAAI;GACxC,eAAe,KAAK,UAAU,IAAI;EACpC,SAAS,KAAK;GACZ,MAAM,OAAO,UAA4B,QAAQ,KAAK,IAAI,MAAM,UAAU,OAAO,KAAK;GACtF,MAAM,IAAI,gCAAgC,CAAC,UAAU,MAAM,IAAI,GAAG,CAAC,CAAC;EACtE;EAGF,OAAO;CACT;CAEA,MAAM,WAAmC;EACvC,MAAM,UAAU,MAAM,KAAKA,QAAQ,QAAQ;EAE3C,IAAI,QAAQ,WAAW,GACrB,OAAO;EAGT,MAAM,cAAc,QAAQ,QAAQ,SAAS;EAC7C,MAAM,YAAY,KAAKD,YAAY,MAAM,MAAM,EAAE,SAAS,WAAW;EAErE,IAAI,CAAC,WACH,MAAM,IAAI,gCAAgC,CAAC,aAAa,4BAA4B,CAAC;EAGvF,IAAI;GACF,MAAM,UAAU,KAAK,EAAE,QAAQ,KAAKE,QAAQ,CAAC;GAC7C,MAAM,KAAKD,QAAQ,OAAO,WAAW;GACrC,OAAO;EACT,SAAS,KAAK;GACZ,MAAM,OAAO,UAA4B,QAAQ,KAAK,IAAI,MAAM,UAAU,OAAO,KAAK;GACtF,MAAM,IAAI,gCAAgC,CAAC,aAAa,IAAI,GAAG,CAAC,CAAC;EACnE;CACF;AACF"}
+{"version":3,"file":"migrate.mjs","names":["#migrations","#ledger","#schema"],"sources":["../../../src/batteries/vector/migrate.ts"],"sourcesContent":["/**\n * Knex-style migration runner for the vector battery.\n *\n * @module @nhtio/adk/batteries/vector/migrate\n */\n\nimport { isError } from '@nhtio/adk/guards'\nimport { E_VECTOR_STORE_MIGRATION_FAILED } from './exceptions'\nimport type { VectorSchemaBuilder } from './schema'\n\n/** The context passed to each migration's `up`/`down` — exposes the schema builder. */\nexport interface VectorMigrationContext {\n  /** Schema facade for performing collection DDL within the migration. */\n  schema: VectorSchemaBuilder\n}\n\n/** A single migration module: a name plus its forward (`up`) and reverse (`down`) steps. */\nexport interface VectorMigration {\n  /** Unique migration name, used as its ledger key. */\n  name: string\n  /** Apply the migration. */\n  up: (ctx: VectorMigrationContext) => Promise<void>\n  /** Reverse the migration. */\n  down: (ctx: VectorMigrationContext) => Promise<void>\n}\n\n/** Persistence for which migrations have run; backed by a store-provided implementation. */\nexport interface MigrationLedger {\n  /** Resolve the names of migrations already applied, in application order. */\n  applied(): Promise<string[]>\n  /** Record `name` as applied. */\n  record(name: string): Promise<void>\n  /** Remove `name` from the applied set (on rollback). */\n  remove(name: string): Promise<void>\n}\n\n/** Construction options for a {@link VectorMigrator}. */\nexport interface VectorMigrateOptions {\n  /** The ordered set of migration modules. */\n  migrations: VectorMigration[]\n  /** Ledger tracking which migrations have run. */\n  ledger: MigrationLedger\n  /** Schema facade handed to each migration. */\n  schema: VectorSchemaBuilder\n}\n\n/** Knex-style migration runner: applies pending migrations forward and rolls the last one back. */\nexport class VectorMigrator {\n  readonly #migrations: VectorMigration[]\n  readonly #ledger: MigrationLedger\n  readonly #schema: VectorSchemaBuilder\n\n  /**\n   * @param opts - The migrations, ledger, and schema facade to run against.\n   */\n  constructor(opts: VectorMigrateOptions) {\n    this.#migrations = opts.migrations\n    this.#ledger = opts.ledger\n    this.#schema = opts.schema\n  }\n\n  /**\n   * Apply every not-yet-applied migration in order, recording each in the ledger.\n   *\n   * @returns The names of the migrations applied during this run.\n   * @throws {@link @nhtio/adk/batteries!E_VECTOR_STORE_MIGRATION_FAILED} when a migration's `up` throws.\n   */\n  async latest(): Promise<string[]> {\n    const applied = await this.#ledger.applied()\n    const toApply = this.#migrations.filter((m) => !applied.includes(m.name))\n\n    const appliedThisRun: string[] = []\n\n    for (const migration of toApply) {\n      try {\n        await migration.up({ schema: this.#schema })\n        await this.#ledger.record(migration.name)\n        appliedThisRun.push(migration.name)\n      } catch (err) {\n        const msg = (value: unknown): string => (isError(value) ? value.message : String(value))\n        throw new E_VECTOR_STORE_MIGRATION_FAILED([migration.name, msg(err)])\n      }\n    }\n\n    return appliedThisRun\n  }\n\n  /**\n   * Reverse the most recently applied migration and remove it from the ledger.\n   *\n   * @returns The name of the rolled-back migration, or `null` when nothing was applied.\n   * @throws {@link @nhtio/adk/batteries!E_VECTOR_STORE_MIGRATION_FAILED} when the migration module is missing or\n   *   its `down` throws.\n   */\n  async rollback(): Promise<string | null> {\n    const applied = await this.#ledger.applied()\n\n    if (applied.length === 0) {\n      return null\n    }\n\n    const lastApplied = applied[applied.length - 1]\n    const migration = this.#migrations.find((m) => m.name === lastApplied)\n\n    if (!migration) {\n      throw new E_VECTOR_STORE_MIGRATION_FAILED([lastApplied, 'migration module not found'])\n    }\n\n    try {\n      await migration.down({ schema: this.#schema })\n      await this.#ledger.remove(lastApplied)\n      return lastApplied\n    } catch (err) {\n      const msg = (value: unknown): string => (isError(value) ? value.message : String(value))\n      throw new E_VECTOR_STORE_MIGRATION_FAILED([lastApplied, msg(err)])\n    }\n  }\n}\n"],"mappings":";;;;;;;;;;AA+CA,IAAa,iBAAb,MAA4B;CAC1B;CACA;CACA;;;;CAKA,YAAY,MAA4B;EACtC,KAAKA,cAAc,KAAK;EACxB,KAAKC,UAAU,KAAK;EACpB,KAAKC,UAAU,KAAK;CACtB;;;;;;;CAQA,MAAM,SAA4B;EAChC,MAAM,UAAU,MAAM,KAAKD,QAAQ,QAAQ;EAC3C,MAAM,UAAU,KAAKD,YAAY,QAAQ,MAAM,CAAC,QAAQ,SAAS,EAAE,IAAI,CAAC;EAExE,MAAM,iBAA2B,CAAC;EAElC,KAAK,MAAM,aAAa,SACtB,IAAI;GACF,MAAM,UAAU,GAAG,EAAE,QAAQ,KAAKE,QAAQ,CAAC;GAC3C,MAAM,KAAKD,QAAQ,OAAO,UAAU,IAAI;GACxC,eAAe,KAAK,UAAU,IAAI;EACpC,SAAS,KAAK;GACZ,MAAM,OAAO,UAA4B,QAAQ,KAAK,IAAI,MAAM,UAAU,OAAO,KAAK;GACtF,MAAM,IAAI,gCAAgC,CAAC,UAAU,MAAM,IAAI,GAAG,CAAC,CAAC;EACtE;EAGF,OAAO;CACT;;;;;;;;CASA,MAAM,WAAmC;EACvC,MAAM,UAAU,MAAM,KAAKA,QAAQ,QAAQ;EAE3C,IAAI,QAAQ,WAAW,GACrB,OAAO;EAGT,MAAM,cAAc,QAAQ,QAAQ,SAAS;EAC7C,MAAM,YAAY,KAAKD,YAAY,MAAM,MAAM,EAAE,SAAS,WAAW;EAErE,IAAI,CAAC,WACH,MAAM,IAAI,gCAAgC,CAAC,aAAa,4BAA4B,CAAC;EAGvF,IAAI;GACF,MAAM,UAAU,KAAK,EAAE,QAAQ,KAAKE,QAAQ,CAAC;GAC7C,MAAM,KAAKD,QAAQ,OAAO,WAAW;GACrC,OAAO;EACT,SAAS,KAAK;GACZ,MAAM,OAAO,UAA4B,QAAQ,KAAK,IAAI,MAAM,UAAU,OAAO,KAAK;GACtF,MAAM,IAAI,gCAAgC,CAAC,aAAa,IAAI,GAAG,CAAC,CAAC;EACnE;CACF;AACF"}

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

@@ -6,6 +6,7 @@ import type { VectorFilter } from "../filters";
 import type { SearchPlan, UpsertPlan, DeletePlan, CollectionSpec } from "../plan";
 import type { VectorMatch, VectorStoreCapabilities, BaseVectorStoreOptions } from "../types";
 export interface MilvusVectorStoreOptions extends BaseVectorStoreOptions {
+    /** Connection and authentication parameters for the backend. */
     connection?: {
         address?: string;
         url?: string;
@@ -18,6 +19,7 @@ export interface MilvusVectorStoreOptions extends BaseVectorStoreOptions {
 export declare class MilvusVectorStore extends BaseVectorStore {
     #private;
     readonly capabilities: VectorStoreCapabilities;
+    /** Static availability probe: whether this adapter's runtime driver can load in the current environment. */
     static isAvailable(): boolean;
     isAvailable(): boolean;
     connect(): Promise<void>;
@@ -29,7 +31,10 @@ export declare class MilvusVectorStore extends BaseVectorStore {
     executeUpsert(plan: UpsertPlan): Promise<void>;
     executeSearch(plan: SearchPlan): Promise<VectorMatch[]>;
     executeDelete(plan: DeletePlan): Promise<void>;
+    /** Project a raw Milvus hit into a {@link VectorMatch} per the requested projection, normalizing its score. */
     projectHit(hit: any, projection: any, metric: string): VectorMatch;
+    /** Instance wrapper over the module-level {@link translateMilvusFilter}. */
     translateMilvusFilter(filter?: VectorFilter): string;
 }
+/** Translate a neutral {@link VectorFilter} into a Milvus boolean filter expression string. */
 export declare const translateMilvusFilter: (filter?: VectorFilter) => string;

package/batteries/vector/milvus.cjs

@@ -47,6 +47,7 @@ var MilvusVectorStore = class extends require_batteries_vector_contract.BaseVect
 	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";
 	}
@@ -271,6 +272,7 @@ var MilvusVectorStore = class extends require_batteries_vector_contract.BaseVect
 			throw new require_batteries_vector_exceptions.E_VECTOR_STORE_DELETE_FAILED([String(err)]);
 		}
 	}
+	/** Project a raw Milvus hit into a {@link VectorMatch} per the requested projection, normalizing its score. */
 	projectHit(hit, projection, metric) {
 		const out = {};
 		if (projection.id) out.id = hit.id;
@@ -283,10 +285,12 @@ var MilvusVectorStore = class extends require_batteries_vector_contract.BaseVect
 		}
 		return out;
 	}
+	/** Instance wrapper over the module-level {@link translateMilvusFilter}. */
 	translateMilvusFilter(filter) {
 		return translateMilvusFilter(filter);
 	}
 };
+/** Translate a neutral {@link VectorFilter} into a Milvus boolean filter expression string. */
 var translateMilvusFilter = (filter) => {
 	if (!filter) return "";
 	if (require_batteries_vector_filters.isRawFilter(filter)) {