@nicia-ai/typegraph 0.43.0 → 0.45.0

package/dist/{chunk-HHBKGPEI.js → chunk-DXEEHSGN.js}

@@ -1,16 +1,82 @@
-import { formatPostgresTimestamp, coerceNumericScore, nowIso } from './chunk-CVNGKTHO.js';
-import { runtimeStrategyContributions } from './chunk-Z3WIL6S3.js';
-import { toDrizzleSql } from './chunk-UJRWOV5B.js';
+import { formatPostgresTimestamp, coerceNumericScore, nowIso } from './chunk-YMTXMPV6.js';
+import { runtimeStrategyContributions } from './chunk-BGYJW37L.js';
+import { toDrizzleSql } from './chunk-EFEOOCJ3.js';
 import { chunk } from './chunk-35S6P5ZU.js';
-import { createBackendOverlay } from './chunk-UZLEQFTV.js';
+import { createBackendOverlay } from './chunk-55ITBQJI.js';
 import { sortedReplacer } from './chunk-UR7W5YQK.js';
-import { parseDimensionMismatch, isMissingTableError } from './chunk-CUPJL6TS.js';
+import { parseDimensionMismatch, isMissingTableError } from './chunk-V34A6R5V.js';
 import { sha256Hex } from './chunk-K34OPSJK.js';
-import { sql as sql$1, asCompiledStatementSql, isSqlFragment } from './chunk-M4GYQF2H.js';
+import { getDialect } from './chunk-PVUI6KGR.js';
+import { sql as sql$1, asCompiledStatementSql, isSqlFragment } from './chunk-6DCB664D.js';
 import { isPresent } from './chunk-QMQLUA66.js';
-import { EmbeddingDimensionChangedError, ConfigurationError, MigrationError, SchemaContentConflictError, DatabaseOperationError, UniquenessError, TrustedImportError, StaleVersionError, StoreNotInitializedError } from './chunk-OYJSYDIH.js';
+import { EmbeddingDimensionChangedError, ConfigurationError, StaleVersionError, MigrationError, SchemaContentConflictError, DatabaseOperationError, UniquenessError, TrustedImportError, StoreNotInitializedError } from './chunk-4MB3AQAQ.js';
 import { sql, is, getTableName } from 'drizzle-orm';
 
+// src/backend/edge-endpoint-sets.ts
+var FIND_EDGES_ENDPOINT_FIXED_PARAM_COUNT = 6;
+var FIND_EDGES_HETEROGENEOUS_FIXED_PARAM_COUNT = 4;
+function assertLimitPerEndpoint(operation, graphId, limitPerEndpoint, kind) {
+  if (limitPerEndpoint === void 0 || Number.isInteger(limitPerEndpoint) && limitPerEndpoint > 0) {
+    return;
+  }
+  throw new ConfigurationError(
+    `${operation} \`limitPerEndpoint\` must be a positive integer, received ${String(limitPerEndpoint)}.`,
+    {
+      code: "EDGE_ENDPOINT_SET_INVALID",
+      graphId,
+      ...kind === void 0 ? {} : { kind }
+    },
+    {
+      suggestion: "Pass a positive integer to cap each endpoint's rows, or omit it for an unbounded read."
+    }
+  );
+}
+function resolveEdgeEndpointIds(params) {
+  assertLimitPerEndpoint(
+    "findEdgesByEndpointSet",
+    params.graphId,
+    params.limitPerEndpoint,
+    params.kind
+  );
+  return [...new Set(params.endpointIds)];
+}
+function endpointKey(endpoint) {
+  return `${endpoint.kind}\0${endpoint.id}`;
+}
+function resolveHeterogeneousEdgeRead(params, maxBindParameters) {
+  assertLimitPerEndpoint(
+    "findEdgesByHeterogeneousEndpointSet",
+    params.graphId,
+    params.limitPerEndpoint
+  );
+  const edgeKinds = [...new Set(params.edgeKinds)];
+  const endpoints = [
+    ...new Map(
+      params.endpoints.map((endpoint) => [endpointKey(endpoint), endpoint])
+    ).values()
+  ];
+  if (edgeKinds.length === 0 || endpoints.length === 0) {
+    return { edgeKinds, endpoints, endpointChunkSize: 1 };
+  }
+  const endpointBindBudget = maxBindParameters - FIND_EDGES_HETEROGENEOUS_FIXED_PARAM_COUNT - edgeKinds.length;
+  const endpointChunkSize = Math.floor(endpointBindBudget / 2);
+  if (endpointChunkSize >= 1) {
+    return { edgeKinds, endpoints, endpointChunkSize };
+  }
+  throw new ConfigurationError(
+    "findEdgesByHeterogeneousEndpointSet cannot fit one endpoint and the selected edge kinds within the backend bind-parameter budget.",
+    {
+      code: "EDGE_HETEROGENEOUS_READ_BIND_BUDGET_EXCEEDED",
+      graphId: params.graphId,
+      edgeKindCount: edgeKinds.length,
+      maxBindParameters
+    },
+    {
+      suggestion: "Select fewer edge kinds in one call or use a backend with a larger bind-parameter budget."
+    }
+  );
+}
+
 // src/backend/live-node-candidates.ts
 function buildLiveNodeCandidates(nodesTableName, graphId, nodeKind, now) {
   const nodes = sql$1.identifier(nodesTableName);
@@ -133,6 +199,32 @@ function evaluateContributionState(row, signature) {
   if (row.materializedAt === void 0) return "missing";
   return "initialized";
 }
+function diagnoseContribution(row, signature, tableExists) {
+  if (!tableExists) {
+    if (row === void 0) return void 0;
+    if (row.materializedAt !== void 0) return "orphaned-marker";
+    return row.lastError === void 0 ? void 0 : "failed-materialization";
+  }
+  if (row?.materializedAt !== void 0 && row.signature !== signature) {
+    return "stale";
+  }
+  const state = evaluateContributionState(row, signature);
+  switch (state) {
+    case "initialized": {
+      return void 0;
+    }
+    case "stale": {
+      return "stale";
+    }
+    case "missing":
+    case "failed": {
+      return "missing-marker";
+    }
+    default: {
+      return state;
+    }
+  }
+}
 function identityOf(graphId, contribution) {
   return {
     graphId,
@@ -205,6 +297,7 @@ function contributionKey(graphId, contribution) {
 function createContributionMaterializer(deps) {
   const { dialect, fulltextStrategy, fulltextTableName } = deps;
   const initializedSignatures = /* @__PURE__ */ new Map();
+  const uncacheableKeys = /* @__PURE__ */ new Set();
   const computedSignatures = /* @__PURE__ */ new Map();
   async function resolveContributionSignature(key, contribution) {
     const cached = computedSignatures.get(key);
@@ -237,6 +330,11 @@ function createContributionMaterializer(deps) {
   function runtimeContributions() {
     return runtimeStrategyContributions(fulltextStrategy, fulltextTableName);
   }
+  function cacheInitializedSignature(key, signature) {
+    if (!uncacheableKeys.has(key)) {
+      initializedSignatures.set(key, signature);
+    }
+  }
   async function materializeOne(graphId, contribution, signature, existing, options) {
     const force = options?.force === true;
     const identity = identityOf(graphId, contribution);
@@ -305,6 +403,7 @@ function createContributionMaterializer(deps) {
   }
   async function ensureContributions(graphId, contributions, options) {
     const force = options?.force === true;
+    const bypassCache = options?.bypassCache === true;
     const entries = await Promise.all(
       contributions.map(async (contribution) => {
         const key = contributionKey(graphId, contribution);
@@ -315,8 +414,14 @@ function createContributionMaterializer(deps) {
         };
       })
     );
-    const pending = force ? entries : entries.filter(
-      (entry) => initializedSignatures.get(entry.key) !== entry.signature
+    if (bypassCache) {
+      for (const entry of entries) {
+        uncacheableKeys.add(entry.key);
+        initializedSignatures.delete(entry.key);
+      }
+    }
+    const pending = force || bypassCache ? entries : entries.filter(
+      (entry) => uncacheableKeys.has(entry.key) || initializedSignatures.get(entry.key) !== entry.signature
     );
     if (pending.length === 0) return;
     const initialRead = force ? void 0 : await readMarkerRows(graphId);
@@ -327,7 +432,7 @@ function createContributionMaterializer(deps) {
       ) === "initialized"
     )) {
       for (const entry of pending) {
-        initializedSignatures.set(entry.key, entry.signature);
+        cacheInitializedSignature(entry.key, entry.signature);
       }
       return;
     }
@@ -348,7 +453,7 @@ function createContributionMaterializer(deps) {
         }
       );
       if (outcome === "materialized") {
-        initializedSignatures.set(entry.key, entry.signature);
+        cacheInitializedSignature(entry.key, entry.signature);
       }
     }
   }
@@ -364,7 +469,7 @@ function createContributionMaterializer(deps) {
       })
     );
     const pending = entries.filter(
-      (entry) => initializedSignatures.get(entry.key) !== entry.signature
+      (entry) => uncacheableKeys.has(entry.key) || initializedSignatures.get(entry.key) !== entry.signature
     );
     if (pending.length === 0) return;
     const read = await readMarkerRows(graphId);
@@ -384,7 +489,7 @@ function createContributionMaterializer(deps) {
           details: { logicalName: contribution.logicalName }
         });
       }
-      initializedSignatures.set(key, signature);
+      cacheInitializedSignature(key, signature);
     }
   }
   async function ensureRuntimeContributions(graphId) {
@@ -420,15 +525,123 @@ function createContributionMaterializer(deps) {
       await assertContributions(graphId, contributions);
     }
   }
-  async function dropVectorSlot(slot) {
+  function verificationTargetsByGraph(graphId, vectorSlots) {
+    const targets = /* @__PURE__ */ new Map();
+    function addTarget(id, target) {
+      const existing = targets.get(id);
+      if (existing === void 0) targets.set(id, [target]);
+      else existing.push(target);
+    }
+    for (const contribution of runtimeContributions()) {
+      addTarget(graphId, { contribution });
+    }
+    const { vectorStrategy } = deps;
+    if (vectorStrategy !== void 0) {
+      for (const slot of vectorSlots) {
+        for (const contribution of vectorStrategy.ownedTables(slot)) {
+          addTarget(slot.graphId, {
+            contribution,
+            kind: slot.nodeKind,
+            fieldPath: slot.fieldPath
+          });
+        }
+      }
+    }
+    return targets;
+  }
+  async function diagnoseContributions(graphId, vectorSlots) {
+    const targetsByGraph = verificationTargetsByGraph(graphId, vectorSlots);
+    const probes = /* @__PURE__ */ new Map();
+    function tableExists(tableName) {
+      const pending = probes.get(tableName);
+      if (pending !== void 0) return pending;
+      const probe = deps.tableExists(tableName);
+      probes.set(tableName, probe);
+      return probe;
+    }
+    const diagnosed = [];
+    for (const [id, targets] of targetsByGraph) {
+      const read = await readMarkerRows(id);
+      const rows = read.kind === "rows" ? read.rows : /* @__PURE__ */ new Map();
+      for (const { contribution, kind, fieldPath } of targets) {
+        const key = contributionKey(id, contribution);
+        const row = rows.get(key);
+        const state = diagnoseContribution(
+          row,
+          await resolveContributionSignature(key, contribution),
+          await tableExists(contribution.tableName)
+        );
+        if (state === void 0) continue;
+        diagnosed.push({
+          graphId: id,
+          contribution,
+          diagnostic: {
+            owner: contribution.owner,
+            logicalName: contribution.logicalName,
+            physicalName: contribution.tableName,
+            ...kind === void 0 ? {} : { kind },
+            ...fieldPath === void 0 ? {} : { fieldPath },
+            state,
+            // The recorded reason, carried through verbatim. `state` folds
+            // several marker verdicts together because they share a repair;
+            // this is what keeps the fold from also discarding the one thing
+            // the catalog can never tell the operator.
+            ...row?.lastError === void 0 ? {} : { lastError: row.lastError }
+          }
+        });
+      }
+    }
+    return diagnosed;
+  }
+  async function verifyContributions(graphId, vectorSlots) {
+    const diagnosed = await diagnoseContributions(graphId, vectorSlots);
+    return diagnosed.map((entry) => entry.diagnostic);
+  }
+  async function repairContributions(graphId, vectorSlots) {
+    const diagnosed = await diagnoseContributions(graphId, vectorSlots);
+    const results = [];
+    for (const { graphId: targetGraphId, contribution, diagnostic } of diagnosed) {
+      if (diagnostic.state === "stale" || diagnostic.state === "orphaned-marker") {
+        results.push({ diagnostic, status: "requires-rebuild" });
+        continue;
+      }
+      try {
+        await ensureContributions(targetGraphId, [contribution], {
+          bypassCache: true
+        });
+        results.push({ diagnostic, status: "repaired" });
+      } catch (error) {
+        results.push({
+          diagnostic,
+          status: "failed",
+          error: error instanceof Error ? error.message : String(error)
+        });
+      }
+    }
+    return {
+      results,
+      remaining: await verifyContributions(graphId, vectorSlots)
+    };
+  }
+  function evictVectorSlot(slot) {
     if (deps.vectorStrategy === void 0) return;
     for (const contribution of deps.vectorStrategy.ownedTables(slot)) {
-      await deps.deleteMarker(identityOf(slot.graphId, contribution));
       const key = contributionKey(slot.graphId, contribution);
+      uncacheableKeys.add(key);
       initializedSignatures.delete(key);
       computedSignatures.delete(key);
     }
   }
+  async function dropVectorSlot(slot) {
+    if (deps.vectorStrategy === void 0) return;
+    try {
+      for (const contribution of deps.vectorStrategy.ownedTables(slot)) {
+        await deps.deleteMarker(identityOf(slot.graphId, contribution));
+      }
+    } finally {
+      evictVectorSlot(slot);
+    }
+  }
   return {
     ensureRuntimeContributions,
     assertInitialized,
@@ -436,7 +649,10 @@ function createContributionMaterializer(deps) {
     ensureVectorSlots,
     assertVectorSlot,
     assertVectorSlots,
-    dropVectorSlot
+    dropVectorSlot,
+    evictVectorSlot,
+    verifyContributions,
+    repairContributions
   };
 }
 var SQLITE_INDEX_MAT_TIMESTAMPS = {
@@ -788,6 +1004,19 @@ function buildCountNodesByKind(tables, params) {
     WHERE ${whereClause}
   `;
 }
+function buildIdSetCondition(column, ids) {
+  return sql`${column} IN (${sql.join(
+    ids.map((id) => sql`${id}`),
+    sql`, `
+  )})`;
+}
+function buildEdgeOrdering(tables, orderBy) {
+  const { edges } = tables;
+  return orderBy === "id" ? { qualified: sql`${edges.id} ASC`, bare: sql.raw(`"id" ASC`) } : {
+    qualified: sql`${edges.createdAt} DESC, ${edges.id} DESC`,
+    bare: sql.raw(`"created_at" DESC, "id" DESC`)
+  };
+}
 function buildFindEdgesByKind(tables, params) {
   const { edges } = tables;
   const conditions = [
@@ -811,7 +1040,10 @@ function buildFindEdgesByKind(tables, params) {
     conditions.push(sql`${edges.id} > ${params.after}`);
   }
   const whereClause = sql.join(conditions, sql` AND `);
-  const orderByClause = params.orderBy === "id" ? sql`${edges.id} ASC` : sql`${edges.createdAt} DESC, ${edges.id} DESC`;
+  const { qualified: orderByClause } = buildEdgeOrdering(
+    tables,
+    params.orderBy
+  );
   if (params.limit !== void 0 && params.offset !== void 0) {
     return sql`
       SELECT * FROM ${edges}
@@ -834,6 +1066,94 @@ function buildFindEdgesByKind(tables, params) {
     ORDER BY ${orderByClause}
   `;
 }
+function buildFindEdgesByEndpointSet(tables, params, endpointIds) {
+  const { edges } = tables;
+  const fromSide = params.side === "from";
+  const kindColumn = fromSide ? edges.fromKind : edges.toKind;
+  const idColumn = fromSide ? edges.fromId : edges.toId;
+  const whereClause = sql.join(
+    [
+      sql`${edges.graphId} = ${params.graphId}`,
+      sql`${edges.kind} = ${params.kind}`,
+      ...buildTemporalConditions(edges, params),
+      sql`${kindColumn} = ${params.endpointKind}`,
+      buildIdSetCondition(idColumn, endpointIds)
+    ],
+    sql` AND `
+  );
+  const { qualified: orderByClause, bare: derivedOrderByClause } = buildEdgeOrdering(tables, void 0);
+  if (params.limitPerEndpoint === void 0) {
+    return sql`
+      SELECT * FROM ${edges}
+      WHERE ${whereClause}
+      ORDER BY ${orderByClause}
+    `;
+  }
+  const ranked = sql`
+    SELECT *, ROW_NUMBER() OVER (
+      PARTITION BY ${idColumn} ORDER BY ${orderByClause}
+    ) AS endpoint_rank
+    FROM ${edges}
+    WHERE ${whereClause}
+  `;
+  return sql`
+    SELECT * FROM (${ranked}) AS ranked_edges
+    WHERE endpoint_rank <= ${params.limitPerEndpoint}
+    ORDER BY ${derivedOrderByClause}
+  `;
+}
+function buildFindEdgesByHeterogeneousEndpointSet(tables, params, endpoints, edgeKinds) {
+  const { edges } = tables;
+  const fromSide = params.side === "from";
+  const kindColumn = fromSide ? edges.fromKind : edges.toKind;
+  const idColumn = fromSide ? edges.fromId : edges.toId;
+  const requestedKind = sql.raw(`requested_endpoints."endpoint_kind"`);
+  const requestedId = sql.raw(`requested_endpoints."endpoint_id"`);
+  const requestedRows = sql.join(
+    endpoints.map((endpoint) => sql`(${endpoint.kind}, ${endpoint.id})`),
+    sql`, `
+  );
+  const whereClause = sql.join(
+    [
+      sql`${edges.graphId} = ${params.graphId}`,
+      buildIdSetCondition(edges.kind, edgeKinds),
+      ...buildTemporalConditions(edges, params)
+    ],
+    sql` AND `
+  );
+  const joinClause = sql`
+    FROM ${edges}
+    INNER JOIN requested_endpoints
+      ON ${kindColumn} = ${requestedKind}
+     AND ${idColumn} = ${requestedId}
+    WHERE ${whereClause}
+  `;
+  const { qualified: orderByClause, bare: derivedOrderByClause } = buildEdgeOrdering(tables, void 0);
+  if (params.limitPerEndpoint === void 0) {
+    return sql`
+      WITH requested_endpoints(endpoint_kind, endpoint_id) AS (
+        VALUES ${requestedRows}
+      )
+      SELECT ${edges}.*
+      ${joinClause}
+      ORDER BY ${orderByClause}
+    `;
+  }
+  const ranked = sql`
+    SELECT ${edges}.*, ROW_NUMBER() OVER (
+      PARTITION BY ${kindColumn}, ${idColumn} ORDER BY ${orderByClause}
+    ) AS endpoint_rank
+    ${joinClause}
+  `;
+  return sql`
+    WITH requested_endpoints(endpoint_kind, endpoint_id) AS (
+      VALUES ${requestedRows}
+    )
+    SELECT * FROM (${ranked}) AS ranked_edges
+    WHERE endpoint_rank <= ${params.limitPerEndpoint}
+    ORDER BY ${derivedOrderByClause}
+  `;
+}
 function buildCountEdgesByKind(tables, params) {
   const { edges } = tables;
   const conditions = [
@@ -1243,6 +1563,37 @@ function buildUpdateNode(tables, params, timestamp) {
     RETURNING *
   `;
 }
+function buildUpdateNodeSet(tables, dialect, params, timestamp) {
+  const { nodes } = tables;
+  const adapter = getDialect(dialect);
+  const patchedProps = toDrizzleSql(
+    adapter.jsonSetProperties(
+      sql$1.identifier(nodes.props.name),
+      params.patch,
+      params.unsetProperties ?? []
+    ),
+    dialect
+  );
+  const candidateIds = toDrizzleSql(params.candidateIds, dialect);
+  const candidateIdColumn = toDrizzleSql(
+    sql$1.identifier(params.candidateIdColumn),
+    dialect
+  );
+  return sql`
+    UPDATE ${nodes}
+    SET ${quotedColumn(nodes.props)} = ${patchedProps},
+        ${quotedColumn(nodes.updatedAt)} = ${timestamp},
+        ${quotedColumn(nodes.version)} = ${quotedColumn(nodes.version)} + 1
+    WHERE ${nodes.graphId} = ${params.graphId}
+      AND ${nodes.kind} = ${params.kind}
+      AND ${nodes.deletedAt} IS NULL
+      AND ${nodes.id} IN (
+        SELECT ${candidateIdColumn}
+        FROM (${candidateIds}) AS tg_set_candidates
+      )
+    RETURNING *
+  `;
+}
 function buildDeleteNode(tables, params, timestamp) {
   const { nodes } = tables;
   return sql`
@@ -1478,12 +1829,23 @@ function buildDeleteUnique(tables, params, timestamp) {
       AND ${uniques.deletedAt} IS NULL
   `;
 }
-function buildHardDeleteUniquesByNode(tables, graphId, nodeId) {
+function buildHardDeleteUniquesByNode(tables, graphId, concreteKind, nodeId) {
+  return buildHardDeleteUniquesByNodeIds(tables, {
+    graphId,
+    concreteKind,
+    nodeIds: [nodeId]
+  });
+}
+function buildHardDeleteUniquesByNodeIds(tables, params) {
   const { uniques } = tables;
   return sql`
     DELETE FROM ${uniques}
-    WHERE ${uniques.graphId} = ${graphId}
-      AND ${uniques.nodeId} = ${nodeId}
+    WHERE ${uniques.graphId} = ${params.graphId}
+      AND ${uniques.concreteKind} = ${params.concreteKind}
+      AND ${uniques.nodeId} IN (${sql.join(
+    params.nodeIds.map((nodeId) => sql`${nodeId}`),
+    sql`, `
+  )})
   `;
 }
 function buildCheckUnique(tables, params) {
@@ -1571,9 +1933,12 @@ var COMMON_TABLE_OPERATION_BUILDERS = {
   buildFindNodesByKind,
   buildCountNodesByKind,
   buildFindEdgesByKind,
+  buildFindEdgesByEndpointSet,
+  buildFindEdgesByHeterogeneousEndpointSet,
   buildCountEdgesByKind,
   buildDeleteUnique,
   buildHardDeleteUniquesByNode,
+  buildHardDeleteUniquesByNodeIds,
   buildCheckUnique,
   buildCheckUniqueBatch,
   buildGetSchemaVersion
@@ -1584,6 +1949,7 @@ function createCommonOperationStrategy(tables, dialect, fulltextStrategy) {
     COMMON_TABLE_OPERATION_BUILDERS
   );
   const fulltextTable = tables.fulltextTableName;
+  const contributionMaterializations = tables.contributionMaterializations;
   const fulltextBuilders = {
     buildUpsertFulltext: (params, timestamp) => fulltextStrategy.buildUpsert(fulltextTable, params, timestamp).map((statement) => toDrizzleSql(statement, dialect)),
     buildDeleteFulltext: (params) => fulltextStrategy.buildDelete(fulltextTable, params).map((statement) => toDrizzleSql(statement, dialect)),
@@ -1650,9 +2016,22 @@ function createCommonOperationStrategy(tables, dialect, fulltextStrategy) {
       });
     }
   };
+  function buildDeleteContributionMaterialization(identity) {
+    return sql`
+      DELETE FROM ${contributionMaterializations}
+      WHERE graph_id = ${identity.graphId}
+        AND logical_name = ${identity.logicalName}
+        AND owner = ${identity.owner}
+        AND table_name = ${identity.tableName}
+    `;
+  }
   return {
     ...tableOperations,
     ...fulltextBuilders,
+    buildUpdateNodeSet(params, timestamp) {
+      return buildUpdateNodeSet(tables, dialect, params, timestamp);
+    },
+    buildDeleteContributionMaterialization,
     buildInsertUnique(params) {
       return buildInsertUnique(tables, dialect, params);
     },
@@ -1735,6 +2114,9 @@ function assertAdoptedDialect(externalTx, brand, backend) {
 }
 function verifyExpectedActiveVersion(graphId, expected, actualActiveVersion) {
   const expectedVersion = expected.kind === "active" ? expected.version : 0;
+  assertActiveSchemaVersion(graphId, expectedVersion, actualActiveVersion);
+}
+function assertActiveSchemaVersion(graphId, expectedVersion, actualActiveVersion) {
   if (actualActiveVersion !== expectedVersion) {
     throw new StaleVersionError({
       graphId,
@@ -1743,17 +2125,58 @@ function verifyExpectedActiveVersion(graphId, expected, actualActiveVersion) {
     });
   }
 }
+async function commitSchemaVersionIfKindsEmpty(backend, params, probes) {
+  const [existing, active] = await Promise.all([
+    backend.getSchemaVersion(params.graphId, params.version),
+    backend.getActiveSchema(params.graphId)
+  ]);
+  if (existing !== void 0 && (existing.is_active || existing.schema_hash !== params.schemaHash)) {
+    return {
+      status: "committed",
+      row: await backend.commitSchemaVersion(params)
+    };
+  }
+  verifyExpectedActiveVersion(
+    params.graphId,
+    params.expected,
+    active?.version ?? 0
+  );
+  const populated = [];
+  for (const probe of probes) {
+    const count = probe.entity === "node" ? await backend.countNodesByKind({
+      graphId: params.graphId,
+      kind: probe.kind
+    }) : await backend.countEdgesByKind({
+      graphId: params.graphId,
+      kind: probe.kind
+    });
+    if (count > 0) populated.push({ ...probe, count });
+  }
+  if (populated.length > 0) {
+    return { status: "populated", kinds: populated };
+  }
+  return {
+    status: "committed",
+    row: await backend.commitSchemaVersion(params)
+  };
+}
 function createCommonOperationBackend(options) {
-  const { batchConfig, execution, operationStrategy, rowMappers } = options;
+  const {
+    batchConfig,
+    execution,
+    maxBindParameters,
+    operationStrategy,
+    rowMappers
+  } = options;
   const nowIso2 = options.nowIso ?? nowIso;
-  const requiredClearTableExists = createCachedTableExistence(
+  const tableExists = createCachedTableExistence(
     (tableName) => execution.execGet(
       operationStrategy.buildTableExists(tableName)
     ),
     options.tableExistenceCache
   );
   async function runIgnorableClearStatement(statement) {
-    if (statement.ignoreMissingTable === true && statement.requiredTableName !== void 0 && !await requiredClearTableExists(statement.requiredTableName)) {
+    if (statement.ignoreMissingTable === true && statement.requiredTableName !== void 0 && !await tableExists(statement.requiredTableName)) {
       return;
     }
     await execution.execRun(statement.query);
@@ -1765,6 +2188,10 @@ function createCommonOperationBackend(options) {
     return row === void 0 ? 0 : rowMappers.toSchemaVersionRow(row).version;
   }
   return {
+    tableExists,
+    async executeSchemaDdl(ddl) {
+      await execution.execRun(asCompiledStatementSql(sql$1.raw(ddl)));
+    },
     async executeStatement(query) {
       await execution.execRun(query);
     },
@@ -1842,6 +2269,25 @@ function createCommonOperationBackend(options) {
         );
       return rowMappers.toNodeRow(row);
     },
+    async updateNodeSet(params) {
+      if (Object.keys(params.patch).length === 0 && (params.unsetProperties?.length ?? 0) === 0) {
+        throw new ConfigurationError(
+          "Set-based node update requires at least one property",
+          { operation: "updateNodeSet", kind: params.kind }
+        );
+      }
+      if (params.candidateIdColumn.length === 0) {
+        throw new ConfigurationError(
+          "Set-based node update requires a candidate id column",
+          { operation: "updateNodeSet", kind: params.kind }
+        );
+      }
+      const timestamp = nowIso2();
+      const query = operationStrategy.buildUpdateNodeSet(params, timestamp);
+      const rows = await execution.execAll(query);
+      const updatedRows = rows.map((row) => rowMappers.toNodeRow(row));
+      return { affectedCount: updatedRows.length, rows: updatedRows };
+    },
     async deleteNode(params) {
       const timestamp = nowIso2();
       const query = operationStrategy.buildDeleteNode(params, timestamp);
@@ -1859,6 +2305,7 @@ function createCommonOperationBackend(options) {
     async hardDeleteNode(params) {
       const deleteUniquesQuery = operationStrategy.buildHardDeleteUniquesByNode(
         params.graphId,
+        params.kind,
         params.id
       );
       await execution.execRun(deleteUniquesQuery);
@@ -2017,6 +2464,37 @@ function createCommonOperationBackend(options) {
       const rows = await execution.execAll(query);
       return rows.map((row) => rowMappers.toEdgeRow(row));
     },
+    async findEdgesByEndpointSet(params) {
+      const ids = resolveEdgeEndpointIds(params);
+      const edgeRows = [];
+      for (const idChunk of chunk(
+        ids,
+        batchConfig.findEdgesEndpointChunkSize
+      )) {
+        const query = operationStrategy.buildFindEdgesByEndpointSet(
+          params,
+          idChunk
+        );
+        const rows = await execution.execAll(query);
+        for (const row of rows) edgeRows.push(rowMappers.toEdgeRow(row));
+      }
+      return edgeRows;
+    },
+    async findEdgesByHeterogeneousEndpointSet(params) {
+      const { edgeKinds, endpoints, endpointChunkSize } = resolveHeterogeneousEdgeRead(params, maxBindParameters);
+      if (edgeKinds.length === 0 || endpoints.length === 0) return [];
+      const edgeRows = [];
+      for (const endpointChunk of chunk(endpoints, endpointChunkSize)) {
+        const query = operationStrategy.buildFindEdgesByHeterogeneousEndpointSet(
+          params,
+          endpointChunk,
+          edgeKinds
+        );
+        const rows = await execution.execAll(query);
+        for (const row of rows) edgeRows.push(rowMappers.toEdgeRow(row));
+      }
+      return edgeRows;
+    },
     async countEdgesByKind(params) {
       const query = operationStrategy.buildCountEdgesByKind(params);
       const row = await execution.execGet(query);
@@ -2087,6 +2565,19 @@ function createCommonOperationBackend(options) {
       const query = operationStrategy.buildDeleteUnique(params, timestamp);
       await execution.execRun(query);
     },
+    async hardDeleteUniquesByNodeIds(params) {
+      const nodeIds = [...new Set(params.nodeIds)];
+      for (const chunk2 of chunk(
+        nodeIds,
+        batchConfig.uniqueDeleteChunkSize
+      )) {
+        const query = operationStrategy.buildHardDeleteUniquesByNodeIds({
+          ...params,
+          nodeIds: chunk2
+        });
+        await execution.execRun(query);
+      }
+    },
     async checkUnique(params) {
       const query = operationStrategy.buildCheckUnique(params);
       const row = await execution.execGet(query);
@@ -2487,6 +2978,6 @@ function getOrCreateLru(cache, key, cacheMax, create) {
   return value;
 }
 
-export { EMBEDDING_UPSERT_PARAM_COUNT, POSTGRES_CONTRIBUTION_MAT_TIMESTAMPS, POSTGRES_INDEX_MAT_TIMESTAMPS, POSTGRES_KIND_REMOVAL_TIMESTAMPS, SQLITE_CONTRIBUTION_MAT_TIMESTAMPS, SQLITE_INDEX_MAT_TIMESTAMPS, SQLITE_KIND_REMOVAL_TIMESTAMPS, analyzeImportedTables, assertAdoptedDialect, assertTrustedImportDatabaseEmpty, buildContributionInsertValues, buildContributionOnConflictSet, buildKindRemovalInsertValues, buildKindRemovalOnConflictSet, buildLiveNodeCandidates, buildMaterializationInsertValues, buildMaterializationOnConflictSet, createCachedTableExistence, createCommonOperationBackend, createContributionMaterializer, createPostgresOperationStrategy, createPostgresTrustedImportSession, createSqliteOperationStrategy, createSqliteTrustedImportSession, gateFulltext, gateFulltextMethods, getOrCreateLru, lockPostgresTrustedImportTables, mapContributionMaterializationRow, mapHybridSearchRow, mapKindRemovalRow, mapMaterializationRow, mapVectorWriteError, restoreSecondaryIndexes, suspendPostgresSecondaryIndexes, suspendSqliteSecondaryIndexes, vectorSlotFromCreateIndexParams, vectorSlotFromDropIndexParams, vectorSlotFromParams };
-//# sourceMappingURL=chunk-HHBKGPEI.js.map
-//# sourceMappingURL=chunk-HHBKGPEI.js.map
+export { EMBEDDING_UPSERT_PARAM_COUNT, FIND_EDGES_ENDPOINT_FIXED_PARAM_COUNT, POSTGRES_CONTRIBUTION_MAT_TIMESTAMPS, POSTGRES_INDEX_MAT_TIMESTAMPS, POSTGRES_KIND_REMOVAL_TIMESTAMPS, SQLITE_CONTRIBUTION_MAT_TIMESTAMPS, SQLITE_INDEX_MAT_TIMESTAMPS, SQLITE_KIND_REMOVAL_TIMESTAMPS, analyzeImportedTables, assertActiveSchemaVersion, assertAdoptedDialect, assertTrustedImportDatabaseEmpty, buildContributionInsertValues, buildContributionOnConflictSet, buildKindRemovalInsertValues, buildKindRemovalOnConflictSet, buildLiveNodeCandidates, buildMaterializationInsertValues, buildMaterializationOnConflictSet, commitSchemaVersionIfKindsEmpty, createCachedTableExistence, createCommonOperationBackend, createContributionMaterializer, createPostgresOperationStrategy, createPostgresTrustedImportSession, createSqliteOperationStrategy, createSqliteTrustedImportSession, gateFulltext, gateFulltextMethods, getOrCreateLru, lockPostgresTrustedImportTables, mapContributionMaterializationRow, mapHybridSearchRow, mapKindRemovalRow, mapMaterializationRow, mapVectorWriteError, restoreSecondaryIndexes, suspendPostgresSecondaryIndexes, suspendSqliteSecondaryIndexes, tableExistsFromRow, vectorSlotFromCreateIndexParams, vectorSlotFromDropIndexParams, vectorSlotFromParams };
+//# sourceMappingURL=chunk-DXEEHSGN.js.map
+//# sourceMappingURL=chunk-DXEEHSGN.js.map