@absolutejs/rag-postgres 0.0.5 → 0.0.6

package/dist/index.js

@@ -1,622 +1,956 @@
 // @bun
-var __require = import.meta.require;
-
 // src/index.ts
+import { createRAGCollection, ragPlugin } from "@absolutejs/rag/adapter-kit";
+
+// src/createPostgresRAGStore.ts
 import {
-  createRAGCollection,
   createRAGVector,
-  normalizeVector
-} from "@absolutejs/rag";
-var ABSOLUTE_POSTGRESQL_RAG_PACKAGE_NAME = "@absolutejs/rag-postgres";
-var POSTGRESQL_RAG_IMPLEMENTATIONS = ["pgvector"];
-var PGVECTOR_DISTANCE_METRICS = [
-  "cosine",
-  "l2",
-  "inner_product"
-];
-var PGVECTOR_INDEX_TYPES = ["none", "hnsw", "ivfflat"];
-var DEFAULT_SCHEMA_NAME = "absolute_rag";
-var DEFAULT_CHUNK_TABLE_NAME = "chunks";
-var DEFAULT_MIGRATION_TABLE_NAME = "migrations";
-var DEFAULT_DIMENSIONS = 1536;
-var IDENTIFIER_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
-var assertIdentifier = (value, label) => {
-  if (typeof value !== "string" || !IDENTIFIER_RE.test(value)) {
-    throw new Error(`${ABSOLUTE_POSTGRESQL_RAG_PACKAGE_NAME}: invalid ${label} "${String(value)}"`);
-  }
-};
-var quoteIdentifier = (value) => {
-  assertIdentifier(value, "identifier");
-  return `"${value}"`;
-};
-var qualifiedTable = (schemaName, tableName) => `${quoteIdentifier(schemaName)}.${quoteIdentifier(tableName)}`;
-var escapeLiteral = (value) => value.replace(/'/g, "''");
-var vectorLiteral = (vector) => {
-  if (!Array.isArray(vector) || vector.length === 0) {
-    throw new Error(`${ABSOLUTE_POSTGRESQL_RAG_PACKAGE_NAME}: vector values must be a non-empty array`);
-  }
-  return `[${vector.map((value) => {
-    if (typeof value !== "number" || !Number.isFinite(value)) {
-      throw new Error(`${ABSOLUTE_POSTGRESQL_RAG_PACKAGE_NAME}: vector values must be finite numbers`);
+  matchesMetadataFilterRecord,
+  normalizeVector,
+  planNativeCandidateSearchBackfillK,
+  planNativeCandidateSearchK,
+  RAG_NATIVE_QUERY_CANDIDATE_LIMIT,
+  RAG_VECTOR_DIMENSIONS_DEFAULT,
+  rankRAGLexicalMatches,
+  resolveAdaptiveNativeCandidateLimit,
+  summarizeSQLiteCandidateCoverage
+} from "@absolutejs/rag/adapter-kit";
+var DEFAULT_DIMENSIONS = RAG_VECTOR_DIMENSIONS_DEFAULT;
+var DEFAULT_TABLE_NAME = "rag_chunks";
+var DEFAULT_SCHEMA_NAME = "public";
+var DEFAULT_QUERY_MULTIPLIER = 4;
+var MAX_QUERY_MULTIPLIER = 16;
+var DEFAULT_POSTGRES_INDEX_TYPE = "hnsw";
+var DEFAULT_POSTGRES_IVFFLAT_LISTS = 100;
+var DEFAULT_POSTGRES_HNSW_M = 16;
+var DEFAULT_POSTGRES_HNSW_EF_CONSTRUCTION = 64;
+var IDENTIFIER_RE = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+var FILTER_PATH_SEGMENT_RE = /^[a-zA-Z0-9_]+$/;
+var isObjectFilterRecord = (value) => Boolean(value) && typeof value === "object" && !Array.isArray(value);
+var isNestedFilterArray = (value) => Array.isArray(value) && value.every((entry) => isObjectFilterRecord(entry));
+var isOperatorFilterRecord = (value) => isObjectFilterRecord(value) && Object.keys(value).some((key) => key.startsWith("$"));
+var countFilterClauses = (filter) => {
+  if (!filter) {
+    return 0;
+  }
+  let count = 0;
+  for (const [key, value] of Object.entries(filter)) {
+    if (key === "$and" || key === "$or") {
+      if (isNestedFilterArray(value)) {
+        count += value.reduce((total, entry) => total + countFilterClauses(entry), 0);
+      }
+      continue;
     }
-    return String(value);
-  }).join(",")}]`;
-};
-var makePlaceholder = (params, value, cast = "") => {
-  params.push(value);
-  const suffix = cast ? `::${cast}` : "";
-  return `$${params.length}${suffix}`;
-};
-var normalizeMetric = (metric) => {
-  if (metric === "l2" || metric === "inner_product") {
-    return metric;
+    if (key === "$not") {
+      if (isObjectFilterRecord(value)) {
+        count += countFilterClauses(value);
+      }
+      continue;
+    }
+    count += 1;
   }
-  return "cosine";
+  return count;
 };
-var normalizeIndex = (index) => {
-  if (!index || index.type === undefined) {
-    return { type: "none" };
+var toPostgresJsonPath = (key) => {
+  const segments = key.split(".").filter(Boolean);
+  if (segments.length === 0 || !segments.every((segment) => FILTER_PATH_SEGMENT_RE.test(segment))) {
+    return null;
   }
-  if (index.type === "hnsw" || index.type === "ivfflat" || index.type === "none") {
-    return index;
+  return segments;
+};
+var toPostgresFilterBinding = (value) => {
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean" || value === null) {
+    return value;
   }
-  throw new Error(`${ABSOLUTE_POSTGRESQL_RAG_PACKAGE_NAME}: unsupported pgvector index type "${String(index.type)}"`);
+  return;
 };
-var resolveSchemaConfig = (options) => {
-  const schemaName = options.schema?.schemaName ?? DEFAULT_SCHEMA_NAME;
-  const chunkTableName = options.schema?.chunkTableName ?? DEFAULT_CHUNK_TABLE_NAME;
-  const migrationTableName = options.schema?.migrationTableName ?? DEFAULT_MIGRATION_TABLE_NAME;
-  assertIdentifier(schemaName, "schema name");
-  assertIdentifier(chunkTableName, "chunk table name");
-  assertIdentifier(migrationTableName, "migration table name");
-  return {
-    schemaName,
-    chunkTableName,
-    migrationTableName
-  };
+var buildPostgresJsonbScalarEquality = (input) => {
+  const comparison = input.comparison ?? "=";
+  return comparison === "=" ? `jsonb_typeof(${input.valueSql}) = 'null'` : `coalesce(jsonb_typeof(${input.valueSql}), 'missing') <> 'null'`;
 };
-var resolveVectorConfig = (options) => {
-  const vector = options?.vector;
-  if (!vector || vector.provider !== "pgvector") {
-    throw new Error(`${ABSOLUTE_POSTGRESQL_RAG_PACKAGE_NAME}: PostgreSQL RAG currently requires vector.provider = "pgvector"`);
-  }
-  const dimensions = vector.dimensions ?? DEFAULT_DIMENSIONS;
-  if (!Number.isInteger(dimensions) || dimensions <= 0) {
-    throw new Error(`${ABSOLUTE_POSTGRESQL_RAG_PACKAGE_NAME}: dimensions must be a positive integer`);
+var buildPostgresMetadataScalarEquality = (input) => input.value === null ? buildPostgresJsonbScalarEquality({
+  comparison: input.comparison,
+  valueSql: input.valueSql
+}) : `${input.actualSql} ${input.comparison ?? "="} ${input.bind(String(input.value))}`;
+var buildPostgresFilterPlan = (filter, startIndex = 0) => {
+  if (!filter) {
+    return { clause: "", params: [] };
   }
-  const distanceMetric = normalizeMetric(vector.distanceMetric);
-  const index = normalizeIndex(vector.index);
-  return {
-    ...vector,
-    dimensions,
-    distanceMetric,
-    extensionName: vector.extensionName ?? "vector",
-    index
+  const params = [];
+  const bind = (value) => {
+    params.push(value);
+    return `$${params.length + startIndex}`;
   };
-};
-var operatorForMetric = (distanceMetric) => {
-  switch (distanceMetric) {
-    case "l2":
-      return "<->";
-    case "inner_product":
-      return "<#>";
-    case "cosine":
-    default:
-      return "<=>";
-  }
-};
-var operatorClassForMetric = (distanceMetric) => {
-  switch (distanceMetric) {
-    case "l2":
-      return "vector_l2_ops";
-    case "inner_product":
-      return "vector_ip_ops";
-    case "cosine":
-    default:
-      return "vector_cosine_ops";
-  }
-};
-var scoreFromDistance = (distance, distanceMetric) => {
-  if (typeof distance !== "number" || !Number.isFinite(distance)) {
-    return 0;
-  }
-  switch (distanceMetric) {
-    case "inner_product":
-      return -distance;
-    case "l2":
-      return 1 / (1 + Math.abs(distance));
-    case "cosine":
-    default:
-      return 1 - distance;
-  }
-};
-var createIndexSql = ({
-  schemaName,
-  chunkTableName,
-  distanceMetric,
-  index
-}) => {
-  if (!index || index.type === "none") {
-    return [];
-  }
-  const qualifiedChunkTable = qualifiedTable(schemaName, chunkTableName);
-  const opClass = operatorClassForMetric(distanceMetric);
-  const indexName = `${chunkTableName}_embedding_${index.type}_${distanceMetric}_idx`;
-  const withParts = [];
-  if (index.type === "hnsw") {
-    if (Number.isInteger(index.m) && (index.m ?? 0) > 0) {
-      withParts.push(`m = ${index.m}`);
-    }
-    if (Number.isInteger(index.efConstruction) && (index.efConstruction ?? 0) > 0) {
-      withParts.push(`ef_construction = ${index.efConstruction}`);
+  const build = (entry) => {
+    const clauses = [];
+    for (const [key, value] of Object.entries(entry)) {
+      if (key === "$and" || key === "$or") {
+        if (!isNestedFilterArray(value) || value.length === 0) {
+          return null;
+        }
+        const nested = value.map((item) => build(item));
+        if (nested.some((item) => item === null)) {
+          return null;
+        }
+        clauses.push(`(${nested.filter((item) => Boolean(item)).join(key === "$and" ? " AND " : " OR ")})`);
+        continue;
+      }
+      if (key === "$not") {
+        if (!isObjectFilterRecord(value)) {
+          return null;
+        }
+        const nested = build(value);
+        if (!nested) {
+          return null;
+        }
+        clauses.push(`NOT (${nested})`);
+        continue;
+      }
+      const isScalarField = key === "chunkId" || key === "source" || key === "title";
+      const jsonPath = isScalarField ? null : toPostgresJsonPath(key);
+      if (!isScalarField && !jsonPath) {
+        return null;
+      }
+      let actualSql;
+      let metadataPathSegments = [];
+      let metadataValueSql;
+      if (isScalarField) {
+        actualSql = key === "chunkId" ? "chunk_id" : key;
+      } else {
+        metadataPathSegments = jsonPath ?? [];
+        actualSql = `jsonb_extract_path_text(metadata, ${metadataPathSegments.map((segment) => `'${segment}'`).join(", ")})`;
+        metadataValueSql = `metadata #> '{${metadataPathSegments.join(",")}}'`;
+      }
+      if (!isOperatorFilterRecord(value)) {
+        const binding = toPostgresFilterBinding(value);
+        if (binding === undefined) {
+          return null;
+        }
+        clauses.push(isScalarField ? `${actualSql} = ${bind(String(binding))}` : buildPostgresMetadataScalarEquality({
+          actualSql,
+          bind,
+          value: binding,
+          valueSql: metadataValueSql
+        }));
+        continue;
+      }
+      const operatorClauses = Object.entries(value).map(([operator, expected]) => {
+        switch (operator) {
+          case "$exists":
+            return isScalarField ? expected ? `${actualSql} IS NOT NULL` : `${actualSql} IS NULL` : expected ? `${metadataValueSql} IS NOT NULL` : `${metadataValueSql} IS NULL`;
+          case "$in": {
+            if (!Array.isArray(expected) || expected.length === 0) {
+              return null;
+            }
+            const bindings = expected.map((entry2) => toPostgresFilterBinding(entry2)).filter((entry2) => entry2 !== undefined);
+            if (bindings.length !== expected.length) {
+              return null;
+            }
+            return isScalarField ? `${actualSql} IN (${bindings.map((entry2) => bind(String(entry2))).join(", ")})` : `(${bindings.map((entry2) => buildPostgresMetadataScalarEquality({
+              actualSql,
+              bind,
+              value: entry2,
+              valueSql: metadataValueSql
+            })).join(" OR ")})`;
+          }
+          case "$ne": {
+            const binding = toPostgresFilterBinding(expected);
+            return binding === undefined ? null : isScalarField ? `${actualSql} <> ${bind(String(binding))}` : buildPostgresMetadataScalarEquality({
+              actualSql,
+              bind,
+              comparison: "<>",
+              value: binding,
+              valueSql: metadataValueSql
+            });
+          }
+          case "$gt":
+          case "$gte":
+          case "$lt":
+          case "$lte": {
+            if (typeof expected !== "number" || !Number.isFinite(expected)) {
+              return null;
+            }
+            const comparison = operator === "$gt" ? ">" : operator === "$gte" ? ">=" : operator === "$lt" ? "<" : "<=";
+            return `((${actualSql}) ~ '^-?[0-9]+(\\.[0-9]+)?$' AND (${actualSql})::double precision ${comparison} ${bind(expected)})`;
+          }
+          case "$contains":
+            if (isScalarField) {
+              return null;
+            }
+            if (toPostgresFilterBinding(expected) === undefined) {
+              return null;
+            }
+            return `(${metadataValueSql} IS NOT NULL AND ${metadataValueSql} ? ${bind(String(expected))})`;
+          case "$containsAny":
+          case "$containsAll": {
+            if (isScalarField || !Array.isArray(expected)) {
+              return null;
+            }
+            const values = expected.map((entry2) => toPostgresFilterBinding(entry2)).filter((entry2) => entry2 !== undefined);
+            if (values.length === 0 || values.length !== expected.length) {
+              return null;
+            }
+            const sqlArray = `ARRAY[${values.map((value2) => bind(String(value2))).join(", ")}]::text[]`;
+            return `(${metadataValueSql} IS NOT NULL AND ${metadataValueSql} ${operator === "$containsAny" ? "?|" : "?&"} ${sqlArray})`;
+          }
+          default:
+            return null;
+        }
+      });
+      if (operatorClauses.some((clause2) => clause2 === null)) {
+        return null;
+      }
+      clauses.push(operatorClauses.filter((clause2) => Boolean(clause2)).map((clause2) => `(${clause2})`).join(" AND "));
     }
-  }
-  if (index.type === "ivfflat" && Number.isInteger(index.lists) && (index.lists ?? 0) > 0) {
-    withParts.push(`lists = ${index.lists}`);
-  }
-  const withClause = withParts.length > 0 ? ` WITH (${withParts.join(", ")})` : "";
-  return [
-    `CREATE INDEX IF NOT EXISTS ${quoteIdentifier(indexName)} ON ${qualifiedChunkTable} USING ${index.type} (embedding ${opClass})${withClause}`
-  ];
+    return clauses.length > 0 ? clauses.map((clause2) => `(${clause2})`).join(" AND ") : "";
+  };
+  const clause = build(filter);
+  return clause === null || clause.trim().length === 0 ? null : { clause, params };
 };
-var createQuerySessionSql = ({
-  index
-}) => {
-  if (!index || index.type === "none") {
-    return [];
+var buildPostgresPushdownFilter = (filter) => {
+  if (!filter) {
+    return;
   }
-  const sql = [];
-  if (index.type === "hnsw") {
-    if (Number.isInteger(index.efSearch) && (index.efSearch ?? 0) > 0) {
-      sql.push(`SET LOCAL hnsw.ef_search = ${index.efSearch}`);
+  const hasPushdownFilterPlan = (entry) => {
+    const plan = buildPostgresFilterPlan(entry);
+    return plan !== null && Boolean(plan.clause) && plan.clause.trim().length > 0;
+  };
+  const hasPushdownFilterPlanEntry = (entry) => {
+    if (!isObjectFilterRecord(entry)) {
+      return false;
     }
-    if (index.iterativeScan && index.iterativeScan !== "off") {
-      sql.push(`SET LOCAL hnsw.iterative_scan = '${escapeLiteral(index.iterativeScan)}'`);
+    return hasPushdownFilterPlan(entry);
+  };
+  const nextEntries = [];
+  for (const [key, value] of Object.entries(filter)) {
+    if (key === "$and" || key === "$or") {
+      if (!isNestedFilterArray(value)) {
+        continue;
+      }
+      const nested = value.map((entry) => buildPostgresPushdownFilter(entry)).filter((entry) => hasPushdownFilterPlanEntry(entry));
+      if (nested.length > 0) {
+        nextEntries.push([key, nested]);
+      }
+      continue;
     }
-  }
-  if (index.type === "ivfflat") {
-    if (Number.isInteger(index.probes) && (index.probes ?? 0) > 0) {
-      sql.push(`SET LOCAL ivfflat.probes = ${index.probes}`);
+    if (key === "$not") {
+      if (!isObjectFilterRecord(value)) {
+        continue;
+      }
+      const nested = buildPostgresPushdownFilter(value);
+      if (hasPushdownFilterPlanEntry(nested)) {
+        nextEntries.push([key, nested]);
+      }
+      continue;
     }
-    if (Number.isInteger(index.maxProbes) && (index.maxProbes ?? 0) > 0) {
-      sql.push(`SET LOCAL ivfflat.max_probes = ${index.maxProbes}`);
+    if (Array.isArray(value) || isOperatorFilterRecord(value) && Object.keys(value).some((operator) => !(operator === "$exists" || operator === "$in" || operator === "$contains" || operator === "$containsAny" || operator === "$containsAll" || operator === "$ne" || operator === "$gt" || operator === "$gte" || operator === "$lt" || operator === "$lte"))) {
+      continue;
     }
-    if (index.iterativeScan && index.iterativeScan !== "off") {
-      sql.push(`SET LOCAL ivfflat.iterative_scan = '${escapeLiteral(index.iterativeScan)}'`);
+    const isScalarColumnKey = ["chunkId", "source", "title"].includes(key);
+    const jsonPath = isScalarColumnKey ? null : toPostgresJsonPath(key);
+    if (!isScalarColumnKey && !jsonPath) {
+      continue;
     }
+    if (!hasPushdownFilterPlan({ [key]: value })) {
+      continue;
+    }
+    nextEntries.push([key, value]);
   }
-  return sql;
-};
-var stageOrder = [
-  "extension",
-  "schema",
-  "table",
-  "index"
-];
-var buildMigrationName = (stage, stageIndex, sql) => {
-  const normalized = sql.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "").slice(0, 48) || "statement";
-  const globalOrder = String(stageOrder.indexOf(stage) + 1).padStart(2, "0");
-  const localOrder = String(stageIndex + 1).padStart(3, "0");
-  return `${globalOrder}_${stage}_${localOrder}_${normalized}`;
-};
-var createMigrationTableSql = (schemaName, migrationTableName) => `CREATE TABLE IF NOT EXISTS ${qualifiedTable(schemaName, migrationTableName)} (name TEXT PRIMARY KEY, applied_at TIMESTAMPTZ NOT NULL DEFAULT NOW())`;
-var filterTrackedTableSql = (tableSql, schemaName, migrationTableName) => {
-  const migrationTableTarget = qualifiedTable(schemaName, migrationTableName);
-  return tableSql.filter((sql) => !sql.includes(migrationTableTarget));
-};
-var createPostgresSchemaPlan = (options) => {
-  const schema = resolveSchemaConfig(options ?? {});
-  const vector = resolveVectorConfig(options ?? {});
-  const qualifiedChunkTable = qualifiedTable(schema.schemaName, schema.chunkTableName);
-  const qualifiedMigrationTable = qualifiedTable(schema.schemaName, schema.migrationTableName);
-  const extensionSql = vector.autoCreateExtension === false ? [] : [
-    `CREATE EXTENSION IF NOT EXISTS ${quoteIdentifier(vector.extensionName)}`
-  ];
-  const schemaSql = vector.autoCreateSchema === false ? [] : [
-    `CREATE SCHEMA IF NOT EXISTS ${quoteIdentifier(schema.schemaName)}`
-  ];
-  const tableSql = vector.autoCreateTables === false ? [] : [
-    `CREATE TABLE IF NOT EXISTS ${qualifiedChunkTable} (id BIGSERIAL PRIMARY KEY, chunk_id TEXT NOT NULL UNIQUE, text TEXT NOT NULL, title TEXT, source TEXT, metadata JSONB NOT NULL DEFAULT '{}'::jsonb, embedding VECTOR(${vector.dimensions}) NOT NULL, created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW())`,
-    `CREATE INDEX IF NOT EXISTS ${quoteIdentifier(`${schema.chunkTableName}_chunk_id_idx`)} ON ${qualifiedChunkTable} (chunk_id)`,
-    `CREATE INDEX IF NOT EXISTS ${quoteIdentifier(`${schema.chunkTableName}_source_idx`)} ON ${qualifiedChunkTable} (source)`,
-    `CREATE INDEX IF NOT EXISTS ${quoteIdentifier(`${schema.chunkTableName}_metadata_idx`)} ON ${qualifiedChunkTable} USING GIN (metadata)`,
-    createMigrationTableSql(schema.schemaName, schema.migrationTableName)
-  ];
-  const indexSql = vector.autoCreateIndex === false ? [] : createIndexSql({
-    schemaName: schema.schemaName,
-    chunkTableName: schema.chunkTableName,
-    distanceMetric: vector.distanceMetric,
-    index: vector.index
-  });
-  return {
-    implementation: "pgvector",
-    extensionSql,
-    schemaSql,
-    tableSql,
-    indexSql,
-    querySessionSql: createQuerySessionSql({ index: vector.index }),
-    migrationTableQualifiedName: qualifiedMigrationTable
-  };
+  return nextEntries.length > 0 ? Object.fromEntries(nextEntries) : undefined;
 };
-var createPostgresMigrationPlan = (options) => {
-  const schema = resolveSchemaConfig(options ?? {});
-  const schemaPlan = createPostgresSchemaPlan(options ?? {});
-  const bootstrapSql = [];
-  if (schemaPlan.schemaSql.length > 0) {
-    bootstrapSql.push(...schemaPlan.schemaSql);
-  }
-  const migrationTableSql = createMigrationTableSql(schema.schemaName, schema.migrationTableName);
-  if (!bootstrapSql.includes(migrationTableSql)) {
-    bootstrapSql.push(migrationTableSql);
-  }
-  const migrations = [
-    ...schemaPlan.extensionSql.map((sql, index) => ({
-      stage: "extension",
-      sql,
-      stageIndex: index
-    })),
-    ...filterTrackedTableSql(schemaPlan.tableSql, schema.schemaName, schema.migrationTableName).map((sql, index) => ({
-      stage: "table",
-      sql,
-      stageIndex: index
-    })),
-    ...schemaPlan.indexSql.map((sql, index) => ({
-      stage: "index",
-      sql,
-      stageIndex: index
-    }))
-  ].map((entry) => ({
-    name: buildMigrationName(entry.stage, entry.stageIndex, entry.sql),
-    stage: entry.stage,
-    sql: entry.sql
-  }));
+var resolvePostgresPushdownMode = (input) => {
+  const totalFilterClauseCount = countFilterClauses(input.filter);
+  const pushdownClauseCount = countFilterClauses(input.pushdownFilter);
+  const jsRemainderClauseCount = Math.max(0, totalFilterClauseCount - pushdownClauseCount);
+  const pushdownMode = pushdownClauseCount === 0 ? "none" : pushdownClauseCount >= totalFilterClauseCount ? "full" : "partial";
   return {
-    implementation: schemaPlan.implementation,
-    schemaName: schema.schemaName,
-    migrationTableName: schema.migrationTableName,
-    migrationTableQualifiedName: qualifiedTable(schema.schemaName, schema.migrationTableName),
-    bootstrapSql,
-    migrations,
-    schemaPlan
+    jsRemainderClauseCount,
+    jsRemainderRatio: totalFilterClauseCount > 0 ? jsRemainderClauseCount / totalFilterClauseCount : undefined,
+    pushdownClauseCount,
+    pushdownCoverageRatio: totalFilterClauseCount > 0 ? pushdownClauseCount / totalFilterClauseCount : undefined,
+    pushdownMode,
+    totalFilterClauseCount
   };
 };
-var createWrappedPostgresClient = (sql, rootSql = sql) => ({
-  query: async (queryText, params = []) => {
-    const rows = await sql.unsafe(queryText, params);
-    return {
-      rows,
-      rowCount: typeof rows.count === "number" ? rows.count : rows.length
-    };
-  },
-  transaction: async (run) => rootSql.begin(async (transactionSql) => run(createWrappedPostgresClient(transactionSql, transactionSql))),
-  close: async () => {
-    if (typeof rootSql.end === "function") {
-      await rootSql.end({ timeout: 5 });
-    }
+var assertSupportedIdentifier = (name) => {
+  if (!IDENTIFIER_RE.test(name)) {
+    throw new Error(`Invalid identifier "${name}". Only alphanumeric and underscore names are allowed.`);
   }
-});
-var createDefaultPostgresClientFactory = (options) => {
-  const connectionString = typeof options.connectionString === "string" ? options.connectionString.trim() : "";
-  if (connectionString.length === 0) {
-    return;
-  }
-  let clientPromise;
-  return async () => {
-    if (!clientPromise) {
-      clientPromise = (async () => {
-        const postgresModule = await import("postgres");
-        const postgres = postgresModule.default;
-        const sql = postgres(connectionString, {
-          onnotice: () => {},
-          ...options.driver ?? {}
-        });
-        return createWrappedPostgresClient(sql, sql);
-      })();
-    }
-    return clientPromise;
-  };
 };
-var resolveClientFactory = (options) => {
-  if (typeof options.clientFactory === "function") {
-    const { clientFactory } = options;
-    return async () => clientFactory();
+var normalizePostgresIndexType = (value) => {
+  if (value === undefined) {
+    return DEFAULT_POSTGRES_INDEX_TYPE;
   }
-  if (options.client) {
-    const { client } = options;
-    return async () => client;
+  if (value === "none" || value === "hnsw" || value === "ivfflat") {
+    return value;
   }
-  const defaultFactory = createDefaultPostgresClientFactory(options);
-  if (defaultFactory) {
-    return defaultFactory;
+  throw new Error(`Invalid postgres index type "${String(value)}". Expected "none", "hnsw", or "ivfflat".`);
+};
+var normalizePositiveInteger = (value, fallback) => {
+  if (value === undefined || !Number.isFinite(value)) {
+    return fallback;
   }
-  return async () => {
-    throw new Error(`${ABSOLUTE_POSTGRESQL_RAG_PACKAGE_NAME}: createPostgresRAG requires connectionString, client, or clientFactory.`);
-  };
+  return Math.max(1, Math.floor(value));
 };
-var buildMetadataFilter = (filter) => {
-  if (!filter) {
+var getPostgresIndexOperatorClass = (metric) => metric === "cosine" ? "vector_cosine_ops" : metric === "inner_product" ? "vector_ip_ops" : "vector_l2_ops";
+var getPostgresIndexName = (qualifiedTableName, indexType) => indexType === "none" ? undefined : `${qualifiedTableName.replace(".", "_")}_embedding_${indexType}_idx`;
+var buildPostgresIndexSql = (input) => {
+  if (input.indexType === "none") {
     return;
   }
-  const metadataEntries = Object.entries(filter).filter(([key]) => key !== "chunkId" && key !== "title" && key !== "source");
-  if (metadataEntries.length === 0) {
-    return;
+  const opclass = getPostgresIndexOperatorClass(input.distanceMetric);
+  const indexName = getPostgresIndexName(input.qualifiedTableName, input.indexType);
+  const optionsSql = input.indexType === "hnsw" ? ` with (m = ${input.hnswM}, ef_construction = ${input.hnswEfConstruction})` : ` with (lists = ${input.indexLists})`;
+  const createPrefix = input.ifNotExists === false ? "create index" : "create index if not exists";
+  return `${createPrefix} ${indexName} on ${input.qualifiedTableName} using ${input.indexType} (embedding ${opclass})${optionsSql}`;
+};
+var normalizeQueryMultiplier = (value) => {
+  if (value === undefined || !Number.isFinite(value)) {
+    return DEFAULT_QUERY_MULTIPLIER;
   }
-  return Object.fromEntries(metadataEntries);
+  return Math.min(MAX_QUERY_MULTIPLIER, Math.max(1, Math.floor(value)));
 };
-var parseMetadataValue = (value) => {
-  if (value === null || value === undefined) {
+var normalizeMaxBackfills = (value) => {
+  if (value === undefined || !Number.isFinite(value)) {
     return;
   }
+  return Math.max(0, Math.floor(value));
+};
+var normalizeMinResults = (value, topK) => {
+  if (value === undefined || !Number.isFinite(value)) {
+    return topK;
+  }
+  return Math.min(topK, Math.max(1, Math.floor(value)));
+};
+var resolveFillTarget = (input) => {
+  const fillPolicy = input.fillPolicy ?? "satisfy_min_results";
+  return {
+    fillPolicy,
+    targetResults: fillPolicy === "strict_topk" ? input.topK : input.minResults
+  };
+};
+var toQualifiedTableName = (schemaName, tableName) => `${schemaName}.${tableName}`;
+var toVectorLiteral = (vector) => `[${vector.join(",")}]`;
+var parseMetadata = (value) => {
   if (typeof value === "string") {
     try {
       const parsed = JSON.parse(value);
-      if (parsed && typeof parsed === "object") {
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
         return parsed;
       }
     } catch {
       return;
     }
   }
-  if (typeof value === "object") {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return;
+  }
+  return value;
+};
+var parseVectorText = (value) => {
+  if (!value) {
+    return [];
+  }
+  const normalized = value.trim();
+  const wrapped = normalized.startsWith("[") ? normalized : `[${normalized.replace(/[()]/g, "")}]`;
+  try {
+    const parsed = JSON.parse(wrapped);
+    return Array.isArray(parsed) ? parsed.filter((entry) => typeof entry === "number" && Number.isFinite(entry)) : [];
+  } catch {
+    return [];
+  }
+};
+var parseCountValue = (value) => {
+  if (typeof value === "number" && Number.isFinite(value)) {
     return value;
   }
-  return;
+  if (typeof value === "bigint") {
+    return Number(value);
+  }
+  if (typeof value === "string") {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : 0;
+  }
+  return 0;
 };
-var createPgvectorStoreStatus = ({
-  vector,
-  schema,
-  diagnostics,
-  initialized
-}) => ({
-  backend: "postgres",
-  vectorMode: "native_pgvector",
-  dimensions: vector.dimensions,
-  native: {
-    requested: true,
-    available: initialized && !diagnostics.lastInitError,
-    active: initialized && !diagnostics.lastInitError,
-    mode: "pgvector",
-    extensionName: vector.extensionName,
-    schemaName: schema.schemaName,
-    tableName: schema.chunkTableName,
-    distanceMetric: vector.distanceMetric,
-    indexType: vector.index.type,
-    fallbackReason: diagnostics.fallbackReason,
-    lastInitError: diagnostics.lastInitError,
-    lastQueryError: diagnostics.lastQueryError,
-    lastUpsertError: diagnostics.lastUpsertError,
-    lastMigrationError: diagnostics.lastMigrationError
+var parseBooleanValue = (value) => {
+  if (typeof value === "boolean") {
+    return value;
   }
-});
-var getAppliedMigrationNames = async (client, migrationPlan) => {
-  const result = await client.query(`SELECT name FROM ${migrationPlan.migrationTableQualifiedName} ORDER BY name ASC`);
-  return new Set(result.rows.map((row) => String(row.name)));
-};
-var insertAppliedMigration = async (client, migrationPlan, name) => {
-  await client.query(`INSERT INTO ${migrationPlan.migrationTableQualifiedName} (name) VALUES ($1) ON CONFLICT (name) DO NOTHING`, [name]);
-};
-var executeMigrationSequence = async (client, migrationPlan, migrations) => {
-  const appliedNames = [];
-  for (const migration of migrations) {
-    await client.query(migration.sql);
-    await insertAppliedMigration(client, migrationPlan, migration.name);
-    appliedNames.push(migration.name);
-  }
-  return appliedNames;
-};
-var applyPostgresMigrations = async (options, applyOptions = {}) => {
-  const migrationPlan = createPostgresMigrationPlan(options ?? {});
-  const injectedClient = applyOptions.client;
-  const getClient = injectedClient ? async () => injectedClient : resolveClientFactory(options ?? {});
-  const client = await getClient();
-  for (const sql of migrationPlan.bootstrapSql) {
-    await client.query(sql);
-  }
-  const alreadyApplied = await getAppliedMigrationNames(client, migrationPlan);
-  const pendingMigrations = migrationPlan.migrations.filter((migration) => !alreadyApplied.has(migration.name));
-  const skippedNames = migrationPlan.migrations.filter((migration) => alreadyApplied.has(migration.name)).map((migration) => migration.name);
-  if (applyOptions.dryRun === true) {
-    return {
-      migrationPlan,
-      appliedNames: [],
-      skippedNames,
-      pendingNames: pendingMigrations.map((migration) => migration.name),
-      appliedCount: 0,
-      pendingCount: pendingMigrations.length,
-      dryRun: true
-    };
+  if (typeof value === "number") {
+    return value !== 0;
   }
-  const run = async (activeClient) => {
-    const names = await executeMigrationSequence(activeClient, migrationPlan, pendingMigrations);
-    return {
-      migrationPlan,
-      appliedNames: names,
-      skippedNames,
-      pendingNames: pendingMigrations.map((migration) => migration.name),
-      appliedCount: names.length,
-      pendingCount: pendingMigrations.length,
-      dryRun: false
-    };
-  };
-  if (typeof client.transaction === "function" && pendingMigrations.length > 0) {
-    return client.transaction(async (transactionClient) => run(transactionClient));
-  }
-  return run(client);
-};
-var applyPostgresSchemaPlan = applyPostgresMigrations;
-var createPgvectorStore = (options) => {
-  const vector = resolveVectorConfig(options ?? {});
-  const schema = resolveSchemaConfig(options ?? {});
-  const plan = createPostgresSchemaPlan(options ?? {});
-  const getClient = resolveClientFactory(options ?? {});
-  const diagnostics = {
-    fallbackReason: undefined,
-    lastInitError: undefined,
-    lastQueryError: undefined,
-    lastUpsertError: undefined,
-    lastMigrationError: undefined
-  };
-  let initialized = false;
-  let initPromise;
-  const ensureInitialized = async () => {
-    if (initialized) {
-      return;
+  if (typeof value === "bigint") {
+    return value !== 0n;
+  }
+  if (typeof value === "string") {
+    const normalized = value.trim().toLowerCase();
+    return normalized === "true" || normalized === "t" || normalized === "1";
+  }
+  return false;
+};
+var refreshPostgresRuntimeDiagnostics = async (db, nativeDiagnostics, input) => {
+  try {
+    const rows = await db.unsafe(`select
+				c.reltuples::bigint as estimated_row_count,
+				pg_relation_size($1::regclass) as table_bytes,
+				pg_indexes_size($1::regclass) as index_bytes,
+				pg_total_relation_size($1::regclass) as total_bytes,
+				exists(
+					select 1
+					from pg_indexes
+					where schemaname = $2
+					  and tablename = $3
+					  and indexname = $4
+				) as index_present
+			from pg_class c
+			join pg_namespace n on n.oid = c.relnamespace
+			where n.nspname = $2
+			  and c.relname = $3
+			limit 1`, [
+      input.qualifiedTableName,
+      input.schemaName,
+      input.tableName,
+      input.indexName ?? ""
+    ]);
+    const row = rows[0];
+    nativeDiagnostics.indexName = input.indexName;
+    nativeDiagnostics.indexPresent = input.indexName ? parseBooleanValue(row?.index_present) : undefined;
+    nativeDiagnostics.estimatedRowCount = parseCountValue(row?.estimated_row_count);
+    nativeDiagnostics.tableBytes = parseCountValue(row?.table_bytes);
+    nativeDiagnostics.indexBytes = parseCountValue(row?.index_bytes);
+    nativeDiagnostics.totalBytes = parseCountValue(row?.total_bytes);
+    nativeDiagnostics.lastHealthCheckAt = Date.now();
+    nativeDiagnostics.lastHealthError = undefined;
+  } catch (error) {
+    nativeDiagnostics.lastHealthCheckAt = Date.now();
+    nativeDiagnostics.lastHealthError = error instanceof Error ? error.message : String(error);
+  }
+};
+var analyzePostgresTable = async (db, nativeDiagnostics, input) => {
+  try {
+    await db.unsafe(`analyze ${input.qualifiedTableName}`);
+    nativeDiagnostics.lastAnalyzeAt = Date.now();
+    nativeDiagnostics.lastAnalyzeError = undefined;
+    await refreshPostgresRuntimeDiagnostics(db, nativeDiagnostics, input);
+  } catch (error) {
+    nativeDiagnostics.lastAnalyzeAt = Date.now();
+    nativeDiagnostics.lastAnalyzeError = error instanceof Error ? error.message : String(error);
+    throw error;
+  }
+};
+var rebuildPostgresNativeIndex = async (db, nativeDiagnostics, input) => {
+  if (!input.indexName || input.indexType === "none") {
+    throw new Error("Postgres native index rebuild is not configured");
+  }
+  try {
+    await db.unsafe(`drop index if exists ${input.indexName}`);
+    await db.unsafe(buildPostgresIndexSql({
+      distanceMetric: input.distanceMetric,
+      hnswEfConstruction: input.hnswEfConstruction,
+      hnswM: input.hnswM,
+      ifNotExists: false,
+      indexLists: input.indexLists,
+      indexType: input.indexType,
+      qualifiedTableName: input.qualifiedTableName
+    }));
+    nativeDiagnostics.lastReindexAt = Date.now();
+    nativeDiagnostics.lastReindexError = undefined;
+    await analyzePostgresTable(db, nativeDiagnostics, input);
+  } catch (error) {
+    nativeDiagnostics.lastReindexAt = Date.now();
+    nativeDiagnostics.lastReindexError = error instanceof Error ? error.message : String(error);
+    throw error;
+  }
+};
+var getPostgresChunkIdsByChunkIds = async (db, qualifiedTableName, chunkIds) => {
+  const normalized = [...new Set(chunkIds)].filter((chunkId) => chunkId.length > 0);
+  if (normalized.length === 0) {
+    return [];
+  }
+  const placeholders = normalized.map((_, index) => `$${index + 1}`).join(", ");
+  const rows = await db.unsafe(`select chunk_id from ${qualifiedTableName} where chunk_id in (${placeholders})`, normalized);
+  return rows.map((row) => row.chunk_id).filter((chunkId) => typeof chunkId === "string");
+};
+var getPostgresCandidateChunkIdsByFilter = async (db, qualifiedTableName, filter) => {
+  if (!filter || Object.keys(filter).length === 0) {
+    return [];
+  }
+  const pushdownFilter = buildPostgresPushdownFilter(filter);
+  const filterPlan = buildPostgresFilterPlan(pushdownFilter);
+  const rowsSql = filterPlan?.clause ? `select chunk_id, text, title, source, metadata from ${qualifiedTableName} where ${filterPlan.clause}` : `select chunk_id, text, title, source, metadata from ${qualifiedTableName}`;
+  const rows = await db.unsafe(rowsSql, filterPlan?.clause ? filterPlan.params ?? [] : []);
+  const chunks = rows.map((row) => mapRowToChunk(row)).filter((chunk) => matchesFilter(chunk, filter));
+  return chunks.map((chunk) => chunk.chunkId);
+};
+var getPostgresCandidateChunkIds = async (db, qualifiedTableName, input) => {
+  const chunkIdSet = new Set;
+  if (input.filter && Object.keys(input.filter).length > 0) {
+    for (const chunkId of await getPostgresCandidateChunkIdsByFilter(db, qualifiedTableName, input.filter)) {
+      chunkIdSet.add(chunkId);
     }
-    if (!initPromise) {
-      initPromise = (async () => {
-        try {
-          const client = await getClient();
-          await applyPostgresMigrations(options ?? {}, { client });
-          initialized = true;
-          diagnostics.lastInitError = undefined;
-          diagnostics.lastMigrationError = undefined;
-          diagnostics.fallbackReason = undefined;
-        } catch (error) {
-          initialized = false;
-          const message = error instanceof Error ? error.message : String(error);
-          diagnostics.lastInitError = message;
-          diagnostics.lastMigrationError = message;
-          diagnostics.fallbackReason = message;
-          throw error;
-        }
-      })();
+  }
+  if (input.chunkIds && input.chunkIds.length > 0) {
+    for (const chunkId of await getPostgresChunkIdsByChunkIds(db, qualifiedTableName, input.chunkIds)) {
+      chunkIdSet.add(chunkId);
     }
-    return initPromise;
+  }
+  return [...chunkIdSet];
+};
+var normalizeDistance = (distance, metric) => {
+  if (!Number.isFinite(distance)) {
+    return 0;
+  }
+  if (metric === "cosine") {
+    return Math.min(1, Math.max(0, 1 - distance));
+  }
+  if (metric === "inner_product") {
+    return Math.max(0, -distance);
+  }
+  return Math.max(0, 1 / (1 + Math.abs(distance)));
+};
+var getDistanceOperator = (metric) => metric === "cosine" ? "<=>" : metric === "inner_product" ? "<#>" : "<->";
+var createPostgresStatus = (dimensions, nativeDiagnostics) => ({
+  backend: "postgres",
+  dimensions,
+  native: nativeDiagnostics,
+  vectorMode: "native_pgvector"
+});
+var createPostgresCapabilities = () => ({
+  backend: "postgres",
+  nativeVectorSearch: true,
+  persistence: "external",
+  serverSideFiltering: true,
+  streamingIngestStatus: false
+});
+var updatePostgresLastQueryPlan = (input) => {
+  const pushdown = resolvePostgresPushdownMode({
+    filter: input.filter,
+    pushdownFilter: input.pushdownFilter
+  });
+  input.nativeDiagnostics.lastQueryPlan = {
+    backfillCount: input.backfillCount,
+    candidateBudgetExhausted: input.candidateBudgetExhausted,
+    candidateCoverage: summarizeSQLiteCandidateCoverage({
+      filteredCandidateCount: input.filteredCandidateCount,
+      returnedCount: input.returnedCount,
+      topK: input.topK
+    }),
+    filteredCandidateCount: input.filteredCandidateCount,
+    finalSearchK: input.finalSearchK,
+    initialSearchK: input.initialSearchK,
+    searchExpansionRatio: typeof input.initialSearchK === "number" && typeof input.finalSearchK === "number" && input.initialSearchK > 0 ? input.finalSearchK / input.initialSearchK : undefined,
+    candidateLimitUsed: input.candidateLimitUsed,
+    maxBackfillsUsed: input.maxBackfillsUsed,
+    minResultsUsed: input.minResultsUsed,
+    fillPolicyUsed: input.fillPolicyUsed,
+    plannerProfileUsed: input.plannerProfileUsed,
+    jsRemainderClauseCount: pushdown.jsRemainderClauseCount,
+    queryMultiplierUsed: input.queryMultiplierUsed,
+    jsRemainderRatio: pushdown.jsRemainderRatio,
+    pushdownApplied: pushdown.pushdownClauseCount > 0,
+    pushdownClauseCount: pushdown.pushdownClauseCount,
+    pushdownCoverageRatio: pushdown.pushdownCoverageRatio,
+    pushdownMode: pushdown.pushdownMode,
+    queryMode: "native_pgvector",
+    candidateYieldRatio: typeof input.returnedCount === "number" && typeof input.finalSearchK === "number" && input.finalSearchK > 0 ? input.returnedCount / input.finalSearchK : undefined,
+    returnedCount: input.returnedCount,
+    backfillLimitReached: input.backfillLimitReached,
+    minResultsSatisfied: input.minResultsSatisfied,
+    topKFillRatio: typeof input.returnedCount === "number" && input.topK > 0 ? input.returnedCount / input.topK : undefined,
+    totalFilterClauseCount: pushdown.totalFilterClauseCount,
+    underfilledTopK: input.underfilledTopK
+  };
+};
+var matchesFilter = (record, filter) => matchesMetadataFilterRecord({
+  chunkId: record.chunkId,
+  metadata: record.metadata,
+  source: record.source,
+  title: record.title,
+  ...record.metadata ?? {}
+}, filter);
+var mapRowToChunk = (row) => ({
+  chunkId: row.chunk_id,
+  metadata: parseMetadata(row.metadata),
+  source: row.source ?? undefined,
+  text: row.text,
+  title: row.title ?? undefined,
+  vector: parseVectorText(row.embedding)
+});
+var ensurePostgresSchema = async (db, input) => {
+  await db.unsafe("create extension if not exists vector");
+  const [schemaName] = input.qualifiedTableName.split(".");
+  if (schemaName) {
+    await db.unsafe(`create schema if not exists ${schemaName}`);
+  }
+  await db.unsafe(`
+		create table if not exists ${input.qualifiedTableName} (
+			chunk_id text primary key,
+			text text not null,
+			title text,
+			source text,
+			metadata jsonb,
+			embedding vector(${input.dimensions}) not null
+		)
+	`);
+  const indexSql = buildPostgresIndexSql(input);
+  if (indexSql) {
+    await db.unsafe(indexSql);
+  }
+};
+var createPostgresRAGStore = (options = {}) => {
+  const dimensions = options.dimensions ?? DEFAULT_DIMENSIONS;
+  const distanceMetric = options.distanceMetric ?? "cosine";
+  const queryMultiplier = normalizeQueryMultiplier(options.queryMultiplier);
+  const indexType = normalizePostgresIndexType(options.indexType);
+  const indexLists = normalizePositiveInteger(options.indexLists, DEFAULT_POSTGRES_IVFFLAT_LISTS);
+  const hnswM = normalizePositiveInteger(options.hnswM, DEFAULT_POSTGRES_HNSW_M);
+  const hnswEfConstruction = normalizePositiveInteger(options.hnswEfConstruction, DEFAULT_POSTGRES_HNSW_EF_CONSTRUCTION);
+  const tableName = options.tableName ?? DEFAULT_TABLE_NAME;
+  const schemaName = options.schemaName ?? DEFAULT_SCHEMA_NAME;
+  assertSupportedIdentifier(tableName);
+  assertSupportedIdentifier(schemaName);
+  const qualifiedTableName = toQualifiedTableName(schemaName, tableName);
+  const indexName = getPostgresIndexName(qualifiedTableName, indexType);
+  const db = options.sql ?? new Bun.SQL(options.connectionString ?? process.env.RAG_POSTGRES_URL ?? process.env.DATABASE_URL ?? "postgres://postgres:postgres@localhost:55433/absolute_rag_demo");
+  const nativeDiagnostics = {
+    active: true,
+    available: true,
+    distanceMetric,
+    extensionName: "vector",
+    indexName,
+    indexType,
+    mode: "pgvector",
+    requested: true,
+    schemaName,
+    tableName
+  };
+  const capabilities = createPostgresCapabilities();
+  const distanceOperator = getDistanceOperator(distanceMetric);
+  let initialized;
+  const init = () => {
+    initialized ??= ensurePostgresSchema(db, {
+      dimensions,
+      distanceMetric,
+      hnswEfConstruction,
+      hnswM,
+      indexLists,
+      indexType,
+      qualifiedTableName
+    }).then(() => refreshPostgresRuntimeDiagnostics(db, nativeDiagnostics, {
+      indexName,
+      qualifiedTableName,
+      schemaName,
+      tableName
+    })).catch((error) => {
+      nativeDiagnostics.active = false;
+      nativeDiagnostics.available = false;
+      nativeDiagnostics.lastInitError = error instanceof Error ? error.message : String(error);
+      nativeDiagnostics.lastMigrationError = error instanceof Error ? error.message : String(error);
+      nativeDiagnostics.fallbackReason = nativeDiagnostics.lastInitError;
+      throw error;
+    });
+    return initialized;
   };
   const embed = async (input) => {
-    if (typeof options.embedding === "function") {
-      const result = await options.embedding(input);
-      return normalizeVector(result);
+    input.model;
+    input.signal;
+    if (options.mockEmbedding) {
+      return options.mockEmbedding(input.text);
     }
-    return normalizeVector([
-      ...createRAGVector(input.text, vector.dimensions)
-    ]);
+    return normalizeVector(createRAGVector(input.text, dimensions));
   };
   const query = async (input) => {
-    await ensureInitialized();
-    const client = await getClient();
-    const params = [];
-    const qualifiedChunkTable = qualifiedTable(schema.schemaName, schema.chunkTableName);
-    const operator = operatorForMetric(vector.distanceMetric);
-    const vectorPlaceholder = makePlaceholder(params, vectorLiteral(normalizeVector(input.queryVector)), "vector");
-    const limitPlaceholder = makePlaceholder(params, input.topK);
-    const whereParts = [];
-    const filter = input.filter;
-    if (filter?.chunkId !== undefined) {
-      whereParts.push(`chunk_id = ${makePlaceholder(params, filter.chunkId)}`);
-    }
-    if (filter?.title !== undefined) {
-      whereParts.push(`title = ${makePlaceholder(params, filter.title)}`);
-    }
-    if (filter?.source !== undefined) {
-      whereParts.push(`source = ${makePlaceholder(params, filter.source)}`);
-    }
-    const metadataFilter = buildMetadataFilter(filter);
-    if (metadataFilter) {
-      whereParts.push(`metadata @> ${makePlaceholder(params, JSON.stringify(metadataFilter), "jsonb")}`);
+    await init();
+    const queryVector = normalizeVector(input.queryVector);
+    const queryMultiplier2 = normalizeQueryMultiplier(input.queryMultiplier ?? options.queryMultiplier);
+    const maxBackfills = normalizeMaxBackfills(input.maxBackfills);
+    const minResults = normalizeMinResults(input.minResults, input.topK);
+    const fillTarget = resolveFillTarget({
+      fillPolicy: input.fillPolicy,
+      minResults,
+      topK: input.topK
+    });
+    const queryVectorLiteral = toVectorLiteral(queryVector);
+    const pushdownFilter = buildPostgresPushdownFilter(input.filter);
+    const queryFilterPlan = buildPostgresFilterPlan(pushdownFilter);
+    const effectivePushdownFilter = queryFilterPlan ? pushdownFilter : undefined;
+    const countFilterPlan = queryFilterPlan;
+    const countSql = countFilterPlan?.clause ? `select count(*)::int as count from ${qualifiedTableName} where ${countFilterPlan.clause}` : `select count(*)::int as count from ${qualifiedTableName}`;
+    const totalRowsResult = await db.unsafe(countSql, countFilterPlan?.params ?? []);
+    nativeDiagnostics.lastFilterDebug = {
+      countParams: countFilterPlan?.params ?? [],
+      countResultRaw: totalRowsResult?.[0],
+      countSql,
+      filter: input.filter,
+      pushdownFilter: effectivePushdownFilter
+    };
+    const totalRows = parseCountValue(totalRowsResult?.[0]?.count);
+    const candidateLimit = resolveAdaptiveNativeCandidateLimit({
+      defaultCandidateLimit: RAG_NATIVE_QUERY_CANDIDATE_LIMIT,
+      explicitCandidateLimit: input.candidateLimit,
+      filteredCandidateCount: totalRows,
+      plannerProfile: input.plannerProfile,
+      queryMultiplier: queryMultiplier2,
+      topK: input.topK
+    });
+    const hasPushdownFilter = Boolean(effectivePushdownFilter);
+    const plannedFilteredCandidateCount = hasPushdownFilter && totalRows === 0 ? undefined : totalRows;
+    const initialSearchK = planNativeCandidateSearchK({
+      candidateLimit,
+      filteredCandidateCount: plannedFilteredCandidateCount,
+      queryMultiplier: queryMultiplier2,
+      topK: input.topK
+    });
+    if (initialSearchK === 0) {
+      return [];
     }
-    const whereSql = whereParts.length > 0 ? `WHERE ${whereParts.join(" AND ")}` : "";
-    const sessionSql = plan.querySessionSql;
-    const selectSql = `SELECT chunk_id, text, title, source, metadata, embedding ${operator} ${vectorPlaceholder} AS distance FROM ${qualifiedChunkTable} ${whereSql} ORDER BY distance ASC LIMIT ${limitPlaceholder}`;
-    try {
-      for (const sql of sessionSql) {
-        await client.query(sql);
+    let currentSearchK = initialSearchK;
+    let backfillCount = 0;
+    let candidateBudgetExhausted = false;
+    let backfillLimitReached = false;
+    let effectiveFilteredCandidateCount = plannedFilteredCandidateCount;
+    let mapped = [];
+    for (;; ) {
+      const rowsSql = queryFilterPlan?.clause ? `select chunk_id, text, title, source, metadata, embedding::text as embedding, embedding ${distanceOperator} '${queryVectorLiteral}'::vector as distance from ${qualifiedTableName} where ${queryFilterPlan.clause} order by embedding ${distanceOperator} '${queryVectorLiteral}'::vector limit $${queryFilterPlan.params.length + 1}` : `select chunk_id, text, title, source, metadata, embedding::text as embedding, embedding ${distanceOperator} '${queryVectorLiteral}'::vector as distance from ${qualifiedTableName} order by embedding ${distanceOperator} '${queryVectorLiteral}'::vector limit $1`;
+      const rows = await db.unsafe(rowsSql, queryFilterPlan?.clause ? [...queryFilterPlan.params ?? [], currentSearchK] : [currentSearchK]);
+      nativeDiagnostics.lastFilterDebug = {
+        ...nativeDiagnostics.lastFilterDebug,
+        queryParams: queryFilterPlan?.clause ? [...queryFilterPlan.params ?? [], currentSearchK] : [currentSearchK],
+        queryRowCount: rows.length,
+        querySql: rowsSql
+      };
+      if (hasPushdownFilter && effectiveFilteredCandidateCount === undefined && rows.length <= currentSearchK) {
+        effectiveFilteredCandidateCount = rows.length;
       }
-      const result = await client.query(selectSql, params);
-      return result.rows.map((row) => ({
-        chunkId: row.chunk_id,
-        chunkText: row.text,
-        title: row.title ?? undefined,
-        source: row.source ?? undefined,
-        metadata: parseMetadataValue(row.metadata),
-        score: scoreFromDistance(Number(row.distance), vector.distanceMetric)
-      }));
-    } catch (error) {
-      diagnostics.lastQueryError = error instanceof Error ? error.message : String(error);
-      throw error;
+      mapped = rows.map((row) => {
+        const chunk = mapRowToChunk(row);
+        return {
+          chunk,
+          score: normalizeDistance(Number(row.distance ?? 0), distanceMetric)
+        };
+      }).filter(({ chunk }) => matchesFilter(chunk, input.filter)).map((entry) => ({
+        chunkId: entry.chunk.chunkId,
+        chunkText: entry.chunk.text,
+        embedding: entry.chunk.vector,
+        metadata: entry.chunk.metadata,
+        score: entry.score,
+        source: entry.chunk.source,
+        title: entry.chunk.title
+      })).sort((left, right) => right.score - left.score);
+      if (mapped.length >= fillTarget.targetResults) {
+        break;
+      }
+      const nextSearchK = planNativeCandidateSearchBackfillK({
+        backfillCount,
+        candidateLimit,
+        currentSearchK,
+        filteredCandidateCount: effectiveFilteredCandidateCount,
+        maxBackfills
+      });
+      if (nextSearchK <= currentSearchK) {
+        backfillLimitReached = typeof maxBackfills === "number" && backfillCount >= maxBackfills && mapped.length < fillTarget.targetResults;
+        candidateBudgetExhausted = mapped.length < fillTarget.targetResults;
+        break;
+      }
+      currentSearchK = nextSearchK;
+      backfillCount += 1;
     }
+    nativeDiagnostics.lastQueryError = undefined;
+    const returned = mapped.slice(0, input.topK);
+    updatePostgresLastQueryPlan({
+      backfillCount,
+      backfillLimitReached,
+      candidateBudgetExhausted,
+      candidateLimitUsed: candidateLimit,
+      maxBackfillsUsed: maxBackfills,
+      minResultsUsed: minResults,
+      fillPolicyUsed: fillTarget.fillPolicy,
+      plannerProfileUsed: input.plannerProfile,
+      filter: input.filter,
+      pushdownFilter: effectivePushdownFilter,
+      queryMultiplierUsed: queryMultiplier2,
+      filteredCandidateCount: effectiveFilteredCandidateCount,
+      finalSearchK: currentSearchK,
+      initialSearchK,
+      nativeDiagnostics,
+      minResultsSatisfied: returned.length >= minResults,
+      returnedCount: returned.length,
+      topK: input.topK,
+      underfilledTopK: returned.length < input.topK
+    });
+    return returned;
+  };
+  const queryLexical = async (input) => {
+    await init();
+    const pushdownFilter = buildPostgresPushdownFilter(input.filter);
+    const lexicalFilterPlan = buildPostgresFilterPlan(pushdownFilter);
+    const rowsSql = lexicalFilterPlan?.clause ? `select chunk_id, text, title, source, metadata from ${qualifiedTableName} where ${lexicalFilterPlan.clause}` : `select chunk_id, text, title, source, metadata from ${qualifiedTableName}`;
+    const rows = await db.unsafe(rowsSql, lexicalFilterPlan?.params ?? []);
+    const chunks = rows.map((row) => mapRowToChunk(row)).filter((chunk) => matchesFilter(chunk, input.filter));
+    const ranked = rankRAGLexicalMatches(input.query, chunks);
+    return ranked.slice(0, input.topK).map(({ result, score }) => ({
+      chunkId: result.chunkId,
+      chunkText: result.text,
+      metadata: result.metadata,
+      score,
+      source: result.source,
+      title: result.title
+    }));
   };
   const upsert = async (input) => {
-    await ensureInitialized();
-    const client = await getClient();
-    const qualifiedChunkTable = qualifiedTable(schema.schemaName, schema.chunkTableName);
-    const sql = `INSERT INTO ${qualifiedChunkTable} (chunk_id, text, title, source, metadata, embedding, updated_at) VALUES ($1, $2, $3, $4, $5::jsonb, $6::vector, NOW()) ON CONFLICT (chunk_id) DO UPDATE SET text = EXCLUDED.text, title = EXCLUDED.title, source = EXCLUDED.source, metadata = EXCLUDED.metadata, embedding = EXCLUDED.embedding, updated_at = NOW()`;
-    try {
-      for (const chunk of input.chunks) {
-        const vectorValue = Array.isArray(chunk.embedding) && chunk.embedding.length > 0 ? normalizeVector(chunk.embedding) : await embed({ text: chunk.text });
-        await client.query(sql, [
-          chunk.chunkId,
-          chunk.text,
-          chunk.title ?? null,
-          chunk.source ?? null,
-          JSON.stringify(chunk.metadata ?? {}),
-          vectorLiteral(vectorValue)
-        ]);
-      }
-    } catch (error) {
-      diagnostics.lastUpsertError = error instanceof Error ? error.message : String(error);
-      throw error;
+    await init();
+    const chunks = input.chunks.length > 0 ? await Promise.all(input.chunks.map(async (chunk) => ({
+      chunkId: chunk.chunkId,
+      metadata: chunk.metadata,
+      source: chunk.source,
+      text: chunk.text,
+      title: chunk.title,
+      vector: chunk.embedding ? normalizeVector(chunk.embedding) : normalizeVector(await embed({ text: chunk.text }))
+    }))) : [];
+    for (const chunk of chunks) {
+      await db.unsafe(`insert into ${qualifiedTableName} (chunk_id, text, title, source, metadata, embedding)
+				 values ($1, $2, $3, $4, $5::jsonb, $6::vector)
+				 on conflict (chunk_id) do update set
+				   text = excluded.text,
+				   title = excluded.title,
+				   source = excluded.source,
+				   metadata = excluded.metadata,
+				   embedding = excluded.embedding`, [
+        chunk.chunkId,
+        chunk.text,
+        chunk.title ?? null,
+        chunk.source ?? null,
+        chunk.metadata ?? null,
+        toVectorLiteral(chunk.vector)
+      ]);
+    }
+    await refreshPostgresRuntimeDiagnostics(db, nativeDiagnostics, {
+      indexName,
+      qualifiedTableName,
+      schemaName,
+      tableName
+    });
+  };
+  const count = async (input = {}) => {
+    await init();
+    const filter = input.filter;
+    const chunkIds = input.chunkIds;
+    const hasFilter = Boolean(filter && Object.keys(filter).length > 0);
+    const hasChunkIds = Boolean(chunkIds && chunkIds.length > 0);
+    if (!hasFilter && !hasChunkIds) {
+      const countResult = await db.unsafe(`select count(*)::int as count from ${qualifiedTableName}`);
+      return parseCountValue(countResult[0]?.count);
     }
+    return (await getPostgresCandidateChunkIds(db, qualifiedTableName, {
+      filter,
+      chunkIds
+    })).length;
+  };
+  const remove = async (input = {}) => {
+    await init();
+    const filter = input.filter;
+    const chunkIds = input.chunkIds;
+    const hasFilter = Boolean(filter && Object.keys(filter).length > 0);
+    const hasChunkIds = Boolean(chunkIds && chunkIds.length > 0);
+    if (!hasFilter && !hasChunkIds) {
+      return 0;
+    }
+    const ids = await getPostgresCandidateChunkIds(db, qualifiedTableName, {
+      filter,
+      chunkIds
+    });
+    if (ids.length === 0) {
+      return 0;
+    }
+    const placeholders = ids.map((_, index) => `$${index + 1}`).join(", ");
+    await db.unsafe(`delete from ${qualifiedTableName} where chunk_id in (${placeholders})`, ids);
+    await refreshPostgresRuntimeDiagnostics(db, nativeDiagnostics, {
+      indexName,
+      qualifiedTableName,
+      schemaName,
+      tableName
+    });
+    return ids.length;
   };
   const clear = async () => {
-    await ensureInitialized();
-    const client = await getClient();
-    const qualifiedChunkTable = qualifiedTable(schema.schemaName, schema.chunkTableName);
-    await client.query(`DELETE FROM ${qualifiedChunkTable}`);
+    await init();
+    await db.unsafe(`truncate table ${qualifiedTableName}`);
+    await refreshPostgresRuntimeDiagnostics(db, nativeDiagnostics, {
+      indexName,
+      qualifiedTableName,
+      schemaName,
+      tableName
+    });
+  };
+  const analyze = async () => {
+    await init();
+    await analyzePostgresTable(db, nativeDiagnostics, {
+      indexName,
+      qualifiedTableName,
+      schemaName,
+      tableName
+    });
+  };
+  const rebuildNativeIndex = async () => {
+    await init();
+    await rebuildPostgresNativeIndex(db, nativeDiagnostics, {
+      distanceMetric,
+      hnswEfConstruction,
+      hnswM,
+      indexLists,
+      indexName,
+      indexType,
+      qualifiedTableName,
+      schemaName,
+      tableName
+    });
+  };
+  const close = async () => {
+    await db.close?.();
   };
   return {
+    analyze,
+    clear,
+    close,
     embed,
+    getCapabilities: () => capabilities,
+    getStatus: () => createPostgresStatus(dimensions, nativeDiagnostics),
     query,
-    upsert,
-    clear,
-    getCapabilities: () => ({
-      backend: "postgres",
-      persistence: "external",
-      nativeVectorSearch: true,
-      serverSideFiltering: true,
-      streamingIngestStatus: false
-    }),
-    getStatus: () => createPgvectorStoreStatus({
-      vector,
-      schema,
-      diagnostics,
-      initialized
-    })
+    queryLexical,
+    rebuildNativeIndex: indexName ? rebuildNativeIndex : undefined,
+    count,
+    delete: remove,
+    upsert
   };
 };
-var createPostgresRAGCollection = (options) => createRAGCollection({
-  store: createPgvectorStore(options)
-});
-var createPostgresRAG = (options) => {
-  const store = createPgvectorStore(options);
-  const collection = createRAGCollection({ store });
-  const schemaPlan = createPostgresSchemaPlan(options);
-  const migrationPlan = createPostgresMigrationPlan(options);
+
+// src/index.ts
+var ABSOLUTE_POSTGRESQL_RAG_PACKAGE_NAME = "@absolutejs/rag-postgres";
+var createPostgresRAGCollection = (options = {}) => {
+  const store = options.store ?? createPostgresRAGStore(options.storeOptions ?? {});
+  return createRAGCollection({ store });
+};
+var createPostgresRAG = (options = {}) => {
+  const store = options.store ?? createPostgresRAGStore(options.storeOptions ?? {});
+  const collection = options.collection ?? createRAGCollection({ store });
   return {
     store,
     collection,
-    getStatus: () => store.getStatus?.(),
-    getCapabilities: () => store.getCapabilities?.(),
-    getSchemaPlan: () => schemaPlan,
-    getMigrationPlan: () => migrationPlan,
-    applyMigrations: (applyOptions) => applyPostgresMigrations(options, applyOptions)
+    getStatus: () => collection.getStatus?.() ?? store.getStatus?.(),
+    getCapabilities: () => collection.getCapabilities?.() ?? store.getCapabilities?.()
   };
 };
 var createPostgreSQLRAG = createPostgresRAG;
 export {
-  createPostgresSchemaPlan,
+  ragPlugin,
+  createRAGCollection,
+  createPostgresRAGStore,
   createPostgresRAGCollection,
   createPostgresRAG,
-  createPostgresMigrationPlan,
   createPostgreSQLRAG,
-  createPgvectorStore,
-  applyPostgresSchemaPlan,
-  applyPostgresMigrations,
-  POSTGRESQL_RAG_IMPLEMENTATIONS,
-  PGVECTOR_INDEX_TYPES,
-  PGVECTOR_DISTANCE_METRICS,
   ABSOLUTE_POSTGRESQL_RAG_PACKAGE_NAME
 };
 
-//# debugId=22931C2F3EFA23C264756E2164756E21
+//# debugId=705798FA59AD060364756E2164756E21
 //# sourceMappingURL=index.js.map