@nhtio/adk 1.20260604.0 → 1.20260607.0

package/batteries/vector/filters.cjs

@@ -0,0 +1,107 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+require("../../chunk-Ble4zEEl.js");
+const require_tool_registry = require("../../tool_registry-DYUYqXvo.js");
+require("../../guards.cjs");
+let _nhtio_validation = require("@nhtio/validation");
+//#region src/batteries/vector/filters.ts
+/**
+* Filter types and evaluator for the vector battery.
+*
+* @module @nhtio/adk/batteries/vector/filters
+*/
+var raw = (sql, bindings = []) => ({
+	__raw: sql,
+	bindings
+});
+var isRawExpr = (v) => require_tool_registry.isObject(v) && typeof v.__raw === "string" && Array.isArray(v.bindings);
+var isFilterCondition = (f) => typeof f.field === "string" && typeof f.op === "string";
+var isRawFilter = (f) => typeof f.$dialect === "string";
+var isFilterGroup = (f) => !isFilterCondition(f) && !isRawFilter(f);
+var rawFilterSchema = _nhtio_validation.validator.object({
+	$dialect: _nhtio_validation.validator.string().required(),
+	$raw: _nhtio_validation.validator.alternatives(_nhtio_validation.validator.string(), _nhtio_validation.validator.any()).required(),
+	$bindings: _nhtio_validation.validator.array().items(_nhtio_validation.validator.any()).optional()
+});
+var filterConditionSchema = _nhtio_validation.validator.object({
+	field: _nhtio_validation.validator.string().required(),
+	op: _nhtio_validation.validator.string().valid("eq", "ne", "gt", "gte", "lt", "lte", "in", "nin", "exists", "contains").required(),
+	value: _nhtio_validation.validator.alternatives(_nhtio_validation.validator.any(), _nhtio_validation.validator.array().items(_nhtio_validation.validator.any())).optional()
+});
+var vectorFilterSchema = _nhtio_validation.validator.alternatives(filterConditionSchema, rawFilterSchema, _nhtio_validation.validator.object({
+	and: _nhtio_validation.validator.array().items(_nhtio_validation.validator.link("#vectorFilter")).optional(),
+	or: _nhtio_validation.validator.array().items(_nhtio_validation.validator.link("#vectorFilter")).optional(),
+	not: _nhtio_validation.validator.link("#vectorFilter").optional()
+}).unknown(false)).id("vectorFilter");
+var getField = (metadata, path) => {
+	const keys = path.split(".");
+	let current = metadata;
+	for (const key of keys) {
+		if (current === void 0 || current === null) return;
+		if (typeof current !== "object") return;
+		current = current[key];
+	}
+	return current;
+};
+var evaluateFilter = (filter, metadata) => {
+	if (isRawFilter(filter)) throw new Error("raw filters are not evaluable by the in-memory filter evaluator");
+	if (isFilterCondition(filter)) {
+		const { field, op, value } = filter;
+		const fieldVal = getField(metadata, field);
+		if (isRawExpr(value)) throw new Error("raw expressions are not evaluable by the in-memory filter evaluator");
+		switch (op) {
+			case "eq": return fieldVal === value;
+			case "ne": return fieldVal !== value;
+			case "gt":
+				if (fieldVal === void 0 || value === void 0) return false;
+				if (typeof fieldVal === "number" && typeof value === "number") return fieldVal > value;
+				if (typeof fieldVal === "string" && typeof value === "string") return fieldVal > value;
+				return false;
+			case "gte":
+				if (fieldVal === void 0 || value === void 0) return false;
+				if (typeof fieldVal === "number" && typeof value === "number") return fieldVal >= value;
+				if (typeof fieldVal === "string" && typeof value === "string") return fieldVal >= value;
+				return false;
+			case "lt":
+				if (fieldVal === void 0 || value === void 0) return false;
+				if (typeof fieldVal === "number" && typeof value === "number") return fieldVal < value;
+				if (typeof fieldVal === "string" && typeof value === "string") return fieldVal < value;
+				return false;
+			case "lte":
+				if (fieldVal === void 0 || value === void 0) return false;
+				if (typeof fieldVal === "number" && typeof value === "number") return fieldVal <= value;
+				if (typeof fieldVal === "string" && typeof value === "string") return fieldVal <= value;
+				return false;
+			case "in":
+				if (!Array.isArray(value)) return false;
+				return value.includes(fieldVal);
+			case "nin":
+				if (!Array.isArray(value)) return true;
+				return !value.includes(fieldVal);
+			case "exists": return value === void 0 || value === true ? fieldVal !== void 0 : fieldVal === void 0;
+			case "contains":
+				if (fieldVal === void 0) return false;
+				if (Array.isArray(fieldVal)) return fieldVal.includes(value);
+				if (typeof fieldVal === "string") return fieldVal.includes(String(value));
+				return false;
+			default: return false;
+		}
+	}
+	if (isFilterGroup(filter)) {
+		const { and, or, not } = filter;
+		if (and !== void 0) return and.every((child) => evaluateFilter(child, metadata));
+		if (or !== void 0) return or.some((child) => evaluateFilter(child, metadata));
+		if (not !== void 0) return !evaluateFilter(not, metadata);
+		return true;
+	}
+	return false;
+};
+//#endregion
+exports.evaluateFilter = evaluateFilter;
+exports.isFilterCondition = isFilterCondition;
+exports.isFilterGroup = isFilterGroup;
+exports.isRawExpr = isRawExpr;
+exports.isRawFilter = isRawFilter;
+exports.raw = raw;
+exports.vectorFilterSchema = vectorFilterSchema;
+
+//# sourceMappingURL=filters.cjs.map

package/batteries/vector/filters.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"filters.cjs","names":[],"sources":["../../../src/batteries/vector/filters.ts"],"sourcesContent":["/**\n * Filter types and evaluator for the vector battery.\n *\n * @module @nhtio/adk/batteries/vector/filters\n */\n\nimport { isObject } from '@nhtio/adk/guards'\nimport { validator } from '@nhtio/validation'\nimport type { VectorMetadata, VectorMetadataValue } from './types'\n\nexport type FilterOperator =\n  | 'eq'\n  | 'ne'\n  | 'gt'\n  | 'gte'\n  | 'lt'\n  | 'lte'\n  | 'in'\n  | 'nin'\n  | 'exists'\n  | 'contains'\n\nexport interface RawExpr {\n  __raw: string\n  bindings: unknown[]\n}\n\nexport const raw = (sql: string, bindings: unknown[] = []): RawExpr => ({ __raw: sql, bindings })\n\nexport const isRawExpr = (v: unknown): v is RawExpr =>\n  isObject(v) && typeof v.__raw === 'string' && Array.isArray(v.bindings)\n\nexport interface FilterCondition {\n  field: string\n  op: FilterOperator\n  value?: VectorMetadataValue | VectorMetadataValue[] | RawExpr\n}\nexport interface FilterGroup {\n  and?: VectorFilter[]\n  or?: VectorFilter[]\n  not?: VectorFilter\n}\nexport interface RawFilter {\n  $dialect: string\n  $raw: string | unknown\n  $bindings?: unknown[]\n}\nexport type VectorFilter = FilterCondition | FilterGroup | RawFilter\n\nexport const isFilterCondition = (f: VectorFilter): f is FilterCondition =>\n  typeof (f as FilterCondition).field === 'string' && typeof (f as FilterCondition).op === 'string'\n\nexport const isRawFilter = (f: VectorFilter): f is RawFilter =>\n  typeof (f as RawFilter).$dialect === 'string'\n\nexport const isFilterGroup = (f: VectorFilter): f is FilterGroup =>\n  !isFilterCondition(f) && !isRawFilter(f)\n\nconst rawFilterSchema = validator.object<RawFilter>({\n  $dialect: validator.string().required(),\n  // eslint-disable-next-line adk/require-validator-any-required -- value type-arg: $raw is any structured dialect payload; disposition is set by the .required() on the alternatives\n  $raw: validator.alternatives(validator.string(), validator.any()).required(),\n  // eslint-disable-next-line adk/require-validator-any-required -- item type-arg: bindings hold arbitrary values; disposition is set by .optional() on the array\n  $bindings: validator.array().items(validator.any()).optional(),\n})\n\nconst filterConditionSchema = validator.object<FilterCondition>({\n  field: validator.string().required(),\n  op: validator\n    .string()\n    .valid('eq', 'ne', 'gt', 'gte', 'lt', 'lte', 'in', 'nin', 'exists', 'contains')\n    .required(),\n  value: validator\n    // eslint-disable-next-line adk/require-validator-any-required -- value type-arg: a filter value is any scalar or array of any; disposition is set by .optional() below\n    .alternatives(validator.any(), validator.array().items(validator.any()))\n    .optional(),\n})\n\nexport const vectorFilterSchema = validator\n  .alternatives(\n    filterConditionSchema,\n    rawFilterSchema,\n    validator\n      .object<FilterGroup>({\n        and: validator.array().items(validator.link('#vectorFilter')).optional(),\n        or: validator.array().items(validator.link('#vectorFilter')).optional(),\n        not: validator.link('#vectorFilter').optional(),\n      })\n      .unknown(false)\n  )\n  .id('vectorFilter')\n\nconst getField = (metadata: VectorMetadata, path: string): VectorMetadataValue | undefined => {\n  const keys = path.split('.')\n  let current: VectorMetadataValue | undefined = metadata\n  for (const key of keys) {\n    if (current === undefined || current === null) {\n      return undefined\n    }\n    if (typeof current !== 'object') {\n      return undefined\n    }\n    current = (current as Record<string, VectorMetadataValue>)[key]\n  }\n  return current\n}\n\nexport const evaluateFilter = (filter: VectorFilter, metadata: VectorMetadata): boolean => {\n  if (isRawFilter(filter)) {\n    throw new Error('raw filters are not evaluable by the in-memory filter evaluator')\n  }\n\n  if (isFilterCondition(filter)) {\n    const { field, op, value } = filter\n    const fieldVal = getField(metadata, field)\n\n    if (isRawExpr(value)) {\n      throw new Error('raw expressions are not evaluable by the in-memory filter evaluator')\n    }\n\n    switch (op) {\n      case 'eq': {\n        return fieldVal === value\n      }\n\n      case 'ne': {\n        return fieldVal !== value\n      }\n\n      case 'gt': {\n        if (fieldVal === undefined || value === undefined) {\n          return false\n        }\n        if (typeof fieldVal === 'number' && typeof value === 'number') {\n          return fieldVal > value\n        }\n        if (typeof fieldVal === 'string' && typeof value === 'string') {\n          return fieldVal > value\n        }\n        return false\n      }\n\n      case 'gte': {\n        if (fieldVal === undefined || value === undefined) {\n          return false\n        }\n        if (typeof fieldVal === 'number' && typeof value === 'number') {\n          return fieldVal >= value\n        }\n        if (typeof fieldVal === 'string' && typeof value === 'string') {\n          return fieldVal >= value\n        }\n        return false\n      }\n\n      case 'lt': {\n        if (fieldVal === undefined || value === undefined) {\n          return false\n        }\n        if (typeof fieldVal === 'number' && typeof value === 'number') {\n          return fieldVal < value\n        }\n        if (typeof fieldVal === 'string' && typeof value === 'string') {\n          return fieldVal < value\n        }\n        return false\n      }\n\n      case 'lte': {\n        if (fieldVal === undefined || value === undefined) {\n          return false\n        }\n        if (typeof fieldVal === 'number' && typeof value === 'number') {\n          return fieldVal <= value\n        }\n        if (typeof fieldVal === 'string' && typeof value === 'string') {\n          return fieldVal <= value\n        }\n        return false\n      }\n\n      case 'in': {\n        if (!Array.isArray(value)) {\n          return false\n        }\n        return value.includes(fieldVal as never)\n      }\n\n      case 'nin': {\n        if (!Array.isArray(value)) {\n          return true\n        }\n        return !value.includes(fieldVal as never)\n      }\n\n      case 'exists': {\n        const checkExists = value === undefined || value === true\n        return checkExists ? fieldVal !== undefined : fieldVal === undefined\n      }\n\n      case 'contains': {\n        if (fieldVal === undefined) {\n          return false\n        }\n        if (Array.isArray(fieldVal)) {\n          return fieldVal.includes(value as never)\n        }\n        if (typeof fieldVal === 'string') {\n          return fieldVal.includes(String(value))\n        }\n        return false\n      }\n\n      default: {\n        return false\n      }\n    }\n  }\n\n  if (isFilterGroup(filter)) {\n    const { and, or, not } = filter\n\n    if (and !== undefined) {\n      return and.every((child) => evaluateFilter(child, metadata))\n    }\n\n    if (or !== undefined) {\n      return or.some((child) => evaluateFilter(child, metadata))\n    }\n\n    if (not !== undefined) {\n      return !evaluateFilter(not, metadata)\n    }\n\n    return true\n  }\n\n  return false\n}\n"],"mappings":";;;;;;;;;;;AA2BA,IAAa,OAAO,KAAa,WAAsB,CAAC,OAAgB;CAAE,OAAO;CAAK;AAAS;AAE/F,IAAa,aAAa,MACxB,sBAAA,SAAS,CAAC,KAAK,OAAO,EAAE,UAAU,YAAY,MAAM,QAAQ,EAAE,QAAQ;AAmBxE,IAAa,qBAAqB,MAChC,OAAQ,EAAsB,UAAU,YAAY,OAAQ,EAAsB,OAAO;AAE3F,IAAa,eAAe,MAC1B,OAAQ,EAAgB,aAAa;AAEvC,IAAa,iBAAiB,MAC5B,CAAC,kBAAkB,CAAC,KAAK,CAAC,YAAY,CAAC;AAEzC,IAAM,kBAAkB,kBAAA,UAAU,OAAkB;CAClD,UAAU,kBAAA,UAAU,OAAO,EAAE,SAAS;CAEtC,MAAM,kBAAA,UAAU,aAAa,kBAAA,UAAU,OAAO,GAAG,kBAAA,UAAU,IAAI,CAAC,EAAE,SAAS;CAE3E,WAAW,kBAAA,UAAU,MAAM,EAAE,MAAM,kBAAA,UAAU,IAAI,CAAC,EAAE,SAAS;AAC/D,CAAC;AAED,IAAM,wBAAwB,kBAAA,UAAU,OAAwB;CAC9D,OAAO,kBAAA,UAAU,OAAO,EAAE,SAAS;CACnC,IAAI,kBAAA,UACD,OAAO,EACP,MAAM,MAAM,MAAM,MAAM,OAAO,MAAM,OAAO,MAAM,OAAO,UAAU,UAAU,EAC7E,SAAS;CACZ,OAAO,kBAAA,UAEJ,aAAa,kBAAA,UAAU,IAAI,GAAG,kBAAA,UAAU,MAAM,EAAE,MAAM,kBAAA,UAAU,IAAI,CAAC,CAAC,EACtE,SAAS;AACd,CAAC;AAED,IAAa,qBAAqB,kBAAA,UAC/B,aACC,uBACA,iBACA,kBAAA,UACG,OAAoB;CACnB,KAAK,kBAAA,UAAU,MAAM,EAAE,MAAM,kBAAA,UAAU,KAAK,eAAe,CAAC,EAAE,SAAS;CACvE,IAAI,kBAAA,UAAU,MAAM,EAAE,MAAM,kBAAA,UAAU,KAAK,eAAe,CAAC,EAAE,SAAS;CACtE,KAAK,kBAAA,UAAU,KAAK,eAAe,EAAE,SAAS;AAChD,CAAC,EACA,QAAQ,KAAK,CAClB,EACC,GAAG,cAAc;AAEpB,IAAM,YAAY,UAA0B,SAAkD;CAC5F,MAAM,OAAO,KAAK,MAAM,GAAG;CAC3B,IAAI,UAA2C;CAC/C,KAAK,MAAM,OAAO,MAAM;EACtB,IAAI,YAAY,KAAA,KAAa,YAAY,MACvC;EAEF,IAAI,OAAO,YAAY,UACrB;EAEF,UAAW,QAAgD;CAC7D;CACA,OAAO;AACT;AAEA,IAAa,kBAAkB,QAAsB,aAAsC;CACzF,IAAI,YAAY,MAAM,GACpB,MAAM,IAAI,MAAM,iEAAiE;CAGnF,IAAI,kBAAkB,MAAM,GAAG;EAC7B,MAAM,EAAE,OAAO,IAAI,UAAU;EAC7B,MAAM,WAAW,SAAS,UAAU,KAAK;EAEzC,IAAI,UAAU,KAAK,GACjB,MAAM,IAAI,MAAM,qEAAqE;EAGvF,QAAQ,IAAR;GACE,KAAK,MACH,OAAO,aAAa;GAGtB,KAAK,MACH,OAAO,aAAa;GAGtB,KAAK;IACH,IAAI,aAAa,KAAA,KAAa,UAAU,KAAA,GACtC,OAAO;IAET,IAAI,OAAO,aAAa,YAAY,OAAO,UAAU,UACnD,OAAO,WAAW;IAEpB,IAAI,OAAO,aAAa,YAAY,OAAO,UAAU,UACnD,OAAO,WAAW;IAEpB,OAAO;GAGT,KAAK;IACH,IAAI,aAAa,KAAA,KAAa,UAAU,KAAA,GACtC,OAAO;IAET,IAAI,OAAO,aAAa,YAAY,OAAO,UAAU,UACnD,OAAO,YAAY;IAErB,IAAI,OAAO,aAAa,YAAY,OAAO,UAAU,UACnD,OAAO,YAAY;IAErB,OAAO;GAGT,KAAK;IACH,IAAI,aAAa,KAAA,KAAa,UAAU,KAAA,GACtC,OAAO;IAET,IAAI,OAAO,aAAa,YAAY,OAAO,UAAU,UACnD,OAAO,WAAW;IAEpB,IAAI,OAAO,aAAa,YAAY,OAAO,UAAU,UACnD,OAAO,WAAW;IAEpB,OAAO;GAGT,KAAK;IACH,IAAI,aAAa,KAAA,KAAa,UAAU,KAAA,GACtC,OAAO;IAET,IAAI,OAAO,aAAa,YAAY,OAAO,UAAU,UACnD,OAAO,YAAY;IAErB,IAAI,OAAO,aAAa,YAAY,OAAO,UAAU,UACnD,OAAO,YAAY;IAErB,OAAO;GAGT,KAAK;IACH,IAAI,CAAC,MAAM,QAAQ,KAAK,GACtB,OAAO;IAET,OAAO,MAAM,SAAS,QAAiB;GAGzC,KAAK;IACH,IAAI,CAAC,MAAM,QAAQ,KAAK,GACtB,OAAO;IAET,OAAO,CAAC,MAAM,SAAS,QAAiB;GAG1C,KAAK,UAEH,OADoB,UAAU,KAAA,KAAa,UAAU,OAChC,aAAa,KAAA,IAAY,aAAa,KAAA;GAG7D,KAAK;IACH,IAAI,aAAa,KAAA,GACf,OAAO;IAET,IAAI,MAAM,QAAQ,QAAQ,GACxB,OAAO,SAAS,SAAS,KAAc;IAEzC,IAAI,OAAO,aAAa,UACtB,OAAO,SAAS,SAAS,OAAO,KAAK,CAAC;IAExC,OAAO;GAGT,SACE,OAAO;EAEX;CACF;CAEA,IAAI,cAAc,MAAM,GAAG;EACzB,MAAM,EAAE,KAAK,IAAI,QAAQ;EAEzB,IAAI,QAAQ,KAAA,GACV,OAAO,IAAI,OAAO,UAAU,eAAe,OAAO,QAAQ,CAAC;EAG7D,IAAI,OAAO,KAAA,GACT,OAAO,GAAG,MAAM,UAAU,eAAe,OAAO,QAAQ,CAAC;EAG3D,IAAI,QAAQ,KAAA,GACV,OAAO,CAAC,eAAe,KAAK,QAAQ;EAGtC,OAAO;CACT;CAEA,OAAO;AACT"}

package/batteries/vector/filters.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Filter types and evaluator for the vector battery.
+ *
+ * @module @nhtio/adk/batteries/vector/filters
+ */
+import type { VectorMetadata, VectorMetadataValue } from "./types";
+export type FilterOperator = 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'nin' | 'exists' | 'contains';
+export interface RawExpr {
+    __raw: string;
+    bindings: unknown[];
+}
+export declare const raw: (sql: string, bindings?: unknown[]) => RawExpr;
+export declare const isRawExpr: (v: unknown) => v is RawExpr;
+export interface FilterCondition {
+    field: string;
+    op: FilterOperator;
+    value?: VectorMetadataValue | VectorMetadataValue[] | RawExpr;
+}
+export interface FilterGroup {
+    and?: VectorFilter[];
+    or?: VectorFilter[];
+    not?: VectorFilter;
+}
+export interface RawFilter {
+    $dialect: string;
+    $raw: string | unknown;
+    $bindings?: unknown[];
+}
+export type VectorFilter = FilterCondition | FilterGroup | RawFilter;
+export declare const isFilterCondition: (f: VectorFilter) => f is FilterCondition;
+export declare const isRawFilter: (f: VectorFilter) => f is RawFilter;
+export declare const isFilterGroup: (f: VectorFilter) => f is FilterGroup;
+export declare const vectorFilterSchema: import("@nhtio/validation").AlternativesSchema<any>;
+export declare const evaluateFilter: (filter: VectorFilter, metadata: VectorMetadata) => boolean;

package/batteries/vector/filters.mjs

@@ -0,0 +1,99 @@
+import { c as isObject } from "../../tool_registry-D1pSSlsd.mjs";
+import "../../guards.mjs";
+import { validator } from "@nhtio/validation";
+//#region src/batteries/vector/filters.ts
+/**
+* Filter types and evaluator for the vector battery.
+*
+* @module @nhtio/adk/batteries/vector/filters
+*/
+var raw = (sql, bindings = []) => ({
+	__raw: sql,
+	bindings
+});
+var isRawExpr = (v) => isObject(v) && typeof v.__raw === "string" && Array.isArray(v.bindings);
+var isFilterCondition = (f) => typeof f.field === "string" && typeof f.op === "string";
+var isRawFilter = (f) => typeof f.$dialect === "string";
+var isFilterGroup = (f) => !isFilterCondition(f) && !isRawFilter(f);
+var rawFilterSchema = validator.object({
+	$dialect: validator.string().required(),
+	$raw: validator.alternatives(validator.string(), validator.any()).required(),
+	$bindings: validator.array().items(validator.any()).optional()
+});
+var filterConditionSchema = validator.object({
+	field: validator.string().required(),
+	op: validator.string().valid("eq", "ne", "gt", "gte", "lt", "lte", "in", "nin", "exists", "contains").required(),
+	value: validator.alternatives(validator.any(), validator.array().items(validator.any())).optional()
+});
+var vectorFilterSchema = validator.alternatives(filterConditionSchema, rawFilterSchema, validator.object({
+	and: validator.array().items(validator.link("#vectorFilter")).optional(),
+	or: validator.array().items(validator.link("#vectorFilter")).optional(),
+	not: validator.link("#vectorFilter").optional()
+}).unknown(false)).id("vectorFilter");
+var getField = (metadata, path) => {
+	const keys = path.split(".");
+	let current = metadata;
+	for (const key of keys) {
+		if (current === void 0 || current === null) return;
+		if (typeof current !== "object") return;
+		current = current[key];
+	}
+	return current;
+};
+var evaluateFilter = (filter, metadata) => {
+	if (isRawFilter(filter)) throw new Error("raw filters are not evaluable by the in-memory filter evaluator");
+	if (isFilterCondition(filter)) {
+		const { field, op, value } = filter;
+		const fieldVal = getField(metadata, field);
+		if (isRawExpr(value)) throw new Error("raw expressions are not evaluable by the in-memory filter evaluator");
+		switch (op) {
+			case "eq": return fieldVal === value;
+			case "ne": return fieldVal !== value;
+			case "gt":
+				if (fieldVal === void 0 || value === void 0) return false;
+				if (typeof fieldVal === "number" && typeof value === "number") return fieldVal > value;
+				if (typeof fieldVal === "string" && typeof value === "string") return fieldVal > value;
+				return false;
+			case "gte":
+				if (fieldVal === void 0 || value === void 0) return false;
+				if (typeof fieldVal === "number" && typeof value === "number") return fieldVal >= value;
+				if (typeof fieldVal === "string" && typeof value === "string") return fieldVal >= value;
+				return false;
+			case "lt":
+				if (fieldVal === void 0 || value === void 0) return false;
+				if (typeof fieldVal === "number" && typeof value === "number") return fieldVal < value;
+				if (typeof fieldVal === "string" && typeof value === "string") return fieldVal < value;
+				return false;
+			case "lte":
+				if (fieldVal === void 0 || value === void 0) return false;
+				if (typeof fieldVal === "number" && typeof value === "number") return fieldVal <= value;
+				if (typeof fieldVal === "string" && typeof value === "string") return fieldVal <= value;
+				return false;
+			case "in":
+				if (!Array.isArray(value)) return false;
+				return value.includes(fieldVal);
+			case "nin":
+				if (!Array.isArray(value)) return true;
+				return !value.includes(fieldVal);
+			case "exists": return value === void 0 || value === true ? fieldVal !== void 0 : fieldVal === void 0;
+			case "contains":
+				if (fieldVal === void 0) return false;
+				if (Array.isArray(fieldVal)) return fieldVal.includes(value);
+				if (typeof fieldVal === "string") return fieldVal.includes(String(value));
+				return false;
+			default: return false;
+		}
+	}
+	if (isFilterGroup(filter)) {
+		const { and, or, not } = filter;
+		if (and !== void 0) return and.every((child) => evaluateFilter(child, metadata));
+		if (or !== void 0) return or.some((child) => evaluateFilter(child, metadata));
+		if (not !== void 0) return !evaluateFilter(not, metadata);
+		return true;
+	}
+	return false;
+};
+//#endregion
+export { evaluateFilter, isFilterCondition, isFilterGroup, isRawExpr, isRawFilter, raw, vectorFilterSchema };
+
+//# sourceMappingURL=filters.mjs.map

package/batteries/vector/filters.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"filters.mjs","names":[],"sources":["../../../src/batteries/vector/filters.ts"],"sourcesContent":["/**\n * Filter types and evaluator for the vector battery.\n *\n * @module @nhtio/adk/batteries/vector/filters\n */\n\nimport { isObject } from '@nhtio/adk/guards'\nimport { validator } from '@nhtio/validation'\nimport type { VectorMetadata, VectorMetadataValue } from './types'\n\nexport type FilterOperator =\n  | 'eq'\n  | 'ne'\n  | 'gt'\n  | 'gte'\n  | 'lt'\n  | 'lte'\n  | 'in'\n  | 'nin'\n  | 'exists'\n  | 'contains'\n\nexport interface RawExpr {\n  __raw: string\n  bindings: unknown[]\n}\n\nexport const raw = (sql: string, bindings: unknown[] = []): RawExpr => ({ __raw: sql, bindings })\n\nexport const isRawExpr = (v: unknown): v is RawExpr =>\n  isObject(v) && typeof v.__raw === 'string' && Array.isArray(v.bindings)\n\nexport interface FilterCondition {\n  field: string\n  op: FilterOperator\n  value?: VectorMetadataValue | VectorMetadataValue[] | RawExpr\n}\nexport interface FilterGroup {\n  and?: VectorFilter[]\n  or?: VectorFilter[]\n  not?: VectorFilter\n}\nexport interface RawFilter {\n  $dialect: string\n  $raw: string | unknown\n  $bindings?: unknown[]\n}\nexport type VectorFilter = FilterCondition | FilterGroup | RawFilter\n\nexport const isFilterCondition = (f: VectorFilter): f is FilterCondition =>\n  typeof (f as FilterCondition).field === 'string' && typeof (f as FilterCondition).op === 'string'\n\nexport const isRawFilter = (f: VectorFilter): f is RawFilter =>\n  typeof (f as RawFilter).$dialect === 'string'\n\nexport const isFilterGroup = (f: VectorFilter): f is FilterGroup =>\n  !isFilterCondition(f) && !isRawFilter(f)\n\nconst rawFilterSchema = validator.object<RawFilter>({\n  $dialect: validator.string().required(),\n  // eslint-disable-next-line adk/require-validator-any-required -- value type-arg: $raw is any structured dialect payload; disposition is set by the .required() on the alternatives\n  $raw: validator.alternatives(validator.string(), validator.any()).required(),\n  // eslint-disable-next-line adk/require-validator-any-required -- item type-arg: bindings hold arbitrary values; disposition is set by .optional() on the array\n  $bindings: validator.array().items(validator.any()).optional(),\n})\n\nconst filterConditionSchema = validator.object<FilterCondition>({\n  field: validator.string().required(),\n  op: validator\n    .string()\n    .valid('eq', 'ne', 'gt', 'gte', 'lt', 'lte', 'in', 'nin', 'exists', 'contains')\n    .required(),\n  value: validator\n    // eslint-disable-next-line adk/require-validator-any-required -- value type-arg: a filter value is any scalar or array of any; disposition is set by .optional() below\n    .alternatives(validator.any(), validator.array().items(validator.any()))\n    .optional(),\n})\n\nexport const vectorFilterSchema = validator\n  .alternatives(\n    filterConditionSchema,\n    rawFilterSchema,\n    validator\n      .object<FilterGroup>({\n        and: validator.array().items(validator.link('#vectorFilter')).optional(),\n        or: validator.array().items(validator.link('#vectorFilter')).optional(),\n        not: validator.link('#vectorFilter').optional(),\n      })\n      .unknown(false)\n  )\n  .id('vectorFilter')\n\nconst getField = (metadata: VectorMetadata, path: string): VectorMetadataValue | undefined => {\n  const keys = path.split('.')\n  let current: VectorMetadataValue | undefined = metadata\n  for (const key of keys) {\n    if (current === undefined || current === null) {\n      return undefined\n    }\n    if (typeof current !== 'object') {\n      return undefined\n    }\n    current = (current as Record<string, VectorMetadataValue>)[key]\n  }\n  return current\n}\n\nexport const evaluateFilter = (filter: VectorFilter, metadata: VectorMetadata): boolean => {\n  if (isRawFilter(filter)) {\n    throw new Error('raw filters are not evaluable by the in-memory filter evaluator')\n  }\n\n  if (isFilterCondition(filter)) {\n    const { field, op, value } = filter\n    const fieldVal = getField(metadata, field)\n\n    if (isRawExpr(value)) {\n      throw new Error('raw expressions are not evaluable by the in-memory filter evaluator')\n    }\n\n    switch (op) {\n      case 'eq': {\n        return fieldVal === value\n      }\n\n      case 'ne': {\n        return fieldVal !== value\n      }\n\n      case 'gt': {\n        if (fieldVal === undefined || value === undefined) {\n          return false\n        }\n        if (typeof fieldVal === 'number' && typeof value === 'number') {\n          return fieldVal > value\n        }\n        if (typeof fieldVal === 'string' && typeof value === 'string') {\n          return fieldVal > value\n        }\n        return false\n      }\n\n      case 'gte': {\n        if (fieldVal === undefined || value === undefined) {\n          return false\n        }\n        if (typeof fieldVal === 'number' && typeof value === 'number') {\n          return fieldVal >= value\n        }\n        if (typeof fieldVal === 'string' && typeof value === 'string') {\n          return fieldVal >= value\n        }\n        return false\n      }\n\n      case 'lt': {\n        if (fieldVal === undefined || value === undefined) {\n          return false\n        }\n        if (typeof fieldVal === 'number' && typeof value === 'number') {\n          return fieldVal < value\n        }\n        if (typeof fieldVal === 'string' && typeof value === 'string') {\n          return fieldVal < value\n        }\n        return false\n      }\n\n      case 'lte': {\n        if (fieldVal === undefined || value === undefined) {\n          return false\n        }\n        if (typeof fieldVal === 'number' && typeof value === 'number') {\n          return fieldVal <= value\n        }\n        if (typeof fieldVal === 'string' && typeof value === 'string') {\n          return fieldVal <= value\n        }\n        return false\n      }\n\n      case 'in': {\n        if (!Array.isArray(value)) {\n          return false\n        }\n        return value.includes(fieldVal as never)\n      }\n\n      case 'nin': {\n        if (!Array.isArray(value)) {\n          return true\n        }\n        return !value.includes(fieldVal as never)\n      }\n\n      case 'exists': {\n        const checkExists = value === undefined || value === true\n        return checkExists ? fieldVal !== undefined : fieldVal === undefined\n      }\n\n      case 'contains': {\n        if (fieldVal === undefined) {\n          return false\n        }\n        if (Array.isArray(fieldVal)) {\n          return fieldVal.includes(value as never)\n        }\n        if (typeof fieldVal === 'string') {\n          return fieldVal.includes(String(value))\n        }\n        return false\n      }\n\n      default: {\n        return false\n      }\n    }\n  }\n\n  if (isFilterGroup(filter)) {\n    const { and, or, not } = filter\n\n    if (and !== undefined) {\n      return and.every((child) => evaluateFilter(child, metadata))\n    }\n\n    if (or !== undefined) {\n      return or.some((child) => evaluateFilter(child, metadata))\n    }\n\n    if (not !== undefined) {\n      return !evaluateFilter(not, metadata)\n    }\n\n    return true\n  }\n\n  return false\n}\n"],"mappings":"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"}

package/batteries/vector/helpers.cjs

@@ -0,0 +1,23 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+require("../../chunk-Ble4zEEl.js");
+//#region src/batteries/vector/helpers.ts
+var clamp01 = (n) => Math.min(1, Math.max(0, n));
+var normalizeScore = (raw, metric, kind) => {
+	if (metric === "cosine") if (kind === "similarity") return clamp01((raw + 1) / 2);
+	else return clamp01((1 - raw + 1) / 2);
+	else if (metric === "dot") if (kind === "similarity") return clamp01(1 / (1 + Math.exp(-raw)));
+	else return clamp01(1 / (1 + Math.exp(raw)));
+	else if (metric === "euclidean") return clamp01(1 / (1 + Math.max(0, raw)));
+	else return clamp01(raw);
+};
+var mapMetric = (metric, map) => map[metric];
+var dimensionsMatch = (vector, expected) => expected === void 0 ? true : vector.length === expected;
+var isFiniteVector = (vector) => Array.isArray(vector) && vector.every((n) => typeof n === "number" && Number.isFinite(n));
+//#endregion
+exports.clamp01 = clamp01;
+exports.dimensionsMatch = dimensionsMatch;
+exports.isFiniteVector = isFiniteVector;
+exports.mapMetric = mapMetric;
+exports.normalizeScore = normalizeScore;
+
+//# sourceMappingURL=helpers.cjs.map

package/batteries/vector/helpers.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.cjs","names":[],"sources":["../../../src/batteries/vector/helpers.ts"],"sourcesContent":["/**\n * Helper utilities for the vector storage provider battery.\n *\n * @module @nhtio/adk/batteries/vector/helpers\n */\n\nimport type { DistanceMetric } from './types'\n\nexport type ScoreKind = 'similarity' | 'distance'\n\nexport const clamp01 = (n: number): number => Math.min(1, Math.max(0, n))\n\nexport const normalizeScore = (raw: number, metric: DistanceMetric, kind: ScoreKind): number => {\n  if (metric === 'cosine') {\n    if (kind === 'similarity') {\n      return clamp01((raw + 1) / 2)\n    } else {\n      const sim = 1 - raw\n      return clamp01((sim + 1) / 2)\n    }\n  } else if (metric === 'dot') {\n    if (kind === 'similarity') {\n      return clamp01(1 / (1 + Math.exp(-raw)))\n    } else {\n      return clamp01(1 / (1 + Math.exp(raw)))\n    }\n  } else if (metric === 'euclidean') {\n    const d = Math.max(0, raw)\n    return clamp01(1 / (1 + d))\n  } else {\n    return clamp01(raw)\n  }\n}\n\nexport const mapMetric = <T>(metric: DistanceMetric, map: Record<DistanceMetric, T>): T =>\n  map[metric]\n\nexport const dimensionsMatch = (vector: number[], expected: number | undefined): boolean =>\n  expected === undefined ? true : vector.length === expected\n\nexport const isFiniteVector = (vector: number[]): boolean =>\n  Array.isArray(vector) && vector.every((n) => typeof n === 'number' && Number.isFinite(n))\n"],"mappings":";;;AAUA,IAAa,WAAW,MAAsB,KAAK,IAAI,GAAG,KAAK,IAAI,GAAG,CAAC,CAAC;AAExE,IAAa,kBAAkB,KAAa,QAAwB,SAA4B;CAC9F,IAAI,WAAW,UACb,IAAI,SAAS,cACX,OAAO,SAAS,MAAM,KAAK,CAAC;MAG5B,OAAO,SADK,IAAI,MACM,KAAK,CAAC;MAEzB,IAAI,WAAW,OACpB,IAAI,SAAS,cACX,OAAO,QAAQ,KAAK,IAAI,KAAK,IAAI,CAAC,GAAG,EAAE;MAEvC,OAAO,QAAQ,KAAK,IAAI,KAAK,IAAI,GAAG,EAAE;MAEnC,IAAI,WAAW,aAEpB,OAAO,QAAQ,KAAK,IADV,KAAK,IAAI,GAAG,GACE,EAAE;MAE1B,OAAO,QAAQ,GAAG;AAEtB;AAEA,IAAa,aAAgB,QAAwB,QACnD,IAAI;AAEN,IAAa,mBAAmB,QAAkB,aAChD,aAAa,KAAA,IAAY,OAAO,OAAO,WAAW;AAEpD,IAAa,kBAAkB,WAC7B,MAAM,QAAQ,MAAM,KAAK,OAAO,OAAO,MAAM,OAAO,MAAM,YAAY,OAAO,SAAS,CAAC,CAAC"}

package/batteries/vector/helpers.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Helper utilities for the vector storage provider battery.
+ *
+ * @module @nhtio/adk/batteries/vector/helpers
+ */
+import type { DistanceMetric } from "./types";
+export type ScoreKind = 'similarity' | 'distance';
+export declare const clamp01: (n: number) => number;
+export declare const normalizeScore: (raw: number, metric: DistanceMetric, kind: ScoreKind) => number;
+export declare const mapMetric: <T>(metric: DistanceMetric, map: Record<DistanceMetric, T>) => T;
+export declare const dimensionsMatch: (vector: number[], expected: number | undefined) => boolean;
+export declare const isFiniteVector: (vector: number[]) => boolean;

package/batteries/vector/helpers.mjs

@@ -0,0 +1,17 @@
+//#region src/batteries/vector/helpers.ts
+var clamp01 = (n) => Math.min(1, Math.max(0, n));
+var normalizeScore = (raw, metric, kind) => {
+	if (metric === "cosine") if (kind === "similarity") return clamp01((raw + 1) / 2);
+	else return clamp01((1 - raw + 1) / 2);
+	else if (metric === "dot") if (kind === "similarity") return clamp01(1 / (1 + Math.exp(-raw)));
+	else return clamp01(1 / (1 + Math.exp(raw)));
+	else if (metric === "euclidean") return clamp01(1 / (1 + Math.max(0, raw)));
+	else return clamp01(raw);
+};
+var mapMetric = (metric, map) => map[metric];
+var dimensionsMatch = (vector, expected) => expected === void 0 ? true : vector.length === expected;
+var isFiniteVector = (vector) => Array.isArray(vector) && vector.every((n) => typeof n === "number" && Number.isFinite(n));
+//#endregion
+export { clamp01, dimensionsMatch, isFiniteVector, mapMetric, normalizeScore };
+
+//# sourceMappingURL=helpers.mjs.map

package/batteries/vector/helpers.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.mjs","names":[],"sources":["../../../src/batteries/vector/helpers.ts"],"sourcesContent":["/**\n * Helper utilities for the vector storage provider battery.\n *\n * @module @nhtio/adk/batteries/vector/helpers\n */\n\nimport type { DistanceMetric } from './types'\n\nexport type ScoreKind = 'similarity' | 'distance'\n\nexport const clamp01 = (n: number): number => Math.min(1, Math.max(0, n))\n\nexport const normalizeScore = (raw: number, metric: DistanceMetric, kind: ScoreKind): number => {\n  if (metric === 'cosine') {\n    if (kind === 'similarity') {\n      return clamp01((raw + 1) / 2)\n    } else {\n      const sim = 1 - raw\n      return clamp01((sim + 1) / 2)\n    }\n  } else if (metric === 'dot') {\n    if (kind === 'similarity') {\n      return clamp01(1 / (1 + Math.exp(-raw)))\n    } else {\n      return clamp01(1 / (1 + Math.exp(raw)))\n    }\n  } else if (metric === 'euclidean') {\n    const d = Math.max(0, raw)\n    return clamp01(1 / (1 + d))\n  } else {\n    return clamp01(raw)\n  }\n}\n\nexport const mapMetric = <T>(metric: DistanceMetric, map: Record<DistanceMetric, T>): T =>\n  map[metric]\n\nexport const dimensionsMatch = (vector: number[], expected: number | undefined): boolean =>\n  expected === undefined ? true : vector.length === expected\n\nexport const isFiniteVector = (vector: number[]): boolean =>\n  Array.isArray(vector) && vector.every((n) => typeof n === 'number' && Number.isFinite(n))\n"],"mappings":";AAUA,IAAa,WAAW,MAAsB,KAAK,IAAI,GAAG,KAAK,IAAI,GAAG,CAAC,CAAC;AAExE,IAAa,kBAAkB,KAAa,QAAwB,SAA4B;CAC9F,IAAI,WAAW,UACb,IAAI,SAAS,cACX,OAAO,SAAS,MAAM,KAAK,CAAC;MAG5B,OAAO,SADK,IAAI,MACM,KAAK,CAAC;MAEzB,IAAI,WAAW,OACpB,IAAI,SAAS,cACX,OAAO,QAAQ,KAAK,IAAI,KAAK,IAAI,CAAC,GAAG,EAAE;MAEvC,OAAO,QAAQ,KAAK,IAAI,KAAK,IAAI,GAAG,EAAE;MAEnC,IAAI,WAAW,aAEpB,OAAO,QAAQ,KAAK,IADV,KAAK,IAAI,GAAG,GACE,EAAE;MAE1B,OAAO,QAAQ,GAAG;AAEtB;AAEA,IAAa,aAAgB,QAAwB,QACnD,IAAI;AAEN,IAAa,mBAAmB,QAAkB,aAChD,aAAa,KAAA,IAAY,OAAO,OAAO,WAAW;AAEpD,IAAa,kBAAkB,WAC7B,MAAM,QAAQ,MAAM,KAAK,OAAO,OAAO,MAAM,OAAO,MAAM,YAAY,OAAO,SAAS,CAAC,CAAC"}

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

@@ -0,0 +1,35 @@
+/**
+ * @module @nhtio/adk/batteries/vector/hnswlib
+ *
+ * Embedded HNSWLib adapter (in-process, no server — like in_memory/sqlite_vec/duckdb). hnswlib is
+ * a pure ANN index keyed by integer labels and holding ONLY vectors, so this adapter pairs the
+ * index with a JS sidecar that owns id↔label mapping plus the document/metadata records. KNN runs
+ * through the HNSW index; metadata filtering, filter-scans, projection and delete are served from
+ * the sidecar via the neutral filter tree's JS reference evaluator (exact cross-adapter parity).
+ *
+ * Driver: `hnswlib-node` (native addon; requires the build to be approved — see
+ * pnpm-workspace.yaml `allowBuilds`). Persistence is in-memory per process; pass a fresh store per
+ * use. (The index supports writeIndex/readIndex on disk, but the sidecar would need its own
+ * persistence — out of scope for the in-memory contract here.)
+ */
+import { BaseVectorStore } from "../contract";
+import type { SearchPlan, UpsertPlan, DeletePlan, CollectionSpec } from "../plan";
+import type { VectorMatch, VectorStoreCapabilities, BaseVectorStoreOptions } from "../types";
+export interface HnswlibVectorStoreOptions extends BaseVectorStoreOptions {
+    initialCapacity?: number;
+}
+export declare class HnswlibVectorStore extends BaseVectorStore {
+    #private;
+    readonly capabilities: VectorStoreCapabilities;
+    static isAvailable(): boolean;
+    isAvailable(): boolean;
+    connect(): Promise<void>;
+    close(): Promise<void>;
+    createCollection(spec: CollectionSpec, ifNotExists: boolean): Promise<void>;
+    dropCollection(collection: string, ifExists: boolean): Promise<void>;
+    hasCollection(collection: string): Promise<boolean>;
+    renameCollection(from: string, to: string): Promise<void>;
+    executeUpsert(plan: UpsertPlan): Promise<void>;
+    executeSearch(plan: SearchPlan): Promise<VectorMatch[]>;
+    executeDelete(plan: DeletePlan): Promise<void>;
+}

package/batteries/vector/hnswlib.cjs

@@ -0,0 +1,237 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+require("../../chunk-Ble4zEEl.js");
+const require_tool_registry = require("../../tool_registry-DYUYqXvo.js");
+require("../../guards.cjs");
+const require_batteries_vector_filters = require("./filters.cjs");
+const require_batteries_vector_helpers = require("./helpers.cjs");
+const require_batteries_vector_exceptions = require("./exceptions.cjs");
+const require_batteries_vector_contract = require("./contract.cjs");
+const require_batteries_vector_validation = require("./validation.cjs");
+//#region src/batteries/vector/hnswlib/index.ts
+/**
+* @module @nhtio/adk/batteries/vector/hnswlib
+*
+* Embedded HNSWLib adapter (in-process, no server — like in_memory/sqlite_vec/duckdb). hnswlib is
+* a pure ANN index keyed by integer labels and holding ONLY vectors, so this adapter pairs the
+* index with a JS sidecar that owns id↔label mapping plus the document/metadata records. KNN runs
+* through the HNSW index; metadata filtering, filter-scans, projection and delete are served from
+* the sidecar via the neutral filter tree's JS reference evaluator (exact cross-adapter parity).
+*
+* Driver: `hnswlib-node` (native addon; requires the build to be approved — see
+* pnpm-workspace.yaml `allowBuilds`). Persistence is in-memory per process; pass a fresh store per
+* use. (The index supports writeIndex/readIndex on disk, but the sidecar would need its own
+* persistence — out of scope for the in-memory contract here.)
+*/
+var getHnswlib = async () => {
+	try {
+		const mod = await import("hnswlib-node");
+		return mod.default ?? mod;
+	} catch {
+		throw new require_batteries_vector_exceptions.E_VECTOR_STORE_DRIVER_UNAVAILABLE(["hnswlib-node"]);
+	}
+};
+var spaceFor = (metric) => metric === "euclidean" ? "l2" : metric === "dot" ? "ip" : "cosine";
+var HnswlibVectorStore = class extends require_batteries_vector_contract.BaseVectorStore {
+	capabilities = {
+		transactions: false,
+		namedVectors: false,
+		rename: true,
+		rawSql: false,
+		builtInEncoding: false,
+		consistency: {
+			configurable: false,
+			default: "strong",
+			modes: ["strong"]
+		}
+	};
+	#lib = null;
+	#collections = /* @__PURE__ */ new Map();
+	get #opts() {
+		return this.options;
+	}
+	static isAvailable() {
+		return typeof process !== "undefined";
+	}
+	isAvailable() {
+		return typeof process !== "undefined";
+	}
+	async connect() {
+		if (this.#lib) return;
+		this.#lib = await getHnswlib();
+	}
+	async close() {
+		this.#collections.clear();
+		this.#lib = null;
+	}
+	async #ensureLib() {
+		if (!this.#lib) await this.connect();
+		return this.#lib;
+	}
+	#coll(collection) {
+		const c = this.#collections.get(collection);
+		if (!c) throw new require_batteries_vector_exceptions.E_VECTOR_STORE_COLLECTION_FAILED(["collection", "unknown collection: " + collection]);
+		return c;
+	}
+	async createCollection(spec, ifNotExists) {
+		const lib = await this.#ensureLib();
+		if (this.#collections.has(spec.collection)) {
+			if (ifNotExists) return;
+			this.#collections.delete(spec.collection);
+		}
+		try {
+			const capacity = this.#opts.initialCapacity ?? 1024;
+			const index = new lib.HierarchicalNSW(spaceFor(spec.vector.metric), spec.vector.dimensions);
+			index.initIndex(capacity);
+			this.#collections.set(spec.collection, {
+				index,
+				dims: spec.vector.dimensions,
+				metric: spec.vector.metric,
+				byId: /* @__PURE__ */ new Map(),
+				idByLabel: /* @__PURE__ */ new Map(),
+				nextLabel: 0,
+				capacity
+			});
+		} catch (err) {
+			throw new require_batteries_vector_exceptions.E_VECTOR_STORE_COLLECTION_FAILED(["createCollection", String(err)]);
+		}
+	}
+	async dropCollection(collection, ifExists) {
+		if (!this.#collections.has(collection)) {
+			if (ifExists) return;
+			throw new require_batteries_vector_exceptions.E_VECTOR_STORE_COLLECTION_FAILED(["dropCollection", "unknown collection"]);
+		}
+		this.#collections.delete(collection);
+	}
+	async hasCollection(collection) {
+		return this.#collections.has(collection);
+	}
+	async renameCollection(from, to) {
+		const c = this.#collections.get(from);
+		if (!c) throw new require_batteries_vector_exceptions.E_VECTOR_STORE_UNSUPPORTED_OPERATION(["renameCollection", "unknown: " + from]);
+		this.#collections.set(to, c);
+		this.#collections.delete(from);
+	}
+	#ensureCapacity(c, additional) {
+		const needed = c.byId.size + additional;
+		if (needed > c.capacity) {
+			const next = Math.max(needed, c.capacity * 2);
+			c.index.resizeIndex(next);
+			c.capacity = next;
+		}
+	}
+	async executeUpsert(plan) {
+		if (plan.records.length === 0) return;
+		require_batteries_vector_validation.validateRecords(plan.records);
+		await this.#ensureLib();
+		const c = this.#coll(plan.collection);
+		const expected = this.#opts.dimensions ?? c.dims;
+		try {
+			this.#ensureCapacity(c, plan.records.length);
+			for (const r of plan.records) {
+				let vector = r.vector;
+				if (!vector && r.document) {
+					const [v] = await this.encode([r.document], "document");
+					vector = v;
+				}
+				if (!vector) throw new require_batteries_vector_exceptions.E_VECTOR_STORE_UPSERT_FAILED(["Record missing vector and document"]);
+				if (expected !== void 0 && vector.length !== expected) throw new require_batteries_vector_exceptions.E_VECTOR_STORE_DIMENSION_MISMATCH([expected, vector.length]);
+				const existing = c.byId.get(r.id);
+				if (existing) try {
+					c.index.markDelete(existing.label);
+				} catch {}
+				this.#ensureCapacity(c, 1);
+				const label = c.nextLabel++;
+				c.index.addPoint(vector, label);
+				c.idByLabel.set(label, r.id);
+				c.byId.set(r.id, {
+					id: r.id,
+					label,
+					vector,
+					document: r.document,
+					metadata: r.metadata
+				});
+			}
+		} catch (err) {
+			if (require_tool_registry.isInstanceOf(err, "E_VECTOR_STORE_DIMENSION_MISMATCH", require_batteries_vector_exceptions.E_VECTOR_STORE_DIMENSION_MISMATCH) || require_tool_registry.isInstanceOf(err, "E_VECTOR_STORE_UPSERT_FAILED", require_batteries_vector_exceptions.E_VECTOR_STORE_UPSERT_FAILED)) throw err;
+			throw new require_batteries_vector_exceptions.E_VECTOR_STORE_UPSERT_FAILED([String(err)]);
+		}
+	}
+	async executeSearch(plan) {
+		await this.#ensureLib();
+		const c = this.#coll(plan.collection);
+		const metric = this.#opts.metric ?? c.metric;
+		let queryVector;
+		if (plan.near) {
+			if ("vector" in plan.near) queryVector = plan.near.vector;
+			else if ("serverText" in plan.near) {
+				const [v] = await this.encode([plan.near.serverText], "query");
+				queryVector = v;
+			} else if ("id" in plan.near) {
+				const rec = c.byId.get(plan.near.id);
+				if (!rec) throw new require_batteries_vector_exceptions.E_VECTOR_STORE_SEARCH_FAILED(["Referenced id not found: " + plan.near.id]);
+				queryVector = rec.vector;
+			}
+		}
+		const offset = plan.offset ?? 0;
+		try {
+			if (queryVector) {
+				const live = c.byId.size;
+				if (live === 0) return [];
+				const want = plan.filter ? live : Math.min(plan.topK + offset, live);
+				const k = Math.min(Math.max(want, 1), live);
+				const res = c.index.searchKnn(queryVector, k);
+				const hits = [];
+				for (let i = 0; i < res.neighbors.length; i++) {
+					const id = c.idByLabel.get(res.neighbors[i]);
+					if (id === void 0) continue;
+					const rec = c.byId.get(id);
+					if (rec) hits.push({
+						rec,
+						dist: res.distances[i]
+					});
+				}
+				return (plan.filter ? hits.filter((h) => require_batteries_vector_filters.evaluateFilter(plan.filter, h.rec.metadata ?? {})) : hits).slice(offset, offset + plan.topK).map((h) => this.#project(h.rec, plan, metric, h.dist));
+			} else {
+				const rows = [...c.byId.values()];
+				return (plan.filter ? rows.filter((rec) => require_batteries_vector_filters.evaluateFilter(plan.filter, rec.metadata ?? {})) : rows).slice(offset, offset + plan.topK).map((rec) => this.#project(rec, plan, metric, void 0));
+			}
+		} catch (err) {
+			throw new require_batteries_vector_exceptions.E_VECTOR_STORE_SEARCH_FAILED([String(err)]);
+		}
+	}
+	#project(rec, plan, metric, dist) {
+		const proj = plan.projection;
+		const out = {};
+		if (proj.id) out.id = rec.id;
+		if (proj.vector) out.vector = rec.vector.slice();
+		if (proj.document) out.document = rec.document;
+		if (proj.metadata) out.metadata = rec.metadata ?? {};
+		if (dist !== void 0) out.score = require_batteries_vector_helpers.normalizeScore(dist, metric, "distance");
+		return out;
+	}
+	async executeDelete(plan) {
+		await this.#ensureLib();
+		const c = this.#coll(plan.collection);
+		try {
+			let targets;
+			if (plan.ids && plan.ids.length > 0) targets = plan.ids;
+			else if (plan.filter) targets = [...c.byId.values()].filter((rec) => require_batteries_vector_filters.evaluateFilter(plan.filter, rec.metadata ?? {})).map((rec) => rec.id);
+			else targets = [...c.byId.keys()];
+			for (const id of targets) {
+				const rec = c.byId.get(id);
+				if (!rec) continue;
+				try {
+					c.index.markDelete(rec.label);
+				} catch {}
+				c.idByLabel.delete(rec.label);
+				c.byId.delete(id);
+			}
+		} catch (err) {
+			throw new require_batteries_vector_exceptions.E_VECTOR_STORE_DELETE_FAILED([String(err)]);
+		}
+	}
+};
+//#endregion
+exports.HnswlibVectorStore = HnswlibVectorStore;
+
+//# sourceMappingURL=hnswlib.cjs.map