@nhtio/adk 1.20260607.2 → 1.20260609.0

package/batteries/vector/filters.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");
 let _nhtio_validation = require("@nhtio/validation");
 //#region src/batteries/vector/filters.ts
@@ -9,13 +9,23 @@ let _nhtio_validation = require("@nhtio/validation");
 *
 * @module @nhtio/adk/batteries/vector/filters
 */
+/**
+* Construct a {@link RawExpr} from literal text and optional positional `bindings`.
+*
+* @param sql - The raw expression text.
+* @param bindings - Positional binding values.
+*/
 var raw = (sql, bindings = []) => ({
 	__raw: sql,
 	bindings
 });
+/** Type guard: `true` if `v` is a {@link RawExpr}. */
 var isRawExpr = (v) => require_tool_registry.isObject(v) && typeof v.__raw === "string" && Array.isArray(v.bindings);
+/** Type guard: `true` if `f` is a {@link FilterCondition}. */
 var isFilterCondition = (f) => typeof f.field === "string" && typeof f.op === "string";
+/** Type guard: `true` if `f` is a {@link RawFilter}. */
 var isRawFilter = (f) => typeof f.$dialect === "string";
+/** Type guard: `true` if `f` is a {@link FilterGroup} (neither a condition nor a raw filter). */
 var isFilterGroup = (f) => !isFilterCondition(f) && !isRawFilter(f);
 var rawFilterSchema = _nhtio_validation.validator.object({
 	$dialect: _nhtio_validation.validator.string().required(),
@@ -27,6 +37,7 @@ var filterConditionSchema = _nhtio_validation.validator.object({
 	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()
 });
+/** Recursive validator schema for any {@link VectorFilter} (condition, raw, or nested group). */
 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(),
@@ -42,6 +53,16 @@ var getField = (metadata, path) => {
 	}
 	return current;
 };
+/**
+* Evaluate a {@link VectorFilter} against a record's metadata in memory — the reference semantics
+* adapters must match for client-side filtering and conformance.
+*
+* @param filter - The filter to evaluate.
+* @param metadata - The record metadata to test.
+* @returns `true` if the metadata satisfies the filter.
+* @throws when the filter (or a nested value) is a raw expression, which the in-memory evaluator
+*   cannot interpret.
+*/
 var evaluateFilter = (filter, metadata) => {
 	if (isRawFilter(filter)) throw new Error("raw filters are not evaluable by the in-memory filter evaluator");
 	if (isFilterCondition(filter)) {

package/batteries/vector/filters.cjs.map

@@ -1 +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":"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"}
+{"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\n/** A comparison operator usable in a {@link FilterCondition}. */\nexport type FilterOperator =\n  | 'eq'\n  | 'ne'\n  | 'gt'\n  | 'gte'\n  | 'lt'\n  | 'lte'\n  | 'in'\n  | 'nin'\n  | 'exists'\n  | 'contains'\n\n/** A raw, adapter-dialect filter expression: literal text plus positional bindings. */\nexport interface RawExpr {\n  /** The raw expression text. */\n  __raw: string\n  /** Positional binding values substituted into the expression. */\n  bindings: unknown[]\n}\n\n/**\n * Construct a {@link RawExpr} from literal text and optional positional `bindings`.\n *\n * @param sql - The raw expression text.\n * @param bindings - Positional binding values.\n */\nexport const raw = (sql: string, bindings: unknown[] = []): RawExpr => ({ __raw: sql, bindings })\n\n/** Type guard: `true` if `v` is a {@link RawExpr}. */\nexport const isRawExpr = (v: unknown): v is RawExpr =>\n  isObject(v) && typeof v.__raw === 'string' && Array.isArray(v.bindings)\n\n/** A single field comparison: `field op value`. */\nexport interface FilterCondition {\n  /** The metadata field path (dot-separated for nested fields). */\n  field: string\n  /** The comparison operator. */\n  op: FilterOperator\n  /** The value(s) compared against, or a {@link RawExpr}; omitted for `exists`. */\n  value?: VectorMetadataValue | VectorMetadataValue[] | RawExpr\n}\n/** A boolean combination of nested filters. Exactly one of `and`/`or`/`not` is meaningful. */\nexport interface FilterGroup {\n  /** All nested filters must match. */\n  and?: VectorFilter[]\n  /** At least one nested filter must match. */\n  or?: VectorFilter[]\n  /** The nested filter must not match. */\n  not?: VectorFilter\n}\n/** An adapter-dialect raw filter forwarded to the backend verbatim. */\nexport interface RawFilter {\n  /** The dialect the raw expression is written in (e.g. `'sql'`). */\n  $dialect: string\n  /** The raw expression — a string, or a structured dialect-specific payload. */\n  $raw: string | unknown\n  /** Positional binding values for the raw expression. */\n  $bindings?: unknown[]\n}\n/** Any filter node: a {@link FilterCondition}, a {@link FilterGroup}, or a {@link RawFilter}. */\nexport type VectorFilter = FilterCondition | FilterGroup | RawFilter\n\n/** Type guard: `true` if `f` is a {@link FilterCondition}. */\nexport const isFilterCondition = (f: VectorFilter): f is FilterCondition =>\n  typeof (f as FilterCondition).field === 'string' && typeof (f as FilterCondition).op === 'string'\n\n/** Type guard: `true` if `f` is a {@link RawFilter}. */\nexport const isRawFilter = (f: VectorFilter): f is RawFilter =>\n  typeof (f as RawFilter).$dialect === 'string'\n\n/** Type guard: `true` if `f` is a {@link FilterGroup} (neither a condition nor a raw filter). */\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\n/** Recursive validator schema for any {@link VectorFilter} (condition, raw, or nested group). */\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\n/**\n * Evaluate a {@link VectorFilter} against a record's metadata in memory — the reference semantics\n * adapters must match for client-side filtering and conformance.\n *\n * @param filter - The filter to evaluate.\n * @param metadata - The record metadata to test.\n * @returns `true` if the metadata satisfies the filter.\n * @throws when the filter (or a nested value) is a raw expression, which the in-memory evaluator\n *   cannot interpret.\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/filters.d.ts

@@ -4,31 +4,69 @@
  * @module @nhtio/adk/batteries/vector/filters
  */
 import type { VectorMetadata, VectorMetadataValue } from "./types";
+/** A comparison operator usable in a {@link FilterCondition}. */
 export type FilterOperator = 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'nin' | 'exists' | 'contains';
+/** A raw, adapter-dialect filter expression: literal text plus positional bindings. */
 export interface RawExpr {
+    /** The raw expression text. */
     __raw: string;
+    /** Positional binding values substituted into the expression. */
     bindings: unknown[];
 }
+/**
+ * Construct a {@link RawExpr} from literal text and optional positional `bindings`.
+ *
+ * @param sql - The raw expression text.
+ * @param bindings - Positional binding values.
+ */
 export declare const raw: (sql: string, bindings?: unknown[]) => RawExpr;
+/** Type guard: `true` if `v` is a {@link RawExpr}. */
 export declare const isRawExpr: (v: unknown) => v is RawExpr;
+/** A single field comparison: `field op value`. */
 export interface FilterCondition {
+    /** The metadata field path (dot-separated for nested fields). */
     field: string;
+    /** The comparison operator. */
     op: FilterOperator;
+    /** The value(s) compared against, or a {@link RawExpr}; omitted for `exists`. */
     value?: VectorMetadataValue | VectorMetadataValue[] | RawExpr;
 }
+/** A boolean combination of nested filters. Exactly one of `and`/`or`/`not` is meaningful. */
 export interface FilterGroup {
+    /** All nested filters must match. */
     and?: VectorFilter[];
+    /** At least one nested filter must match. */
     or?: VectorFilter[];
+    /** The nested filter must not match. */
     not?: VectorFilter;
 }
+/** An adapter-dialect raw filter forwarded to the backend verbatim. */
 export interface RawFilter {
+    /** The dialect the raw expression is written in (e.g. `'sql'`). */
     $dialect: string;
+    /** The raw expression — a string, or a structured dialect-specific payload. */
     $raw: string | unknown;
+    /** Positional binding values for the raw expression. */
     $bindings?: unknown[];
 }
+/** Any filter node: a {@link FilterCondition}, a {@link FilterGroup}, or a {@link RawFilter}. */
 export type VectorFilter = FilterCondition | FilterGroup | RawFilter;
+/** Type guard: `true` if `f` is a {@link FilterCondition}. */
 export declare const isFilterCondition: (f: VectorFilter) => f is FilterCondition;
+/** Type guard: `true` if `f` is a {@link RawFilter}. */
 export declare const isRawFilter: (f: VectorFilter) => f is RawFilter;
+/** Type guard: `true` if `f` is a {@link FilterGroup} (neither a condition nor a raw filter). */
 export declare const isFilterGroup: (f: VectorFilter) => f is FilterGroup;
+/** Recursive validator schema for any {@link VectorFilter} (condition, raw, or nested group). */
 export declare const vectorFilterSchema: import("@nhtio/validation").AlternativesSchema<any>;
+/**
+ * Evaluate a {@link VectorFilter} against a record's metadata in memory — the reference semantics
+ * adapters must match for client-side filtering and conformance.
+ *
+ * @param filter - The filter to evaluate.
+ * @param metadata - The record metadata to test.
+ * @returns `true` if the metadata satisfies the filter.
+ * @throws when the filter (or a nested value) is a raw expression, which the in-memory evaluator
+ *   cannot interpret.
+ */
 export declare const evaluateFilter: (filter: VectorFilter, metadata: VectorMetadata) => boolean;

package/batteries/vector/filters.mjs

@@ -1,4 +1,4 @@
-import { c as isObject } from "../../tool_registry-D1pSSlsd.mjs";
+import { c as isObject } from "../../tool_registry-791Vrjtf.mjs";
 import "../../guards.mjs";
 import { validator } from "@nhtio/validation";
 //#region src/batteries/vector/filters.ts
@@ -7,13 +7,23 @@ import { validator } from "@nhtio/validation";
 *
 * @module @nhtio/adk/batteries/vector/filters
 */
+/**
+* Construct a {@link RawExpr} from literal text and optional positional `bindings`.
+*
+* @param sql - The raw expression text.
+* @param bindings - Positional binding values.
+*/
 var raw = (sql, bindings = []) => ({
 	__raw: sql,
 	bindings
 });
+/** Type guard: `true` if `v` is a {@link RawExpr}. */
 var isRawExpr = (v) => isObject(v) && typeof v.__raw === "string" && Array.isArray(v.bindings);
+/** Type guard: `true` if `f` is a {@link FilterCondition}. */
 var isFilterCondition = (f) => typeof f.field === "string" && typeof f.op === "string";
+/** Type guard: `true` if `f` is a {@link RawFilter}. */
 var isRawFilter = (f) => typeof f.$dialect === "string";
+/** Type guard: `true` if `f` is a {@link FilterGroup} (neither a condition nor a raw filter). */
 var isFilterGroup = (f) => !isFilterCondition(f) && !isRawFilter(f);
 var rawFilterSchema = validator.object({
 	$dialect: validator.string().required(),
@@ -25,6 +35,7 @@ var filterConditionSchema = validator.object({
 	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()
 });
+/** Recursive validator schema for any {@link VectorFilter} (condition, raw, or nested group). */
 var vectorFilterSchema = validator.alternatives(filterConditionSchema, rawFilterSchema, validator.object({
 	and: validator.array().items(validator.link("#vectorFilter")).optional(),
 	or: validator.array().items(validator.link("#vectorFilter")).optional(),
@@ -40,6 +51,16 @@ var getField = (metadata, path) => {
 	}
 	return current;
 };
+/**
+* Evaluate a {@link VectorFilter} against a record's metadata in memory — the reference semantics
+* adapters must match for client-side filtering and conformance.
+*
+* @param filter - The filter to evaluate.
+* @param metadata - The record metadata to test.
+* @returns `true` if the metadata satisfies the filter.
+* @throws when the filter (or a nested value) is a raw expression, which the in-memory evaluator
+*   cannot interpret.
+*/
 var evaluateFilter = (filter, metadata) => {
 	if (isRawFilter(filter)) throw new Error("raw filters are not evaluable by the in-memory filter evaluator");
 	if (isFilterCondition(filter)) {

package/batteries/vector/filters.mjs.map

@@ -1 +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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"}
+{"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\n/** A comparison operator usable in a {@link FilterCondition}. */\nexport type FilterOperator =\n  | 'eq'\n  | 'ne'\n  | 'gt'\n  | 'gte'\n  | 'lt'\n  | 'lte'\n  | 'in'\n  | 'nin'\n  | 'exists'\n  | 'contains'\n\n/** A raw, adapter-dialect filter expression: literal text plus positional bindings. */\nexport interface RawExpr {\n  /** The raw expression text. */\n  __raw: string\n  /** Positional binding values substituted into the expression. */\n  bindings: unknown[]\n}\n\n/**\n * Construct a {@link RawExpr} from literal text and optional positional `bindings`.\n *\n * @param sql - The raw expression text.\n * @param bindings - Positional binding values.\n */\nexport const raw = (sql: string, bindings: unknown[] = []): RawExpr => ({ __raw: sql, bindings })\n\n/** Type guard: `true` if `v` is a {@link RawExpr}. */\nexport const isRawExpr = (v: unknown): v is RawExpr =>\n  isObject(v) && typeof v.__raw === 'string' && Array.isArray(v.bindings)\n\n/** A single field comparison: `field op value`. */\nexport interface FilterCondition {\n  /** The metadata field path (dot-separated for nested fields). */\n  field: string\n  /** The comparison operator. */\n  op: FilterOperator\n  /** The value(s) compared against, or a {@link RawExpr}; omitted for `exists`. */\n  value?: VectorMetadataValue | VectorMetadataValue[] | RawExpr\n}\n/** A boolean combination of nested filters. Exactly one of `and`/`or`/`not` is meaningful. */\nexport interface FilterGroup {\n  /** All nested filters must match. */\n  and?: VectorFilter[]\n  /** At least one nested filter must match. */\n  or?: VectorFilter[]\n  /** The nested filter must not match. */\n  not?: VectorFilter\n}\n/** An adapter-dialect raw filter forwarded to the backend verbatim. */\nexport interface RawFilter {\n  /** The dialect the raw expression is written in (e.g. `'sql'`). */\n  $dialect: string\n  /** The raw expression — a string, or a structured dialect-specific payload. */\n  $raw: string | unknown\n  /** Positional binding values for the raw expression. */\n  $bindings?: unknown[]\n}\n/** Any filter node: a {@link FilterCondition}, a {@link FilterGroup}, or a {@link RawFilter}. */\nexport type VectorFilter = FilterCondition | FilterGroup | RawFilter\n\n/** Type guard: `true` if `f` is a {@link FilterCondition}. */\nexport const isFilterCondition = (f: VectorFilter): f is FilterCondition =>\n  typeof (f as FilterCondition).field === 'string' && typeof (f as FilterCondition).op === 'string'\n\n/** Type guard: `true` if `f` is a {@link RawFilter}. */\nexport const isRawFilter = (f: VectorFilter): f is RawFilter =>\n  typeof (f as RawFilter).$dialect === 'string'\n\n/** Type guard: `true` if `f` is a {@link FilterGroup} (neither a condition nor a raw filter). */\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\n/** Recursive validator schema for any {@link VectorFilter} (condition, raw, or nested group). */\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\n/**\n * Evaluate a {@link VectorFilter} against a record's metadata in memory — the reference semantics\n * adapters must match for client-side filtering and conformance.\n *\n * @param filter - The filter to evaluate.\n * @param metadata - The record metadata to test.\n * @returns `true` if the metadata satisfies the filter.\n * @throws when the filter (or a nested value) is a raw expression, which the in-memory evaluator\n *   cannot interpret.\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

@@ -1,7 +1,17 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 require("../../chunk-Ble4zEEl.js");
 //#region src/batteries/vector/helpers.ts
+/** Clamp `n` into the inclusive `[0, 1]` range. */
 var clamp01 = (n) => Math.min(1, Math.max(0, n));
+/**
+* Normalize a backend's raw score into a `[0, 1]` similarity where higher is closer, accounting for
+* the distance metric and whether the raw value is a similarity or a distance.
+*
+* @param raw - The backend's raw score.
+* @param metric - The distance metric the score was computed under.
+* @param kind - Whether `raw` is a similarity or a distance.
+* @returns The normalized similarity in `[0, 1]`.
+*/
 var normalizeScore = (raw, metric, kind) => {
 	if (metric === "cosine") if (kind === "similarity") return clamp01((raw + 1) / 2);
 	else return clamp01((1 - raw + 1) / 2);
@@ -10,8 +20,11 @@ var normalizeScore = (raw, metric, kind) => {
 	else if (metric === "euclidean") return clamp01(1 / (1 + Math.max(0, raw)));
 	else return clamp01(raw);
 };
+/** Look up the adapter-specific value for `metric` in a complete metric→value map. */
 var mapMetric = (metric, map) => map[metric];
+/** `true` if `vector`'s length matches `expected` (or `expected` is undefined). */
 var dimensionsMatch = (vector, expected) => expected === void 0 ? true : vector.length === expected;
+/** `true` if `vector` is an array of finite numbers (no NaN/Infinity). */
 var isFiniteVector = (vector) => Array.isArray(vector) && vector.every((n) => typeof n === "number" && Number.isFinite(n));
 //#endregion
 exports.clamp01 = clamp01;

package/batteries/vector/helpers.cjs.map

@@ -1 +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"}
+{"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\n/** Whether a raw backend score is a similarity (higher = closer) or a distance (lower = closer). */\nexport type ScoreKind = 'similarity' | 'distance'\n\n/** Clamp `n` into the inclusive `[0, 1]` range. */\nexport const clamp01 = (n: number): number => Math.min(1, Math.max(0, n))\n\n/**\n * Normalize a backend's raw score into a `[0, 1]` similarity where higher is closer, accounting for\n * the distance metric and whether the raw value is a similarity or a distance.\n *\n * @param raw - The backend's raw score.\n * @param metric - The distance metric the score was computed under.\n * @param kind - Whether `raw` is a similarity or a distance.\n * @returns The normalized similarity in `[0, 1]`.\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\n/** Look up the adapter-specific value for `metric` in a complete metric→value map. */\nexport const mapMetric = <T>(metric: DistanceMetric, map: Record<DistanceMetric, T>): T =>\n  map[metric]\n\n/** `true` if `vector`'s length matches `expected` (or `expected` is undefined). */\nexport const dimensionsMatch = (vector: number[], expected: number | undefined): boolean =>\n  expected === undefined ? true : vector.length === expected\n\n/** `true` if `vector` is an array of finite numbers (no NaN/Infinity). */\nexport const isFiniteVector = (vector: number[]): boolean =>\n  Array.isArray(vector) && vector.every((n) => typeof n === 'number' && Number.isFinite(n))\n"],"mappings":";;;;AAYA,IAAa,WAAW,MAAsB,KAAK,IAAI,GAAG,KAAK,IAAI,GAAG,CAAC,CAAC;;;;;;;;;;AAWxE,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;;AAGA,IAAa,aAAgB,QAAwB,QACnD,IAAI;;AAGN,IAAa,mBAAmB,QAAkB,aAChD,aAAa,KAAA,IAAY,OAAO,OAAO,WAAW;;AAGpD,IAAa,kBAAkB,WAC7B,MAAM,QAAQ,MAAM,KAAK,OAAO,OAAO,MAAM,OAAO,MAAM,YAAY,OAAO,SAAS,CAAC,CAAC"}

package/batteries/vector/helpers.d.ts

@@ -4,9 +4,23 @@
  * @module @nhtio/adk/batteries/vector/helpers
  */
 import type { DistanceMetric } from "./types";
+/** Whether a raw backend score is a similarity (higher = closer) or a distance (lower = closer). */
 export type ScoreKind = 'similarity' | 'distance';
+/** Clamp `n` into the inclusive `[0, 1]` range. */
 export declare const clamp01: (n: number) => number;
+/**
+ * Normalize a backend's raw score into a `[0, 1]` similarity where higher is closer, accounting for
+ * the distance metric and whether the raw value is a similarity or a distance.
+ *
+ * @param raw - The backend's raw score.
+ * @param metric - The distance metric the score was computed under.
+ * @param kind - Whether `raw` is a similarity or a distance.
+ * @returns The normalized similarity in `[0, 1]`.
+ */
 export declare const normalizeScore: (raw: number, metric: DistanceMetric, kind: ScoreKind) => number;
+/** Look up the adapter-specific value for `metric` in a complete metric→value map. */
 export declare const mapMetric: <T>(metric: DistanceMetric, map: Record<DistanceMetric, T>) => T;
+/** `true` if `vector`'s length matches `expected` (or `expected` is undefined). */
 export declare const dimensionsMatch: (vector: number[], expected: number | undefined) => boolean;
+/** `true` if `vector` is an array of finite numbers (no NaN/Infinity). */
 export declare const isFiniteVector: (vector: number[]) => boolean;

package/batteries/vector/helpers.mjs

@@ -1,5 +1,15 @@
 //#region src/batteries/vector/helpers.ts
+/** Clamp `n` into the inclusive `[0, 1]` range. */
 var clamp01 = (n) => Math.min(1, Math.max(0, n));
+/**
+* Normalize a backend's raw score into a `[0, 1]` similarity where higher is closer, accounting for
+* the distance metric and whether the raw value is a similarity or a distance.
+*
+* @param raw - The backend's raw score.
+* @param metric - The distance metric the score was computed under.
+* @param kind - Whether `raw` is a similarity or a distance.
+* @returns The normalized similarity in `[0, 1]`.
+*/
 var normalizeScore = (raw, metric, kind) => {
 	if (metric === "cosine") if (kind === "similarity") return clamp01((raw + 1) / 2);
 	else return clamp01((1 - raw + 1) / 2);
@@ -8,8 +18,11 @@ var normalizeScore = (raw, metric, kind) => {
 	else if (metric === "euclidean") return clamp01(1 / (1 + Math.max(0, raw)));
 	else return clamp01(raw);
 };
+/** Look up the adapter-specific value for `metric` in a complete metric→value map. */
 var mapMetric = (metric, map) => map[metric];
+/** `true` if `vector`'s length matches `expected` (or `expected` is undefined). */
 var dimensionsMatch = (vector, expected) => expected === void 0 ? true : vector.length === expected;
+/** `true` if `vector` is an array of finite numbers (no NaN/Infinity). */
 var isFiniteVector = (vector) => Array.isArray(vector) && vector.every((n) => typeof n === "number" && Number.isFinite(n));
 //#endregion
 export { clamp01, dimensionsMatch, isFiniteVector, mapMetric, normalizeScore };

package/batteries/vector/helpers.mjs.map

@@ -1 +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"}
+{"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\n/** Whether a raw backend score is a similarity (higher = closer) or a distance (lower = closer). */\nexport type ScoreKind = 'similarity' | 'distance'\n\n/** Clamp `n` into the inclusive `[0, 1]` range. */\nexport const clamp01 = (n: number): number => Math.min(1, Math.max(0, n))\n\n/**\n * Normalize a backend's raw score into a `[0, 1]` similarity where higher is closer, accounting for\n * the distance metric and whether the raw value is a similarity or a distance.\n *\n * @param raw - The backend's raw score.\n * @param metric - The distance metric the score was computed under.\n * @param kind - Whether `raw` is a similarity or a distance.\n * @returns The normalized similarity in `[0, 1]`.\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\n/** Look up the adapter-specific value for `metric` in a complete metric→value map. */\nexport const mapMetric = <T>(metric: DistanceMetric, map: Record<DistanceMetric, T>): T =>\n  map[metric]\n\n/** `true` if `vector`'s length matches `expected` (or `expected` is undefined). */\nexport const dimensionsMatch = (vector: number[], expected: number | undefined): boolean =>\n  expected === undefined ? true : vector.length === expected\n\n/** `true` if `vector` is an array of finite numbers (no NaN/Infinity). */\nexport const isFiniteVector = (vector: number[]): boolean =>\n  Array.isArray(vector) && vector.every((n) => typeof n === 'number' && Number.isFinite(n))\n"],"mappings":";;AAYA,IAAa,WAAW,MAAsB,KAAK,IAAI,GAAG,KAAK,IAAI,GAAG,CAAC,CAAC;;;;;;;;;;AAWxE,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;;AAGA,IAAa,aAAgB,QAAwB,QACnD,IAAI;;AAGN,IAAa,mBAAmB,QAAkB,aAChD,aAAa,KAAA,IAAY,OAAO,OAAO,WAAW;;AAGpD,IAAa,kBAAkB,WAC7B,MAAM,QAAQ,MAAM,KAAK,OAAO,OAAO,MAAM,OAAO,MAAM,YAAY,OAAO,SAAS,CAAC,CAAC"}

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

@@ -16,11 +16,13 @@ import { BaseVectorStore } from "../contract";
 import type { SearchPlan, UpsertPlan, DeletePlan, CollectionSpec } from "../plan";
 import type { VectorMatch, VectorStoreCapabilities, BaseVectorStoreOptions } from "../types";
 export interface HnswlibVectorStoreOptions extends BaseVectorStoreOptions {
+    /** Initial index capacity per collection; grows automatically via `resizeIndex`. Default 1024. */
     initialCapacity?: number;
 }
 export declare class HnswlibVectorStore 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/hnswlib.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_helpers = require("./helpers.cjs");
@@ -49,6 +49,7 @@ var HnswlibVectorStore = class extends require_batteries_vector_contract.BaseVec
 	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/hnswlib.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"hnswlib.cjs","names":["#opts","#lib","#collections","#ensureLib","#coll","#ensureCapacity","#project"],"sources":["../../../src/batteries/vector/hnswlib/index.ts"],"sourcesContent":["/**\n * @module @nhtio/adk/batteries/vector/hnswlib\n *\n * Embedded HNSWLib adapter (in-process, no server — like in_memory/sqlite_vec/duckdb). hnswlib is\n * a pure ANN index keyed by integer labels and holding ONLY vectors, so this adapter pairs the\n * index with a JS sidecar that owns id↔label mapping plus the document/metadata records. KNN runs\n * through the HNSW index; metadata filtering, filter-scans, projection and delete are served from\n * the sidecar via the neutral filter tree's JS reference evaluator (exact cross-adapter parity).\n *\n * Driver: `hnswlib-node` (native addon; requires the build to be approved — see\n * pnpm-workspace.yaml `allowBuilds`). Persistence is in-memory per process; pass a fresh store per\n * use. (The index supports writeIndex/readIndex on disk, but the sidecar would need its own\n * persistence — out of scope for the in-memory contract here.)\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_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 HnswlibVectorStoreOptions extends BaseVectorStoreOptions {\n  // Initial index capacity per collection (grows automatically via resizeIndex). Default 1024.\n  initialCapacity?: number\n}\n\ninterface StoredRecord {\n  id: string\n  label: number\n  vector: number[]\n  document?: string\n  metadata?: VectorMetadata\n}\n\ninterface Collection {\n  index: any\n  dims: number\n  metric: DistanceMetric\n  byId: Map<string, StoredRecord>\n  idByLabel: Map<number, string>\n  nextLabel: number\n  capacity: number\n}\n\nconst getHnswlib = async () => {\n  try {\n    const mod = await import('hnswlib-node')\n    return (mod as any).default ?? mod\n  } catch {\n    throw new E_VECTOR_STORE_DRIVER_UNAVAILABLE(['hnswlib-node'])\n  }\n}\n\nconst spaceFor = (metric: DistanceMetric): string =>\n  metric === 'euclidean' ? 'l2' : metric === 'dot' ? 'ip' : 'cosine'\n\nexport class HnswlibVectorStore extends BaseVectorStore {\n  readonly capabilities: VectorStoreCapabilities = {\n    transactions: false,\n    namedVectors: false,\n    rename: true,\n    rawSql: false,\n    builtInEncoding: false,\n    // In-process and synchronous: a write is visible on resolve. The option is a no-op.\n    consistency: { configurable: false, default: 'strong', modes: ['strong'] },\n  }\n\n  #lib: any | null = null\n  #collections: Map<string, Collection> = new Map()\n\n  get #opts(): HnswlibVectorStoreOptions {\n    return this.options as HnswlibVectorStoreOptions\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.#lib) return\n    this.#lib = await getHnswlib()\n  }\n\n  async close(): Promise<void> {\n    this.#collections.clear()\n    this.#lib = null\n  }\n\n  async #ensureLib(): Promise<any> {\n    if (!this.#lib) await this.connect()\n    return this.#lib!\n  }\n\n  #coll(collection: string): Collection {\n    const c = this.#collections.get(collection)\n    if (!c) {\n      throw new E_VECTOR_STORE_COLLECTION_FAILED([\n        'collection',\n        'unknown collection: ' + collection,\n      ])\n    }\n    return c\n  }\n\n  async createCollection(spec: CollectionSpec, ifNotExists: boolean): Promise<void> {\n    const lib = await this.#ensureLib()\n    if (this.#collections.has(spec.collection)) {\n      if (ifNotExists) return\n      this.#collections.delete(spec.collection)\n    }\n    try {\n      const capacity = this.#opts.initialCapacity ?? 1024\n      const index = new lib.HierarchicalNSW(spaceFor(spec.vector.metric), spec.vector.dimensions)\n      index.initIndex(capacity)\n      this.#collections.set(spec.collection, {\n        index,\n        dims: spec.vector.dimensions,\n        metric: spec.vector.metric,\n        byId: new Map(),\n        idByLabel: new Map(),\n        nextLabel: 0,\n        capacity,\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    if (!this.#collections.has(collection)) {\n      if (ifExists) return\n      throw new E_VECTOR_STORE_COLLECTION_FAILED(['dropCollection', 'unknown collection'])\n    }\n    this.#collections.delete(collection)\n  }\n\n  async hasCollection(collection: string): Promise<boolean> {\n    return this.#collections.has(collection)\n  }\n\n  async renameCollection(from: string, to: string): Promise<void> {\n    const c = this.#collections.get(from)\n    if (!c) throw new E_VECTOR_STORE_UNSUPPORTED_OPERATION(['renameCollection', 'unknown: ' + from])\n    this.#collections.set(to, c)\n    this.#collections.delete(from)\n  }\n\n  #ensureCapacity(c: Collection, additional: number): void {\n    const needed = c.byId.size + additional\n    if (needed > c.capacity) {\n      const next = Math.max(needed, c.capacity * 2)\n      c.index.resizeIndex(next)\n      c.capacity = next\n    }\n  }\n\n  async executeUpsert(plan: UpsertPlan): Promise<void> {\n    if (plan.records.length === 0) return\n    validateRecords(plan.records)\n    await this.#ensureLib()\n    const c = this.#coll(plan.collection)\n    const expected = this.#opts.dimensions ?? c.dims\n    try {\n      this.#ensureCapacity(c, plan.records.length)\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        // Reuse the existing label on update (mark the old point deleted, then re-add under a\n        // fresh label so the vector value actually changes — hnswlib has no in-place update).\n        const existing = c.byId.get(r.id)\n        if (existing) {\n          try {\n            c.index.markDelete(existing.label)\n          } catch {\n            // already gone — ignore\n          }\n        }\n        this.#ensureCapacity(c, 1)\n        const label = c.nextLabel++\n        c.index.addPoint(vector, label)\n        c.idByLabel.set(label, r.id)\n        c.byId.set(r.id, { id: r.id, label, vector, document: r.document, metadata: r.metadata })\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    await this.#ensureLib()\n    const c = this.#coll(plan.collection)\n    const metric = this.#opts.metric ?? c.metric\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 rec = c.byId.get(plan.near.id)\n        if (!rec) {\n          throw new E_VECTOR_STORE_SEARCH_FAILED(['Referenced id not found: ' + plan.near.id])\n        }\n        queryVector = rec.vector\n      }\n    }\n\n    const offset = plan.offset ?? 0\n    try {\n      if (queryVector) {\n        // Over-fetch when filtering (and to absorb deleted points), then JS-filter for parity.\n        const live = c.byId.size\n        if (live === 0) return []\n        const want = plan.filter ? live : Math.min(plan.topK + offset, live)\n        const k = Math.min(Math.max(want, 1), live)\n        const res = c.index.searchKnn(queryVector, k)\n        const hits: Array<{ rec: StoredRecord; dist: number }> = []\n        for (let i = 0; i < res.neighbors.length; i++) {\n          const id = c.idByLabel.get(res.neighbors[i])\n          if (id === undefined) continue\n          const rec = c.byId.get(id)\n          if (rec) hits.push({ rec, dist: res.distances[i] })\n        }\n        const filtered = plan.filter\n          ? hits.filter((h) => evaluateFilter(plan.filter!, h.rec.metadata ?? {}))\n          : hits\n        return filtered\n          .slice(offset, offset + plan.topK)\n          .map((h) => this.#project(h.rec, plan, metric, h.dist))\n      } else {\n        // Filter-scan: serve from the sidecar (insertion order), JS-filter, no score.\n        const rows = [...c.byId.values()]\n        const filtered = plan.filter\n          ? rows.filter((rec) => evaluateFilter(plan.filter!, rec.metadata ?? {}))\n          : rows\n        return filtered\n          .slice(offset, offset + plan.topK)\n          .map((rec) => this.#project(rec, plan, metric, undefined))\n      }\n    } catch (err) {\n      throw new E_VECTOR_STORE_SEARCH_FAILED([String(err)])\n    }\n  }\n\n  #project(\n    rec: StoredRecord,\n    plan: SearchPlan,\n    metric: string,\n    dist: number | undefined\n  ): VectorMatch {\n    const proj = plan.projection\n    const out: VectorMatch = {}\n    if (proj.id) out.id = rec.id\n    if (proj.vector) out.vector = rec.vector.slice()\n    if (proj.document) out.document = rec.document\n    if (proj.metadata) out.metadata = rec.metadata ?? {}\n    if (dist !== undefined) {\n      out.score = normalizeScore(dist, metric as DistanceMetric, 'distance')\n    }\n    return out\n  }\n\n  async executeDelete(plan: DeletePlan): Promise<void> {\n    await this.#ensureLib()\n    const c = this.#coll(plan.collection)\n    try {\n      let targets: string[]\n      if (plan.ids && plan.ids.length > 0) {\n        targets = plan.ids\n      } else if (plan.filter) {\n        targets = [...c.byId.values()]\n          .filter((rec) => evaluateFilter(plan.filter!, rec.metadata ?? {}))\n          .map((rec) => rec.id)\n      } else {\n        targets = [...c.byId.keys()]\n      }\n      for (const id of targets) {\n        const rec = c.byId.get(id)\n        if (!rec) continue\n        try {\n          c.index.markDelete(rec.label)\n        } catch {\n          // already deleted — ignore\n        }\n        c.idByLabel.delete(rec.label)\n        c.byId.delete(id)\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":"hnswlib.cjs","names":["#opts","#lib","#collections","#ensureLib","#coll","#ensureCapacity","#project"],"sources":["../../../src/batteries/vector/hnswlib/index.ts"],"sourcesContent":["/**\n * @module @nhtio/adk/batteries/vector/hnswlib\n *\n * Embedded HNSWLib adapter (in-process, no server — like in_memory/sqlite_vec/duckdb). hnswlib is\n * a pure ANN index keyed by integer labels and holding ONLY vectors, so this adapter pairs the\n * index with a JS sidecar that owns id↔label mapping plus the document/metadata records. KNN runs\n * through the HNSW index; metadata filtering, filter-scans, projection and delete are served from\n * the sidecar via the neutral filter tree's JS reference evaluator (exact cross-adapter parity).\n *\n * Driver: `hnswlib-node` (native addon; requires the build to be approved — see\n * pnpm-workspace.yaml `allowBuilds`). Persistence is in-memory per process; pass a fresh store per\n * use. (The index supports writeIndex/readIndex on disk, but the sidecar would need its own\n * persistence — out of scope for the in-memory contract here.)\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_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 HnswlibVectorStoreOptions extends BaseVectorStoreOptions {\n  /** Initial index capacity per collection; grows automatically via `resizeIndex`. Default 1024. */\n  initialCapacity?: number\n}\n\ninterface StoredRecord {\n  id: string\n  label: number\n  vector: number[]\n  document?: string\n  metadata?: VectorMetadata\n}\n\ninterface Collection {\n  index: any\n  dims: number\n  metric: DistanceMetric\n  byId: Map<string, StoredRecord>\n  idByLabel: Map<number, string>\n  nextLabel: number\n  capacity: number\n}\n\nconst getHnswlib = async () => {\n  try {\n    const mod = await import('hnswlib-node')\n    return (mod as any).default ?? mod\n  } catch {\n    throw new E_VECTOR_STORE_DRIVER_UNAVAILABLE(['hnswlib-node'])\n  }\n}\n\nconst spaceFor = (metric: DistanceMetric): string =>\n  metric === 'euclidean' ? 'l2' : metric === 'dot' ? 'ip' : 'cosine'\n\nexport class HnswlibVectorStore extends BaseVectorStore {\n  readonly capabilities: VectorStoreCapabilities = {\n    transactions: false,\n    namedVectors: false,\n    rename: true,\n    rawSql: false,\n    builtInEncoding: false,\n    // In-process and synchronous: a write is visible on resolve. The option is a no-op.\n    consistency: { configurable: false, default: 'strong', modes: ['strong'] },\n  }\n\n  #lib: any | null = null\n  #collections: Map<string, Collection> = new Map()\n\n  get #opts(): HnswlibVectorStoreOptions {\n    return this.options as HnswlibVectorStoreOptions\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.#lib) return\n    this.#lib = await getHnswlib()\n  }\n\n  async close(): Promise<void> {\n    this.#collections.clear()\n    this.#lib = null\n  }\n\n  async #ensureLib(): Promise<any> {\n    if (!this.#lib) await this.connect()\n    return this.#lib!\n  }\n\n  #coll(collection: string): Collection {\n    const c = this.#collections.get(collection)\n    if (!c) {\n      throw new E_VECTOR_STORE_COLLECTION_FAILED([\n        'collection',\n        'unknown collection: ' + collection,\n      ])\n    }\n    return c\n  }\n\n  async createCollection(spec: CollectionSpec, ifNotExists: boolean): Promise<void> {\n    const lib = await this.#ensureLib()\n    if (this.#collections.has(spec.collection)) {\n      if (ifNotExists) return\n      this.#collections.delete(spec.collection)\n    }\n    try {\n      const capacity = this.#opts.initialCapacity ?? 1024\n      const index = new lib.HierarchicalNSW(spaceFor(spec.vector.metric), spec.vector.dimensions)\n      index.initIndex(capacity)\n      this.#collections.set(spec.collection, {\n        index,\n        dims: spec.vector.dimensions,\n        metric: spec.vector.metric,\n        byId: new Map(),\n        idByLabel: new Map(),\n        nextLabel: 0,\n        capacity,\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    if (!this.#collections.has(collection)) {\n      if (ifExists) return\n      throw new E_VECTOR_STORE_COLLECTION_FAILED(['dropCollection', 'unknown collection'])\n    }\n    this.#collections.delete(collection)\n  }\n\n  async hasCollection(collection: string): Promise<boolean> {\n    return this.#collections.has(collection)\n  }\n\n  async renameCollection(from: string, to: string): Promise<void> {\n    const c = this.#collections.get(from)\n    if (!c) throw new E_VECTOR_STORE_UNSUPPORTED_OPERATION(['renameCollection', 'unknown: ' + from])\n    this.#collections.set(to, c)\n    this.#collections.delete(from)\n  }\n\n  #ensureCapacity(c: Collection, additional: number): void {\n    const needed = c.byId.size + additional\n    if (needed > c.capacity) {\n      const next = Math.max(needed, c.capacity * 2)\n      c.index.resizeIndex(next)\n      c.capacity = next\n    }\n  }\n\n  async executeUpsert(plan: UpsertPlan): Promise<void> {\n    if (plan.records.length === 0) return\n    validateRecords(plan.records)\n    await this.#ensureLib()\n    const c = this.#coll(plan.collection)\n    const expected = this.#opts.dimensions ?? c.dims\n    try {\n      this.#ensureCapacity(c, plan.records.length)\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        // Reuse the existing label on update (mark the old point deleted, then re-add under a\n        // fresh label so the vector value actually changes — hnswlib has no in-place update).\n        const existing = c.byId.get(r.id)\n        if (existing) {\n          try {\n            c.index.markDelete(existing.label)\n          } catch {\n            // already gone — ignore\n          }\n        }\n        this.#ensureCapacity(c, 1)\n        const label = c.nextLabel++\n        c.index.addPoint(vector, label)\n        c.idByLabel.set(label, r.id)\n        c.byId.set(r.id, { id: r.id, label, vector, document: r.document, metadata: r.metadata })\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    await this.#ensureLib()\n    const c = this.#coll(plan.collection)\n    const metric = this.#opts.metric ?? c.metric\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 rec = c.byId.get(plan.near.id)\n        if (!rec) {\n          throw new E_VECTOR_STORE_SEARCH_FAILED(['Referenced id not found: ' + plan.near.id])\n        }\n        queryVector = rec.vector\n      }\n    }\n\n    const offset = plan.offset ?? 0\n    try {\n      if (queryVector) {\n        // Over-fetch when filtering (and to absorb deleted points), then JS-filter for parity.\n        const live = c.byId.size\n        if (live === 0) return []\n        const want = plan.filter ? live : Math.min(plan.topK + offset, live)\n        const k = Math.min(Math.max(want, 1), live)\n        const res = c.index.searchKnn(queryVector, k)\n        const hits: Array<{ rec: StoredRecord; dist: number }> = []\n        for (let i = 0; i < res.neighbors.length; i++) {\n          const id = c.idByLabel.get(res.neighbors[i])\n          if (id === undefined) continue\n          const rec = c.byId.get(id)\n          if (rec) hits.push({ rec, dist: res.distances[i] })\n        }\n        const filtered = plan.filter\n          ? hits.filter((h) => evaluateFilter(plan.filter!, h.rec.metadata ?? {}))\n          : hits\n        return filtered\n          .slice(offset, offset + plan.topK)\n          .map((h) => this.#project(h.rec, plan, metric, h.dist))\n      } else {\n        // Filter-scan: serve from the sidecar (insertion order), JS-filter, no score.\n        const rows = [...c.byId.values()]\n        const filtered = plan.filter\n          ? rows.filter((rec) => evaluateFilter(plan.filter!, rec.metadata ?? {}))\n          : rows\n        return filtered\n          .slice(offset, offset + plan.topK)\n          .map((rec) => this.#project(rec, plan, metric, undefined))\n      }\n    } catch (err) {\n      throw new E_VECTOR_STORE_SEARCH_FAILED([String(err)])\n    }\n  }\n\n  #project(\n    rec: StoredRecord,\n    plan: SearchPlan,\n    metric: string,\n    dist: number | undefined\n  ): VectorMatch {\n    const proj = plan.projection\n    const out: VectorMatch = {}\n    if (proj.id) out.id = rec.id\n    if (proj.vector) out.vector = rec.vector.slice()\n    if (proj.document) out.document = rec.document\n    if (proj.metadata) out.metadata = rec.metadata ?? {}\n    if (dist !== undefined) {\n      out.score = normalizeScore(dist, metric as DistanceMetric, 'distance')\n    }\n    return out\n  }\n\n  async executeDelete(plan: DeletePlan): Promise<void> {\n    await this.#ensureLib()\n    const c = this.#coll(plan.collection)\n    try {\n      let targets: string[]\n      if (plan.ids && plan.ids.length > 0) {\n        targets = plan.ids\n      } else if (plan.filter) {\n        targets = [...c.byId.values()]\n          .filter((rec) => evaluateFilter(plan.filter!, rec.metadata ?? {}))\n          .map((rec) => rec.id)\n      } else {\n        targets = [...c.byId.keys()]\n      }\n      for (const id of targets) {\n        const rec = c.byId.get(id)\n        if (!rec) continue\n        try {\n          c.index.markDelete(rec.label)\n        } catch {\n          // already deleted — ignore\n        }\n        c.idByLabel.delete(rec.label)\n        c.byId.delete(id)\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/hnswlib.mjs

@@ -1,4 +1,4 @@
-import { s as isInstanceOf } from "../../tool_registry-D1pSSlsd.mjs";
+import { s as isInstanceOf } from "../../tool_registry-791Vrjtf.mjs";
 import "../../guards.mjs";
 import { evaluateFilter } from "./filters.mjs";
 import { normalizeScore } from "./helpers.mjs";
@@ -47,6 +47,7 @@ var HnswlibVectorStore = 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";
 	}