@nicia-ai/typegraph 0.42.1 → 0.44.0

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

@@ -1,16 +1,36 @@
-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-PHXITZE4.js';
+import { runtimeStrategyContributions } from './chunk-7G32LIQM.js';
+import { toDrizzleSql } from './chunk-GWEDD3DH.js';
 import { chunk } from './chunk-35S6P5ZU.js';
-import { createBackendOverlay } from './chunk-UZLEQFTV.js';
+import { createBackendOverlay } from './chunk-FMMIX6N4.js';
 import { sortedReplacer } from './chunk-UR7W5YQK.js';
-import { parseDimensionMismatch, isMissingTableError } from './chunk-CUPJL6TS.js';
+import { parseDimensionMismatch, isMissingTableError } from './chunk-B75XRV3O.js';
 import { sha256Hex } from './chunk-K34OPSJK.js';
-import { sql as sql$1, asCompiledStatementSql, isSqlFragment } from './chunk-M4GYQF2H.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;
+function resolveEdgeEndpointIds(params) {
+  const { limitPerEndpoint } = params;
+  if (limitPerEndpoint !== void 0 && (!Number.isInteger(limitPerEndpoint) || limitPerEndpoint <= 0)) {
+    throw new ConfigurationError(
+      `findEdgesByEndpointSet \`limitPerEndpoint\` must be a positive integer, received ${String(limitPerEndpoint)}.`,
+      {
+        code: "EDGE_ENDPOINT_SET_INVALID",
+        graphId: params.graphId,
+        kind: params.kind
+      },
+      {
+        suggestion: "Pass a positive integer to cap each endpoint's rows, or omit it for an unbounded read."
+      }
+    );
+  }
+  return [...new Set(params.endpointIds)];
+}
+
 // src/backend/live-node-candidates.ts
 function buildLiveNodeCandidates(nodesTableName, graphId, nodeKind, now) {
   const nodes = sql$1.identifier(nodesTableName);
@@ -133,6 +153,29 @@ 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";
+  }
+  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 +248,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 +281,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);
@@ -316,7 +365,7 @@ function createContributionMaterializer(deps) {
       })
     );
     const pending = force ? entries : 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 initialRead = force ? void 0 : await readMarkerRows(graphId);
@@ -327,7 +376,7 @@ function createContributionMaterializer(deps) {
       ) === "initialized"
     )) {
       for (const entry of pending) {
-        initializedSignatures.set(entry.key, entry.signature);
+        cacheInitializedSignature(entry.key, entry.signature);
       }
       return;
     }
@@ -348,7 +397,7 @@ function createContributionMaterializer(deps) {
         }
       );
       if (outcome === "materialized") {
-        initializedSignatures.set(entry.key, entry.signature);
+        cacheInitializedSignature(entry.key, entry.signature);
       }
     }
   }
@@ -364,7 +413,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 +433,7 @@ function createContributionMaterializer(deps) {
           details: { logicalName: contribution.logicalName }
         });
       }
-      initializedSignatures.set(key, signature);
+      cacheInitializedSignature(key, signature);
     }
   }
   async function ensureRuntimeContributions(graphId) {
@@ -420,15 +469,85 @@ function createContributionMaterializer(deps) {
       await assertContributions(graphId, contributions);
     }
   }
-  async function dropVectorSlot(slot) {
+  async function verifyContributions(graphId, vectorSlots) {
+    const targetsByGraph = /* @__PURE__ */ new Map();
+    function addTarget(id, target) {
+      const existing = targetsByGraph.get(id);
+      if (existing === void 0) targetsByGraph.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
+          });
+        }
+      }
+    }
+    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 diagnostics = [];
+    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;
+        diagnostics.push({
+          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 diagnostics;
+  }
+  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 +555,9 @@ function createContributionMaterializer(deps) {
     ensureVectorSlots,
     assertVectorSlot,
     assertVectorSlots,
-    dropVectorSlot
+    dropVectorSlot,
+    evictVectorSlot,
+    verifyContributions
   };
 }
 var SQLITE_INDEX_MAT_TIMESTAMPS = {
@@ -788,6 +909,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 +945,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 +971,42 @@ 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 buildCountEdgesByKind(tables, params) {
   const { edges } = tables;
   const conditions = [
@@ -1571,6 +1744,7 @@ var COMMON_TABLE_OPERATION_BUILDERS = {
   buildFindNodesByKind,
   buildCountNodesByKind,
   buildFindEdgesByKind,
+  buildFindEdgesByEndpointSet,
   buildCountEdgesByKind,
   buildDeleteUnique,
   buildHardDeleteUniquesByNode,
@@ -1584,6 +1758,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 +1825,19 @@ 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,
+    buildDeleteContributionMaterialization,
     buildInsertUnique(params) {
       return buildInsertUnique(tables, dialect, params);
     },
@@ -1735,6 +1920,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 +1931,52 @@ 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 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 +1988,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);
     },
@@ -2017,6 +2244,22 @@ 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 countEdgesByKind(params) {
       const query = operationStrategy.buildCountEdgesByKind(params);
       const row = await execution.execGet(query);
@@ -2487,6 +2730,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-SQRD2CYF.js.map
+//# sourceMappingURL=chunk-SQRD2CYF.js.map