@nicia-ai/typegraph 0.33.0 → 0.35.0

package/dist/{chunk-OS6KS3HV.js → chunk-RGP33ZJ5.js}

@@ -1,10 +1,11 @@
-import { pgvectorStrategy, assertPgvectorEfSearch } from './chunk-PRMKPFN5.js';
-import { quoteIdentifier } from './chunk-3EUKJEQ3.js';
-import { tables, createVectorSlotLatch, createPostgresOperationStrategy, createCachedTableExistence, createContributionMaterializer, gateFulltextMethods, createCommonOperationBackend, generatePgCreateTableSQL, mapContributionMaterializationRow, POSTGRES_CONTRIBUTION_MAT_TIMESTAMPS, buildContributionInsertValues, buildContributionOnConflictSet, assertAdoptedDialect, buildKindRemovalInsertValues, POSTGRES_KIND_REMOVAL_TIMESTAMPS, buildKindRemovalOnConflictSet, mapKindRemovalRow, buildMaterializationInsertValues, POSTGRES_INDEX_MAT_TIMESTAMPS, buildMaterializationOnConflictSet, mapMaterializationRow, generatePostgresDDL, vectorSlotFromParams, mapVectorWriteError, vectorSlotFromDropIndexParams, vectorSlotFromCreateIndexParams, gateFulltext, compileQueryWithDialect, getOrCreateLru } from './chunk-UPDMJEW6.js';
-import { createNodeRowMapper, POSTGRES_ROW_MAPPER_CONFIG, createEdgeRowMapper, createUniqueRowMapper, createSchemaVersionRowMapper, nowIso, POSTGRES_CAPABILITIES, coerceNumericScore, POSTGRES_MAX_BIND_PARAMETERS } from './chunk-PYD3UCDU.js';
-import { isMissingTableError } from './chunk-GYVBEZAO.js';
-import { tsvectorStrategy, buildFulltextCapabilities, buildVectorCapabilities, assertVectorSearchLimit } from './chunk-C4C4Q7A6.js';
-import { ConfigurationError } from './chunk-TQOYM4LN.js';
+import { tables, createVectorSlotLatch, createPostgresOperationStrategy, createCachedTableExistence, createContributionMaterializer, gateFulltextMethods, EMBEDDING_UPSERT_PARAM_COUNT, createCommonOperationBackend, vectorSlotFromParams, hybridCandidatesRef, mapVectorWriteError, mapHybridSearchRow, generatePgCreateTableSQL, mapContributionMaterializationRow, POSTGRES_CONTRIBUTION_MAT_TIMESTAMPS, buildContributionInsertValues, buildContributionOnConflictSet, assertAdoptedDialect, buildKindRemovalInsertValues, POSTGRES_KIND_REMOVAL_TIMESTAMPS, buildKindRemovalOnConflictSet, mapKindRemovalRow, buildMaterializationInsertValues, POSTGRES_INDEX_MAT_TIMESTAMPS, buildMaterializationOnConflictSet, mapMaterializationRow, generatePostgresDDL, vectorSlotFromDropIndexParams, vectorSlotFromCreateIndexParams, gateFulltext, compileQueryWithDialect, getOrCreateLru } from './chunk-WDBCBWC4.js';
+import { pgvectorStrategy, assertPgvectorEfSearch } from './chunk-Q5TEXCTB.js';
+import { createNodeRowMapper, POSTGRES_ROW_MAPPER_CONFIG, createEdgeRowMapper, createUniqueRowMapper, createSchemaVersionRowMapper, quoteIdentifier, nowIso, coerceNumericScore } from './chunk-55MZDDZV.js';
+import { tsvectorStrategy, assertVectorSearchLimit, buildFulltextCapabilities, buildVectorCapabilities } from './chunk-FPIZFYHE.js';
+import { shouldForceCustomPlan, annIndexScanTypes } from './chunk-UT3S4SEN.js';
+import { POSTGRES_MAX_BIND_PARAMETERS, POSTGRES_CAPABILITIES, chunk } from './chunk-JBTOYDMN.js';
+import { isMissingTableError, isInsufficientResourcesError } from './chunk-I7ZUZKFD.js';
+import { ConfigurationError, CompilerInvariantError, TransactionClosedError } from './chunk-MP2JQKSG.js';
 import { getTableName, sql, and, eq, isNull, inArray } from 'drizzle-orm';
 import { PgDatabase, PgTransaction } from 'drizzle-orm/pg-core';
 
@@ -72,21 +73,32 @@ function wrapNodePgClient(client, cacheMax) {
         values: params
       });
       return { rows: normalizeRows(result.rows) };
+    },
+    async queryUnnamed(sqlText, params) {
+      const result = await client.query(sqlText, params);
+      return { rows: normalizeRows(result.rows) };
     }
   };
 }
 function wrapNodePgClientUnnamed(client) {
+  async function queryUnnamed(sqlText, params) {
+    const result = await client.query(sqlText, params);
+    return { rows: normalizeRows(result.rows) };
+  }
   return {
-    async query(sqlText, params) {
-      const result = await client.query(sqlText, params);
-      return { rows: normalizeRows(result.rows) };
-    }
+    query: queryUnnamed,
+    queryUnnamed
   };
 }
 function adaptPostgresJsClient(sql2) {
+  async function query(sqlText, params) {
+    const rows = await sql2.unsafe(sqlText, params);
+    return { rows };
+  }
   return {
-    async query(sqlText, params) {
-      const rows = await sql2.unsafe(sqlText, params);
+    query,
+    async queryUnnamed(sqlText, params) {
+      const rows = await sql2.unsafe(sqlText, params, { prepare: false });
       return { rows };
     }
   };
@@ -149,6 +161,13 @@ function createPostgresExecutionAdapter(db, options = {}) {
     compile,
     async execute(query) {
       const compiled = compile(query);
+      if (shouldForceCustomPlan(query)) {
+        const result = await pgQueryClient.queryUnnamed(
+          compiled.sql,
+          compiled.params
+        );
+        return result.rows;
+      }
       return executeCompiled(compiled);
     },
     executeCompiled,
@@ -158,6 +177,57 @@ function createPostgresExecutionAdapter(db, options = {}) {
   };
 }
 
+// src/backend/drizzle/execution/statement-queue.ts
+function ignoreOutcome() {
+}
+function createStatementQueue() {
+  let tail = Promise.resolve();
+  let closed = false;
+  return {
+    enqueue(task) {
+      if (closed) return Promise.reject(new TransactionClosedError());
+      const result = tail.then(() => task());
+      tail = result.then(ignoreOutcome, ignoreOutcome);
+      return result;
+    },
+    async drainAndClose() {
+      closed = true;
+      await tail;
+    }
+  };
+}
+function createSerialExecutionAdapter(adapter) {
+  const { enqueue, drainAndClose } = createStatementQueue();
+  const { executeCompiled, prepare } = adapter;
+  return {
+    drainAndClose,
+    compile(query) {
+      return adapter.compile(query);
+    },
+    execute(query) {
+      return enqueue(() => adapter.execute(query));
+    },
+    runExclusive(critical) {
+      return enqueue(() => critical(adapter));
+    },
+    ...executeCompiled === void 0 ? {} : {
+      executeCompiled(compiledQuery) {
+        return enqueue(() => executeCompiled(compiledQuery));
+      }
+    },
+    ...prepare === void 0 ? {} : {
+      prepare(sqlText) {
+        const statement = prepare(sqlText);
+        return {
+          execute(params) {
+            return enqueue(() => statement.execute(params));
+          }
+        };
+      }
+    }
+  };
+}
+
 // src/backend/drizzle/postgres.ts
 var NODE_INSERT_PARAM_COUNT = 9;
 var EDGE_INSERT_PARAM_COUNT = 12;
@@ -177,11 +247,26 @@ var POSTGRES_GET_EDGES_ID_CHUNK_SIZE = Math.max(
   1,
   POSTGRES_MAX_BIND_PARAMETERS - 1
 );
+var FULLTEXT_UPSERT_PARAM_COUNT = 6;
+var FULLTEXT_DELETE_FIXED_PARAM_COUNT = 2;
+var POSTGRES_FULLTEXT_UPSERT_BATCH_SIZE = Math.max(
+  1,
+  Math.floor(POSTGRES_MAX_BIND_PARAMETERS / FULLTEXT_UPSERT_PARAM_COUNT)
+);
+var POSTGRES_FULLTEXT_DELETE_CHUNK_SIZE = Math.max(
+  1,
+  POSTGRES_MAX_BIND_PARAMETERS - FULLTEXT_DELETE_FIXED_PARAM_COUNT
+);
 var CHECK_UNIQUE_BATCH_FIXED_PARAM_COUNT = 3;
 var POSTGRES_CHECK_UNIQUE_BATCH_CHUNK_SIZE = Math.max(
   1,
   POSTGRES_MAX_BIND_PARAMETERS - CHECK_UNIQUE_BATCH_FIXED_PARAM_COUNT
 );
+var UNIQUE_INSERT_PARAM_COUNT = 6;
+var POSTGRES_UNIQUE_INSERT_BATCH_SIZE = Math.max(
+  1,
+  Math.floor(POSTGRES_MAX_BIND_PARAMETERS / UNIQUE_INSERT_PARAM_COUNT)
+);
 var toNodeRow = createNodeRowMapper(POSTGRES_ROW_MAPPER_CONFIG);
 var toEdgeRow = createEdgeRowMapper(POSTGRES_ROW_MAPPER_CONFIG);
 var toUniqueRow = createUniqueRowMapper(POSTGRES_ROW_MAPPER_CONFIG);
@@ -200,6 +285,7 @@ function createPostgresBackend(db, options = {}) {
   const fulltextStrategy = options.fulltext ?? tsvectorStrategy;
   const vectorStrategy = options.vector === false ? void 0 : options.vector ?? pgvectorStrategy;
   const vectorSlotLatch = vectorStrategy === void 0 ? void 0 : createVectorSlotLatch();
+  const iterativeScanProbe = createIterativeScanProbe();
   const baseCapabilities = buildPostgresCapabilities(
     fulltextStrategy,
     vectorStrategy
@@ -221,18 +307,16 @@ function createPostgresBackend(db, options = {}) {
     recordedNodes: getTableName(tables2.recordedNodes),
     recordedEdges: getTableName(tables2.recordedEdges),
     recordedClock: getTableName(tables2.recordedClock),
+    revisionOrigins: getTableName(tables2.revisionOrigins),
     fulltext: tables2.fulltextTableName,
     uniques: getTableName(tables2.uniques)
   };
-  const coreAnalyzeStatement = sql`ANALYZE ${sql.join(
-    [
-      tableNames.nodes,
-      tableNames.edges,
-      getTableName(tables2.uniques),
-      tableNames.fulltext
-    ].map((name) => quoteIdentifier(name)),
-    sql`, `
-  )}`;
+  const coreAnalyzeStatements = [
+    tableNames.nodes,
+    tableNames.edges,
+    getTableName(tables2.uniques),
+    tableNames.fulltext
+  ].map((name) => sql`ANALYZE (SKIP_LOCKED) ${quoteIdentifier(name)}`);
   const recordedAnalyzeTables = [
     tableNames.recordedNodes,
     tableNames.recordedEdges,
@@ -251,7 +335,8 @@ function createPostgresBackend(db, options = {}) {
     capabilities,
     fulltextStrategy,
     vectorStrategy,
-    vectorSlotLatch
+    vectorSlotLatch,
+    iterativeScanProbe
   });
   const recordedTableExists = createCachedTableExistence(
     async (tableName) => {
@@ -275,15 +360,21 @@ function createPostgresBackend(db, options = {}) {
     }
     return db.transaction(async (tx) => {
       await tx.execute(sql`SELECT pg_advisory_xact_lock(hashtext(${graphId}))`);
-      const txBackend = createTransactionBackend({
+      const { backend: txBackend, drainAndClose } = createTransactionBackend({
         db: tx,
         adapterOptions,
         operationStrategy,
         tableNames,
         capabilities,
         fulltextStrategy,
-        vectorStrategy});
-      return fn(txBackend);
+        vectorStrategy,
+        iterativeScanProbe
+      });
+      try {
+        return await fn(txBackend);
+      } finally {
+        await drainAndClose();
+      }
     });
   }
   const matTable = tables2.contributionMaterializations;
@@ -337,15 +428,23 @@ function createPostgresBackend(db, options = {}) {
     recordMarker: recordContributionMaterializationRow
   });
   function bindTransactionBackend(tx) {
-    const txBackend = createTransactionBackend({
+    const { backend: backend2, drainAndClose } = createTransactionBackend({
       db: tx,
       adapterOptions,
       operationStrategy,
       tableNames,
       capabilities,
       fulltextStrategy,
-      vectorStrategy});
-    return gateFulltext(txBackend, contributionMaterializer.assertInitialized);
+      vectorStrategy,
+      iterativeScanProbe
+    });
+    return {
+      backend: gateFulltext(
+        backend2,
+        contributionMaterializer.assertInitialized
+      ),
+      drainAndClose
+    };
   }
   const backend = {
     ...operations,
@@ -355,6 +454,11 @@ function createPostgresBackend(db, options = {}) {
         await db.execute(sql.raw(statement));
       }
     },
+    async ensureRevisionOriginsTable() {
+      await db.execute(
+        sql.raw(generatePgCreateTableSQL(tables2.revisionOrigins))
+      );
+    },
     // Every fulltext-touching method asserts the durable marker instead
     // of lazily emitting DDL. Steady state performs zero ensure; an
     // uninitialized database throws `StoreNotInitializedError` loudly
@@ -371,6 +475,50 @@ function createPostgresBackend(db, options = {}) {
       await db.execute(
         sql.raw(generatePgCreateTableSQL(tables2.indexMaterializations))
       );
+      const tableName = getTableName(tables2.indexMaterializations);
+      await db.execute(
+        sql.raw(
+          `ALTER TABLE "${tableName}" ADD COLUMN IF NOT EXISTS "building_since" timestamptz;`
+        )
+      );
+      await db.execute(
+        sql.raw(
+          `ALTER TABLE "${tableName}" ADD COLUMN IF NOT EXISTS "claim_token" text;`
+        )
+      );
+    },
+    async claimIndexMaterialization(params) {
+      const t = tables2.indexMaterializations;
+      const rows = await db.execute(sql`
+        INSERT INTO ${t} (
+          "index_name", "graph_id", "entity", "kind", "signature",
+          "schema_version", "last_attempted_at", "building_since",
+          "claim_token"
+        )
+        VALUES (
+          ${params.indexName}, ${params.graphId}, ${params.entity},
+          ${params.kind}, ${params.signature}, ${params.schemaVersion},
+          now(), now(), ${params.token}
+        )
+        ON CONFLICT ("index_name") DO UPDATE SET
+          "building_since" = now(),
+          "claim_token" = EXCLUDED."claim_token"
+        WHERE ${t}."building_since" IS NULL
+           OR ${t}."building_since" < now() - (${params.leaseMs} * interval '1 millisecond')
+        RETURNING "index_name"
+      `);
+      const result = rows;
+      const returned = Array.isArray(result) ? result : result.rows ?? [];
+      return returned.length > 0;
+    },
+    async releaseIndexMaterializationClaim(params) {
+      const t = tables2.indexMaterializations;
+      await db.execute(sql`
+        UPDATE ${t}
+        SET "building_since" = NULL, "claim_token" = NULL
+        WHERE "index_name" = ${params.indexName}
+          AND "claim_token" = ${params.token}
+      `);
     },
     async getIndexMaterialization(indexName) {
       const t = tables2.indexMaterializations;
@@ -472,7 +620,9 @@ function createPostgresBackend(db, options = {}) {
       });
     },
     async refreshStatistics() {
-      await db.execute(coreAnalyzeStatement);
+      for (const statement of coreAnalyzeStatements) {
+        await db.execute(statement);
+      }
       const tablePresence = await Promise.all(
         recordedAnalyzeTables.map(async (tableName) => ({
           tableName,
@@ -480,12 +630,9 @@ function createPostgresBackend(db, options = {}) {
         }))
       );
       const presentRecordedTables = tablePresence.filter((entry) => entry.exists).map((entry) => entry.tableName);
-      if (presentRecordedTables.length > 0) {
+      for (const tableName of presentRecordedTables) {
         await db.execute(
-          sql`ANALYZE ${sql.join(
-            presentRecordedTables.map((name) => quoteIdentifier(name)),
-            sql`, `
-          )}`
+          sql`ANALYZE (SKIP_LOCKED) ${quoteIdentifier(tableName)}`
         );
       }
     },
@@ -505,10 +652,14 @@ function createPostgresBackend(db, options = {}) {
       const txConfig = options2?.isolationLevel ? {
         isolationLevel: options2.isolationLevel.replace("_", " ")
       } : void 0;
-      return db.transaction(
-        async (tx) => fn(bindTransactionBackend(tx), tx),
-        txConfig
-      );
+      return db.transaction(async (tx) => {
+        const { backend: txBackend, drainAndClose } = bindTransactionBackend(tx);
+        try {
+          return await fn(txBackend, tx);
+        } finally {
+          await drainAndClose();
+        }
+      }, txConfig);
     },
     adoptTransaction(externalTx) {
       if (!capabilities.transactions) {
@@ -522,13 +673,46 @@ function createPostgresBackend(db, options = {}) {
         );
       }
       assertAdoptedDialect(externalTx, PgDatabase, "postgres");
-      return bindTransactionBackend(externalTx);
+      return bindTransactionBackend(externalTx).backend;
     },
     async close() {
     }
   };
   return backend;
 }
+function createIterativeScanProbe() {
+  let probe;
+  let warned = false;
+  function warnUnavailable(version) {
+    if (warned) return;
+    warned = true;
+    if (typeof console === "undefined" || typeof console.warn !== "function") {
+      return;
+    }
+    console.warn(
+      `[typegraph] pgvector ${version} has no iterative scan (added in 0.8), so a filtered approximate vector search stays ef_search-bounded and can return fewer rows than \`limit\` while more matches exist. Upgrade pgvector to >= 0.8, or use an exact search (\`approximate: false\`) where a full page matters.`
+    );
+  }
+  return {
+    isSupported(execAll) {
+      probe ??= (async () => {
+        try {
+          const [row] = await execAll(
+            sql`SELECT extversion AS v FROM pg_extension WHERE extname = 'vector'`
+          );
+          if (typeof row?.v !== "string") return false;
+          const [major = 0, minor = 0] = row.v.split(".").map((part) => Number.parseInt(part, 10));
+          const supported = major > 0 || major === 0 && minor >= 8;
+          if (!supported) warnUnavailable(row.v);
+          return supported;
+        } catch {
+          return false;
+        }
+      })();
+      return probe;
+    }
+  };
+}
 function createPostgresOperationBackend(options) {
   const {
     db,
@@ -539,7 +723,8 @@ function createPostgresOperationBackend(options) {
     capabilities,
     fulltextStrategy,
     vectorStrategy,
-    vectorSlotLatch
+    vectorSlotLatch,
+    iterativeScanProbe
   } = options;
   async function execAll(query) {
     return executionAdapter.execute(query);
@@ -562,31 +747,75 @@ function createPostgresOperationBackend(options) {
       "[typegraph] efSearch (hnsw.ef_search override) was ignored: this Postgres backend has transactions disabled (e.g. drizzle-orm/neon-http), and SET LOCAL needs a transaction to scope the override. Use a transactional driver (node-postgres / neon-serverless / postgres-js) to apply efSearch."
     );
   }
-  async function runVectorSearch(efSearch, query) {
-    if (efSearch === void 0) {
-      return execAll(query);
+  function pgvectorIterativeScanSupported() {
+    return iterativeScanProbe.isSupported(execAll);
+  }
+  async function vectorSearchGucOverrides(params) {
+    const overrides = [];
+    if (params.efSearch !== void 0) {
+      if (capabilities.transactions) {
+        overrides.push({
+          name: "hnsw.ef_search",
+          value: String(params.efSearch)
+        });
+      } else {
+        warnEfSearchUnsupported();
+      }
     }
-    if (!capabilities.transactions) {
-      warnEfSearchUnsupported();
-      return execAll(query);
+    if (params.indexType === "hnsw" && capabilities.transactions && await pgvectorIterativeScanSupported()) {
+      overrides.push({ name: "hnsw.iterative_scan", value: "strict_order" });
     }
-    const setEfSearch = sql.raw(`SET LOCAL hnsw.ef_search = ${efSearch}`);
-    if (db instanceof PgTransaction) {
-      const [setting] = await execAll(
-        sql`SELECT current_setting('hnsw.ef_search') AS ef_search`
+    if (params.indexType === "ivfflat" && capabilities.transactions && await pgvectorIterativeScanSupported()) {
+      overrides.push({
+        name: "ivfflat.iterative_scan",
+        value: "relaxed_order"
+      });
+    }
+    return overrides;
+  }
+  async function runVectorSearchGucGroup(overrides, query) {
+    const runExclusive = executionAdapter.runExclusive;
+    if (runExclusive === void 0) {
+      throw new CompilerInvariantError(
+        "A transaction-scoped Postgres backend must expose runExclusive; its execution adapter was not wrapped by createSerialExecutionAdapter."
       );
-      await execRun(setEfSearch);
-      const rows = await execAll(query);
-      if (setting !== void 0) {
-        await execRun(
-          sql`SELECT set_config('hnsw.ef_search', ${setting.ef_search}, true)`
+    }
+    return runExclusive(async (connection) => {
+      const snapshots = [];
+      for (const override of overrides) {
+        const [setting] = await connection.execute(
+          sql`SELECT current_setting(${override.name}) AS v`
+        );
+        if (setting !== void 0) {
+          snapshots.push({ name: override.name, value: setting.v });
+        }
+        await connection.execute(
+          sql`SELECT set_config(${override.name}, ${override.value}, true)`
+        );
+      }
+      const rows = await connection.execute(query);
+      for (const snapshot of snapshots) {
+        await connection.execute(
+          sql`SELECT set_config(${snapshot.name}, ${snapshot.value}, true)`
         );
       }
       return rows;
+    });
+  }
+  async function runVectorSearch(overrides, query) {
+    if (overrides.length === 0) {
+      return execAll(query);
+    }
+    if (db instanceof PgTransaction) {
+      return runVectorSearchGucGroup(overrides, query);
     }
     return db.transaction(async (tx) => {
       const txAdapter = createPostgresExecutionAdapter(tx, adapterOptions);
-      await txAdapter.execute(setEfSearch);
+      for (const override of overrides) {
+        await txAdapter.execute(
+          sql`SELECT set_config(${override.name}, ${override.value}, true)`
+        );
+      }
       return txAdapter.execute(query);
     });
   }
@@ -596,14 +825,25 @@ function createPostgresOperationBackend(options) {
       await execRun(sql.raw(statement));
     });
   }
+  const batchConfig = {
+    checkUniqueBatchChunkSize: POSTGRES_CHECK_UNIQUE_BATCH_CHUNK_SIZE,
+    edgeInsertBatchSize: POSTGRES_EDGE_INSERT_BATCH_SIZE,
+    // Unlike the static siblings, the embedding upsert honors a runtime
+    // `maxBindParameters` override so its chunk size tracks the connection's
+    // actual bind budget.
+    embeddingUpsertBatchSize: Math.max(
+      1,
+      Math.floor(
+        (capabilities.maxBindParameters ?? POSTGRES_MAX_BIND_PARAMETERS) / EMBEDDING_UPSERT_PARAM_COUNT
+      )
+    ),
+    getEdgesChunkSize: POSTGRES_GET_EDGES_ID_CHUNK_SIZE,
+    getNodesChunkSize: POSTGRES_GET_NODES_ID_CHUNK_SIZE,
+    nodeInsertBatchSize: POSTGRES_NODE_INSERT_BATCH_SIZE,
+    uniqueInsertBatchSize: POSTGRES_UNIQUE_INSERT_BATCH_SIZE
+  };
   const commonBackend = createCommonOperationBackend({
-    batchConfig: {
-      checkUniqueBatchChunkSize: POSTGRES_CHECK_UNIQUE_BATCH_CHUNK_SIZE,
-      edgeInsertBatchSize: POSTGRES_EDGE_INSERT_BATCH_SIZE,
-      getEdgesChunkSize: POSTGRES_GET_EDGES_ID_CHUNK_SIZE,
-      getNodesChunkSize: POSTGRES_GET_NODES_ID_CHUNK_SIZE,
-      nodeInsertBatchSize: POSTGRES_NODE_INSERT_BATCH_SIZE
-    },
+    batchConfig,
     execution: {
       execAll,
       execGet,
@@ -638,6 +878,48 @@ function createPostgresOperationBackend(options) {
         throw mapVectorWriteError(error, params);
       }
     },
+    async upsertEmbeddingBatch(params) {
+      if (params.rows.length === 0) return;
+      const slot = vectorSlotFromParams(params);
+      await ensureVectorSlotStorage(slot);
+      const rowsById = new Map(
+        params.rows.map((row) => [row.nodeId, row])
+      );
+      const rows = [...rowsById.values()];
+      const timestamp = nowIso();
+      try {
+        for (const chunk2 of chunk(
+          rows,
+          batchConfig.embeddingUpsertBatchSize
+        )) {
+          const statements = vectorStrategy.buildUpsertBatch === void 0 ? chunk2.flatMap(
+            (row) => vectorStrategy.buildUpsert(
+              slot,
+              {
+                graphId: params.graphId,
+                nodeKind: params.nodeKind,
+                nodeId: row.nodeId,
+                fieldPath: params.fieldPath,
+                embedding: row.embedding,
+                dimensions: params.dimensions,
+                metric: params.metric,
+                indexType: params.indexType
+              },
+              timestamp
+            )
+          ) : vectorStrategy.buildUpsertBatch(
+            slot,
+            { ...params, rows: chunk2 },
+            timestamp
+          );
+          for (const statement of statements) {
+            await execRun(statement);
+          }
+        }
+      } catch (error) {
+        throw mapVectorWriteError(error, params);
+      }
+    },
     async deleteEmbedding(params) {
       const slot = vectorSlotFromParams(params);
       await ensureVectorSlotStorage(slot);
@@ -651,10 +933,20 @@ function createPostgresOperationBackend(options) {
       assertPgvectorEfSearch(params.efSearch);
       const slot = vectorSlotFromParams(params);
       await ensureVectorSlotStorage(slot);
-      const query = vectorStrategy.buildSearch(slot, params);
+      const query = vectorStrategy.buildSearch(
+        slot,
+        params,
+        // Store-compiled candidates (predicates + subclass + currency)
+        // take precedence; the live-node default covers direct backend use.
+        params.candidates ?? operationStrategy.buildLiveNodeIds(
+          params.graphId,
+          params.nodeKind
+        )
+      );
+      const gucOverrides = await vectorSearchGucOverrides(params);
       let rows;
       try {
-        rows = await runVectorSearch(params.efSearch, query);
+        rows = await runVectorSearch(gucOverrides, query);
       } catch (error) {
         throw mapVectorWriteError(error, params);
       }
@@ -662,7 +954,65 @@ function createPostgresOperationBackend(options) {
         nodeId: row.node_id,
         score: row.score
       }));
-    }
+    },
+    // Single-statement hybrid needs ROW_NUMBER(); a capability
+    // profile that disables window functions keeps the store's
+    // multi-statement fallback by simply not exposing the member.
+    ...capabilities.windowFunctions ? {
+      async hybridSearch(params) {
+        assertVectorSearchLimit(params.limit);
+        assertVectorSearchLimit(params.vector.k);
+        assertPgvectorEfSearch(params.vector.efSearch);
+        const slot = vectorSlotFromParams({
+          graphId: params.graphId,
+          nodeKind: params.nodeKind,
+          fieldPath: params.vector.fieldPath,
+          dimensions: params.vector.dimensions,
+          metric: params.vector.metric,
+          indexType: params.vector.indexType
+        });
+        await ensureVectorSlotStorage(slot);
+        const candidates = params.candidates ?? operationStrategy.buildLiveNodeIds(
+          params.graphId,
+          params.nodeKind
+        );
+        const vectorParams = {
+          graphId: params.graphId,
+          nodeKind: params.nodeKind,
+          fieldPath: params.vector.fieldPath,
+          queryEmbedding: params.vector.queryEmbedding,
+          metric: params.vector.metric,
+          dimensions: params.vector.dimensions,
+          indexType: params.vector.indexType,
+          limit: params.vector.k,
+          ...params.vector.minScore === void 0 ? {} : { minScore: params.vector.minScore }
+        };
+        const vectorSql = vectorStrategy.buildSearch(
+          slot,
+          vectorParams,
+          hybridCandidatesRef()
+        );
+        const statement = operationStrategy.buildHybridSearch(
+          { ...params, candidates },
+          vectorSql,
+          params.vector.metric === "cosine"
+        );
+        const gucOverrides = await vectorSearchGucOverrides({
+          indexType: params.vector.indexType,
+          ...params.vector.efSearch === void 0 ? {} : { efSearch: params.vector.efSearch }
+        });
+        let raw;
+        try {
+          raw = await runVectorSearch(
+            gucOverrides,
+            statement
+          );
+        } catch (error) {
+          throw mapVectorWriteError(error, vectorParams);
+        }
+        return raw.map((row) => mapHybridSearchRow(row, toNodeRow));
+      }
+    } : {}
   };
   const operationBackend = {
     ...commonBackend,
@@ -682,7 +1032,30 @@ function createPostgresOperationBackend(options) {
         concurrent: params.concurrent === true
       });
       if (indexStatement !== void 0) {
-        await execRun(indexStatement);
+        try {
+          await execRun(indexStatement);
+        } catch (error) {
+          if (!isInsufficientResourcesError(error)) throw error;
+          const dropStatement = vectorStrategy.buildDropIndex?.(slot);
+          if (dropStatement !== void 0) {
+            await execRun(dropStatement);
+          }
+          const table = quoteIdentifier(
+            vectorStrategy.tableName(
+              slot.graphId,
+              slot.nodeKind,
+              slot.fieldPath
+            )
+          );
+          await execRun(
+            sql`ALTER TABLE ${table} SET (parallel_workers = 0)`
+          );
+          try {
+            await execRun(indexStatement);
+          } finally {
+            await execRun(sql`ALTER TABLE ${table} RESET (parallel_workers)`);
+          }
+        }
       }
     },
     // === Fulltext Operations ===
@@ -705,19 +1078,32 @@ function createPostgresOperationBackend(options) {
     async upsertFulltextBatch(params) {
       if (params.rows.length === 0) return;
       const timestamp = nowIso();
-      const statements = operationStrategy.buildUpsertFulltextBatch(
-        params,
-        timestamp
-      );
-      for (const stmt of statements) {
-        await execRun(stmt);
+      for (const rows of chunk(
+        params.rows,
+        POSTGRES_FULLTEXT_UPSERT_BATCH_SIZE
+      )) {
+        const statements = operationStrategy.buildUpsertFulltextBatch(
+          { ...params, rows },
+          timestamp
+        );
+        for (const stmt of statements) {
+          await execRun(stmt);
+        }
       }
     },
     async deleteFulltextBatch(params) {
       if (params.nodeIds.length === 0) return;
-      const statements = operationStrategy.buildDeleteFulltextBatch(params);
-      for (const stmt of statements) {
-        await execRun(stmt);
+      for (const nodeIds of chunk(
+        params.nodeIds,
+        POSTGRES_FULLTEXT_DELETE_CHUNK_SIZE
+      )) {
+        const statements = operationStrategy.buildDeleteFulltextBatch({
+          ...params,
+          nodeIds
+        });
+        for (const stmt of statements) {
+          await execRun(stmt);
+        }
       }
     },
     async fulltextSearch(params) {
@@ -743,6 +1129,17 @@ function createPostgresOperationBackend(options) {
     },
     // === Query Execution ===
     async execute(query) {
+      const annTypes = annIndexScanTypes(query);
+      if (annTypes !== void 0 && vectorStrategy !== void 0) {
+        const overrides = [];
+        for (const indexType of annTypes) {
+          if (indexType !== "hnsw" && indexType !== "ivfflat") continue;
+          overrides.push(
+            ...await vectorSearchGucOverrides({ indexType })
+          );
+        }
+        return runVectorSearch(overrides, query);
+      }
       return executionAdapter.execute(query);
     },
     compileSql(query) {
@@ -752,8 +1149,10 @@ function createPostgresOperationBackend(options) {
   return operationBackend;
 }
 function createTransactionBackend(options) {
-  const txExecutionAdapter = options.executionAdapter ?? createPostgresExecutionAdapter(options.db, options.adapterOptions);
-  return createPostgresOperationBackend({
+  const txExecutionAdapter = createSerialExecutionAdapter(
+    createPostgresExecutionAdapter(options.db, options.adapterOptions)
+  );
+  const backend = createPostgresOperationBackend({
     db: options.db,
     executionAdapter: txExecutionAdapter,
     adapterOptions: options.adapterOptions,
@@ -762,10 +1161,14 @@ function createTransactionBackend(options) {
     capabilities: options.capabilities,
     fulltextStrategy: options.fulltextStrategy,
     vectorStrategy: options.vectorStrategy,
-    vectorSlotLatch: options.vectorStrategy === void 0 ? void 0 : createVectorSlotLatch()
+    vectorSlotLatch: options.vectorStrategy === void 0 ? void 0 : createVectorSlotLatch(),
+    // The probe is process-wide truth, so — unlike the slot latch — the outer
+    // instance's is reused rather than a fresh one per transaction.
+    iterativeScanProbe: options.iterativeScanProbe
   });
+  return { backend, drainAndClose: txExecutionAdapter.drainAndClose };
 }
 
 export { createPostgresBackend };
-//# sourceMappingURL=chunk-OS6KS3HV.js.map
-//# sourceMappingURL=chunk-OS6KS3HV.js.map
+//# sourceMappingURL=chunk-RGP33ZJ5.js.map
+//# sourceMappingURL=chunk-RGP33ZJ5.js.map