@dudousxd/nestjs-agent-rag 0.10.0 → 0.10.2

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/chunk.ts","../src/vector-store.ts","../src/metadata-patch.ts","../src/filter.ts","../src/memory-vector-store.ts","../src/pg-vector-store.ts","../src/redis-vector-store.ts","../src/retrieval-descriptor.ts","../src/embedding-retriever.ts","../src/keyword-retriever.ts","../src/lexical-retriever.ts","../src/hybrid-retriever.ts","../src/reranking-retriever.ts","../src/filtered-retriever.ts","../src/ingest.ts","../src/retrieval-telemetry.ts","../src/retrieval-tool.ts"],"sourcesContent":["export interface ChunkOptions {\n  /** Target max characters per chunk. Default 800. */\n  chunkSize?: number;\n  /** Characters of overlap carried from the end of one chunk into the next. Default 100. */\n  overlap?: number;\n  /**\n   * Treat the text as records joined by this string, and never split one across chunks.\n   *\n   * Default chunking is structure-blind: it breaks at the *latest* paragraph/sentence/word boundary\n   * in the window, which for record-shaped text means a cut lands mid-record routinely. That is fine\n   * for prose, where the two halves are still sentences. It is not fine for a table flattened to one\n   * record per row, because the half that keeps the row identifier and the half that keeps the value\n   * end up in different chunks, and neither can answer a question about that row on its own.\n   *\n   * With a separator set, whole records are packed greedily up to `chunkSize` and a record is never\n   * cut — except one longer than `chunkSize`, which has nowhere to go and is character-split as\n   * usual, since no chunker can avoid that.\n   *\n   * `overlap` is IGNORED in this mode, deliberately. Overlap exists to rescue a sentence that a\n   * boundary cut in half; a boundary that never falls inside a record has nothing to rescue, and\n   * carrying the tail of the previous chunk in would duplicate whole records into neighbouring chunks\n   * — paying for the same rows twice at embedding time and letting one row match from two places.\n   *\n   * Measured on a 200-row spreadsheet flattened to one field-labelled record per row (15 columns,\n   * ~800-char budget): blind chunking left 27% of records split, and on questions targeting a field\n   * on the far side of such a cut, BM25 answered 54/66 (MRR 0.818) against 66/66 (MRR 1.000) with\n   * records kept whole. The dense leg scored 7/66 either way — 200 near-identical rows produce\n   * near-identical vectors, so that leg cannot do row lookup at all and chunking does not change it.\n   */\n  separator?: string;\n}\n\n/**\n * Splits text into overlapping chunks for embedding. Greedy up to `chunkSize`, but prefers to break\n * on a paragraph → sentence → word boundary in the back half of the window (so a chunk rarely cuts\n * mid-sentence), then carries `overlap` characters into the next chunk to preserve context across\n * the seam. Pure and deterministic.\n */\nexport function chunkText(text: string, options: ChunkOptions = {}): string[] {\n  const chunkSize = options.chunkSize ?? 800;\n  const overlap = options.overlap ?? 100;\n  const normalized = text.trim();\n  if (normalized.length === 0) {\n    return [];\n  }\n  if (options.separator !== undefined && options.separator.length > 0) {\n    return chunkByRecord(normalized, chunkSize, options.separator);\n  }\n  if (normalized.length <= chunkSize) {\n    return [normalized];\n  }\n\n  const chunks: string[] = [];\n  let start = 0;\n  while (start < normalized.length) {\n    const end = Math.min(start + chunkSize, normalized.length);\n    let breakAt = end;\n    if (end < normalized.length) {\n      const window = normalized.slice(start, end);\n      const boundary = Math.max(\n        window.lastIndexOf('\\n\\n'),\n        window.lastIndexOf('. '),\n        window.lastIndexOf(' '),\n      );\n      // Only honour a boundary in the back half, else a tiny chunk cascades.\n      if (boundary > chunkSize / 2) {\n        breakAt = start + boundary + 1;\n      }\n    }\n    const chunk = normalized.slice(start, breakAt).trim();\n    if (chunk.length > 0) {\n      chunks.push(chunk);\n    }\n    if (breakAt >= normalized.length) {\n      break;\n    }\n    // Step forward with overlap, but always make progress (guards against a stuck boundary).\n    start = Math.max(breakAt - overlap, start + 1);\n  }\n  return chunks;\n}\n\n/**\n * Pack whole records up to `chunkSize`, never splitting one. See {@link ChunkOptions.separator}.\n *\n * A record longer than the budget is handed to the blind chunker, which is the honest fallback: it is\n * the same splitting that would have happened anyway, and it is confined to the one record that could\n * not fit rather than applied to the whole document.\n */\nfunction chunkByRecord(text: string, chunkSize: number, separator: string): string[] {\n  const chunks: string[] = [];\n  let current = '';\n  const flush = (): void => {\n    if (current.length > 0) {\n      chunks.push(current);\n      current = '';\n    }\n  };\n  for (const record of text.split(separator)) {\n    const trimmed = record.trim();\n    if (trimmed.length === 0) {\n      continue;\n    }\n    if (trimmed.length > chunkSize) {\n      flush();\n      // `separator: undefined` on purpose — this is the blind path, for the one record that cannot\n      // fit whole. Overlap stays off so the fallback does not reintroduce duplication the mode exists\n      // to avoid.\n      chunks.push(...chunkText(trimmed, { chunkSize, overlap: 0 }));\n      continue;\n    }\n    const candidate = current.length > 0 ? `${current}${separator}${trimmed}` : trimmed;\n    if (candidate.length > chunkSize) {\n      flush();\n      current = trimmed;\n    } else {\n      current = candidate;\n    }\n  }\n  flush();\n  return chunks;\n}\n","import type { Passage } from '@dudousxd/nestjs-agent-core';\nimport type { MetadataPatch } from './metadata-patch.js';\n\n/** A stored, embedded chunk. `embedding` length must match the store's configured dimensions. */\nexport interface VectorRecord {\n  id: string;\n  text: string;\n  embedding: number[];\n  /** Citation-facing origin (document title, URL, row id). */\n  source?: string;\n  metadata?: Record<string, unknown>;\n}\n\nexport interface VectorSearchOptions {\n  topK: number;\n  /** Exact-match metadata filter (all keys must equal). Passed through from `RetrieveOptions.filter`. */\n  filter?: Record<string, unknown>;\n}\n\n/**\n * The write + search side of RAG storage. `@dudousxd/nestjs-agent-rag` ships `MemoryVectorStore`\n * (in-JS cosine, tests + small scale) and `PgVectorStore` (pgvector); any impl works. Pair one with\n * an `EmbeddingProvider` via {@link import('./embedding-retriever.js').EmbeddingRetriever} to get a\n * core `Retriever`.\n *\n * Every method here is **required**, the enumeration and bulk-deletion half included. The rule for\n * where a new method goes, so the next person adding one has it rather than inferring it from\n * precedent:\n *\n * - **Required, on this interface**, when every backend *can* implement it from what it already\n *   stores. {@link VectorStore.updateMetadata}, {@link VectorStore.listDocumentIds},\n *   {@link VectorStore.removeMany}, {@link VectorStore.removeWhere} and\n *   {@link VectorStore.countChunks} are CRUD over the records the store already holds — the same\n *   footing as {@link VectorStore.remove} and\n *   {@link VectorStore.listDocuments}. Making them optional would buy nothing but a permanent\n *   `if (supported)` at every call site plus an unreachable \"and if it isn't?\" branch.\n * - **Optional, in a capability interface**, when some backend genuinely *cannot* without\n *   infrastructure the consumer has to adopt. The only such capability today is\n *   {@link LexicalVectorStore.searchText}: RediSearch has BM25 natively, Postgres would need a\n *   `tsvector` column plus a GIN index plus a migration the consumer must run, and\n *   `MemoryVectorStore` would have to implement BM25 itself.\n *\n * The test is whether a backend can do it at all — not whether adding it would inconvenience an\n * implementer who has already shipped.\n *\n * Implementations MUST apply every filter with exactly the same semantics as\n * {@link VectorStore.search} — including the empty-array deny primitive — because the filter is\n * routinely an access-control boundary, not a hint. On {@link VectorStore.removeWhere} that is not a\n * correctness nicety but the single most destructive thing an implementation could get wrong.\n */\nexport interface VectorStore {\n  upsert(records: VectorRecord[]): Promise<void>;\n  search(embedding: number[], options: VectorSearchOptions): Promise<Passage[]>;\n  /**\n   * Delete every chunk belonging to a source document — all records whose id is `${documentId}`\n   * or `${documentId}#<n>` (the id scheme {@link import('./ingest.js').chunkDocuments} produces).\n   * Use it to drop a document from the index, and before re-ingesting one: `upsert` overwrites\n   * matching ids but can't remove chunks a shorter new version no longer produces, so a re-ingest\n   * without a preceding `remove` leaves the old tail orphaned.\n   */\n  remove(documentId: string): Promise<void>;\n  /**\n   * Rewrite a document's metadata **without touching its text or its embeddings** — the update path\n   * for a dimension that is genuinely mutable (which bases a document is relevant to, who may see it,\n   * what it was reclassified as) rather than derived from its content.\n   *\n   * Without this, a consumer whose documents get re-classified has exactly two options, and both are\n   * bad: re-embed the whole document — paying the model bill, and burning the ingestion budget, to\n   * change a string — or refuse to stamp the dimension onto chunks at all and resolve it at query\n   * time instead, which turns a filter the index could have applied into a join the caller has to.\n   *\n   * `patch` is applied to **every chunk** of the document (metadata is a document-level property that\n   * happens to be stored per chunk), with the merge semantics documented on {@link MetadataPatch}:\n   * partial merge, `null` to remove a key, `undefined` ignored, values — including arrays — replaced\n   * wholesale.\n   *\n   * Returns **the number of chunks written**. An unknown `documentId` updates nothing and returns\n   * `0`; it does not throw. That is deliberate and matches {@link VectorStore.remove}, which is\n   * likewise silent on a document that isn't there: this is a reconciliation-shaped API, called by a\n   * loop diffing a source of truth against the index, and such a loop races with ingestion and\n   * deletion by construction. Turning \"the document was removed between the diff and the write\" into\n   * an exception would make the ordinary case an error, and the caller would have to catch and\n   * swallow it to get back the behaviour it wanted. The count gives the same information without\n   * that: `0` means nothing was there. (An empty patch also writes nothing and returns `0` — the\n   * return counts chunks *written*, not chunks *matched*.)\n   *\n   * Implementations MUST keep every representation of the metadata in step. A store that keeps both\n   * a filterable projection and a returned blob (RediSearch's `meta_*` TAGs beside its\n   * `metadata_json`) and updates only one makes the store lie to itself: a chunk that *filters* as\n   * one value but *reports* another, where which half you notice depends on whether you searched or\n   * read.\n   */\n  updateMetadata(documentId: string, patch: MetadataPatch): Promise<number>;\n  /**\n   * List the distinct source documents currently indexed (chunk ids collapsed back to their document\n   * by stripping the trailing `#<n>`), each with a representative chunk's `metadata`, optionally\n   * narrowed by a metadata `filter`. The enumeration seam for reconciliation: diff this against your\n   * source of truth to find documents to ingest (missing), re-ingest (a stored fingerprint like\n   * `size` changed), or {@link VectorStore.remove remove} (orphaned).\n   */\n  listDocuments(filter?: Record<string, unknown>): Promise<IndexedDocument[]>;\n\n  /**\n   * Read one document's chunks back — id, text, metadata — ordered by their position in the\n   * document, optionally paged with `limit`/`offset`.\n   *\n   * The gap this closes is that **the text a store holds is otherwise write-only**. Every other way\n   * back to it is a ranked query: {@link VectorStore.search} needs an embedding,\n   * {@link LexicalVectorStore.searchText} needs a query string, and both return whatever *matched*,\n   * in relevance order, capped at `topK`. Neither can answer \"show me what was indexed for this\n   * document, in order\" — the question you ask when retrieval returns the wrong passage and you need\n   * to know whether the chunker cut badly or the retriever chose badly. Without this, the only way to\n   * see stored text is to reach around the adapter into the backing engine, which is exactly the\n   * abstraction break a consumer adopts a store to avoid.\n   *\n   * Document-scoped rather than filter-scoped, matching {@link VectorStore.remove} and\n   * {@link VectorStore.updateMetadata}: ordering is the whole point, and \"position within the\n   * document\" is only meaningful once a document has been picked. Enumerate documents with\n   * {@link VectorStore.listDocuments} first when you need to sweep.\n   *\n   * An unknown `documentId` yields `[]`; it does not throw, matching `remove` and `updateMetadata`.\n   *\n   * NOT an access-control seam. It takes no metadata `filter` and applies none, so it cannot enforce\n   * one — a caller that gates retrieval on a metadata field (tenant, audience, collection) MUST\n   * resolve that gate itself before calling, exactly as it would before `remove`. It is deliberately\n   * shaped for an operator/debug surface, not for serving end users.\n   */\n  listChunks(documentId: string, options?: ListChunksOptions): Promise<StoredChunk[]>;\n\n  /**\n   * The distinct source document ids currently indexed, optionally narrowed by a metadata `filter` —\n   * {@link VectorStore.listDocuments} without the metadata. Use it when you only need the id set (a\n   * reconciliation diff against your source of truth, a count, a delete list): implementations are\n   * expected to skip fetching and parsing per-chunk metadata entirely, which is most of the cost of\n   * `listDocuments` on a large corpus.\n   *\n   * An empty-array filter value denies, yielding `[]`.\n   */\n  listDocumentIds(filter?: Record<string, unknown>): Promise<string[]>;\n\n  /**\n   * Delete every chunk of every one of `documentIds`, with the same per-document semantics as\n   * {@link VectorStore.remove} — but as one bulk operation rather than N independent ones. An empty\n   * array is a no-op.\n   *\n   * The gap this closes is asymptotic, not cosmetic: on the Redis adapter each `remove` is a `SCAN`\n   * that walks the whole keyspace, which in a real deployment also holds queues, workflow state and\n   * the app cache. Two thousand documents is two thousand full passes; this is one filtered query.\n   */\n  removeMany(documentIds: string[]): Promise<void>;\n\n  /**\n   * Delete every chunk matching a metadata `filter`, and resolve the number of **chunks** removed\n   * (not documents). The collection-maintenance primitive: dropping a collection, evicting a tenant,\n   * purging a retired audience.\n   *\n   * Two guard rails, because this is the one method here that destroys data:\n   *\n   * - **The empty-array deny is honoured, and it means \"delete nothing\".** `removeWhere({ audience: [] })`\n   *   removes zero chunks. Treating a deny as \"no filter\" would delete the entire corpus, which is\n   *   exactly inverted from what the caller asked for.\n   * - **The filter must be non-empty.** `removeWhere({})` throws {@link UnsafeRemovalError} rather\n   *   than wiping the store, because an empty object is overwhelmingly more likely to be a filter that\n   *   got built wrong (a dropped key, an `undefined` scope) than a deliberate request to delete\n   *   everything. Deliberate mass deletion stays available and stays explicit:\n   *   `removeMany(await store.listDocumentIds())`, or the backend's own drop.\n   *\n   * What it removes is exactly what a {@link VectorStore.search} carrying the same filter could\n   * reach — no more (it cannot escape the filter) and no less.\n   */\n  removeWhere(filter: Record<string, unknown>): Promise<number>;\n\n  /**\n   * How many **chunks** match `filter` (all of them when it is omitted) — a counted query, without\n   * transferring the chunks. Sizing a reindex, reporting a collection's footprint, and confirming a\n   * {@link VectorStore.removeWhere} did what you expected. An empty-array filter value denies,\n   * yielding `0`.\n   */\n  countChunks(filter?: Record<string, unknown>): Promise<number>;\n}\n\n/**\n * An **optional** capability a {@link VectorStore} may also implement: full-text (lexical) search\n * over the chunk text it already stores, using the backing engine's own keyword index — RediSearch's\n * BM25 over the `TEXT` field, say. Its point is the multi-process deployment: when ingestion runs on\n * a worker and search runs on an API pod, the API process never sees the chunks, so the in-process\n * {@link import('./keyword-retriever.js').KeywordRetriever} has nothing to index. A store that\n * implements this needs no second index, no corpus in JS heap, and no refresh window — a chunk is\n * lexically findable the moment it is upserted.\n *\n * Wrap it as a core `Retriever` with {@link import('./lexical-retriever.js').LexicalRetriever}.\n *\n * Implementations MUST apply `options.filter` with exactly the same semantics as\n * {@link VectorStore.search} — including the empty-array deny primitive — because the filter is\n * routinely an access-control boundary, not a hint.\n */\nexport interface LexicalVectorStore extends VectorStore {\n  /**\n   * Rank stored chunks against a natural-language `query` by keyword relevance. `options.filter`\n   * narrows exactly as in {@link VectorStore.search}. The returned `score` is the engine's own\n   * relevance score (BM25), which shares no scale with `search`'s cosine similarity — fuse the two\n   * with {@link import('./hybrid-retriever.js').HybridRetriever}, whose RRF is rank-based and so\n   * needs no common scale.\n   */\n  searchText(query: string, options: VectorSearchOptions): Promise<Passage[]>;\n}\n\n/**\n * Does this store carry the optional {@link LexicalVectorStore} capability? Lets a consumer pick the\n * store-backed lexical leg when available and fall back to `KeywordRetriever` (or to dense-only)\n * when it is not, without knowing which adapter it was handed.\n */\nexport function isLexicalVectorStore(store: VectorStore): store is LexicalVectorStore {\n  return typeof (store as Partial<LexicalVectorStore>).searchText === 'function';\n}\n\n/**\n * A destructive call was refused because its scope could not be trusted. Thrown by\n * {@link VectorStore.removeWhere} — never for something that merely matched nothing (that\n * is a legitimate result of `0`), only for a filter that would have deleted *more* than the caller\n * plausibly meant.\n */\nexport class UnsafeRemovalError extends Error {\n  constructor(\n    /** Why the removal was refused. */\n    readonly reason: 'empty-filter' | 'unindexed-field',\n    message: string,\n  ) {\n    super(message);\n    this.name = 'UnsafeRemovalError';\n  }\n}\n\n/** A distinct source document as seen by the index — its id plus a representative chunk's metadata. */\nexport interface IndexedDocument {\n  id: string;\n  metadata?: Record<string, unknown>;\n}\n\n/** One stored chunk, read back verbatim — what {@link VectorStore.listChunks} yields. */\nexport interface StoredChunk {\n  /** The chunk id: `${documentId}#<n>`, or the bare document id for a single-chunk document. */\n  id: string;\n  /** Zero-based position within the document, parsed from the id. A bare id is chunk `0`. */\n  index: number;\n  /** The chunk text as it was indexed — the exact string the embedding was computed from. */\n  text: string;\n  metadata?: Record<string, unknown>;\n}\n\n/** Paging for {@link VectorStore.listChunks}. Omit both to read the whole document. */\nexport interface ListChunksOptions {\n  /** Max chunks to return, applied after ordering by {@link StoredChunk.index}. */\n  limit?: number;\n  /** Chunks to skip, applied after ordering. */\n  offset?: number;\n}\n\n/** Chunk `n` of `${documentId}#<n>`; a bare document id (single-chunk document) is `0`. */\nexport function chunkIndexOf(chunkId: string): number {\n  const match = /#(\\d+)$/.exec(chunkId);\n  return match?.[1] === undefined ? 0 : Number(match[1]);\n}\n\n/** Collapse a chunk id (`${documentId}#<n>`) back to its source document id. */\nexport function documentIdOf(chunkId: string): string {\n  return chunkId.replace(/#\\d+$/, '');\n}\n","/**\n * A partial update to a document's metadata, as taken by\n * {@link import('./vector-store.js').VectorStore.updateMetadata}. Deliberately *partial*: the useful\n * shape is \"this one dimension was reclassified\", not \"here is the whole metadata object again\" —\n * a caller that had the whole object would have to reconstruct fields it does not own (the ingestion\n * fingerprint, the source, the mime type) just to change one string, and would silently drop them\n * the day the library adds another.\n *\n * The semantics are RFC 7386 (JSON Merge Patch), with one deliberate narrowing:\n *\n * - **Merge, not replace.** Keys present in the patch are written; keys absent from it keep their\n *   stored value.\n * - **`null` removes the key.** That is the RFC's sentinel and it is the *only* way to remove one.\n *   The consequence — a literal `null` cannot be stored as a value — is intended: metadata is a\n *   filter surface, and \"the key is absent\" and \"the key is null\" would filter identically anyway.\n * - **`undefined` is ignored** — the key is left exactly as stored, as if the patch had not mentioned\n *   it. `undefined` does not survive `JSON.stringify`, and a patch routinely crosses a JSON boundary\n *   (an HTTP body, a durable-workflow step payload) on its way here; honouring it would make\n *   `{ audience: undefined }` mean *delete* on one side of that boundary and *no-op* on the other.\n *   It is also what `{ ...doc, audience: doc.audience }` produces by accident, and an accidental\n *   deletion of an access-control dimension is the worst outcome this API can have. Removing a key\n *   is therefore always spelled `null`.\n * - **Shallow.** A value replaces wholesale; it is not merged into the stored value. This is the\n *   narrowing versus RFC 7386, which recurses into nested objects. It matters most for **arrays**,\n *   where wholesale replacement is certainly what a caller means: `{ bases: ['A', 'C'] }` sets the\n *   document's bases to exactly A and C — it does not append to, or union with, what was there. An\n *   array-valued key is a *set-valued dimension* (the multi-valued TAG a store filters on), and the\n *   only sane way to shrink such a set is to state the new one.\n */\nexport type MetadataPatch = Record<string, unknown>;\n\n/**\n * Split a patch into the assignments it makes and the keys it removes — the shape a store that\n * updates metadata declaratively (SQL, a hash write + field delete) needs, since setting and\n * unsetting are different operations there. `undefined` values appear in neither.\n */\nexport function splitMetadataPatch(patch: MetadataPatch): {\n  set: Record<string, unknown>;\n  remove: string[];\n} {\n  const set: Record<string, unknown> = {};\n  const remove: string[] = [];\n  for (const [key, value] of Object.entries(patch)) {\n    if (value === null) {\n      remove.push(key);\n    } else if (value !== undefined) {\n      set[key] = value;\n    }\n  }\n  return { set, remove };\n}\n\n/** Does this patch write anything at all? An empty (or all-`undefined`) patch is a no-op. */\nexport function isEmptyMetadataPatch(patch: MetadataPatch): boolean {\n  const { set, remove } = splitMetadataPatch(patch);\n  return Object.keys(set).length === 0 && remove.length === 0;\n}\n\n/**\n * Apply a {@link MetadataPatch} to a document's stored metadata, returning a NEW object — the\n * reference implementation of the semantics documented on `MetadataPatch`, so every adapter that\n * merges in JS agrees with every other one. Never mutates its input: `MemoryVectorStore` hands out\n * the very object a caller upserted, and quietly rewriting it under them would be a surprise no\n * other store reproduces.\n */\nexport function applyMetadataPatch(\n  metadata: Record<string, unknown> | undefined,\n  patch: MetadataPatch,\n): Record<string, unknown> {\n  const { set, remove } = splitMetadataPatch(patch);\n  const next: Record<string, unknown> = { ...metadata, ...set };\n  for (const key of remove) {\n    delete next[key];\n  }\n  return next;\n}\n","/** Metadata filter, shared by the in-memory {@link import('./memory-vector-store.js').MemoryVectorStore}\n * and {@link import('./keyword-retriever.js').KeywordRetriever}. Every key must match:\n *\n * - a **scalar** filter value keeps exact-match — the record's value must equal it;\n * - an **array** filter value means **match-any** (OR / set membership) — the record matches when its\n *   value for that key is one of them, or (for a multi-valued record) shares at least one element.\n *   An empty array matches nothing (no value is a member of the empty set) — the deny primitive.\n *\n * Array-valued filters are how a caller expresses capability-style access control over a shared store\n * (e.g. `{ audience: ['public', 'role:ADMIN', 'base:…'] }`) without the store knowing what a token means.\n */\nexport function matchesFilter(\n  metadata: Record<string, unknown> | undefined,\n  filter: Record<string, unknown>,\n): boolean {\n  const entries = Object.entries(filter);\n  if (metadata === undefined) {\n    return entries.length === 0;\n  }\n  return entries.every(([key, expected]) => {\n    if (Array.isArray(expected)) {\n      const actual = metadata[key];\n      return Array.isArray(actual)\n        ? actual.some((value) => expected.includes(value))\n        : expected.includes(actual);\n    }\n    return metadata[key] === expected;\n  });\n}\n\n/**\n * Does this filter provably match **nothing**? True when any key carries an empty array, because\n * nothing is a member of the empty set and every key must match (AND). This is the package's **deny\n * primitive** — the shape a capability-style ACL collapses to for an actor holding no tokens — so\n * every store has to honour it identically, and a store that cannot express \"match nothing\" in its\n * query language (RediSearch has no valid empty-tag syntax) must short-circuit on it instead.\n *\n * It is exported from this module rather than reimplemented per adapter precisely because getting it\n * wrong is *silent*: a read path that ignores it over-returns, and a **write** path that ignores it\n * (see {@link import('./vector-store.js').VectorStore.removeWhere}) deletes the corpus a\n * deny was supposed to protect.\n */\nexport function filterMatchesNothing(filter?: Record<string, unknown>): boolean {\n  if (filter === undefined) {\n    return false;\n  }\n  return Object.values(filter).some((value) => Array.isArray(value) && value.length === 0);\n}\n","import type { Passage } from '@dudousxd/nestjs-agent-core';\nimport { filterMatchesNothing, matchesFilter } from './filter.js';\nimport { type MetadataPatch, applyMetadataPatch, isEmptyMetadataPatch } from './metadata-patch.js';\nimport type { RetrievalDescriptor } from './retrieval-descriptor.js';\nimport {\n  type IndexedDocument,\n  type ListChunksOptions,\n  type StoredChunk,\n  UnsafeRemovalError,\n  type VectorRecord,\n  type VectorSearchOptions,\n  type VectorStore,\n  chunkIndexOf,\n  documentIdOf,\n} from './vector-store.js';\n\n/**\n * An in-process {@link VectorStore} — cosine similarity over a Map, no infra. The reference adapter\n * for tests and small/embedded corpora; for production scale use `PgVectorStore` (or your own).\n *\n * It implements the enumeration and bulk-deletion half of {@link VectorStore} too. There is no\n * performance argument for it here — every method below is a loop over the same Map — but a store that tests are\n * written against has to behave identically to the one production runs, and the semantics that matter\n * (`removeWhere` refusing an empty filter, an empty-array filter deleting nothing) are behavioural,\n * not incidental to Redis.\n */\nexport class MemoryVectorStore implements VectorStore {\n  private readonly records = new Map<string, VectorRecord>();\n\n  /**\n   * Telemetry self-description. No `collection`: there is no namespace to name — the corpus IS this\n   * instance, and two `MemoryVectorStore`s in one process are two corpora with nothing to tell them\n   * apart on a dashboard.\n   */\n  describeRetrieval(): RetrievalDescriptor {\n    return { store: 'memory' };\n  }\n\n  async upsert(records: VectorRecord[]): Promise<void> {\n    for (const record of records) {\n      this.records.set(record.id, record);\n    }\n  }\n\n  async remove(documentId: string): Promise<void> {\n    for (const id of this.records.keys()) {\n      if (documentIdOf(id) === documentId) {\n        this.records.delete(id);\n      }\n    }\n  }\n\n  /**\n   * Merge `patch` into every chunk of `documentId`, leaving `text` and `embedding` untouched. The\n   * record is *replaced* rather than mutated: `upsert` stores the caller's own object, and patching\n   * it in place would edit an object the caller still holds — a surprise no out-of-process store\n   * could reproduce, and therefore one this reference adapter must not teach.\n   */\n  async updateMetadata(documentId: string, patch: MetadataPatch): Promise<number> {\n    if (isEmptyMetadataPatch(patch)) {\n      return 0;\n    }\n    let updated = 0;\n    for (const [id, record] of this.records) {\n      if (documentIdOf(id) !== documentId) {\n        continue;\n      }\n      this.records.set(id, { ...record, metadata: applyMetadataPatch(record.metadata, patch) });\n      updated += 1;\n    }\n    return updated;\n  }\n\n  async listDocuments(filter?: Record<string, unknown>): Promise<IndexedDocument[]> {\n    const documents = new Map<string, IndexedDocument>();\n    for (const record of this.records.values()) {\n      if (filter !== undefined && !matchesFilter(record.metadata, filter)) {\n        continue;\n      }\n      const id = documentIdOf(record.id);\n      if (!documents.has(id)) {\n        documents.set(id, {\n          id,\n          ...(record.metadata !== undefined ? { metadata: record.metadata } : {}),\n        });\n      }\n    }\n    return [...documents.values()];\n  }\n\n  /**\n   * The chunks of one document, in document order. See {@link VectorStore.listChunks}.\n   *\n   * Insertion order is not document order — `upsert` stores whatever the caller passed, and a\n   * re-ingest that rewrites chunk 3 alone moves it to the end of the Map. So this sorts by the index\n   * parsed from the id, the same thing the SQL and Redis adapters order by, rather than trusting the\n   * Map. A reference adapter that returned \"usually ordered\" would let a consumer ship a bug that\n   * only shows up on the store tests are NOT written against.\n   */\n  async listChunks(documentId: string, options?: ListChunksOptions): Promise<StoredChunk[]> {\n    const chunks: StoredChunk[] = [];\n    for (const record of this.records.values()) {\n      if (documentIdOf(record.id) !== documentId) {\n        continue;\n      }\n      chunks.push({\n        id: record.id,\n        index: chunkIndexOf(record.id),\n        text: record.text,\n        ...(record.metadata !== undefined ? { metadata: record.metadata } : {}),\n      });\n    }\n    chunks.sort((a, b) => a.index - b.index);\n    const offset = options?.offset ?? 0;\n    return options?.limit === undefined\n      ? chunks.slice(offset)\n      : chunks.slice(offset, offset + options.limit);\n  }\n\n  async listDocumentIds(filter?: Record<string, unknown>): Promise<string[]> {\n    if (filterMatchesNothing(filter)) {\n      return [];\n    }\n    const documents = new Set<string>();\n    for (const record of this.records.values()) {\n      if (filter !== undefined && !matchesFilter(record.metadata, filter)) {\n        continue;\n      }\n      documents.add(documentIdOf(record.id));\n    }\n    return [...documents];\n  }\n\n  async removeMany(documentIds: string[]): Promise<void> {\n    if (documentIds.length === 0) {\n      return;\n    }\n    const wanted = new Set(documentIds);\n    for (const id of this.records.keys()) {\n      if (wanted.has(documentIdOf(id))) {\n        this.records.delete(id);\n      }\n    }\n  }\n\n  /**\n   * See {@link VectorStore.removeWhere}. The empty-array short-circuit below is redundant\n   * against `matchesFilter` (which already matches nothing for an empty array) and is kept anyway:\n   * this is the method where \"the filter accidentally means everything\" destroys data, so the deny is\n   * stated where a reader can see it rather than inferred from another module's truth table.\n   */\n  async removeWhere(filter: Record<string, unknown>): Promise<number> {\n    if (Object.keys(filter).length === 0) {\n      throw new UnsafeRemovalError(\n        'empty-filter',\n        'removeWhere() refuses an empty filter: it would delete every chunk in the store. ' +\n          'Pass a filter that scopes the removal, or delete deliberately with ' +\n          'removeMany(await store.listDocumentIds()).',\n      );\n    }\n    if (filterMatchesNothing(filter)) {\n      return 0;\n    }\n    let removed = 0;\n    for (const [id, record] of this.records) {\n      if (matchesFilter(record.metadata, filter)) {\n        this.records.delete(id);\n        removed += 1;\n      }\n    }\n    return removed;\n  }\n\n  async countChunks(filter?: Record<string, unknown>): Promise<number> {\n    if (filterMatchesNothing(filter)) {\n      return 0;\n    }\n    let count = 0;\n    for (const record of this.records.values()) {\n      if (filter === undefined || matchesFilter(record.metadata, filter)) {\n        count += 1;\n      }\n    }\n    return count;\n  }\n\n  async search(embedding: number[], options: VectorSearchOptions): Promise<Passage[]> {\n    const scored: Passage[] = [];\n    for (const record of this.records.values()) {\n      if (options.filter !== undefined && !matchesFilter(record.metadata, options.filter)) {\n        continue;\n      }\n      scored.push({\n        id: record.id,\n        text: record.text,\n        score: cosineSimilarity(embedding, record.embedding),\n        ...(record.source !== undefined ? { source: record.source } : {}),\n        ...(record.metadata !== undefined ? { metadata: record.metadata } : {}),\n      });\n    }\n    return scored.sort((a, b) => b.score - a.score).slice(0, options.topK);\n  }\n}\n\nfunction cosineSimilarity(a: number[], b: number[]): number {\n  let dot = 0;\n  let normA = 0;\n  let normB = 0;\n  const length = Math.min(a.length, b.length);\n  for (let index = 0; index < length; index += 1) {\n    const valueA = a[index] ?? 0;\n    const valueB = b[index] ?? 0;\n    dot += valueA * valueB;\n    normA += valueA * valueA;\n    normB += valueB * valueB;\n  }\n  const denominator = Math.sqrt(normA) * Math.sqrt(normB);\n  return denominator === 0 ? 0 : dot / denominator;\n}\n","import type { Passage } from '@dudousxd/nestjs-agent-core';\nimport { filterMatchesNothing } from './filter.js';\nimport { type MetadataPatch, isEmptyMetadataPatch, splitMetadataPatch } from './metadata-patch.js';\nimport type { RetrievalDescriptor } from './retrieval-descriptor.js';\nimport type {\n  IndexedDocument,\n  ListChunksOptions,\n  StoredChunk,\n  VectorRecord,\n  VectorSearchOptions,\n  VectorStore,\n} from './vector-store.js';\nimport { UnsafeRemovalError } from './vector-store.js';\n\n/**\n * The minimal Postgres surface {@link PgVectorStore} needs — adapt your own `pg` / `postgres.js`\n * client to it, so this package pulls in NO driver (bring your own, like the store adapters take an\n * ORM handle and the Redis transport takes a client). `query` runs parameterized SQL (`$1,$2,…`) and\n * resolves the result rows.\n */\nexport interface PgClient {\n  query<Row = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<Row[]>;\n}\n\nexport interface PgVectorStoreOptions {\n  /** Table name. Default `agent_rag_chunks`. */\n  table?: string;\n  /** Embedding width — must match your model (e.g. 1536 for text-embedding-3-small). Default 1536. */\n  dimensions?: number;\n}\n\n/**\n * A pgvector-backed {@link VectorStore} — the production reference adapter. Cosine distance via the\n * `<=>` operator over an HNSW index; metadata in a `jsonb` column filtered with `@>`. Call\n * {@link PgVectorStore.ensureSchema} once at boot to create the extension, table, and index.\n *\n * This store does **not** implement the optional\n * {@link import('./vector-store.js').LexicalVectorStore} capability, unlike\n * {@link import('./redis-vector-store.js').RedisVectorStore}. That is a deliberate omission, not an\n * oversight: RediSearch already indexes the chunk text (the schema declares it `TEXT`), so BM25 is\n * free there, whereas the table below indexes nothing lexically — `text` is a plain column with no\n * `tsvector` and no GIN index. Adding one is not a transparent upgrade:\n *\n * - it is new DDL in `ensureSchema`, and `CREATE INDEX` (non-concurrently, as this method must, since\n *   `CONCURRENTLY` cannot run in a transaction) takes a write lock on an already-populated chunks\n *   table — a boot-time stall proportional to corpus size for every existing deployment;\n * - it forces a text-search-configuration choice (`english` vs `simple` vs …) that must match between\n *   the index expression and every query, or Postgres silently ignores the index and sequentially\n *   scans the corpus — a failure mode that stays *correct* while quietly getting slower with scale.\n *\n * Both want a migration a consumer runs and observes, not a side effect of upgrading the library. The\n * capability interface is open, so a `PgLexicalVectorStore` (or an option here, gated on an\n * explicitly-created index) can be added later without changing anything else.\n *\n * The enumeration and bulk-deletion methods {@link VectorStore} requires need nothing new here,\n * unlike the lexical capability above: enumeration and bulk deletion are `DISTINCT`, `= ANY($1)`, `DELETE … WHERE`\n * and `count(*)` over the table and index that already exist. No DDL, no boot-time lock, no migration.\n */\nexport class PgVectorStore implements VectorStore {\n  private readonly table: string;\n  private readonly dimensions: number;\n\n  constructor(\n    private readonly client: PgClient,\n    options: PgVectorStoreOptions = {},\n  ) {\n    this.table = options.table ?? 'agent_rag_chunks';\n    this.dimensions = options.dimensions ?? 1536;\n  }\n\n  /** Telemetry self-description — the table is the namespace a retrieval was served from. */\n  describeRetrieval(): RetrievalDescriptor {\n    return { store: 'pg', collection: this.table };\n  }\n\n  /** Idempotent DDL: the `vector` extension, the chunks table, and the cosine HNSW index. */\n  async ensureSchema(): Promise<void> {\n    await this.client.query('CREATE EXTENSION IF NOT EXISTS vector');\n    await this.client.query(\n      `CREATE TABLE IF NOT EXISTS ${this.table} (\n        id TEXT PRIMARY KEY,\n        text TEXT NOT NULL,\n        source TEXT,\n        metadata JSONB,\n        embedding vector(${this.dimensions}) NOT NULL\n      )`,\n    );\n    await this.client.query(\n      `CREATE INDEX IF NOT EXISTS ${this.table}_embedding_idx\n        ON ${this.table} USING hnsw (embedding vector_cosine_ops)`,\n    );\n  }\n\n  async upsert(records: VectorRecord[]): Promise<void> {\n    for (const record of records) {\n      await this.client.query(\n        `INSERT INTO ${this.table} (id, text, source, metadata, embedding)\n         VALUES ($1, $2, $3, $4, $5)\n         ON CONFLICT (id) DO UPDATE SET\n           text = EXCLUDED.text,\n           source = EXCLUDED.source,\n           metadata = EXCLUDED.metadata,\n           embedding = EXCLUDED.embedding`,\n        [\n          record.id,\n          record.text,\n          record.source ?? null,\n          record.metadata !== undefined ? JSON.stringify(record.metadata) : null,\n          toVectorLiteral(record.embedding),\n        ],\n      );\n    }\n  }\n\n  async remove(documentId: string): Promise<void> {\n    await this.client.query(`DELETE FROM ${this.table} WHERE ${DOCUMENT_ID_FROM_CHUNK} = $1`, [\n      documentId,\n    ]);\n  }\n\n  /**\n   * Rewrite a document's metadata without re-embedding it. See {@link VectorStore.updateMetadata}\n   * for the semantics; here the whole thing is one statement, because jsonb already *is* the merge:\n   * `||` is a shallow key-wise merge (right side wins, arrays replaced wholesale — precisely\n   * {@link MetadataPatch}) and `- text[]` drops the keys the patch removed. `COALESCE` covers a chunk\n   * ingested with no metadata at all, so a patch can create the object rather than no-op on `NULL`.\n   *\n   * Unlike RediSearch there is no second representation to keep in step — the `metadata` column is\n   * both what `search` filters on and what it returns — so the correctness trap the Redis adapter has\n   * to work for simply does not exist here. `RETURNING id` is what supplies the chunk count, since\n   * {@link PgClient} is a rows-only surface with no `rowCount`.\n   */\n  async updateMetadata(documentId: string, patch: MetadataPatch): Promise<number> {\n    if (isEmptyMetadataPatch(patch)) {\n      return 0;\n    }\n    const { set, remove } = splitMetadataPatch(patch);\n    const rows = await this.client.query<{ id: string }>(\n      `UPDATE ${this.table}\n          SET metadata = (COALESCE(metadata, '{}'::jsonb) || $2::jsonb) - $3::text[]\n        WHERE ${DOCUMENT_ID_FROM_CHUNK} = $1\n        RETURNING id`,\n      [documentId, JSON.stringify(set), remove],\n    );\n    return rows.length;\n  }\n\n  async listDocuments(filter?: Record<string, unknown>): Promise<IndexedDocument[]> {\n    const where = buildWhere(filter, 1);\n    // DISTINCT ON collapses chunks to one row per document; all chunks share the doc's metadata.\n    const rows = await this.client.query<{\n      doc_id: string;\n      metadata: Record<string, unknown> | null;\n    }>(\n      `SELECT DISTINCT ON (${DOCUMENT_ID_FROM_CHUNK}) ${DOCUMENT_ID_FROM_CHUNK} AS doc_id, metadata\n       FROM ${this.table}\n       ${where.sql}\n       ORDER BY ${DOCUMENT_ID_FROM_CHUNK}`,\n      where.params,\n    );\n    return rows.map((row) => ({\n      id: row.doc_id,\n      ...(row.metadata !== null ? { metadata: row.metadata } : {}),\n    }));\n  }\n\n  /**\n   * The chunks of one document, in document order. See {@link VectorStore.listChunks}.\n   *\n   * The order is computed from the id rather than stored: `#12` must sort after `#2`, which a plain\n   * `ORDER BY id` gets wrong on every document past ten chunks because it compares text. So the\n   * trailing number is extracted and cast to `int`, and a bare id (a single-chunk document, which\n   * carries no `#n` suffix) collapses to `0` — the same rule `chunkIndexOf` applies in the other two\n   * adapters.\n   *\n   * `embedding` is left out of the projection: it is the widest column in the table and useless to a\n   * caller reading text back.\n   */\n  async listChunks(documentId: string, options?: ListChunksOptions): Promise<StoredChunk[]> {\n    const params: unknown[] = [documentId];\n    let sql = `SELECT id, ${CHUNK_INDEX_FROM_ID} AS chunk_index, text, metadata\n       FROM ${this.table}\n       WHERE ${DOCUMENT_ID_FROM_CHUNK} = $1\n       ORDER BY chunk_index`;\n    if (options?.limit !== undefined) {\n      params.push(options.limit);\n      sql += ` LIMIT $${params.length}`;\n    }\n    if (options?.offset !== undefined) {\n      params.push(options.offset);\n      sql += ` OFFSET $${params.length}`;\n    }\n    const rows = await this.client.query<{\n      id: string;\n      chunk_index: number;\n      text: string;\n      metadata: Record<string, unknown> | null;\n    }>(sql, params);\n    return rows.map((row) => ({\n      id: row.id,\n      index: Number(row.chunk_index),\n      text: row.text,\n      ...(row.metadata !== null ? { metadata: row.metadata } : {}),\n    }));\n  }\n\n  /** {@link listDocuments} without the metadata: one `DISTINCT` over the derived document id. */\n  async listDocumentIds(filter?: Record<string, unknown>): Promise<string[]> {\n    if (filterMatchesNothing(filter)) {\n      return [];\n    }\n    const where = buildWhere(filter, 1);\n    const rows = await this.client.query<{ doc_id: string }>(\n      `SELECT DISTINCT ${DOCUMENT_ID_FROM_CHUNK} AS doc_id\n       FROM ${this.table}\n       ${where.sql}\n       ORDER BY doc_id`,\n      where.params,\n    );\n    return rows.map((row) => row.doc_id);\n  }\n\n  /** N documents in one statement — the set-based form of {@link PgVectorStore.remove}. */\n  async removeMany(documentIds: string[]): Promise<void> {\n    if (documentIds.length === 0) {\n      return;\n    }\n    await this.client.query(\n      `DELETE FROM ${this.table} WHERE ${DOCUMENT_ID_FROM_CHUNK} = ANY($1::text[])`,\n      [documentIds],\n    );\n  }\n\n  /**\n   * See {@link VectorStore.removeWhere}: empty filter object throws, empty-array value\n   * deletes nothing. The count comes from `RETURNING id` rather than a driver-specific `rowCount`,\n   * because {@link PgClient} is deliberately just \"run SQL, get rows\".\n   */\n  async removeWhere(filter: Record<string, unknown>): Promise<number> {\n    if (Object.keys(filter).length === 0) {\n      throw new UnsafeRemovalError(\n        'empty-filter',\n        'removeWhere() refuses an empty filter: it would delete every chunk in the table. ' +\n          'Pass a filter that scopes the removal, or delete deliberately with ' +\n          'removeMany(await store.listDocumentIds()).',\n      );\n    }\n    // Redundant with buildWhere's `false` clause, and stated anyway — the deny primitive should be\n    // visible at the destructive call site, not one indirection away.\n    if (filterMatchesNothing(filter)) {\n      return 0;\n    }\n    const where = buildWhere(filter, 1);\n    const rows = await this.client.query<{ id: string }>(\n      `DELETE FROM ${this.table} ${where.sql} RETURNING id`,\n      where.params,\n    );\n    return rows.length;\n  }\n\n  async countChunks(filter?: Record<string, unknown>): Promise<number> {\n    if (filterMatchesNothing(filter)) {\n      return 0;\n    }\n    const where = buildWhere(filter, 1);\n    const rows = await this.client.query<{ count: number | string }>(\n      `SELECT count(*)::int AS count FROM ${this.table} ${where.sql}`,\n      where.params,\n    );\n    return Number(rows[0]?.count ?? 0);\n  }\n\n  async search(embedding: number[], options: VectorSearchOptions): Promise<Passage[]> {\n    const vector = toVectorLiteral(embedding);\n    // $1 = query vector, $2 = topK; metadata-filter params start at $3.\n    const where = buildWhere(options.filter, 3);\n    const rows = await this.client.query<PgRow>(\n      `SELECT id, text, source, metadata, 1 - (embedding <=> $1::vector) AS score\n       FROM ${this.table}\n       ${where.sql}\n       ORDER BY embedding <=> $1::vector\n       LIMIT $2`,\n      [vector, options.topK, ...where.params],\n    );\n    return rows.map((row) => ({\n      id: row.id,\n      text: row.text,\n      score: Number(row.score),\n      ...(row.source !== null ? { source: row.source } : {}),\n      ...(row.metadata !== null ? { metadata: row.metadata } : {}),\n    }));\n  }\n}\n\ninterface PgRow {\n  id: string;\n  text: string;\n  source: string | null;\n  metadata: Record<string, unknown> | null;\n  score: number | string;\n}\n\n/**\n * Build the `WHERE` fragment for a metadata `filter`, with parameter placeholders numbered from\n * `startIndex`. Scalar values collapse into a single `@>` jsonb-containment check (exact-match, as\n * before). An **array** value is a **match-any** (OR / set membership) check via jsonb `?|`: the\n * record matches when its value for that key — scalar or array — shares an element with the filter\n * array. An empty array can never match (deny primitive). Keys are passed as parameters (`metadata->$k`)\n * so a caller-supplied metadata key can't inject SQL. Returns `{ sql: '', params: [] }` when there is\n * no filter, preserving the previous unfiltered query shape.\n */\nfunction buildWhere(\n  filter: Record<string, unknown> | undefined,\n  startIndex: number,\n): { sql: string; params: unknown[] } {\n  if (filter === undefined || Object.keys(filter).length === 0) {\n    return { sql: '', params: [] };\n  }\n  const clauses: string[] = [];\n  const params: unknown[] = [];\n  const scalar: Record<string, unknown> = {};\n  let index = startIndex;\n  for (const [key, value] of Object.entries(filter)) {\n    if (Array.isArray(value)) {\n      if (value.length === 0) {\n        clauses.push('false');\n        continue;\n      }\n      const keyParam = `$${index}`;\n      params.push(key);\n      index += 1;\n      const arrParam = `$${index}`;\n      params.push(value.map(String));\n      index += 1;\n      clauses.push(\n        `(CASE WHEN jsonb_typeof(metadata->${keyParam}) = 'array' ` +\n          `THEN metadata->${keyParam} ELSE jsonb_build_array(metadata->${keyParam}) END) ?| ${arrParam}::text[]`,\n      );\n    } else {\n      scalar[key] = value;\n    }\n  }\n  if (Object.keys(scalar).length > 0) {\n    clauses.push(`metadata @> $${index}::jsonb`);\n    params.push(JSON.stringify(scalar));\n    index += 1;\n  }\n  return { sql: `WHERE ${clauses.join(' AND ')}`, params };\n}\n\n/**\n * SQL that collapses a chunk id (`${documentId}#<n>`) back to its source document id — the pgvector\n * mirror of {@link import('./vector-store.js').documentIdOf}. Shared by `remove` and\n * `listDocuments` so both key on the exact same definition of \"chunk belongs to document\".\n */\nconst DOCUMENT_ID_FROM_CHUNK = \"regexp_replace(id, '#[0-9]+$', '')\";\n\n/** The `n` of `…#<n>` as an integer, so chunks sort numerically; a bare id (no suffix) is `0`. */\nconst CHUNK_INDEX_FROM_ID = \"COALESCE((substring(id from '#([0-9]+)$'))::int, 0)\";\n\n/** pgvector accepts a `'[1,2,3]'` text literal cast to `vector`. */\nfunction toVectorLiteral(embedding: number[]): string {\n  return `[${embedding.join(',')}]`;\n}\n","import type { Passage } from '@dudousxd/nestjs-agent-core';\nimport { filterMatchesNothing } from './filter.js';\nimport { type MetadataPatch, applyMetadataPatch, isEmptyMetadataPatch } from './metadata-patch.js';\nimport type { RetrievalDescriptor } from './retrieval-descriptor.js';\nimport {\n  type IndexedDocument,\n  type LexicalVectorStore,\n  type ListChunksOptions,\n  type StoredChunk,\n  UnsafeRemovalError,\n  type VectorRecord,\n  type VectorSearchOptions,\n  type VectorStore,\n  chunkIndexOf,\n  documentIdOf,\n} from './vector-store.js';\n\n/**\n * The minimal Redis surface {@link RedisVectorStore} needs: send a raw command and get the reply.\n * Both `node-redis` (`client.sendCommand(args)`) and `ioredis` (wrap `redis.call`) satisfy it — so\n * this package pulls in NO Redis driver (bring your own, like the other adapters). Requires the\n * RediSearch module (Redis Stack / Redis 8+).\n */\nexport interface RedisSearchClient {\n  sendCommand(args: (string | Buffer)[]): Promise<unknown>;\n}\n\n/**\n * The index that already exists in Redis contradicts this store's configuration in a way that cannot\n * be repaired in place. Thrown by {@link RedisVectorStore.ensureSchema} — which would otherwise have\n * returned happily and left every subsequent query quietly wrong.\n *\n * The canonical case is a changed embedding width (a model swap, 1024 → 1536): RediSearch fixes a\n * vector field's `DIM` at `FT.CREATE`, and every vector already stored was produced by the OLD model,\n * so there is no in-place fix — the index has to be dropped and the corpus re-embedded. That is\n * destructive and belongs to the host, never to a boot-time `ensureSchema`.\n */\nexport class RedisVectorSchemaMismatchError extends Error {\n  constructor(\n    /** The RediSearch index that was inspected. */\n    readonly index: string,\n    /** The index attribute that differs (e.g. `embedding`, `meta_tenant`). */\n    readonly field: string,\n    /** What this store is configured for. */\n    readonly expected: string,\n    /** What `FT.INFO` reports the live index has. */\n    readonly actual: string,\n    remedy: string,\n  ) {\n    super(\n      `RediSearch index \"${index}\" disagrees with this RedisVectorStore's configuration: ` +\n        `field \"${field}\" is ${actual}, expected ${expected}. ${remedy}`,\n    );\n    this.name = 'RedisVectorSchemaMismatchError';\n  }\n}\n\nexport interface RedisVectorStoreOptions {\n  /** RediSearch index name. Default `agent_rag_idx`. */\n  index?: string;\n  /** Key prefix for the per-chunk hashes. Default `agent_rag:`. */\n  prefix?: string;\n  /** Embedding width — must match your model (e.g. 1536). Default 1536. */\n  dimensions?: number;\n  /**\n   * Metadata keys to index as filterable TAG fields. RediSearch needs filter fields declared up\n   * front, so only keys listed here can be passed in `search`'s `filter`. Default none.\n   */\n  filterableFields?: string[];\n  /**\n   * RediSearch scorer used by {@link RedisVectorStore.searchText}. Default `BM25` — the standard\n   * lexical ranking, and the same family the in-process `KeywordRetriever` implements. Override for\n   * a server that names it differently (`BM25STD` on newer builds) or to pick `TFIDF`/`DISMAX`.\n   */\n  lexicalScorer?: string;\n}\n\n/**\n * A RediSearch-backed {@link VectorStore} — HNSW + cosine over Redis, the ecosystem-native option\n * for anyone already running Redis (see `-transport-redis`). Chunks are hashes under `prefix`, the\n * embedding a FLOAT32 vector field; `search` is a KNN query. Call {@link RedisVectorStore.ensureSchema}\n * once at boot to create the index.\n *\n * The chunk text is declared as a RediSearch `TEXT` field, so this store also satisfies\n * {@link LexicalVectorStore}: {@link RedisVectorStore.searchText} is BM25 over that same index —\n * the lexical half of hybrid search with no second index to build, feed, or invalidate.\n */\nexport class RedisVectorStore implements LexicalVectorStore {\n  private readonly index: string;\n  private readonly prefix: string;\n  private readonly dimensions: number;\n  private readonly filterableFields: string[];\n  private readonly lexicalScorer: string;\n\n  constructor(\n    private readonly client: RedisSearchClient,\n    options: RedisVectorStoreOptions = {},\n  ) {\n    this.index = options.index ?? 'agent_rag_idx';\n    this.prefix = options.prefix ?? 'agent_rag:';\n    this.dimensions = options.dimensions ?? 1536;\n    this.filterableFields = options.filterableFields ?? [];\n    this.lexicalScorer = options.lexicalScorer ?? 'BM25';\n  }\n\n  /**\n   * Telemetry self-description — the RediSearch INDEX, not the key prefix: the index is what both\n   * legs query, and two stores sharing one index (the dense and lexical halves of a hybrid) must\n   * report the same namespace or `describeSharedSource` would see them disagree and drop the store.\n   */\n  describeRetrieval(): RetrievalDescriptor {\n    return { store: 'redis', collection: this.index };\n  }\n\n  /**\n   * Idempotent, and drift-aware: create the HNSW/cosine index if `FT.INFO` says it doesn't exist —\n   * and if it DOES exist, compare what's there against this store's configuration instead of\n   * assuming they agree. An index that outlives a config change is the normal case (schemas live in\n   * Redis, config lives in a redeployed process), and the two failure modes it produces are both\n   * invisible at runtime: a `filterableFields` entry added later has no `meta_*` TAG, so every search\n   * filtering on it matches *nothing*; a changed `dimensions` leaves the index on the old width, so\n   * writes are rejected or KNN ranks garbage. Neither raises anything on its own.\n   *\n   * The two are repaired differently, because only one of them CAN be repaired:\n   *\n   * - **A missing filterable TAG is additive** → `FT.ALTER … SCHEMA ADD`. Nothing that already works\n   *   changes, so doing it automatically is safe. Note the chunks written *before* the alter carry no\n   *   `meta_*` hash field at all (`upsert` only writes the fields configured at the time), so they\n   *   only become filterable on that key once they're re-ingested — the schema is repaired here, the\n   *   backfill is the host's call.\n   * - **A dimension (or field-type) change is not repairable** → {@link RedisVectorSchemaMismatchError}.\n   *   It needs a drop + full reindex, which would destroy the host's corpus; failing loudly at boot is\n   *   the only honest option.\n   *\n   * If `FT.INFO` comes back in a shape this parser doesn't recognise, no drift is inferred — an\n   * unreadable reply must not be turned into a false alarm that blocks a boot.\n   */\n  async ensureSchema(): Promise<void> {\n    let info: unknown;\n    try {\n      info = await this.client.sendCommand(['FT.INFO', this.index]);\n    } catch {\n      await this.createIndex();\n      return;\n    }\n    await this.reconcileSchema(info);\n  }\n\n  /** Repair what can be repaired in place; throw on what can't. */\n  private async reconcileSchema(info: unknown): Promise<void> {\n    const attributes = parseIndexAttributes(info);\n    if (attributes.size === 0) {\n      return;\n    }\n\n    const vector = attributes.get('embedding');\n    if (vector?.dimensions !== undefined && vector.dimensions !== this.dimensions) {\n      throw new RedisVectorSchemaMismatchError(\n        this.index,\n        'embedding',\n        `DIM ${this.dimensions}`,\n        `DIM ${vector.dimensions}`,\n        `A vector field's width is fixed at FT.CREATE and every stored embedding has the old one, so this cannot be altered in place: drop the index (FT.DROPINDEX ${this.index} DD) and re-ingest with the new embedding model.`,\n      );\n    }\n\n    const missing: string[] = [];\n    for (const field of this.filterableFields) {\n      const name = `meta_${field}`;\n      const existing = attributes.get(name);\n      if (existing === undefined) {\n        missing.push(name);\n      } else if (existing.type !== 'TAG') {\n        throw new RedisVectorSchemaMismatchError(\n          this.index,\n          name,\n          'TAG',\n          existing.type,\n          `A field's type cannot be changed in place: drop the index (FT.DROPINDEX ${this.index} DD) and re-ingest, or rename the metadata key.`,\n        );\n      }\n    }\n    for (const name of missing) {\n      await this.client.sendCommand(['FT.ALTER', this.index, 'SCHEMA', 'ADD', name, 'TAG']);\n    }\n  }\n\n  private async createIndex(): Promise<void> {\n    const schema: string[] = ['text', 'TEXT', 'source', 'TAG', 'metadata_json', 'TEXT', 'NOINDEX'];\n    for (const field of this.filterableFields) {\n      schema.push(`meta_${field}`, 'TAG');\n    }\n    schema.push(\n      'embedding',\n      'VECTOR',\n      'HNSW',\n      '6',\n      'TYPE',\n      'FLOAT32',\n      'DIM',\n      String(this.dimensions),\n      'DISTANCE_METRIC',\n      'COSINE',\n    );\n    await this.client.sendCommand([\n      'FT.CREATE',\n      this.index,\n      'ON',\n      'HASH',\n      'PREFIX',\n      '1',\n      this.prefix,\n      'SCHEMA',\n      ...schema,\n    ]);\n  }\n\n  async upsert(records: VectorRecord[]): Promise<void> {\n    for (const record of records) {\n      const args: (string | Buffer)[] = [\n        'HSET',\n        `${this.prefix}${record.id}`,\n        'text',\n        record.text,\n        'embedding',\n        encodeVector(record.embedding),\n      ];\n      if (record.source !== undefined) {\n        args.push('source', record.source);\n      }\n      if (record.metadata !== undefined) {\n        args.push('metadata_json', JSON.stringify(record.metadata));\n        for (const field of this.filterableFields) {\n          const value = record.metadata[field];\n          if (value !== undefined) {\n            args.push(`meta_${field}`, encodeTag(value));\n          }\n        }\n      }\n      await this.client.sendCommand(args);\n    }\n  }\n\n  /**\n   * Single-document deletion, by `SCAN … MATCH`.\n   *\n   * This deliberately stays a keyspace scan even though the rest of this class no longer needs one.\n   * The obvious optimisation is to stamp each chunk with its document id as an implicit filterable\n   * TAG at {@link RedisVectorStore.upsert} and turn `remove` into an `FT.SEARCH` — and that is exactly\n   * the change that must not ship, because chunks written *before* it carry no such field. `FT.SEARCH`\n   * would find zero of them, `remove` would return happily, and a document that has been \"deleted\"\n   * would go on being retrieved. A delete that silently stops deleting is worse than a slow one, and\n   * the library cannot tell a fully-migrated corpus from an unmigrated one: both look like \"this\n   * document has no indexed chunks\". Nor is a search-then-fall-back-to-scan hybrid safe — a document\n   * re-ingested after the upgrade has *some* stamped chunks, so the search finds hits, the fallback\n   * never runs, and the unstamped tail survives. That is the same silent failure with a smaller blast\n   * radius, which makes it harder to notice rather than less wrong.\n   *\n   * The consumer pain this was measured against — deleting a whole collection, one `remove` per\n   * document — is answered instead by {@link RedisVectorStore.removeWhere} (one filtered query, no\n   * keyspace scan at all) and {@link RedisVectorStore.removeMany} (one scan for N documents rather\n   * than N scans). Neither depends on a field that older chunks lack, so neither has a migration.\n   */\n  async remove(documentId: string): Promise<void> {\n    const keys = await this.chunkKeys(documentId);\n    if (keys.length > 0) {\n      await this.client.sendCommand(['DEL', ...keys]);\n    }\n  }\n\n  /**\n   * Rewrite the metadata of every chunk of `documentId` in place, leaving `text` and `embedding`\n   * alone. See {@link VectorStore.updateMetadata} for the merge semantics and the return value.\n   *\n   * The care this needs is entirely about the fact that a chunk stores its metadata **twice**: as the\n   * `metadata_json` blob (what {@link RedisVectorStore.search} reads back onto a `Passage`) and as\n   * `meta_<field>` TAG fields (what RediSearch actually filters on, and only for the declared\n   * `filterableFields`). Move one without the other and the store lies to itself — a chunk that\n   * filters as the old value but reports the new one, or the reverse — so this method rewrites both\n   * from the same merged object:\n   *\n   * - a patched key that is **not** filterable lands in `metadata_json` only, and no stray `meta_*`\n   *   field is invented for it (it would be dead weight the index does not know about);\n   * - a patched key that **is** filterable also rewrites its TAG, using the identical encoding\n   *   `upsert` uses, so an updated chunk is indistinguishable from a re-ingested one;\n   * - a filterable key the patch **removes** has its TAG `HDEL`-ed, not left behind as a tag matching\n   *   a value the document no longer carries.\n   *\n   * A plain `HSET` is all the index needs: RediSearch re-indexes a hash the moment it is written, so\n   * the very next `FT.SEARCH` sees the new TAG and no longer the old one — no reindex command, and\n   * no need to rewrite the (untouched, and expensive) vector to nudge it. `HDEL` on an indexed field\n   * likewise drops it from the index. Verified against a real Redis Stack in\n   * `redis-vector-store.db.spec.ts`, not assumed.\n   *\n   * Removals are issued **before** the write, so the only window a concurrent reader can observe is\n   * \"TAG already gone, `metadata_json` not yet updated\" — which fails *closed* on a filter carrying\n   * an ACL. The reverse order would briefly leave a document tagged with a capability its metadata no\n   * longer claims. Read-modify-write across chunks is not transactional; concurrent writers to the\n   * same chunk are last-writer-wins, exactly as two concurrent `upsert`s already are.\n   */\n  async updateMetadata(documentId: string, patch: MetadataPatch): Promise<number> {\n    if (isEmptyMetadataPatch(patch)) {\n      return 0;\n    }\n    const keys = await this.chunkKeys(documentId);\n    let updated = 0;\n    for (const key of keys) {\n      const raw = await this.client.sendCommand(['HGET', key, 'metadata_json']);\n      const current = parseMetadata(raw === null || raw === undefined ? undefined : toStr(raw));\n      const next = applyMetadataPatch(current.metadata, patch);\n\n      const args: (string | Buffer)[] = ['HSET', key, 'metadata_json', JSON.stringify(next)];\n      const stale: string[] = [];\n      for (const field of this.filterableFields) {\n        const value = next[field];\n        if (value !== undefined) {\n          args.push(`meta_${field}`, encodeTag(value));\n        } else if (current.metadata?.[field] !== undefined) {\n          stale.push(`meta_${field}`);\n        }\n      }\n      if (stale.length > 0) {\n        await this.client.sendCommand(['HDEL', key, ...stale]);\n      }\n      await this.client.sendCommand(args);\n      updated += 1;\n    }\n    return updated;\n  }\n\n  /**\n   * Every chunk key that currently EXISTS for `documentId` — the bare `${prefix}${documentId}` plus\n   * the `${documentId}#<n>` chunks found by `SCAN`. One definition of \"chunk belongs to document\",\n   * shared by `remove` and `updateMetadata`, so the two can never disagree about which keys a\n   * document owns. The glob is escaped so `gone` does not reach into `goner#0`.\n   */\n  private async chunkKeys(documentId: string): Promise<string[]> {\n    const keys = new Set<string>();\n    const bare = `${this.prefix}${documentId}`;\n    const exists = await this.client.sendCommand(['EXISTS', bare]);\n    if (Number(toStr(exists)) > 0) {\n      keys.add(bare);\n    }\n    const pattern = `${this.prefix}${escapeGlob(documentId)}#*`;\n    let cursor = '0';\n    do {\n      const reply = await this.client.sendCommand([\n        'SCAN',\n        cursor,\n        'MATCH',\n        pattern,\n        'COUNT',\n        '256',\n      ]);\n      const page = parseScanReply(reply);\n      cursor = page.cursor;\n      for (const key of page.keys) {\n        keys.add(key);\n      }\n    } while (cursor !== '0');\n    return [...keys];\n  }\n\n  /**\n   * The chunks of one document, in document order. See {@link VectorStore.listChunks}.\n   *\n   * Reads the hashes directly (`HMGET text metadata_json`) rather than going through `FT.SEARCH`.\n   * Two reasons, and the second is the one that matters: the query language has no way to ask for\n   * \"every chunk of this document\" — `id` is the key name, not an indexed field — and `FT.SEARCH`\n   * caps at `LIMIT`, so paging a document through it would mean ordering by a field the index does\n   * not hold. `chunkKeys` is the same enumeration {@link RedisVectorStore.remove} and\n   * {@link RedisVectorStore.updateMetadata} already use, so \"the chunks this returns\" and \"the chunks\n   * a delete would take\" cannot drift apart.\n   *\n   * It inherits that method's cost too: one keyspace `SCAN` per call. Acceptable here because this\n   * is an inspection path (one document, on demand) and not something retrieval runs — but it is why\n   * this must not be put on a hot path or called in a loop over a corpus.\n   *\n   * `embedding` is deliberately not fetched: it is by far the largest field on the hash and nothing\n   * a caller reading text back can do with it.\n   */\n  async listChunks(documentId: string, options?: ListChunksOptions): Promise<StoredChunk[]> {\n    const keys = await this.chunkKeys(documentId);\n    const ordered = keys\n      .map((key) => ({ key, id: key.slice(this.prefix.length) }))\n      .map((entry) => ({ ...entry, index: chunkIndexOf(entry.id) }))\n      .sort((a, b) => a.index - b.index);\n\n    const offset = options?.offset ?? 0;\n    const page =\n      options?.limit === undefined\n        ? ordered.slice(offset)\n        : ordered.slice(offset, offset + options.limit);\n\n    const chunks: StoredChunk[] = [];\n    for (const entry of page) {\n      const reply = await this.client.sendCommand(['HMGET', entry.key, 'text', 'metadata_json']);\n      const fields = Array.isArray(reply) ? reply : [];\n      const text = fields[0] === null || fields[0] === undefined ? undefined : toStr(fields[0]);\n      if (text === undefined) {\n        // The key was deleted between the SCAN and this read. Skip it rather than reporting a chunk\n        // with empty text, which would read as \"the chunker produced nothing here\".\n        continue;\n      }\n      const raw = fields[1] === null || fields[1] === undefined ? undefined : toStr(fields[1]);\n      chunks.push({\n        id: entry.id,\n        index: entry.index,\n        text,\n        ...parseMetadata(raw),\n      });\n    }\n    return chunks;\n  }\n\n  async listDocuments(filter?: Record<string, unknown>): Promise<IndexedDocument[]> {\n    if (filterMatchesNothing(filter)) {\n      return [];\n    }\n    const query = buildFilter(filter);\n    const documents = new Map<string, IndexedDocument>();\n    const batchSize = 1000;\n    let offset = 0;\n    for (;;) {\n      // RETURN metadata_json (not NOCONTENT) so we can carry a representative chunk's metadata;\n      // parseSearchReply already yields prefix-stripped ids + parsed metadata for both RESP2/RESP3.\n      const reply = await this.client.sendCommand([\n        'FT.SEARCH',\n        this.index,\n        query,\n        'RETURN',\n        '1',\n        'metadata_json',\n        'LIMIT',\n        String(offset),\n        String(batchSize),\n        'DIALECT',\n        '2',\n      ]);\n      const passages = parseSearchReply(reply, this.prefix);\n      for (const passage of passages) {\n        const id = documentIdOf(passage.id);\n        if (!documents.has(id)) {\n          documents.set(id, {\n            id,\n            ...(passage.metadata !== undefined ? { metadata: passage.metadata } : {}),\n          });\n        }\n      }\n      if (passages.length < batchSize) {\n        break;\n      }\n      offset += batchSize;\n    }\n    return [...documents.values()];\n  }\n\n  /**\n   * The id-only half of {@link RedisVectorStore.listDocuments}, served by `FT.SEARCH … NOCONTENT`:\n   * RediSearch returns bare keys, so nothing carries `metadata_json` over the wire and nothing is\n   * JSON-parsed. `listDocuments` has to parse one metadata blob per *chunk* — thousands of parses to\n   * produce a few hundred ids it then throws the metadata away from — and this does none of it.\n   *\n   * The collapse to document ids still happens client-side. RediSearch can group server-side\n   * (`FT.AGGREGATE … GROUPBY`), but only over an indexed *field*, and a chunk's document id lives in\n   * its key, not in a field — deriving it would mean stamping one at write time, which is the\n   * migration {@link RedisVectorStore.remove} explains this class refuses. Deduplicating a page of\n   * keys in JS is free by comparison.\n   */\n  async listDocumentIds(filter?: Record<string, unknown>): Promise<string[]> {\n    if (filterMatchesNothing(filter)) {\n      return [];\n    }\n    const query = buildFilter(filter);\n    const documents = new Set<string>();\n    let offset = 0;\n    for (;;) {\n      const reply = await this.client.sendCommand([\n        'FT.SEARCH',\n        this.index,\n        query,\n        'NOCONTENT',\n        'LIMIT',\n        String(offset),\n        String(SCAN_PAGE),\n        'DIALECT',\n        '2',\n      ]);\n      const keys = parseSearchKeys(reply);\n      for (const key of keys) {\n        documents.add(documentIdOf(stripPrefix(key, this.prefix)));\n      }\n      if (keys.length < SCAN_PAGE) {\n        break;\n      }\n      offset += SCAN_PAGE;\n    }\n    return [...documents];\n  }\n\n  /**\n   * Bulk deletion by document id — **one** keyspace scan for N documents, where N calls to\n   * {@link RedisVectorStore.remove} would be N of them. The scan is `MATCH ${prefix}*`, so Redis still\n   * filters to this store's own keys server-side; membership is then decided in JS against a `Set`,\n   * which is what lets a single pass serve any number of ids.\n   *\n   * It deletes by key, exactly as `remove` does, so it is correct on chunks written by any version of\n   * this library — there is no field it needs the corpus to already carry.\n   */\n  async removeMany(documentIds: string[]): Promise<void> {\n    if (documentIds.length === 0) {\n      return;\n    }\n    const wanted = new Set(documentIds);\n    // A document may have been stored under its bare id (no `#n` suffix); those keys are exact and\n    // need no scan to find, so seed them and let the scan add the chunked ones.\n    let pending = documentIds.map((id) => `${this.prefix}${id}`);\n    let cursor = '0';\n    do {\n      const reply = await this.client.sendCommand([\n        'SCAN',\n        cursor,\n        'MATCH',\n        `${escapeGlob(this.prefix)}*`,\n        'COUNT',\n        String(SCAN_PAGE),\n      ]);\n      const page = parseScanReply(reply);\n      cursor = page.cursor;\n      for (const key of page.keys) {\n        if (wanted.has(documentIdOf(stripPrefix(key, this.prefix)))) {\n          pending.push(key);\n        }\n      }\n      if (pending.length >= DELETE_BATCH) {\n        await this.client.sendCommand(['DEL', ...pending]);\n        pending = [];\n      }\n    } while (cursor !== '0');\n    if (pending.length > 0) {\n      await this.client.sendCommand(['DEL', ...pending]);\n    }\n  }\n\n  /**\n   * Delete every chunk matching `filter`, via `FT.SEARCH … NOCONTENT` + `DEL` — no keyspace scan at\n   * all, so dropping a collection costs one indexed query per page instead of one full pass per\n   * document. Resolves the number of chunk keys actually deleted.\n   *\n   * The two refusals, in this order, before any query is issued:\n   *\n   * 1. **An empty filter object throws** {@link UnsafeRemovalError}. `buildFilter({})` is `*`, and `*`\n   *    here would mean \"delete the corpus\" — far too destructive an outcome for the shape a filter\n   *    degenerates to when it is built wrong.\n   * 2. **An empty-array value deletes nothing** and resolves `0`. This is the package's deny primitive\n   *    (an actor with no capability tokens), and it is the one that has to be gated *explicitly*: a\n   *    plausible-looking \"normalise the filter first\" refactor that drops empty arrays turns a deny\n   *    into `*` and wipes everything the deny existed to protect.\n   *\n   * Then one more, which is specific to RediSearch: every filter key must be a declared\n   * `filterableFields` entry. `search` lets the engine reject an unknown field, which is fine for a\n   * read; for a delete the check is worth making up front and by name.\n   *\n   * Deletion happens page by page, always re-querying from offset 0 — the rows just deleted are gone\n   * from the index, so paging forward would skip their replacements. If a page comes back non-empty\n   * but `DEL` reports nothing removed (keys expired between query and delete, or the index is stale),\n   * the loop stops rather than spinning on results it can never consume.\n   */\n  async removeWhere(filter: Record<string, unknown>): Promise<number> {\n    const keys = Object.keys(filter);\n    if (keys.length === 0) {\n      throw new UnsafeRemovalError(\n        'empty-filter',\n        'removeWhere() refuses an empty filter: it would delete every chunk in the index. ' +\n          'Pass a filter that scopes the removal, or delete deliberately with ' +\n          'removeMany(await store.listDocumentIds()).',\n      );\n    }\n    const unindexed = keys.filter((key) => !this.filterableFields.includes(key));\n    if (unindexed.length > 0) {\n      const named = unindexed.map((key) => `\"${key}\"`).join(', ');\n      const declared = this.filterableFields.join(', ') || 'none';\n      throw new UnsafeRemovalError(\n        'unindexed-field',\n        `removeWhere() cannot scope on ${named}: not declared in this store's filterableFields (${declared}), so RediSearch has no TAG to match on.`,\n      );\n    }\n    // THE guard. Removing it turns the deny primitive into an unfiltered delete — see the db spec's\n    // \"an empty-array filter deletes NOTHING\" case, which exists to fail loudly if this ever goes.\n    if (filterMatchesNothing(filter)) {\n      return 0;\n    }\n\n    const query = buildFilter(filter);\n    let removed = 0;\n    for (;;) {\n      const reply = await this.client.sendCommand([\n        'FT.SEARCH',\n        this.index,\n        query,\n        'NOCONTENT',\n        'LIMIT',\n        '0',\n        String(DELETE_BATCH),\n        'DIALECT',\n        '2',\n      ]);\n      const page = parseSearchKeys(reply);\n      if (page.length === 0) {\n        break;\n      }\n      const deleted = Number(await this.client.sendCommand(['DEL', ...page]));\n      if (!Number.isFinite(deleted) || deleted === 0) {\n        break;\n      }\n      removed += deleted;\n    }\n    return removed;\n  }\n\n  /**\n   * Count matching chunks with `FT.SEARCH … LIMIT 0 0` — RediSearch returns the total and no\n   * documents, so the cost is the query, not the corpus. An empty-array filter value denies and\n   * yields `0`, same as every other filtered path here.\n   */\n  async countChunks(filter?: Record<string, unknown>): Promise<number> {\n    if (filterMatchesNothing(filter)) {\n      return 0;\n    }\n    const reply = await this.client.sendCommand([\n      'FT.SEARCH',\n      this.index,\n      buildFilter(filter),\n      'NOCONTENT',\n      'LIMIT',\n      '0',\n      '0',\n      'DIALECT',\n      '2',\n    ]);\n    return parseSearchTotal(reply);\n  }\n\n  async search(embedding: number[], options: VectorSearchOptions): Promise<Passage[]> {\n    if (filterMatchesNothing(options.filter)) {\n      return [];\n    }\n    const query = `${buildFilter(options.filter)}=>[KNN ${options.topK} @embedding $BLOB AS vector_score]`;\n    const reply = await this.client.sendCommand([\n      'FT.SEARCH',\n      this.index,\n      query,\n      'PARAMS',\n      '2',\n      'BLOB',\n      encodeVector(embedding),\n      'RETURN',\n      '4',\n      'text',\n      'source',\n      'metadata_json',\n      'vector_score',\n      'SORTBY',\n      'vector_score',\n      'ASC',\n      'DIALECT',\n      '2',\n      'LIMIT',\n      '0',\n      String(options.topK),\n    ]);\n    return parseSearchReply(reply, this.prefix);\n  }\n\n  /**\n   * Lexical (BM25) search over the same index `search` uses — the {@link LexicalVectorStore} half of\n   * hybrid retrieval, served by RediSearch's own keyword index rather than an in-process copy of the\n   * corpus. `options.filter` is ANDed onto the text clause with the identical TAG semantics as\n   * `search` (array = OR, empty array = deny), so a lexical hit can never escape a filter a vector\n   * hit would have respected.\n   *\n   * A query with no searchable terms — empty, whitespace, or pure punctuation — returns `[]`. That is\n   * deliberate: RediSearch's `*` would match the entire corpus, which is the opposite of what a\n   * relevance query with nothing to be relevant to should do.\n   */\n  async searchText(query: string, options: VectorSearchOptions): Promise<Passage[]> {\n    if (filterMatchesNothing(options.filter)) {\n      return [];\n    }\n    const terms = tokenizeQuery(query);\n    if (terms.length === 0) {\n      return [];\n    }\n    const filterQuery = buildFilter(options.filter);\n    const textQuery = `@text:(${terms.join('|')})`;\n    const reply = await this.client.sendCommand([\n      'FT.SEARCH',\n      this.index,\n      filterQuery === '*' ? textQuery : `(${filterQuery} ${textQuery})`,\n      'SCORER',\n      this.lexicalScorer,\n      'WITHSCORES',\n      'RETURN',\n      '3',\n      'text',\n      'source',\n      'metadata_json',\n      'DIALECT',\n      '2',\n      'LIMIT',\n      '0',\n      String(options.topK),\n    ]);\n    return parseSearchReply(reply, this.prefix, 'lexical');\n  }\n}\n\n/** Page size for `SCAN COUNT` and for the id-only `FT.SEARCH` pages. */\nconst SCAN_PAGE = 1000;\n\n/** How many keys to hand a single `DEL`, and therefore how big a `removeWhere` page is. */\nconst DELETE_BATCH = 512;\n\n/** Recover a chunk id from its Redis key. */\nfunction stripPrefix(key: string, prefix: string): string {\n  return key.startsWith(prefix) ? key.slice(prefix.length) : key;\n}\n\n/**\n * Parse the keys out of an `FT.SEARCH … NOCONTENT` reply, tolerating both wire shapes: the RESP2 array\n * `[total, key, key, …]` and the RESP3 object `{ total_results, results: [{ id }] }`. Keys come back\n * whole (prefix included) — callers strip it.\n */\nfunction parseSearchKeys(reply: unknown): string[] {\n  if (Array.isArray(reply)) {\n    return reply.slice(1).map(toStr);\n  }\n  if (typeof reply === 'object' && reply !== null && 'results' in reply) {\n    const results = (reply as { results: unknown }).results;\n    return Array.isArray(results) ? results.map(readId) : [];\n  }\n  return [];\n}\n\n/**\n * Parse the match count out of an `FT.SEARCH … LIMIT 0 0` reply — element 0 in RESP2, `total_results`\n * in the RESP3 object. An unrecognised shape counts as 0 rather than `NaN`, so a caller comparing\n * against a threshold can't be handed something that fails every comparison silently.\n */\nfunction parseSearchTotal(reply: unknown): number {\n  if (Array.isArray(reply)) {\n    const total = Number(toStr(reply[0]));\n    return Number.isFinite(total) ? total : 0;\n  }\n  if (typeof reply === 'object' && reply !== null && 'total_results' in reply) {\n    const total = Number((reply as { total_results: unknown }).total_results);\n    return Number.isFinite(total) ? total : 0;\n  }\n  return 0;\n}\n\n/** One attribute as the live index reports it — enough to spot the drift that matters. */\ninterface IndexAttribute {\n  /** `TEXT` / `TAG` / `VECTOR`. */\n  type: string;\n  /** `VECTOR` fields only: the width the index was created with. */\n  dimensions?: number;\n}\n\n/**\n * Parse `FT.INFO`'s `attributes` into `attribute name → { type, dimensions }`, tolerating both wire\n * shapes exactly like {@link parseSearchReply} does: the RESP2 flat key/value array (whose attributes\n * are themselves flat key/value arrays) and node-redis's RESP3 object (attributes as objects).\n * Unknown shapes yield an empty map, which callers read as \"can't tell\" rather than \"nothing there\".\n */\nfunction parseIndexAttributes(reply: unknown): Map<string, IndexAttribute> {\n  const attributes = new Map<string, IndexAttribute>();\n  for (const entry of readInfoField(reply, 'attributes')) {\n    const fields = readKeyValues(entry);\n    const name = fields.attribute ?? fields.identifier;\n    if (name === undefined) {\n      continue;\n    }\n    const dim = Number(fields.dim);\n    attributes.set(name, {\n      type: (fields.type ?? '').toUpperCase(),\n      ...(fields.dim !== undefined && Number.isFinite(dim) ? { dimensions: dim } : {}),\n    });\n  }\n  return attributes;\n}\n\n/** Read one top-level `FT.INFO` field as an array, from either the RESP2 pair-array or RESP3 object. */\nfunction readInfoField(reply: unknown, key: string): unknown[] {\n  if (Array.isArray(reply)) {\n    for (let index = 0; index + 1 < reply.length; index += 2) {\n      if (toStr(reply[index]) === key) {\n        const value = reply[index + 1];\n        return Array.isArray(value) ? value : [];\n      }\n    }\n    return [];\n  }\n  if (typeof reply === 'object' && reply !== null && key in reply) {\n    const value = (reply as Record<string, unknown>)[key];\n    return Array.isArray(value) ? value : [];\n  }\n  return [];\n}\n\n/** Flatten one attribute entry (RESP2 pair-array or RESP3 object) into lower-cased string fields. */\nfunction readKeyValues(entry: unknown): Record<string, string | undefined> {\n  const fields: Record<string, string | undefined> = {};\n  if (Array.isArray(entry)) {\n    for (let index = 0; index + 1 < entry.length; index += 2) {\n      fields[toStr(entry[index]).toLowerCase()] = toStr(entry[index + 1]);\n    }\n    return fields;\n  }\n  if (typeof entry === 'object' && entry !== null) {\n    for (const [key, value] of Object.entries(entry)) {\n      fields[key.toLowerCase()] = toStr(value);\n    }\n  }\n  return fields;\n}\n\n/** RediSearch expects a little-endian FLOAT32 buffer for the query/stored vector. */\nfunction encodeVector(embedding: number[]): Buffer {\n  return Buffer.from(new Float32Array(embedding).buffer);\n}\n\n/**\n * `*` for no filter, else an AND of TAG clauses. A scalar value is an exact tag match\n * (`@meta_owner:{u1}`); an **array** value is a TAG alternation — match-any / OR\n * (`@meta_audience:{public|role\\:ADMIN}`), the capability-ACL primitive. RediSearch TAG fields are\n * multi-valued per document, so this also matches documents carrying several of the tags.\n */\nfunction buildFilter(filter?: Record<string, unknown>): string {\n  if (filter === undefined || Object.keys(filter).length === 0) {\n    return '*';\n  }\n  const clauses = Object.entries(filter).map(([key, value]) => {\n    const values = Array.isArray(value) ? value : [value];\n    const alternation = values.map((entry) => escapeTag(String(entry))).join('|');\n    return `@meta_${key}:{${alternation}}`;\n  });\n  return `(${clauses.join(' ')})`;\n}\n\n/**\n * Reduce a raw user query to RediSearch query *terms*, the union of which becomes the text clause.\n *\n * This is the escaping story for the text leg, and it escapes by **construction** rather than by\n * quoting: a term is kept only as a run of letters, digits and `_`, so nothing that could carry\n * meaning in RediSearch's query language — `@ { } | ( ) * ~ - \" ' : ; , => %` and friends — can\n * survive into the emitted query. A query cannot therefore add a clause, negate one, open a field\n * selector, or widen the filter it is ANDed with. (Escaping each punctuation character instead, as\n * {@link escapeTag} does for TAG values, would be safe but *lossy*: RediSearch's own tokenizer split\n * the indexed text on that same punctuation, so an escaped `hello\\-world` term matches nothing.)\n *\n * Unicode letters and digits are kept — stripping to ASCII would silently make non-English corpora\n * unsearchable. Since `\\p{L}`/`\\p{N}` contain no RediSearch metacharacters, keeping them is safe.\n */\nfunction tokenizeQuery(query: string): string[] {\n  return query.match(/[\\p{L}\\p{N}_]+/gu) ?? [];\n}\n\n/**\n * Encode one metadata value as the `meta_<field>` hash field RediSearch indexes as a TAG. An **array**\n * becomes a multi-valued TAG (comma-separated, RediSearch's default separator) so a document can\n * carry several capability tokens — which is also why individual values must not contain commas.\n *\n * Shared by `upsert` and `updateMetadata` on purpose: they write the same field, and the day the two\n * encode it differently is the day a patched chunk stops matching a filter a freshly-ingested one\n * matches, for a value that looks identical in `metadata_json`.\n */\nfunction encodeTag(value: unknown): string {\n  return Array.isArray(value) ? value.map(String).join(',') : String(value);\n}\n\n/** Escape RediSearch TAG punctuation so an id/tenant value matches literally. */\nfunction escapeTag(value: string): string {\n  return value.replace(/[^a-zA-Z0-9_]/g, (char) => `\\\\${char}`);\n}\n\n/** Escape `SCAN MATCH` glob metacharacters so a document id matches its chunk keys literally. */\nfunction escapeGlob(value: string): string {\n  return value.replace(/[*?[\\]\\\\]/g, (char) => `\\\\${char}`);\n}\n\n/**\n * Parse a `SCAN` reply into `{ cursor, keys }`, tolerating both wire shapes: the RESP2 array\n * `[cursor, [key, …]]` and node-redis's RESP3 object `{ cursor, keys }`.\n */\nfunction parseScanReply(reply: unknown): { cursor: string; keys: string[] } {\n  if (Array.isArray(reply) && reply.length >= 2) {\n    const rawKeys = reply[1];\n    return {\n      cursor: toStr(reply[0]),\n      keys: Array.isArray(rawKeys) ? rawKeys.map(toStr) : [],\n    };\n  }\n  if (typeof reply === 'object' && reply !== null && 'cursor' in reply && 'keys' in reply) {\n    const { cursor, keys } = reply as { cursor: unknown; keys: unknown };\n    return {\n      cursor: toStr(cursor),\n      keys: Array.isArray(keys) ? keys.map(toStr) : [],\n    };\n  }\n  return { cursor: '0', keys: [] };\n}\n\nfunction toStr(value: unknown): string {\n  if (typeof value === 'string') {\n    return value;\n  }\n  return Buffer.isBuffer(value) ? value.toString('utf8') : String(value);\n}\n\n/**\n * Which leg produced the reply, and therefore where a passage's `score` comes from:\n *\n * - `vector` — the KNN query. Score is the returned `vector_score` **distance**, turned into a\n *   cosine similarity by `1 - distance`. Two array elements per result (`key`, `fields`).\n * - `lexical` — the `WITHSCORES` text query. The engine's BM25 relevance is already a\n *   bigger-is-better score, and it arrives *inline*: three array elements per result\n *   (`key`, `score`, `fields`), which is why the stride is not a constant.\n */\ntype ScoreSource = 'vector' | 'lexical';\n\n/**\n * Parse an `FT.SEARCH` reply into passages, tolerating both wire shapes: the RESP2 array\n * `[total, key, [f, v, …], …]` (ioredis / node-redis RESP2) and the RESP3 object\n * `{ results: [{ id, extra_attributes: { … } }] }` (node-redis's default). The `prefix` is stripped\n * back off the key to recover the chunk id; `scoreSource` selects the scoring convention.\n */\nfunction parseSearchReply(\n  reply: unknown,\n  prefix: string,\n  scoreSource: ScoreSource = 'vector',\n): Passage[] {\n  const stride = scoreSource === 'lexical' ? 3 : 2;\n  if (Array.isArray(reply)) {\n    const passages: Passage[] = [];\n    for (let index = 1; index + stride - 1 < reply.length; index += stride) {\n      const rawFields = reply[index + stride - 1];\n      if (Array.isArray(rawFields)) {\n        const attrs: Record<string, string> = {};\n        for (let field = 0; field + 1 < rawFields.length; field += 2) {\n          attrs[toStr(rawFields[field])] = toStr(rawFields[field + 1]);\n        }\n        const inlineScore = scoreSource === 'lexical' ? toStr(reply[index + 1]) : undefined;\n        passages.push(toPassage(toStr(reply[index]), attrs, prefix, scoreSource, inlineScore));\n      }\n    }\n    return passages;\n  }\n  if (typeof reply === 'object' && reply !== null && 'results' in reply) {\n    const results = (reply as { results: unknown }).results;\n    if (Array.isArray(results)) {\n      return results.map((result) =>\n        toPassage(\n          readId(result),\n          readAttributes(result),\n          prefix,\n          scoreSource,\n          scoreSource === 'lexical' ? readScore(result) : undefined,\n        ),\n      );\n    }\n  }\n  return [];\n}\n\n/** RESP3 `WITHSCORES` puts the relevance score on the result object rather than inline in the array. */\nfunction readScore(result: unknown): string | undefined {\n  if (typeof result === 'object' && result !== null && 'score' in result) {\n    return toStr((result as { score: unknown }).score);\n  }\n  return undefined;\n}\n\nfunction readId(result: unknown): string {\n  if (typeof result === 'object' && result !== null && 'id' in result) {\n    return toStr((result as { id: unknown }).id);\n  }\n  return '';\n}\n\nfunction readAttributes(result: unknown): Record<string, string> {\n  const attrs: Record<string, string> = {};\n  if (typeof result === 'object' && result !== null && 'extra_attributes' in result) {\n    const raw = (result as { extra_attributes: unknown }).extra_attributes;\n    if (typeof raw === 'object' && raw !== null) {\n      for (const [key, value] of Object.entries(raw)) {\n        attrs[key] = toStr(value);\n      }\n    }\n  }\n  return attrs;\n}\n\nfunction toPassage(\n  rawId: string,\n  attrs: Record<string, string>,\n  prefix: string,\n  scoreSource: ScoreSource = 'vector',\n  inlineScore?: string,\n): Passage {\n  const score =\n    scoreSource === 'lexical' ? Number(inlineScore ?? '0') : 1 - Number(attrs.vector_score ?? '1');\n  const source = attrs.source;\n  return {\n    id: rawId.startsWith(prefix) ? rawId.slice(prefix.length) : rawId,\n    text: attrs.text ?? '',\n    score: Number.isFinite(score) ? score : 0,\n    ...(source !== undefined ? { source } : {}),\n    ...parseMetadata(attrs.metadata_json),\n  };\n}\n\nfunction parseMetadata(raw: string | undefined): { metadata?: Record<string, unknown> } {\n  if (raw === undefined) {\n    return {};\n  }\n  try {\n    const parsed: unknown = JSON.parse(raw);\n    if (typeof parsed === 'object' && parsed !== null) {\n      return { metadata: parsed as Record<string, unknown> };\n    }\n  } catch {\n    // not JSON — no metadata\n  }\n  return {};\n}\n","/**\n * What a retrieval was served BY — the static half of retrieval telemetry, separated from the\n * emitting half (`retrieval-telemetry.ts`) so a store or a retriever can describe itself without\n * importing anything that emits. That separation is not tidiness: `retrieval-telemetry.ts` imports\n * the retrievers' shapes to detect them, and the retrievers import their descriptor kind, so putting\n * both halves in one module would make every retriever ↔ telemetry edge a cycle.\n */\n\n/** Which retrieval strategy answered. `unknown` is a retriever this package did not ship. */\nexport type RetrieverKind =\n  | 'embedding'\n  | 'keyword'\n  | 'lexical'\n  | 'hybrid'\n  | 'filtered'\n  | 'reranking'\n  | 'unknown';\n\n/** Which backend held the chunks. Omitted entirely for a retriever that holds its own (keyword). */\nexport type VectorStoreKind = 'memory' | 'pg' | 'redis';\n\n/**\n * A retriever's (or a store's) self-description, as it appears on a retrieval event. Every field is\n * optional because the describer is answering only for the layer it *is*: a store knows its backend\n * and namespace but not which strategy queried it; `KeywordRetriever` knows its strategy but has no\n * store at all.\n */\nexport interface RetrievalDescriptor {\n  retriever?: RetrieverKind;\n  store?: VectorStoreKind;\n  /**\n   * The namespace the chunks live in — `PgVectorStore`'s table, `RedisVectorStore`'s RediSearch\n   * index. This is the STORE-level namespace, not a per-query metadata scope: a host that partitions\n   * one index into logical collections with a metadata filter (the usual multi-tenant shape) reports\n   * that through `InstrumentRetrieverOptions.collection`, which overrides this.\n   */\n  collection?: string;\n}\n\n/**\n * The optional capability a store or retriever implements to appear on a retrieval event as\n * something other than `unknown`. Deliberately NOT a member of `VectorStore` or of core's\n * `Retriever`: both are implemented outside this package, and adding a required member to either\n * would break every existing implementation on upgrade — for a field that only observability reads.\n */\nexport interface DescribesRetrieval {\n  describeRetrieval(): RetrievalDescriptor;\n}\n\n/** Structural guard, so a `VectorStore`/`Retriever` is narrowed to the capability without a cast. */\nexport function describesRetrieval(value: unknown): value is DescribesRetrieval {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    typeof Reflect.get(value, 'describeRetrieval') === 'function'\n  );\n}\n\n/** A candidate's descriptor, or an empty one when it does not carry the capability. */\nexport function describeRetrieval(candidate: unknown): RetrievalDescriptor {\n  return describesRetrieval(candidate) ? candidate.describeRetrieval() : {};\n}\n\n/**\n * The store half of a wrapped retriever's descriptor: the base's `store`/`collection` with its\n * `retriever` dropped, so the wrapper can stamp its own strategy on top.\n *\n * `new FilteredRetriever(new EmbeddingRetriever(embedder, pg), scope)` therefore reports\n * `{ retriever: 'filtered', store: 'pg', collection: 'agent_rag_chunks' }` rather than losing the\n * store: which backend answered is the thing a \"retrievals by store\" panel exists to show, and a\n * production wiring is almost always two or three wrappers deep.\n */\nexport function describeSource(base: unknown): Omit<RetrievalDescriptor, 'retriever'> {\n  const { retriever: _ignored, ...source } = describeRetrieval(base);\n  return source;\n}\n\n/**\n * The store half shared by EVERY leg of a composed retriever, or nothing when they disagree.\n *\n * A hybrid whose legs are the dense and lexical halves of the same RediSearch index (the shape\n * `LexicalRetriever` exists for) genuinely was served by that one store, and reporting it is what\n * makes the store breakdown add up. A hybrid fusing pgvector with an in-process BM25 index was not\n * served by either alone, and picking the first leg would silently attribute every such retrieval to\n * a store that answered half of it.\n */\nexport function describeSharedSource(\n  legs: readonly unknown[],\n): Omit<RetrievalDescriptor, 'retriever'> {\n  const sources = legs.map(describeSource);\n  const [first] = sources;\n  if (first === undefined) {\n    return {};\n  }\n  const agrees = sources.every(\n    (source) => source.store === first.store && source.collection === first.collection,\n  );\n  return agrees ? first : {};\n}\n","import type {\n  EmbeddingProvider,\n  Passage,\n  RetrieveOptions,\n  Retriever,\n} from '@dudousxd/nestjs-agent-core';\nimport { type RetrievalDescriptor, describeSource } from './retrieval-descriptor.js';\nimport type { VectorStore } from './vector-store.js';\n\nexport interface EmbeddingRetrieverOptions {\n  /**\n   * Drop passages scoring below this, so a query the corpus cannot answer returns nothing.\n   *\n   * A vector search always returns its `topK` nearest neighbours, and \"nearest\" is not \"relevant\".\n   * Ask a corpus of maintenance policy about the dining hall menu and it hands back the five least\n   * unrelated paragraphs it has, each with a score, in confident rank order. Nothing in that result\n   * says the answer is absent, so without a floor the consumer either feeds a model five irrelevant\n   * passages or invents a threshold of its own.\n   *\n   * **This is the only place in the package where a threshold is meaningful, which is why it lives\n   * here and not on `HybridRetriever`.** The score here comes straight from the store's vector\n   * search: a calibrated similarity, comparable across queries and monotonic in how well the passage\n   * matches. A fused score is neither — see the score section on `HybridRetriever`. Threshold each\n   * leg, then fuse; never the other way round.\n   *\n   * Pick the number by measuring, not by taste: score questions you know the corpus answers against\n   * questions you know it does not, and put the floor in the gap between the two populations. It is\n   * specific to the embedding model and the distance metric, so it does not survive changing either.\n   * Left unset nothing is dropped, which is the previous behaviour exactly.\n   */\n  minScore?: number;\n}\n\n/**\n * Bridges an {@link EmbeddingProvider} + {@link VectorStore} into the core {@link Retriever} SPI:\n * embed the query, then vector-search. This is what you wire as the agent's retriever (as a tool\n * via `createRetrievalTool`, or into `AgentModule.forRoot({ retrieval })` for inject mode).\n */\nexport class EmbeddingRetriever implements Retriever {\n  constructor(\n    private readonly embedder: EmbeddingProvider,\n    private readonly store: VectorStore,\n    private readonly options: EmbeddingRetrieverOptions = {},\n  ) {}\n\n  /** Telemetry self-description — the dense strategy, over whatever store it was handed. */\n  describeRetrieval(): RetrievalDescriptor {\n    return { retriever: 'embedding', ...describeSource(this.store) };\n  }\n\n  async retrieve(query: string, options: RetrieveOptions = {}): Promise<Passage[]> {\n    const [embedding] = await this.embedder.embed([query]);\n    if (embedding === undefined) {\n      return [];\n    }\n    const passages = await this.store.search(embedding, {\n      topK: options.topK ?? 5,\n      ...(options.filter !== undefined ? { filter: options.filter } : {}),\n    });\n    const { minScore } = this.options;\n    // Applied here rather than pushed into the store's query: not every backend can express \"score\n    // above X\" in the same call as its KNN search, and filtering after keeps the floor byte-identical\n    // across all three adapters instead of subtly engine-specific. It also keeps `topK` meaning \"ask\n    // the store for this many\", so a floor never silently turns into a smaller search.\n    return minScore === undefined\n      ? passages\n      : passages.filter((passage) => passage.score >= minScore);\n  }\n}\n","import type { Passage, RetrieveOptions, Retriever } from '@dudousxd/nestjs-agent-core';\nimport { matchesFilter } from './filter.js';\nimport type { ChunkRecord } from './ingest.js';\nimport type { RetrievalDescriptor } from './retrieval-descriptor.js';\nimport { documentIdOf } from './vector-store.js';\n\nexport interface KeywordRetrieverOptions {\n  /** BM25 term-frequency saturation. Default 1.5. */\n  k1?: number;\n  /** BM25 length normalization, 0 (off) … 1 (full). Default 0.75. */\n  b?: number;\n}\n\ninterface IndexedDoc {\n  record: ChunkRecord;\n  /** term → frequency within this doc. */\n  frequencies: Map<string, number>;\n  length: number;\n}\n\n/**\n * An in-memory BM25 lexical retriever — the keyword half of hybrid search. Feed it the SAME\n * {@link ChunkRecord}s you upsert into the vector store (from `chunkDocuments`) so their chunk ids\n * line up and `HybridRetriever` can fuse the two rankings. Full BM25: idf, term-frequency saturation\n * (`k1`), and document-length normalization (`b`).\n *\n * Because it holds its OWN copy of each chunk's text, it needs the same delete-sync as the vector\n * store: whenever you call {@link import('./vector-store.js').VectorStore.remove}, call\n * {@link KeywordRetriever.remove} with the same document id. Skipping it leaves the document\n * lexically retrievable — `retrieve` would keep returning the removed passage's full text.\n */\nexport class KeywordRetriever implements Retriever {\n  private readonly docs = new Map<string, IndexedDoc>();\n  private readonly documentFrequency = new Map<string, number>();\n  private totalLength = 0;\n  private readonly k1: number;\n  private readonly b: number;\n\n  constructor(options: KeywordRetrieverOptions = {}) {\n    this.k1 = options.k1 ?? 1.5;\n    this.b = options.b ?? 0.75;\n  }\n\n  /**\n   * Telemetry self-description. No `store`: this retriever holds its own copy of the corpus in\n   * process, so attributing its retrievals to whichever vector store happens to hold the same chunks\n   * would credit a backend that was never queried.\n   */\n  describeRetrieval(): RetrievalDescriptor {\n    return { retriever: 'keyword' };\n  }\n\n  /** How many chunks are currently indexed. */\n  get size(): number {\n    return this.docs.size;\n  }\n\n  /** Index (or re-index) records. Re-adding an existing id replaces its posting and updates stats. */\n  add(records: ChunkRecord[]): void {\n    for (const record of records) {\n      this.removeChunk(record.id);\n      const tokens = tokenize(record.text);\n      const frequencies = new Map<string, number>();\n      for (const token of tokens) {\n        frequencies.set(token, (frequencies.get(token) ?? 0) + 1);\n      }\n      for (const term of frequencies.keys()) {\n        this.documentFrequency.set(term, (this.documentFrequency.get(term) ?? 0) + 1);\n      }\n      this.docs.set(record.id, { record, frequencies, length: tokens.length });\n      this.totalLength += tokens.length;\n    }\n  }\n\n  /**\n   * Forget a source document — every chunk whose id is `${documentId}` or `${documentId}#<n>`, the\n   * same id scheme (and the same {@link documentIdOf} collapse) the vector stores use for their\n   * `remove`. The keyword half of a hybrid index keeps its own copy of the chunk text, so a document\n   * dropped from the vector store stays fully retrievable here until this is called. Unknown ids are\n   * a no-op.\n   */\n  remove(documentId: string): void {\n    for (const id of [...this.docs.keys()]) {\n      if (id === documentId || documentIdOf(id) === documentId) {\n        this.removeChunk(id);\n      }\n    }\n  }\n\n  /** Drop every indexed chunk, resetting the corpus statistics with it. */\n  clear(): void {\n    this.docs.clear();\n    this.documentFrequency.clear();\n    this.totalLength = 0;\n  }\n\n  /** Drop ONE chunk by its exact id, decrementing the corpus statistics it contributed. */\n  private removeChunk(id: string): void {\n    const existing = this.docs.get(id);\n    if (existing === undefined) {\n      return;\n    }\n    for (const term of existing.frequencies.keys()) {\n      const next = (this.documentFrequency.get(term) ?? 1) - 1;\n      if (next <= 0) {\n        this.documentFrequency.delete(term);\n      } else {\n        this.documentFrequency.set(term, next);\n      }\n    }\n    this.totalLength -= existing.length;\n    this.docs.delete(id);\n  }\n\n  async retrieve(query: string, options: RetrieveOptions = {}): Promise<Passage[]> {\n    const total = this.docs.size;\n    if (total === 0) {\n      return [];\n    }\n    const averageLength = this.totalLength / total;\n    const queryTerms = new Set(tokenize(query));\n    const scored: Passage[] = [];\n    for (const { record, frequencies, length } of this.docs.values()) {\n      if (options.filter !== undefined && !matchesFilter(record.metadata, options.filter)) {\n        continue;\n      }\n      let score = 0;\n      for (const term of queryTerms) {\n        const termFrequency = frequencies.get(term);\n        if (termFrequency === undefined) {\n          continue;\n        }\n        const df = this.documentFrequency.get(term) ?? 0;\n        const idf = Math.log(1 + (total - df + 0.5) / (df + 0.5));\n        const denominator =\n          termFrequency + this.k1 * (1 - this.b + (this.b * length) / averageLength);\n        score += idf * ((termFrequency * (this.k1 + 1)) / denominator);\n      }\n      if (score > 0) {\n        scored.push({\n          id: record.id,\n          text: record.text,\n          score,\n          ...(record.source !== undefined ? { source: record.source } : {}),\n          ...(record.metadata !== undefined ? { metadata: record.metadata } : {}),\n        });\n      }\n    }\n    return scored.sort((a, b) => b.score - a.score).slice(0, options.topK ?? 5);\n  }\n}\n\nfunction tokenize(text: string): string[] {\n  return text.toLowerCase().match(/[a-z0-9]+/g) ?? [];\n}\n","import type { Passage, RetrieveOptions, Retriever } from '@dudousxd/nestjs-agent-core';\nimport { type RetrievalDescriptor, describeSource } from './retrieval-descriptor.js';\nimport type { LexicalVectorStore } from './vector-store.js';\n\n/**\n * The keyword half of hybrid search, served by the store's own full-text index — the mirror of\n * {@link import('./embedding-retriever.js').EmbeddingRetriever}, which serves the dense half. It\n * holds no state: every query goes to the store, so any process that can reach the store can run\n * lexical search, whether or not it did the ingestion.\n *\n * Compose it exactly like the dense leg:\n *\n * ```ts\n * const retriever = new HybridRetriever([\n *   new EmbeddingRetriever(embedder, store),\n *   new LexicalRetriever(store),\n * ]);\n * ```\n *\n * Both legs read the same chunks from the same index, so their ids line up by construction and\n * `HybridRetriever`'s RRF fuses them without either side needing a score on a common scale.\n *\n * Prefer this over {@link import('./keyword-retriever.js').KeywordRetriever} whenever the store\n * supports it (see {@link import('./vector-store.js').isLexicalVectorStore}) and ingestion and\n * search can run in different processes; `KeywordRetriever` remains the answer for `MemoryVectorStore`\n * and single-process deployments.\n */\nexport class LexicalRetriever implements Retriever {\n  constructor(private readonly store: LexicalVectorStore) {}\n\n  /** Telemetry self-description — the store's own lexical index, so the store is the same one. */\n  describeRetrieval(): RetrievalDescriptor {\n    return { retriever: 'lexical', ...describeSource(this.store) };\n  }\n\n  async retrieve(query: string, options: RetrieveOptions = {}): Promise<Passage[]> {\n    return this.store.searchText(query, {\n      topK: options.topK ?? 5,\n      ...(options.filter !== undefined ? { filter: options.filter } : {}),\n    });\n  }\n}\n","import type { Passage, RetrieveOptions, Retriever } from '@dudousxd/nestjs-agent-core';\nimport { type RetrievalDescriptor, describeSharedSource } from './retrieval-descriptor.js';\n\nexport interface HybridRetrieverOptions {\n  /** RRF constant — larger flattens the rank weighting. Default 60 (the value from the original paper). */\n  k?: number;\n  /** Candidates pulled from each retriever before fusion. Default 20. */\n  fetchTopK?: number;\n  /** Per-retriever multipliers on each RRF contribution (same order as `retrievers`). Default all 1. */\n  weights?: number[];\n}\n\n/**\n * Fuses several retrievers with Reciprocal Rank Fusion — the robust way to combine, say, dense\n * vector search with lexical BM25. RRF scores each passage by `Σ weight / (k + rank)` across the\n * lists it appears in, so it needs no score normalization between incompatible scales (cosine vs\n * BM25). Deduplicates by passage id, so aligned chunk ids from the two retrievers reinforce.\n *\n * ## The score on a fused passage is not a similarity. Do not threshold it.\n *\n * Read this before using `passage.score` for anything other than the order it already produced.\n *\n * Not normalizing between scales is what makes RRF robust, and the price is that the number it\n * emits is a function of **rank alone** — it never sees a similarity at all. Two consequences that\n * bite in practice:\n *\n * - **It is not comparable to the score on a passage from {@link EmbeddingRetriever}**, even though\n *   it arrives in the same field, of the same type, from the same `Retriever` interface. There is no\n *   discriminator; a consumer holding a `Passage[]` cannot tell which kind of number it has. If you\n *   surface scores to a user or a model, know which retriever produced them.\n * - **Its range is narrow, fixed, and says nothing about quality.** Every possible score lies in\n *   `[minWeight / (k + fetchTopK), Σ weights / (k + 1)]` — with the defaults (`k = 60`,\n *   `fetchTopK = 20`, two unweighted legs) that is `[0.0125, 0.0328]`. A perfect match and the\n *   least-bad member of a set of terrible matches both come back around `0.016`.\n *\n * The second point is why a relevance floor cannot live here. What the fused score actually measures\n * is how strongly the legs *agree* — and agreement tracks nothing about correctness. When both legs\n * return the same nearest nothing for an unanswerable query, they reinforce it to the ceiling, the\n * same ceiling a unanimous correct answer gets. Measured on one corpus, the dense leg alone\n * separated cleanly (weakest real answer 0.244, loudest absent-topic answer 0.143) while those same\n * queries after fusion scored 0.032 and 0.033 — inverted. On another corpus the inversion may not\n * appear; what does not change is that both numbers live in a band roughly one part in fifty wide,\n * with no room for a threshold to mean anything.\n *\n * So: put the floor on the legs, with {@link EmbeddingRetrieverOptions.minScore}, and fuse what\n * survives. `HybridRetriever` deliberately has no `minScore` of its own; a threshold option here\n * would be an invitation to apply it to a number that cannot support one.\n */\nexport class HybridRetriever implements Retriever {\n  constructor(\n    private readonly retrievers: Retriever[],\n    private readonly options: HybridRetrieverOptions = {},\n  ) {}\n\n  /** Telemetry self-description — the store only when every leg agrees; see `describeSharedSource`. */\n  describeRetrieval(): RetrievalDescriptor {\n    return { retriever: 'hybrid', ...describeSharedSource(this.retrievers) };\n  }\n\n  async retrieve(query: string, options: RetrieveOptions = {}): Promise<Passage[]> {\n    const k = this.options.k ?? 60;\n    const fetchTopK = this.options.fetchTopK ?? 20;\n    const weights = this.options.weights;\n    const lists = await Promise.all(\n      this.retrievers.map((retriever) =>\n        retriever.retrieve(query, {\n          topK: fetchTopK,\n          ...(options.filter !== undefined ? { filter: options.filter } : {}),\n        }),\n      ),\n    );\n\n    const fused = new Map<string, { passage: Passage; score: number }>();\n    lists.forEach((list, listIndex) => {\n      const weight = weights?.[listIndex] ?? 1;\n      list.forEach((passage, rank) => {\n        const contribution = weight / (k + rank + 1);\n        const existing = fused.get(passage.id);\n        if (existing !== undefined) {\n          existing.score += contribution;\n        } else {\n          fused.set(passage.id, { passage, score: contribution });\n        }\n      });\n    });\n\n    return [...fused.values()]\n      .sort((a, b) => b.score - a.score)\n      .slice(0, options.topK ?? 5)\n      .map((entry) => ({ ...entry.passage, score: entry.score }));\n  }\n}\n","import type { Passage, Reranker, RetrieveOptions, Retriever } from '@dudousxd/nestjs-agent-core';\nimport { type RetrievalDescriptor, describeSource } from './retrieval-descriptor.js';\n\nexport interface RerankingRetrieverOptions {\n  /** How many candidates to pull from the base retriever before reranking. Default 20. */\n  fetchTopK?: number;\n}\n\n/**\n * Two-stage retrieval: over-fetch cheap candidates from a base `Retriever`, then reorder them with a\n * stronger {@link Reranker} and keep the top few. The standard precision boost — a fast first stage\n * casts a wide net, a slow accurate second stage sharpens it. Composes over ANY retriever (vector,\n * hybrid, keyword), and is itself a `Retriever`.\n */\nexport class RerankingRetriever implements Retriever {\n  constructor(\n    private readonly base: Retriever,\n    private readonly reranker: Reranker,\n    private readonly options: RerankingRetrieverOptions = {},\n  ) {}\n\n  /** Telemetry self-description — the two-stage strategy, over the base's store. */\n  describeRetrieval(): RetrievalDescriptor {\n    return { retriever: 'reranking', ...describeSource(this.base) };\n  }\n\n  async retrieve(query: string, options: RetrieveOptions = {}): Promise<Passage[]> {\n    const candidates = await this.base.retrieve(query, {\n      topK: this.options.fetchTopK ?? 20,\n      ...(options.filter !== undefined ? { filter: options.filter } : {}),\n    });\n    return this.reranker.rerank(query, candidates, { topK: options.topK ?? 5 });\n  }\n}\n","import type { Passage, RetrieveOptions, Retriever } from '@dudousxd/nestjs-agent-core';\nimport { type RetrievalDescriptor, describeSource } from './retrieval-descriptor.js';\n\n/**\n * Wraps a `Retriever` so every `retrieve` call ANDs a fixed metadata `filter` on top of whatever the\n * caller passes — the owner/tenant-scoping primitive. `new FilteredRetriever(base, { ownerId })` only\n * ever returns that owner's passages, so a shared vector store serves per-user / per-tenant RAG\n * without the agent (or a crafted query) reaching across the boundary.\n *\n * The fixed filter takes precedence on key conflicts: a caller can narrow further but cannot widen\n * past the scope. Composes over ANY retriever (vector, hybrid, reranked) and is itself a `Retriever`.\n */\nexport class FilteredRetriever implements Retriever {\n  constructor(\n    private readonly base: Retriever,\n    private readonly filter: Record<string, unknown>,\n  ) {}\n\n  /** Telemetry self-description — this scope, over the base's store. */\n  describeRetrieval(): RetrievalDescriptor {\n    return { retriever: 'filtered', ...describeSource(this.base) };\n  }\n\n  async retrieve(query: string, options: RetrieveOptions = {}): Promise<Passage[]> {\n    return this.base.retrieve(query, {\n      ...options,\n      filter: { ...options.filter, ...this.filter },\n    });\n  }\n}\n","import type { EmbeddingProvider } from '@dudousxd/nestjs-agent-core';\nimport { type ChunkOptions, chunkText } from './chunk.js';\nimport type { VectorRecord, VectorStore } from './vector-store.js';\n\n/** A source document to ingest. `id` scopes the chunk ids (`${id}#${n}`); `source` is the citation. */\nexport interface IngestDocument {\n  id: string;\n  text: string;\n  source?: string;\n  metadata?: Record<string, unknown>;\n}\n\n/** A chunked, not-yet-embedded record. Feed the same array to a vector store AND a keyword index so\n * both retrievers key on identical chunk ids (which is what lets hybrid fusion line them up). */\nexport interface ChunkRecord {\n  id: string;\n  text: string;\n  source?: string;\n  metadata?: Record<string, unknown>;\n}\n\nexport interface IngestChunksOptions {\n  embedder: EmbeddingProvider;\n  store: VectorStore;\n}\n\nexport interface IngestOptions extends ChunkOptions, IngestChunksOptions {}\n\n/**\n * Split documents into chunk records. Chunk ids are `${doc.id}#${index}`, so re-chunking the same\n * document produces the same ids (upsert overwrites in place rather than duplicating).\n */\nexport function chunkDocuments(\n  documents: IngestDocument[],\n  options: ChunkOptions = {},\n): ChunkRecord[] {\n  const chunks: ChunkRecord[] = [];\n  for (const document of documents) {\n    chunkText(document.text, options).forEach((text, index) => {\n      chunks.push({\n        id: `${document.id}#${index}`,\n        text,\n        ...(document.source !== undefined ? { source: document.source } : {}),\n        ...(document.metadata !== undefined ? { metadata: document.metadata } : {}),\n      });\n    });\n  }\n  return chunks;\n}\n\n/** Embed pre-chunked records (one batched `embed`) and upsert them. Returns the record count. */\nexport async function ingestChunks(\n  chunks: ChunkRecord[],\n  options: IngestChunksOptions,\n): Promise<number> {\n  if (chunks.length === 0) {\n    return 0;\n  }\n  const embeddings = await options.embedder.embed(chunks.map((chunk) => chunk.text));\n  const records: VectorRecord[] = chunks.map((chunk, index) => ({\n    ...chunk,\n    embedding: embeddings[index] ?? [],\n  }));\n  await options.store.upsert(records);\n  return records.length;\n}\n\n/** Chunk → embed → upsert in one call. For hybrid search, use {@link chunkDocuments} +\n * {@link ingestChunks} and feed the same chunks to a {@link import('./keyword-retriever.js').KeywordRetriever}. */\nexport async function ingestDocuments(\n  documents: IngestDocument[],\n  options: IngestOptions,\n): Promise<number> {\n  return ingestChunks(chunkDocuments(documents, options), options);\n}\n","import { AsyncLocalStorage } from 'node:async_hooks';\nimport type { Passage, RetrieveOptions, Retriever } from '@dudousxd/nestjs-agent-core';\nimport { channelName, emit, getChannel } from '@dudousxd/nestjs-diagnostics';\nimport {\n  type RetrievalDescriptor,\n  type RetrieverKind,\n  type VectorStoreKind,\n  describeRetrieval,\n} from './retrieval-descriptor.js';\n\n/**\n * Retrieval telemetry: one diagnostics event per retrieval, carrying how long it took, how much came\n * back, how good it was, and what served it.\n *\n * Until this existed, retrieval reached Telescope only as the *tool call* that wrapped it (see\n * `retrieval-tool.ts`), which says a retrieval happened and nothing else. The questions an operator\n * actually arrives with — is retrieval slow, is it returning nothing, is one collection colder than\n * the rest, did the scores collapse after a model swap — are all invisible in a tool-call row,\n * because a tool call that returns zero passages and one that returns five perfect ones are the same\n * row with the same `ok` status.\n *\n * ## One seam, not six\n *\n * Instrumentation is a WRAPPER over the core `Retriever` SPI ({@link instrumentRetriever}), not code\n * inside each retriever. Every retriever in this package — and every retriever outside it — is the\n * same one-method interface, so one wrapper covers all of them, including ones this package has\n * never heard of. The alternative, an `emit` inside each of the six `retrieve` methods, would have\n * had to be repeated in each, skipped by third-party retrievers entirely, and would have double- and\n * triple-counted the composed ones (a hybrid over two legs emitting three events for one retrieval).\n *\n * ## How a composed retrieval reports\n *\n * **The outermost instrumented retriever in a call tree emits; anything instrumented inside it stays\n * silent.** A retrieval is one question the caller asked, so it is one event no matter how many\n * retrievers cooperated to answer it: `RerankingRetriever` over a `HybridRetriever` over a dense and\n * a lexical leg is ONE retrieval, reported as `retriever: 'reranking'` with the duration of the\n * whole thing and the scores the caller actually got back.\n *\n * The suppression is enforced with an {@link AsyncLocalStorage} flag rather than by asking hosts to\n * wrap carefully, because the wrapping that double-counts is the natural one: a host that wraps its\n * top-level retriever and *also* wraps the dense leg it shares with another code path has not made a\n * mistake, and would otherwise get two events per retrieval, a zero-hit rate computed over a mixture\n * of legs and composites, and a retrieval count roughly twice its query count.\n *\n * ## Opt-out safety, and what the hot path pays\n *\n * The event goes out on `aviary:rag:retrieval` via `@dudousxd/nestjs-diagnostics`, whose `emit` is\n * gated on `channel.hasSubscribers` and never throws. This wrapper checks that same gate BEFORE it\n * does anything at all — no clock read, no `AsyncLocalStorage.run`, no score arithmetic — and\n * delegates straight through when nothing is listening. A host that wires this package without\n * Telescope (or any subscriber) pays two `Map` lookups and a boolean per retrieval, and nothing else\n * changes: the wrapper returns the base retriever's passages verbatim, and rethrows its errors\n * unchanged.\n *\n * ## Why this channel is not merged into the typed `ChannelRegistry`\n *\n * `@dudousxd/nestjs-agent-rag-media` already emits `media.ingested`/`media.removed`/`media.skipped`/\n * `media.failed` on the same `rag` lib, and flip's host app emits `rag:search` on it. Declaring\n * `ChannelRegistry['rag'] = { retrieval: RagRetrievalEvent }` here would narrow `EventOf<'rag'>` to\n * this one key process-wide and turn every one of those sibling emits into a compile error in any\n * project that installs both packages. The payload stays typed where it matters — {@link emitRagRetrieval}\n * takes {@link RagRetrievalEvent} — and the wire contract is documented below instead.\n */\n\n/** The diagnostics lib segment. Shared with `@dudousxd/nestjs-agent-rag-media`'s `media.*` events. */\nexport const RAG_DIAGNOSTIC_LIB = 'rag';\n\n/** The diagnostics event segment. */\nexport const RAG_RETRIEVAL_EVENT = 'retrieval';\n\n/**\n * The full channel name a subscriber listens on: `aviary:rag:retrieval`. This is the wire contract —\n * `@dudousxd/nestjs-agent-telescope` subscribes to this exact string rather than importing this\n * package, which is what keeps the telescope extension free of a dependency on the retrieval stack\n * (and lets a host that uses neither still observe retrieval with a bare `diagnostics_channel`\n * subscription).\n */\nexport const RAG_RETRIEVAL_CHANNEL = channelName(RAG_DIAGNOSTIC_LIB, RAG_RETRIEVAL_EVENT);\n\n/**\n * The payload of one retrieval event. Counts, durations, kinds and scores only — never the query\n * text and never passage text. Both are user content, and this lands in an ops store with a short\n * retention window and a Slack-facing redaction budget; everything here is safe to put on a\n * dashboard and is what tells the failure modes apart anyway.\n *\n * The DURATION is not in here: it rides the envelope (`emit`'s `opts.durationMs`), which is the field\n * Telescope's OTel exporter turns into a latency histogram. Putting it in the payload instead would\n * have made retrieval latency a number somebody reads out of a JSON blob rather than a graph.\n */\nexport interface RagRetrievalEvent {\n  /** Which strategy answered — the OUTERMOST one, for a composed retriever. */\n  retriever: RetrieverKind;\n  /** Which backend held the chunks. Absent for an in-process retriever, or when legs disagree. */\n  store?: VectorStoreKind;\n  /** Store namespace (pg table / RediSearch index), or the host's logical collection. */\n  collection?: string;\n  /** What the caller asked for, so `chunks < topK` is readable as \"the corpus ran out\". */\n  topK: number;\n  /** How many passages came back. */\n  chunks: number;\n  /**\n   * `chunks === 0`. Carried as its own flag rather than left to be derived, because the zero-hit RATE\n   * is the headline number and deriving it means every consumer re-deriving the same predicate.\n   */\n  zeroHit: boolean;\n  /** Best score in the result, rounded to 4dp. Absent on a zero-hit. */\n  topScore?: number;\n  /** Mean score across the result, rounded to 4dp. Absent on a zero-hit. */\n  meanScore?: number;\n  /**\n   * The retrieval threw. Reported rather than dropped because a failed retrieval and an empty one\n   * look identical from the agent's side — both become \"I couldn't find anything\" — so a channel\n   * that only carried successes would go quiet exactly when retrieval broke.\n   */\n  failed: boolean;\n  /** The error message, when `failed`. */\n  error?: string;\n}\n\n/** Publish one retrieval event. `durationMs` rides the envelope; see {@link RagRetrievalEvent}. */\nexport function emitRagRetrieval(event: RagRetrievalEvent, durationMs: number): void {\n  emit(RAG_DIAGNOSTIC_LIB, RAG_RETRIEVAL_EVENT, event, { durationMs });\n}\n\nexport interface InstrumentRetrieverOptions {\n  /**\n   * Override the auto-detected {@link RetrievalDescriptor}, field by field. Needed for a retriever or\n   * store from outside this package (which reports `retriever: 'unknown'` and no store), and for a\n   * host that wants its own naming.\n   */\n  describe?: RetrievalDescriptor;\n  /**\n   * The logical collection this retrieval searched, when the store namespace is not it. Pass a\n   * function to read it off the call's metadata filter — the multi-tenant shape, where one index\n   * holds every collection and the filter picks one:\n   *\n   * ```ts\n   * instrumentRetriever(retriever, {\n   *   collection: (filter) => (typeof filter?.collectionId === 'string' ? filter.collectionId : undefined),\n   * })\n   * ```\n   *\n   * Returning `undefined` falls back to the store namespace, which is the right answer for a query\n   * scoped to many collections at once: a breakdown panel needs ONE label per retrieval, and\n   * inventing a synthetic `\"a+b+c\"` bucket would produce a chart whose slices are combinations\n   * rather than collections.\n   */\n  collection?: string | ((filter: Record<string, unknown> | undefined) => string | undefined);\n}\n\n/**\n * The default a retriever falls back to when the caller names no `topK` — every retriever in this\n * package uses `options.topK ?? 5`, so reporting anything else here would make `chunks < topK`\n * misread as truncation on exactly the calls that did not ask for a limit.\n */\nconst DEFAULT_TOP_K = 5;\n\n/**\n * Set for the duration of an instrumented `retrieve`, so an instrumented retriever running INSIDE\n * another one knows it is a leg and stays silent. See the composed-retrieval section above.\n */\nconst inRetrieval = new AsyncLocalStorage<true>();\n\n/** Round to 4dp — enough to see a score distribution move, short enough to keep the payload small. */\nfunction round4(value: number): number {\n  return Math.round(value * 10_000) / 10_000;\n}\n\n/** Top + mean score, skipping any passage whose `score` is not a finite number. */\nfunction scoreStats(passages: Passage[]): { topScore?: number; meanScore?: number } {\n  const scores = passages.map((passage) => passage.score).filter((score) => Number.isFinite(score));\n  if (scores.length === 0) {\n    return {};\n  }\n  const sum = scores.reduce((total, score) => total + score, 0);\n  return { topScore: round4(Math.max(...scores)), meanScore: round4(sum / scores.length) };\n}\n\nclass InstrumentedRetriever implements Retriever {\n  constructor(\n    private readonly base: Retriever,\n    private readonly options: InstrumentRetrieverOptions = {},\n  ) {}\n\n  /** Transparent to detection: wrapping a retriever must not turn it into an `unknown` one. */\n  describeRetrieval(): RetrievalDescriptor {\n    return { ...describeRetrieval(this.base), ...this.options.describe };\n  }\n\n  async retrieve(query: string, options: RetrieveOptions = {}): Promise<Passage[]> {\n    // Both gates before any work: nothing subscribed, or we are a leg of an outer instrumented\n    // retrieval that will report the whole thing itself.\n    if (!getChannel(RAG_DIAGNOSTIC_LIB, RAG_RETRIEVAL_EVENT).hasSubscribers) {\n      return this.base.retrieve(query, options);\n    }\n    if (inRetrieval.getStore() === true) {\n      return this.base.retrieve(query, options);\n    }\n\n    const descriptor = this.describeRetrieval();\n    const topK = options.topK ?? DEFAULT_TOP_K;\n    const startedAt = Date.now();\n    try {\n      const passages = await inRetrieval.run(true, () => this.base.retrieve(query, options));\n      emitRagRetrieval(\n        {\n          retriever: descriptor.retriever ?? 'unknown',\n          ...(descriptor.store !== undefined ? { store: descriptor.store } : {}),\n          ...this.collectionOf(options.filter, descriptor),\n          topK,\n          chunks: passages.length,\n          zeroHit: passages.length === 0,\n          ...scoreStats(passages),\n          failed: false,\n        },\n        Date.now() - startedAt,\n      );\n      return passages;\n    } catch (error) {\n      emitRagRetrieval(\n        {\n          retriever: descriptor.retriever ?? 'unknown',\n          ...(descriptor.store !== undefined ? { store: descriptor.store } : {}),\n          ...this.collectionOf(options.filter, descriptor),\n          topK,\n          chunks: 0,\n          zeroHit: true,\n          failed: true,\n          error: error instanceof Error ? error.message : String(error),\n        },\n        Date.now() - startedAt,\n      );\n      throw error;\n    }\n  }\n\n  /** The host's collection for this call, else the store namespace, else nothing. */\n  private collectionOf(\n    filter: Record<string, unknown> | undefined,\n    descriptor: RetrievalDescriptor,\n  ): { collection?: string } {\n    const { collection } = this.options;\n    const resolved =\n      typeof collection === 'function' ? collection(filter) : (collection ?? descriptor.collection);\n    return resolved !== undefined ? { collection: resolved } : {};\n  }\n}\n\n/**\n * Wrap a retriever so every `retrieve` publishes a {@link RagRetrievalEvent} on\n * {@link RAG_RETRIEVAL_CHANNEL}. Wrap the retriever you actually hand to the agent — the outermost\n * one — and nothing else needs changing:\n *\n * ```ts\n * const retriever = instrumentRetriever(\n *   new HybridRetriever([new EmbeddingRetriever(embedder, store), new LexicalRetriever(store)]),\n * );\n * ```\n *\n * {@link createRetrievalTool} already does this for the tool it builds, so agentic retrieval is\n * instrumented with no host change at all; call this directly for inject-mode retrieval\n * (`AgentModule.forRoot({ retrieval })`) or for a host that calls `retrieve` itself. Wrapping twice\n * is harmless — see the composed-retrieval section above.\n */\nexport function instrumentRetriever(\n  retriever: Retriever,\n  options: InstrumentRetrieverOptions = {},\n): Retriever {\n  return new InstrumentedRetriever(retriever, options);\n}\n","import type { Passage, Retriever, ToolHandler, ToolSpec } from '@dudousxd/nestjs-agent-core';\nimport type { StandardSchemaV1 } from '@standard-schema/spec';\nimport { type InstrumentRetrieverOptions, instrumentRetriever } from './retrieval-telemetry.js';\n\nexport interface RetrievalToolOptions {\n  /** Tool name the model sees. Default `search_knowledge`. */\n  name?: string;\n  description?: string;\n  /** Passages per search. Default lets the retriever decide (typically 5). */\n  topK?: number;\n  /**\n   * Retrieval telemetry (`aviary:rag:retrieval` — duration, chunk count, score distribution, store\n   * and collection). **On by default**, because this tool is the once-per-retrieval seam in agentic\n   * mode: instrumenting here is what makes the RAG panels work for a host that only ever calls\n   * `createRetrievalTool`, with no wiring at all. It costs nothing when nobody subscribes (see\n   * {@link instrumentRetriever}), and cannot double-count when the host has already wrapped the\n   * retriever itself.\n   *\n   * Pass `false` to opt a single tool out — a host that reports retrieval its own way, or one whose\n   * corpus is small enough that the events are noise.\n   */\n  telemetry?: boolean | InstrumentRetrieverOptions;\n}\n\n/** A functional tool (`{ spec, handler }`) — pass it to nestjs `provideAgentTool`. */\nexport interface RetrievalTool {\n  spec: ToolSpec;\n  handler: ToolHandler;\n}\n\nfunction isQueryInput(value: unknown): value is { query: string } {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    'query' in value &&\n    typeof (value as Record<'query', unknown>).query === 'string'\n  );\n}\n\n/** A hand-rolled Standard Schema for `{ query: string }` — keeps this package validation-lib-free. */\nconst querySchema: StandardSchemaV1<{ query: string }> = {\n  '~standard': {\n    version: 1,\n    vendor: 'nestjs-agent-rag',\n    validate(value: unknown) {\n      return isQueryInput(value)\n        ? { value: { query: value.query } }\n        : { issues: [{ message: 'retrieval tool expects { query: string }' }] };\n    },\n  },\n};\n\n/**\n * Builds the agentic-retrieval tool: a `read`-kind `search_knowledge(query)` the model calls when it\n * decides it needs context. Its output `{ passages }` persists as the tool call's result, so sources\n * flow to the frontend and telescope through the normal tool-call machinery (the citation surface).\n *\n * The retrieval ITSELF is also instrumented (`aviary:rag:retrieval`) unless `telemetry: false` — the\n * tool-call row says a retrieval happened, the retrieval event says how long it took, how much came\n * back and how good it was. See {@link instrumentRetriever}.\n *\n * ```ts\n * providers: [provideAgentTool(createRetrievalTool(retriever))]\n * ```\n */\nexport function createRetrievalTool(\n  retriever: Retriever,\n  options: RetrievalToolOptions = {},\n): RetrievalTool {\n  const topK = options.topK;\n  const { telemetry = true } = options;\n  const instrumented =\n    telemetry === false\n      ? retriever\n      : instrumentRetriever(retriever, telemetry === true ? {} : telemetry);\n  return {\n    spec: {\n      name: options.name ?? 'search_knowledge',\n      kind: 'read',\n      description:\n        options.description ??\n        'Search the knowledge base for passages relevant to a query. Returns passages with their source for citation.',\n      inputSchema: querySchema,\n    },\n    handler: {\n      async execute(input: unknown): Promise<{ passages: Passage[] }> {\n        if (!isQueryInput(input)) {\n          throw new Error('retrieval tool expects { query: string }');\n        }\n        const passages = await instrumented.retrieve(\n          input.query,\n          topK !== undefined ? { topK } : {},\n        );\n        return { passages };\n      },\n    },\n  };\n}\n"],"mappings":"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","names":["chunkText","text","options","chunkSize","overlap","normalized","trim","length","separator","undefined","chunkByRecord","chunks","start","end","Math","min","breakAt","window","slice","boundary","max","lastIndexOf","chunk","push","current","flush","record","split","trimmed","candidate","isLexicalVectorStore","store","searchText","UnsafeRemovalError","Error","reason","message","name","chunkIndexOf","chunkId","match","exec","undefined","Number","documentIdOf","replace","splitMetadataPatch","patch","set","remove","key","value","Object","entries","push","undefined","isEmptyMetadataPatch","keys","length","applyMetadataPatch","metadata","next","matchesFilter","metadata","filter","entries","Object","undefined","length","every","key","expected","Array","isArray","actual","some","value","includes","filterMatchesNothing","values","MemoryVectorStore","records","Map","describeRetrieval","store","upsert","record","set","id","remove","documentId","keys","documentIdOf","delete","updateMetadata","patch","isEmptyMetadataPatch","updated","metadata","applyMetadataPatch","listDocuments","filter","documents","values","undefined","matchesFilter","has","listChunks","options","chunks","push","index","chunkIndexOf","text","sort","a","b","offset","limit","slice","listDocumentIds","filterMatchesNothing","Set","add","removeMany","documentIds","length","wanted","removeWhere","Object","UnsafeRemovalError","removed","countChunks","count","search","embedding","scored","score","cosineSimilarity","source","topK","dot","normA","normB","Math","min","valueA","valueB","denominator","sqrt","PgVectorStore","table","dimensions","client","options","describeRetrieval","store","collection","ensureSchema","query","upsert","records","record","id","text","source","metadata","undefined","JSON","stringify","toVectorLiteral","embedding","remove","documentId","DOCUMENT_ID_FROM_CHUNK","updateMetadata","patch","isEmptyMetadataPatch","set","splitMetadataPatch","rows","length","listDocuments","filter","where","buildWhere","sql","params","map","row","doc_id","listChunks","CHUNK_INDEX_FROM_ID","limit","push","offset","index","Number","chunk_index","listDocumentIds","filterMatchesNothing","removeMany","documentIds","removeWhere","Object","keys","UnsafeRemovalError","countChunks","count","search","vector","topK","score","startIndex","clauses","scalar","key","value","entries","Array","isArray","keyParam","arrParam","String","join","RedisVectorSchemaMismatchError","Error","index","field","expected","actual","remedy","name","RedisVectorStore","prefix","dimensions","filterableFields","lexicalScorer","client","options","describeRetrieval","store","collection","ensureSchema","info","sendCommand","createIndex","reconcileSchema","attributes","parseIndexAttributes","size","vector","get","undefined","missing","existing","push","type","schema","String","upsert","records","record","args","id","text","encodeVector","embedding","source","metadata","JSON","stringify","value","encodeTag","remove","documentId","keys","chunkKeys","length","updateMetadata","patch","isEmptyMetadataPatch","updated","key","raw","current","parseMetadata","toStr","next","applyMetadataPatch","stale","Set","bare","exists","Number","add","pattern","escapeGlob","cursor","reply","page","parseScanReply","listChunks","ordered","map","slice","entry","chunkIndexOf","sort","a","b","offset","limit","chunks","fields","Array","isArray","listDocuments","filter","filterMatchesNothing","query","buildFilter","documents","Map","batchSize","passages","parseSearchReply","passage","documentIdOf","has","set","values","listDocumentIds","SCAN_PAGE","parseSearchKeys","stripPrefix","removeMany","documentIds","wanted","pending","DELETE_BATCH","removeWhere","Object","UnsafeRemovalError","unindexed","includes","named","join","declared","removed","deleted","isFinite","countChunks","parseSearchTotal","search","topK","searchText","terms","tokenizeQuery","filterQuery","textQuery","startsWith","results","readId","total","total_results","readInfoField","readKeyValues","attribute","identifier","dim","toUpperCase","toLowerCase","entries","Buffer","from","Float32Array","buffer","clauses","alternation","escapeTag","match","replace","char","rawKeys","isBuffer","toString","scoreSource","stride","rawFields","attrs","inlineScore","toPassage","result","readAttributes","readScore","score","extra_attributes","rawId","vector_score","metadata_json","parsed","parse","describesRetrieval","value","Reflect","get","describeRetrieval","candidate","describeSource","base","retriever","_ignored","source","describeSharedSource","legs","sources","map","first","undefined","agrees","every","store","collection","EmbeddingRetriever","embedder","store","options","describeRetrieval","retriever","describeSource","retrieve","query","embedding","embed","undefined","passages","search","topK","filter","minScore","passage","score","KeywordRetriever","docs","Map","documentFrequency","totalLength","k1","b","options","describeRetrieval","retriever","size","add","records","record","removeChunk","id","tokens","tokenize","text","frequencies","token","set","get","term","keys","length","remove","documentId","documentIdOf","clear","existing","undefined","next","delete","retrieve","query","total","averageLength","queryTerms","Set","scored","values","filter","matchesFilter","metadata","score","termFrequency","df","idf","Math","log","denominator","push","source","sort","a","slice","topK","toLowerCase","match","LexicalRetriever","store","describeRetrieval","retriever","describeSource","retrieve","query","options","searchText","topK","filter","undefined","HybridRetriever","retrievers","options","describeRetrieval","retriever","describeSharedSource","retrieve","query","k","fetchTopK","weights","lists","Promise","all","map","topK","filter","undefined","fused","Map","forEach","list","listIndex","weight","passage","rank","contribution","existing","get","id","score","set","values","sort","a","b","slice","entry","RerankingRetriever","base","reranker","options","describeRetrieval","retriever","describeSource","retrieve","query","candidates","topK","fetchTopK","filter","undefined","rerank","FilteredRetriever","base","filter","describeRetrieval","retriever","describeSource","retrieve","query","options","chunkDocuments","documents","options","chunks","document","chunkText","text","forEach","index","push","id","source","undefined","metadata","ingestChunks","length","embeddings","embedder","embed","map","chunk","records","embedding","store","upsert","ingestDocuments","AsyncLocalStorage","channelName","emit","getChannel","RAG_DIAGNOSTIC_LIB","RAG_RETRIEVAL_EVENT","RAG_RETRIEVAL_CHANNEL","channelName","emitRagRetrieval","event","durationMs","emit","DEFAULT_TOP_K","inRetrieval","AsyncLocalStorage","round4","value","Math","round","scoreStats","passages","scores","map","passage","score","filter","Number","isFinite","length","sum","reduce","total","topScore","max","meanScore","InstrumentedRetriever","base","options","describeRetrieval","describe","retrieve","query","getChannel","hasSubscribers","getStore","descriptor","topK","startedAt","Date","now","run","retriever","store","undefined","collectionOf","chunks","zeroHit","failed","error","Error","message","String","collection","resolved","instrumentRetriever","isQueryInput","value","query","querySchema","version","vendor","validate","issues","message","createRetrievalTool","retriever","options","topK","telemetry","instrumented","instrumentRetriever","spec","name","kind","description","inputSchema","handler","execute","input","Error","passages","retrieve","undefined"]}
+{"version":3,"sources":["../src/chunk.ts","../src/vector-store.ts","../src/metadata-patch.ts","../src/filter.ts","../src/memory-vector-store.ts","../src/pg-vector-store.ts","../src/redis-vector-store.ts","../src/retrieval-descriptor.ts","../src/embedding-retriever.ts","../src/keyword-retriever.ts","../src/lexical-retriever.ts","../src/hybrid-retriever.ts","../src/reranking-retriever.ts","../src/filtered-retriever.ts","../src/ingest.ts","../src/retrieval-telemetry.ts","../src/retrieval-tool.ts"],"sourcesContent":["export interface ChunkOptions {\n  /** Target max characters per chunk. Default 800. */\n  chunkSize?: number;\n  /** Characters of overlap carried from the end of one chunk into the next. Default 100. */\n  overlap?: number;\n  /**\n   * Treat the text as records joined by this string, and never split one across chunks.\n   *\n   * Default chunking is structure-blind: it breaks at the *latest* paragraph/sentence/word boundary\n   * in the window, which for record-shaped text means a cut lands mid-record routinely. That is fine\n   * for prose, where the two halves are still sentences. It is not fine for a table flattened to one\n   * record per row, because the half that keeps the row identifier and the half that keeps the value\n   * end up in different chunks, and neither can answer a question about that row on its own.\n   *\n   * With a separator set, whole records are packed greedily up to `chunkSize` and a record is never\n   * cut — except one longer than `chunkSize`, which has nowhere to go and is character-split as\n   * usual, since no chunker can avoid that.\n   *\n   * `overlap` is IGNORED in this mode, deliberately. Overlap exists to rescue a sentence that a\n   * boundary cut in half; a boundary that never falls inside a record has nothing to rescue, and\n   * carrying the tail of the previous chunk in would duplicate whole records into neighbouring chunks\n   * — paying for the same rows twice at embedding time and letting one row match from two places.\n   *\n   * Measured on a 200-row spreadsheet flattened to one field-labelled record per row (15 columns,\n   * ~800-char budget): blind chunking left 27% of records split, and on questions targeting a field\n   * on the far side of such a cut, BM25 answered 54/66 (MRR 0.818) against 66/66 (MRR 1.000) with\n   * records kept whole. The dense leg scored 7/66 either way — 200 near-identical rows produce\n   * near-identical vectors, so that leg cannot do row lookup at all and chunking does not change it.\n   */\n  separator?: string;\n}\n\n/**\n * Splits text into overlapping chunks for embedding. Greedy up to `chunkSize`, but prefers to break\n * on a paragraph → sentence → word boundary in the back half of the window (so a chunk rarely cuts\n * mid-sentence), then carries `overlap` characters into the next chunk to preserve context across\n * the seam. Pure and deterministic.\n */\nexport function chunkText(text: string, options: ChunkOptions = {}): string[] {\n  const chunkSize = options.chunkSize ?? 800;\n  const overlap = options.overlap ?? 100;\n  const normalized = text.trim();\n  if (normalized.length === 0) {\n    return [];\n  }\n  if (options.separator !== undefined && options.separator.length > 0) {\n    return chunkByRecord(normalized, chunkSize, options.separator);\n  }\n  if (normalized.length <= chunkSize) {\n    return [normalized];\n  }\n\n  const chunks: string[] = [];\n  let start = 0;\n  while (start < normalized.length) {\n    const end = Math.min(start + chunkSize, normalized.length);\n    let breakAt = end;\n    if (end < normalized.length) {\n      const window = normalized.slice(start, end);\n      const boundary = Math.max(\n        window.lastIndexOf('\\n\\n'),\n        window.lastIndexOf('. '),\n        window.lastIndexOf(' '),\n      );\n      // Only honour a boundary in the back half, else a tiny chunk cascades.\n      if (boundary > chunkSize / 2) {\n        breakAt = start + boundary + 1;\n      }\n    }\n    const chunk = normalized.slice(start, breakAt).trim();\n    if (chunk.length > 0) {\n      chunks.push(chunk);\n    }\n    if (breakAt >= normalized.length) {\n      break;\n    }\n    // Step forward with overlap, but always make progress (guards against a stuck boundary).\n    start = Math.max(breakAt - overlap, start + 1);\n  }\n  return chunks;\n}\n\n/**\n * Pack whole records up to `chunkSize`, never splitting one. See {@link ChunkOptions.separator}.\n *\n * A record longer than the budget is handed to the blind chunker, which is the honest fallback: it is\n * the same splitting that would have happened anyway, and it is confined to the one record that could\n * not fit rather than applied to the whole document.\n */\nfunction chunkByRecord(text: string, chunkSize: number, separator: string): string[] {\n  const chunks: string[] = [];\n  let current = '';\n  const flush = (): void => {\n    if (current.length > 0) {\n      chunks.push(current);\n      current = '';\n    }\n  };\n  for (const record of text.split(separator)) {\n    const trimmed = record.trim();\n    if (trimmed.length === 0) {\n      continue;\n    }\n    if (trimmed.length > chunkSize) {\n      flush();\n      // `separator: undefined` on purpose — this is the blind path, for the one record that cannot\n      // fit whole. Overlap stays off so the fallback does not reintroduce duplication the mode exists\n      // to avoid.\n      chunks.push(...chunkText(trimmed, { chunkSize, overlap: 0 }));\n      continue;\n    }\n    const candidate = current.length > 0 ? `${current}${separator}${trimmed}` : trimmed;\n    if (candidate.length > chunkSize) {\n      flush();\n      current = trimmed;\n    } else {\n      current = candidate;\n    }\n  }\n  flush();\n  return chunks;\n}\n","import type { Passage } from '@dudousxd/nestjs-agent-core';\nimport type { MetadataPatch } from './metadata-patch.js';\n\n/** A stored, embedded chunk. `embedding` length must match the store's configured dimensions. */\nexport interface VectorRecord {\n  id: string;\n  text: string;\n  embedding: number[];\n  /** Citation-facing origin (document title, URL, row id). */\n  source?: string;\n  metadata?: Record<string, unknown>;\n}\n\nexport interface VectorSearchOptions {\n  topK: number;\n  /** Exact-match metadata filter (all keys must equal). Passed through from `RetrieveOptions.filter`. */\n  filter?: Record<string, unknown>;\n}\n\n/**\n * The write + search side of RAG storage. `@dudousxd/nestjs-agent-rag` ships `MemoryVectorStore`\n * (in-JS cosine, tests + small scale) and `PgVectorStore` (pgvector); any impl works. Pair one with\n * an `EmbeddingProvider` via {@link import('./embedding-retriever.js').EmbeddingRetriever} to get a\n * core `Retriever`.\n *\n * Every method here is **required**, the enumeration and bulk-deletion half included. The rule for\n * where a new method goes, so the next person adding one has it rather than inferring it from\n * precedent:\n *\n * - **Required, on this interface**, when every backend *can* implement it from what it already\n *   stores. {@link VectorStore.updateMetadata}, {@link VectorStore.listDocumentIds},\n *   {@link VectorStore.removeMany}, {@link VectorStore.removeWhere} and\n *   {@link VectorStore.countChunks} are CRUD over the records the store already holds — the same\n *   footing as {@link VectorStore.remove} and\n *   {@link VectorStore.listDocuments}. Making them optional would buy nothing but a permanent\n *   `if (supported)` at every call site plus an unreachable \"and if it isn't?\" branch.\n * - **Optional, in a capability interface**, when some backend genuinely *cannot* without\n *   infrastructure the consumer has to adopt. The only such capability today is\n *   {@link LexicalVectorStore.searchText}: RediSearch has BM25 natively, Postgres would need a\n *   `tsvector` column plus a GIN index plus a migration the consumer must run, and\n *   `MemoryVectorStore` would have to implement BM25 itself.\n *\n * The test is whether a backend can do it at all — not whether adding it would inconvenience an\n * implementer who has already shipped.\n *\n * Implementations MUST apply every filter with exactly the same semantics as\n * {@link VectorStore.search} — including the empty-array deny primitive — because the filter is\n * routinely an access-control boundary, not a hint. On {@link VectorStore.removeWhere} that is not a\n * correctness nicety but the single most destructive thing an implementation could get wrong.\n */\nexport interface VectorStore {\n  upsert(records: VectorRecord[]): Promise<void>;\n  search(embedding: number[], options: VectorSearchOptions): Promise<Passage[]>;\n  /**\n   * Delete every chunk belonging to a source document — all records whose id is `${documentId}`\n   * or `${documentId}#<n>` (the id scheme {@link import('./ingest.js').chunkDocuments} produces).\n   * Use it to drop a document from the index, and before re-ingesting one: `upsert` overwrites\n   * matching ids but can't remove chunks a shorter new version no longer produces, so a re-ingest\n   * without a preceding `remove` leaves the old tail orphaned.\n   */\n  remove(documentId: string): Promise<void>;\n  /**\n   * Rewrite a document's metadata **without touching its text or its embeddings** — the update path\n   * for a dimension that is genuinely mutable (which bases a document is relevant to, who may see it,\n   * what it was reclassified as) rather than derived from its content.\n   *\n   * Without this, a consumer whose documents get re-classified has exactly two options, and both are\n   * bad: re-embed the whole document — paying the model bill, and burning the ingestion budget, to\n   * change a string — or refuse to stamp the dimension onto chunks at all and resolve it at query\n   * time instead, which turns a filter the index could have applied into a join the caller has to.\n   *\n   * `patch` is applied to **every chunk** of the document (metadata is a document-level property that\n   * happens to be stored per chunk), with the merge semantics documented on {@link MetadataPatch}:\n   * partial merge, `null` to remove a key, `undefined` ignored, values — including arrays — replaced\n   * wholesale.\n   *\n   * Returns **the number of chunks written**. An unknown `documentId` updates nothing and returns\n   * `0`; it does not throw. That is deliberate and matches {@link VectorStore.remove}, which is\n   * likewise silent on a document that isn't there: this is a reconciliation-shaped API, called by a\n   * loop diffing a source of truth against the index, and such a loop races with ingestion and\n   * deletion by construction. Turning \"the document was removed between the diff and the write\" into\n   * an exception would make the ordinary case an error, and the caller would have to catch and\n   * swallow it to get back the behaviour it wanted. The count gives the same information without\n   * that: `0` means nothing was there. (An empty patch also writes nothing and returns `0` — the\n   * return counts chunks *written*, not chunks *matched*.)\n   *\n   * Implementations MUST keep every representation of the metadata in step. A store that keeps both\n   * a filterable projection and a returned blob (RediSearch's `meta_*` TAGs beside its\n   * `metadata_json`) and updates only one makes the store lie to itself: a chunk that *filters* as\n   * one value but *reports* another, where which half you notice depends on whether you searched or\n   * read.\n   */\n  updateMetadata(documentId: string, patch: MetadataPatch): Promise<number>;\n  /**\n   * List the distinct source documents currently indexed (chunk ids collapsed back to their document\n   * by stripping the trailing `#<n>`), each with a representative chunk's `metadata`, optionally\n   * narrowed by a metadata `filter`. The enumeration seam for reconciliation: diff this against your\n   * source of truth to find documents to ingest (missing), re-ingest (a stored fingerprint like\n   * `size` changed), or {@link VectorStore.remove remove} (orphaned).\n   */\n  listDocuments(filter?: Record<string, unknown>): Promise<IndexedDocument[]>;\n\n  /**\n   * Read one document's chunks back — id, text, metadata — ordered by their position in the\n   * document, optionally paged with `limit`/`offset`.\n   *\n   * The gap this closes is that **the text a store holds is otherwise write-only**. Every other way\n   * back to it is a ranked query: {@link VectorStore.search} needs an embedding,\n   * {@link LexicalVectorStore.searchText} needs a query string, and both return whatever *matched*,\n   * in relevance order, capped at `topK`. Neither can answer \"show me what was indexed for this\n   * document, in order\" — the question you ask when retrieval returns the wrong passage and you need\n   * to know whether the chunker cut badly or the retriever chose badly. Without this, the only way to\n   * see stored text is to reach around the adapter into the backing engine, which is exactly the\n   * abstraction break a consumer adopts a store to avoid.\n   *\n   * Document-scoped rather than filter-scoped, matching {@link VectorStore.remove} and\n   * {@link VectorStore.updateMetadata}: ordering is the whole point, and \"position within the\n   * document\" is only meaningful once a document has been picked. Enumerate documents with\n   * {@link VectorStore.listDocuments} first when you need to sweep.\n   *\n   * An unknown `documentId` yields `[]`; it does not throw, matching `remove` and `updateMetadata`.\n   *\n   * NOT an access-control seam. It takes no metadata `filter` and applies none, so it cannot enforce\n   * one — a caller that gates retrieval on a metadata field (tenant, audience, collection) MUST\n   * resolve that gate itself before calling, exactly as it would before `remove`. It is deliberately\n   * shaped for an operator/debug surface, not for serving end users.\n   */\n  listChunks(documentId: string, options?: ListChunksOptions): Promise<StoredChunk[]>;\n\n  /**\n   * The distinct source document ids currently indexed, optionally narrowed by a metadata `filter` —\n   * {@link VectorStore.listDocuments} without the metadata. Use it when you only need the id set (a\n   * reconciliation diff against your source of truth, a count, a delete list): implementations are\n   * expected to skip fetching and parsing per-chunk metadata entirely, which is most of the cost of\n   * `listDocuments` on a large corpus.\n   *\n   * An empty-array filter value denies, yielding `[]`.\n   */\n  listDocumentIds(filter?: Record<string, unknown>): Promise<string[]>;\n\n  /**\n   * Delete every chunk of every one of `documentIds`, with the same per-document semantics as\n   * {@link VectorStore.remove} — but as one bulk operation rather than N independent ones. An empty\n   * array is a no-op.\n   *\n   * The gap this closes is asymptotic, not cosmetic: on the Redis adapter each `remove` is a `SCAN`\n   * that walks the whole keyspace, which in a real deployment also holds queues, workflow state and\n   * the app cache. Two thousand documents is two thousand full passes; this is one filtered query.\n   */\n  removeMany(documentIds: string[]): Promise<void>;\n\n  /**\n   * Delete every chunk matching a metadata `filter`, and resolve the number of **chunks** removed\n   * (not documents). The collection-maintenance primitive: dropping a collection, evicting a tenant,\n   * purging a retired audience.\n   *\n   * Two guard rails, because this is the one method here that destroys data:\n   *\n   * - **The empty-array deny is honoured, and it means \"delete nothing\".** `removeWhere({ audience: [] })`\n   *   removes zero chunks. Treating a deny as \"no filter\" would delete the entire corpus, which is\n   *   exactly inverted from what the caller asked for.\n   * - **The filter must be non-empty.** `removeWhere({})` throws {@link UnsafeRemovalError} rather\n   *   than wiping the store, because an empty object is overwhelmingly more likely to be a filter that\n   *   got built wrong (a dropped key, an `undefined` scope) than a deliberate request to delete\n   *   everything. Deliberate mass deletion stays available and stays explicit:\n   *   `removeMany(await store.listDocumentIds())`, or the backend's own drop.\n   *\n   * What it removes is exactly what a {@link VectorStore.search} carrying the same filter could\n   * reach — no more (it cannot escape the filter) and no less.\n   */\n  removeWhere(filter: Record<string, unknown>): Promise<number>;\n\n  /**\n   * How many **chunks** match `filter` (all of them when it is omitted) — a counted query, without\n   * transferring the chunks. Sizing a reindex, reporting a collection's footprint, and confirming a\n   * {@link VectorStore.removeWhere} did what you expected. An empty-array filter value denies,\n   * yielding `0`.\n   */\n  countChunks(filter?: Record<string, unknown>): Promise<number>;\n}\n\n/**\n * An **optional** capability a {@link VectorStore} may also implement: full-text (lexical) search\n * over the chunk text it already stores, using the backing engine's own keyword index — RediSearch's\n * BM25 over the `TEXT` field, say. Its point is the multi-process deployment: when ingestion runs on\n * a worker and search runs on an API pod, the API process never sees the chunks, so the in-process\n * {@link import('./keyword-retriever.js').KeywordRetriever} has nothing to index. A store that\n * implements this needs no second index, no corpus in JS heap, and no refresh window — a chunk is\n * lexically findable the moment it is upserted.\n *\n * Wrap it as a core `Retriever` with {@link import('./lexical-retriever.js').LexicalRetriever}.\n *\n * Implementations MUST apply `options.filter` with exactly the same semantics as\n * {@link VectorStore.search} — including the empty-array deny primitive — because the filter is\n * routinely an access-control boundary, not a hint.\n */\nexport interface LexicalVectorStore extends VectorStore {\n  /**\n   * Rank stored chunks against a natural-language `query` by keyword relevance. `options.filter`\n   * narrows exactly as in {@link VectorStore.search}. The returned `score` is the engine's own\n   * relevance score (BM25), which shares no scale with `search`'s cosine similarity — fuse the two\n   * with {@link import('./hybrid-retriever.js').HybridRetriever}, whose RRF is rank-based and so\n   * needs no common scale.\n   */\n  searchText(query: string, options: VectorSearchOptions): Promise<Passage[]>;\n}\n\n/**\n * Does this store carry the optional {@link LexicalVectorStore} capability? Lets a consumer pick the\n * store-backed lexical leg when available and fall back to `KeywordRetriever` (or to dense-only)\n * when it is not, without knowing which adapter it was handed.\n */\nexport function isLexicalVectorStore(store: VectorStore): store is LexicalVectorStore {\n  return typeof (store as Partial<LexicalVectorStore>).searchText === 'function';\n}\n\n/**\n * A destructive call was refused because its scope could not be trusted. Thrown by\n * {@link VectorStore.removeWhere} — never for something that merely matched nothing (that\n * is a legitimate result of `0`), only for a filter that would have deleted *more* than the caller\n * plausibly meant.\n */\nexport class UnsafeRemovalError extends Error {\n  constructor(\n    /** Why the removal was refused. */\n    readonly reason: 'empty-filter' | 'unindexed-field',\n    message: string,\n  ) {\n    super(message);\n    this.name = 'UnsafeRemovalError';\n  }\n}\n\n/** A distinct source document as seen by the index — its id plus a representative chunk's metadata. */\nexport interface IndexedDocument {\n  id: string;\n  metadata?: Record<string, unknown>;\n}\n\n/** One stored chunk, read back verbatim — what {@link VectorStore.listChunks} yields. */\nexport interface StoredChunk {\n  /** The chunk id: `${documentId}#<n>`, or the bare document id for a single-chunk document. */\n  id: string;\n  /** Zero-based position within the document, parsed from the id. A bare id is chunk `0`. */\n  index: number;\n  /** The chunk text as it was indexed — the exact string the embedding was computed from. */\n  text: string;\n  metadata?: Record<string, unknown>;\n}\n\n/** Paging for {@link VectorStore.listChunks}. Omit both to read the whole document. */\nexport interface ListChunksOptions {\n  /** Max chunks to return, applied after ordering by {@link StoredChunk.index}. */\n  limit?: number;\n  /** Chunks to skip, applied after ordering. */\n  offset?: number;\n}\n\n/** Chunk `n` of `${documentId}#<n>`; a bare document id (single-chunk document) is `0`. */\nexport function chunkIndexOf(chunkId: string): number {\n  const match = /#(\\d+)$/.exec(chunkId);\n  return match?.[1] === undefined ? 0 : Number(match[1]);\n}\n\n/** Collapse a chunk id (`${documentId}#<n>`) back to its source document id. */\nexport function documentIdOf(chunkId: string): string {\n  return chunkId.replace(/#\\d+$/, '');\n}\n","/**\n * A partial update to a document's metadata, as taken by\n * {@link import('./vector-store.js').VectorStore.updateMetadata}. Deliberately *partial*: the useful\n * shape is \"this one dimension was reclassified\", not \"here is the whole metadata object again\" —\n * a caller that had the whole object would have to reconstruct fields it does not own (the ingestion\n * fingerprint, the source, the mime type) just to change one string, and would silently drop them\n * the day the library adds another.\n *\n * The semantics are RFC 7386 (JSON Merge Patch), with one deliberate narrowing:\n *\n * - **Merge, not replace.** Keys present in the patch are written; keys absent from it keep their\n *   stored value.\n * - **`null` removes the key.** That is the RFC's sentinel and it is the *only* way to remove one.\n *   The consequence — a literal `null` cannot be stored as a value — is intended: metadata is a\n *   filter surface, and \"the key is absent\" and \"the key is null\" would filter identically anyway.\n * - **`undefined` is ignored** — the key is left exactly as stored, as if the patch had not mentioned\n *   it. `undefined` does not survive `JSON.stringify`, and a patch routinely crosses a JSON boundary\n *   (an HTTP body, a durable-workflow step payload) on its way here; honouring it would make\n *   `{ audience: undefined }` mean *delete* on one side of that boundary and *no-op* on the other.\n *   It is also what `{ ...doc, audience: doc.audience }` produces by accident, and an accidental\n *   deletion of an access-control dimension is the worst outcome this API can have. Removing a key\n *   is therefore always spelled `null`.\n * - **Shallow.** A value replaces wholesale; it is not merged into the stored value. This is the\n *   narrowing versus RFC 7386, which recurses into nested objects. It matters most for **arrays**,\n *   where wholesale replacement is certainly what a caller means: `{ bases: ['A', 'C'] }` sets the\n *   document's bases to exactly A and C — it does not append to, or union with, what was there. An\n *   array-valued key is a *set-valued dimension* (the multi-valued TAG a store filters on), and the\n *   only sane way to shrink such a set is to state the new one.\n */\nexport type MetadataPatch = Record<string, unknown>;\n\n/**\n * Split a patch into the assignments it makes and the keys it removes — the shape a store that\n * updates metadata declaratively (SQL, a hash write + field delete) needs, since setting and\n * unsetting are different operations there. `undefined` values appear in neither.\n */\nexport function splitMetadataPatch(patch: MetadataPatch): {\n  set: Record<string, unknown>;\n  remove: string[];\n} {\n  const set: Record<string, unknown> = {};\n  const remove: string[] = [];\n  for (const [key, value] of Object.entries(patch)) {\n    if (value === null) {\n      remove.push(key);\n    } else if (value !== undefined) {\n      set[key] = value;\n    }\n  }\n  return { set, remove };\n}\n\n/** Does this patch write anything at all? An empty (or all-`undefined`) patch is a no-op. */\nexport function isEmptyMetadataPatch(patch: MetadataPatch): boolean {\n  const { set, remove } = splitMetadataPatch(patch);\n  return Object.keys(set).length === 0 && remove.length === 0;\n}\n\n/**\n * Apply a {@link MetadataPatch} to a document's stored metadata, returning a NEW object — the\n * reference implementation of the semantics documented on `MetadataPatch`, so every adapter that\n * merges in JS agrees with every other one. Never mutates its input: `MemoryVectorStore` hands out\n * the very object a caller upserted, and quietly rewriting it under them would be a surprise no\n * other store reproduces.\n */\nexport function applyMetadataPatch(\n  metadata: Record<string, unknown> | undefined,\n  patch: MetadataPatch,\n): Record<string, unknown> {\n  const { set, remove } = splitMetadataPatch(patch);\n  const next: Record<string, unknown> = { ...metadata, ...set };\n  for (const key of remove) {\n    delete next[key];\n  }\n  return next;\n}\n","/** Metadata filter, shared by the in-memory {@link import('./memory-vector-store.js').MemoryVectorStore}\n * and {@link import('./keyword-retriever.js').KeywordRetriever}. Every key must match:\n *\n * - a **scalar** filter value keeps exact-match — the record's value must equal it;\n * - an **array** filter value means **match-any** (OR / set membership) — the record matches when its\n *   value for that key is one of them, or (for a multi-valued record) shares at least one element.\n *   An empty array matches nothing (no value is a member of the empty set) — the deny primitive.\n *\n * Array-valued filters are how a caller expresses capability-style access control over a shared store\n * (e.g. `{ audience: ['public', 'role:ADMIN', 'base:…'] }`) without the store knowing what a token means.\n */\nexport function matchesFilter(\n  metadata: Record<string, unknown> | undefined,\n  filter: Record<string, unknown>,\n): boolean {\n  const entries = Object.entries(filter);\n  if (metadata === undefined) {\n    return entries.length === 0;\n  }\n  return entries.every(([key, expected]) => {\n    if (Array.isArray(expected)) {\n      const actual = metadata[key];\n      return Array.isArray(actual)\n        ? actual.some((value) => expected.includes(value))\n        : expected.includes(actual);\n    }\n    return metadata[key] === expected;\n  });\n}\n\n/**\n * Does this filter provably match **nothing**? True when any key carries an empty array, because\n * nothing is a member of the empty set and every key must match (AND). This is the package's **deny\n * primitive** — the shape a capability-style ACL collapses to for an actor holding no tokens — so\n * every store has to honour it identically, and a store that cannot express \"match nothing\" in its\n * query language (RediSearch has no valid empty-tag syntax) must short-circuit on it instead.\n *\n * It is exported from this module rather than reimplemented per adapter precisely because getting it\n * wrong is *silent*: a read path that ignores it over-returns, and a **write** path that ignores it\n * (see {@link import('./vector-store.js').VectorStore.removeWhere}) deletes the corpus a\n * deny was supposed to protect.\n */\nexport function filterMatchesNothing(filter?: Record<string, unknown>): boolean {\n  if (filter === undefined) {\n    return false;\n  }\n  return Object.values(filter).some((value) => Array.isArray(value) && value.length === 0);\n}\n","import type { Passage } from '@dudousxd/nestjs-agent-core';\nimport { filterMatchesNothing, matchesFilter } from './filter.js';\nimport { type MetadataPatch, applyMetadataPatch, isEmptyMetadataPatch } from './metadata-patch.js';\nimport type { RetrievalDescriptor } from './retrieval-descriptor.js';\nimport {\n  type IndexedDocument,\n  type ListChunksOptions,\n  type StoredChunk,\n  UnsafeRemovalError,\n  type VectorRecord,\n  type VectorSearchOptions,\n  type VectorStore,\n  chunkIndexOf,\n  documentIdOf,\n} from './vector-store.js';\n\n/**\n * An in-process {@link VectorStore} — cosine similarity over a Map, no infra. The reference adapter\n * for tests and small/embedded corpora; for production scale use `PgVectorStore` (or your own).\n *\n * It implements the enumeration and bulk-deletion half of {@link VectorStore} too. There is no\n * performance argument for it here — every method below is a loop over the same Map — but a store that tests are\n * written against has to behave identically to the one production runs, and the semantics that matter\n * (`removeWhere` refusing an empty filter, an empty-array filter deleting nothing) are behavioural,\n * not incidental to Redis.\n */\nexport class MemoryVectorStore implements VectorStore {\n  private readonly records = new Map<string, VectorRecord>();\n\n  /**\n   * Telemetry self-description. No `collection`: there is no namespace to name — the corpus IS this\n   * instance, and two `MemoryVectorStore`s in one process are two corpora with nothing to tell them\n   * apart on a dashboard.\n   */\n  describeRetrieval(): RetrievalDescriptor {\n    return { store: 'memory' };\n  }\n\n  async upsert(records: VectorRecord[]): Promise<void> {\n    for (const record of records) {\n      this.records.set(record.id, record);\n    }\n  }\n\n  async remove(documentId: string): Promise<void> {\n    for (const id of this.records.keys()) {\n      if (documentIdOf(id) === documentId) {\n        this.records.delete(id);\n      }\n    }\n  }\n\n  /**\n   * Merge `patch` into every chunk of `documentId`, leaving `text` and `embedding` untouched. The\n   * record is *replaced* rather than mutated: `upsert` stores the caller's own object, and patching\n   * it in place would edit an object the caller still holds — a surprise no out-of-process store\n   * could reproduce, and therefore one this reference adapter must not teach.\n   */\n  async updateMetadata(documentId: string, patch: MetadataPatch): Promise<number> {\n    if (isEmptyMetadataPatch(patch)) {\n      return 0;\n    }\n    let updated = 0;\n    for (const [id, record] of this.records) {\n      if (documentIdOf(id) !== documentId) {\n        continue;\n      }\n      this.records.set(id, { ...record, metadata: applyMetadataPatch(record.metadata, patch) });\n      updated += 1;\n    }\n    return updated;\n  }\n\n  async listDocuments(filter?: Record<string, unknown>): Promise<IndexedDocument[]> {\n    const documents = new Map<string, IndexedDocument>();\n    for (const record of this.records.values()) {\n      if (filter !== undefined && !matchesFilter(record.metadata, filter)) {\n        continue;\n      }\n      const id = documentIdOf(record.id);\n      if (!documents.has(id)) {\n        documents.set(id, {\n          id,\n          ...(record.metadata !== undefined ? { metadata: record.metadata } : {}),\n        });\n      }\n    }\n    return [...documents.values()];\n  }\n\n  /**\n   * The chunks of one document, in document order. See {@link VectorStore.listChunks}.\n   *\n   * Insertion order is not document order — `upsert` stores whatever the caller passed, and a\n   * re-ingest that rewrites chunk 3 alone moves it to the end of the Map. So this sorts by the index\n   * parsed from the id, the same thing the SQL and Redis adapters order by, rather than trusting the\n   * Map. A reference adapter that returned \"usually ordered\" would let a consumer ship a bug that\n   * only shows up on the store tests are NOT written against.\n   */\n  async listChunks(documentId: string, options?: ListChunksOptions): Promise<StoredChunk[]> {\n    const chunks: StoredChunk[] = [];\n    for (const record of this.records.values()) {\n      if (documentIdOf(record.id) !== documentId) {\n        continue;\n      }\n      chunks.push({\n        id: record.id,\n        index: chunkIndexOf(record.id),\n        text: record.text,\n        ...(record.metadata !== undefined ? { metadata: record.metadata } : {}),\n      });\n    }\n    chunks.sort((a, b) => a.index - b.index);\n    const offset = options?.offset ?? 0;\n    return options?.limit === undefined\n      ? chunks.slice(offset)\n      : chunks.slice(offset, offset + options.limit);\n  }\n\n  async listDocumentIds(filter?: Record<string, unknown>): Promise<string[]> {\n    if (filterMatchesNothing(filter)) {\n      return [];\n    }\n    const documents = new Set<string>();\n    for (const record of this.records.values()) {\n      if (filter !== undefined && !matchesFilter(record.metadata, filter)) {\n        continue;\n      }\n      documents.add(documentIdOf(record.id));\n    }\n    return [...documents];\n  }\n\n  async removeMany(documentIds: string[]): Promise<void> {\n    if (documentIds.length === 0) {\n      return;\n    }\n    const wanted = new Set(documentIds);\n    for (const id of this.records.keys()) {\n      if (wanted.has(documentIdOf(id))) {\n        this.records.delete(id);\n      }\n    }\n  }\n\n  /**\n   * See {@link VectorStore.removeWhere}. The empty-array short-circuit below is redundant\n   * against `matchesFilter` (which already matches nothing for an empty array) and is kept anyway:\n   * this is the method where \"the filter accidentally means everything\" destroys data, so the deny is\n   * stated where a reader can see it rather than inferred from another module's truth table.\n   */\n  async removeWhere(filter: Record<string, unknown>): Promise<number> {\n    if (Object.keys(filter).length === 0) {\n      throw new UnsafeRemovalError(\n        'empty-filter',\n        'removeWhere() refuses an empty filter: it would delete every chunk in the store. ' +\n          'Pass a filter that scopes the removal, or delete deliberately with ' +\n          'removeMany(await store.listDocumentIds()).',\n      );\n    }\n    if (filterMatchesNothing(filter)) {\n      return 0;\n    }\n    let removed = 0;\n    for (const [id, record] of this.records) {\n      if (matchesFilter(record.metadata, filter)) {\n        this.records.delete(id);\n        removed += 1;\n      }\n    }\n    return removed;\n  }\n\n  async countChunks(filter?: Record<string, unknown>): Promise<number> {\n    if (filterMatchesNothing(filter)) {\n      return 0;\n    }\n    let count = 0;\n    for (const record of this.records.values()) {\n      if (filter === undefined || matchesFilter(record.metadata, filter)) {\n        count += 1;\n      }\n    }\n    return count;\n  }\n\n  async search(embedding: number[], options: VectorSearchOptions): Promise<Passage[]> {\n    const scored: Passage[] = [];\n    for (const record of this.records.values()) {\n      if (options.filter !== undefined && !matchesFilter(record.metadata, options.filter)) {\n        continue;\n      }\n      scored.push({\n        id: record.id,\n        text: record.text,\n        score: cosineSimilarity(embedding, record.embedding),\n        ...(record.source !== undefined ? { source: record.source } : {}),\n        ...(record.metadata !== undefined ? { metadata: record.metadata } : {}),\n      });\n    }\n    return scored.sort((a, b) => b.score - a.score).slice(0, options.topK);\n  }\n}\n\nfunction cosineSimilarity(a: number[], b: number[]): number {\n  let dot = 0;\n  let normA = 0;\n  let normB = 0;\n  const length = Math.min(a.length, b.length);\n  for (let index = 0; index < length; index += 1) {\n    const valueA = a[index] ?? 0;\n    const valueB = b[index] ?? 0;\n    dot += valueA * valueB;\n    normA += valueA * valueA;\n    normB += valueB * valueB;\n  }\n  const denominator = Math.sqrt(normA) * Math.sqrt(normB);\n  return denominator === 0 ? 0 : dot / denominator;\n}\n","import type { Passage } from '@dudousxd/nestjs-agent-core';\nimport { filterMatchesNothing } from './filter.js';\nimport { type MetadataPatch, isEmptyMetadataPatch, splitMetadataPatch } from './metadata-patch.js';\nimport type { RetrievalDescriptor } from './retrieval-descriptor.js';\nimport type {\n  IndexedDocument,\n  ListChunksOptions,\n  StoredChunk,\n  VectorRecord,\n  VectorSearchOptions,\n  VectorStore,\n} from './vector-store.js';\nimport { UnsafeRemovalError } from './vector-store.js';\n\n/**\n * The minimal Postgres surface {@link PgVectorStore} needs — adapt your own `pg` / `postgres.js`\n * client to it, so this package pulls in NO driver (bring your own, like the store adapters take an\n * ORM handle and the Redis transport takes a client). `query` runs parameterized SQL (`$1,$2,…`) and\n * resolves the result rows.\n */\nexport interface PgClient {\n  query<Row = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<Row[]>;\n}\n\nexport interface PgVectorStoreOptions {\n  /** Table name. Default `agent_rag_chunks`. */\n  table?: string;\n  /** Embedding width — must match your model (e.g. 1536 for text-embedding-3-small). Default 1536. */\n  dimensions?: number;\n}\n\n/** The one byte Postgres `text`/`jsonb` columns refuse outright. */\nconst NUL_BYTE = String.fromCharCode(0);\n\n/**\n * Strip the NUL byte (U+0000) out of a value before it reaches Postgres. `text` and `jsonb` columns\n * reject it outright — `invalid byte sequence for encoding \"UTF8\": 0x00` — and text extracted from\n * PDFs occasionally carries one even though other stores (Qdrant) accept it happily, so a chunk that\n * ingested fine elsewhere can fail here. Strings have the byte removed; arrays and **plain** objects\n * are walked recursively (object keys included, since a NUL can land in a metadata key too).\n *\n * \"Plain\" is deliberately narrow — `Object.getPrototypeOf(value)` must be `Object.prototype` or\n * `null` — so a `Date`, a `Buffer`, a class instance or any other non-plain object passes through\n * untouched rather than collapsing to `{}` via a blind `Object.entries`. Rebuilt objects go through\n * `Object.fromEntries` rather than assignment into a fresh `{}`, so a metadata key literally named\n * `__proto__` becomes an ordinary own property instead of silently repointing the result's prototype.\n */\nfunction stripNulBytes<T>(value: T): T {\n  if (typeof value === 'string') {\n    return (value.includes(NUL_BYTE) ? value.split(NUL_BYTE).join('') : value) as unknown as T;\n  }\n  if (Array.isArray(value)) {\n    return value.map((item) => stripNulBytes(item)) as unknown as T;\n  }\n  if (value !== null && typeof value === 'object') {\n    const proto = Object.getPrototypeOf(value);\n    if (proto !== Object.prototype && proto !== null) {\n      return value;\n    }\n    return Object.fromEntries(\n      Object.entries(value as Record<string, unknown>).map(([key, entry]) => [\n        stripNulBytes(key),\n        stripNulBytes(entry),\n      ]),\n    ) as unknown as T;\n  }\n  return value;\n}\n\n/**\n * A pgvector-backed {@link VectorStore} — the production reference adapter. Cosine distance via the\n * `<=>` operator over an HNSW index; metadata in a `jsonb` column filtered with `@>`. Call\n * {@link PgVectorStore.ensureSchema} once at boot to create the extension, table, and index.\n *\n * This store does **not** implement the optional\n * {@link import('./vector-store.js').LexicalVectorStore} capability, unlike\n * {@link import('./redis-vector-store.js').RedisVectorStore}. That is a deliberate omission, not an\n * oversight: RediSearch already indexes the chunk text (the schema declares it `TEXT`), so BM25 is\n * free there, whereas the table below indexes nothing lexically — `text` is a plain column with no\n * `tsvector` and no GIN index. Adding one is not a transparent upgrade:\n *\n * - it is new DDL in `ensureSchema`, and `CREATE INDEX` (non-concurrently, as this method must, since\n *   `CONCURRENTLY` cannot run in a transaction) takes a write lock on an already-populated chunks\n *   table — a boot-time stall proportional to corpus size for every existing deployment;\n * - it forces a text-search-configuration choice (`english` vs `simple` vs …) that must match between\n *   the index expression and every query, or Postgres silently ignores the index and sequentially\n *   scans the corpus — a failure mode that stays *correct* while quietly getting slower with scale.\n *\n * Both want a migration a consumer runs and observes, not a side effect of upgrading the library. The\n * capability interface is open, so a `PgLexicalVectorStore` (or an option here, gated on an\n * explicitly-created index) can be added later without changing anything else.\n *\n * The enumeration and bulk-deletion methods {@link VectorStore} requires need nothing new here,\n * unlike the lexical capability above: enumeration and bulk deletion are `DISTINCT`, `= ANY($1)`, `DELETE … WHERE`\n * and `count(*)` over the table and index that already exist. No DDL, no boot-time lock, no migration.\n */\nexport class PgVectorStore implements VectorStore {\n  private readonly table: string;\n  private readonly dimensions: number;\n\n  constructor(\n    private readonly client: PgClient,\n    options: PgVectorStoreOptions = {},\n  ) {\n    this.table = options.table ?? 'agent_rag_chunks';\n    this.dimensions = options.dimensions ?? 1536;\n  }\n\n  /** Telemetry self-description — the table is the namespace a retrieval was served from. */\n  describeRetrieval(): RetrievalDescriptor {\n    return { store: 'pg', collection: this.table };\n  }\n\n  /** Idempotent DDL: the `vector` extension, the chunks table, and the cosine HNSW index. */\n  async ensureSchema(): Promise<void> {\n    await this.client.query('CREATE EXTENSION IF NOT EXISTS vector');\n    await this.client.query(\n      `CREATE TABLE IF NOT EXISTS ${this.table} (\n        id TEXT PRIMARY KEY,\n        text TEXT NOT NULL,\n        source TEXT,\n        metadata JSONB,\n        embedding vector(${this.dimensions}) NOT NULL\n      )`,\n    );\n    await this.client.query(\n      `CREATE INDEX IF NOT EXISTS ${this.table}_embedding_idx\n        ON ${this.table} USING hnsw (embedding vector_cosine_ops)`,\n    );\n  }\n\n  async upsert(records: VectorRecord[]): Promise<void> {\n    for (const record of records) {\n      // Postgres rejects the NUL byte in text/jsonb — see stripNulBytes.\n      const id = stripNulBytes(record.id);\n      const text = stripNulBytes(record.text);\n      const source = record.source !== undefined ? stripNulBytes(record.source) : undefined;\n      const metadata = record.metadata !== undefined ? stripNulBytes(record.metadata) : undefined;\n      await this.client.query(\n        `INSERT INTO ${this.table} (id, text, source, metadata, embedding)\n         VALUES ($1, $2, $3, $4, $5)\n         ON CONFLICT (id) DO UPDATE SET\n           text = EXCLUDED.text,\n           source = EXCLUDED.source,\n           metadata = EXCLUDED.metadata,\n           embedding = EXCLUDED.embedding`,\n        [\n          id,\n          text,\n          source ?? null,\n          metadata !== undefined ? JSON.stringify(metadata) : null,\n          toVectorLiteral(record.embedding),\n        ],\n      );\n    }\n  }\n\n  async remove(documentId: string): Promise<void> {\n    // Stripped so it matches the id `upsert` actually stored, and so a NUL-bearing id can't 0x00\n    // the DELETE itself.\n    await this.client.query(`DELETE FROM ${this.table} WHERE ${DOCUMENT_ID_FROM_CHUNK} = $1`, [\n      stripNulBytes(documentId),\n    ]);\n  }\n\n  /**\n   * Rewrite a document's metadata without re-embedding it. See {@link VectorStore.updateMetadata}\n   * for the semantics; here the whole thing is one statement, because jsonb already *is* the merge:\n   * `||` is a shallow key-wise merge (right side wins, arrays replaced wholesale — precisely\n   * {@link MetadataPatch}) and `- text[]` drops the keys the patch removed. `COALESCE` covers a chunk\n   * ingested with no metadata at all, so a patch can create the object rather than no-op on `NULL`.\n   *\n   * Unlike RediSearch there is no second representation to keep in step — the `metadata` column is\n   * both what `search` filters on and what it returns — so the correctness trap the Redis adapter has\n   * to work for simply does not exist here. `RETURNING id` is what supplies the chunk count, since\n   * {@link PgClient} is a rows-only surface with no `rowCount`.\n   */\n  async updateMetadata(documentId: string, patch: MetadataPatch): Promise<number> {\n    if (isEmptyMetadataPatch(patch)) {\n      return 0;\n    }\n    // Postgres rejects the NUL byte in text/jsonb — see stripNulBytes. `documentId` too, so it\n    // matches the id `upsert` actually stored.\n    const { set, remove } = splitMetadataPatch(stripNulBytes(patch));\n    const rows = await this.client.query<{ id: string }>(\n      `UPDATE ${this.table}\n          SET metadata = (COALESCE(metadata, '{}'::jsonb) || $2::jsonb) - $3::text[]\n        WHERE ${DOCUMENT_ID_FROM_CHUNK} = $1\n        RETURNING id`,\n      [stripNulBytes(documentId), JSON.stringify(set), remove],\n    );\n    return rows.length;\n  }\n\n  async listDocuments(filter?: Record<string, unknown>): Promise<IndexedDocument[]> {\n    const where = buildWhere(filter, 1);\n    // DISTINCT ON collapses chunks to one row per document; all chunks share the doc's metadata.\n    const rows = await this.client.query<{\n      doc_id: string;\n      metadata: Record<string, unknown> | null;\n    }>(\n      `SELECT DISTINCT ON (${DOCUMENT_ID_FROM_CHUNK}) ${DOCUMENT_ID_FROM_CHUNK} AS doc_id, metadata\n       FROM ${this.table}\n       ${where.sql}\n       ORDER BY ${DOCUMENT_ID_FROM_CHUNK}`,\n      where.params,\n    );\n    return rows.map((row) => ({\n      id: row.doc_id,\n      ...(row.metadata !== null ? { metadata: row.metadata } : {}),\n    }));\n  }\n\n  /**\n   * The chunks of one document, in document order. See {@link VectorStore.listChunks}.\n   *\n   * The order is computed from the id rather than stored: `#12` must sort after `#2`, which a plain\n   * `ORDER BY id` gets wrong on every document past ten chunks because it compares text. So the\n   * trailing number is extracted and cast to `int`, and a bare id (a single-chunk document, which\n   * carries no `#n` suffix) collapses to `0` — the same rule `chunkIndexOf` applies in the other two\n   * adapters.\n   *\n   * `embedding` is left out of the projection: it is the widest column in the table and useless to a\n   * caller reading text back.\n   */\n  async listChunks(documentId: string, options?: ListChunksOptions): Promise<StoredChunk[]> {\n    // Stripped so it matches the id `upsert` actually stored.\n    const params: unknown[] = [stripNulBytes(documentId)];\n    let sql = `SELECT id, ${CHUNK_INDEX_FROM_ID} AS chunk_index, text, metadata\n       FROM ${this.table}\n       WHERE ${DOCUMENT_ID_FROM_CHUNK} = $1\n       ORDER BY chunk_index`;\n    if (options?.limit !== undefined) {\n      params.push(options.limit);\n      sql += ` LIMIT $${params.length}`;\n    }\n    if (options?.offset !== undefined) {\n      params.push(options.offset);\n      sql += ` OFFSET $${params.length}`;\n    }\n    const rows = await this.client.query<{\n      id: string;\n      chunk_index: number;\n      text: string;\n      metadata: Record<string, unknown> | null;\n    }>(sql, params);\n    return rows.map((row) => ({\n      id: row.id,\n      index: Number(row.chunk_index),\n      text: row.text,\n      ...(row.metadata !== null ? { metadata: row.metadata } : {}),\n    }));\n  }\n\n  /** {@link listDocuments} without the metadata: one `DISTINCT` over the derived document id. */\n  async listDocumentIds(filter?: Record<string, unknown>): Promise<string[]> {\n    if (filterMatchesNothing(filter)) {\n      return [];\n    }\n    const where = buildWhere(filter, 1);\n    const rows = await this.client.query<{ doc_id: string }>(\n      `SELECT DISTINCT ${DOCUMENT_ID_FROM_CHUNK} AS doc_id\n       FROM ${this.table}\n       ${where.sql}\n       ORDER BY doc_id`,\n      where.params,\n    );\n    return rows.map((row) => row.doc_id);\n  }\n\n  /** N documents in one statement — the set-based form of {@link PgVectorStore.remove}. */\n  async removeMany(documentIds: string[]): Promise<void> {\n    if (documentIds.length === 0) {\n      return;\n    }\n    // Stripped so every id matches what `upsert` actually stored.\n    await this.client.query(\n      `DELETE FROM ${this.table} WHERE ${DOCUMENT_ID_FROM_CHUNK} = ANY($1::text[])`,\n      [stripNulBytes(documentIds)],\n    );\n  }\n\n  /**\n   * See {@link VectorStore.removeWhere}: empty filter object throws, empty-array value\n   * deletes nothing. The count comes from `RETURNING id` rather than a driver-specific `rowCount`,\n   * because {@link PgClient} is deliberately just \"run SQL, get rows\".\n   */\n  async removeWhere(filter: Record<string, unknown>): Promise<number> {\n    if (Object.keys(filter).length === 0) {\n      throw new UnsafeRemovalError(\n        'empty-filter',\n        'removeWhere() refuses an empty filter: it would delete every chunk in the table. ' +\n          'Pass a filter that scopes the removal, or delete deliberately with ' +\n          'removeMany(await store.listDocumentIds()).',\n      );\n    }\n    // Redundant with buildWhere's `false` clause, and stated anyway — the deny primitive should be\n    // visible at the destructive call site, not one indirection away.\n    if (filterMatchesNothing(filter)) {\n      return 0;\n    }\n    const where = buildWhere(filter, 1);\n    const rows = await this.client.query<{ id: string }>(\n      `DELETE FROM ${this.table} ${where.sql} RETURNING id`,\n      where.params,\n    );\n    return rows.length;\n  }\n\n  async countChunks(filter?: Record<string, unknown>): Promise<number> {\n    if (filterMatchesNothing(filter)) {\n      return 0;\n    }\n    const where = buildWhere(filter, 1);\n    const rows = await this.client.query<{ count: number | string }>(\n      `SELECT count(*)::int AS count FROM ${this.table} ${where.sql}`,\n      where.params,\n    );\n    return Number(rows[0]?.count ?? 0);\n  }\n\n  async search(embedding: number[], options: VectorSearchOptions): Promise<Passage[]> {\n    const vector = toVectorLiteral(embedding);\n    // $1 = query vector, $2 = topK; metadata-filter params start at $3.\n    const where = buildWhere(options.filter, 3);\n    const rows = await this.client.query<PgRow>(\n      `SELECT id, text, source, metadata, 1 - (embedding <=> $1::vector) AS score\n       FROM ${this.table}\n       ${where.sql}\n       ORDER BY embedding <=> $1::vector\n       LIMIT $2`,\n      [vector, options.topK, ...where.params],\n    );\n    return rows.map((row) => ({\n      id: row.id,\n      text: row.text,\n      score: Number(row.score),\n      ...(row.source !== null ? { source: row.source } : {}),\n      ...(row.metadata !== null ? { metadata: row.metadata } : {}),\n    }));\n  }\n}\n\ninterface PgRow {\n  id: string;\n  text: string;\n  source: string | null;\n  metadata: Record<string, unknown> | null;\n  score: number | string;\n}\n\n/**\n * Build the `WHERE` fragment for a metadata `filter`, with parameter placeholders numbered from\n * `startIndex`. Scalar values collapse into a single `@>` jsonb-containment check (exact-match, as\n * before). An **array** value is a **match-any** (OR / set membership) check via jsonb `?|`: the\n * record matches when its value for that key — scalar or array — shares an element with the filter\n * array. An empty array can never match (deny primitive). Keys are passed as parameters (`metadata->$k`)\n * so a caller-supplied metadata key can't inject SQL. Returns `{ sql: '', params: [] }` when there is\n * no filter, preserving the previous unfiltered query shape.\n *\n * The filter is run through {@link stripNulBytes} up front: both the keys (bound as `$k` params) and\n * the scalar/array values end up as query bindings, and a caller-supplied filter is exactly as\n * capable of carrying a NUL byte as the text it is filtering.\n */\nfunction buildWhere(\n  filter: Record<string, unknown> | undefined,\n  startIndex: number,\n): { sql: string; params: unknown[] } {\n  if (filter === undefined || Object.keys(filter).length === 0) {\n    return { sql: '', params: [] };\n  }\n  const stripped = stripNulBytes(filter);\n  const clauses: string[] = [];\n  const params: unknown[] = [];\n  const scalar: Record<string, unknown> = {};\n  let index = startIndex;\n  for (const [key, value] of Object.entries(stripped)) {\n    if (Array.isArray(value)) {\n      if (value.length === 0) {\n        clauses.push('false');\n        continue;\n      }\n      const keyParam = `$${index}`;\n      params.push(key);\n      index += 1;\n      const arrParam = `$${index}`;\n      params.push(value.map(String));\n      index += 1;\n      clauses.push(\n        `(CASE WHEN jsonb_typeof(metadata->${keyParam}) = 'array' ` +\n          `THEN metadata->${keyParam} ELSE jsonb_build_array(metadata->${keyParam}) END) ?| ${arrParam}::text[]`,\n      );\n    } else {\n      scalar[key] = value;\n    }\n  }\n  if (Object.keys(scalar).length > 0) {\n    clauses.push(`metadata @> $${index}::jsonb`);\n    params.push(JSON.stringify(scalar));\n    index += 1;\n  }\n  return { sql: `WHERE ${clauses.join(' AND ')}`, params };\n}\n\n/**\n * SQL that collapses a chunk id (`${documentId}#<n>`) back to its source document id — the pgvector\n * mirror of {@link import('./vector-store.js').documentIdOf}. Shared by `remove` and\n * `listDocuments` so both key on the exact same definition of \"chunk belongs to document\".\n */\nconst DOCUMENT_ID_FROM_CHUNK = \"regexp_replace(id, '#[0-9]+$', '')\";\n\n/** The `n` of `…#<n>` as an integer, so chunks sort numerically; a bare id (no suffix) is `0`. */\nconst CHUNK_INDEX_FROM_ID = \"COALESCE((substring(id from '#([0-9]+)$'))::int, 0)\";\n\n/** pgvector accepts a `'[1,2,3]'` text literal cast to `vector`. */\nfunction toVectorLiteral(embedding: number[]): string {\n  return `[${embedding.join(',')}]`;\n}\n","import type { Passage } from '@dudousxd/nestjs-agent-core';\nimport { filterMatchesNothing } from './filter.js';\nimport { type MetadataPatch, applyMetadataPatch, isEmptyMetadataPatch } from './metadata-patch.js';\nimport type { RetrievalDescriptor } from './retrieval-descriptor.js';\nimport {\n  type IndexedDocument,\n  type LexicalVectorStore,\n  type ListChunksOptions,\n  type StoredChunk,\n  UnsafeRemovalError,\n  type VectorRecord,\n  type VectorSearchOptions,\n  type VectorStore,\n  chunkIndexOf,\n  documentIdOf,\n} from './vector-store.js';\n\n/**\n * The minimal Redis surface {@link RedisVectorStore} needs: send a raw command and get the reply.\n * Both `node-redis` (`client.sendCommand(args)`) and `ioredis` (wrap `redis.call`) satisfy it — so\n * this package pulls in NO Redis driver (bring your own, like the other adapters). Requires the\n * RediSearch module (Redis Stack / Redis 8+).\n */\nexport interface RedisSearchClient {\n  sendCommand(args: (string | Buffer)[]): Promise<unknown>;\n}\n\n/**\n * The index that already exists in Redis contradicts this store's configuration in a way that cannot\n * be repaired in place. Thrown by {@link RedisVectorStore.ensureSchema} — which would otherwise have\n * returned happily and left every subsequent query quietly wrong.\n *\n * The canonical case is a changed embedding width (a model swap, 1024 → 1536): RediSearch fixes a\n * vector field's `DIM` at `FT.CREATE`, and every vector already stored was produced by the OLD model,\n * so there is no in-place fix — the index has to be dropped and the corpus re-embedded. That is\n * destructive and belongs to the host, never to a boot-time `ensureSchema`.\n */\nexport class RedisVectorSchemaMismatchError extends Error {\n  constructor(\n    /** The RediSearch index that was inspected. */\n    readonly index: string,\n    /** The index attribute that differs (e.g. `embedding`, `meta_tenant`). */\n    readonly field: string,\n    /** What this store is configured for. */\n    readonly expected: string,\n    /** What `FT.INFO` reports the live index has. */\n    readonly actual: string,\n    remedy: string,\n  ) {\n    super(\n      `RediSearch index \"${index}\" disagrees with this RedisVectorStore's configuration: ` +\n        `field \"${field}\" is ${actual}, expected ${expected}. ${remedy}`,\n    );\n    this.name = 'RedisVectorSchemaMismatchError';\n  }\n}\n\nexport interface RedisVectorStoreOptions {\n  /** RediSearch index name. Default `agent_rag_idx`. */\n  index?: string;\n  /** Key prefix for the per-chunk hashes. Default `agent_rag:`. */\n  prefix?: string;\n  /** Embedding width — must match your model (e.g. 1536). Default 1536. */\n  dimensions?: number;\n  /**\n   * Metadata keys to index as filterable TAG fields. RediSearch needs filter fields declared up\n   * front, so only keys listed here can be passed in `search`'s `filter`. Default none.\n   */\n  filterableFields?: string[];\n  /**\n   * RediSearch scorer used by {@link RedisVectorStore.searchText}. Default `BM25` — the standard\n   * lexical ranking, and the same family the in-process `KeywordRetriever` implements. Override for\n   * a server that names it differently (`BM25STD` on newer builds) or to pick `TFIDF`/`DISMAX`.\n   */\n  lexicalScorer?: string;\n}\n\n/**\n * A RediSearch-backed {@link VectorStore} — HNSW + cosine over Redis, the ecosystem-native option\n * for anyone already running Redis (see `-transport-redis`). Chunks are hashes under `prefix`, the\n * embedding a FLOAT32 vector field; `search` is a KNN query. Call {@link RedisVectorStore.ensureSchema}\n * once at boot to create the index.\n *\n * The chunk text is declared as a RediSearch `TEXT` field, so this store also satisfies\n * {@link LexicalVectorStore}: {@link RedisVectorStore.searchText} is BM25 over that same index —\n * the lexical half of hybrid search with no second index to build, feed, or invalidate.\n */\nexport class RedisVectorStore implements LexicalVectorStore {\n  private readonly index: string;\n  private readonly prefix: string;\n  private readonly dimensions: number;\n  private readonly filterableFields: string[];\n  private readonly lexicalScorer: string;\n\n  constructor(\n    private readonly client: RedisSearchClient,\n    options: RedisVectorStoreOptions = {},\n  ) {\n    this.index = options.index ?? 'agent_rag_idx';\n    this.prefix = options.prefix ?? 'agent_rag:';\n    this.dimensions = options.dimensions ?? 1536;\n    this.filterableFields = options.filterableFields ?? [];\n    this.lexicalScorer = options.lexicalScorer ?? 'BM25';\n  }\n\n  /**\n   * Telemetry self-description — the RediSearch INDEX, not the key prefix: the index is what both\n   * legs query, and two stores sharing one index (the dense and lexical halves of a hybrid) must\n   * report the same namespace or `describeSharedSource` would see them disagree and drop the store.\n   */\n  describeRetrieval(): RetrievalDescriptor {\n    return { store: 'redis', collection: this.index };\n  }\n\n  /**\n   * Idempotent, and drift-aware: create the HNSW/cosine index if `FT.INFO` says it doesn't exist —\n   * and if it DOES exist, compare what's there against this store's configuration instead of\n   * assuming they agree. An index that outlives a config change is the normal case (schemas live in\n   * Redis, config lives in a redeployed process), and the two failure modes it produces are both\n   * invisible at runtime: a `filterableFields` entry added later has no `meta_*` TAG, so every search\n   * filtering on it matches *nothing*; a changed `dimensions` leaves the index on the old width, so\n   * writes are rejected or KNN ranks garbage. Neither raises anything on its own.\n   *\n   * The two are repaired differently, because only one of them CAN be repaired:\n   *\n   * - **A missing filterable TAG is additive** → `FT.ALTER … SCHEMA ADD`. Nothing that already works\n   *   changes, so doing it automatically is safe. Note the chunks written *before* the alter carry no\n   *   `meta_*` hash field at all (`upsert` only writes the fields configured at the time), so they\n   *   only become filterable on that key once they're re-ingested — the schema is repaired here, the\n   *   backfill is the host's call.\n   * - **A dimension (or field-type) change is not repairable** → {@link RedisVectorSchemaMismatchError}.\n   *   It needs a drop + full reindex, which would destroy the host's corpus; failing loudly at boot is\n   *   the only honest option.\n   *\n   * If `FT.INFO` comes back in a shape this parser doesn't recognise, no drift is inferred — an\n   * unreadable reply must not be turned into a false alarm that blocks a boot.\n   */\n  async ensureSchema(): Promise<void> {\n    let info: unknown;\n    try {\n      info = await this.client.sendCommand(['FT.INFO', this.index]);\n    } catch {\n      await this.createIndex();\n      return;\n    }\n    await this.reconcileSchema(info);\n  }\n\n  /** Repair what can be repaired in place; throw on what can't. */\n  private async reconcileSchema(info: unknown): Promise<void> {\n    const attributes = parseIndexAttributes(info);\n    if (attributes.size === 0) {\n      return;\n    }\n\n    const vector = attributes.get('embedding');\n    if (vector?.dimensions !== undefined && vector.dimensions !== this.dimensions) {\n      throw new RedisVectorSchemaMismatchError(\n        this.index,\n        'embedding',\n        `DIM ${this.dimensions}`,\n        `DIM ${vector.dimensions}`,\n        `A vector field's width is fixed at FT.CREATE and every stored embedding has the old one, so this cannot be altered in place: drop the index (FT.DROPINDEX ${this.index} DD) and re-ingest with the new embedding model.`,\n      );\n    }\n\n    const missing: string[] = [];\n    for (const field of this.filterableFields) {\n      const name = `meta_${field}`;\n      const existing = attributes.get(name);\n      if (existing === undefined) {\n        missing.push(name);\n      } else if (existing.type !== 'TAG') {\n        throw new RedisVectorSchemaMismatchError(\n          this.index,\n          name,\n          'TAG',\n          existing.type,\n          `A field's type cannot be changed in place: drop the index (FT.DROPINDEX ${this.index} DD) and re-ingest, or rename the metadata key.`,\n        );\n      }\n    }\n    for (const name of missing) {\n      await this.client.sendCommand(['FT.ALTER', this.index, 'SCHEMA', 'ADD', name, 'TAG']);\n    }\n  }\n\n  private async createIndex(): Promise<void> {\n    const schema: string[] = ['text', 'TEXT', 'source', 'TAG', 'metadata_json', 'TEXT', 'NOINDEX'];\n    for (const field of this.filterableFields) {\n      schema.push(`meta_${field}`, 'TAG');\n    }\n    schema.push(\n      'embedding',\n      'VECTOR',\n      'HNSW',\n      '6',\n      'TYPE',\n      'FLOAT32',\n      'DIM',\n      String(this.dimensions),\n      'DISTANCE_METRIC',\n      'COSINE',\n    );\n    await this.client.sendCommand([\n      'FT.CREATE',\n      this.index,\n      'ON',\n      'HASH',\n      'PREFIX',\n      '1',\n      this.prefix,\n      'SCHEMA',\n      ...schema,\n    ]);\n  }\n\n  async upsert(records: VectorRecord[]): Promise<void> {\n    for (const record of records) {\n      const args: (string | Buffer)[] = [\n        'HSET',\n        `${this.prefix}${record.id}`,\n        'text',\n        record.text,\n        'embedding',\n        encodeVector(record.embedding),\n      ];\n      if (record.source !== undefined) {\n        args.push('source', record.source);\n      }\n      if (record.metadata !== undefined) {\n        args.push('metadata_json', JSON.stringify(record.metadata));\n        for (const field of this.filterableFields) {\n          const value = record.metadata[field];\n          if (value !== undefined) {\n            args.push(`meta_${field}`, encodeTag(value));\n          }\n        }\n      }\n      await this.client.sendCommand(args);\n    }\n  }\n\n  /**\n   * Single-document deletion, by `SCAN … MATCH`.\n   *\n   * This deliberately stays a keyspace scan even though the rest of this class no longer needs one.\n   * The obvious optimisation is to stamp each chunk with its document id as an implicit filterable\n   * TAG at {@link RedisVectorStore.upsert} and turn `remove` into an `FT.SEARCH` — and that is exactly\n   * the change that must not ship, because chunks written *before* it carry no such field. `FT.SEARCH`\n   * would find zero of them, `remove` would return happily, and a document that has been \"deleted\"\n   * would go on being retrieved. A delete that silently stops deleting is worse than a slow one, and\n   * the library cannot tell a fully-migrated corpus from an unmigrated one: both look like \"this\n   * document has no indexed chunks\". Nor is a search-then-fall-back-to-scan hybrid safe — a document\n   * re-ingested after the upgrade has *some* stamped chunks, so the search finds hits, the fallback\n   * never runs, and the unstamped tail survives. That is the same silent failure with a smaller blast\n   * radius, which makes it harder to notice rather than less wrong.\n   *\n   * The consumer pain this was measured against — deleting a whole collection, one `remove` per\n   * document — is answered instead by {@link RedisVectorStore.removeWhere} (one filtered query, no\n   * keyspace scan at all) and {@link RedisVectorStore.removeMany} (one scan for N documents rather\n   * than N scans). Neither depends on a field that older chunks lack, so neither has a migration.\n   */\n  async remove(documentId: string): Promise<void> {\n    const keys = await this.chunkKeys(documentId);\n    if (keys.length > 0) {\n      await this.client.sendCommand(['DEL', ...keys]);\n    }\n  }\n\n  /**\n   * Rewrite the metadata of every chunk of `documentId` in place, leaving `text` and `embedding`\n   * alone. See {@link VectorStore.updateMetadata} for the merge semantics and the return value.\n   *\n   * The care this needs is entirely about the fact that a chunk stores its metadata **twice**: as the\n   * `metadata_json` blob (what {@link RedisVectorStore.search} reads back onto a `Passage`) and as\n   * `meta_<field>` TAG fields (what RediSearch actually filters on, and only for the declared\n   * `filterableFields`). Move one without the other and the store lies to itself — a chunk that\n   * filters as the old value but reports the new one, or the reverse — so this method rewrites both\n   * from the same merged object:\n   *\n   * - a patched key that is **not** filterable lands in `metadata_json` only, and no stray `meta_*`\n   *   field is invented for it (it would be dead weight the index does not know about);\n   * - a patched key that **is** filterable also rewrites its TAG, using the identical encoding\n   *   `upsert` uses, so an updated chunk is indistinguishable from a re-ingested one;\n   * - a filterable key the patch **removes** has its TAG `HDEL`-ed, not left behind as a tag matching\n   *   a value the document no longer carries.\n   *\n   * A plain `HSET` is all the index needs: RediSearch re-indexes a hash the moment it is written, so\n   * the very next `FT.SEARCH` sees the new TAG and no longer the old one — no reindex command, and\n   * no need to rewrite the (untouched, and expensive) vector to nudge it. `HDEL` on an indexed field\n   * likewise drops it from the index. Verified against a real Redis Stack in\n   * `redis-vector-store.db.spec.ts`, not assumed.\n   *\n   * Removals are issued **before** the write, so the only window a concurrent reader can observe is\n   * \"TAG already gone, `metadata_json` not yet updated\" — which fails *closed* on a filter carrying\n   * an ACL. The reverse order would briefly leave a document tagged with a capability its metadata no\n   * longer claims. Read-modify-write across chunks is not transactional; concurrent writers to the\n   * same chunk are last-writer-wins, exactly as two concurrent `upsert`s already are.\n   */\n  async updateMetadata(documentId: string, patch: MetadataPatch): Promise<number> {\n    if (isEmptyMetadataPatch(patch)) {\n      return 0;\n    }\n    const keys = await this.chunkKeys(documentId);\n    let updated = 0;\n    for (const key of keys) {\n      const raw = await this.client.sendCommand(['HGET', key, 'metadata_json']);\n      const current = parseMetadata(raw === null || raw === undefined ? undefined : toStr(raw));\n      const next = applyMetadataPatch(current.metadata, patch);\n\n      const args: (string | Buffer)[] = ['HSET', key, 'metadata_json', JSON.stringify(next)];\n      const stale: string[] = [];\n      for (const field of this.filterableFields) {\n        const value = next[field];\n        if (value !== undefined) {\n          args.push(`meta_${field}`, encodeTag(value));\n        } else if (current.metadata?.[field] !== undefined) {\n          stale.push(`meta_${field}`);\n        }\n      }\n      if (stale.length > 0) {\n        await this.client.sendCommand(['HDEL', key, ...stale]);\n      }\n      await this.client.sendCommand(args);\n      updated += 1;\n    }\n    return updated;\n  }\n\n  /**\n   * Every chunk key that currently EXISTS for `documentId` — the bare `${prefix}${documentId}` plus\n   * the `${documentId}#<n>` chunks found by `SCAN`. One definition of \"chunk belongs to document\",\n   * shared by `remove` and `updateMetadata`, so the two can never disagree about which keys a\n   * document owns. The glob is escaped so `gone` does not reach into `goner#0`.\n   */\n  private async chunkKeys(documentId: string): Promise<string[]> {\n    const keys = new Set<string>();\n    const bare = `${this.prefix}${documentId}`;\n    const exists = await this.client.sendCommand(['EXISTS', bare]);\n    if (Number(toStr(exists)) > 0) {\n      keys.add(bare);\n    }\n    const pattern = `${this.prefix}${escapeGlob(documentId)}#*`;\n    let cursor = '0';\n    do {\n      const reply = await this.client.sendCommand([\n        'SCAN',\n        cursor,\n        'MATCH',\n        pattern,\n        'COUNT',\n        '256',\n      ]);\n      const page = parseScanReply(reply);\n      cursor = page.cursor;\n      for (const key of page.keys) {\n        keys.add(key);\n      }\n    } while (cursor !== '0');\n    return [...keys];\n  }\n\n  /**\n   * The chunks of one document, in document order. See {@link VectorStore.listChunks}.\n   *\n   * Reads the hashes directly (`HMGET text metadata_json`) rather than going through `FT.SEARCH`.\n   * Two reasons, and the second is the one that matters: the query language has no way to ask for\n   * \"every chunk of this document\" — `id` is the key name, not an indexed field — and `FT.SEARCH`\n   * caps at `LIMIT`, so paging a document through it would mean ordering by a field the index does\n   * not hold. `chunkKeys` is the same enumeration {@link RedisVectorStore.remove} and\n   * {@link RedisVectorStore.updateMetadata} already use, so \"the chunks this returns\" and \"the chunks\n   * a delete would take\" cannot drift apart.\n   *\n   * It inherits that method's cost too: one keyspace `SCAN` per call. Acceptable here because this\n   * is an inspection path (one document, on demand) and not something retrieval runs — but it is why\n   * this must not be put on a hot path or called in a loop over a corpus.\n   *\n   * `embedding` is deliberately not fetched: it is by far the largest field on the hash and nothing\n   * a caller reading text back can do with it.\n   */\n  async listChunks(documentId: string, options?: ListChunksOptions): Promise<StoredChunk[]> {\n    const keys = await this.chunkKeys(documentId);\n    const ordered = keys\n      .map((key) => ({ key, id: key.slice(this.prefix.length) }))\n      .map((entry) => ({ ...entry, index: chunkIndexOf(entry.id) }))\n      .sort((a, b) => a.index - b.index);\n\n    const offset = options?.offset ?? 0;\n    const page =\n      options?.limit === undefined\n        ? ordered.slice(offset)\n        : ordered.slice(offset, offset + options.limit);\n\n    const chunks: StoredChunk[] = [];\n    for (const entry of page) {\n      const reply = await this.client.sendCommand(['HMGET', entry.key, 'text', 'metadata_json']);\n      const fields = Array.isArray(reply) ? reply : [];\n      const text = fields[0] === null || fields[0] === undefined ? undefined : toStr(fields[0]);\n      if (text === undefined) {\n        // The key was deleted between the SCAN and this read. Skip it rather than reporting a chunk\n        // with empty text, which would read as \"the chunker produced nothing here\".\n        continue;\n      }\n      const raw = fields[1] === null || fields[1] === undefined ? undefined : toStr(fields[1]);\n      chunks.push({\n        id: entry.id,\n        index: entry.index,\n        text,\n        ...parseMetadata(raw),\n      });\n    }\n    return chunks;\n  }\n\n  async listDocuments(filter?: Record<string, unknown>): Promise<IndexedDocument[]> {\n    if (filterMatchesNothing(filter)) {\n      return [];\n    }\n    const query = buildFilter(filter);\n    const documents = new Map<string, IndexedDocument>();\n    const batchSize = 1000;\n    let offset = 0;\n    for (;;) {\n      // RETURN metadata_json (not NOCONTENT) so we can carry a representative chunk's metadata;\n      // parseSearchReply already yields prefix-stripped ids + parsed metadata for both RESP2/RESP3.\n      const reply = await this.client.sendCommand([\n        'FT.SEARCH',\n        this.index,\n        query,\n        'RETURN',\n        '1',\n        'metadata_json',\n        'LIMIT',\n        String(offset),\n        String(batchSize),\n        'DIALECT',\n        '2',\n      ]);\n      const passages = parseSearchReply(reply, this.prefix);\n      for (const passage of passages) {\n        const id = documentIdOf(passage.id);\n        if (!documents.has(id)) {\n          documents.set(id, {\n            id,\n            ...(passage.metadata !== undefined ? { metadata: passage.metadata } : {}),\n          });\n        }\n      }\n      if (passages.length < batchSize) {\n        break;\n      }\n      offset += batchSize;\n    }\n    return [...documents.values()];\n  }\n\n  /**\n   * The id-only half of {@link RedisVectorStore.listDocuments}, served by `FT.SEARCH … NOCONTENT`:\n   * RediSearch returns bare keys, so nothing carries `metadata_json` over the wire and nothing is\n   * JSON-parsed. `listDocuments` has to parse one metadata blob per *chunk* — thousands of parses to\n   * produce a few hundred ids it then throws the metadata away from — and this does none of it.\n   *\n   * The collapse to document ids still happens client-side. RediSearch can group server-side\n   * (`FT.AGGREGATE … GROUPBY`), but only over an indexed *field*, and a chunk's document id lives in\n   * its key, not in a field — deriving it would mean stamping one at write time, which is the\n   * migration {@link RedisVectorStore.remove} explains this class refuses. Deduplicating a page of\n   * keys in JS is free by comparison.\n   */\n  async listDocumentIds(filter?: Record<string, unknown>): Promise<string[]> {\n    if (filterMatchesNothing(filter)) {\n      return [];\n    }\n    const query = buildFilter(filter);\n    const documents = new Set<string>();\n    let offset = 0;\n    for (;;) {\n      const reply = await this.client.sendCommand([\n        'FT.SEARCH',\n        this.index,\n        query,\n        'NOCONTENT',\n        'LIMIT',\n        String(offset),\n        String(SCAN_PAGE),\n        'DIALECT',\n        '2',\n      ]);\n      const keys = parseSearchKeys(reply);\n      for (const key of keys) {\n        documents.add(documentIdOf(stripPrefix(key, this.prefix)));\n      }\n      if (keys.length < SCAN_PAGE) {\n        break;\n      }\n      offset += SCAN_PAGE;\n    }\n    return [...documents];\n  }\n\n  /**\n   * Bulk deletion by document id — **one** keyspace scan for N documents, where N calls to\n   * {@link RedisVectorStore.remove} would be N of them. The scan is `MATCH ${prefix}*`, so Redis still\n   * filters to this store's own keys server-side; membership is then decided in JS against a `Set`,\n   * which is what lets a single pass serve any number of ids.\n   *\n   * It deletes by key, exactly as `remove` does, so it is correct on chunks written by any version of\n   * this library — there is no field it needs the corpus to already carry.\n   */\n  async removeMany(documentIds: string[]): Promise<void> {\n    if (documentIds.length === 0) {\n      return;\n    }\n    const wanted = new Set(documentIds);\n    // A document may have been stored under its bare id (no `#n` suffix); those keys are exact and\n    // need no scan to find, so seed them and let the scan add the chunked ones.\n    let pending = documentIds.map((id) => `${this.prefix}${id}`);\n    let cursor = '0';\n    do {\n      const reply = await this.client.sendCommand([\n        'SCAN',\n        cursor,\n        'MATCH',\n        `${escapeGlob(this.prefix)}*`,\n        'COUNT',\n        String(SCAN_PAGE),\n      ]);\n      const page = parseScanReply(reply);\n      cursor = page.cursor;\n      for (const key of page.keys) {\n        if (wanted.has(documentIdOf(stripPrefix(key, this.prefix)))) {\n          pending.push(key);\n        }\n      }\n      if (pending.length >= DELETE_BATCH) {\n        await this.client.sendCommand(['DEL', ...pending]);\n        pending = [];\n      }\n    } while (cursor !== '0');\n    if (pending.length > 0) {\n      await this.client.sendCommand(['DEL', ...pending]);\n    }\n  }\n\n  /**\n   * Delete every chunk matching `filter`, via `FT.SEARCH … NOCONTENT` + `DEL` — no keyspace scan at\n   * all, so dropping a collection costs one indexed query per page instead of one full pass per\n   * document. Resolves the number of chunk keys actually deleted.\n   *\n   * The two refusals, in this order, before any query is issued:\n   *\n   * 1. **An empty filter object throws** {@link UnsafeRemovalError}. `buildFilter({})` is `*`, and `*`\n   *    here would mean \"delete the corpus\" — far too destructive an outcome for the shape a filter\n   *    degenerates to when it is built wrong.\n   * 2. **An empty-array value deletes nothing** and resolves `0`. This is the package's deny primitive\n   *    (an actor with no capability tokens), and it is the one that has to be gated *explicitly*: a\n   *    plausible-looking \"normalise the filter first\" refactor that drops empty arrays turns a deny\n   *    into `*` and wipes everything the deny existed to protect.\n   *\n   * Then one more, which is specific to RediSearch: every filter key must be a declared\n   * `filterableFields` entry. `search` lets the engine reject an unknown field, which is fine for a\n   * read; for a delete the check is worth making up front and by name.\n   *\n   * Deletion happens page by page, always re-querying from offset 0 — the rows just deleted are gone\n   * from the index, so paging forward would skip their replacements. If a page comes back non-empty\n   * but `DEL` reports nothing removed (keys expired between query and delete, or the index is stale),\n   * the loop stops rather than spinning on results it can never consume.\n   */\n  async removeWhere(filter: Record<string, unknown>): Promise<number> {\n    const keys = Object.keys(filter);\n    if (keys.length === 0) {\n      throw new UnsafeRemovalError(\n        'empty-filter',\n        'removeWhere() refuses an empty filter: it would delete every chunk in the index. ' +\n          'Pass a filter that scopes the removal, or delete deliberately with ' +\n          'removeMany(await store.listDocumentIds()).',\n      );\n    }\n    const unindexed = keys.filter((key) => !this.filterableFields.includes(key));\n    if (unindexed.length > 0) {\n      const named = unindexed.map((key) => `\"${key}\"`).join(', ');\n      const declared = this.filterableFields.join(', ') || 'none';\n      throw new UnsafeRemovalError(\n        'unindexed-field',\n        `removeWhere() cannot scope on ${named}: not declared in this store's filterableFields (${declared}), so RediSearch has no TAG to match on.`,\n      );\n    }\n    // THE guard. Removing it turns the deny primitive into an unfiltered delete — see the db spec's\n    // \"an empty-array filter deletes NOTHING\" case, which exists to fail loudly if this ever goes.\n    if (filterMatchesNothing(filter)) {\n      return 0;\n    }\n\n    const query = buildFilter(filter);\n    let removed = 0;\n    for (;;) {\n      const reply = await this.client.sendCommand([\n        'FT.SEARCH',\n        this.index,\n        query,\n        'NOCONTENT',\n        'LIMIT',\n        '0',\n        String(DELETE_BATCH),\n        'DIALECT',\n        '2',\n      ]);\n      const page = parseSearchKeys(reply);\n      if (page.length === 0) {\n        break;\n      }\n      const deleted = Number(await this.client.sendCommand(['DEL', ...page]));\n      if (!Number.isFinite(deleted) || deleted === 0) {\n        break;\n      }\n      removed += deleted;\n    }\n    return removed;\n  }\n\n  /**\n   * Count matching chunks with `FT.SEARCH … LIMIT 0 0` — RediSearch returns the total and no\n   * documents, so the cost is the query, not the corpus. An empty-array filter value denies and\n   * yields `0`, same as every other filtered path here.\n   */\n  async countChunks(filter?: Record<string, unknown>): Promise<number> {\n    if (filterMatchesNothing(filter)) {\n      return 0;\n    }\n    const reply = await this.client.sendCommand([\n      'FT.SEARCH',\n      this.index,\n      buildFilter(filter),\n      'NOCONTENT',\n      'LIMIT',\n      '0',\n      '0',\n      'DIALECT',\n      '2',\n    ]);\n    return parseSearchTotal(reply);\n  }\n\n  async search(embedding: number[], options: VectorSearchOptions): Promise<Passage[]> {\n    if (filterMatchesNothing(options.filter)) {\n      return [];\n    }\n    const query = `${buildFilter(options.filter)}=>[KNN ${options.topK} @embedding $BLOB AS vector_score]`;\n    const reply = await this.client.sendCommand([\n      'FT.SEARCH',\n      this.index,\n      query,\n      'PARAMS',\n      '2',\n      'BLOB',\n      encodeVector(embedding),\n      'RETURN',\n      '4',\n      'text',\n      'source',\n      'metadata_json',\n      'vector_score',\n      'SORTBY',\n      'vector_score',\n      'ASC',\n      'DIALECT',\n      '2',\n      'LIMIT',\n      '0',\n      String(options.topK),\n    ]);\n    return parseSearchReply(reply, this.prefix);\n  }\n\n  /**\n   * Lexical (BM25) search over the same index `search` uses — the {@link LexicalVectorStore} half of\n   * hybrid retrieval, served by RediSearch's own keyword index rather than an in-process copy of the\n   * corpus. `options.filter` is ANDed onto the text clause with the identical TAG semantics as\n   * `search` (array = OR, empty array = deny), so a lexical hit can never escape a filter a vector\n   * hit would have respected.\n   *\n   * A query with no searchable terms — empty, whitespace, or pure punctuation — returns `[]`. That is\n   * deliberate: RediSearch's `*` would match the entire corpus, which is the opposite of what a\n   * relevance query with nothing to be relevant to should do.\n   */\n  async searchText(query: string, options: VectorSearchOptions): Promise<Passage[]> {\n    if (filterMatchesNothing(options.filter)) {\n      return [];\n    }\n    const terms = tokenizeQuery(query);\n    if (terms.length === 0) {\n      return [];\n    }\n    const filterQuery = buildFilter(options.filter);\n    const textQuery = `@text:(${terms.join('|')})`;\n    const reply = await this.client.sendCommand([\n      'FT.SEARCH',\n      this.index,\n      filterQuery === '*' ? textQuery : `(${filterQuery} ${textQuery})`,\n      'SCORER',\n      this.lexicalScorer,\n      'WITHSCORES',\n      'RETURN',\n      '3',\n      'text',\n      'source',\n      'metadata_json',\n      'DIALECT',\n      '2',\n      'LIMIT',\n      '0',\n      String(options.topK),\n    ]);\n    return parseSearchReply(reply, this.prefix, 'lexical');\n  }\n}\n\n/** Page size for `SCAN COUNT` and for the id-only `FT.SEARCH` pages. */\nconst SCAN_PAGE = 1000;\n\n/** How many keys to hand a single `DEL`, and therefore how big a `removeWhere` page is. */\nconst DELETE_BATCH = 512;\n\n/** Recover a chunk id from its Redis key. */\nfunction stripPrefix(key: string, prefix: string): string {\n  return key.startsWith(prefix) ? key.slice(prefix.length) : key;\n}\n\n/**\n * Parse the keys out of an `FT.SEARCH … NOCONTENT` reply, tolerating both wire shapes: the RESP2 array\n * `[total, key, key, …]` and the RESP3 object `{ total_results, results: [{ id }] }`. Keys come back\n * whole (prefix included) — callers strip it.\n */\nfunction parseSearchKeys(reply: unknown): string[] {\n  if (Array.isArray(reply)) {\n    return reply.slice(1).map(toStr);\n  }\n  if (typeof reply === 'object' && reply !== null && 'results' in reply) {\n    const results = (reply as { results: unknown }).results;\n    return Array.isArray(results) ? results.map(readId) : [];\n  }\n  return [];\n}\n\n/**\n * Parse the match count out of an `FT.SEARCH … LIMIT 0 0` reply — element 0 in RESP2, `total_results`\n * in the RESP3 object. An unrecognised shape counts as 0 rather than `NaN`, so a caller comparing\n * against a threshold can't be handed something that fails every comparison silently.\n */\nfunction parseSearchTotal(reply: unknown): number {\n  if (Array.isArray(reply)) {\n    const total = Number(toStr(reply[0]));\n    return Number.isFinite(total) ? total : 0;\n  }\n  if (typeof reply === 'object' && reply !== null && 'total_results' in reply) {\n    const total = Number((reply as { total_results: unknown }).total_results);\n    return Number.isFinite(total) ? total : 0;\n  }\n  return 0;\n}\n\n/** One attribute as the live index reports it — enough to spot the drift that matters. */\ninterface IndexAttribute {\n  /** `TEXT` / `TAG` / `VECTOR`. */\n  type: string;\n  /** `VECTOR` fields only: the width the index was created with. */\n  dimensions?: number;\n}\n\n/**\n * Parse `FT.INFO`'s `attributes` into `attribute name → { type, dimensions }`, tolerating both wire\n * shapes exactly like {@link parseSearchReply} does: the RESP2 flat key/value array (whose attributes\n * are themselves flat key/value arrays) and node-redis's RESP3 object (attributes as objects).\n * Unknown shapes yield an empty map, which callers read as \"can't tell\" rather than \"nothing there\".\n */\nfunction parseIndexAttributes(reply: unknown): Map<string, IndexAttribute> {\n  const attributes = new Map<string, IndexAttribute>();\n  for (const entry of readInfoField(reply, 'attributes')) {\n    const fields = readKeyValues(entry);\n    const name = fields.attribute ?? fields.identifier;\n    if (name === undefined) {\n      continue;\n    }\n    const dim = Number(fields.dim);\n    attributes.set(name, {\n      type: (fields.type ?? '').toUpperCase(),\n      ...(fields.dim !== undefined && Number.isFinite(dim) ? { dimensions: dim } : {}),\n    });\n  }\n  return attributes;\n}\n\n/** Read one top-level `FT.INFO` field as an array, from either the RESP2 pair-array or RESP3 object. */\nfunction readInfoField(reply: unknown, key: string): unknown[] {\n  if (Array.isArray(reply)) {\n    for (let index = 0; index + 1 < reply.length; index += 2) {\n      if (toStr(reply[index]) === key) {\n        const value = reply[index + 1];\n        return Array.isArray(value) ? value : [];\n      }\n    }\n    return [];\n  }\n  if (typeof reply === 'object' && reply !== null && key in reply) {\n    const value = (reply as Record<string, unknown>)[key];\n    return Array.isArray(value) ? value : [];\n  }\n  return [];\n}\n\n/** Flatten one attribute entry (RESP2 pair-array or RESP3 object) into lower-cased string fields. */\nfunction readKeyValues(entry: unknown): Record<string, string | undefined> {\n  const fields: Record<string, string | undefined> = {};\n  if (Array.isArray(entry)) {\n    for (let index = 0; index + 1 < entry.length; index += 2) {\n      fields[toStr(entry[index]).toLowerCase()] = toStr(entry[index + 1]);\n    }\n    return fields;\n  }\n  if (typeof entry === 'object' && entry !== null) {\n    for (const [key, value] of Object.entries(entry)) {\n      fields[key.toLowerCase()] = toStr(value);\n    }\n  }\n  return fields;\n}\n\n/** RediSearch expects a little-endian FLOAT32 buffer for the query/stored vector. */\nfunction encodeVector(embedding: number[]): Buffer {\n  return Buffer.from(new Float32Array(embedding).buffer);\n}\n\n/**\n * `*` for no filter, else an AND of TAG clauses. A scalar value is an exact tag match\n * (`@meta_owner:{u1}`); an **array** value is a TAG alternation — match-any / OR\n * (`@meta_audience:{public|role\\:ADMIN}`), the capability-ACL primitive. RediSearch TAG fields are\n * multi-valued per document, so this also matches documents carrying several of the tags.\n */\nfunction buildFilter(filter?: Record<string, unknown>): string {\n  if (filter === undefined || Object.keys(filter).length === 0) {\n    return '*';\n  }\n  const clauses = Object.entries(filter).map(([key, value]) => {\n    const values = Array.isArray(value) ? value : [value];\n    const alternation = values.map((entry) => escapeTag(String(entry))).join('|');\n    return `@meta_${key}:{${alternation}}`;\n  });\n  return `(${clauses.join(' ')})`;\n}\n\n/**\n * Reduce a raw user query to RediSearch query *terms*, the union of which becomes the text clause.\n *\n * This is the escaping story for the text leg, and it escapes by **construction** rather than by\n * quoting: a term is kept only as a run of letters, digits and `_`, so nothing that could carry\n * meaning in RediSearch's query language — `@ { } | ( ) * ~ - \" ' : ; , => %` and friends — can\n * survive into the emitted query. A query cannot therefore add a clause, negate one, open a field\n * selector, or widen the filter it is ANDed with. (Escaping each punctuation character instead, as\n * {@link escapeTag} does for TAG values, would be safe but *lossy*: RediSearch's own tokenizer split\n * the indexed text on that same punctuation, so an escaped `hello\\-world` term matches nothing.)\n *\n * Unicode letters and digits are kept — stripping to ASCII would silently make non-English corpora\n * unsearchable. Since `\\p{L}`/`\\p{N}` contain no RediSearch metacharacters, keeping them is safe.\n */\nfunction tokenizeQuery(query: string): string[] {\n  return query.match(/[\\p{L}\\p{N}_]+/gu) ?? [];\n}\n\n/**\n * Encode one metadata value as the `meta_<field>` hash field RediSearch indexes as a TAG. An **array**\n * becomes a multi-valued TAG (comma-separated, RediSearch's default separator) so a document can\n * carry several capability tokens — which is also why individual values must not contain commas.\n *\n * Shared by `upsert` and `updateMetadata` on purpose: they write the same field, and the day the two\n * encode it differently is the day a patched chunk stops matching a filter a freshly-ingested one\n * matches, for a value that looks identical in `metadata_json`.\n */\nfunction encodeTag(value: unknown): string {\n  return Array.isArray(value) ? value.map(String).join(',') : String(value);\n}\n\n/** Escape RediSearch TAG punctuation so an id/tenant value matches literally. */\nfunction escapeTag(value: string): string {\n  return value.replace(/[^a-zA-Z0-9_]/g, (char) => `\\\\${char}`);\n}\n\n/** Escape `SCAN MATCH` glob metacharacters so a document id matches its chunk keys literally. */\nfunction escapeGlob(value: string): string {\n  return value.replace(/[*?[\\]\\\\]/g, (char) => `\\\\${char}`);\n}\n\n/**\n * Parse a `SCAN` reply into `{ cursor, keys }`, tolerating both wire shapes: the RESP2 array\n * `[cursor, [key, …]]` and node-redis's RESP3 object `{ cursor, keys }`.\n */\nfunction parseScanReply(reply: unknown): { cursor: string; keys: string[] } {\n  if (Array.isArray(reply) && reply.length >= 2) {\n    const rawKeys = reply[1];\n    return {\n      cursor: toStr(reply[0]),\n      keys: Array.isArray(rawKeys) ? rawKeys.map(toStr) : [],\n    };\n  }\n  if (typeof reply === 'object' && reply !== null && 'cursor' in reply && 'keys' in reply) {\n    const { cursor, keys } = reply as { cursor: unknown; keys: unknown };\n    return {\n      cursor: toStr(cursor),\n      keys: Array.isArray(keys) ? keys.map(toStr) : [],\n    };\n  }\n  return { cursor: '0', keys: [] };\n}\n\nfunction toStr(value: unknown): string {\n  if (typeof value === 'string') {\n    return value;\n  }\n  return Buffer.isBuffer(value) ? value.toString('utf8') : String(value);\n}\n\n/**\n * Which leg produced the reply, and therefore where a passage's `score` comes from:\n *\n * - `vector` — the KNN query. Score is the returned `vector_score` **distance**, turned into a\n *   cosine similarity by `1 - distance`. Two array elements per result (`key`, `fields`).\n * - `lexical` — the `WITHSCORES` text query. The engine's BM25 relevance is already a\n *   bigger-is-better score, and it arrives *inline*: three array elements per result\n *   (`key`, `score`, `fields`), which is why the stride is not a constant.\n */\ntype ScoreSource = 'vector' | 'lexical';\n\n/**\n * Parse an `FT.SEARCH` reply into passages, tolerating both wire shapes: the RESP2 array\n * `[total, key, [f, v, …], …]` (ioredis / node-redis RESP2) and the RESP3 object\n * `{ results: [{ id, extra_attributes: { … } }] }` (node-redis's default). The `prefix` is stripped\n * back off the key to recover the chunk id; `scoreSource` selects the scoring convention.\n */\nfunction parseSearchReply(\n  reply: unknown,\n  prefix: string,\n  scoreSource: ScoreSource = 'vector',\n): Passage[] {\n  const stride = scoreSource === 'lexical' ? 3 : 2;\n  if (Array.isArray(reply)) {\n    const passages: Passage[] = [];\n    for (let index = 1; index + stride - 1 < reply.length; index += stride) {\n      const rawFields = reply[index + stride - 1];\n      if (Array.isArray(rawFields)) {\n        const attrs: Record<string, string> = {};\n        for (let field = 0; field + 1 < rawFields.length; field += 2) {\n          attrs[toStr(rawFields[field])] = toStr(rawFields[field + 1]);\n        }\n        const inlineScore = scoreSource === 'lexical' ? toStr(reply[index + 1]) : undefined;\n        passages.push(toPassage(toStr(reply[index]), attrs, prefix, scoreSource, inlineScore));\n      }\n    }\n    return passages;\n  }\n  if (typeof reply === 'object' && reply !== null && 'results' in reply) {\n    const results = (reply as { results: unknown }).results;\n    if (Array.isArray(results)) {\n      return results.map((result) =>\n        toPassage(\n          readId(result),\n          readAttributes(result),\n          prefix,\n          scoreSource,\n          scoreSource === 'lexical' ? readScore(result) : undefined,\n        ),\n      );\n    }\n  }\n  return [];\n}\n\n/** RESP3 `WITHSCORES` puts the relevance score on the result object rather than inline in the array. */\nfunction readScore(result: unknown): string | undefined {\n  if (typeof result === 'object' && result !== null && 'score' in result) {\n    return toStr((result as { score: unknown }).score);\n  }\n  return undefined;\n}\n\nfunction readId(result: unknown): string {\n  if (typeof result === 'object' && result !== null && 'id' in result) {\n    return toStr((result as { id: unknown }).id);\n  }\n  return '';\n}\n\nfunction readAttributes(result: unknown): Record<string, string> {\n  const attrs: Record<string, string> = {};\n  if (typeof result === 'object' && result !== null && 'extra_attributes' in result) {\n    const raw = (result as { extra_attributes: unknown }).extra_attributes;\n    if (typeof raw === 'object' && raw !== null) {\n      for (const [key, value] of Object.entries(raw)) {\n        attrs[key] = toStr(value);\n      }\n    }\n  }\n  return attrs;\n}\n\nfunction toPassage(\n  rawId: string,\n  attrs: Record<string, string>,\n  prefix: string,\n  scoreSource: ScoreSource = 'vector',\n  inlineScore?: string,\n): Passage {\n  const score =\n    scoreSource === 'lexical' ? Number(inlineScore ?? '0') : 1 - Number(attrs.vector_score ?? '1');\n  const source = attrs.source;\n  return {\n    id: rawId.startsWith(prefix) ? rawId.slice(prefix.length) : rawId,\n    text: attrs.text ?? '',\n    score: Number.isFinite(score) ? score : 0,\n    ...(source !== undefined ? { source } : {}),\n    ...parseMetadata(attrs.metadata_json),\n  };\n}\n\nfunction parseMetadata(raw: string | undefined): { metadata?: Record<string, unknown> } {\n  if (raw === undefined) {\n    return {};\n  }\n  try {\n    const parsed: unknown = JSON.parse(raw);\n    if (typeof parsed === 'object' && parsed !== null) {\n      return { metadata: parsed as Record<string, unknown> };\n    }\n  } catch {\n    // not JSON — no metadata\n  }\n  return {};\n}\n","/**\n * What a retrieval was served BY — the static half of retrieval telemetry, separated from the\n * emitting half (`retrieval-telemetry.ts`) so a store or a retriever can describe itself without\n * importing anything that emits. That separation is not tidiness: `retrieval-telemetry.ts` imports\n * the retrievers' shapes to detect them, and the retrievers import their descriptor kind, so putting\n * both halves in one module would make every retriever ↔ telemetry edge a cycle.\n */\n\n/** Which retrieval strategy answered. `unknown` is a retriever this package did not ship. */\nexport type RetrieverKind =\n  | 'embedding'\n  | 'keyword'\n  | 'lexical'\n  | 'hybrid'\n  | 'filtered'\n  | 'reranking'\n  | 'unknown';\n\n/** Which backend held the chunks. Omitted entirely for a retriever that holds its own (keyword). */\nexport type VectorStoreKind = 'memory' | 'pg' | 'redis';\n\n/**\n * A retriever's (or a store's) self-description, as it appears on a retrieval event. Every field is\n * optional because the describer is answering only for the layer it *is*: a store knows its backend\n * and namespace but not which strategy queried it; `KeywordRetriever` knows its strategy but has no\n * store at all.\n */\nexport interface RetrievalDescriptor {\n  retriever?: RetrieverKind;\n  store?: VectorStoreKind;\n  /**\n   * The namespace the chunks live in — `PgVectorStore`'s table, `RedisVectorStore`'s RediSearch\n   * index. This is the STORE-level namespace, not a per-query metadata scope: a host that partitions\n   * one index into logical collections with a metadata filter (the usual multi-tenant shape) reports\n   * that through `InstrumentRetrieverOptions.collection`, which overrides this.\n   */\n  collection?: string;\n}\n\n/**\n * The optional capability a store or retriever implements to appear on a retrieval event as\n * something other than `unknown`. Deliberately NOT a member of `VectorStore` or of core's\n * `Retriever`: both are implemented outside this package, and adding a required member to either\n * would break every existing implementation on upgrade — for a field that only observability reads.\n */\nexport interface DescribesRetrieval {\n  describeRetrieval(): RetrievalDescriptor;\n}\n\n/** Structural guard, so a `VectorStore`/`Retriever` is narrowed to the capability without a cast. */\nexport function describesRetrieval(value: unknown): value is DescribesRetrieval {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    typeof Reflect.get(value, 'describeRetrieval') === 'function'\n  );\n}\n\n/** A candidate's descriptor, or an empty one when it does not carry the capability. */\nexport function describeRetrieval(candidate: unknown): RetrievalDescriptor {\n  return describesRetrieval(candidate) ? candidate.describeRetrieval() : {};\n}\n\n/**\n * The store half of a wrapped retriever's descriptor: the base's `store`/`collection` with its\n * `retriever` dropped, so the wrapper can stamp its own strategy on top.\n *\n * `new FilteredRetriever(new EmbeddingRetriever(embedder, pg), scope)` therefore reports\n * `{ retriever: 'filtered', store: 'pg', collection: 'agent_rag_chunks' }` rather than losing the\n * store: which backend answered is the thing a \"retrievals by store\" panel exists to show, and a\n * production wiring is almost always two or three wrappers deep.\n */\nexport function describeSource(base: unknown): Omit<RetrievalDescriptor, 'retriever'> {\n  const { retriever: _ignored, ...source } = describeRetrieval(base);\n  return source;\n}\n\n/**\n * The store half shared by EVERY leg of a composed retriever, or nothing when they disagree.\n *\n * A hybrid whose legs are the dense and lexical halves of the same RediSearch index (the shape\n * `LexicalRetriever` exists for) genuinely was served by that one store, and reporting it is what\n * makes the store breakdown add up. A hybrid fusing pgvector with an in-process BM25 index was not\n * served by either alone, and picking the first leg would silently attribute every such retrieval to\n * a store that answered half of it.\n */\nexport function describeSharedSource(\n  legs: readonly unknown[],\n): Omit<RetrievalDescriptor, 'retriever'> {\n  const sources = legs.map(describeSource);\n  const [first] = sources;\n  if (first === undefined) {\n    return {};\n  }\n  const agrees = sources.every(\n    (source) => source.store === first.store && source.collection === first.collection,\n  );\n  return agrees ? first : {};\n}\n","import type {\n  EmbeddingProvider,\n  Passage,\n  RetrieveOptions,\n  Retriever,\n} from '@dudousxd/nestjs-agent-core';\nimport { type RetrievalDescriptor, describeSource } from './retrieval-descriptor.js';\nimport type { VectorStore } from './vector-store.js';\n\nexport interface EmbeddingRetrieverOptions {\n  /**\n   * Drop passages scoring below this, so a query the corpus cannot answer returns nothing.\n   *\n   * A vector search always returns its `topK` nearest neighbours, and \"nearest\" is not \"relevant\".\n   * Ask a corpus of maintenance policy about the dining hall menu and it hands back the five least\n   * unrelated paragraphs it has, each with a score, in confident rank order. Nothing in that result\n   * says the answer is absent, so without a floor the consumer either feeds a model five irrelevant\n   * passages or invents a threshold of its own.\n   *\n   * **This is the only place in the package where a threshold is meaningful, which is why it lives\n   * here and not on `HybridRetriever`.** The score here comes straight from the store's vector\n   * search: a calibrated similarity, comparable across queries and monotonic in how well the passage\n   * matches. A fused score is neither — see the score section on `HybridRetriever`. Threshold each\n   * leg, then fuse; never the other way round.\n   *\n   * Pick the number by measuring, not by taste: score questions you know the corpus answers against\n   * questions you know it does not, and put the floor in the gap between the two populations. It is\n   * specific to the embedding model and the distance metric, so it does not survive changing either.\n   * Left unset nothing is dropped, which is the previous behaviour exactly.\n   */\n  minScore?: number;\n}\n\n/**\n * Bridges an {@link EmbeddingProvider} + {@link VectorStore} into the core {@link Retriever} SPI:\n * embed the query, then vector-search. This is what you wire as the agent's retriever (as a tool\n * via `createRetrievalTool`, or into `AgentModule.forRoot({ retrieval })` for inject mode).\n */\nexport class EmbeddingRetriever implements Retriever {\n  constructor(\n    private readonly embedder: EmbeddingProvider,\n    private readonly store: VectorStore,\n    private readonly options: EmbeddingRetrieverOptions = {},\n  ) {}\n\n  /** Telemetry self-description — the dense strategy, over whatever store it was handed. */\n  describeRetrieval(): RetrievalDescriptor {\n    return { retriever: 'embedding', ...describeSource(this.store) };\n  }\n\n  async retrieve(query: string, options: RetrieveOptions = {}): Promise<Passage[]> {\n    const [embedding] = await this.embedder.embed([query]);\n    if (embedding === undefined) {\n      return [];\n    }\n    const passages = await this.store.search(embedding, {\n      topK: options.topK ?? 5,\n      ...(options.filter !== undefined ? { filter: options.filter } : {}),\n    });\n    const { minScore } = this.options;\n    // Applied here rather than pushed into the store's query: not every backend can express \"score\n    // above X\" in the same call as its KNN search, and filtering after keeps the floor byte-identical\n    // across all three adapters instead of subtly engine-specific. It also keeps `topK` meaning \"ask\n    // the store for this many\", so a floor never silently turns into a smaller search.\n    return minScore === undefined\n      ? passages\n      : passages.filter((passage) => passage.score >= minScore);\n  }\n}\n","import type { Passage, RetrieveOptions, Retriever } from '@dudousxd/nestjs-agent-core';\nimport { matchesFilter } from './filter.js';\nimport type { ChunkRecord } from './ingest.js';\nimport type { RetrievalDescriptor } from './retrieval-descriptor.js';\nimport { documentIdOf } from './vector-store.js';\n\nexport interface KeywordRetrieverOptions {\n  /** BM25 term-frequency saturation. Default 1.5. */\n  k1?: number;\n  /** BM25 length normalization, 0 (off) … 1 (full). Default 0.75. */\n  b?: number;\n}\n\ninterface IndexedDoc {\n  record: ChunkRecord;\n  /** term → frequency within this doc. */\n  frequencies: Map<string, number>;\n  length: number;\n}\n\n/**\n * An in-memory BM25 lexical retriever — the keyword half of hybrid search. Feed it the SAME\n * {@link ChunkRecord}s you upsert into the vector store (from `chunkDocuments`) so their chunk ids\n * line up and `HybridRetriever` can fuse the two rankings. Full BM25: idf, term-frequency saturation\n * (`k1`), and document-length normalization (`b`).\n *\n * Because it holds its OWN copy of each chunk's text, it needs the same delete-sync as the vector\n * store: whenever you call {@link import('./vector-store.js').VectorStore.remove}, call\n * {@link KeywordRetriever.remove} with the same document id. Skipping it leaves the document\n * lexically retrievable — `retrieve` would keep returning the removed passage's full text.\n */\nexport class KeywordRetriever implements Retriever {\n  private readonly docs = new Map<string, IndexedDoc>();\n  private readonly documentFrequency = new Map<string, number>();\n  private totalLength = 0;\n  private readonly k1: number;\n  private readonly b: number;\n\n  constructor(options: KeywordRetrieverOptions = {}) {\n    this.k1 = options.k1 ?? 1.5;\n    this.b = options.b ?? 0.75;\n  }\n\n  /**\n   * Telemetry self-description. No `store`: this retriever holds its own copy of the corpus in\n   * process, so attributing its retrievals to whichever vector store happens to hold the same chunks\n   * would credit a backend that was never queried.\n   */\n  describeRetrieval(): RetrievalDescriptor {\n    return { retriever: 'keyword' };\n  }\n\n  /** How many chunks are currently indexed. */\n  get size(): number {\n    return this.docs.size;\n  }\n\n  /** Index (or re-index) records. Re-adding an existing id replaces its posting and updates stats. */\n  add(records: ChunkRecord[]): void {\n    for (const record of records) {\n      this.removeChunk(record.id);\n      const tokens = tokenize(record.text);\n      const frequencies = new Map<string, number>();\n      for (const token of tokens) {\n        frequencies.set(token, (frequencies.get(token) ?? 0) + 1);\n      }\n      for (const term of frequencies.keys()) {\n        this.documentFrequency.set(term, (this.documentFrequency.get(term) ?? 0) + 1);\n      }\n      this.docs.set(record.id, { record, frequencies, length: tokens.length });\n      this.totalLength += tokens.length;\n    }\n  }\n\n  /**\n   * Forget a source document — every chunk whose id is `${documentId}` or `${documentId}#<n>`, the\n   * same id scheme (and the same {@link documentIdOf} collapse) the vector stores use for their\n   * `remove`. The keyword half of a hybrid index keeps its own copy of the chunk text, so a document\n   * dropped from the vector store stays fully retrievable here until this is called. Unknown ids are\n   * a no-op.\n   */\n  remove(documentId: string): void {\n    for (const id of [...this.docs.keys()]) {\n      if (id === documentId || documentIdOf(id) === documentId) {\n        this.removeChunk(id);\n      }\n    }\n  }\n\n  /** Drop every indexed chunk, resetting the corpus statistics with it. */\n  clear(): void {\n    this.docs.clear();\n    this.documentFrequency.clear();\n    this.totalLength = 0;\n  }\n\n  /** Drop ONE chunk by its exact id, decrementing the corpus statistics it contributed. */\n  private removeChunk(id: string): void {\n    const existing = this.docs.get(id);\n    if (existing === undefined) {\n      return;\n    }\n    for (const term of existing.frequencies.keys()) {\n      const next = (this.documentFrequency.get(term) ?? 1) - 1;\n      if (next <= 0) {\n        this.documentFrequency.delete(term);\n      } else {\n        this.documentFrequency.set(term, next);\n      }\n    }\n    this.totalLength -= existing.length;\n    this.docs.delete(id);\n  }\n\n  async retrieve(query: string, options: RetrieveOptions = {}): Promise<Passage[]> {\n    const total = this.docs.size;\n    if (total === 0) {\n      return [];\n    }\n    const averageLength = this.totalLength / total;\n    const queryTerms = new Set(tokenize(query));\n    const scored: Passage[] = [];\n    for (const { record, frequencies, length } of this.docs.values()) {\n      if (options.filter !== undefined && !matchesFilter(record.metadata, options.filter)) {\n        continue;\n      }\n      let score = 0;\n      for (const term of queryTerms) {\n        const termFrequency = frequencies.get(term);\n        if (termFrequency === undefined) {\n          continue;\n        }\n        const df = this.documentFrequency.get(term) ?? 0;\n        const idf = Math.log(1 + (total - df + 0.5) / (df + 0.5));\n        const denominator =\n          termFrequency + this.k1 * (1 - this.b + (this.b * length) / averageLength);\n        score += idf * ((termFrequency * (this.k1 + 1)) / denominator);\n      }\n      if (score > 0) {\n        scored.push({\n          id: record.id,\n          text: record.text,\n          score,\n          ...(record.source !== undefined ? { source: record.source } : {}),\n          ...(record.metadata !== undefined ? { metadata: record.metadata } : {}),\n        });\n      }\n    }\n    return scored.sort((a, b) => b.score - a.score).slice(0, options.topK ?? 5);\n  }\n}\n\nfunction tokenize(text: string): string[] {\n  return text.toLowerCase().match(/[a-z0-9]+/g) ?? [];\n}\n","import type { Passage, RetrieveOptions, Retriever } from '@dudousxd/nestjs-agent-core';\nimport { type RetrievalDescriptor, describeSource } from './retrieval-descriptor.js';\nimport type { LexicalVectorStore } from './vector-store.js';\n\n/**\n * The keyword half of hybrid search, served by the store's own full-text index — the mirror of\n * {@link import('./embedding-retriever.js').EmbeddingRetriever}, which serves the dense half. It\n * holds no state: every query goes to the store, so any process that can reach the store can run\n * lexical search, whether or not it did the ingestion.\n *\n * Compose it exactly like the dense leg:\n *\n * ```ts\n * const retriever = new HybridRetriever([\n *   new EmbeddingRetriever(embedder, store),\n *   new LexicalRetriever(store),\n * ]);\n * ```\n *\n * Both legs read the same chunks from the same index, so their ids line up by construction and\n * `HybridRetriever`'s RRF fuses them without either side needing a score on a common scale.\n *\n * Prefer this over {@link import('./keyword-retriever.js').KeywordRetriever} whenever the store\n * supports it (see {@link import('./vector-store.js').isLexicalVectorStore}) and ingestion and\n * search can run in different processes; `KeywordRetriever` remains the answer for `MemoryVectorStore`\n * and single-process deployments.\n */\nexport class LexicalRetriever implements Retriever {\n  constructor(private readonly store: LexicalVectorStore) {}\n\n  /** Telemetry self-description — the store's own lexical index, so the store is the same one. */\n  describeRetrieval(): RetrievalDescriptor {\n    return { retriever: 'lexical', ...describeSource(this.store) };\n  }\n\n  async retrieve(query: string, options: RetrieveOptions = {}): Promise<Passage[]> {\n    return this.store.searchText(query, {\n      topK: options.topK ?? 5,\n      ...(options.filter !== undefined ? { filter: options.filter } : {}),\n    });\n  }\n}\n","import type { Passage, RetrieveOptions, Retriever } from '@dudousxd/nestjs-agent-core';\nimport { type RetrievalDescriptor, describeSharedSource } from './retrieval-descriptor.js';\n\nexport interface HybridRetrieverOptions {\n  /** RRF constant — larger flattens the rank weighting. Default 60 (the value from the original paper). */\n  k?: number;\n  /** Candidates pulled from each retriever before fusion. Default 20. */\n  fetchTopK?: number;\n  /** Per-retriever multipliers on each RRF contribution (same order as `retrievers`). Default all 1. */\n  weights?: number[];\n}\n\n/**\n * Fuses several retrievers with Reciprocal Rank Fusion — the robust way to combine, say, dense\n * vector search with lexical BM25. RRF scores each passage by `Σ weight / (k + rank)` across the\n * lists it appears in, so it needs no score normalization between incompatible scales (cosine vs\n * BM25). Deduplicates by passage id, so aligned chunk ids from the two retrievers reinforce.\n *\n * ## The score on a fused passage is not a similarity. Do not threshold it.\n *\n * Read this before using `passage.score` for anything other than the order it already produced.\n *\n * Not normalizing between scales is what makes RRF robust, and the price is that the number it\n * emits is a function of **rank alone** — it never sees a similarity at all. Two consequences that\n * bite in practice:\n *\n * - **It is not comparable to the score on a passage from {@link EmbeddingRetriever}**, even though\n *   it arrives in the same field, of the same type, from the same `Retriever` interface. There is no\n *   discriminator; a consumer holding a `Passage[]` cannot tell which kind of number it has. If you\n *   surface scores to a user or a model, know which retriever produced them.\n * - **Its range is narrow, fixed, and says nothing about quality.** Every possible score lies in\n *   `[minWeight / (k + fetchTopK), Σ weights / (k + 1)]` — with the defaults (`k = 60`,\n *   `fetchTopK = 20`, two unweighted legs) that is `[0.0125, 0.0328]`. A perfect match and the\n *   least-bad member of a set of terrible matches both come back around `0.016`.\n *\n * The second point is why a relevance floor cannot live here. What the fused score actually measures\n * is how strongly the legs *agree* — and agreement tracks nothing about correctness. When both legs\n * return the same nearest nothing for an unanswerable query, they reinforce it to the ceiling, the\n * same ceiling a unanimous correct answer gets. Measured on one corpus, the dense leg alone\n * separated cleanly (weakest real answer 0.244, loudest absent-topic answer 0.143) while those same\n * queries after fusion scored 0.032 and 0.033 — inverted. On another corpus the inversion may not\n * appear; what does not change is that both numbers live in a band roughly one part in fifty wide,\n * with no room for a threshold to mean anything.\n *\n * So: put the floor on the legs, with {@link EmbeddingRetrieverOptions.minScore}, and fuse what\n * survives. `HybridRetriever` deliberately has no `minScore` of its own; a threshold option here\n * would be an invitation to apply it to a number that cannot support one.\n */\nexport class HybridRetriever implements Retriever {\n  constructor(\n    private readonly retrievers: Retriever[],\n    private readonly options: HybridRetrieverOptions = {},\n  ) {}\n\n  /** Telemetry self-description — the store only when every leg agrees; see `describeSharedSource`. */\n  describeRetrieval(): RetrievalDescriptor {\n    return { retriever: 'hybrid', ...describeSharedSource(this.retrievers) };\n  }\n\n  async retrieve(query: string, options: RetrieveOptions = {}): Promise<Passage[]> {\n    const k = this.options.k ?? 60;\n    const fetchTopK = this.options.fetchTopK ?? 20;\n    const weights = this.options.weights;\n    const lists = await Promise.all(\n      this.retrievers.map((retriever) =>\n        retriever.retrieve(query, {\n          topK: fetchTopK,\n          ...(options.filter !== undefined ? { filter: options.filter } : {}),\n        }),\n      ),\n    );\n\n    const fused = new Map<string, { passage: Passage; score: number }>();\n    lists.forEach((list, listIndex) => {\n      const weight = weights?.[listIndex] ?? 1;\n      list.forEach((passage, rank) => {\n        const contribution = weight / (k + rank + 1);\n        const existing = fused.get(passage.id);\n        if (existing !== undefined) {\n          existing.score += contribution;\n        } else {\n          fused.set(passage.id, { passage, score: contribution });\n        }\n      });\n    });\n\n    return [...fused.values()]\n      .sort((a, b) => b.score - a.score)\n      .slice(0, options.topK ?? 5)\n      .map((entry) => ({ ...entry.passage, score: entry.score }));\n  }\n}\n","import type { Passage, Reranker, RetrieveOptions, Retriever } from '@dudousxd/nestjs-agent-core';\nimport { type RetrievalDescriptor, describeSource } from './retrieval-descriptor.js';\n\nexport interface RerankingRetrieverOptions {\n  /** How many candidates to pull from the base retriever before reranking. Default 20. */\n  fetchTopK?: number;\n}\n\n/**\n * Two-stage retrieval: over-fetch cheap candidates from a base `Retriever`, then reorder them with a\n * stronger {@link Reranker} and keep the top few. The standard precision boost — a fast first stage\n * casts a wide net, a slow accurate second stage sharpens it. Composes over ANY retriever (vector,\n * hybrid, keyword), and is itself a `Retriever`.\n */\nexport class RerankingRetriever implements Retriever {\n  constructor(\n    private readonly base: Retriever,\n    private readonly reranker: Reranker,\n    private readonly options: RerankingRetrieverOptions = {},\n  ) {}\n\n  /** Telemetry self-description — the two-stage strategy, over the base's store. */\n  describeRetrieval(): RetrievalDescriptor {\n    return { retriever: 'reranking', ...describeSource(this.base) };\n  }\n\n  async retrieve(query: string, options: RetrieveOptions = {}): Promise<Passage[]> {\n    const candidates = await this.base.retrieve(query, {\n      topK: this.options.fetchTopK ?? 20,\n      ...(options.filter !== undefined ? { filter: options.filter } : {}),\n    });\n    return this.reranker.rerank(query, candidates, { topK: options.topK ?? 5 });\n  }\n}\n","import type { Passage, RetrieveOptions, Retriever } from '@dudousxd/nestjs-agent-core';\nimport { type RetrievalDescriptor, describeSource } from './retrieval-descriptor.js';\n\n/**\n * Wraps a `Retriever` so every `retrieve` call ANDs a fixed metadata `filter` on top of whatever the\n * caller passes — the owner/tenant-scoping primitive. `new FilteredRetriever(base, { ownerId })` only\n * ever returns that owner's passages, so a shared vector store serves per-user / per-tenant RAG\n * without the agent (or a crafted query) reaching across the boundary.\n *\n * The fixed filter takes precedence on key conflicts: a caller can narrow further but cannot widen\n * past the scope. Composes over ANY retriever (vector, hybrid, reranked) and is itself a `Retriever`.\n */\nexport class FilteredRetriever implements Retriever {\n  constructor(\n    private readonly base: Retriever,\n    private readonly filter: Record<string, unknown>,\n  ) {}\n\n  /** Telemetry self-description — this scope, over the base's store. */\n  describeRetrieval(): RetrievalDescriptor {\n    return { retriever: 'filtered', ...describeSource(this.base) };\n  }\n\n  async retrieve(query: string, options: RetrieveOptions = {}): Promise<Passage[]> {\n    return this.base.retrieve(query, {\n      ...options,\n      filter: { ...options.filter, ...this.filter },\n    });\n  }\n}\n","import type { EmbeddingProvider } from '@dudousxd/nestjs-agent-core';\nimport { type ChunkOptions, chunkText } from './chunk.js';\nimport type { VectorRecord, VectorStore } from './vector-store.js';\n\n/** A source document to ingest. `id` scopes the chunk ids (`${id}#${n}`); `source` is the citation. */\nexport interface IngestDocument {\n  id: string;\n  text: string;\n  source?: string;\n  metadata?: Record<string, unknown>;\n}\n\n/** A chunked, not-yet-embedded record. Feed the same array to a vector store AND a keyword index so\n * both retrievers key on identical chunk ids (which is what lets hybrid fusion line them up). */\nexport interface ChunkRecord {\n  id: string;\n  text: string;\n  source?: string;\n  metadata?: Record<string, unknown>;\n}\n\nexport interface IngestChunksOptions {\n  embedder: EmbeddingProvider;\n  store: VectorStore;\n}\n\nexport interface IngestOptions extends ChunkOptions, IngestChunksOptions {}\n\n/**\n * Split documents into chunk records. Chunk ids are `${doc.id}#${index}`, so re-chunking the same\n * document produces the same ids (upsert overwrites in place rather than duplicating).\n */\nexport function chunkDocuments(\n  documents: IngestDocument[],\n  options: ChunkOptions = {},\n): ChunkRecord[] {\n  const chunks: ChunkRecord[] = [];\n  for (const document of documents) {\n    chunkText(document.text, options).forEach((text, index) => {\n      chunks.push({\n        id: `${document.id}#${index}`,\n        text,\n        ...(document.source !== undefined ? { source: document.source } : {}),\n        ...(document.metadata !== undefined ? { metadata: document.metadata } : {}),\n      });\n    });\n  }\n  return chunks;\n}\n\n/** Embed pre-chunked records (one batched `embed`) and upsert them. Returns the record count. */\nexport async function ingestChunks(\n  chunks: ChunkRecord[],\n  options: IngestChunksOptions,\n): Promise<number> {\n  if (chunks.length === 0) {\n    return 0;\n  }\n  const embeddings = await options.embedder.embed(chunks.map((chunk) => chunk.text));\n  const records: VectorRecord[] = chunks.map((chunk, index) => ({\n    ...chunk,\n    embedding: embeddings[index] ?? [],\n  }));\n  await options.store.upsert(records);\n  return records.length;\n}\n\n/** Chunk → embed → upsert in one call. For hybrid search, use {@link chunkDocuments} +\n * {@link ingestChunks} and feed the same chunks to a {@link import('./keyword-retriever.js').KeywordRetriever}. */\nexport async function ingestDocuments(\n  documents: IngestDocument[],\n  options: IngestOptions,\n): Promise<number> {\n  return ingestChunks(chunkDocuments(documents, options), options);\n}\n","import { AsyncLocalStorage } from 'node:async_hooks';\nimport type { Passage, RetrieveOptions, Retriever } from '@dudousxd/nestjs-agent-core';\nimport { channelName, emit, getChannel } from '@dudousxd/nestjs-diagnostics';\nimport {\n  type RetrievalDescriptor,\n  type RetrieverKind,\n  type VectorStoreKind,\n  describeRetrieval,\n} from './retrieval-descriptor.js';\n\n/**\n * Retrieval telemetry: one diagnostics event per retrieval, carrying how long it took, how much came\n * back, how good it was, and what served it.\n *\n * Until this existed, retrieval reached Telescope only as the *tool call* that wrapped it (see\n * `retrieval-tool.ts`), which says a retrieval happened and nothing else. The questions an operator\n * actually arrives with — is retrieval slow, is it returning nothing, is one collection colder than\n * the rest, did the scores collapse after a model swap — are all invisible in a tool-call row,\n * because a tool call that returns zero passages and one that returns five perfect ones are the same\n * row with the same `ok` status.\n *\n * ## One seam, not six\n *\n * Instrumentation is a WRAPPER over the core `Retriever` SPI ({@link instrumentRetriever}), not code\n * inside each retriever. Every retriever in this package — and every retriever outside it — is the\n * same one-method interface, so one wrapper covers all of them, including ones this package has\n * never heard of. The alternative, an `emit` inside each of the six `retrieve` methods, would have\n * had to be repeated in each, skipped by third-party retrievers entirely, and would have double- and\n * triple-counted the composed ones (a hybrid over two legs emitting three events for one retrieval).\n *\n * ## How a composed retrieval reports\n *\n * **The outermost instrumented retriever in a call tree emits; anything instrumented inside it stays\n * silent.** A retrieval is one question the caller asked, so it is one event no matter how many\n * retrievers cooperated to answer it: `RerankingRetriever` over a `HybridRetriever` over a dense and\n * a lexical leg is ONE retrieval, reported as `retriever: 'reranking'` with the duration of the\n * whole thing and the scores the caller actually got back.\n *\n * The suppression is enforced with an {@link AsyncLocalStorage} flag rather than by asking hosts to\n * wrap carefully, because the wrapping that double-counts is the natural one: a host that wraps its\n * top-level retriever and *also* wraps the dense leg it shares with another code path has not made a\n * mistake, and would otherwise get two events per retrieval, a zero-hit rate computed over a mixture\n * of legs and composites, and a retrieval count roughly twice its query count.\n *\n * ## Opt-out safety, and what the hot path pays\n *\n * The event goes out on `aviary:rag:retrieval` via `@dudousxd/nestjs-diagnostics`, whose `emit` is\n * gated on `channel.hasSubscribers` and never throws. This wrapper checks that same gate BEFORE it\n * does anything at all — no clock read, no `AsyncLocalStorage.run`, no score arithmetic — and\n * delegates straight through when nothing is listening. A host that wires this package without\n * Telescope (or any subscriber) pays two `Map` lookups and a boolean per retrieval, and nothing else\n * changes: the wrapper returns the base retriever's passages verbatim, and rethrows its errors\n * unchanged.\n *\n * ## Why this channel is not merged into the typed `ChannelRegistry`\n *\n * `@dudousxd/nestjs-agent-rag-media` already emits `media.ingested`/`media.removed`/`media.skipped`/\n * `media.failed` on the same `rag` lib, and flip's host app emits `rag:search` on it. Declaring\n * `ChannelRegistry['rag'] = { retrieval: RagRetrievalEvent }` here would narrow `EventOf<'rag'>` to\n * this one key process-wide and turn every one of those sibling emits into a compile error in any\n * project that installs both packages. The payload stays typed where it matters — {@link emitRagRetrieval}\n * takes {@link RagRetrievalEvent} — and the wire contract is documented below instead.\n */\n\n/** The diagnostics lib segment. Shared with `@dudousxd/nestjs-agent-rag-media`'s `media.*` events. */\nexport const RAG_DIAGNOSTIC_LIB = 'rag';\n\n/** The diagnostics event segment. */\nexport const RAG_RETRIEVAL_EVENT = 'retrieval';\n\n/**\n * The full channel name a subscriber listens on: `aviary:rag:retrieval`. This is the wire contract —\n * `@dudousxd/nestjs-agent-telescope` subscribes to this exact string rather than importing this\n * package, which is what keeps the telescope extension free of a dependency on the retrieval stack\n * (and lets a host that uses neither still observe retrieval with a bare `diagnostics_channel`\n * subscription).\n */\nexport const RAG_RETRIEVAL_CHANNEL = channelName(RAG_DIAGNOSTIC_LIB, RAG_RETRIEVAL_EVENT);\n\n/**\n * The payload of one retrieval event. Counts, durations, kinds and scores only — never the query\n * text and never passage text. Both are user content, and this lands in an ops store with a short\n * retention window and a Slack-facing redaction budget; everything here is safe to put on a\n * dashboard and is what tells the failure modes apart anyway.\n *\n * The DURATION is not in here: it rides the envelope (`emit`'s `opts.durationMs`), which is the field\n * Telescope's OTel exporter turns into a latency histogram. Putting it in the payload instead would\n * have made retrieval latency a number somebody reads out of a JSON blob rather than a graph.\n */\nexport interface RagRetrievalEvent {\n  /** Which strategy answered — the OUTERMOST one, for a composed retriever. */\n  retriever: RetrieverKind;\n  /** Which backend held the chunks. Absent for an in-process retriever, or when legs disagree. */\n  store?: VectorStoreKind;\n  /** Store namespace (pg table / RediSearch index), or the host's logical collection. */\n  collection?: string;\n  /** What the caller asked for, so `chunks < topK` is readable as \"the corpus ran out\". */\n  topK: number;\n  /** How many passages came back. */\n  chunks: number;\n  /**\n   * `chunks === 0`. Carried as its own flag rather than left to be derived, because the zero-hit RATE\n   * is the headline number and deriving it means every consumer re-deriving the same predicate.\n   */\n  zeroHit: boolean;\n  /** Best score in the result, rounded to 4dp. Absent on a zero-hit. */\n  topScore?: number;\n  /** Mean score across the result, rounded to 4dp. Absent on a zero-hit. */\n  meanScore?: number;\n  /**\n   * The retrieval threw. Reported rather than dropped because a failed retrieval and an empty one\n   * look identical from the agent's side — both become \"I couldn't find anything\" — so a channel\n   * that only carried successes would go quiet exactly when retrieval broke.\n   */\n  failed: boolean;\n  /** The error message, when `failed`. */\n  error?: string;\n}\n\n/** Publish one retrieval event. `durationMs` rides the envelope; see {@link RagRetrievalEvent}. */\nexport function emitRagRetrieval(event: RagRetrievalEvent, durationMs: number): void {\n  emit(RAG_DIAGNOSTIC_LIB, RAG_RETRIEVAL_EVENT, event, { durationMs });\n}\n\nexport interface InstrumentRetrieverOptions {\n  /**\n   * Override the auto-detected {@link RetrievalDescriptor}, field by field. Needed for a retriever or\n   * store from outside this package (which reports `retriever: 'unknown'` and no store), and for a\n   * host that wants its own naming.\n   */\n  describe?: RetrievalDescriptor;\n  /**\n   * The logical collection this retrieval searched, when the store namespace is not it. Pass a\n   * function to read it off the call's metadata filter — the multi-tenant shape, where one index\n   * holds every collection and the filter picks one:\n   *\n   * ```ts\n   * instrumentRetriever(retriever, {\n   *   collection: (filter) => (typeof filter?.collectionId === 'string' ? filter.collectionId : undefined),\n   * })\n   * ```\n   *\n   * Returning `undefined` falls back to the store namespace, which is the right answer for a query\n   * scoped to many collections at once: a breakdown panel needs ONE label per retrieval, and\n   * inventing a synthetic `\"a+b+c\"` bucket would produce a chart whose slices are combinations\n   * rather than collections.\n   */\n  collection?: string | ((filter: Record<string, unknown> | undefined) => string | undefined);\n}\n\n/**\n * The default a retriever falls back to when the caller names no `topK` — every retriever in this\n * package uses `options.topK ?? 5`, so reporting anything else here would make `chunks < topK`\n * misread as truncation on exactly the calls that did not ask for a limit.\n */\nconst DEFAULT_TOP_K = 5;\n\n/**\n * Set for the duration of an instrumented `retrieve`, so an instrumented retriever running INSIDE\n * another one knows it is a leg and stays silent. See the composed-retrieval section above.\n */\nconst inRetrieval = new AsyncLocalStorage<true>();\n\n/** Round to 4dp — enough to see a score distribution move, short enough to keep the payload small. */\nfunction round4(value: number): number {\n  return Math.round(value * 10_000) / 10_000;\n}\n\n/** Top + mean score, skipping any passage whose `score` is not a finite number. */\nfunction scoreStats(passages: Passage[]): { topScore?: number; meanScore?: number } {\n  const scores = passages.map((passage) => passage.score).filter((score) => Number.isFinite(score));\n  if (scores.length === 0) {\n    return {};\n  }\n  const sum = scores.reduce((total, score) => total + score, 0);\n  return { topScore: round4(Math.max(...scores)), meanScore: round4(sum / scores.length) };\n}\n\nclass InstrumentedRetriever implements Retriever {\n  constructor(\n    private readonly base: Retriever,\n    private readonly options: InstrumentRetrieverOptions = {},\n  ) {}\n\n  /** Transparent to detection: wrapping a retriever must not turn it into an `unknown` one. */\n  describeRetrieval(): RetrievalDescriptor {\n    return { ...describeRetrieval(this.base), ...this.options.describe };\n  }\n\n  async retrieve(query: string, options: RetrieveOptions = {}): Promise<Passage[]> {\n    // Both gates before any work: nothing subscribed, or we are a leg of an outer instrumented\n    // retrieval that will report the whole thing itself.\n    if (!getChannel(RAG_DIAGNOSTIC_LIB, RAG_RETRIEVAL_EVENT).hasSubscribers) {\n      return this.base.retrieve(query, options);\n    }\n    if (inRetrieval.getStore() === true) {\n      return this.base.retrieve(query, options);\n    }\n\n    const descriptor = this.describeRetrieval();\n    const topK = options.topK ?? DEFAULT_TOP_K;\n    const startedAt = Date.now();\n    try {\n      const passages = await inRetrieval.run(true, () => this.base.retrieve(query, options));\n      emitRagRetrieval(\n        {\n          retriever: descriptor.retriever ?? 'unknown',\n          ...(descriptor.store !== undefined ? { store: descriptor.store } : {}),\n          ...this.collectionOf(options.filter, descriptor),\n          topK,\n          chunks: passages.length,\n          zeroHit: passages.length === 0,\n          ...scoreStats(passages),\n          failed: false,\n        },\n        Date.now() - startedAt,\n      );\n      return passages;\n    } catch (error) {\n      emitRagRetrieval(\n        {\n          retriever: descriptor.retriever ?? 'unknown',\n          ...(descriptor.store !== undefined ? { store: descriptor.store } : {}),\n          ...this.collectionOf(options.filter, descriptor),\n          topK,\n          chunks: 0,\n          zeroHit: true,\n          failed: true,\n          error: error instanceof Error ? error.message : String(error),\n        },\n        Date.now() - startedAt,\n      );\n      throw error;\n    }\n  }\n\n  /** The host's collection for this call, else the store namespace, else nothing. */\n  private collectionOf(\n    filter: Record<string, unknown> | undefined,\n    descriptor: RetrievalDescriptor,\n  ): { collection?: string } {\n    const { collection } = this.options;\n    const resolved =\n      typeof collection === 'function' ? collection(filter) : (collection ?? descriptor.collection);\n    return resolved !== undefined ? { collection: resolved } : {};\n  }\n}\n\n/**\n * Wrap a retriever so every `retrieve` publishes a {@link RagRetrievalEvent} on\n * {@link RAG_RETRIEVAL_CHANNEL}. Wrap the retriever you actually hand to the agent — the outermost\n * one — and nothing else needs changing:\n *\n * ```ts\n * const retriever = instrumentRetriever(\n *   new HybridRetriever([new EmbeddingRetriever(embedder, store), new LexicalRetriever(store)]),\n * );\n * ```\n *\n * {@link createRetrievalTool} already does this for the tool it builds, so agentic retrieval is\n * instrumented with no host change at all; call this directly for inject-mode retrieval\n * (`AgentModule.forRoot({ retrieval })`) or for a host that calls `retrieve` itself. Wrapping twice\n * is harmless — see the composed-retrieval section above.\n */\nexport function instrumentRetriever(\n  retriever: Retriever,\n  options: InstrumentRetrieverOptions = {},\n): Retriever {\n  return new InstrumentedRetriever(retriever, options);\n}\n","import type { Passage, Retriever, ToolHandler, ToolSpec } from '@dudousxd/nestjs-agent-core';\nimport type { StandardSchemaV1 } from '@standard-schema/spec';\nimport { type InstrumentRetrieverOptions, instrumentRetriever } from './retrieval-telemetry.js';\n\nexport interface RetrievalToolOptions {\n  /** Tool name the model sees. Default `search_knowledge`. */\n  name?: string;\n  description?: string;\n  /** Passages per search. Default lets the retriever decide (typically 5). */\n  topK?: number;\n  /**\n   * Retrieval telemetry (`aviary:rag:retrieval` — duration, chunk count, score distribution, store\n   * and collection). **On by default**, because this tool is the once-per-retrieval seam in agentic\n   * mode: instrumenting here is what makes the RAG panels work for a host that only ever calls\n   * `createRetrievalTool`, with no wiring at all. It costs nothing when nobody subscribes (see\n   * {@link instrumentRetriever}), and cannot double-count when the host has already wrapped the\n   * retriever itself.\n   *\n   * Pass `false` to opt a single tool out — a host that reports retrieval its own way, or one whose\n   * corpus is small enough that the events are noise.\n   */\n  telemetry?: boolean | InstrumentRetrieverOptions;\n}\n\n/** A functional tool (`{ spec, handler }`) — pass it to nestjs `provideAgentTool`. */\nexport interface RetrievalTool {\n  spec: ToolSpec;\n  handler: ToolHandler;\n}\n\nfunction isQueryInput(value: unknown): value is { query: string } {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    'query' in value &&\n    typeof (value as Record<'query', unknown>).query === 'string'\n  );\n}\n\n/** A hand-rolled Standard Schema for `{ query: string }` — keeps this package validation-lib-free. */\nconst querySchema: StandardSchemaV1<{ query: string }> = {\n  '~standard': {\n    version: 1,\n    vendor: 'nestjs-agent-rag',\n    validate(value: unknown) {\n      return isQueryInput(value)\n        ? { value: { query: value.query } }\n        : { issues: [{ message: 'retrieval tool expects { query: string }' }] };\n    },\n  },\n};\n\n/**\n * Builds the agentic-retrieval tool: a `read`-kind `search_knowledge(query)` the model calls when it\n * decides it needs context. Its output `{ passages }` persists as the tool call's result, so sources\n * flow to the frontend and telescope through the normal tool-call machinery (the citation surface).\n *\n * The retrieval ITSELF is also instrumented (`aviary:rag:retrieval`) unless `telemetry: false` — the\n * tool-call row says a retrieval happened, the retrieval event says how long it took, how much came\n * back and how good it was. See {@link instrumentRetriever}.\n *\n * ```ts\n * providers: [provideAgentTool(createRetrievalTool(retriever))]\n * ```\n */\nexport function createRetrievalTool(\n  retriever: Retriever,\n  options: RetrievalToolOptions = {},\n): RetrievalTool {\n  const topK = options.topK;\n  const { telemetry = true } = options;\n  const instrumented =\n    telemetry === false\n      ? retriever\n      : instrumentRetriever(retriever, telemetry === true ? {} : telemetry);\n  return {\n    spec: {\n      name: options.name ?? 'search_knowledge',\n      kind: 'read',\n      description:\n        options.description ??\n        'Search the knowledge base for passages relevant to a query. Returns passages with their source for citation.',\n      inputSchema: querySchema,\n    },\n    handler: {\n      async execute(input: unknown): Promise<{ passages: Passage[] }> {\n        if (!isQueryInput(input)) {\n          throw new Error('retrieval tool expects { query: string }');\n        }\n        const passages = await instrumented.retrieve(\n          input.query,\n          topK !== undefined ? { topK } : {},\n        );\n        return { passages };\n      },\n    },\n  };\n}\n"],"mappings":"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","names":["chunkText","text","options","chunkSize","overlap","normalized","trim","length","separator","undefined","chunkByRecord","chunks","start","end","Math","min","breakAt","window","slice","boundary","max","lastIndexOf","chunk","push","current","flush","record","split","trimmed","candidate","isLexicalVectorStore","store","searchText","UnsafeRemovalError","Error","reason","message","name","chunkIndexOf","chunkId","match","exec","undefined","Number","documentIdOf","replace","splitMetadataPatch","patch","set","remove","key","value","Object","entries","push","undefined","isEmptyMetadataPatch","keys","length","applyMetadataPatch","metadata","next","matchesFilter","metadata","filter","entries","Object","undefined","length","every","key","expected","Array","isArray","actual","some","value","includes","filterMatchesNothing","values","MemoryVectorStore","records","Map","describeRetrieval","store","upsert","record","set","id","remove","documentId","keys","documentIdOf","delete","updateMetadata","patch","isEmptyMetadataPatch","updated","metadata","applyMetadataPatch","listDocuments","filter","documents","values","undefined","matchesFilter","has","listChunks","options","chunks","push","index","chunkIndexOf","text","sort","a","b","offset","limit","slice","listDocumentIds","filterMatchesNothing","Set","add","removeMany","documentIds","length","wanted","removeWhere","Object","UnsafeRemovalError","removed","countChunks","count","search","embedding","scored","score","cosineSimilarity","source","topK","dot","normA","normB","Math","min","valueA","valueB","denominator","sqrt","NUL_BYTE","String","fromCharCode","stripNulBytes","value","includes","split","join","Array","isArray","map","item","proto","Object","getPrototypeOf","prototype","fromEntries","entries","key","entry","PgVectorStore","table","dimensions","client","options","describeRetrieval","store","collection","ensureSchema","query","upsert","records","record","id","text","source","undefined","metadata","JSON","stringify","toVectorLiteral","embedding","remove","documentId","DOCUMENT_ID_FROM_CHUNK","updateMetadata","patch","isEmptyMetadataPatch","set","splitMetadataPatch","rows","length","listDocuments","filter","where","buildWhere","sql","params","row","doc_id","listChunks","CHUNK_INDEX_FROM_ID","limit","push","offset","index","Number","chunk_index","listDocumentIds","filterMatchesNothing","removeMany","documentIds","removeWhere","keys","UnsafeRemovalError","countChunks","count","search","vector","topK","score","startIndex","stripped","clauses","scalar","keyParam","arrParam","RedisVectorSchemaMismatchError","Error","index","field","expected","actual","remedy","name","RedisVectorStore","prefix","dimensions","filterableFields","lexicalScorer","client","options","describeRetrieval","store","collection","ensureSchema","info","sendCommand","createIndex","reconcileSchema","attributes","parseIndexAttributes","size","vector","get","undefined","missing","existing","push","type","schema","String","upsert","records","record","args","id","text","encodeVector","embedding","source","metadata","JSON","stringify","value","encodeTag","remove","documentId","keys","chunkKeys","length","updateMetadata","patch","isEmptyMetadataPatch","updated","key","raw","current","parseMetadata","toStr","next","applyMetadataPatch","stale","Set","bare","exists","Number","add","pattern","escapeGlob","cursor","reply","page","parseScanReply","listChunks","ordered","map","slice","entry","chunkIndexOf","sort","a","b","offset","limit","chunks","fields","Array","isArray","listDocuments","filter","filterMatchesNothing","query","buildFilter","documents","Map","batchSize","passages","parseSearchReply","passage","documentIdOf","has","set","values","listDocumentIds","SCAN_PAGE","parseSearchKeys","stripPrefix","removeMany","documentIds","wanted","pending","DELETE_BATCH","removeWhere","Object","UnsafeRemovalError","unindexed","includes","named","join","declared","removed","deleted","isFinite","countChunks","parseSearchTotal","search","topK","searchText","terms","tokenizeQuery","filterQuery","textQuery","startsWith","results","readId","total","total_results","readInfoField","readKeyValues","attribute","identifier","dim","toUpperCase","toLowerCase","entries","Buffer","from","Float32Array","buffer","clauses","alternation","escapeTag","match","replace","char","rawKeys","isBuffer","toString","scoreSource","stride","rawFields","attrs","inlineScore","toPassage","result","readAttributes","readScore","score","extra_attributes","rawId","vector_score","metadata_json","parsed","parse","describesRetrieval","value","Reflect","get","describeRetrieval","candidate","describeSource","base","retriever","_ignored","source","describeSharedSource","legs","sources","map","first","undefined","agrees","every","store","collection","EmbeddingRetriever","embedder","store","options","describeRetrieval","retriever","describeSource","retrieve","query","embedding","embed","undefined","passages","search","topK","filter","minScore","passage","score","KeywordRetriever","docs","Map","documentFrequency","totalLength","k1","b","options","describeRetrieval","retriever","size","add","records","record","removeChunk","id","tokens","tokenize","text","frequencies","token","set","get","term","keys","length","remove","documentId","documentIdOf","clear","existing","undefined","next","delete","retrieve","query","total","averageLength","queryTerms","Set","scored","values","filter","matchesFilter","metadata","score","termFrequency","df","idf","Math","log","denominator","push","source","sort","a","slice","topK","toLowerCase","match","LexicalRetriever","store","describeRetrieval","retriever","describeSource","retrieve","query","options","searchText","topK","filter","undefined","HybridRetriever","retrievers","options","describeRetrieval","retriever","describeSharedSource","retrieve","query","k","fetchTopK","weights","lists","Promise","all","map","topK","filter","undefined","fused","Map","forEach","list","listIndex","weight","passage","rank","contribution","existing","get","id","score","set","values","sort","a","b","slice","entry","RerankingRetriever","base","reranker","options","describeRetrieval","retriever","describeSource","retrieve","query","candidates","topK","fetchTopK","filter","undefined","rerank","FilteredRetriever","base","filter","describeRetrieval","retriever","describeSource","retrieve","query","options","chunkDocuments","documents","options","chunks","document","chunkText","text","forEach","index","push","id","source","undefined","metadata","ingestChunks","length","embeddings","embedder","embed","map","chunk","records","embedding","store","upsert","ingestDocuments","AsyncLocalStorage","channelName","emit","getChannel","RAG_DIAGNOSTIC_LIB","RAG_RETRIEVAL_EVENT","RAG_RETRIEVAL_CHANNEL","channelName","emitRagRetrieval","event","durationMs","emit","DEFAULT_TOP_K","inRetrieval","AsyncLocalStorage","round4","value","Math","round","scoreStats","passages","scores","map","passage","score","filter","Number","isFinite","length","sum","reduce","total","topScore","max","meanScore","InstrumentedRetriever","base","options","describeRetrieval","describe","retrieve","query","getChannel","hasSubscribers","getStore","descriptor","topK","startedAt","Date","now","run","retriever","store","undefined","collectionOf","chunks","zeroHit","failed","error","Error","message","String","collection","resolved","instrumentRetriever","isQueryInput","value","query","querySchema","version","vendor","validate","issues","message","createRetrievalTool","retriever","options","topK","telemetry","instrumented","instrumentRetriever","spec","name","kind","description","inputSchema","handler","execute","input","Error","passages","retrieve","undefined"]}