@warlock.js/ai 5.0.2 → 5.2.2

package/esm/rag/loaders/load-pdf.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"load-pdf.mjs","names":[],"sources":["../../../../../../../../ai/src/rag/loaders/load-pdf.ts"],"sourcesContent":["import type { RagDocument } from \"../contracts/rag-document.type\";\nimport { PDF_PARSE_INSTALL_INSTRUCTIONS } from \"./errors\";\nimport type { LoadPdfOptions, RagLoaderResult } from \"./loader.type\";\n\n/** Default `id` when the caller supplies none. */\nconst DEFAULT_ID = \"document\";\n\n/**\n * The slice of `pdf-parse`'s result we consume. The peer returns more\n * (`info`, `metadata`, `version`); we only need the extracted `text` and\n * page count, so we type just those to keep the dependency at arm's length.\n */\ntype PdfParseResult = {\n  /** Concatenated text of every page. */\n  text: string;\n  /** Number of pages in the document. */\n  numpages: number;\n  /** Document info dictionary — `Title` lifted into metadata when present. */\n  info?: { Title?: string } & Record<string, unknown>;\n};\n\n/** The `pdf-parse` module's callable default export. */\ntype PdfParseFn = (\n  data: Buffer | Uint8Array,\n  options?: {\n    /**\n     * Per-page renderer `pdf-parse` calls once per page in document order and\n     * `await`s — may return the page text synchronously or as a promise.\n     */\n    pagerender?: (page: unknown) => string | Promise<string>;\n  },\n) => Promise<PdfParseResult>;\n\n// ============================================================\n// Lazily-loaded pdf-parse (OPTIONAL peer)\n// ============================================================\n\nlet pdfParse: PdfParseFn | undefined;\nlet isModuleExists: boolean | undefined;\nlet loadingPromise: Promise<void> | undefined;\n\n/**\n * Settle the lazy import of `pdf-parse` once, concurrency-safe. A bare\n * `catch` flips the flag to `false`; the curated\n * {@link PDF_PARSE_INSTALL_INSTRUCTIONS} surfaces at first\n * {@link loadPdf} call, never a raw module-resolution stack trace. Mirrors\n * the guard moderation detector's `loadOpenAi`.\n */\nfunction loadPdfParse(): Promise<void> {\n  if (isModuleExists !== undefined) {\n    return Promise.resolve();\n  }\n\n  if (loadingPromise) {\n    return loadingPromise;\n  }\n\n  loadingPromise = (async () => {\n    try {\n      // Literal specifier so `vi.mock(\"pdf-parse\")` can intercept it in tests.\n      // Typed via the ambient `pdf-parse` shim in this directory, so the bare\n      // import resolves even though the OPTIONAL peer is not a dependency.\n      const mod = (await import(\"pdf-parse\")) as {\n        default?: PdfParseFn;\n      } & Partial<PdfParseFn>;\n      // pdf-parse ships CommonJS — the callable is `module.exports`, surfaced\n      // as `default` under ESM interop. Fall back to the namespace itself for\n      // bundlers that hoist the callable to the top level.\n      pdfParse = mod.default ?? (mod as unknown as PdfParseFn);\n      isModuleExists = typeof pdfParse === \"function\";\n    } catch {\n      isModuleExists = false;\n    }\n  })();\n\n  return loadingPromise;\n}\n\n/**\n * Coerce a {@link RagDocument}-compatible binary input into a `Buffer` for\n * `pdf-parse`. Accepts a Node `Buffer`, an `ArrayBuffer`, or a typed array\n * (`Uint8Array`) — the shapes a file read / fetch body hands back.\n */\nfunction toBuffer(input: Buffer | ArrayBuffer | Uint8Array): Buffer {\n  if (Buffer.isBuffer(input)) {\n    return input;\n  }\n\n  if (input instanceof ArrayBuffer) {\n    return Buffer.from(input);\n  }\n\n  return Buffer.from(input.buffer, input.byteOffset, input.byteLength);\n}\n\n/**\n * Load a PDF's bytes into {@link RagDocument}(s) via the OPTIONAL `pdf-parse`\n * peer. The peer is resolved lazily on the FIRST call (not at import) so\n * importing `@warlock.js/ai` never forces it to be installed; when it is\n * absent the curated {@link PDF_PARSE_INSTALL_INSTRUCTIONS} is thrown as a\n * plain `Error` (a missing optional peer is an infrastructure fault, not a\n * content problem).\n *\n * By default the whole PDF becomes a single document carrying\n * `metadata.pageCount`. With `perPage: true`, each page becomes its own\n * document (`id` suffixed `#p<n>`, `metadata.page` set) so citations stay\n * page-precise. Document `metadata.title` comes from the PDF info\n * dictionary's `Title` (unless overridden), and `metadata.loader` is\n * `\"pdf\"`. The output is the exact shape `index()` consumes.\n *\n * @example\n * import { readFile } from \"node:fs/promises\";\n * const kb = ai.rag({ embedder, store });\n * await kb.index(await loadPdf(await readFile(\"guide.pdf\"), { id: \"guide\" }));\n *\n * @example\n * // One document per page for page-precise citations:\n * await kb.index(await loadPdf(bytes, { id: \"manual\", perPage: true }));\n *\n * @param input - The PDF bytes (`Buffer`, `ArrayBuffer`, or `Uint8Array`).\n * @param options - `perPage` plus shared `id` / `metadata` / `tags`\n *   ({@link LoadPdfOptions}).\n * @returns A {@link RagLoaderResult} ready for `rag.index()`.\n * @throws {Error} carrying {@link PDF_PARSE_INSTALL_INSTRUCTIONS} when the\n *   `pdf-parse` peer is not installed.\n */\nexport async function loadPdf(\n  input: Buffer | ArrayBuffer | Uint8Array,\n  options: LoadPdfOptions = {},\n): Promise<RagLoaderResult> {\n  await loadPdfParse();\n\n  if (!isModuleExists || !pdfParse) {\n    throw new Error(PDF_PARSE_INSTALL_INSTRUCTIONS);\n  }\n\n  const id = options.id ?? DEFAULT_ID;\n  const perPage = options.perPage ?? false;\n\n  if (perPage) {\n    return loadPerPage(input, id, options);\n  }\n\n  const parsed = await pdfParse(toBuffer(input));\n  const text = parsed.text.trim();\n  const title = parsed.info?.Title?.trim();\n\n  // An image-only / empty PDF extracts no text — emit nothing so index()\n  // never receives a no-op record.\n  if (text.length === 0) {\n    return [];\n  }\n\n  const doc: RagDocument = {\n    id,\n    text,\n    metadata: {\n      source: id,\n      loader: \"pdf\",\n      pageCount: parsed.numpages,\n      ...(title ? { title } : {}),\n      ...options.metadata,\n    },\n    tags: options.tags,\n  };\n\n  return [doc];\n}\n\n/** One page of a parsed PDF — the text-layer item list `pagerender` sees. */\ntype PdfPage = {\n  getTextContent: (\n    options?: unknown,\n  ) => Promise<{ items: { str: string }[] }>;\n};\n\n/**\n * Per-page variant: render each page separately via `pdf-parse`'s\n * `pagerender` hook, accumulating one document per non-empty page. Each\n * carries `metadata.page` (1-based) and `metadata.pageCount`, and its id is\n * the base id suffixed `#p<n>` so every page-document is distinctly\n * identified for citation.\n *\n * `pdf-parse` calls `pagerender` once per page in document order and\n * `await`s the returned string, so capturing each page's joined text content\n * here gives reliable page boundaries the concatenated `text` lacks.\n */\nasync function loadPerPage(\n  input: Buffer | ArrayBuffer | Uint8Array,\n  id: string,\n  options: LoadPdfOptions,\n): Promise<RagDocument[]> {\n  const pages: string[] = [];\n\n  const parsed = await pdfParse!(toBuffer(input), {\n    pagerender: async (page: unknown): Promise<string> => {\n      const rendered = await renderPage(page as PdfPage);\n      pages.push(rendered);\n      return rendered;\n    },\n  });\n\n  const title = parsed.info?.Title?.trim();\n  const docs: RagDocument[] = [];\n\n  pages.forEach((pageText, index) => {\n    const text = pageText.trim();\n\n    if (text.length === 0) {\n      return;\n    }\n\n    const pageNumber = index + 1;\n\n    docs.push({\n      id: `${id}#p${pageNumber}`,\n      text,\n      metadata: {\n        source: id,\n        loader: \"pdf\",\n        page: pageNumber,\n        pageCount: parsed.numpages,\n        ...(title ? { title } : {}),\n        ...options.metadata,\n      },\n      tags: options.tags,\n    });\n  });\n\n  return docs;\n}\n\n/**\n * Join a single page's text-layer items in reading order, inserting a space\n * between items so adjacent words do not run together. Mirrors the essence\n * of `pdf-parse`'s default renderer without depending on its internals, so\n * the per-page hook stays stable across `pdf-parse` versions. A page with no\n * text layer (scanned image) renders to an empty string and is dropped.\n */\nasync function renderPage(page: PdfPage): Promise<string> {\n  if (typeof page?.getTextContent !== \"function\") {\n    return \"\";\n  }\n\n  const content = await page.getTextContent({\n    normalizeWhitespace: true,\n    disableCombineTextItems: false,\n  });\n\n  return content.items\n    .map((item) => item.str)\n    .join(\" \")\n    .replace(/\\s+/g, \" \")\n    .trim();\n}\n"],"mappings":";;;;AAKA,MAAM,aAAa;AAgCnB,IAAI;AACJ,IAAI;AACJ,IAAI;;;;;;;;AASJ,SAAS,eAA8B;CACrC,IAAI,mBAAmB,QACrB,OAAO,QAAQ,QAAQ;CAGzB,IAAI,gBACF,OAAO;CAGT,kBAAkB,YAAY;EAC5B,IAAI;GAIF,MAAM,MAAO,MAAM,OAAO;GAM1B,WAAW,IAAI,WAAY;GAC3B,iBAAiB,OAAO,aAAa;EACvC,QAAQ;GACN,iBAAiB;EACnB;CACF,EAAC,CAAE;CAEH,OAAO;AACT;;;;;;AAOA,SAAS,SAAS,OAAkD;CAClE,IAAI,OAAO,SAAS,KAAK,GACvB,OAAO;CAGT,IAAI,iBAAiB,aACnB,OAAO,OAAO,KAAK,KAAK;CAG1B,OAAO,OAAO,KAAK,MAAM,QAAQ,MAAM,YAAY,MAAM,UAAU;AACrE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiCA,eAAsB,QACpB,OACA,UAA0B,CAAC,GACD;CAC1B,MAAM,aAAa;CAEnB,IAAI,CAAC,kBAAkB,CAAC,UACtB,MAAM,IAAI,MAAM,8BAA8B;CAGhD,MAAM,KAAK,QAAQ,MAAM;CAGzB,IAFgB,QAAQ,WAAW,OAGjC,OAAO,YAAY,OAAO,IAAI,OAAO;CAGvC,MAAM,SAAS,MAAM,SAAS,SAAS,KAAK,CAAC;CAC7C,MAAM,OAAO,OAAO,KAAK,KAAK;CAC9B,MAAM,QAAQ,OAAO,MAAM,OAAO,KAAK;CAIvC,IAAI,KAAK,WAAW,GAClB,OAAO,CAAC;CAgBV,OAAO,CAAC;EAZN;EACA;EACA,UAAU;GACR,QAAQ;GACR,QAAQ;GACR,WAAW,OAAO;GAClB,GAAI,QAAQ,EAAE,MAAM,IAAI,CAAC;GACzB,GAAG,QAAQ;EACb;EACA,MAAM,QAAQ;CAGN,CAAC;AACb;;;;;;;;;;;;AAoBA,eAAe,YACb,OACA,IACA,SACwB;CACxB,MAAM,QAAkB,CAAC;CAEzB,MAAM,SAAS,MAAM,SAAU,SAAS,KAAK,GAAG,EAC9C,YAAY,OAAO,SAAmC;EACpD,MAAM,WAAW,MAAM,WAAW,IAAe;EACjD,MAAM,KAAK,QAAQ;EACnB,OAAO;CACT,EACF,CAAC;CAED,MAAM,QAAQ,OAAO,MAAM,OAAO,KAAK;CACvC,MAAM,OAAsB,CAAC;CAE7B,MAAM,SAAS,UAAU,UAAU;EACjC,MAAM,OAAO,SAAS,KAAK;EAE3B,IAAI,KAAK,WAAW,GAClB;EAGF,MAAM,aAAa,QAAQ;EAE3B,KAAK,KAAK;GACR,IAAI,GAAG,GAAG,IAAI;GACd;GACA,UAAU;IACR,QAAQ;IACR,QAAQ;IACR,MAAM;IACN,WAAW,OAAO;IAClB,GAAI,QAAQ,EAAE,MAAM,IAAI,CAAC;IACzB,GAAG,QAAQ;GACb;GACA,MAAM,QAAQ;EAChB,CAAC;CACH,CAAC;CAED,OAAO;AACT;;;;;;;;AASA,eAAe,WAAW,MAAgC;CACxD,IAAI,OAAO,MAAM,mBAAmB,YAClC,OAAO;CAQT,QAAO,MALe,KAAK,eAAe;EACxC,qBAAqB;EACrB,yBAAyB;CAC3B,CAAC,EAEa,CAAC,MACZ,KAAK,SAAS,KAAK,GAAG,CAAC,CACvB,KAAK,GAAG,CAAC,CACT,QAAQ,QAAQ,GAAG,CAAC,CACpB,KAAK;AACV"}
+{"version":3,"file":"load-pdf.mjs","names":[],"sources":["../../../../../../../../ai/src/rag/loaders/load-pdf.ts"],"sourcesContent":["import type { RagDocument } from \"../contracts/rag-document.type\";\nimport { PDF_PARSE_INSTALL_INSTRUCTIONS } from \"./errors\";\nimport type { LoadPdfOptions, RagLoaderResult } from \"./loader.type\";\n\n/** Default `id` when the caller supplies none. */\nconst DEFAULT_ID = \"document\";\n\n/**\n * The slice of `pdf-parse`'s result we consume. The peer returns more\n * (`info`, `metadata`, `version`); we only need the extracted `text` and\n * page count, so we type just those to keep the dependency at arm's length.\n */\ntype PdfParseResult = {\n  /** Concatenated text of every page. */\n  text: string;\n  /** Number of pages in the document. */\n  numpages: number;\n  /** Document info dictionary — `Title` lifted into metadata when present. */\n  info?: { Title?: string } & Record<string, unknown>;\n};\n\n/** The `pdf-parse` module's callable default export. */\ntype PdfParseFn = (\n  data: Buffer | Uint8Array,\n  options?: {\n    /**\n     * Per-page renderer `pdf-parse` calls once per page in document order and\n     * `await`s — may return the page text synchronously or as a promise.\n     */\n    pagerender?: (page: unknown) => string | Promise<string>;\n  },\n) => Promise<PdfParseResult>;\n\n// ============================================================\n// Lazily-loaded pdf-parse (OPTIONAL peer)\n// ============================================================\n\nlet pdfParse: PdfParseFn | undefined;\nlet isModuleExists: boolean | undefined;\nlet loadingPromise: Promise<void> | undefined;\n\n/**\n * Settle the lazy import of `pdf-parse` once, concurrency-safe. A bare\n * `catch` flips the flag to `false`; the curated\n * {@link PDF_PARSE_INSTALL_INSTRUCTIONS} surfaces at first\n * {@link loadPdf} call, never a raw module-resolution stack trace. Mirrors\n * the guard moderation detector's `loadOpenAi`.\n */\nfunction loadPdfParse(): Promise<void> {\n  if (isModuleExists !== undefined) {\n    return Promise.resolve();\n  }\n\n  if (loadingPromise) {\n    return loadingPromise;\n  }\n\n  loadingPromise = (async () => {\n    try {\n      // Literal specifier so `vi.mock(\"pdf-parse\")` can intercept it in tests.\n      // Typed via the ambient `pdf-parse` shim in this directory, so the bare\n      // import resolves even though the OPTIONAL peer is not a dependency.\n      // Through `unknown`: with the optional peer actually installed, the real\n      // pdf-parse types resolve and TS refuses the direct cast as non-overlapping.\n      // The narrowing below is a genuine RUNTIME shape check across the CJS/ESM\n      // interop shapes, which is exactly the case `unknown` exists for.\n      const mod = (await import(\"pdf-parse\")) as unknown as {\n        default?: PdfParseFn;\n      } & Partial<PdfParseFn>;\n      // pdf-parse ships CommonJS — the callable is `module.exports`, surfaced\n      // as `default` under ESM interop. Fall back to the namespace itself for\n      // bundlers that hoist the callable to the top level.\n      pdfParse = mod.default ?? (mod as unknown as PdfParseFn);\n      isModuleExists = typeof pdfParse === \"function\";\n    } catch {\n      isModuleExists = false;\n    }\n  })();\n\n  return loadingPromise;\n}\n\n/**\n * Coerce a {@link RagDocument}-compatible binary input into a `Buffer` for\n * `pdf-parse`. Accepts a Node `Buffer`, an `ArrayBuffer`, or a typed array\n * (`Uint8Array`) — the shapes a file read / fetch body hands back.\n */\nfunction toBuffer(input: Buffer | ArrayBuffer | Uint8Array): Buffer {\n  if (Buffer.isBuffer(input)) {\n    return input;\n  }\n\n  if (input instanceof ArrayBuffer) {\n    return Buffer.from(input);\n  }\n\n  return Buffer.from(input.buffer, input.byteOffset, input.byteLength);\n}\n\n/**\n * Load a PDF's bytes into {@link RagDocument}(s) via the OPTIONAL `pdf-parse`\n * peer. The peer is resolved lazily on the FIRST call (not at import) so\n * importing `@warlock.js/ai` never forces it to be installed; when it is\n * absent the curated {@link PDF_PARSE_INSTALL_INSTRUCTIONS} is thrown as a\n * plain `Error` (a missing optional peer is an infrastructure fault, not a\n * content problem).\n *\n * By default the whole PDF becomes a single document carrying\n * `metadata.pageCount`. With `perPage: true`, each page becomes its own\n * document (`id` suffixed `#p<n>`, `metadata.page` set) so citations stay\n * page-precise. Document `metadata.title` comes from the PDF info\n * dictionary's `Title` (unless overridden), and `metadata.loader` is\n * `\"pdf\"`. The output is the exact shape `index()` consumes.\n *\n * @example\n * import { readFile } from \"node:fs/promises\";\n * const kb = ai.rag({ embedder, store });\n * await kb.index(await loadPdf(await readFile(\"guide.pdf\"), { id: \"guide\" }));\n *\n * @example\n * // One document per page for page-precise citations:\n * await kb.index(await loadPdf(bytes, { id: \"manual\", perPage: true }));\n *\n * @param input - The PDF bytes (`Buffer`, `ArrayBuffer`, or `Uint8Array`).\n * @param options - `perPage` plus shared `id` / `metadata` / `tags`\n *   ({@link LoadPdfOptions}).\n * @returns A {@link RagLoaderResult} ready for `rag.index()`.\n * @throws {Error} carrying {@link PDF_PARSE_INSTALL_INSTRUCTIONS} when the\n *   `pdf-parse` peer is not installed.\n */\nexport async function loadPdf(\n  input: Buffer | ArrayBuffer | Uint8Array,\n  options: LoadPdfOptions = {},\n): Promise<RagLoaderResult> {\n  await loadPdfParse();\n\n  if (!isModuleExists || !pdfParse) {\n    throw new Error(PDF_PARSE_INSTALL_INSTRUCTIONS);\n  }\n\n  const id = options.id ?? DEFAULT_ID;\n  const perPage = options.perPage ?? false;\n\n  if (perPage) {\n    return loadPerPage(input, id, options);\n  }\n\n  const parsed = await pdfParse(toBuffer(input));\n  const text = parsed.text.trim();\n  const title = parsed.info?.Title?.trim();\n\n  // An image-only / empty PDF extracts no text — emit nothing so index()\n  // never receives a no-op record.\n  if (text.length === 0) {\n    return [];\n  }\n\n  const doc: RagDocument = {\n    id,\n    text,\n    metadata: {\n      source: id,\n      loader: \"pdf\",\n      pageCount: parsed.numpages,\n      ...(title ? { title } : {}),\n      ...options.metadata,\n    },\n    tags: options.tags,\n  };\n\n  return [doc];\n}\n\n/** One page of a parsed PDF — the text-layer item list `pagerender` sees. */\ntype PdfPage = {\n  getTextContent: (\n    options?: unknown,\n  ) => Promise<{ items: { str: string }[] }>;\n};\n\n/**\n * Per-page variant: render each page separately via `pdf-parse`'s\n * `pagerender` hook, accumulating one document per non-empty page. Each\n * carries `metadata.page` (1-based) and `metadata.pageCount`, and its id is\n * the base id suffixed `#p<n>` so every page-document is distinctly\n * identified for citation.\n *\n * `pdf-parse` calls `pagerender` once per page in document order and\n * `await`s the returned string, so capturing each page's joined text content\n * here gives reliable page boundaries the concatenated `text` lacks.\n */\nasync function loadPerPage(\n  input: Buffer | ArrayBuffer | Uint8Array,\n  id: string,\n  options: LoadPdfOptions,\n): Promise<RagDocument[]> {\n  const pages: string[] = [];\n\n  const parsed = await pdfParse!(toBuffer(input), {\n    pagerender: async (page: unknown): Promise<string> => {\n      const rendered = await renderPage(page as PdfPage);\n      pages.push(rendered);\n      return rendered;\n    },\n  });\n\n  const title = parsed.info?.Title?.trim();\n  const docs: RagDocument[] = [];\n\n  pages.forEach((pageText, index) => {\n    const text = pageText.trim();\n\n    if (text.length === 0) {\n      return;\n    }\n\n    const pageNumber = index + 1;\n\n    docs.push({\n      id: `${id}#p${pageNumber}`,\n      text,\n      metadata: {\n        source: id,\n        loader: \"pdf\",\n        page: pageNumber,\n        pageCount: parsed.numpages,\n        ...(title ? { title } : {}),\n        ...options.metadata,\n      },\n      tags: options.tags,\n    });\n  });\n\n  return docs;\n}\n\n/**\n * Join a single page's text-layer items in reading order, inserting a space\n * between items so adjacent words do not run together. Mirrors the essence\n * of `pdf-parse`'s default renderer without depending on its internals, so\n * the per-page hook stays stable across `pdf-parse` versions. A page with no\n * text layer (scanned image) renders to an empty string and is dropped.\n */\nasync function renderPage(page: PdfPage): Promise<string> {\n  if (typeof page?.getTextContent !== \"function\") {\n    return \"\";\n  }\n\n  const content = await page.getTextContent({\n    normalizeWhitespace: true,\n    disableCombineTextItems: false,\n  });\n\n  return content.items\n    .map((item) => item.str)\n    .join(\" \")\n    .replace(/\\s+/g, \" \")\n    .trim();\n}\n"],"mappings":";;;;AAKA,MAAM,aAAa;AAgCnB,IAAI;AACJ,IAAI;AACJ,IAAI;;;;;;;;AASJ,SAAS,eAA8B;CACrC,IAAI,mBAAmB,QACrB,OAAO,QAAQ,QAAQ;CAGzB,IAAI,gBACF,OAAO;CAGT,kBAAkB,YAAY;EAC5B,IAAI;GAQF,MAAM,MAAO,MAAM,OAAO;GAM1B,WAAW,IAAI,WAAY;GAC3B,iBAAiB,OAAO,aAAa;EACvC,QAAQ;GACN,iBAAiB;EACnB;CACF,GAAG;CAEH,OAAO;AACT;;;;;;AAOA,SAAS,SAAS,OAAkD;CAClE,IAAI,OAAO,SAAS,KAAK,GACvB,OAAO;CAGT,IAAI,iBAAiB,aACnB,OAAO,OAAO,KAAK,KAAK;CAG1B,OAAO,OAAO,KAAK,MAAM,QAAQ,MAAM,YAAY,MAAM,UAAU;AACrE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiCA,eAAsB,QACpB,OACA,UAA0B,CAAC,GACD;CAC1B,MAAM,aAAa;CAEnB,IAAI,CAAC,kBAAkB,CAAC,UACtB,MAAM,IAAI,MAAM,8BAA8B;CAGhD,MAAM,KAAK,QAAQ,MAAM;CAGzB,IAFgB,QAAQ,WAAW,OAGjC,OAAO,YAAY,OAAO,IAAI,OAAO;CAGvC,MAAM,SAAS,MAAM,SAAS,SAAS,KAAK,CAAC;CAC7C,MAAM,OAAO,OAAO,KAAK,KAAK;CAC9B,MAAM,QAAQ,OAAO,MAAM,OAAO,KAAK;CAIvC,IAAI,KAAK,WAAW,GAClB,OAAO,CAAC;CAgBV,OAAO,CAAC;EAZN;EACA;EACA,UAAU;GACR,QAAQ;GACR,QAAQ;GACR,WAAW,OAAO;GAClB,GAAI,QAAQ,EAAE,MAAM,IAAI,CAAC;GACzB,GAAG,QAAQ;EACb;EACA,MAAM,QAAQ;CAGN,CAAC;AACb;;;;;;;;;;;;AAoBA,eAAe,YACb,OACA,IACA,SACwB;CACxB,MAAM,QAAkB,CAAC;CAEzB,MAAM,SAAS,MAAM,SAAU,SAAS,KAAK,GAAG,EAC9C,YAAY,OAAO,SAAmC;EACpD,MAAM,WAAW,MAAM,WAAW,IAAe;EACjD,MAAM,KAAK,QAAQ;EACnB,OAAO;CACT,EACF,CAAC;CAED,MAAM,QAAQ,OAAO,MAAM,OAAO,KAAK;CACvC,MAAM,OAAsB,CAAC;CAE7B,MAAM,SAAS,UAAU,UAAU;EACjC,MAAM,OAAO,SAAS,KAAK;EAE3B,IAAI,KAAK,WAAW,GAClB;EAGF,MAAM,aAAa,QAAQ;EAE3B,KAAK,KAAK;GACR,IAAI,GAAG,GAAG,IAAI;GACd;GACA,UAAU;IACR,QAAQ;IACR,QAAQ;IACR,MAAM;IACN,WAAW,OAAO;IAClB,GAAI,QAAQ,EAAE,MAAM,IAAI,CAAC;IACzB,GAAG,QAAQ;GACb;GACA,MAAM,QAAQ;EAChB,CAAC;CACH,CAAC;CAED,OAAO;AACT;;;;;;;;AASA,eAAe,WAAW,MAAgC;CACxD,IAAI,OAAO,MAAM,mBAAmB,YAClC,OAAO;CAQT,QAAO,MALe,KAAK,eAAe;EACxC,qBAAqB;EACrB,yBAAyB;CAC3B,CAAC,GAEc,MACZ,KAAK,SAAS,KAAK,GAAG,EACtB,KAAK,GAAG,EACR,QAAQ,QAAQ,GAAG,EACnB,KAAK;AACV"}

package/esm/rag/loaders/load-text.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"load-text.mjs","names":[],"sources":["../../../../../../../../ai/src/rag/loaders/load-text.ts"],"sourcesContent":["import type { RagDocument } from \"../contracts/rag-document.type\";\nimport type { LoadTextOptions, RagLoaderResult } from \"./loader.type\";\n\n/** Default `id` when the caller supplies neither `id` nor an item id. */\nconst DEFAULT_ID = \"document\";\n\n/**\n * One raw text item — a bare string, or a `{ id, text, … }` record giving the\n * item its own id / metadata / tags. Passing records lets a single\n * {@link loadText} call turn many strings into many distinctly-identified\n * {@link RagDocument}s.\n */\nexport type TextInput =\n  | string\n  | {\n      /** Stable id for this item. Falls back to the option `id` + index. */\n      id?: string;\n      /** The text body. */\n      text: string;\n      /** Per-item metadata, merged under the shared option `metadata`. */\n      metadata?: Record<string, unknown>;\n      /** Per-item tags (override the shared option `tags` when present). */\n      tags?: string[];\n    };\n\n/**\n * Load plain text into {@link RagDocument}(s) — the zero-dependency base\n * loader every other loader ultimately funnels into. Accepts a single\n * string, a single `{ id, text }` record, or an array mixing both; each\n * input becomes one document carrying `metadata.loader = \"text\"` plus a\n * `metadata.source` (the resolved id).\n *\n * Caller `metadata` always wins over the loader-derived keys, and per-item\n * `metadata` / `tags` (when an item is a record) layer on top of the shared\n * option values. Empty / whitespace-only items are dropped — they would\n * chunk to nothing anyway, so the result never carries a no-op document.\n *\n * The output is the exact shape `index()` consumes:\n *\n * @example\n * const kb = ai.rag({ embedder, store });\n * await kb.index(loadText(\"a long string of notes…\"));\n *\n * @example\n * await kb.index(loadText([\n *   { id: \"faq-1\", text: \"…\", metadata: { section: \"billing\" } },\n *   { id: \"faq-2\", text: \"…\" },\n * ]));\n *\n * @param input - A string, a `{ id, text }` record, or an array of either.\n * @param options - Shared `id` / `metadata` / `tags` ({@link LoadTextOptions}).\n * @returns A {@link RagLoaderResult} ready to hand to `rag.index()`.\n */\nexport function loadText(\n  input: TextInput | TextInput[],\n  options: LoadTextOptions = {},\n): RagLoaderResult {\n  const items = Array.isArray(input) ? input : [input];\n  const baseId = options.id ?? DEFAULT_ID;\n  const multiple = items.length > 1;\n\n  const docs: RagDocument[] = [];\n\n  items.forEach((item, index) => {\n    const text = typeof item === \"string\" ? item : item.text;\n\n    // Drop empties up front — they chunk to nothing, so emitting them would\n    // only add a no-op document for index() to skip.\n    if (text.trim().length === 0) {\n      return;\n    }\n\n    const itemId =\n      typeof item === \"string\" ? undefined : item.id;\n    // A single input keeps the bare base id; multiple inputs are suffixed so\n    // every emitted document has a distinct, stable id.\n    const id = itemId ?? (multiple ? `${baseId}#${index}` : baseId);\n\n    const itemMetadata =\n      typeof item === \"string\" ? undefined : item.metadata;\n    const itemTags = typeof item === \"string\" ? undefined : item.tags;\n\n    docs.push({\n      id,\n      text,\n      // Loader-derived keys first, then the shared option metadata, then the\n      // per-item metadata — caller intent always overrides the derived keys.\n      metadata: {\n        source: id,\n        loader: \"text\",\n        ...options.metadata,\n        ...itemMetadata,\n      },\n      tags: itemTags ?? options.tags,\n    });\n  });\n\n  return docs;\n}\n"],"mappings":";;AAIA,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiDnB,SAAgB,SACd,OACA,UAA2B,CAAC,GACX;CACjB,MAAM,QAAQ,MAAM,QAAQ,KAAK,IAAI,QAAQ,CAAC,KAAK;CACnD,MAAM,SAAS,QAAQ,MAAM;CAC7B,MAAM,WAAW,MAAM,SAAS;CAEhC,MAAM,OAAsB,CAAC;CAE7B,MAAM,SAAS,MAAM,UAAU;EAC7B,MAAM,OAAO,OAAO,SAAS,WAAW,OAAO,KAAK;EAIpD,IAAI,KAAK,KAAK,CAAC,CAAC,WAAW,GACzB;EAOF,MAAM,MAHJ,OAAO,SAAS,WAAW,SAAY,KAAK,QAGxB,WAAW,GAAG,OAAO,GAAG,UAAU;EAExD,MAAM,eACJ,OAAO,SAAS,WAAW,SAAY,KAAK;EAC9C,MAAM,WAAW,OAAO,SAAS,WAAW,SAAY,KAAK;EAE7D,KAAK,KAAK;GACR;GACA;GAGA,UAAU;IACR,QAAQ;IACR,QAAQ;IACR,GAAG,QAAQ;IACX,GAAG;GACL;GACA,MAAM,YAAY,QAAQ;EAC5B,CAAC;CACH,CAAC;CAED,OAAO;AACT"}
+{"version":3,"file":"load-text.mjs","names":[],"sources":["../../../../../../../../ai/src/rag/loaders/load-text.ts"],"sourcesContent":["import type { RagDocument } from \"../contracts/rag-document.type\";\nimport type { LoadTextOptions, RagLoaderResult } from \"./loader.type\";\n\n/** Default `id` when the caller supplies neither `id` nor an item id. */\nconst DEFAULT_ID = \"document\";\n\n/**\n * One raw text item — a bare string, or a `{ id, text, … }` record giving the\n * item its own id / metadata / tags. Passing records lets a single\n * {@link loadText} call turn many strings into many distinctly-identified\n * {@link RagDocument}s.\n */\nexport type TextInput =\n  | string\n  | {\n      /** Stable id for this item. Falls back to the option `id` + index. */\n      id?: string;\n      /** The text body. */\n      text: string;\n      /** Per-item metadata, merged under the shared option `metadata`. */\n      metadata?: Record<string, unknown>;\n      /** Per-item tags (override the shared option `tags` when present). */\n      tags?: string[];\n    };\n\n/**\n * Load plain text into {@link RagDocument}(s) — the zero-dependency base\n * loader every other loader ultimately funnels into. Accepts a single\n * string, a single `{ id, text }` record, or an array mixing both; each\n * input becomes one document carrying `metadata.loader = \"text\"` plus a\n * `metadata.source` (the resolved id).\n *\n * Caller `metadata` always wins over the loader-derived keys, and per-item\n * `metadata` / `tags` (when an item is a record) layer on top of the shared\n * option values. Empty / whitespace-only items are dropped — they would\n * chunk to nothing anyway, so the result never carries a no-op document.\n *\n * The output is the exact shape `index()` consumes:\n *\n * @example\n * const kb = ai.rag({ embedder, store });\n * await kb.index(loadText(\"a long string of notes…\"));\n *\n * @example\n * await kb.index(loadText([\n *   { id: \"faq-1\", text: \"…\", metadata: { section: \"billing\" } },\n *   { id: \"faq-2\", text: \"…\" },\n * ]));\n *\n * @param input - A string, a `{ id, text }` record, or an array of either.\n * @param options - Shared `id` / `metadata` / `tags` ({@link LoadTextOptions}).\n * @returns A {@link RagLoaderResult} ready to hand to `rag.index()`.\n */\nexport function loadText(\n  input: TextInput | TextInput[],\n  options: LoadTextOptions = {},\n): RagLoaderResult {\n  const items = Array.isArray(input) ? input : [input];\n  const baseId = options.id ?? DEFAULT_ID;\n  const multiple = items.length > 1;\n\n  const docs: RagDocument[] = [];\n\n  items.forEach((item, index) => {\n    const text = typeof item === \"string\" ? item : item.text;\n\n    // Drop empties up front — they chunk to nothing, so emitting them would\n    // only add a no-op document for index() to skip.\n    if (text.trim().length === 0) {\n      return;\n    }\n\n    const itemId =\n      typeof item === \"string\" ? undefined : item.id;\n    // A single input keeps the bare base id; multiple inputs are suffixed so\n    // every emitted document has a distinct, stable id.\n    const id = itemId ?? (multiple ? `${baseId}#${index}` : baseId);\n\n    const itemMetadata =\n      typeof item === \"string\" ? undefined : item.metadata;\n    const itemTags = typeof item === \"string\" ? undefined : item.tags;\n\n    docs.push({\n      id,\n      text,\n      // Loader-derived keys first, then the shared option metadata, then the\n      // per-item metadata — caller intent always overrides the derived keys.\n      metadata: {\n        source: id,\n        loader: \"text\",\n        ...options.metadata,\n        ...itemMetadata,\n      },\n      tags: itemTags ?? options.tags,\n    });\n  });\n\n  return docs;\n}\n"],"mappings":";;AAIA,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiDnB,SAAgB,SACd,OACA,UAA2B,CAAC,GACX;CACjB,MAAM,QAAQ,MAAM,QAAQ,KAAK,IAAI,QAAQ,CAAC,KAAK;CACnD,MAAM,SAAS,QAAQ,MAAM;CAC7B,MAAM,WAAW,MAAM,SAAS;CAEhC,MAAM,OAAsB,CAAC;CAE7B,MAAM,SAAS,MAAM,UAAU;EAC7B,MAAM,OAAO,OAAO,SAAS,WAAW,OAAO,KAAK;EAIpD,IAAI,KAAK,KAAK,EAAE,WAAW,GACzB;EAOF,MAAM,MAHJ,OAAO,SAAS,WAAW,SAAY,KAAK,QAGxB,WAAW,GAAG,OAAO,GAAG,UAAU;EAExD,MAAM,eACJ,OAAO,SAAS,WAAW,SAAY,KAAK;EAC9C,MAAM,WAAW,OAAO,SAAS,WAAW,SAAY,KAAK;EAE7D,KAAK,KAAK;GACR;GACA;GAGA,UAAU;IACR,QAAQ;IACR,QAAQ;IACR,GAAG,QAAQ;IACX,GAAG;GACL;GACA,MAAM,YAAY,QAAQ;EAC5B,CAAC;CACH,CAAC;CAED,OAAO;AACT"}

package/esm/rag/rerank/keyword-reranker.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"keyword-reranker.mjs","names":[],"sources":["../../../../../../../../ai/src/rag/rerank/keyword-reranker.ts"],"sourcesContent":["import type { RetrievedChunk } from \"../contracts/citation.type\";\nimport type { RagReranker } from \"./reranker.contract\";\n\n/** Options for the {@link keywordReranker}. */\nexport type KeywordRerankerOptions = {\n  /**\n   * Weight of the lexical-overlap signal blended with the original cosine\n   * score, in `[0, 1]`. `1` ranks purely by keyword overlap; `0` keeps the\n   * cosine order. Default `0.5`.\n   */\n  weight?: number;\n};\n\n/** Splits text into lowercase alphanumeric terms. */\nfunction tokenize(text: string): string[] {\n  return text\n    .toLowerCase()\n    .split(/[^a-z0-9]+/)\n    .filter((term) => term.length > 0);\n}\n\n/**\n * Zero-dependency lexical reranker (a BM25-lite, IDF-free keyword overlap).\n *\n * For each candidate it computes the fraction of distinct query terms that\n * appear in the chunk, blends that with the candidate's original cosine\n * score by `weight`, and sorts descending. A pure-lexical pass costs\n * nothing beyond string splits — no peer, no model — so it is the\n * recommended opt-in reranker when an embedding-only ranking surfaces a\n * keyword-rich chunk too low.\n *\n * Ties (equal blended score) preserve the incoming order, so the cosine\n * ranking breaks ties deterministically.\n *\n * @example\n * const kb = ai.rag({ embedder, store, reranker: ai.rag.keywordReranker() });\n */\nexport function keywordReranker(options: KeywordRerankerOptions = {}): RagReranker {\n  const weight = options.weight ?? 0.5;\n\n  return {\n    name: \"keyword\",\n    async rerank(query: string, candidates: RetrievedChunk[]): Promise<RetrievedChunk[]> {\n      if (candidates.length === 0) {\n        return [];\n      }\n\n      const queryTerms = new Set(tokenize(query));\n\n      if (queryTerms.size === 0) {\n        return [...candidates];\n      }\n\n      const scored = candidates.map((candidate, position) => {\n        const chunkTerms = new Set(tokenize(candidate.text));\n\n        let overlap = 0;\n        for (const term of queryTerms) {\n          if (chunkTerms.has(term)) {\n            overlap += 1;\n          }\n        }\n\n        const lexical = overlap / queryTerms.size;\n        const blended = weight * lexical + (1 - weight) * candidate.score;\n\n        return { candidate, blended, position };\n      });\n\n      scored.sort((first, second) => {\n        if (second.blended !== first.blended) {\n          return second.blended - first.blended;\n        }\n\n        // Stable on ties: keep the incoming (cosine) order.\n        return first.position - second.position;\n      });\n\n      return scored.map((entry) => ({\n        ...entry.candidate,\n        score: entry.blended,\n        citation: { ...entry.candidate.citation, score: entry.blended },\n      }));\n    },\n  };\n}\n"],"mappings":";;AAcA,SAAS,SAAS,MAAwB;CACxC,OAAO,KACJ,YAAY,CAAC,CACb,MAAM,YAAY,CAAC,CACnB,QAAQ,SAAS,KAAK,SAAS,CAAC;AACrC;;;;;;;;;;;;;;;;;AAkBA,SAAgB,gBAAgB,UAAkC,CAAC,GAAgB;CACjF,MAAM,SAAS,QAAQ,UAAU;CAEjC,OAAO;EACL,MAAM;EACN,MAAM,OAAO,OAAe,YAAyD;GACnF,IAAI,WAAW,WAAW,GACxB,OAAO,CAAC;GAGV,MAAM,aAAa,IAAI,IAAI,SAAS,KAAK,CAAC;GAE1C,IAAI,WAAW,SAAS,GACtB,OAAO,CAAC,GAAG,UAAU;GAGvB,MAAM,SAAS,WAAW,KAAK,WAAW,aAAa;IACrD,MAAM,aAAa,IAAI,IAAI,SAAS,UAAU,IAAI,CAAC;IAEnD,IAAI,UAAU;IACd,KAAK,MAAM,QAAQ,YACjB,IAAI,WAAW,IAAI,IAAI,GACrB,WAAW;IAOf,OAAO;KAAE;KAAW,SAFJ,UADA,UAAU,WAAW,SACD,IAAI,UAAU,UAAU;KAE/B;IAAS;GACxC,CAAC;GAED,OAAO,MAAM,OAAO,WAAW;IAC7B,IAAI,OAAO,YAAY,MAAM,SAC3B,OAAO,OAAO,UAAU,MAAM;IAIhC,OAAO,MAAM,WAAW,OAAO;GACjC,CAAC;GAED,OAAO,OAAO,KAAK,WAAW;IAC5B,GAAG,MAAM;IACT,OAAO,MAAM;IACb,UAAU;KAAE,GAAG,MAAM,UAAU;KAAU,OAAO,MAAM;IAAQ;GAChE,EAAE;EACJ;CACF;AACF"}
+{"version":3,"file":"keyword-reranker.mjs","names":[],"sources":["../../../../../../../../ai/src/rag/rerank/keyword-reranker.ts"],"sourcesContent":["import type { RetrievedChunk } from \"../contracts/citation.type\";\nimport type { RagReranker } from \"./reranker.contract\";\n\n/** Options for the {@link keywordReranker}. */\nexport type KeywordRerankerOptions = {\n  /**\n   * Weight of the lexical-overlap signal blended with the original cosine\n   * score, in `[0, 1]`. `1` ranks purely by keyword overlap; `0` keeps the\n   * cosine order. Default `0.5`.\n   */\n  weight?: number;\n};\n\n/** Splits text into lowercase alphanumeric terms. */\nfunction tokenize(text: string): string[] {\n  return text\n    .toLowerCase()\n    .split(/[^a-z0-9]+/)\n    .filter((term) => term.length > 0);\n}\n\n/**\n * Zero-dependency lexical reranker (a BM25-lite, IDF-free keyword overlap).\n *\n * For each candidate it computes the fraction of distinct query terms that\n * appear in the chunk, blends that with the candidate's original cosine\n * score by `weight`, and sorts descending. A pure-lexical pass costs\n * nothing beyond string splits — no peer, no model — so it is the\n * recommended opt-in reranker when an embedding-only ranking surfaces a\n * keyword-rich chunk too low.\n *\n * Ties (equal blended score) preserve the incoming order, so the cosine\n * ranking breaks ties deterministically.\n *\n * @example\n * const kb = ai.rag({ embedder, store, reranker: ai.rag.keywordReranker() });\n */\nexport function keywordReranker(options: KeywordRerankerOptions = {}): RagReranker {\n  const weight = options.weight ?? 0.5;\n\n  return {\n    name: \"keyword\",\n    async rerank(query: string, candidates: RetrievedChunk[]): Promise<RetrievedChunk[]> {\n      if (candidates.length === 0) {\n        return [];\n      }\n\n      const queryTerms = new Set(tokenize(query));\n\n      if (queryTerms.size === 0) {\n        return [...candidates];\n      }\n\n      const scored = candidates.map((candidate, position) => {\n        const chunkTerms = new Set(tokenize(candidate.text));\n\n        let overlap = 0;\n        for (const term of queryTerms) {\n          if (chunkTerms.has(term)) {\n            overlap += 1;\n          }\n        }\n\n        const lexical = overlap / queryTerms.size;\n        const blended = weight * lexical + (1 - weight) * candidate.score;\n\n        return { candidate, blended, position };\n      });\n\n      scored.sort((first, second) => {\n        if (second.blended !== first.blended) {\n          return second.blended - first.blended;\n        }\n\n        // Stable on ties: keep the incoming (cosine) order.\n        return first.position - second.position;\n      });\n\n      return scored.map((entry) => ({\n        ...entry.candidate,\n        score: entry.blended,\n        citation: { ...entry.candidate.citation, score: entry.blended },\n      }));\n    },\n  };\n}\n"],"mappings":";;AAcA,SAAS,SAAS,MAAwB;CACxC,OAAO,KACJ,YAAY,EACZ,MAAM,YAAY,EAClB,QAAQ,SAAS,KAAK,SAAS,CAAC;AACrC;;;;;;;;;;;;;;;;;AAkBA,SAAgB,gBAAgB,UAAkC,CAAC,GAAgB;CACjF,MAAM,SAAS,QAAQ,UAAU;CAEjC,OAAO;EACL,MAAM;EACN,MAAM,OAAO,OAAe,YAAyD;GACnF,IAAI,WAAW,WAAW,GACxB,OAAO,CAAC;GAGV,MAAM,aAAa,IAAI,IAAI,SAAS,KAAK,CAAC;GAE1C,IAAI,WAAW,SAAS,GACtB,OAAO,CAAC,GAAG,UAAU;GAGvB,MAAM,SAAS,WAAW,KAAK,WAAW,aAAa;IACrD,MAAM,aAAa,IAAI,IAAI,SAAS,UAAU,IAAI,CAAC;IAEnD,IAAI,UAAU;IACd,KAAK,MAAM,QAAQ,YACjB,IAAI,WAAW,IAAI,IAAI,GACrB,WAAW;IAOf,OAAO;KAAE;KAAW,SAFJ,UADA,UAAU,WAAW,SACD,IAAI,UAAU,UAAU;KAE/B;IAAS;GACxC,CAAC;GAED,OAAO,MAAM,OAAO,WAAW;IAC7B,IAAI,OAAO,YAAY,MAAM,SAC3B,OAAO,OAAO,UAAU,MAAM;IAIhC,OAAO,MAAM,WAAW,OAAO;GACjC,CAAC;GAED,OAAO,OAAO,KAAK,WAAW;IAC5B,GAAG,MAAM;IACT,OAAO,MAAM;IACb,UAAU;KAAE,GAAG,MAAM,UAAU;KAAU,OAAO,MAAM;IAAQ;GAChE,EAAE;EACJ;CACF;AACF"}

package/esm/rag/rerank/llm-reranker.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"llm-reranker.mjs","names":[],"sources":["../../../../../../../../ai/src/rag/rerank/llm-reranker.ts"],"sourcesContent":["import type { Message } from \"../../contracts/conversation-message.type\";\nimport type { ModelContract } from \"../../contracts/model.contract\";\nimport type { RetrievedChunk } from \"../contracts/citation.type\";\nimport type { RagReranker } from \"./reranker.contract\";\n\n/** Options for the {@link llmReranker}. */\nexport type LlmRerankerOptions = {\n  /** The model used to score candidate relevance. Required. */\n  model: ModelContract;\n  /**\n   * How many candidates to score per model call. Larger batches mean\n   * fewer round-trips but a longer prompt. Default `10`.\n   */\n  batchSize?: number;\n};\n\n/**\n * A single relevance score the model returns for a candidate, in `[0, 1]`,\n * keyed by the candidate's position in the batch.\n */\ntype ScoreLine = {\n  index: number;\n  score: number;\n};\n\n/**\n * Build the scoring prompt — the model rates each candidate's relevance to\n * the query on a `0..1` scale and replies with one `index: score` line per\n * candidate. Kept terse and JSON-light so any chat model can answer.\n */\nfunction buildPrompt(query: string, candidates: RetrievedChunk[]): Message[] {\n  const lines = candidates\n    .map((candidate, index) => `[${index}] ${candidate.text}`)\n    .join(\"\\n\\n\");\n\n  return [\n    {\n      role: \"system\",\n      content:\n        \"You are a relevance grader. For each numbered passage, rate how well it answers the query on a scale from 0 (irrelevant) to 1 (fully relevant). Reply with ONLY a JSON array of objects like [{\\\"index\\\":0,\\\"score\\\":0.9}], one entry per passage, no prose.\",\n    },\n    {\n      role: \"user\",\n      content: `Query: ${query}\\n\\nPassages:\\n${lines}`,\n    },\n  ];\n}\n\n/**\n * Parse the model's reply into a score map. Tolerant of surrounding prose:\n * extracts the first JSON array and reads `{ index, score }` entries.\n * Returns an empty map when nothing parseable is found, so the caller can\n * fall back to the original order.\n */\nfunction parseScores(reply: string): Map<number, number> {\n  const scores = new Map<number, number>();\n  const start = reply.indexOf(\"[\");\n  const end = reply.lastIndexOf(\"]\");\n\n  if (start === -1 || end === -1 || end <= start) {\n    return scores;\n  }\n\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(reply.slice(start, end + 1));\n  } catch {\n    return scores;\n  }\n\n  if (!Array.isArray(parsed)) {\n    return scores;\n  }\n\n  for (const entry of parsed as ScoreLine[]) {\n    if (\n      entry &&\n      typeof entry.index === \"number\" &&\n      typeof entry.score === \"number\" &&\n      Number.isFinite(entry.score)\n    ) {\n      scores.set(entry.index, Math.max(0, Math.min(1, entry.score)));\n    }\n  }\n\n  return scores;\n}\n\n/**\n * Optional model-backed reranker.\n *\n * Asks an LLM to grade each over-fetched candidate's relevance to the\n * query on a `0..1` scale, then sorts descending by the model's score.\n * Candidates the model does not score keep their original cosine score, so\n * a partial/garbled reply degrades gracefully rather than dropping hits.\n * Scoring is batched (`batchSize`) to bound prompt length.\n *\n * Unlike {@link keywordReranker}, this costs one or more model calls per\n * retrieval — opt in only when precision matters more than latency/cost.\n *\n * @example\n * const kb = ai.rag({\n *   embedder,\n *   store,\n *   reranker: ai.rag.llmReranker({ model: openai.model({ name: \"gpt-4o-mini\" }) }),\n * });\n */\nexport function llmReranker(options: LlmRerankerOptions): RagReranker {\n  const batchSize = options.batchSize ?? 10;\n\n  return {\n    name: \"llm\",\n    async rerank(query: string, candidates: RetrievedChunk[]): Promise<RetrievedChunk[]> {\n      if (candidates.length === 0) {\n        return [];\n      }\n\n      const rescored: RetrievedChunk[] = [];\n\n      for (let offset = 0; offset < candidates.length; offset += batchSize) {\n        const batch = candidates.slice(offset, offset + batchSize);\n        const response = await options.model.complete(buildPrompt(query, batch));\n        const scores = parseScores(response.content);\n\n        batch.forEach((candidate, index) => {\n          const score = scores.has(index) ? (scores.get(index) as number) : candidate.score;\n\n          rescored.push({\n            ...candidate,\n            score,\n            citation: { ...candidate.citation, score },\n          });\n        });\n      }\n\n      return rescored.sort((first, second) => second.score - first.score);\n    },\n  };\n}\n"],"mappings":";;;;;;AA8BA,SAAS,YAAY,OAAe,YAAyC;CAK3E,OAAO,CACL;EACE,MAAM;EACN,SACE;CACJ,GACA;EACE,MAAM;EACN,SAAS,UAAU,MAAM,iBAZf,WACX,KAAK,WAAW,UAAU,IAAI,MAAM,IAAI,UAAU,MAAM,CAAC,CACzD,KAAK,MAU0C;CAChD,CACF;AACF;;;;;;;AAQA,SAAS,YAAY,OAAoC;CACvD,MAAM,yBAAS,IAAI,IAAoB;CACvC,MAAM,QAAQ,MAAM,QAAQ,GAAG;CAC/B,MAAM,MAAM,MAAM,YAAY,GAAG;CAEjC,IAAI,UAAU,MAAM,QAAQ,MAAM,OAAO,OACvC,OAAO;CAGT,IAAI;CACJ,IAAI;EACF,SAAS,KAAK,MAAM,MAAM,MAAM,OAAO,MAAM,CAAC,CAAC;CACjD,QAAQ;EACN,OAAO;CACT;CAEA,IAAI,CAAC,MAAM,QAAQ,MAAM,GACvB,OAAO;CAGT,KAAK,MAAM,SAAS,QAClB,IACE,SACA,OAAO,MAAM,UAAU,YACvB,OAAO,MAAM,UAAU,YACvB,OAAO,SAAS,MAAM,KAAK,GAE3B,OAAO,IAAI,MAAM,OAAO,KAAK,IAAI,GAAG,KAAK,IAAI,GAAG,MAAM,KAAK,CAAC,CAAC;CAIjE,OAAO;AACT;;;;;;;;;;;;;;;;;;;;AAqBA,SAAgB,YAAY,SAA0C;CACpE,MAAM,YAAY,QAAQ,aAAa;CAEvC,OAAO;EACL,MAAM;EACN,MAAM,OAAO,OAAe,YAAyD;GACnF,IAAI,WAAW,WAAW,GACxB,OAAO,CAAC;GAGV,MAAM,WAA6B,CAAC;GAEpC,KAAK,IAAI,SAAS,GAAG,SAAS,WAAW,QAAQ,UAAU,WAAW;IACpE,MAAM,QAAQ,WAAW,MAAM,QAAQ,SAAS,SAAS;IAEzD,MAAM,SAAS,aAAY,MADJ,QAAQ,MAAM,SAAS,YAAY,OAAO,KAAK,CAAC,EACpC,CAAC,OAAO;IAE3C,MAAM,SAAS,WAAW,UAAU;KAClC,MAAM,QAAQ,OAAO,IAAI,KAAK,IAAK,OAAO,IAAI,KAAK,IAAe,UAAU;KAE5E,SAAS,KAAK;MACZ,GAAG;MACH;MACA,UAAU;OAAE,GAAG,UAAU;OAAU;MAAM;KAC3C,CAAC;IACH,CAAC;GACH;GAEA,OAAO,SAAS,MAAM,OAAO,WAAW,OAAO,QAAQ,MAAM,KAAK;EACpE;CACF;AACF"}
+{"version":3,"file":"llm-reranker.mjs","names":[],"sources":["../../../../../../../../ai/src/rag/rerank/llm-reranker.ts"],"sourcesContent":["import type { Message } from \"../../contracts/conversation-message.type\";\nimport type { ModelContract } from \"../../contracts/model.contract\";\nimport type { RetrievedChunk } from \"../contracts/citation.type\";\nimport type { RagReranker } from \"./reranker.contract\";\n\n/** Options for the {@link llmReranker}. */\nexport type LlmRerankerOptions = {\n  /** The model used to score candidate relevance. Required. */\n  model: ModelContract;\n  /**\n   * How many candidates to score per model call. Larger batches mean\n   * fewer round-trips but a longer prompt. Default `10`.\n   */\n  batchSize?: number;\n};\n\n/**\n * A single relevance score the model returns for a candidate, in `[0, 1]`,\n * keyed by the candidate's position in the batch.\n */\ntype ScoreLine = {\n  index: number;\n  score: number;\n};\n\n/**\n * Build the scoring prompt — the model rates each candidate's relevance to\n * the query on a `0..1` scale and replies with one `index: score` line per\n * candidate. Kept terse and JSON-light so any chat model can answer.\n */\nfunction buildPrompt(query: string, candidates: RetrievedChunk[]): Message[] {\n  const lines = candidates\n    .map((candidate, index) => `[${index}] ${candidate.text}`)\n    .join(\"\\n\\n\");\n\n  return [\n    {\n      role: \"system\",\n      content:\n        \"You are a relevance grader. For each numbered passage, rate how well it answers the query on a scale from 0 (irrelevant) to 1 (fully relevant). Reply with ONLY a JSON array of objects like [{\\\"index\\\":0,\\\"score\\\":0.9}], one entry per passage, no prose.\",\n    },\n    {\n      role: \"user\",\n      content: `Query: ${query}\\n\\nPassages:\\n${lines}`,\n    },\n  ];\n}\n\n/**\n * Parse the model's reply into a score map. Tolerant of surrounding prose:\n * extracts the first JSON array and reads `{ index, score }` entries.\n * Returns an empty map when nothing parseable is found, so the caller can\n * fall back to the original order.\n */\nfunction parseScores(reply: string): Map<number, number> {\n  const scores = new Map<number, number>();\n  const start = reply.indexOf(\"[\");\n  const end = reply.lastIndexOf(\"]\");\n\n  if (start === -1 || end === -1 || end <= start) {\n    return scores;\n  }\n\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(reply.slice(start, end + 1));\n  } catch {\n    return scores;\n  }\n\n  if (!Array.isArray(parsed)) {\n    return scores;\n  }\n\n  for (const entry of parsed as ScoreLine[]) {\n    if (\n      entry &&\n      typeof entry.index === \"number\" &&\n      typeof entry.score === \"number\" &&\n      Number.isFinite(entry.score)\n    ) {\n      scores.set(entry.index, Math.max(0, Math.min(1, entry.score)));\n    }\n  }\n\n  return scores;\n}\n\n/**\n * Optional model-backed reranker.\n *\n * Asks an LLM to grade each over-fetched candidate's relevance to the\n * query on a `0..1` scale, then sorts descending by the model's score.\n * Candidates the model does not score keep their original cosine score, so\n * a partial/garbled reply degrades gracefully rather than dropping hits.\n * Scoring is batched (`batchSize`) to bound prompt length.\n *\n * Unlike {@link keywordReranker}, this costs one or more model calls per\n * retrieval — opt in only when precision matters more than latency/cost.\n *\n * @example\n * const kb = ai.rag({\n *   embedder,\n *   store,\n *   reranker: ai.rag.llmReranker({ model: openai.model({ name: \"gpt-4o-mini\" }) }),\n * });\n */\nexport function llmReranker(options: LlmRerankerOptions): RagReranker {\n  const batchSize = options.batchSize ?? 10;\n\n  return {\n    name: \"llm\",\n    async rerank(query: string, candidates: RetrievedChunk[]): Promise<RetrievedChunk[]> {\n      if (candidates.length === 0) {\n        return [];\n      }\n\n      const rescored: RetrievedChunk[] = [];\n\n      for (let offset = 0; offset < candidates.length; offset += batchSize) {\n        const batch = candidates.slice(offset, offset + batchSize);\n        const response = await options.model.complete(buildPrompt(query, batch));\n        const scores = parseScores(response.content);\n\n        batch.forEach((candidate, index) => {\n          const score = scores.has(index) ? (scores.get(index) as number) : candidate.score;\n\n          rescored.push({\n            ...candidate,\n            score,\n            citation: { ...candidate.citation, score },\n          });\n        });\n      }\n\n      return rescored.sort((first, second) => second.score - first.score);\n    },\n  };\n}\n"],"mappings":";;;;;;AA8BA,SAAS,YAAY,OAAe,YAAyC;CAK3E,OAAO,CACL;EACE,MAAM;EACN,SACE;CACJ,GACA;EACE,MAAM;EACN,SAAS,UAAU,MAAM,iBAZf,WACX,KAAK,WAAW,UAAU,IAAI,MAAM,IAAI,UAAU,MAAM,EACxD,KAAK,MAU0C;CAChD,CACF;AACF;;;;;;;AAQA,SAAS,YAAY,OAAoC;CACvD,MAAM,yBAAS,IAAI,IAAoB;CACvC,MAAM,QAAQ,MAAM,QAAQ,GAAG;CAC/B,MAAM,MAAM,MAAM,YAAY,GAAG;CAEjC,IAAI,UAAU,MAAM,QAAQ,MAAM,OAAO,OACvC,OAAO;CAGT,IAAI;CACJ,IAAI;EACF,SAAS,KAAK,MAAM,MAAM,MAAM,OAAO,MAAM,CAAC,CAAC;CACjD,QAAQ;EACN,OAAO;CACT;CAEA,IAAI,CAAC,MAAM,QAAQ,MAAM,GACvB,OAAO;CAGT,KAAK,MAAM,SAAS,QAClB,IACE,SACA,OAAO,MAAM,UAAU,YACvB,OAAO,MAAM,UAAU,YACvB,OAAO,SAAS,MAAM,KAAK,GAE3B,OAAO,IAAI,MAAM,OAAO,KAAK,IAAI,GAAG,KAAK,IAAI,GAAG,MAAM,KAAK,CAAC,CAAC;CAIjE,OAAO;AACT;;;;;;;;;;;;;;;;;;;;AAqBA,SAAgB,YAAY,SAA0C;CACpE,MAAM,YAAY,QAAQ,aAAa;CAEvC,OAAO;EACL,MAAM;EACN,MAAM,OAAO,OAAe,YAAyD;GACnF,IAAI,WAAW,WAAW,GACxB,OAAO,CAAC;GAGV,MAAM,WAA6B,CAAC;GAEpC,KAAK,IAAI,SAAS,GAAG,SAAS,WAAW,QAAQ,UAAU,WAAW;IACpE,MAAM,QAAQ,WAAW,MAAM,QAAQ,SAAS,SAAS;IAEzD,MAAM,SAAS,aAAY,MADJ,QAAQ,MAAM,SAAS,YAAY,OAAO,KAAK,CAAC,GACnC,OAAO;IAE3C,MAAM,SAAS,WAAW,UAAU;KAClC,MAAM,QAAQ,OAAO,IAAI,KAAK,IAAK,OAAO,IAAI,KAAK,IAAe,UAAU;KAE5E,SAAS,KAAK;MACZ,GAAG;MACH;MACA,UAAU;OAAE,GAAG,UAAU;OAAU;MAAM;KAC3C,CAAC;IACH,CAAC;GACH;GAEA,OAAO,SAAS,MAAM,OAAO,WAAW,OAAO,QAAQ,MAAM,KAAK;EACpE;CACF;AACF"}

package/esm/rag/retrieve.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"retrieve.mjs","names":[],"sources":["../../../../../../../ai/src/rag/retrieve.ts"],"sourcesContent":["import type { EmbedderContract } from \"../contracts/embedder.contract\";\nimport type {\n  Citation,\n  RetrievedChunk,\n  RetrieveOptions,\n  RetrieveResult,\n} from \"./contracts/citation.type\";\nimport type { RagReranker } from \"./rerank/reranker.contract\";\nimport type { VectorStore } from \"./store/vector-store.contract\";\n\n/** Default number of chunks returned after reranking. */\nexport const DEFAULT_TOP_K = 5;\n\n/** Default cosine floor applied at the vector-store stage. */\nexport const DEFAULT_THRESHOLD = 0.5;\n\n/**\n * Shape persisted per chunk in the vector store. The vector itself is held\n * by the driver's own index (passed via `set({ vector })`), so it is not\n * duplicated here.\n */\nexport type StoredChunk = {\n  sourceId: string;\n  chunkIndex: number;\n  span: [start: number, end: number];\n  text: string;\n  metadata?: Record<string, unknown>;\n};\n\n/** Dependencies the retrieve pipeline needs, resolved once by `rag()`. */\nexport type RetrieveDeps = {\n  embedder: EmbedderContract;\n  store: VectorStore;\n  /** Namespace prefix every stored key carries (e.g. `\"ai.rag.docs\"`). */\n  namespace: string;\n  /** Optional reranker; when absent the cosine order is kept. */\n  reranker?: RagReranker;\n  /** Pipeline-level retrieval defaults. */\n  defaults?: RetrieveOptions;\n  /**\n   * Dimension count captured at first index for the mismatch guard. When\n   * set, the query embedder's `dimensions` must equal it.\n   */\n  indexedDimensions?: number;\n};\n\n/**\n * The cite pipeline: embed the query → over-fetch candidates from the\n * store → filter to this rag's namespace → map to {@link RetrievedChunk}s\n * with a {@link Citation} → optionally rerank → slice `topK`.\n *\n * Behavior matches the design's failure modes:\n * - No hits clearing the threshold → `{ query, chunks: [] }`, never throws.\n * - Namespace-prefix filtering keeps two rags sharing one driver isolated.\n * - A reranker that throws is caught; the raw cosine order is used instead.\n * - A dimension mismatch (indexed with model A, queried with model B)\n *   throws a clear error rather than returning garbage hits.\n */\nexport async function retrieve(\n  query: string,\n  deps: RetrieveDeps,\n  options: RetrieveOptions = {},\n): Promise<RetrieveResult> {\n  const topK = options.topK ?? deps.defaults?.topK ?? DEFAULT_TOP_K;\n  const threshold = options.threshold ?? deps.defaults?.threshold ?? DEFAULT_THRESHOLD;\n  const tags = options.tags ?? deps.defaults?.tags;\n  const candidates = options.candidates ?? deps.defaults?.candidates ?? Math.max(topK * 4, topK);\n\n  const { vector, dimensions } = await deps.embedder.embed(query);\n\n  if (\n    deps.indexedDimensions !== undefined &&\n    dimensions !== 0 &&\n    deps.indexedDimensions !== 0 &&\n    dimensions !== deps.indexedDimensions\n  ) {\n    throw new Error(\n      `rag.retrieve(): query embedder dimensions (${dimensions}) do not match the dimensions captured at index time (${deps.indexedDimensions}); index and query must use the same embedding model`,\n    );\n  }\n\n  const hits = await deps.store.query<StoredChunk>(vector, {\n    topK: candidates,\n    threshold,\n    tags,\n  });\n\n  const prefix = `${deps.namespace}.`;\n\n  let retrieved: RetrievedChunk[] = hits\n    .filter((hit) => hit.key.startsWith(prefix))\n    .map((hit) => toRetrievedChunk(hit.value, hit.score));\n\n  retrieved = await applyReranker(query, retrieved, deps.reranker);\n\n  return { query, chunks: retrieved.slice(0, topK) };\n}\n\n/** Build a cited {@link RetrievedChunk} from a stored chunk + its cosine score. */\nfunction toRetrievedChunk(stored: StoredChunk, score: number): RetrievedChunk {\n  const citation: Citation = {\n    sourceId: stored.sourceId,\n    chunkIndex: stored.chunkIndex,\n    span: stored.span,\n    score,\n    metadata: stored.metadata,\n  };\n\n  return { text: stored.text, score, citation };\n}\n\n/**\n * Run the optional reranker, degrading to the raw cosine order if it\n * throws — a flaky optional reranker must never fail the whole retrieval.\n */\nasync function applyReranker(\n  query: string,\n  candidates: RetrievedChunk[],\n  reranker: RagReranker | undefined,\n): Promise<RetrievedChunk[]> {\n  if (!reranker) {\n    return candidates;\n  }\n\n  try {\n    return await reranker.rerank(query, candidates);\n  } catch {\n    // Logged at the call site in a richer build; here we degrade silently\n    // to vector-only ranking rather than aborting the retrieval.\n    return candidates;\n  }\n}\n"],"mappings":";;AAWA,MAAa,gBAAgB;;AAG7B,MAAa,oBAAoB;;;;;;;;;;;;;AA4CjC,eAAsB,SACpB,OACA,MACA,UAA2B,CAAC,GACH;CACzB,MAAM,OAAO,QAAQ,QAAQ,KAAK,UAAU;CAC5C,MAAM,YAAY,QAAQ,aAAa,KAAK,UAAU;CACtD,MAAM,OAAO,QAAQ,QAAQ,KAAK,UAAU;CAC5C,MAAM,aAAa,QAAQ,cAAc,KAAK,UAAU,cAAc,KAAK,IAAI,OAAO,GAAG,IAAI;CAE7F,MAAM,EAAE,QAAQ,eAAe,MAAM,KAAK,SAAS,MAAM,KAAK;CAE9D,IACE,KAAK,sBAAsB,UAC3B,eAAe,KACf,KAAK,sBAAsB,KAC3B,eAAe,KAAK,mBAEpB,MAAM,IAAI,MACR,8CAA8C,WAAW,wDAAwD,KAAK,kBAAkB,qDAC1I;CAGF,MAAM,OAAO,MAAM,KAAK,MAAM,MAAmB,QAAQ;EACvD,MAAM;EACN;EACA;CACF,CAAC;CAED,MAAM,SAAS,GAAG,KAAK,UAAU;CAEjC,IAAI,YAA8B,KAC/B,QAAQ,QAAQ,IAAI,IAAI,WAAW,MAAM,CAAC,CAAC,CAC3C,KAAK,QAAQ,iBAAiB,IAAI,OAAO,IAAI,KAAK,CAAC;CAEtD,YAAY,MAAM,cAAc,OAAO,WAAW,KAAK,QAAQ;CAE/D,OAAO;EAAE;EAAO,QAAQ,UAAU,MAAM,GAAG,IAAI;CAAE;AACnD;;AAGA,SAAS,iBAAiB,QAAqB,OAA+B;CAC5E,MAAM,WAAqB;EACzB,UAAU,OAAO;EACjB,YAAY,OAAO;EACnB,MAAM,OAAO;EACb;EACA,UAAU,OAAO;CACnB;CAEA,OAAO;EAAE,MAAM,OAAO;EAAM;EAAO;CAAS;AAC9C;;;;;AAMA,eAAe,cACb,OACA,YACA,UAC2B;CAC3B,IAAI,CAAC,UACH,OAAO;CAGT,IAAI;EACF,OAAO,MAAM,SAAS,OAAO,OAAO,UAAU;CAChD,QAAQ;EAGN,OAAO;CACT;AACF"}
+{"version":3,"file":"retrieve.mjs","names":[],"sources":["../../../../../../../ai/src/rag/retrieve.ts"],"sourcesContent":["import type { EmbedderContract } from \"../contracts/embedder.contract\";\nimport type {\n  Citation,\n  RetrievedChunk,\n  RetrieveOptions,\n  RetrieveResult,\n} from \"./contracts/citation.type\";\nimport type { RagReranker } from \"./rerank/reranker.contract\";\nimport type { VectorStore } from \"./store/vector-store.contract\";\n\n/** Default number of chunks returned after reranking. */\nexport const DEFAULT_TOP_K = 5;\n\n/** Default cosine floor applied at the vector-store stage. */\nexport const DEFAULT_THRESHOLD = 0.5;\n\n/**\n * Shape persisted per chunk in the vector store. The vector itself is held\n * by the driver's own index (passed via `set({ vector })`), so it is not\n * duplicated here.\n */\nexport type StoredChunk = {\n  sourceId: string;\n  chunkIndex: number;\n  span: [start: number, end: number];\n  text: string;\n  metadata?: Record<string, unknown>;\n};\n\n/** Dependencies the retrieve pipeline needs, resolved once by `rag()`. */\nexport type RetrieveDeps = {\n  embedder: EmbedderContract;\n  store: VectorStore;\n  /** Namespace prefix every stored key carries (e.g. `\"ai.rag.docs\"`). */\n  namespace: string;\n  /** Optional reranker; when absent the cosine order is kept. */\n  reranker?: RagReranker;\n  /** Pipeline-level retrieval defaults. */\n  defaults?: RetrieveOptions;\n  /**\n   * Dimension count captured at first index for the mismatch guard. When\n   * set, the query embedder's `dimensions` must equal it.\n   */\n  indexedDimensions?: number;\n};\n\n/**\n * The cite pipeline: embed the query → over-fetch candidates from the\n * store → filter to this rag's namespace → map to {@link RetrievedChunk}s\n * with a {@link Citation} → optionally rerank → slice `topK`.\n *\n * Behavior matches the design's failure modes:\n * - No hits clearing the threshold → `{ query, chunks: [] }`, never throws.\n * - Namespace-prefix filtering keeps two rags sharing one driver isolated.\n * - A reranker that throws is caught; the raw cosine order is used instead.\n * - A dimension mismatch (indexed with model A, queried with model B)\n *   throws a clear error rather than returning garbage hits.\n */\nexport async function retrieve(\n  query: string,\n  deps: RetrieveDeps,\n  options: RetrieveOptions = {},\n): Promise<RetrieveResult> {\n  const topK = options.topK ?? deps.defaults?.topK ?? DEFAULT_TOP_K;\n  const threshold = options.threshold ?? deps.defaults?.threshold ?? DEFAULT_THRESHOLD;\n  const tags = options.tags ?? deps.defaults?.tags;\n  const candidates = options.candidates ?? deps.defaults?.candidates ?? Math.max(topK * 4, topK);\n\n  const { vector, dimensions } = await deps.embedder.embed(query);\n\n  if (\n    deps.indexedDimensions !== undefined &&\n    dimensions !== 0 &&\n    deps.indexedDimensions !== 0 &&\n    dimensions !== deps.indexedDimensions\n  ) {\n    throw new Error(\n      `rag.retrieve(): query embedder dimensions (${dimensions}) do not match the dimensions captured at index time (${deps.indexedDimensions}); index and query must use the same embedding model`,\n    );\n  }\n\n  const hits = await deps.store.query<StoredChunk>(vector, {\n    topK: candidates,\n    threshold,\n    tags,\n  });\n\n  const prefix = `${deps.namespace}.`;\n\n  let retrieved: RetrievedChunk[] = hits\n    .filter((hit) => hit.key.startsWith(prefix))\n    .map((hit) => toRetrievedChunk(hit.value, hit.score));\n\n  retrieved = await applyReranker(query, retrieved, deps.reranker);\n\n  return { query, chunks: retrieved.slice(0, topK) };\n}\n\n/** Build a cited {@link RetrievedChunk} from a stored chunk + its cosine score. */\nfunction toRetrievedChunk(stored: StoredChunk, score: number): RetrievedChunk {\n  const citation: Citation = {\n    sourceId: stored.sourceId,\n    chunkIndex: stored.chunkIndex,\n    span: stored.span,\n    score,\n    metadata: stored.metadata,\n  };\n\n  return { text: stored.text, score, citation };\n}\n\n/**\n * Run the optional reranker, degrading to the raw cosine order if it\n * throws — a flaky optional reranker must never fail the whole retrieval.\n */\nasync function applyReranker(\n  query: string,\n  candidates: RetrievedChunk[],\n  reranker: RagReranker | undefined,\n): Promise<RetrievedChunk[]> {\n  if (!reranker) {\n    return candidates;\n  }\n\n  try {\n    return await reranker.rerank(query, candidates);\n  } catch {\n    // Logged at the call site in a richer build; here we degrade silently\n    // to vector-only ranking rather than aborting the retrieval.\n    return candidates;\n  }\n}\n"],"mappings":";;AAWA,MAAa,gBAAgB;;AAG7B,MAAa,oBAAoB;;;;;;;;;;;;;AA4CjC,eAAsB,SACpB,OACA,MACA,UAA2B,CAAC,GACH;CACzB,MAAM,OAAO,QAAQ,QAAQ,KAAK,UAAU;CAC5C,MAAM,YAAY,QAAQ,aAAa,KAAK,UAAU;CACtD,MAAM,OAAO,QAAQ,QAAQ,KAAK,UAAU;CAC5C,MAAM,aAAa,QAAQ,cAAc,KAAK,UAAU,cAAc,KAAK,IAAI,OAAO,GAAG,IAAI;CAE7F,MAAM,EAAE,QAAQ,eAAe,MAAM,KAAK,SAAS,MAAM,KAAK;CAE9D,IACE,KAAK,sBAAsB,UAC3B,eAAe,KACf,KAAK,sBAAsB,KAC3B,eAAe,KAAK,mBAEpB,MAAM,IAAI,MACR,8CAA8C,WAAW,wDAAwD,KAAK,kBAAkB,qDAC1I;CAGF,MAAM,OAAO,MAAM,KAAK,MAAM,MAAmB,QAAQ;EACvD,MAAM;EACN;EACA;CACF,CAAC;CAED,MAAM,SAAS,GAAG,KAAK,UAAU;CAEjC,IAAI,YAA8B,KAC/B,QAAQ,QAAQ,IAAI,IAAI,WAAW,MAAM,CAAC,EAC1C,KAAK,QAAQ,iBAAiB,IAAI,OAAO,IAAI,KAAK,CAAC;CAEtD,YAAY,MAAM,cAAc,OAAO,WAAW,KAAK,QAAQ;CAE/D,OAAO;EAAE;EAAO,QAAQ,UAAU,MAAM,GAAG,IAAI;CAAE;AACnD;;AAGA,SAAS,iBAAiB,QAAqB,OAA+B;CAC5E,MAAM,WAAqB;EACzB,UAAU,OAAO;EACjB,YAAY,OAAO;EACnB,MAAM,OAAO;EACb;EACA,UAAU,OAAO;CACnB;CAEA,OAAO;EAAE,MAAM,OAAO;EAAM;EAAO;CAAS;AAC9C;;;;;AAMA,eAAe,cACb,OACA,YACA,UAC2B;CAC3B,IAAI,CAAC,UACH,OAAO;CAGT,IAAI;EACF,OAAO,MAAM,SAAS,OAAO,OAAO,UAAU;CAChD,QAAQ;EAGN,OAAO;CACT;AACF"}

package/esm/rag/store/cache-vector-store.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"cache-vector-store.mjs","names":[],"sources":["../../../../../../../../ai/src/rag/store/cache-vector-store.ts"],"sourcesContent":["import type { CacheDriver } from \"@warlock.js/cache\";\nimport type { VectorStore } from \"./vector-store.contract\";\n\n/**\n * Adapt any `@warlock.js/cache` `CacheDriver` to the {@link VectorStore}\n * narrowing the RAG pipeline depends on. The cache driver IS the vector\n * store — exactly as `SemanticMemory` and `semanticCache` already use it:\n *\n * - `upsert` → `driver.set(key, value, { vector, tags })`\n * - `query`  → `driver.similar<T>(vector, { topK, threshold, tags })`\n * - `removeNamespace` → `driver.removeNamespace(namespace)`\n *\n * Drivers without similarity support throw `CacheUnsupportedError` from\n * `set({ vector })` / `similar()`; the error surfaces unchanged so the\n * caller sees the cache layer's own message (pointing at the `pg` /\n * `redis` drivers for production-scale similarity).\n *\n * @example\n * const store = cacheVectorStore(new MemoryCacheDriver());\n * await store.upsert(\"ai.rag.docs.guide.0\", { text: \"…\" }, vector);\n * const hits = await store.query(queryVector, { topK: 5, threshold: 0.5 });\n */\nexport function cacheVectorStore(driver: CacheDriver<any, any>): VectorStore {\n  return {\n    async upsert(\n      key: string,\n      value: unknown,\n      vector: number[],\n      tags?: string[],\n    ): Promise<void> {\n      await driver.set(key, value, tags && tags.length > 0 ? { vector, tags } : { vector });\n    },\n\n    async query<T>(\n      vector: number[],\n      options: { topK: number; threshold?: number; tags?: string[] },\n    ): Promise<{ key: string; value: T; score: number }[]> {\n      const hits = await driver.similar<T>(vector, {\n        topK: options.topK,\n        threshold: options.threshold,\n        tags: options.tags,\n      });\n\n      return hits.map((hit: { key: string; value: T; score: number }) => ({\n        key: hit.key,\n        value: hit.value,\n        score: hit.score,\n      }));\n    },\n\n    async removeNamespace(namespace: string): Promise<void> {\n      await driver.removeNamespace(namespace);\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAsBA,SAAgB,iBAAiB,QAA4C;CAC3E,OAAO;EACL,MAAM,OACJ,KACA,OACA,QACA,MACe;GACf,MAAM,OAAO,IAAI,KAAK,OAAO,QAAQ,KAAK,SAAS,IAAI;IAAE;IAAQ;GAAK,IAAI,EAAE,OAAO,CAAC;EACtF;EAEA,MAAM,MACJ,QACA,SACqD;GAOrD,QAAO,MANY,OAAO,QAAW,QAAQ;IAC3C,MAAM,QAAQ;IACd,WAAW,QAAQ;IACnB,MAAM,QAAQ;GAChB,CAAC,EAEU,CAAC,KAAK,SAAmD;IAClE,KAAK,IAAI;IACT,OAAO,IAAI;IACX,OAAO,IAAI;GACb,EAAE;EACJ;EAEA,MAAM,gBAAgB,WAAkC;GACtD,MAAM,OAAO,gBAAgB,SAAS;EACxC;CACF;AACF"}
+{"version":3,"file":"cache-vector-store.mjs","names":[],"sources":["../../../../../../../../ai/src/rag/store/cache-vector-store.ts"],"sourcesContent":["import type { CacheDriver } from \"@warlock.js/cache\";\nimport type { VectorStore } from \"./vector-store.contract\";\n\n/**\n * Adapt any `@warlock.js/cache` `CacheDriver` to the {@link VectorStore}\n * narrowing the RAG pipeline depends on. The cache driver IS the vector\n * store — exactly as `SemanticMemory` and `semanticCache` already use it:\n *\n * - `upsert` → `driver.set(key, value, { vector, tags })`\n * - `query`  → `driver.similar<T>(vector, { topK, threshold, tags })`\n * - `removeNamespace` → `driver.removeNamespace(namespace)`\n *\n * Drivers without similarity support throw `CacheUnsupportedError` from\n * `set({ vector })` / `similar()`; the error surfaces unchanged so the\n * caller sees the cache layer's own message (pointing at the `pg` /\n * `redis` drivers for production-scale similarity).\n *\n * @example\n * const store = cacheVectorStore(new MemoryCacheDriver());\n * await store.upsert(\"ai.rag.docs.guide.0\", { text: \"…\" }, vector);\n * const hits = await store.query(queryVector, { topK: 5, threshold: 0.5 });\n */\nexport function cacheVectorStore(driver: CacheDriver<any, any>): VectorStore {\n  return {\n    async upsert(\n      key: string,\n      value: unknown,\n      vector: number[],\n      tags?: string[],\n    ): Promise<void> {\n      await driver.set(key, value, tags && tags.length > 0 ? { vector, tags } : { vector });\n    },\n\n    async query<T>(\n      vector: number[],\n      options: { topK: number; threshold?: number; tags?: string[] },\n    ): Promise<{ key: string; value: T; score: number }[]> {\n      const hits = await driver.similar<T>(vector, {\n        topK: options.topK,\n        threshold: options.threshold,\n        tags: options.tags,\n      });\n\n      return hits.map((hit: { key: string; value: T; score: number }) => ({\n        key: hit.key,\n        value: hit.value,\n        score: hit.score,\n      }));\n    },\n\n    async removeNamespace(namespace: string): Promise<void> {\n      await driver.removeNamespace(namespace);\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAsBA,SAAgB,iBAAiB,QAA4C;CAC3E,OAAO;EACL,MAAM,OACJ,KACA,OACA,QACA,MACe;GACf,MAAM,OAAO,IAAI,KAAK,OAAO,QAAQ,KAAK,SAAS,IAAI;IAAE;IAAQ;GAAK,IAAI,EAAE,OAAO,CAAC;EACtF;EAEA,MAAM,MACJ,QACA,SACqD;GAOrD,QAAO,MANY,OAAO,QAAW,QAAQ;IAC3C,MAAM,QAAQ;IACd,WAAW,QAAQ;IACnB,MAAM,QAAQ;GAChB,CAAC,GAEW,KAAK,SAAmD;IAClE,KAAK,IAAI;IACT,OAAO,IAAI;IACX,OAAO,IAAI;GACb,EAAE;EACJ;EAEA,MAAM,gBAAgB,WAAkC;GACtD,MAAM,OAAO,gBAAgB,SAAS;EACxC;CACF;AACF"}

package/esm/rag/store/pg-vector-store.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"pg-vector-store.mjs","names":[],"sources":["../../../../../../../../ai/src/rag/store/pg-vector-store.ts"],"sourcesContent":["import type { VectorStore } from \"./vector-store.contract\";\n\n/**\n * Minimal `pg`-compatible client surface the Postgres {@link VectorStore}\n * depends on. Both `pg.Pool` and `pg.Client` satisfy it — the store only\n * ever calls `query`.\n *\n * `@warlock.js/ai` takes **no** hard dependency on `pg`; the dev installs\n * it (an optional peer) and passes the client in. Structurally identical\n * to the snapshot / human-interrupt stores' `PgClientLike`, so a single\n * pool can back the orchestrator checkpoint/snapshot tables, the\n * interrupt table, and this vectors table alike.\n */\nexport interface PgClientLike {\n  query(text: string, params?: unknown[]): Promise<{ rows: unknown[] }>;\n}\n\n/**\n * Options for the Postgres {@link VectorStore}.\n *\n * Two mutually-supportive ways to supply the connection (mirroring\n * `ai.human.interrupt.pg`):\n * - **`client`** — pass an already-built `pg.Pool` / `pg.Client` (anything\n *   satisfying {@link PgClientLike}). The store only ever calls `query`\n *   and never opens or closes it; one pool can back several stores.\n * - **`connectionString`** — let the store lazily `import(\"pg\")` and build\n *   its own `Pool`. `@warlock.js/ai` takes **no** hard dependency on\n *   `pg` (an optional peer); when it is absent the store throws a curated\n *   install string at first use, never a raw module-resolution stack trace\n *   at import.\n *\n * Exactly one of the two must be present.\n */\nexport interface PgVectorStoreOptions {\n  /** An already-built `pg.Pool` / `pg.Client` — anything matching {@link PgClientLike}. */\n  client?: PgClientLike;\n\n  /** Connection string the store passes to a lazily-imported `pg.Pool`. */\n  connectionString?: string;\n\n  /**\n   * Backing table name. Defaults to `warlock_ai_rag_vectors`. Must be a\n   * safe SQL identifier — it is interpolated into DDL/DML.\n   */\n  table?: string;\n\n  /**\n   * Embedding dimensionality used in the `CREATE TABLE` DDL emitted by\n   * {@link VectorStore.schema | ensureSchema}. Defaults to `1536`\n   * (OpenAI `text-embedding-3-small`). The column is declared\n   * `vector(N)`; queries and upserts never re-state it, so an existing\n   * table provisioned at a different size is unaffected — only the DDL\n   * helper reads this.\n   */\n  dimensions?: number;\n\n  /**\n   * Approximate-nearest-neighbour index strategy baked into the DDL\n   * emitted by {@link VectorStore.schema | ensureSchema}. Defaults to\n   * `\"hnsw\"` (better recall/latency on modern pgvector). Use `\"ivfflat\"`\n   * for the classic list-partitioned index, or `\"none\"` to emit no ANN\n   * index (exact scan — correct, but linear in row count).\n   */\n  index?: \"hnsw\" | \"ivfflat\" | \"none\";\n\n  /**\n   * `lists` parameter for an `ivfflat` index (ignored for `hnsw` / `none`).\n   * Defaults to `100`. Tune toward `rows / 1000` for large tables.\n   */\n  ivfflatLists?: number;\n}\n\n/**\n * Default backing table — provisions the store with no extra config when\n * the dev runs {@link VectorStore.schema | ensureSchema} through their\n * migration tool.\n */\nconst DEFAULT_TABLE = \"warlock_ai_rag_vectors\";\n\n/** Default embedding width baked into the DDL (OpenAI `text-embedding-3-small`). */\nconst DEFAULT_DIMENSIONS = 1536;\n\n/** Default `ivfflat` list count when that index strategy is chosen. */\nconst DEFAULT_IVFFLAT_LISTS = 100;\n\n/**\n * Allowed characters in a Postgres identifier (table name). The table name\n * is interpolated into DDL/DML, so anything outside this conservative\n * ASCII subset is rejected — interpolating an arbitrary string would be a\n * SQL-injection footgun (mirrors the snapshot / human-interrupt pg stores\n * and `@warlock.js/cache`'s `PgCacheDriver`).\n */\nconst SAFE_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;\n\n/**\n * Module specifier for the optional `pg` driver. Held in a `string`\n * variable so the dynamic `import()` is not statically resolved at compile\n * time — `pg` is an optional peer that need not be installed for this\n * package to type-check or for a cache-only consumer to run.\n */\nconst PG_MODULE = \"pg\";\n\n/**\n * Curated install string surfaced (at use time) when a `connectionString`\n * is configured but the optional `pg` driver is absent. Never thrown at\n * import — a cache-only consumer must be able to load this module.\n */\nconst PG_INSTALL_INSTRUCTIONS = `\nThe @warlock.js/ai Postgres vector store requires the pg package and a\nPostgres database with the pgvector extension. Install the driver with:\n\n  npm install pg\n\nOr with your preferred package manager:\n\n  pnpm add pg\n  yarn add pg\n`.trim();\n\n/**\n * Minimal structural view of a `pg.Pool` constructor — just enough of the\n * `pg` module surface for the store to build a client when handed a\n * `connectionString`. Declared locally (rather than `typeof import(\"pg\")`)\n * so this module type-checks even when `pg` is not installed.\n */\ninterface PgModuleLike {\n  Pool: new (config: { connectionString: string }) => PgClientLike;\n}\n\n/**\n * Lazily import `pg` and return a `Pool` built from `connectionString`. A\n * bare `catch` rethrows the curated install string — a missing optional\n * peer surfaces as actionable guidance, never a raw resolution error.\n */\nasync function buildPgClient(connectionString: string): Promise<PgClientLike> {\n  let sdk: PgModuleLike;\n\n  try {\n    sdk = (await import(PG_MODULE)) as unknown as PgModuleLike;\n  } catch {\n    throw new Error(PG_INSTALL_INSTRUCTIONS);\n  }\n\n  return new sdk.Pool({ connectionString });\n}\n\n/**\n * Serialize a JS `number[]` to the pgvector text literal: `[1,2,3]`.\n * pgvector accepts a vector either as this bracketed literal or via a\n * typed parameter; passing the literal string + an explicit `::vector`\n * cast keeps the store driver-agnostic (no dependency on a registered\n * `pg` type parser).\n *\n * Non-finite components (`NaN` / `±Infinity`) are rejected — pgvector\n * stores only finite floats, and silently coercing them would corrupt the\n * index. The check is cheap relative to the embed call that produced the\n * vector.\n *\n * @example\n * vectorLiteral([1, 0.5, -2]); // \"[1,0.5,-2]\"\n */\nexport function vectorLiteral(vector: number[]): string {\n  let literal = \"[\";\n\n  for (let index = 0; index < vector.length; index++) {\n    const component = vector[index];\n\n    if (!Number.isFinite(component)) {\n      throw new TypeError(\n        `pgVectorStore: embedding component at index ${index} is not finite (${component}); pgvector stores only finite floats.`,\n      );\n    }\n\n    if (index > 0) {\n      literal += \",\";\n    }\n\n    literal += String(component);\n  }\n\n  return literal + \"]\";\n}\n\n/**\n * Coerce a `value` JSONB column back into the stored payload. node-postgres\n * parses `JSONB` into a JS value already, but some pool wrappers hand back\n * the raw string — be defensive across both (mirrors the snapshot store's\n * `parsePayload`).\n */\nfunction parseValue<T>(value: unknown): T {\n  if (typeof value === \"string\") {\n    return JSON.parse(value) as T;\n  }\n\n  return value as T;\n}\n\n/**\n * Coerce a pgvector cosine **distance** (`<=>`, in `[0, 2]`, 0 = identical)\n * into the cosine **similarity** score the {@link VectorStore} contract\n * declares (`[0, 1]`, 1 = identical). `pg` returns the computed distance\n * column as a string for `double precision`; parse then map `1 - distance`,\n * clamped to `[0, 1]` so a tiny floating-point overshoot never yields a\n * score just outside the contract's range.\n */\nfunction distanceToScore(distance: unknown): number {\n  const value = typeof distance === \"string\" ? Number(distance) : (distance as number);\n  const score = 1 - value;\n\n  if (score < 0) {\n    return 0;\n  }\n\n  if (score > 1) {\n    return 1;\n  }\n\n  return score;\n}\n\n/**\n * Postgres + pgvector-backed {@link VectorStore} — one durable row per\n * indexed chunk, keyed by the RAG pipeline's dotted `key`\n * (`ai.rag.<name>.<sourceId>.<chunkIndex>`), with the chunk payload in a\n * `value` JSONB column and the embedding in a `vector` column.\n *\n * Owns: the three RAG vector operations against a pgvector index —\n * `upsert` (INSERT … ON CONFLICT DO UPDATE), `query` (cosine\n * `ORDER BY embedding <=> $vec` with a `threshold` floor + optional `tags`\n * overlap filter, capped at `topK`), and `removeNamespace` (prefix DELETE).\n * Also emits the reference DDL via {@link PgVectorStore.schema} (alias\n * {@link PgVectorStore.ensureSchema}).\n *\n * Does NOT own: the connection lifecycle (a dev-supplied `client` is never\n * closed; a store-built `Pool` from a `connectionString` is also left open\n * for the process to reuse) or schema migration — the dev runs the DDL\n * through their own tool; the framework never auto-migrates.\n *\n * Front it with the {@link pgVectorStore} factory — callers never `new` it.\n */\nclass PgVectorStore implements VectorStore {\n  /** Validated backing table name, safe to interpolate into SQL. */\n  private readonly table: string;\n\n  /** Embedding width baked into the DDL. */\n  private readonly dimensions: number;\n\n  /** ANN index strategy baked into the DDL. */\n  private readonly index: \"hnsw\" | \"ivfflat\" | \"none\";\n\n  /** `lists` parameter for an `ivfflat` index. */\n  private readonly ivfflatLists: number;\n\n  /**\n   * A ready client, or a promise resolving to one the store builds lazily\n   * from a `connectionString`. Resolved once and memoized so the optional\n   * `pg` import happens at most once.\n   */\n  private readonly clientPromise: Promise<PgClientLike>;\n\n  public constructor(options: PgVectorStoreOptions) {\n    const table = options.table ?? DEFAULT_TABLE;\n\n    if (!SAFE_IDENTIFIER.test(table)) {\n      throw new TypeError(\n        `pgVectorStore: invalid table name '${table}'. Allowed: [A-Za-z_][A-Za-z0-9_]*.`,\n      );\n    }\n\n    this.table = table;\n    this.dimensions = options.dimensions ?? DEFAULT_DIMENSIONS;\n    this.index = options.index ?? \"hnsw\";\n    this.ivfflatLists = options.ivfflatLists ?? DEFAULT_IVFFLAT_LISTS;\n\n    if (options.client) {\n      if (typeof options.client.query !== \"function\") {\n        throw new TypeError(\n          \"pgVectorStore requires a 'client' option implementing { query(text, params) } — pass a pg.Pool or pg.Client.\",\n        );\n      }\n\n      this.clientPromise = Promise.resolve(options.client);\n\n      return;\n    }\n\n    if (options.connectionString) {\n      // Defer the optional `pg` import to first use — a curated install\n      // string surfaces from `buildPgClient`, not at construction.\n      this.clientPromise = buildPgClient(options.connectionString);\n\n      return;\n    }\n\n    throw new TypeError(\n      \"pgVectorStore requires either a 'client' or a 'connectionString' option.\",\n    );\n  }\n\n  /**\n   * Resolve the backing client, surfacing the lazy `pg` import's curated\n   * install string on the first call that needs it.\n   */\n  private client(): Promise<PgClientLike> {\n    return this.clientPromise;\n  }\n\n  /**\n   * Index `value` under `key` with its embedding `vector`. Upserts on the\n   * `key` primary key — re-indexing the same chunk overwrites its payload,\n   * embedding, and tags rather than appending a duplicate row. Optional\n   * `tags` ride a `text[]` column so {@link query} can restrict the\n   * candidate set with an array-overlap filter.\n   *\n   * The embedding is sent as a pgvector text literal (`$3`) cast to\n   * `::vector`, so the store needs no registered `pg` type parser. `tags`\n   * defaults to an empty array (never `NULL`) to keep the overlap filter's\n   * `&&` semantics simple.\n   */\n  public async upsert(\n    key: string,\n    value: unknown,\n    vector: number[],\n    tags?: string[],\n  ): Promise<void> {\n    const client = await this.client();\n\n    await client.query(\n      `INSERT INTO ${this.table} (key, value, embedding, tags)\n       VALUES ($1, $2::jsonb, $3::vector, $4::text[])\n       ON CONFLICT (key) DO UPDATE\n         SET value = EXCLUDED.value,\n             embedding = EXCLUDED.embedding,\n             tags = EXCLUDED.tags`,\n      [key, JSON.stringify(value), vectorLiteral(vector), tags ?? []],\n    );\n  }\n\n  /**\n   * Return the cosine-nearest rows to `vector`, mapped to the contract's\n   * `{ key, value, score }` shape. The SQL:\n   *\n   * - computes `embedding <=> $1::vector` (cosine **distance**) once, aliased\n   *   `distance`, and `ORDER BY` it ascending (nearest first);\n   * - applies the `threshold` floor as `distance <= 1 - threshold`\n   *   (similarity `>=` threshold), so the default `0.5` floor maps to a\n   *   `<= 0.5` distance bound — the filter runs in SQL, not in JS, so a\n   *   below-floor row never crosses the wire;\n   * - when `tags` are given, restricts to rows whose `tags` array overlaps\n   *   the requested set via `tags && $tags::text[]` (one-of semantics,\n   *   matching the cache store);\n   * - caps the result at `topK` with `LIMIT`.\n   *\n   * The returned `score` is `1 - distance`, clamped to `[0, 1]`, so callers\n   * see the same cosine-similarity scale the cache store emits.\n   */\n  public async query<T>(\n    vector: number[],\n    options: { topK: number; threshold?: number; tags?: string[] },\n  ): Promise<{ key: string; value: T; score: number }[]> {\n    const client = await this.client();\n    const queryVector = vectorLiteral(vector);\n\n    // $1 = query vector, $2 = topK. Optional threshold + tags are appended\n    // as $3 / $4 only when present, so the prepared statement carries no\n    // unused placeholders.\n    const params: unknown[] = [queryVector, options.topK];\n    const conditions: string[] = [];\n\n    if (options.threshold !== undefined) {\n      params.push(1 - options.threshold);\n      conditions.push(`(embedding <=> $1::vector) <= $${params.length}`);\n    }\n\n    if (options.tags !== undefined && options.tags.length > 0) {\n      params.push(options.tags);\n      conditions.push(`tags && $${params.length}::text[]`);\n    }\n\n    const where = conditions.length > 0 ? `WHERE ${conditions.join(\" AND \")}` : \"\";\n\n    const { rows } = await client.query(\n      `SELECT key, value, (embedding <=> $1::vector) AS distance\n       FROM ${this.table}\n       ${where}\n       ORDER BY embedding <=> $1::vector\n       LIMIT $2`,\n      params,\n    );\n\n    return (rows as Record<string, unknown>[]).map((row) => ({\n      key: row.key as string,\n      value: parseValue<T>(row.value),\n      score: distanceToScore(row.distance),\n    }));\n  }\n\n  /**\n   * Drop every entry written under `namespace`. The RAG pipeline keys\n   * chunks as `<namespace>.<sourceId>.<chunkIndex>`, so a row belongs to\n   * the namespace when its `key` equals it OR begins with `<namespace>.`\n   * — deleting `ai.rag.docs` must not also catch `ai.rag.docs2`. The `_`\n   * and `%` LIKE wildcards in the namespace are escaped so a namespace\n   * that happens to contain them is matched literally.\n   */\n  public async removeNamespace(namespace: string): Promise<void> {\n    const client = await this.client();\n\n    const escaped = namespace\n      .replace(/\\\\/g, \"\\\\\\\\\")\n      .replace(/_/g, \"\\\\_\")\n      .replace(/%/g, \"\\\\%\");\n\n    await client.query(\n      `DELETE FROM ${this.table}\n       WHERE key = $1 OR key LIKE $2 ESCAPE '\\\\'`,\n      [namespace, `${escaped}.%`],\n    );\n  }\n\n  /**\n   * Return the reference migration DDL for this store's backing table,\n   * interpolating the configured table name, embedding width, and ANN\n   * index strategy. The dev runs it once through their migration tool —\n   * the framework never auto-migrates.\n   *\n   * The emitted statements:\n   * 1. `CREATE EXTENSION IF NOT EXISTS vector;` — enables pgvector (needs\n   *    a superuser or a role with `CREATE` on the database the first time).\n   * 2. `CREATE TABLE IF NOT EXISTS <table> (key TEXT PRIMARY KEY, value\n   *    JSONB NOT NULL, embedding vector(<dimensions>) NOT NULL, tags\n   *    text[] NOT NULL DEFAULT '{}');`\n   * 3. A GIN index on `tags` so the array-overlap filter stays sargable.\n   * 4. The chosen ANN index over `embedding` using `vector_cosine_ops`:\n   *    - `\"hnsw\"` → `USING hnsw (embedding vector_cosine_ops)`;\n   *    - `\"ivfflat\"` → `USING ivfflat (embedding vector_cosine_ops)\n   *      WITH (lists = <ivfflatLists>)`;\n   *    - `\"none\"` → emitted as a comment (exact scan, no ANN index).\n   *\n   * @example\n   * const store = pgVectorStore({ client: pool, dimensions: 1536 });\n   * await pool.query(store.ensureSchema());\n   */\n  public schema(): string {\n    const lines = [\n      `CREATE EXTENSION IF NOT EXISTS vector;`,\n      `CREATE TABLE IF NOT EXISTS ${this.table} (`,\n      `  key        TEXT PRIMARY KEY,`,\n      `  value      JSONB NOT NULL,`,\n      `  embedding  vector(${this.dimensions}) NOT NULL,`,\n      `  tags       TEXT[] NOT NULL DEFAULT '{}'`,\n      `);`,\n      `CREATE INDEX IF NOT EXISTS idx_${this.table}_tags`,\n      `  ON ${this.table} USING gin (tags);`,\n    ];\n\n    if (this.index === \"hnsw\") {\n      lines.push(\n        `CREATE INDEX IF NOT EXISTS idx_${this.table}_embedding`,\n        `  ON ${this.table} USING hnsw (embedding vector_cosine_ops);`,\n      );\n    } else if (this.index === \"ivfflat\") {\n      lines.push(\n        `CREATE INDEX IF NOT EXISTS idx_${this.table}_embedding`,\n        `  ON ${this.table} USING ivfflat (embedding vector_cosine_ops)`,\n        `  WITH (lists = ${this.ivfflatLists});`,\n      );\n    } else {\n      lines.push(\n        `-- No ANN index requested (index: \"none\"): cosine queries fall back`,\n        `-- to an exact sequential scan, which is correct but linear in rows.`,\n      );\n    }\n\n    return lines.join(\"\\n\");\n  }\n\n  /**\n   * Alias for {@link PgVectorStore.schema} — reads more naturally in a\n   * migration script (`await pool.query(store.ensureSchema())`). Returns\n   * the identical DDL string; it does NOT execute anything against the\n   * database (the store never auto-migrates).\n   */\n  public ensureSchema(): string {\n    return this.schema();\n  }\n}\n\n/**\n * The {@link VectorStore} surface plus the pg store's extra DDL helpers.\n * `schema()` / `ensureSchema()` are not part of the base contract (the\n * cache store has no backing table), so the factory's return type widens\n * it for callers that want the migration SQL.\n */\nexport interface PgVectorStoreInstance extends VectorStore {\n  /** Reference migration DDL (extension + table + indexes). Never executed. */\n  schema(): string;\n  /** Alias for {@link PgVectorStoreInstance.schema} — reads better in a migration script. */\n  ensureSchema(): string;\n}\n\n/**\n * Create a Postgres + pgvector-backed {@link VectorStore} for the RAG\n * pipeline. Either pass a live `pg.Pool` / `pg.Client` (`{ client }`) —\n * `@warlock.js/ai` never imports `pg` in that case — or a\n * `{ connectionString }` and let the store lazily `import(\"pg\")` to build\n * its own pool. When `pg` is not installed, a curated install string\n * surfaces on first use, never at import.\n *\n * Run {@link PgVectorStoreInstance.ensureSchema} through your migration\n * tool once before use (it enables the `vector` extension, creates the\n * table, and builds the tag + ANN indexes); the store never auto-migrates.\n *\n * Index and query MUST use the same embedding model — the `vector(N)`\n * column width is fixed at table-creation time from `dimensions`.\n *\n * @example\n * import { Pool } from \"pg\";\n * import { ai } from \"@warlock.js/ai\";\n *\n * const pool = new Pool({ connectionString: process.env.DATABASE_URL });\n * const store = ai.rag.pgVectorStore({ client: pool, dimensions: 1536 });\n *\n * // Once, via your migration tooling:\n * // await pool.query(store.ensureSchema());\n *\n * const kb = ai.rag({\n *   name: \"docs\",\n *   embedder: openai.embedder({ name: \"text-embedding-3-small\" }),\n *   store,\n * });\n *\n * @example\n * // Let the store build its own pool from a connection string:\n * const store = ai.rag.pgVectorStore({\n *   connectionString: process.env.DATABASE_URL,\n *   index: \"ivfflat\",\n *   ivfflatLists: 200,\n * });\n */\nexport function pgVectorStore(options: PgVectorStoreOptions): PgVectorStoreInstance {\n  return new PgVectorStore(options);\n}\n"],"mappings":"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"}
+{"version":3,"file":"pg-vector-store.mjs","names":[],"sources":["../../../../../../../../ai/src/rag/store/pg-vector-store.ts"],"sourcesContent":["import type { VectorStore } from \"./vector-store.contract\";\n\n/**\n * Minimal `pg`-compatible client surface the Postgres {@link VectorStore}\n * depends on. Both `pg.Pool` and `pg.Client` satisfy it — the store only\n * ever calls `query`.\n *\n * `@warlock.js/ai` takes **no** hard dependency on `pg`; the dev installs\n * it (an optional peer) and passes the client in. Structurally identical\n * to the snapshot / human-interrupt stores' `PgClientLike`, so a single\n * pool can back the orchestrator checkpoint/snapshot tables, the\n * interrupt table, and this vectors table alike.\n */\nexport interface PgClientLike {\n  query(text: string, params?: unknown[]): Promise<{ rows: unknown[] }>;\n}\n\n/**\n * Options for the Postgres {@link VectorStore}.\n *\n * Two mutually-supportive ways to supply the connection (mirroring\n * `ai.human.interrupt.pg`):\n * - **`client`** — pass an already-built `pg.Pool` / `pg.Client` (anything\n *   satisfying {@link PgClientLike}). The store only ever calls `query`\n *   and never opens or closes it; one pool can back several stores.\n * - **`connectionString`** — let the store lazily `import(\"pg\")` and build\n *   its own `Pool`. `@warlock.js/ai` takes **no** hard dependency on\n *   `pg` (an optional peer); when it is absent the store throws a curated\n *   install string at first use, never a raw module-resolution stack trace\n *   at import.\n *\n * Exactly one of the two must be present.\n */\nexport interface PgVectorStoreOptions {\n  /** An already-built `pg.Pool` / `pg.Client` — anything matching {@link PgClientLike}. */\n  client?: PgClientLike;\n\n  /** Connection string the store passes to a lazily-imported `pg.Pool`. */\n  connectionString?: string;\n\n  /**\n   * Backing table name. Defaults to `warlock_ai_rag_vectors`. Must be a\n   * safe SQL identifier — it is interpolated into DDL/DML.\n   */\n  table?: string;\n\n  /**\n   * Embedding dimensionality used in the `CREATE TABLE` DDL emitted by\n   * {@link VectorStore.schema | ensureSchema}. Defaults to `1536`\n   * (OpenAI `text-embedding-3-small`). The column is declared\n   * `vector(N)`; queries and upserts never re-state it, so an existing\n   * table provisioned at a different size is unaffected — only the DDL\n   * helper reads this.\n   */\n  dimensions?: number;\n\n  /**\n   * Approximate-nearest-neighbour index strategy baked into the DDL\n   * emitted by {@link VectorStore.schema | ensureSchema}. Defaults to\n   * `\"hnsw\"` (better recall/latency on modern pgvector). Use `\"ivfflat\"`\n   * for the classic list-partitioned index, or `\"none\"` to emit no ANN\n   * index (exact scan — correct, but linear in row count).\n   */\n  index?: \"hnsw\" | \"ivfflat\" | \"none\";\n\n  /**\n   * `lists` parameter for an `ivfflat` index (ignored for `hnsw` / `none`).\n   * Defaults to `100`. Tune toward `rows / 1000` for large tables.\n   */\n  ivfflatLists?: number;\n}\n\n/**\n * Default backing table — provisions the store with no extra config when\n * the dev runs {@link VectorStore.schema | ensureSchema} through their\n * migration tool.\n */\nconst DEFAULT_TABLE = \"warlock_ai_rag_vectors\";\n\n/** Default embedding width baked into the DDL (OpenAI `text-embedding-3-small`). */\nconst DEFAULT_DIMENSIONS = 1536;\n\n/** Default `ivfflat` list count when that index strategy is chosen. */\nconst DEFAULT_IVFFLAT_LISTS = 100;\n\n/**\n * Allowed characters in a Postgres identifier (table name). The table name\n * is interpolated into DDL/DML, so anything outside this conservative\n * ASCII subset is rejected — interpolating an arbitrary string would be a\n * SQL-injection footgun (mirrors the snapshot / human-interrupt pg stores\n * and `@warlock.js/cache`'s `PgCacheDriver`).\n */\nconst SAFE_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;\n\n/**\n * Module specifier for the optional `pg` driver. Held in a `string`\n * variable so the dynamic `import()` is not statically resolved at compile\n * time — `pg` is an optional peer that need not be installed for this\n * package to type-check or for a cache-only consumer to run.\n */\nconst PG_MODULE = \"pg\";\n\n/**\n * Curated install string surfaced (at use time) when a `connectionString`\n * is configured but the optional `pg` driver is absent. Never thrown at\n * import — a cache-only consumer must be able to load this module.\n */\nconst PG_INSTALL_INSTRUCTIONS = `\nThe @warlock.js/ai Postgres vector store requires the pg package and a\nPostgres database with the pgvector extension. Install the driver with:\n\n  npm install pg\n\nOr with your preferred package manager:\n\n  pnpm add pg\n  yarn add pg\n`.trim();\n\n/**\n * Minimal structural view of a `pg.Pool` constructor — just enough of the\n * `pg` module surface for the store to build a client when handed a\n * `connectionString`. Declared locally (rather than `typeof import(\"pg\")`)\n * so this module type-checks even when `pg` is not installed.\n */\ninterface PgModuleLike {\n  Pool: new (config: { connectionString: string }) => PgClientLike;\n}\n\n/**\n * Lazily import `pg` and return a `Pool` built from `connectionString`. A\n * bare `catch` rethrows the curated install string — a missing optional\n * peer surfaces as actionable guidance, never a raw resolution error.\n */\nasync function buildPgClient(connectionString: string): Promise<PgClientLike> {\n  let sdk: PgModuleLike;\n\n  try {\n    sdk = (await import(PG_MODULE)) as unknown as PgModuleLike;\n  } catch {\n    throw new Error(PG_INSTALL_INSTRUCTIONS);\n  }\n\n  return new sdk.Pool({ connectionString });\n}\n\n/**\n * Serialize a JS `number[]` to the pgvector text literal: `[1,2,3]`.\n * pgvector accepts a vector either as this bracketed literal or via a\n * typed parameter; passing the literal string + an explicit `::vector`\n * cast keeps the store driver-agnostic (no dependency on a registered\n * `pg` type parser).\n *\n * Non-finite components (`NaN` / `±Infinity`) are rejected — pgvector\n * stores only finite floats, and silently coercing them would corrupt the\n * index. The check is cheap relative to the embed call that produced the\n * vector.\n *\n * @example\n * vectorLiteral([1, 0.5, -2]); // \"[1,0.5,-2]\"\n */\nexport function vectorLiteral(vector: number[]): string {\n  let literal = \"[\";\n\n  for (let index = 0; index < vector.length; index++) {\n    const component = vector[index];\n\n    if (!Number.isFinite(component)) {\n      throw new TypeError(\n        `pgVectorStore: embedding component at index ${index} is not finite (${component}); pgvector stores only finite floats.`,\n      );\n    }\n\n    if (index > 0) {\n      literal += \",\";\n    }\n\n    literal += String(component);\n  }\n\n  return literal + \"]\";\n}\n\n/**\n * Coerce a `value` JSONB column back into the stored payload. node-postgres\n * parses `JSONB` into a JS value already, but some pool wrappers hand back\n * the raw string — be defensive across both (mirrors the snapshot store's\n * `parsePayload`).\n */\nfunction parseValue<T>(value: unknown): T {\n  if (typeof value === \"string\") {\n    return JSON.parse(value) as T;\n  }\n\n  return value as T;\n}\n\n/**\n * Coerce a pgvector cosine **distance** (`<=>`, in `[0, 2]`, 0 = identical)\n * into the cosine **similarity** score the {@link VectorStore} contract\n * declares (`[0, 1]`, 1 = identical). `pg` returns the computed distance\n * column as a string for `double precision`; parse then map `1 - distance`,\n * clamped to `[0, 1]` so a tiny floating-point overshoot never yields a\n * score just outside the contract's range.\n */\nfunction distanceToScore(distance: unknown): number {\n  const value = typeof distance === \"string\" ? Number(distance) : (distance as number);\n  const score = 1 - value;\n\n  if (score < 0) {\n    return 0;\n  }\n\n  if (score > 1) {\n    return 1;\n  }\n\n  return score;\n}\n\n/**\n * Postgres + pgvector-backed {@link VectorStore} — one durable row per\n * indexed chunk, keyed by the RAG pipeline's dotted `key`\n * (`ai.rag.<name>.<sourceId>.<chunkIndex>`), with the chunk payload in a\n * `value` JSONB column and the embedding in a `vector` column.\n *\n * Owns: the three RAG vector operations against a pgvector index —\n * `upsert` (INSERT … ON CONFLICT DO UPDATE), `query` (cosine\n * `ORDER BY embedding <=> $vec` with a `threshold` floor + optional `tags`\n * overlap filter, capped at `topK`), and `removeNamespace` (prefix DELETE).\n * Also emits the reference DDL via {@link PgVectorStore.schema} (alias\n * {@link PgVectorStore.ensureSchema}).\n *\n * Does NOT own: the connection lifecycle (a dev-supplied `client` is never\n * closed; a store-built `Pool` from a `connectionString` is also left open\n * for the process to reuse) or schema migration — the dev runs the DDL\n * through their own tool; the framework never auto-migrates.\n *\n * Front it with the {@link pgVectorStore} factory — callers never `new` it.\n */\nclass PgVectorStore implements VectorStore {\n  /** Validated backing table name, safe to interpolate into SQL. */\n  private readonly table: string;\n\n  /** Embedding width baked into the DDL. */\n  private readonly dimensions: number;\n\n  /** ANN index strategy baked into the DDL. */\n  private readonly index: \"hnsw\" | \"ivfflat\" | \"none\";\n\n  /** `lists` parameter for an `ivfflat` index. */\n  private readonly ivfflatLists: number;\n\n  /**\n   * A ready client, or a promise resolving to one the store builds lazily\n   * from a `connectionString`. Resolved once and memoized so the optional\n   * `pg` import happens at most once.\n   */\n  private readonly clientPromise: Promise<PgClientLike>;\n\n  public constructor(options: PgVectorStoreOptions) {\n    const table = options.table ?? DEFAULT_TABLE;\n\n    if (!SAFE_IDENTIFIER.test(table)) {\n      throw new TypeError(\n        `pgVectorStore: invalid table name '${table}'. Allowed: [A-Za-z_][A-Za-z0-9_]*.`,\n      );\n    }\n\n    this.table = table;\n    this.dimensions = options.dimensions ?? DEFAULT_DIMENSIONS;\n    this.index = options.index ?? \"hnsw\";\n    this.ivfflatLists = options.ivfflatLists ?? DEFAULT_IVFFLAT_LISTS;\n\n    if (options.client) {\n      if (typeof options.client.query !== \"function\") {\n        throw new TypeError(\n          \"pgVectorStore requires a 'client' option implementing { query(text, params) } — pass a pg.Pool or pg.Client.\",\n        );\n      }\n\n      this.clientPromise = Promise.resolve(options.client);\n\n      return;\n    }\n\n    if (options.connectionString) {\n      // Defer the optional `pg` import to first use — a curated install\n      // string surfaces from `buildPgClient`, not at construction.\n      this.clientPromise = buildPgClient(options.connectionString);\n\n      return;\n    }\n\n    throw new TypeError(\n      \"pgVectorStore requires either a 'client' or a 'connectionString' option.\",\n    );\n  }\n\n  /**\n   * Resolve the backing client, surfacing the lazy `pg` import's curated\n   * install string on the first call that needs it.\n   */\n  private client(): Promise<PgClientLike> {\n    return this.clientPromise;\n  }\n\n  /**\n   * Index `value` under `key` with its embedding `vector`. Upserts on the\n   * `key` primary key — re-indexing the same chunk overwrites its payload,\n   * embedding, and tags rather than appending a duplicate row. Optional\n   * `tags` ride a `text[]` column so {@link query} can restrict the\n   * candidate set with an array-overlap filter.\n   *\n   * The embedding is sent as a pgvector text literal (`$3`) cast to\n   * `::vector`, so the store needs no registered `pg` type parser. `tags`\n   * defaults to an empty array (never `NULL`) to keep the overlap filter's\n   * `&&` semantics simple.\n   */\n  public async upsert(\n    key: string,\n    value: unknown,\n    vector: number[],\n    tags?: string[],\n  ): Promise<void> {\n    const client = await this.client();\n\n    await client.query(\n      `INSERT INTO ${this.table} (key, value, embedding, tags)\n       VALUES ($1, $2::jsonb, $3::vector, $4::text[])\n       ON CONFLICT (key) DO UPDATE\n         SET value = EXCLUDED.value,\n             embedding = EXCLUDED.embedding,\n             tags = EXCLUDED.tags`,\n      [key, JSON.stringify(value), vectorLiteral(vector), tags ?? []],\n    );\n  }\n\n  /**\n   * Return the cosine-nearest rows to `vector`, mapped to the contract's\n   * `{ key, value, score }` shape. The SQL:\n   *\n   * - computes `embedding <=> $1::vector` (cosine **distance**) once, aliased\n   *   `distance`, and `ORDER BY` it ascending (nearest first);\n   * - applies the `threshold` floor as `distance <= 1 - threshold`\n   *   (similarity `>=` threshold), so the default `0.5` floor maps to a\n   *   `<= 0.5` distance bound — the filter runs in SQL, not in JS, so a\n   *   below-floor row never crosses the wire;\n   * - when `tags` are given, restricts to rows whose `tags` array overlaps\n   *   the requested set via `tags && $tags::text[]` (one-of semantics,\n   *   matching the cache store);\n   * - caps the result at `topK` with `LIMIT`.\n   *\n   * The returned `score` is `1 - distance`, clamped to `[0, 1]`, so callers\n   * see the same cosine-similarity scale the cache store emits.\n   */\n  public async query<T>(\n    vector: number[],\n    options: { topK: number; threshold?: number; tags?: string[] },\n  ): Promise<{ key: string; value: T; score: number }[]> {\n    const client = await this.client();\n    const queryVector = vectorLiteral(vector);\n\n    // $1 = query vector, $2 = topK. Optional threshold + tags are appended\n    // as $3 / $4 only when present, so the prepared statement carries no\n    // unused placeholders.\n    const params: unknown[] = [queryVector, options.topK];\n    const conditions: string[] = [];\n\n    if (options.threshold !== undefined) {\n      params.push(1 - options.threshold);\n      conditions.push(`(embedding <=> $1::vector) <= $${params.length}`);\n    }\n\n    if (options.tags !== undefined && options.tags.length > 0) {\n      params.push(options.tags);\n      conditions.push(`tags && $${params.length}::text[]`);\n    }\n\n    const where = conditions.length > 0 ? `WHERE ${conditions.join(\" AND \")}` : \"\";\n\n    const { rows } = await client.query(\n      `SELECT key, value, (embedding <=> $1::vector) AS distance\n       FROM ${this.table}\n       ${where}\n       ORDER BY embedding <=> $1::vector\n       LIMIT $2`,\n      params,\n    );\n\n    return (rows as Record<string, unknown>[]).map((row) => ({\n      key: row.key as string,\n      value: parseValue<T>(row.value),\n      score: distanceToScore(row.distance),\n    }));\n  }\n\n  /**\n   * Drop every entry written under `namespace`. The RAG pipeline keys\n   * chunks as `<namespace>.<sourceId>.<chunkIndex>`, so a row belongs to\n   * the namespace when its `key` equals it OR begins with `<namespace>.`\n   * — deleting `ai.rag.docs` must not also catch `ai.rag.docs2`. The `_`\n   * and `%` LIKE wildcards in the namespace are escaped so a namespace\n   * that happens to contain them is matched literally.\n   */\n  public async removeNamespace(namespace: string): Promise<void> {\n    const client = await this.client();\n\n    const escaped = namespace\n      .replace(/\\\\/g, \"\\\\\\\\\")\n      .replace(/_/g, \"\\\\_\")\n      .replace(/%/g, \"\\\\%\");\n\n    await client.query(\n      `DELETE FROM ${this.table}\n       WHERE key = $1 OR key LIKE $2 ESCAPE '\\\\'`,\n      [namespace, `${escaped}.%`],\n    );\n  }\n\n  /**\n   * Return the reference migration DDL for this store's backing table,\n   * interpolating the configured table name, embedding width, and ANN\n   * index strategy. The dev runs it once through their migration tool —\n   * the framework never auto-migrates.\n   *\n   * The emitted statements:\n   * 1. `CREATE EXTENSION IF NOT EXISTS vector;` — enables pgvector (needs\n   *    a superuser or a role with `CREATE` on the database the first time).\n   * 2. `CREATE TABLE IF NOT EXISTS <table> (key TEXT PRIMARY KEY, value\n   *    JSONB NOT NULL, embedding vector(<dimensions>) NOT NULL, tags\n   *    text[] NOT NULL DEFAULT '{}');`\n   * 3. A GIN index on `tags` so the array-overlap filter stays sargable.\n   * 4. The chosen ANN index over `embedding` using `vector_cosine_ops`:\n   *    - `\"hnsw\"` → `USING hnsw (embedding vector_cosine_ops)`;\n   *    - `\"ivfflat\"` → `USING ivfflat (embedding vector_cosine_ops)\n   *      WITH (lists = <ivfflatLists>)`;\n   *    - `\"none\"` → emitted as a comment (exact scan, no ANN index).\n   *\n   * @example\n   * const store = pgVectorStore({ client: pool, dimensions: 1536 });\n   * await pool.query(store.ensureSchema());\n   */\n  public schema(): string {\n    const lines = [\n      `CREATE EXTENSION IF NOT EXISTS vector;`,\n      `CREATE TABLE IF NOT EXISTS ${this.table} (`,\n      `  key        TEXT PRIMARY KEY,`,\n      `  value      JSONB NOT NULL,`,\n      `  embedding  vector(${this.dimensions}) NOT NULL,`,\n      `  tags       TEXT[] NOT NULL DEFAULT '{}'`,\n      `);`,\n      `CREATE INDEX IF NOT EXISTS idx_${this.table}_tags`,\n      `  ON ${this.table} USING gin (tags);`,\n    ];\n\n    if (this.index === \"hnsw\") {\n      lines.push(\n        `CREATE INDEX IF NOT EXISTS idx_${this.table}_embedding`,\n        `  ON ${this.table} USING hnsw (embedding vector_cosine_ops);`,\n      );\n    } else if (this.index === \"ivfflat\") {\n      lines.push(\n        `CREATE INDEX IF NOT EXISTS idx_${this.table}_embedding`,\n        `  ON ${this.table} USING ivfflat (embedding vector_cosine_ops)`,\n        `  WITH (lists = ${this.ivfflatLists});`,\n      );\n    } else {\n      lines.push(\n        `-- No ANN index requested (index: \"none\"): cosine queries fall back`,\n        `-- to an exact sequential scan, which is correct but linear in rows.`,\n      );\n    }\n\n    return lines.join(\"\\n\");\n  }\n\n  /**\n   * Alias for {@link PgVectorStore.schema} — reads more naturally in a\n   * migration script (`await pool.query(store.ensureSchema())`). Returns\n   * the identical DDL string; it does NOT execute anything against the\n   * database (the store never auto-migrates).\n   */\n  public ensureSchema(): string {\n    return this.schema();\n  }\n}\n\n/**\n * The {@link VectorStore} surface plus the pg store's extra DDL helpers.\n * `schema()` / `ensureSchema()` are not part of the base contract (the\n * cache store has no backing table), so the factory's return type widens\n * it for callers that want the migration SQL.\n */\nexport interface PgVectorStoreInstance extends VectorStore {\n  /** Reference migration DDL (extension + table + indexes). Never executed. */\n  schema(): string;\n  /** Alias for {@link PgVectorStoreInstance.schema} — reads better in a migration script. */\n  ensureSchema(): string;\n}\n\n/**\n * Create a Postgres + pgvector-backed {@link VectorStore} for the RAG\n * pipeline. Either pass a live `pg.Pool` / `pg.Client` (`{ client }`) —\n * `@warlock.js/ai` never imports `pg` in that case — or a\n * `{ connectionString }` and let the store lazily `import(\"pg\")` to build\n * its own pool. When `pg` is not installed, a curated install string\n * surfaces on first use, never at import.\n *\n * Run {@link PgVectorStoreInstance.ensureSchema} through your migration\n * tool once before use (it enables the `vector` extension, creates the\n * table, and builds the tag + ANN indexes); the store never auto-migrates.\n *\n * Index and query MUST use the same embedding model — the `vector(N)`\n * column width is fixed at table-creation time from `dimensions`.\n *\n * @example\n * import { Pool } from \"pg\";\n * import { ai } from \"@warlock.js/ai\";\n *\n * const pool = new Pool({ connectionString: process.env.DATABASE_URL });\n * const store = ai.rag.pgVectorStore({ client: pool, dimensions: 1536 });\n *\n * // Once, via your migration tooling:\n * // await pool.query(store.ensureSchema());\n *\n * const kb = ai.rag({\n *   name: \"docs\",\n *   embedder: openai.embedder({ name: \"text-embedding-3-small\" }),\n *   store,\n * });\n *\n * @example\n * // Let the store build its own pool from a connection string:\n * const store = ai.rag.pgVectorStore({\n *   connectionString: process.env.DATABASE_URL,\n *   index: \"ivfflat\",\n *   ivfflatLists: 200,\n * });\n */\nexport function pgVectorStore(options: PgVectorStoreOptions): PgVectorStoreInstance {\n  return new PgVectorStore(options);\n}\n"],"mappings":"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"}

package/esm/rag/transforms/multi-query.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"multi-query.mjs","names":[],"sources":["../../../../../../../../ai/src/rag/transforms/multi-query.ts"],"sourcesContent":["import type { ModelContract } from \"../../contracts/model.contract\";\n\n/** Options for {@link multiQuery}. */\nexport type MultiQueryOptions = {\n  /** How many alternative phrasings to request. Default 3. */\n  n?: number;\n  /** Include the original query in the returned list. Default true. */\n  includeOriginal?: boolean;\n};\n\n/**\n * Multi-query expansion (A4) — ask a model for several alternative\n * phrasings of `query`, so retrieval covers vocabulary the original\n * wording missed (synonyms, specificity, rephrasings). Pair the variants\n * with {@link hybridRank} / a vector search and fuse the per-variant hits.\n *\n * Deterministic, dependency-light parsing: the model is asked for one\n * query per line; bullets / numbering are stripped, blanks dropped, and\n * the set is de-duplicated. Returns the original (unless opted out) plus\n * up to `n` variants.\n *\n * @example\n * const queries = await multiQuery(model, \"how do I cancel?\", { n: 3 });\n * // → [\"how do I cancel?\", \"cancel my subscription\", \"end my plan\", ...]\n */\nexport async function multiQuery(\n  model: ModelContract,\n  query: string,\n  options: MultiQueryOptions = {},\n): Promise<string[]> {\n  const n = options.n ?? 3;\n  const includeOriginal = options.includeOriginal ?? true;\n\n  const prompt =\n    `Rewrite the following search query into ${n} alternative phrasings that would ` +\n    `retrieve relevant documents. Output ONE query per line, no numbering or commentary.\\n\\n` +\n    `Query: ${query}`;\n\n  const response = await model.complete([{ role: \"user\", content: prompt }]);\n\n  const variants = response.content\n    .split(\"\\n\")\n    .map(line => line.replace(/^\\s*(?:[-*•]|\\d+[.)])\\s*/, \"\").trim())\n    .filter(Boolean);\n\n  const seen = new Set<string>();\n  const out: string[] = [];\n\n  const add = (q: string) => {\n    const key = q.toLowerCase();\n    if (!seen.has(key)) {\n      seen.add(key);\n      out.push(q);\n    }\n  };\n\n  if (includeOriginal) add(query);\n  for (const variant of variants.slice(0, n)) add(variant);\n\n  return out;\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAyBA,eAAsB,WACpB,OACA,OACA,UAA6B,CAAC,GACX;CACnB,MAAM,IAAI,QAAQ,KAAK;CACvB,MAAM,kBAAkB,QAAQ,mBAAmB;CAEnD,MAAM,SACJ,2CAA2C,EAAE,kIAEnC;CAIZ,MAAM,YAAW,MAFM,MAAM,SAAS,CAAC;EAAE,MAAM;EAAQ,SAAS;CAAO,CAAC,CAAC,EAEhD,CAAC,QACvB,MAAM,IAAI,CAAC,CACX,KAAI,SAAQ,KAAK,QAAQ,4BAA4B,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAChE,OAAO,OAAO;CAEjB,MAAM,uBAAO,IAAI,IAAY;CAC7B,MAAM,MAAgB,CAAC;CAEvB,MAAM,OAAO,MAAc;EACzB,MAAM,MAAM,EAAE,YAAY;EAC1B,IAAI,CAAC,KAAK,IAAI,GAAG,GAAG;GAClB,KAAK,IAAI,GAAG;GACZ,IAAI,KAAK,CAAC;EACZ;CACF;CAEA,IAAI,iBAAiB,IAAI,KAAK;CAC9B,KAAK,MAAM,WAAW,SAAS,MAAM,GAAG,CAAC,GAAG,IAAI,OAAO;CAEvD,OAAO;AACT"}
+{"version":3,"file":"multi-query.mjs","names":[],"sources":["../../../../../../../../ai/src/rag/transforms/multi-query.ts"],"sourcesContent":["import type { ModelContract } from \"../../contracts/model.contract\";\n\n/** Options for {@link multiQuery}. */\nexport type MultiQueryOptions = {\n  /** How many alternative phrasings to request. Default 3. */\n  n?: number;\n  /** Include the original query in the returned list. Default true. */\n  includeOriginal?: boolean;\n};\n\n/**\n * Multi-query expansion (A4) — ask a model for several alternative\n * phrasings of `query`, so retrieval covers vocabulary the original\n * wording missed (synonyms, specificity, rephrasings). Pair the variants\n * with {@link hybridRank} / a vector search and fuse the per-variant hits.\n *\n * Deterministic, dependency-light parsing: the model is asked for one\n * query per line; bullets / numbering are stripped, blanks dropped, and\n * the set is de-duplicated. Returns the original (unless opted out) plus\n * up to `n` variants.\n *\n * @example\n * const queries = await multiQuery(model, \"how do I cancel?\", { n: 3 });\n * // → [\"how do I cancel?\", \"cancel my subscription\", \"end my plan\", ...]\n */\nexport async function multiQuery(\n  model: ModelContract,\n  query: string,\n  options: MultiQueryOptions = {},\n): Promise<string[]> {\n  const n = options.n ?? 3;\n  const includeOriginal = options.includeOriginal ?? true;\n\n  const prompt =\n    `Rewrite the following search query into ${n} alternative phrasings that would ` +\n    `retrieve relevant documents. Output ONE query per line, no numbering or commentary.\\n\\n` +\n    `Query: ${query}`;\n\n  const response = await model.complete([{ role: \"user\", content: prompt }]);\n\n  const variants = response.content\n    .split(\"\\n\")\n    .map(line => line.replace(/^\\s*(?:[-*•]|\\d+[.)])\\s*/, \"\").trim())\n    .filter(Boolean);\n\n  const seen = new Set<string>();\n  const out: string[] = [];\n\n  const add = (q: string) => {\n    const key = q.toLowerCase();\n    if (!seen.has(key)) {\n      seen.add(key);\n      out.push(q);\n    }\n  };\n\n  if (includeOriginal) add(query);\n  for (const variant of variants.slice(0, n)) add(variant);\n\n  return out;\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAyBA,eAAsB,WACpB,OACA,OACA,UAA6B,CAAC,GACX;CACnB,MAAM,IAAI,QAAQ,KAAK;CACvB,MAAM,kBAAkB,QAAQ,mBAAmB;CAEnD,MAAM,SACJ,2CAA2C,EAAE,kIAEnC;CAIZ,MAAM,YAAW,MAFM,MAAM,SAAS,CAAC;EAAE,MAAM;EAAQ,SAAS;CAAO,CAAC,CAAC,GAE/C,QACvB,MAAM,IAAI,EACV,KAAI,SAAQ,KAAK,QAAQ,4BAA4B,EAAE,EAAE,KAAK,CAAC,EAC/D,OAAO,OAAO;CAEjB,MAAM,uBAAO,IAAI,IAAY;CAC7B,MAAM,MAAgB,CAAC;CAEvB,MAAM,OAAO,MAAc;EACzB,MAAM,MAAM,EAAE,YAAY;EAC1B,IAAI,CAAC,KAAK,IAAI,GAAG,GAAG;GAClB,KAAK,IAAI,GAAG;GACZ,IAAI,KAAK,CAAC;EACZ;CACF;CAEA,IAAI,iBAAiB,IAAI,KAAK;CAC9B,KAAK,MAAM,WAAW,SAAS,MAAM,GAAG,CAAC,GAAG,IAAI,OAAO;CAEvD,OAAO;AACT"}

package/esm/security/outbound-policy.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"outbound-policy.mjs","names":[],"sources":["../../../../../../../ai/src/security/outbound-policy.ts"],"sourcesContent":["import { lookup } from \"node:dns/promises\";\nimport { isIP } from \"node:net\";\nimport { OutboundPolicyError } from \"../errors\";\nimport { isPrivateOrReservedIp } from \"./private-ip\";\nimport type {\n  OutboundPolicy,\n  ResolvedOutboundPolicy,\n} from \"./outbound-policy.type\";\n\n/** 5 MiB — default cap on an outbound response body. */\nconst DEFAULT_MAX_BYTES = 5 * 1024 * 1024;\n/** 10s — default per-request timeout. */\nconst DEFAULT_TIMEOUT_MS = 10_000;\n/** Default cap on the number of policy-validated redirect hops. */\nconst DEFAULT_MAX_REDIRECTS = 5;\n\n/** 3xx statuses whose `Location` a follow re-issues. */\nconst REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);\n\n/** Credential headers that must not survive a cross-origin redirect. */\nconst CROSS_ORIGIN_STRIP_HEADERS = [\n  \"authorization\",\n  \"cookie\",\n  \"proxy-authorization\",\n];\n\n/**\n * Fill an {@link OutboundPolicy} with strict defaults: https-only,\n * private-IP deny on, 10s timeout, 5 MiB cap, global `fetch`. Idempotent\n * — resolving an already-resolved policy yields the same shape.\n */\nexport function resolveOutboundPolicy(\n  policy: OutboundPolicy = {},\n): ResolvedOutboundPolicy {\n  return {\n    allowedSchemes: policy.allowedSchemes ?? [\"https\"],\n    hostAllowlist: policy.hostAllowlist,\n    denyPrivateIPsAfterDNS: policy.denyPrivateIPsAfterDNS ?? true,\n    maxBytes: policy.maxBytes ?? DEFAULT_MAX_BYTES,\n    timeoutMs: policy.timeoutMs ?? DEFAULT_TIMEOUT_MS,\n    maxRedirects: policy.maxRedirects ?? DEFAULT_MAX_REDIRECTS,\n    signal: policy.signal,\n    fetch: policy.fetch ?? globalThis.fetch,\n  };\n}\n\n/** Strip the `[ ]` IPv6 brackets `URL.hostname` keeps. */\nfunction stripBrackets(host: string): string {\n  return host.startsWith(\"[\") && host.endsWith(\"]\") ? host.slice(1, -1) : host;\n}\n\n/** Whether `host` equals or is a subdomain of any allowlist entry. */\nfunction hostAllowed(host: string, allowlist: string[]): boolean {\n  const lower = host.toLowerCase();\n  return allowlist.some(entry => {\n    const e = entry.toLowerCase();\n    return lower === e || lower.endsWith(`.${e}`);\n  });\n}\n\n/**\n * Validate a URL against the policy BEFORE any network call: scheme\n * allowlist, host allowlist, and (when enabled) a DNS resolution that\n * rejects private / loopback / link-local / metadata addresses — the SSRF\n * guard. Returns the parsed `URL` on success; throws\n * {@link OutboundPolicyError} otherwise.\n */\nexport async function assertUrlAllowed(\n  rawUrl: string,\n  policy: ResolvedOutboundPolicy,\n): Promise<URL> {\n  let url: URL;\n  try {\n    url = new URL(rawUrl);\n  } catch {\n    throw new OutboundPolicyError(`outbound request blocked — invalid URL: ${rawUrl}`, {\n      context: { url: rawUrl },\n    });\n  }\n\n  const scheme = url.protocol.replace(/:$/, \"\").toLowerCase();\n  if (!policy.allowedSchemes.some(s => s.toLowerCase() === scheme)) {\n    throw new OutboundPolicyError(\n      `outbound request blocked — scheme \"${scheme}\" is not allowed (allowed: ${policy.allowedSchemes.join(\", \")})`,\n      { context: { url: rawUrl, scheme } },\n    );\n  }\n\n  const host = stripBrackets(url.hostname);\n\n  if (policy.hostAllowlist && !hostAllowed(host, policy.hostAllowlist)) {\n    throw new OutboundPolicyError(\n      `outbound request blocked — host \"${host}\" is not in the allowlist`,\n      { context: { url: rawUrl, host } },\n    );\n  }\n\n  if (policy.denyPrivateIPsAfterDNS) {\n    await assertHostNotPrivate(host, rawUrl);\n  }\n\n  return url;\n}\n\n/**\n * Reject when `host` is — or resolves to — a private / reserved address.\n * IP literals are checked directly; hostnames are resolved via DNS and\n * every returned address is checked (a public name pointing inward is\n * caught). A resolution failure fails closed.\n */\nasync function assertHostNotPrivate(host: string, rawUrl: string): Promise<void> {\n  if (isIP(host) !== 0) {\n    if (isPrivateOrReservedIp(host)) {\n      throw new OutboundPolicyError(\n        `outbound request blocked — \"${host}\" is a private/reserved address`,\n        { context: { url: rawUrl, address: host } },\n      );\n    }\n    return;\n  }\n\n  let addresses: Array<{ address: string }>;\n  try {\n    addresses = await lookup(host, { all: true });\n  } catch (cause) {\n    throw new OutboundPolicyError(\n      `outbound request blocked — could not resolve host \"${host}\" to verify it is public`,\n      { cause, context: { url: rawUrl, host } },\n    );\n  }\n\n  for (const { address } of addresses) {\n    if (isPrivateOrReservedIp(address)) {\n      throw new OutboundPolicyError(\n        `outbound request blocked — host \"${host}\" resolves to a private/reserved address (${address})`,\n        { context: { url: rawUrl, host, address } },\n      );\n    }\n  }\n}\n\n/** Merge the internal timeout signal with an optional caller signal. */\nfunction mergeSignals(\n  timeout: AbortSignal,\n  external?: AbortSignal,\n): AbortSignal {\n  if (!external) return timeout;\n\n  const controller = new AbortController();\n  const abort = (from: AbortSignal) => controller.abort(from.reason);\n\n  if (timeout.aborted) abort(timeout);\n  else timeout.addEventListener(\"abort\", () => abort(timeout), { once: true });\n\n  if (external.aborted) abort(external);\n  else external.addEventListener(\"abort\", () => abort(external), { once: true });\n\n  return controller.signal;\n}\n\n/** Flatten a headers init into a mutable lower-cased-key record. */\nfunction headersToRecord(\n  headersInit?: RequestInit[\"headers\"],\n): Record<string, string> {\n  const record: Record<string, string> = {};\n  new Headers(headersInit).forEach((value, key) => {\n    record[key] = value;\n  });\n  return record;\n}\n\n/**\n * Policy-guarded `fetch`: validates the URL ({@link assertUrlAllowed}),\n * then performs the request with the policy's timeout and (optional)\n * caller signal merged. Returns the raw `Response` — read its body via\n * {@link readTextCapped} to enforce `maxBytes`. Throws\n * {@link OutboundPolicyError} on a policy violation or timeout.\n *\n * Redirects are NEVER delegated to the platform: every hop is issued\n * with `redirect: \"manual\"` and its `Location` is re-run through\n * {@link assertUrlAllowed} before being followed (capped at\n * `maxRedirects`), so a 3xx from an allowed host cannot smuggle the\n * request to a private / metadata / off-allowlist target. Credential\n * headers are stripped when a hop crosses an origin boundary. Pass\n * `init.redirect: \"manual\"` to receive the raw 3xx, or `\"error\"` to\n * reject on any redirect.\n */\nexport async function guardedFetch(\n  rawUrl: string,\n  policyInput: OutboundPolicy,\n  init?: RequestInit,\n): Promise<Response> {\n  const policy = resolveOutboundPolicy(policyInput);\n  let url = await assertUrlAllowed(rawUrl, policy);\n\n  const timeoutController = new AbortController();\n  const timer = setTimeout(() => {\n    timeoutController.abort(\n      new OutboundPolicyError(\n        `outbound request timed out after ${policy.timeoutMs}ms`,\n        { context: { url: rawUrl, timeoutMs: policy.timeoutMs } },\n      ),\n    );\n  }, policy.timeoutMs);\n\n  const signal = mergeSignals(timeoutController.signal, policy.signal);\n  const redirectMode = init?.redirect ?? \"follow\";\n  const headers = headersToRecord(init?.headers);\n  let method = init?.method ?? \"GET\";\n  let body = init?.body ?? undefined;\n\n  try {\n    for (let hop = 0; ; hop++) {\n      const response = await policy.fetch(url, {\n        ...init,\n        method,\n        headers: { ...headers },\n        body,\n        redirect: \"manual\",\n        signal,\n      });\n\n      const location = response.headers.get(\"location\");\n      if (!REDIRECT_STATUSES.has(response.status) || location === null) {\n        return response;\n      }\n\n      if (redirectMode === \"manual\") {\n        return response;\n      }\n\n      if (redirectMode === \"error\") {\n        throw new OutboundPolicyError(\n          `outbound request blocked — redirect received with redirect: \"error\" (${response.status} → ${location})`,\n          { context: { url: url.toString(), location, status: response.status } },\n        );\n      }\n\n      if (hop >= policy.maxRedirects) {\n        throw new OutboundPolicyError(\n          `outbound request blocked — more than ${policy.maxRedirects} redirects`,\n          { context: { url: rawUrl, maxRedirects: policy.maxRedirects } },\n        );\n      }\n\n      let target: URL;\n      try {\n        target = new URL(location, url);\n      } catch {\n        throw new OutboundPolicyError(\n          `outbound request blocked — invalid redirect Location: ${location}`,\n          { context: { url: url.toString(), location } },\n        );\n      }\n\n      // The redirect target gets the SAME scheme / allowlist / private-IP\n      // validation as the original URL.\n      const next = await assertUrlAllowed(target.toString(), policy);\n\n      // Discard the interim body so the connection can be reused.\n      if (response.body) {\n        await response.body.cancel().catch(() => undefined);\n      }\n\n      if (next.origin !== url.origin) {\n        for (const name of CROSS_ORIGIN_STRIP_HEADERS) {\n          delete headers[name];\n        }\n      }\n\n      // 303 — and the legacy 301/302-on-a-non-GET convention — re-issue\n      // as a bodyless GET, matching platform follow semantics.\n      if (\n        response.status === 303 ||\n        ((response.status === 301 || response.status === 302) &&\n          method !== \"GET\" &&\n          method !== \"HEAD\")\n      ) {\n        method = \"GET\";\n        body = undefined;\n      }\n\n      url = next;\n    }\n  } finally {\n    clearTimeout(timer);\n  }\n}\n\n/**\n * Read a response body as UTF-8 text with a hard byte cap. A declared\n * `content-length` over the cap fails fast; otherwise the stream is read\n * chunk-by-chunk and aborted the moment the running total exceeds\n * `maxBytes`. Throws {@link OutboundPolicyError} on overflow.\n */\nexport async function readTextCapped(\n  response: Response,\n  maxBytes: number,\n): Promise<string> {\n  const declared = Number(response.headers.get(\"content-length\"));\n  if (Number.isFinite(declared) && declared > maxBytes) {\n    throw new OutboundPolicyError(\n      `outbound response body too large — declared ${declared} bytes exceeds the ${maxBytes}-byte cap`,\n      { context: { declared, maxBytes } },\n    );\n  }\n\n  if (!response.body) {\n    const text = await response.text();\n    if (Buffer.byteLength(text) > maxBytes) {\n      throw new OutboundPolicyError(\n        `outbound response body exceeded the ${maxBytes}-byte cap`,\n        { context: { maxBytes } },\n      );\n    }\n    return text;\n  }\n\n  const reader = response.body.getReader();\n  const chunks: Uint8Array[] = [];\n  let total = 0;\n\n  for (;;) {\n    const { done, value } = await reader.read();\n    if (done) break;\n    if (!value) continue;\n\n    total += value.byteLength;\n    if (total > maxBytes) {\n      await reader.cancel();\n      throw new OutboundPolicyError(\n        `outbound response body exceeded the ${maxBytes}-byte cap`,\n        { context: { maxBytes } },\n      );\n    }\n    chunks.push(value);\n  }\n\n  return Buffer.concat(chunks).toString(\"utf8\");\n}\n\n/**\n * Convenience: {@link guardedFetch} + {@link readTextCapped}. Returns the\n * response status alongside the (capped) body text so callers can shape\n * their own not-OK error. The body is only read when the response is OK.\n */\nexport async function fetchTextWithPolicy(\n  rawUrl: string,\n  policyInput: OutboundPolicy,\n  init?: RequestInit,\n): Promise<{ ok: boolean; status: number; statusText: string; text: string }> {\n  const policy = resolveOutboundPolicy(policyInput);\n  const response = await guardedFetch(rawUrl, policy, init);\n\n  return {\n    ok: response.ok,\n    status: response.status,\n    statusText: response.statusText,\n    text: response.ok ? await readTextCapped(response, policy.maxBytes) : \"\",\n  };\n}\n"],"mappings":"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"}
+{"version":3,"file":"outbound-policy.mjs","names":[],"sources":["../../../../../../../ai/src/security/outbound-policy.ts"],"sourcesContent":["import { lookup } from \"node:dns/promises\";\nimport { isIP } from \"node:net\";\nimport { OutboundPolicyError } from \"../errors\";\nimport { isPrivateOrReservedIp } from \"./private-ip\";\nimport type {\n  OutboundPolicy,\n  ResolvedOutboundPolicy,\n} from \"./outbound-policy.type\";\n\n/** 5 MiB — default cap on an outbound response body. */\nconst DEFAULT_MAX_BYTES = 5 * 1024 * 1024;\n/** 10s — default per-request timeout. */\nconst DEFAULT_TIMEOUT_MS = 10_000;\n/** Default cap on the number of policy-validated redirect hops. */\nconst DEFAULT_MAX_REDIRECTS = 5;\n\n/** 3xx statuses whose `Location` a follow re-issues. */\nconst REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);\n\n/** Credential headers that must not survive a cross-origin redirect. */\nconst CROSS_ORIGIN_STRIP_HEADERS = [\n  \"authorization\",\n  \"cookie\",\n  \"proxy-authorization\",\n];\n\n/**\n * Fill an {@link OutboundPolicy} with strict defaults: https-only,\n * private-IP deny on, 10s timeout, 5 MiB cap, global `fetch`. Idempotent\n * — resolving an already-resolved policy yields the same shape.\n */\nexport function resolveOutboundPolicy(\n  policy: OutboundPolicy = {},\n): ResolvedOutboundPolicy {\n  return {\n    allowedSchemes: policy.allowedSchemes ?? [\"https\"],\n    hostAllowlist: policy.hostAllowlist,\n    denyPrivateIPsAfterDNS: policy.denyPrivateIPsAfterDNS ?? true,\n    maxBytes: policy.maxBytes ?? DEFAULT_MAX_BYTES,\n    timeoutMs: policy.timeoutMs ?? DEFAULT_TIMEOUT_MS,\n    maxRedirects: policy.maxRedirects ?? DEFAULT_MAX_REDIRECTS,\n    signal: policy.signal,\n    fetch: policy.fetch ?? globalThis.fetch,\n  };\n}\n\n/** Strip the `[ ]` IPv6 brackets `URL.hostname` keeps. */\nfunction stripBrackets(host: string): string {\n  return host.startsWith(\"[\") && host.endsWith(\"]\") ? host.slice(1, -1) : host;\n}\n\n/** Whether `host` equals or is a subdomain of any allowlist entry. */\nfunction hostAllowed(host: string, allowlist: string[]): boolean {\n  const lower = host.toLowerCase();\n  return allowlist.some(entry => {\n    const e = entry.toLowerCase();\n    return lower === e || lower.endsWith(`.${e}`);\n  });\n}\n\n/**\n * Validate a URL against the policy BEFORE any network call: scheme\n * allowlist, host allowlist, and (when enabled) a DNS resolution that\n * rejects private / loopback / link-local / metadata addresses — the SSRF\n * guard. Returns the parsed `URL` on success; throws\n * {@link OutboundPolicyError} otherwise.\n */\nexport async function assertUrlAllowed(\n  rawUrl: string,\n  policy: ResolvedOutboundPolicy,\n): Promise<URL> {\n  let url: URL;\n  try {\n    url = new URL(rawUrl);\n  } catch {\n    throw new OutboundPolicyError(`outbound request blocked — invalid URL: ${rawUrl}`, {\n      context: { url: rawUrl },\n    });\n  }\n\n  const scheme = url.protocol.replace(/:$/, \"\").toLowerCase();\n  if (!policy.allowedSchemes.some(s => s.toLowerCase() === scheme)) {\n    throw new OutboundPolicyError(\n      `outbound request blocked — scheme \"${scheme}\" is not allowed (allowed: ${policy.allowedSchemes.join(\", \")})`,\n      { context: { url: rawUrl, scheme } },\n    );\n  }\n\n  const host = stripBrackets(url.hostname);\n\n  if (policy.hostAllowlist && !hostAllowed(host, policy.hostAllowlist)) {\n    throw new OutboundPolicyError(\n      `outbound request blocked — host \"${host}\" is not in the allowlist`,\n      { context: { url: rawUrl, host } },\n    );\n  }\n\n  if (policy.denyPrivateIPsAfterDNS) {\n    await assertHostNotPrivate(host, rawUrl);\n  }\n\n  return url;\n}\n\n/**\n * Reject when `host` is — or resolves to — a private / reserved address.\n * IP literals are checked directly; hostnames are resolved via DNS and\n * every returned address is checked (a public name pointing inward is\n * caught). A resolution failure fails closed.\n */\nasync function assertHostNotPrivate(host: string, rawUrl: string): Promise<void> {\n  if (isIP(host) !== 0) {\n    if (isPrivateOrReservedIp(host)) {\n      throw new OutboundPolicyError(\n        `outbound request blocked — \"${host}\" is a private/reserved address`,\n        { context: { url: rawUrl, address: host } },\n      );\n    }\n    return;\n  }\n\n  let addresses: Array<{ address: string }>;\n  try {\n    addresses = await lookup(host, { all: true });\n  } catch (cause) {\n    throw new OutboundPolicyError(\n      `outbound request blocked — could not resolve host \"${host}\" to verify it is public`,\n      { cause, context: { url: rawUrl, host } },\n    );\n  }\n\n  for (const { address } of addresses) {\n    if (isPrivateOrReservedIp(address)) {\n      throw new OutboundPolicyError(\n        `outbound request blocked — host \"${host}\" resolves to a private/reserved address (${address})`,\n        { context: { url: rawUrl, host, address } },\n      );\n    }\n  }\n}\n\n/** Merge the internal timeout signal with an optional caller signal. */\nfunction mergeSignals(\n  timeout: AbortSignal,\n  external?: AbortSignal,\n): AbortSignal {\n  if (!external) return timeout;\n\n  const controller = new AbortController();\n  const abort = (from: AbortSignal) => controller.abort(from.reason);\n\n  if (timeout.aborted) abort(timeout);\n  else timeout.addEventListener(\"abort\", () => abort(timeout), { once: true });\n\n  if (external.aborted) abort(external);\n  else external.addEventListener(\"abort\", () => abort(external), { once: true });\n\n  return controller.signal;\n}\n\n/** Flatten a headers init into a mutable lower-cased-key record. */\nfunction headersToRecord(\n  headersInit?: RequestInit[\"headers\"],\n): Record<string, string> {\n  const record: Record<string, string> = {};\n  new Headers(headersInit).forEach((value, key) => {\n    record[key] = value;\n  });\n  return record;\n}\n\n/**\n * Policy-guarded `fetch`: validates the URL ({@link assertUrlAllowed}),\n * then performs the request with the policy's timeout and (optional)\n * caller signal merged. Returns the raw `Response` — read its body via\n * {@link readTextCapped} to enforce `maxBytes`. Throws\n * {@link OutboundPolicyError} on a policy violation or timeout.\n *\n * Redirects are NEVER delegated to the platform: every hop is issued\n * with `redirect: \"manual\"` and its `Location` is re-run through\n * {@link assertUrlAllowed} before being followed (capped at\n * `maxRedirects`), so a 3xx from an allowed host cannot smuggle the\n * request to a private / metadata / off-allowlist target. Credential\n * headers are stripped when a hop crosses an origin boundary. Pass\n * `init.redirect: \"manual\"` to receive the raw 3xx, or `\"error\"` to\n * reject on any redirect.\n */\nexport async function guardedFetch(\n  rawUrl: string,\n  policyInput: OutboundPolicy,\n  init?: RequestInit,\n): Promise<Response> {\n  const policy = resolveOutboundPolicy(policyInput);\n  let url = await assertUrlAllowed(rawUrl, policy);\n\n  const timeoutController = new AbortController();\n  const timer = setTimeout(() => {\n    timeoutController.abort(\n      new OutboundPolicyError(\n        `outbound request timed out after ${policy.timeoutMs}ms`,\n        { context: { url: rawUrl, timeoutMs: policy.timeoutMs } },\n      ),\n    );\n  }, policy.timeoutMs);\n\n  const signal = mergeSignals(timeoutController.signal, policy.signal);\n  const redirectMode = init?.redirect ?? \"follow\";\n  const headers = headersToRecord(init?.headers);\n  let method = init?.method ?? \"GET\";\n  let body = init?.body ?? undefined;\n\n  try {\n    for (let hop = 0; ; hop++) {\n      const response = await policy.fetch(url, {\n        ...init,\n        method,\n        headers: { ...headers },\n        body,\n        redirect: \"manual\",\n        signal,\n      });\n\n      const location = response.headers.get(\"location\");\n      if (!REDIRECT_STATUSES.has(response.status) || location === null) {\n        return response;\n      }\n\n      if (redirectMode === \"manual\") {\n        return response;\n      }\n\n      if (redirectMode === \"error\") {\n        throw new OutboundPolicyError(\n          `outbound request blocked — redirect received with redirect: \"error\" (${response.status} → ${location})`,\n          { context: { url: url.toString(), location, status: response.status } },\n        );\n      }\n\n      if (hop >= policy.maxRedirects) {\n        throw new OutboundPolicyError(\n          `outbound request blocked — more than ${policy.maxRedirects} redirects`,\n          { context: { url: rawUrl, maxRedirects: policy.maxRedirects } },\n        );\n      }\n\n      let target: URL;\n      try {\n        target = new URL(location, url);\n      } catch {\n        throw new OutboundPolicyError(\n          `outbound request blocked — invalid redirect Location: ${location}`,\n          { context: { url: url.toString(), location } },\n        );\n      }\n\n      // The redirect target gets the SAME scheme / allowlist / private-IP\n      // validation as the original URL.\n      const next = await assertUrlAllowed(target.toString(), policy);\n\n      // Discard the interim body so the connection can be reused.\n      if (response.body) {\n        await response.body.cancel().catch(() => undefined);\n      }\n\n      if (next.origin !== url.origin) {\n        for (const name of CROSS_ORIGIN_STRIP_HEADERS) {\n          delete headers[name];\n        }\n      }\n\n      // 303 — and the legacy 301/302-on-a-non-GET convention — re-issue\n      // as a bodyless GET, matching platform follow semantics.\n      if (\n        response.status === 303 ||\n        ((response.status === 301 || response.status === 302) &&\n          method !== \"GET\" &&\n          method !== \"HEAD\")\n      ) {\n        method = \"GET\";\n        body = undefined;\n      }\n\n      url = next;\n    }\n  } finally {\n    clearTimeout(timer);\n  }\n}\n\n/**\n * Read a response body as UTF-8 text with a hard byte cap. A declared\n * `content-length` over the cap fails fast; otherwise the stream is read\n * chunk-by-chunk and aborted the moment the running total exceeds\n * `maxBytes`. Throws {@link OutboundPolicyError} on overflow.\n */\nexport async function readTextCapped(\n  response: Response,\n  maxBytes: number,\n): Promise<string> {\n  const declared = Number(response.headers.get(\"content-length\"));\n  if (Number.isFinite(declared) && declared > maxBytes) {\n    throw new OutboundPolicyError(\n      `outbound response body too large — declared ${declared} bytes exceeds the ${maxBytes}-byte cap`,\n      { context: { declared, maxBytes } },\n    );\n  }\n\n  if (!response.body) {\n    const text = await response.text();\n    if (Buffer.byteLength(text) > maxBytes) {\n      throw new OutboundPolicyError(\n        `outbound response body exceeded the ${maxBytes}-byte cap`,\n        { context: { maxBytes } },\n      );\n    }\n    return text;\n  }\n\n  const reader = response.body.getReader();\n  const chunks: Uint8Array[] = [];\n  let total = 0;\n\n  for (;;) {\n    const { done, value } = await reader.read();\n    if (done) break;\n    if (!value) continue;\n\n    total += value.byteLength;\n    if (total > maxBytes) {\n      await reader.cancel();\n      throw new OutboundPolicyError(\n        `outbound response body exceeded the ${maxBytes}-byte cap`,\n        { context: { maxBytes } },\n      );\n    }\n    chunks.push(value);\n  }\n\n  return Buffer.concat(chunks).toString(\"utf8\");\n}\n\n/**\n * Convenience: {@link guardedFetch} + {@link readTextCapped}. Returns the\n * response status alongside the (capped) body text so callers can shape\n * their own not-OK error. The body is only read when the response is OK.\n */\nexport async function fetchTextWithPolicy(\n  rawUrl: string,\n  policyInput: OutboundPolicy,\n  init?: RequestInit,\n): Promise<{ ok: boolean; status: number; statusText: string; text: string }> {\n  const policy = resolveOutboundPolicy(policyInput);\n  const response = await guardedFetch(rawUrl, policy, init);\n\n  return {\n    ok: response.ok,\n    status: response.status,\n    statusText: response.statusText,\n    text: response.ok ? await readTextCapped(response, policy.maxBytes) : \"\",\n  };\n}\n"],"mappings":"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"}

package/esm/security/private-ip.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"private-ip.mjs","names":[],"sources":["../../../../../../../ai/src/security/private-ip.ts"],"sourcesContent":["import { isIP } from \"node:net\";\n\n/**\n * True when `ip` is a private, loopback, link-local, unique-local,\n * carrier-grade-NAT, unspecified, or otherwise non-public address — the\n * set an SSRF guard must refuse. Accepts IPv4 and IPv6 literals (including\n * IPv4-mapped IPv6 like `::ffff:169.254.169.254`). A non-IP string returns\n * `false` (the caller resolves hostnames via DNS first).\n *\n * The cloud-metadata endpoint `169.254.169.254` is covered by the IPv4\n * link-local range `169.254.0.0/16`.\n */\nexport function isPrivateOrReservedIp(ip: string): boolean {\n  const family = isIP(ip);\n  if (family === 4) return isPrivateIpv4(ip);\n  if (family === 6) return isPrivateIpv6(ip);\n  return false;\n}\n\n/** Parse a dotted-quad into four octets, or `null` if malformed. */\nfunction parseIpv4(ip: string): [number, number, number, number] | null {\n  const parts = ip.split(\".\");\n  if (parts.length !== 4) return null;\n\n  const octets = parts.map(part => Number(part));\n  if (octets.some(n => !Number.isInteger(n) || n < 0 || n > 255)) return null;\n\n  return octets as [number, number, number, number];\n}\n\nfunction isPrivateIpv4(ip: string): boolean {\n  const octets = parseIpv4(ip);\n  if (!octets) return true; // unparseable → refuse, fail closed\n\n  const [a, b] = octets;\n\n  return (\n    a === 0 || // 0.0.0.0/8 \"this network\"\n    a === 10 || // 10.0.0.0/8 private\n    a === 127 || // 127.0.0.0/8 loopback\n    (a === 100 && b >= 64 && b <= 127) || // 100.64.0.0/10 CGNAT\n    (a === 169 && b === 254) || // 169.254.0.0/16 link-local + metadata\n    (a === 172 && b >= 16 && b <= 31) || // 172.16.0.0/12 private\n    (a === 192 && b === 168) || // 192.168.0.0/16 private\n    (a === 192 && b === 0) || // 192.0.0.0/24 + 192.0.2.0/24 (IETF/test)\n    (a === 198 && (b === 18 || b === 19)) || // 198.18.0.0/15 benchmarking\n    (a === 198 && b === 51) || // 198.51.100.0/24 test-net-2\n    (a === 203 && b === 0) || // 203.0.113.0/24 test-net-3\n    a >= 224 // 224.0.0.0/4 multicast + 240.0.0.0/4 reserved + 255.255.255.255\n  );\n}\n\nfunction isPrivateIpv6(ip: string): boolean {\n  const normalized = ip.toLowerCase().split(\"%\")[0]; // drop zone id\n\n  // IPv4-mapped / -embedded (::ffff:a.b.c.d, ::a.b.c.d) — defer to the v4\n  // check on the trailing dotted-quad so an inward-mapped address is caught.\n  const v4 = normalized.match(/(\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}\\.\\d{1,3})$/);\n  if (v4) {\n    return isPrivateIpv4(v4[1]);\n  }\n\n  if (normalized === \"::1\" || normalized === \"::\") {\n    return true; // loopback / unspecified\n  }\n\n  // Expand only the leading group enough to classify the reserved blocks.\n  const firstGroup = normalized.split(\":\")[0];\n  const head = firstGroup === \"\" ? 0 : Number.parseInt(firstGroup, 16);\n\n  // fc00::/7 unique-local (fc.. / fd..)\n  if ((head & 0xfe00) === 0xfc00) return true;\n  // fe80::/10 link-local\n  if ((head & 0xffc0) === 0xfe80) return true;\n\n  return false;\n}\n"],"mappings":";;;;;;;;;;;;;AAYA,SAAgB,sBAAsB,IAAqB;CACzD,MAAM,SAAS,KAAK,EAAE;CACtB,IAAI,WAAW,GAAG,OAAO,cAAc,EAAE;CACzC,IAAI,WAAW,GAAG,OAAO,cAAc,EAAE;CACzC,OAAO;AACT;;AAGA,SAAS,UAAU,IAAqD;CACtE,MAAM,QAAQ,GAAG,MAAM,GAAG;CAC1B,IAAI,MAAM,WAAW,GAAG,OAAO;CAE/B,MAAM,SAAS,MAAM,KAAI,SAAQ,OAAO,IAAI,CAAC;CAC7C,IAAI,OAAO,MAAK,MAAK,CAAC,OAAO,UAAU,CAAC,KAAK,IAAI,KAAK,IAAI,GAAG,GAAG,OAAO;CAEvE,OAAO;AACT;AAEA,SAAS,cAAc,IAAqB;CAC1C,MAAM,SAAS,UAAU,EAAE;CAC3B,IAAI,CAAC,QAAQ,OAAO;CAEpB,MAAM,CAAC,GAAG,KAAK;CAEf,OACE,MAAM,KACN,MAAM,MACN,MAAM,OACL,MAAM,OAAO,KAAK,MAAM,KAAK,OAC7B,MAAM,OAAO,MAAM,OACnB,MAAM,OAAO,KAAK,MAAM,KAAK,MAC7B,MAAM,OAAO,MAAM,OACnB,MAAM,OAAO,MAAM,KACnB,MAAM,QAAQ,MAAM,MAAM,MAAM,OAChC,MAAM,OAAO,MAAM,MACnB,MAAM,OAAO,MAAM,KACpB,KAAK;AAET;AAEA,SAAS,cAAc,IAAqB;CAC1C,MAAM,aAAa,GAAG,YAAY,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;CAI/C,MAAM,KAAK,WAAW,MAAM,uCAAuC;CACnE,IAAI,IACF,OAAO,cAAc,GAAG,EAAE;CAG5B,IAAI,eAAe,SAAS,eAAe,MACzC,OAAO;CAIT,MAAM,aAAa,WAAW,MAAM,GAAG,CAAC,CAAC;CACzC,MAAM,OAAO,eAAe,KAAK,IAAI,OAAO,SAAS,YAAY,EAAE;CAGnE,KAAK,OAAO,WAAY,OAAQ,OAAO;CAEvC,KAAK,OAAO,WAAY,OAAQ,OAAO;CAEvC,OAAO;AACT"}
+{"version":3,"file":"private-ip.mjs","names":[],"sources":["../../../../../../../ai/src/security/private-ip.ts"],"sourcesContent":["import { isIP } from \"node:net\";\n\n/**\n * True when `ip` is a private, loopback, link-local, unique-local,\n * carrier-grade-NAT, unspecified, or otherwise non-public address — the\n * set an SSRF guard must refuse. Accepts IPv4 and IPv6 literals (including\n * IPv4-mapped IPv6 like `::ffff:169.254.169.254`). A non-IP string returns\n * `false` (the caller resolves hostnames via DNS first).\n *\n * The cloud-metadata endpoint `169.254.169.254` is covered by the IPv4\n * link-local range `169.254.0.0/16`.\n */\nexport function isPrivateOrReservedIp(ip: string): boolean {\n  const family = isIP(ip);\n  if (family === 4) return isPrivateIpv4(ip);\n  if (family === 6) return isPrivateIpv6(ip);\n  return false;\n}\n\n/** Parse a dotted-quad into four octets, or `null` if malformed. */\nfunction parseIpv4(ip: string): [number, number, number, number] | null {\n  const parts = ip.split(\".\");\n  if (parts.length !== 4) return null;\n\n  const octets = parts.map(part => Number(part));\n  if (octets.some(n => !Number.isInteger(n) || n < 0 || n > 255)) return null;\n\n  return octets as [number, number, number, number];\n}\n\nfunction isPrivateIpv4(ip: string): boolean {\n  const octets = parseIpv4(ip);\n  if (!octets) return true; // unparseable → refuse, fail closed\n\n  const [a, b] = octets;\n\n  return (\n    a === 0 || // 0.0.0.0/8 \"this network\"\n    a === 10 || // 10.0.0.0/8 private\n    a === 127 || // 127.0.0.0/8 loopback\n    (a === 100 && b >= 64 && b <= 127) || // 100.64.0.0/10 CGNAT\n    (a === 169 && b === 254) || // 169.254.0.0/16 link-local + metadata\n    (a === 172 && b >= 16 && b <= 31) || // 172.16.0.0/12 private\n    (a === 192 && b === 168) || // 192.168.0.0/16 private\n    (a === 192 && b === 0) || // 192.0.0.0/24 + 192.0.2.0/24 (IETF/test)\n    (a === 198 && (b === 18 || b === 19)) || // 198.18.0.0/15 benchmarking\n    (a === 198 && b === 51) || // 198.51.100.0/24 test-net-2\n    (a === 203 && b === 0) || // 203.0.113.0/24 test-net-3\n    a >= 224 // 224.0.0.0/4 multicast + 240.0.0.0/4 reserved + 255.255.255.255\n  );\n}\n\nfunction isPrivateIpv6(ip: string): boolean {\n  const normalized = ip.toLowerCase().split(\"%\")[0]; // drop zone id\n\n  // IPv4-mapped / -embedded (::ffff:a.b.c.d, ::a.b.c.d) — defer to the v4\n  // check on the trailing dotted-quad so an inward-mapped address is caught.\n  const v4 = normalized.match(/(\\d{1,3}\\.\\d{1,3}\\.\\d{1,3}\\.\\d{1,3})$/);\n  if (v4) {\n    return isPrivateIpv4(v4[1]);\n  }\n\n  if (normalized === \"::1\" || normalized === \"::\") {\n    return true; // loopback / unspecified\n  }\n\n  // Expand only the leading group enough to classify the reserved blocks.\n  const firstGroup = normalized.split(\":\")[0];\n  const head = firstGroup === \"\" ? 0 : Number.parseInt(firstGroup, 16);\n\n  // fc00::/7 unique-local (fc.. / fd..)\n  if ((head & 0xfe00) === 0xfc00) return true;\n  // fe80::/10 link-local\n  if ((head & 0xffc0) === 0xfe80) return true;\n\n  return false;\n}\n"],"mappings":";;;;;;;;;;;;;AAYA,SAAgB,sBAAsB,IAAqB;CACzD,MAAM,SAAS,KAAK,EAAE;CACtB,IAAI,WAAW,GAAG,OAAO,cAAc,EAAE;CACzC,IAAI,WAAW,GAAG,OAAO,cAAc,EAAE;CACzC,OAAO;AACT;;AAGA,SAAS,UAAU,IAAqD;CACtE,MAAM,QAAQ,GAAG,MAAM,GAAG;CAC1B,IAAI,MAAM,WAAW,GAAG,OAAO;CAE/B,MAAM,SAAS,MAAM,KAAI,SAAQ,OAAO,IAAI,CAAC;CAC7C,IAAI,OAAO,MAAK,MAAK,CAAC,OAAO,UAAU,CAAC,KAAK,IAAI,KAAK,IAAI,GAAG,GAAG,OAAO;CAEvE,OAAO;AACT;AAEA,SAAS,cAAc,IAAqB;CAC1C,MAAM,SAAS,UAAU,EAAE;CAC3B,IAAI,CAAC,QAAQ,OAAO;CAEpB,MAAM,CAAC,GAAG,KAAK;CAEf,OACE,MAAM,KACN,MAAM,MACN,MAAM,OACL,MAAM,OAAO,KAAK,MAAM,KAAK,OAC7B,MAAM,OAAO,MAAM,OACnB,MAAM,OAAO,KAAK,MAAM,KAAK,MAC7B,MAAM,OAAO,MAAM,OACnB,MAAM,OAAO,MAAM,KACnB,MAAM,QAAQ,MAAM,MAAM,MAAM,OAChC,MAAM,OAAO,MAAM,MACnB,MAAM,OAAO,MAAM,KACpB,KAAK;AAET;AAEA,SAAS,cAAc,IAAqB;CAC1C,MAAM,aAAa,GAAG,YAAY,EAAE,MAAM,GAAG,EAAE;CAI/C,MAAM,KAAK,WAAW,MAAM,uCAAuC;CACnE,IAAI,IACF,OAAO,cAAc,GAAG,EAAE;CAG5B,IAAI,eAAe,SAAS,eAAe,MACzC,OAAO;CAIT,MAAM,aAAa,WAAW,MAAM,GAAG,EAAE;CACzC,MAAM,OAAO,eAAe,KAAK,IAAI,OAAO,SAAS,YAAY,EAAE;CAGnE,KAAK,OAAO,WAAY,OAAQ,OAAO;CAEvC,KAAK,OAAO,WAAY,OAAQ,OAAO;CAEvC,OAAO;AACT"}

package/esm/security/redact.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"redact.d.mts","names":[],"sources":["../../../../../../../ai/src/security/redact.ts"],"mappings":";;AAMA;;;;AAgBC;cAhBY,sBAAA;;cAmBA,iBAAA;AAAA,KASD,aAAA;EAFX,iFAIC,IAAA,aAFuB;EAIvB,WAAA,WAJuB;EAMvB,QAAA;AAAA;;;AAAQ;AAqBV;;;;;;;iBAAgB,MAAA,IAAU,KAAA,EAAO,CAAA,EAAG,OAAA,GAAS,aAAA,GAAqB,CAAA;;;;;;iBAkDlD,aAAA,CACd,OAAA,EAAS,OAAA,GAAU,MAAA,+BACnB,WAAA,YACC,MAAA;;AArDgE;AAkDnE;;;;iBAuCgB,YAAA,CAAa,IAAY;;;;;;;;KAe7B,aAAA;EACV,IAAA;EACA,OAAA;EACA,IAAA;EACA,KAAA;EACA,KAAA;AAAA;AAAA,iBAGc,WAAA,CACd,KAAA,WACA,OAAA;EAAW,YAAA;AAAA,IAA2B,aAAA,GACrC,aAAa"}
+{"version":3,"file":"redact.d.mts","names":[],"sources":["../../../../../../../ai/src/security/redact.ts"],"mappings":";;AAMA;;;;AAgBC;cAhBY,sBAAA;;cAmBA,iBAAA;AAAA,KASD,aAAA;EAFX,iFAIC,IAAA,aAFuB;EAIvB,WAAA,WAJuB;EAMvB,QAAA;AAAA;;;AAAQ;AAqBV;;;;;;;iBAAgB,MAAA,GAAA,CAAU,KAAA,EAAO,CAAA,EAAG,OAAA,GAAS,aAAA,GAAqB,CAAA;;;;;;iBAkDlD,aAAA,CACd,OAAA,EAAS,OAAA,GAAU,MAAA,+BACnB,WAAA,YACC,MAAA;;AArDgE;AAkDnE;;;;iBAuCgB,YAAA,CAAa,IAAY;;;;;;;;KAe7B,aAAA;EACV,IAAA;EACA,OAAA;EACA,IAAA;EACA,KAAA;EACA,KAAA;AAAA;AAAA,iBAGc,WAAA,CACd,KAAA,WACA,OAAA;EAAW,YAAA;AAAA,IAA2B,aAAA,GACrC,aAAa"}

package/esm/security/redact.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"redact.mjs","names":[],"sources":["../../../../../../../ai/src/security/redact.ts"],"sourcesContent":["/**\n * Default set of sensitive key fragments (matched case-insensitively as\n * substrings of an object key). Covers the secrets that leak through\n * recorded requests, error causes, and trace payloads: auth headers, API\n * keys, cookies, tokens, passwords, and private keys.\n */\nexport const DEFAULT_SENSITIVE_KEYS: readonly string[] = [\n  \"authorization\",\n  \"x-api-key\",\n  \"api-key\",\n  \"apikey\",\n  \"cookie\",\n  \"set-cookie\",\n  \"password\",\n  \"passwd\",\n  \"secret\",\n  \"token\",\n  \"access_token\",\n  \"refresh_token\",\n  \"client_secret\",\n  \"private_key\",\n  \"session\",\n];\n\n/** HTTP header names always stripped from a serialized error/cause. */\nexport const SENSITIVE_HEADERS: readonly string[] = [\n  \"authorization\",\n  \"x-api-key\",\n  \"api-key\",\n  \"cookie\",\n  \"set-cookie\",\n  \"proxy-authorization\",\n];\n\nexport type RedactOptions = {\n  /** Extra key fragments to redact, merged with {@link DEFAULT_SENSITIVE_KEYS}. */\n  keys?: string[];\n  /** Replacement for a redacted value. Default `\"[redacted]\"`. */\n  placeholder?: string;\n  /** Maximum recursion depth before bailing out. Default `8`. */\n  maxDepth?: number;\n};\n\nconst DEFAULT_PLACEHOLDER = \"[redacted]\";\nconst DEFAULT_MAX_DEPTH = 8;\n\nfunction keyIsSensitive(key: string, fragments: string[]): boolean {\n  const lower = key.toLowerCase();\n  return fragments.some(fragment => lower.includes(fragment));\n}\n\n/**\n * Deep-copy `value` with any property whose KEY matches a sensitive\n * fragment replaced by the placeholder. Arrays are walked element-wise;\n * circular references and over-deep trees collapse to the placeholder.\n * Primitives pass through untouched (redaction is key-driven, not\n * value-driven — it never guesses at a bare string being a secret).\n *\n * Shared by VCR cassettes (S2), Panoptic content capture, and the error /\n * cause serializer (S4) so there is ONE redaction policy, not three.\n */\nexport function redact<T>(value: T, options: RedactOptions = {}): T {\n  const fragments = [...DEFAULT_SENSITIVE_KEYS, ...(options.keys ?? [])].map(k =>\n    k.toLowerCase(),\n  );\n  const placeholder = options.placeholder ?? DEFAULT_PLACEHOLDER;\n  const maxDepth = options.maxDepth ?? DEFAULT_MAX_DEPTH;\n  const seen = new WeakSet<object>();\n\n  const walk = (input: unknown, depth: number): unknown => {\n    if (input === null || typeof input !== \"object\") {\n      return input;\n    }\n    if (depth >= maxDepth || seen.has(input)) {\n      return placeholder;\n    }\n    seen.add(input as object);\n\n    if (Array.isArray(input)) {\n      return input.map(item => walk(item, depth + 1));\n    }\n\n    // `name` / `message` / `stack` sit on Error's prototype chain (or as\n    // non-enumerable own properties), so a plain `Object.entries()` walk\n    // sees none of them — a raw Error `cause` would otherwise collapse to\n    // `{}`. Project them explicitly; own enumerable extras (`code`,\n    // `cause`, custom AIError fields) still merge in below and recurse\n    // normally, so a chained `cause` that is itself an Error is unwrapped\n    // the same way.\n    const source: Record<string, unknown> =\n      input instanceof Error\n        ? { ...input, name: input.name, message: input.message, stack: input.stack }\n        : (input as Record<string, unknown>);\n\n    const out: Record<string, unknown> = {};\n    for (const [key, val] of Object.entries(source)) {\n      out[key] = keyIsSensitive(key, fragments)\n        ? placeholder\n        : walk(val, depth + 1);\n    }\n    return out;\n  };\n\n  return walk(value, 0) as T;\n}\n\n/**\n * Strip sensitive HTTP headers from a `Headers` instance or a plain\n * header record, returning a redacted plain object. Header names are\n * matched case-insensitively against {@link SENSITIVE_HEADERS}.\n */\nexport function redactHeaders(\n  headers: Headers | Record<string, unknown> | undefined,\n  placeholder: string = DEFAULT_PLACEHOLDER,\n): Record<string, unknown> {\n  if (!headers) return {};\n\n  const entries: Array<[string, unknown]> =\n    headers instanceof Headers\n      ? [...headers.entries()]\n      : Object.entries(headers);\n\n  const out: Record<string, unknown> = {};\n  for (const [key, val] of entries) {\n    out[key] = SENSITIVE_HEADERS.includes(key.toLowerCase()) ? placeholder : val;\n  }\n  return out;\n}\n\n/**\n * Patterns for secrets that hide in FREE TEXT (error messages, stack\n * traces, log lines) where the key-based {@link redact} can't reach them.\n * Each entry replaces the secret with `[redacted]` while keeping\n * surrounding context.\n */\nconst SECRET_PATTERNS: ReadonlyArray<readonly [RegExp, string]> = [\n  [/\\bBearer\\s+[A-Za-z0-9._~+/-]+=*/gi, \"Bearer [redacted]\"],\n  [/\\b(authorization|x-api-key|api[_-]?key|cookie)(\"?\\s*[:=]\\s*\"?)[^\\s\",}]+/gi, \"$1$2[redacted]\"],\n  [/\\bsk-[A-Za-z0-9]{16,}\\b/g, \"[redacted]\"], // OpenAI-style keys\n  [/\\bxox[baprs]-[A-Za-z0-9-]{8,}\\b/g, \"[redacted]\"], // Slack tokens\n  [/\\bgh[pousr]_[A-Za-z0-9]{20,}\\b/g, \"[redacted]\"], // GitHub tokens\n  [/\\bAKIA[0-9A-Z]{16}\\b/g, \"[redacted]\"], // AWS access key ids\n];\n\n/**\n * Scrub secrets that appear in free-form text — error messages, stack\n * traces, exported log lines. Complements {@link redact} (which is key-\n * driven and can't see a token embedded in a string). Used by the trace /\n * error serializer (S4) before a message or stack is stored or exported.\n */\nexport function scrubSecrets(text: string): string {\n  let out = text;\n  for (const [pattern, replacement] of SECRET_PATTERNS) {\n    out = out.replace(pattern, replacement);\n  }\n  return out;\n}\n\n/**\n * Serialized, secret-free view of an error. `stack` is omitted by default\n * (it can embed local paths, endpoints, and tokens); pass\n * `includeStack: true` only for a trusted local sink. The retained\n * `cause` is deep-redacted via {@link redact}, so a raw provider SDK error\n * carrying `Authorization` / `x-api-key` on `cause.headers` is sanitized.\n */\nexport type RedactedError = {\n  name: string;\n  message: string;\n  code?: string;\n  cause?: unknown;\n  stack?: string;\n};\n\nexport function redactError(\n  error: unknown,\n  options: { includeStack?: boolean } & RedactOptions = {},\n): RedactedError {\n  const { includeStack, ...redactOptions } = options;\n\n  if (error === null || typeof error !== \"object\") {\n    return { name: \"Error\", message: String(error) };\n  }\n\n  const err = error as {\n    name?: unknown;\n    message?: unknown;\n    code?: unknown;\n    cause?: unknown;\n    stack?: unknown;\n  };\n\n  const result: RedactedError = {\n    name: typeof err.name === \"string\" ? err.name : \"Error\",\n    message: typeof err.message === \"string\" ? err.message : String(error),\n  };\n\n  if (typeof err.code === \"string\") {\n    result.code = err.code;\n  }\n  if (err.cause !== undefined) {\n    result.cause =\n      err.cause !== null && typeof err.cause === \"object\"\n        ? redact(err.cause, redactOptions)\n        : err.cause;\n  }\n  if (includeStack && typeof err.stack === \"string\") {\n    result.stack = err.stack;\n  }\n\n  return result;\n}\n"],"mappings":"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"}
+{"version":3,"file":"redact.mjs","names":[],"sources":["../../../../../../../ai/src/security/redact.ts"],"sourcesContent":["/**\n * Default set of sensitive key fragments (matched case-insensitively as\n * substrings of an object key). Covers the secrets that leak through\n * recorded requests, error causes, and trace payloads: auth headers, API\n * keys, cookies, tokens, passwords, and private keys.\n */\nexport const DEFAULT_SENSITIVE_KEYS: readonly string[] = [\n  \"authorization\",\n  \"x-api-key\",\n  \"api-key\",\n  \"apikey\",\n  \"cookie\",\n  \"set-cookie\",\n  \"password\",\n  \"passwd\",\n  \"secret\",\n  \"token\",\n  \"access_token\",\n  \"refresh_token\",\n  \"client_secret\",\n  \"private_key\",\n  \"session\",\n];\n\n/** HTTP header names always stripped from a serialized error/cause. */\nexport const SENSITIVE_HEADERS: readonly string[] = [\n  \"authorization\",\n  \"x-api-key\",\n  \"api-key\",\n  \"cookie\",\n  \"set-cookie\",\n  \"proxy-authorization\",\n];\n\nexport type RedactOptions = {\n  /** Extra key fragments to redact, merged with {@link DEFAULT_SENSITIVE_KEYS}. */\n  keys?: string[];\n  /** Replacement for a redacted value. Default `\"[redacted]\"`. */\n  placeholder?: string;\n  /** Maximum recursion depth before bailing out. Default `8`. */\n  maxDepth?: number;\n};\n\nconst DEFAULT_PLACEHOLDER = \"[redacted]\";\nconst DEFAULT_MAX_DEPTH = 8;\n\nfunction keyIsSensitive(key: string, fragments: string[]): boolean {\n  const lower = key.toLowerCase();\n  return fragments.some(fragment => lower.includes(fragment));\n}\n\n/**\n * Deep-copy `value` with any property whose KEY matches a sensitive\n * fragment replaced by the placeholder. Arrays are walked element-wise;\n * circular references and over-deep trees collapse to the placeholder.\n * Primitives pass through untouched (redaction is key-driven, not\n * value-driven — it never guesses at a bare string being a secret).\n *\n * Shared by VCR cassettes (S2), Panoptic content capture, and the error /\n * cause serializer (S4) so there is ONE redaction policy, not three.\n */\nexport function redact<T>(value: T, options: RedactOptions = {}): T {\n  const fragments = [...DEFAULT_SENSITIVE_KEYS, ...(options.keys ?? [])].map(k =>\n    k.toLowerCase(),\n  );\n  const placeholder = options.placeholder ?? DEFAULT_PLACEHOLDER;\n  const maxDepth = options.maxDepth ?? DEFAULT_MAX_DEPTH;\n  const seen = new WeakSet<object>();\n\n  const walk = (input: unknown, depth: number): unknown => {\n    if (input === null || typeof input !== \"object\") {\n      return input;\n    }\n    if (depth >= maxDepth || seen.has(input)) {\n      return placeholder;\n    }\n    seen.add(input as object);\n\n    if (Array.isArray(input)) {\n      return input.map(item => walk(item, depth + 1));\n    }\n\n    // `name` / `message` / `stack` sit on Error's prototype chain (or as\n    // non-enumerable own properties), so a plain `Object.entries()` walk\n    // sees none of them — a raw Error `cause` would otherwise collapse to\n    // `{}`. Project them explicitly; own enumerable extras (`code`,\n    // `cause`, custom AIError fields) still merge in below and recurse\n    // normally, so a chained `cause` that is itself an Error is unwrapped\n    // the same way.\n    const source: Record<string, unknown> =\n      input instanceof Error\n        ? { ...input, name: input.name, message: input.message, stack: input.stack }\n        : (input as Record<string, unknown>);\n\n    const out: Record<string, unknown> = {};\n    for (const [key, val] of Object.entries(source)) {\n      out[key] = keyIsSensitive(key, fragments)\n        ? placeholder\n        : walk(val, depth + 1);\n    }\n    return out;\n  };\n\n  return walk(value, 0) as T;\n}\n\n/**\n * Strip sensitive HTTP headers from a `Headers` instance or a plain\n * header record, returning a redacted plain object. Header names are\n * matched case-insensitively against {@link SENSITIVE_HEADERS}.\n */\nexport function redactHeaders(\n  headers: Headers | Record<string, unknown> | undefined,\n  placeholder: string = DEFAULT_PLACEHOLDER,\n): Record<string, unknown> {\n  if (!headers) return {};\n\n  const entries: Array<[string, unknown]> =\n    headers instanceof Headers\n      ? [...headers.entries()]\n      : Object.entries(headers);\n\n  const out: Record<string, unknown> = {};\n  for (const [key, val] of entries) {\n    out[key] = SENSITIVE_HEADERS.includes(key.toLowerCase()) ? placeholder : val;\n  }\n  return out;\n}\n\n/**\n * Patterns for secrets that hide in FREE TEXT (error messages, stack\n * traces, log lines) where the key-based {@link redact} can't reach them.\n * Each entry replaces the secret with `[redacted]` while keeping\n * surrounding context.\n */\nconst SECRET_PATTERNS: ReadonlyArray<readonly [RegExp, string]> = [\n  [/\\bBearer\\s+[A-Za-z0-9._~+/-]+=*/gi, \"Bearer [redacted]\"],\n  [/\\b(authorization|x-api-key|api[_-]?key|cookie)(\"?\\s*[:=]\\s*\"?)[^\\s\",}]+/gi, \"$1$2[redacted]\"],\n  [/\\bsk-[A-Za-z0-9]{16,}\\b/g, \"[redacted]\"], // OpenAI-style keys\n  [/\\bxox[baprs]-[A-Za-z0-9-]{8,}\\b/g, \"[redacted]\"], // Slack tokens\n  [/\\bgh[pousr]_[A-Za-z0-9]{20,}\\b/g, \"[redacted]\"], // GitHub tokens\n  [/\\bAKIA[0-9A-Z]{16}\\b/g, \"[redacted]\"], // AWS access key ids\n];\n\n/**\n * Scrub secrets that appear in free-form text — error messages, stack\n * traces, exported log lines. Complements {@link redact} (which is key-\n * driven and can't see a token embedded in a string). Used by the trace /\n * error serializer (S4) before a message or stack is stored or exported.\n */\nexport function scrubSecrets(text: string): string {\n  let out = text;\n  for (const [pattern, replacement] of SECRET_PATTERNS) {\n    out = out.replace(pattern, replacement);\n  }\n  return out;\n}\n\n/**\n * Serialized, secret-free view of an error. `stack` is omitted by default\n * (it can embed local paths, endpoints, and tokens); pass\n * `includeStack: true` only for a trusted local sink. The retained\n * `cause` is deep-redacted via {@link redact}, so a raw provider SDK error\n * carrying `Authorization` / `x-api-key` on `cause.headers` is sanitized.\n */\nexport type RedactedError = {\n  name: string;\n  message: string;\n  code?: string;\n  cause?: unknown;\n  stack?: string;\n};\n\nexport function redactError(\n  error: unknown,\n  options: { includeStack?: boolean } & RedactOptions = {},\n): RedactedError {\n  const { includeStack, ...redactOptions } = options;\n\n  if (error === null || typeof error !== \"object\") {\n    return { name: \"Error\", message: String(error) };\n  }\n\n  const err = error as {\n    name?: unknown;\n    message?: unknown;\n    code?: unknown;\n    cause?: unknown;\n    stack?: unknown;\n  };\n\n  const result: RedactedError = {\n    name: typeof err.name === \"string\" ? err.name : \"Error\",\n    message: typeof err.message === \"string\" ? err.message : String(error),\n  };\n\n  if (typeof err.code === \"string\") {\n    result.code = err.code;\n  }\n  if (err.cause !== undefined) {\n    result.cause =\n      err.cause !== null && typeof err.cause === \"object\"\n        ? redact(err.cause, redactOptions)\n        : err.cause;\n  }\n  if (includeStack && typeof err.stack === \"string\") {\n    result.stack = err.stack;\n  }\n\n  return result;\n}\n"],"mappings":"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"}

package/esm/serve/serve.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"serve.d.mts","names":[],"sources":["../../../../../../../ai/src/serve/serve.ts"],"mappings":";;;;;;AAQA;;;KAAY,kBAAA;EACV,MAAA,CAAO,KAAA,EAAO,MAAA,EAAQ,OAAA,GAAU,MAAA,oBAA0B,UAAA;IAAa,IAAA;EAAA;AAAA;;KAI7D,YAAA;EAJI;;;;;EAUd,SAAA;EAV2E;AAAA;AAI7E;;EAWE,OAAA,IAAW,IAAA,EAAM,MAAA,sBAA4B,MAAA;EAA5B;;;;;EAMjB,SAAA,IAAa,IAAA,EAAM,MAAA,sBAA4B,MAAA;AAAA;;;;;;;;;;;AAAM;AAqBvD;iBAAgB,KAAA,mBACd,UAAA,EAAY,kBAAA,CAAmB,MAAA,GAC/B,OAAA,GAAS,YAAA,CAAa,MAAA,KACpB,GAAA,EAAK,eAAA,EAAiB,GAAA,EAAK,cAAA"}
+{"version":3,"file":"serve.d.mts","names":[],"sources":["../../../../../../../ai/src/serve/serve.ts"],"mappings":";;;;;;AAQA;;;KAAY,kBAAA;EACV,MAAA,CAAO,KAAA,EAAO,MAAA,EAAQ,OAAA,GAAU,MAAA,oBAA0B,UAAA;IAAa,IAAA;EAAA;AAAA;;KAI7D,YAAA;EAJI;;;;;EAUd,SAAA;EAV2E;AAAA;AAI7E;;EAWE,OAAA,IAAW,IAAA,EAAM,MAAA,sBAA4B,MAAA;EAA5B;;;;;EAMjB,SAAA,IAAa,IAAA,EAAM,MAAA,sBAA4B,MAAA;AAAA;;;;;;;;;;;AAAM;AAqBvD;iBAAgB,KAAA,kBAAA,CACd,UAAA,EAAY,kBAAA,CAAmB,MAAA,GAC/B,OAAA,GAAS,YAAA,CAAa,MAAA,KACpB,GAAA,EAAK,eAAA,EAAiB,GAAA,EAAK,cAAA"}

package/esm/serve/serve.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"serve.mjs","names":[],"sources":["../../../../../../../ai/src/serve/serve.ts"],"sourcesContent":["import type { IncomingMessage, ServerResponse } from \"node:http\";\nimport { streamToSSE, type StreamLike } from \"./stream-to-sse\";\n\n/**\n * Anything `serve` can expose: a primitive whose `stream(input, options)`\n * returns a {@link StreamLike}. Agents, supervisors, and orchestrators all\n * satisfy it.\n */\nexport type ServableExecutable<TInput = unknown> = {\n  stream(input: TInput, options?: Record<string, unknown>): StreamLike<{ type: string }, unknown>;\n};\n\n/** Options for {@link serve}. */\nexport type ServeOptions<TInput = unknown> = {\n  /**\n   * Bearer token required on every request. When set, a request must send\n   * `Authorization: Bearer <token>`, else `401` (S4-style auth, the same\n   * control the dashboard uses — fold this in for a production deploy).\n   */\n  authToken?: string;\n  /**\n   * Map the parsed JSON request body to the executable's input. Default:\n   * `body.input`. Override to accept a different request shape.\n   */\n  toInput?: (body: Record<string, unknown>) => TInput;\n  /**\n   * Map the parsed body to per-call stream options (e.g. an orchestrator\n   * `{ sessionId, history }` so a turn resumes the right session — A3\n   * wiring). Default: pass `sessionId` / `history` straight through.\n   */\n  toOptions?: (body: Record<string, unknown>) => Record<string, unknown>;\n};\n\nconst SECURITY_HEADERS: Record<string, string> = {\n  \"x-content-type-options\": \"nosniff\",\n  \"x-frame-options\": \"DENY\",\n  \"referrer-policy\": \"no-referrer\",\n};\n\n/**\n * Turn an executable into a `node:http` request handler that streams its\n * run to the client as Server-Sent Events (A3) — the production-serving\n * primitive. POST a JSON body (`{ input, sessionId?, history? }`); the\n * response is an `text/event-stream` of the primitive's events, the final\n * `result`, then `[DONE]`. Absorbs the auth-token control; pair with a\n * `sessionLock` + an orchestrator for durable multi-turn serving.\n *\n * @example\n * import { createServer } from \"node:http\";\n * createServer(ai.serve(myAgent, { authToken: process.env.TOKEN })).listen(8787);\n */\nexport function serve<TInput = unknown>(\n  executable: ServableExecutable<TInput>,\n  options: ServeOptions<TInput> = {},\n): (req: IncomingMessage, res: ServerResponse) => void {\n  const toInput = options.toInput ?? ((body) => body.input as TInput);\n  const toOptions =\n    options.toOptions ??\n    ((body) => {\n      const opts: Record<string, unknown> = {};\n      if (body.sessionId !== undefined) opts.sessionId = body.sessionId;\n      if (body.history !== undefined) opts.history = body.history;\n      return opts;\n    });\n\n  return function handle(req: IncomingMessage, res: ServerResponse): void {\n    void (async () => {\n      if (req.method !== \"POST\") {\n        sendJson(res, 405, { error: \"method_not_allowed\" });\n        return;\n      }\n\n      if (options.authToken && req.headers.authorization !== `Bearer ${options.authToken}`) {\n        sendJson(res, 401, { error: \"unauthorized\" });\n        return;\n      }\n\n      let body: Record<string, unknown>;\n      try {\n        body = await readJsonBody(req);\n      } catch {\n        sendJson(res, 400, { error: \"invalid_json\" });\n        return;\n      }\n\n      res.writeHead(200, {\n        \"content-type\": \"text/event-stream; charset=utf-8\",\n        \"cache-control\": \"no-cache\",\n        connection: \"keep-alive\",\n        ...SECURITY_HEADERS,\n      });\n\n      try {\n        const stream = executable.stream(toInput(body), toOptions(body));\n        for await (const frame of streamToSSE(stream)) {\n          res.write(frame);\n        }\n      } catch (error) {\n        res.write(\n          `event: error\\ndata: ${JSON.stringify({\n            message: error instanceof Error ? error.message : String(error),\n          })}\\n\\n`,\n        );\n      } finally {\n        res.end();\n      }\n    })();\n  };\n}\n\n/** Read and JSON-parse a request body. */\nfunction readJsonBody(req: IncomingMessage): Promise<Record<string, unknown>> {\n  return new Promise((resolve, reject) => {\n    let raw = \"\";\n    req.on(\"data\", (chunk: Buffer | string) => {\n      raw += chunk.toString();\n    });\n    req.on(\"end\", () => {\n      try {\n        resolve(raw ? (JSON.parse(raw) as Record<string, unknown>) : {});\n      } catch (error) {\n        reject(error);\n      }\n    });\n    req.on(\"error\", reject);\n  });\n}\n\nfunction sendJson(res: ServerResponse, status: number, body: unknown): void {\n  res.writeHead(status, { \"content-type\": \"application/json; charset=utf-8\", ...SECURITY_HEADERS });\n  res.end(JSON.stringify(body));\n}\n"],"mappings":";;;AAiCA,MAAM,mBAA2C;CAC/C,0BAA0B;CAC1B,mBAAmB;CACnB,mBAAmB;AACrB;;;;;;;;;;;;;AAcA,SAAgB,MACd,YACA,UAAgC,CAAC,GACoB;CACrD,MAAM,UAAU,QAAQ,aAAa,SAAS,KAAK;CACnD,MAAM,YACJ,QAAQ,eACN,SAAS;EACT,MAAM,OAAgC,CAAC;EACvC,IAAI,KAAK,cAAc,QAAW,KAAK,YAAY,KAAK;EACxD,IAAI,KAAK,YAAY,QAAW,KAAK,UAAU,KAAK;EACpD,OAAO;CACT;CAEF,OAAO,SAAS,OAAO,KAAsB,KAA2B;EACtE,CAAM,YAAY;GAChB,IAAI,IAAI,WAAW,QAAQ;IACzB,SAAS,KAAK,KAAK,EAAE,OAAO,qBAAqB,CAAC;IAClD;GACF;GAEA,IAAI,QAAQ,aAAa,IAAI,QAAQ,kBAAkB,UAAU,QAAQ,aAAa;IACpF,SAAS,KAAK,KAAK,EAAE,OAAO,eAAe,CAAC;IAC5C;GACF;GAEA,IAAI;GACJ,IAAI;IACF,OAAO,MAAM,aAAa,GAAG;GAC/B,QAAQ;IACN,SAAS,KAAK,KAAK,EAAE,OAAO,eAAe,CAAC;IAC5C;GACF;GAEA,IAAI,UAAU,KAAK;IACjB,gBAAgB;IAChB,iBAAiB;IACjB,YAAY;IACZ,GAAG;GACL,CAAC;GAED,IAAI;IACF,MAAM,SAAS,WAAW,OAAO,QAAQ,IAAI,GAAG,UAAU,IAAI,CAAC;IAC/D,WAAW,MAAM,SAAS,YAAY,MAAM,GAC1C,IAAI,MAAM,KAAK;GAEnB,SAAS,OAAO;IACd,IAAI,MACF,uBAAuB,KAAK,UAAU,EACpC,SAAS,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK,EAChE,CAAC,EAAE,KACL;GACF,UAAU;IACR,IAAI,IAAI;GACV;EACF,EAAC,CAAE;CACL;AACF;;AAGA,SAAS,aAAa,KAAwD;CAC5E,OAAO,IAAI,SAAS,SAAS,WAAW;EACtC,IAAI,MAAM;EACV,IAAI,GAAG,SAAS,UAA2B;GACzC,OAAO,MAAM,SAAS;EACxB,CAAC;EACD,IAAI,GAAG,aAAa;GAClB,IAAI;IACF,QAAQ,MAAO,KAAK,MAAM,GAAG,IAAgC,CAAC,CAAC;GACjE,SAAS,OAAO;IACd,OAAO,KAAK;GACd;EACF,CAAC;EACD,IAAI,GAAG,SAAS,MAAM;CACxB,CAAC;AACH;AAEA,SAAS,SAAS,KAAqB,QAAgB,MAAqB;CAC1E,IAAI,UAAU,QAAQ;EAAE,gBAAgB;EAAmC,GAAG;CAAiB,CAAC;CAChG,IAAI,IAAI,KAAK,UAAU,IAAI,CAAC;AAC9B"}
+{"version":3,"file":"serve.mjs","names":[],"sources":["../../../../../../../ai/src/serve/serve.ts"],"sourcesContent":["import type { IncomingMessage, ServerResponse } from \"node:http\";\nimport { streamToSSE, type StreamLike } from \"./stream-to-sse\";\n\n/**\n * Anything `serve` can expose: a primitive whose `stream(input, options)`\n * returns a {@link StreamLike}. Agents, supervisors, and orchestrators all\n * satisfy it.\n */\nexport type ServableExecutable<TInput = unknown> = {\n  stream(input: TInput, options?: Record<string, unknown>): StreamLike<{ type: string }, unknown>;\n};\n\n/** Options for {@link serve}. */\nexport type ServeOptions<TInput = unknown> = {\n  /**\n   * Bearer token required on every request. When set, a request must send\n   * `Authorization: Bearer <token>`, else `401` (S4-style auth, the same\n   * control the dashboard uses — fold this in for a production deploy).\n   */\n  authToken?: string;\n  /**\n   * Map the parsed JSON request body to the executable's input. Default:\n   * `body.input`. Override to accept a different request shape.\n   */\n  toInput?: (body: Record<string, unknown>) => TInput;\n  /**\n   * Map the parsed body to per-call stream options (e.g. an orchestrator\n   * `{ sessionId, history }` so a turn resumes the right session — A3\n   * wiring). Default: pass `sessionId` / `history` straight through.\n   */\n  toOptions?: (body: Record<string, unknown>) => Record<string, unknown>;\n};\n\nconst SECURITY_HEADERS: Record<string, string> = {\n  \"x-content-type-options\": \"nosniff\",\n  \"x-frame-options\": \"DENY\",\n  \"referrer-policy\": \"no-referrer\",\n};\n\n/**\n * Turn an executable into a `node:http` request handler that streams its\n * run to the client as Server-Sent Events (A3) — the production-serving\n * primitive. POST a JSON body (`{ input, sessionId?, history? }`); the\n * response is an `text/event-stream` of the primitive's events, the final\n * `result`, then `[DONE]`. Absorbs the auth-token control; pair with a\n * `sessionLock` + an orchestrator for durable multi-turn serving.\n *\n * @example\n * import { createServer } from \"node:http\";\n * createServer(ai.serve(myAgent, { authToken: process.env.TOKEN })).listen(8787);\n */\nexport function serve<TInput = unknown>(\n  executable: ServableExecutable<TInput>,\n  options: ServeOptions<TInput> = {},\n): (req: IncomingMessage, res: ServerResponse) => void {\n  const toInput = options.toInput ?? ((body) => body.input as TInput);\n  const toOptions =\n    options.toOptions ??\n    ((body) => {\n      const opts: Record<string, unknown> = {};\n      if (body.sessionId !== undefined) opts.sessionId = body.sessionId;\n      if (body.history !== undefined) opts.history = body.history;\n      return opts;\n    });\n\n  return function handle(req: IncomingMessage, res: ServerResponse): void {\n    void (async () => {\n      if (req.method !== \"POST\") {\n        sendJson(res, 405, { error: \"method_not_allowed\" });\n        return;\n      }\n\n      if (options.authToken && req.headers.authorization !== `Bearer ${options.authToken}`) {\n        sendJson(res, 401, { error: \"unauthorized\" });\n        return;\n      }\n\n      let body: Record<string, unknown>;\n      try {\n        body = await readJsonBody(req);\n      } catch {\n        sendJson(res, 400, { error: \"invalid_json\" });\n        return;\n      }\n\n      res.writeHead(200, {\n        \"content-type\": \"text/event-stream; charset=utf-8\",\n        \"cache-control\": \"no-cache\",\n        connection: \"keep-alive\",\n        ...SECURITY_HEADERS,\n      });\n\n      try {\n        const stream = executable.stream(toInput(body), toOptions(body));\n        for await (const frame of streamToSSE(stream)) {\n          res.write(frame);\n        }\n      } catch (error) {\n        res.write(\n          `event: error\\ndata: ${JSON.stringify({\n            message: error instanceof Error ? error.message : String(error),\n          })}\\n\\n`,\n        );\n      } finally {\n        res.end();\n      }\n    })();\n  };\n}\n\n/** Read and JSON-parse a request body. */\nfunction readJsonBody(req: IncomingMessage): Promise<Record<string, unknown>> {\n  return new Promise((resolve, reject) => {\n    let raw = \"\";\n    req.on(\"data\", (chunk: Buffer | string) => {\n      raw += chunk.toString();\n    });\n    req.on(\"end\", () => {\n      try {\n        resolve(raw ? (JSON.parse(raw) as Record<string, unknown>) : {});\n      } catch (error) {\n        reject(error);\n      }\n    });\n    req.on(\"error\", reject);\n  });\n}\n\nfunction sendJson(res: ServerResponse, status: number, body: unknown): void {\n  res.writeHead(status, { \"content-type\": \"application/json; charset=utf-8\", ...SECURITY_HEADERS });\n  res.end(JSON.stringify(body));\n}\n"],"mappings":";;;AAiCA,MAAM,mBAA2C;CAC/C,0BAA0B;CAC1B,mBAAmB;CACnB,mBAAmB;AACrB;;;;;;;;;;;;;AAcA,SAAgB,MACd,YACA,UAAgC,CAAC,GACoB;CACrD,MAAM,UAAU,QAAQ,aAAa,SAAS,KAAK;CACnD,MAAM,YACJ,QAAQ,eACN,SAAS;EACT,MAAM,OAAgC,CAAC;EACvC,IAAI,KAAK,cAAc,QAAW,KAAK,YAAY,KAAK;EACxD,IAAI,KAAK,YAAY,QAAW,KAAK,UAAU,KAAK;EACpD,OAAO;CACT;CAEF,OAAO,SAAS,OAAO,KAAsB,KAA2B;EACtE,CAAM,YAAY;GAChB,IAAI,IAAI,WAAW,QAAQ;IACzB,SAAS,KAAK,KAAK,EAAE,OAAO,qBAAqB,CAAC;IAClD;GACF;GAEA,IAAI,QAAQ,aAAa,IAAI,QAAQ,kBAAkB,UAAU,QAAQ,aAAa;IACpF,SAAS,KAAK,KAAK,EAAE,OAAO,eAAe,CAAC;IAC5C;GACF;GAEA,IAAI;GACJ,IAAI;IACF,OAAO,MAAM,aAAa,GAAG;GAC/B,QAAQ;IACN,SAAS,KAAK,KAAK,EAAE,OAAO,eAAe,CAAC;IAC5C;GACF;GAEA,IAAI,UAAU,KAAK;IACjB,gBAAgB;IAChB,iBAAiB;IACjB,YAAY;IACZ,GAAG;GACL,CAAC;GAED,IAAI;IACF,MAAM,SAAS,WAAW,OAAO,QAAQ,IAAI,GAAG,UAAU,IAAI,CAAC;IAC/D,WAAW,MAAM,SAAS,YAAY,MAAM,GAC1C,IAAI,MAAM,KAAK;GAEnB,SAAS,OAAO;IACd,IAAI,MACF,uBAAuB,KAAK,UAAU,EACpC,SAAS,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK,EAChE,CAAC,EAAE,KACL;GACF,UAAU;IACR,IAAI,IAAI;GACV;EACF,GAAG;CACL;AACF;;AAGA,SAAS,aAAa,KAAwD;CAC5E,OAAO,IAAI,SAAS,SAAS,WAAW;EACtC,IAAI,MAAM;EACV,IAAI,GAAG,SAAS,UAA2B;GACzC,OAAO,MAAM,SAAS;EACxB,CAAC;EACD,IAAI,GAAG,aAAa;GAClB,IAAI;IACF,QAAQ,MAAO,KAAK,MAAM,GAAG,IAAgC,CAAC,CAAC;GACjE,SAAS,OAAO;IACd,OAAO,KAAK;GACd;EACF,CAAC;EACD,IAAI,GAAG,SAAS,MAAM;CACxB,CAAC;AACH;AAEA,SAAS,SAAS,KAAqB,QAAgB,MAAqB;CAC1E,IAAI,UAAU,QAAQ;EAAE,gBAAgB;EAAmC,GAAG;CAAiB,CAAC;CAChG,IAAI,IAAI,KAAK,UAAU,IAAI,CAAC;AAC9B"}

package/esm/serve/stream-to-sse.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"stream-to-sse.d.mts","names":[],"sources":["../../../../../../../ai/src/serve/stream-to-sse.ts"],"mappings":";;AAOA;;;;KAAY,UAAA;EAA4B,IAAA;AAAA,cACtC,aAAA,CAAc,MAAA;EAAY,MAAA,GAAS,OAAA,CAAQ,OAAA;AAAA;;;;;;;;;;AAAO;AAcpD;;iBAAuB,WAAA;EAA6B,IAAA;AAAA,YAClD,MAAA,EAAQ,UAAA,CAAW,MAAA,EAAQ,OAAA,IAC1B,aAAA"}
+{"version":3,"file":"stream-to-sse.d.mts","names":[],"sources":["../../../../../../../ai/src/serve/stream-to-sse.ts"],"mappings":";;AAOA;;;;KAAY,UAAA;EAA4B,IAAA;AAAA,cACtC,aAAA,CAAc,MAAA;EAAY,MAAA,GAAS,OAAA,CAAQ,OAAA;AAAA;;;;;;;;;;AAAO;AAcpD;;iBAAuB,WAAA;EAA6B,IAAA;AAAA,WAAA,CAClD,MAAA,EAAQ,UAAA,CAAW,MAAA,EAAQ,OAAA,IAC1B,aAAA"}