@nicia-ai/typegraph 0.50.0 → 0.51.1

package/dist/chunk-UYKDYE5D.cjs

@@ -0,0 +1,12 @@
+'use strict';
+
+var chunkH5IJSROF_cjs = require('./chunk-H5IJSROF.cjs');
+
+// src/query/dialect/vector/pagination.ts
+function vectorPageClause(limit, offset) {
+  return offset === void 0 || offset === 0 ? chunkH5IJSROF_cjs.sql`LIMIT ${limit}` : chunkH5IJSROF_cjs.sql`LIMIT ${limit} OFFSET ${offset}`;
+}
+
+exports.vectorPageClause = vectorPageClause;
+//# sourceMappingURL=chunk-UYKDYE5D.cjs.map
+//# sourceMappingURL=chunk-UYKDYE5D.cjs.map

package/dist/{chunk-KWNWG4RC.cjs.map → chunk-UYKDYE5D.cjs.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/query/dialect/vector/pagination.ts"],"names":["sql"],"mappings":";;;;;AAcO,SAAS,gBAAA,CAAiB,OAAe,MAAA,EAA8B;AAC5E,EAAA,OAAO,MAAA,KAAW,MAAA,IAAa,MAAA,KAAW,CAAA,GACtCA,qBAAA,CAAA,MAAA,EAAY,KAAK,CAAA,CAAA,GACjBA,qBAAA,CAAA,MAAA,EAAY,KAAK,CAAA,QAAA,EAAW,MAAM,CAAA,CAAA;AACxC","file":"chunk-KWNWG4RC.cjs","sourcesContent":["/**\n * Shared vector-search pagination clause.\n *\n * Every vector strategy pages its ordered relevance scan the same way: emit a\n * bare `LIMIT` for the first page (`offset` unset or `0`), and `LIMIT … OFFSET`\n * only when a non-zero offset must discard the leading rows. The three engines'\n * `buildSearch` methods each repeated this ternary verbatim; it lives here once\n * so the emitted clause can never drift between dialects.\n *\n * `limit` and `offset` ride as bound parameters (never interpolated), so the\n * clause — string and bound values alike — is identical across engines.\n */\nimport { sql, type SqlFragment } from \"../../sql-fragment\";\n\nexport function vectorPageClause(limit: number, offset?: number): SqlFragment {\n  return offset === undefined || offset === 0 ?\n      sql`LIMIT ${limit}`\n    : sql`LIMIT ${limit} OFFSET ${offset}`;\n}\n"]}
+{"version":3,"sources":["../src/query/dialect/vector/pagination.ts"],"names":["sql"],"mappings":";;;;;AAcO,SAAS,gBAAA,CAAiB,OAAe,MAAA,EAA8B;AAC5E,EAAA,OAAO,MAAA,KAAW,MAAA,IAAa,MAAA,KAAW,CAAA,GACtCA,qBAAA,CAAA,MAAA,EAAY,KAAK,CAAA,CAAA,GACjBA,qBAAA,CAAA,MAAA,EAAY,KAAK,CAAA,QAAA,EAAW,MAAM,CAAA,CAAA;AACxC","file":"chunk-UYKDYE5D.cjs","sourcesContent":["/**\n * Shared vector-search pagination clause.\n *\n * Every vector strategy pages its ordered relevance scan the same way: emit a\n * bare `LIMIT` for the first page (`offset` unset or `0`), and `LIMIT … OFFSET`\n * only when a non-zero offset must discard the leading rows. The three engines'\n * `buildSearch` methods each repeated this ternary verbatim; it lives here once\n * so the emitted clause can never drift between dialects.\n *\n * `limit` and `offset` ride as bound parameters (never interpolated), so the\n * clause — string and bound values alike — is identical across engines.\n */\nimport { sql, type SqlFragment } from \"../../sql-fragment\";\n\nexport function vectorPageClause(limit: number, offset?: number): SqlFragment {\n  return offset === undefined || offset === 0 ?\n      sql`LIMIT ${limit}`\n    : sql`LIMIT ${limit} OFFSET ${offset}`;\n}\n"]}

package/dist/{chunk-FX5ZW6PN.js → chunk-VAAC7L57.js}

@@ -1,9 +1,10 @@
-import { withRecordedRelationsPrecondition, projectGraphBackend, deriveBackend, groupBy, chunk } from './chunk-IRPYOHRC.js';
-import { createSqlSchema } from './chunk-Y55DLLEG.js';
-import { runOptionallyInTransaction, rowPropsToJsonText } from './chunk-PALYTHGM.js';
+import { withRecordedRelationsPrecondition, projectGraphBackend, deriveBackend, groupBy, chunk } from './chunk-QG5VEOKX.js';
+import { statementExecutionVerdict, recordedRevisionOriginsVerdict, assertRecursiveTraversal, batchPointReadVerdict } from './chunk-XORONCV3.js';
+import { resolveWriteFencePlan, requireWriteFence, recordedRevisionOriginsMembers, bindExtraIfReachable, BATCH_POINT_READ, runOptionallyInTransaction, createSqlSchema, rowPropsToJsonText } from './chunk-LKZDQ2B4.js';
 import { optionalRecordedInstantParts, createRecordedInstant, parseRecordedInstant, RECORDED_MAX_REVISION } from './chunk-6NKSE5AU.js';
 import { nowIso, canonicalizeDatabaseTimestamp } from './chunk-K46SDNQD.js';
-import { sql, asCompiledRowsSql, likeEscapeClause, asCompiledStatementSql, LIKE_ESCAPE_CHARACTER } from './chunk-46UGOVRW.js';
+import { likeEscapeClause, LIKE_ESCAPE_CHARACTER } from './chunk-4QKOZYMV.js';
+import { sql, asCompiledRowsSql, asCompiledStatementSql } from './chunk-7QFRK6PU.js';
 import { resolveFieldTypeInfoAtJsonPointer } from './chunk-W6OG3HDG.js';
 import { ConfigurationError, UnsupportedPredicateError, CompilerInvariantError, ValidationError } from './chunk-YDEJQWOL.js';
 import { normalizeJsonPointer, joinJsonPointers, jsonPointer } from './chunk-FWJKWH6U.js';
@@ -780,7 +781,7 @@ function assertCapturableBackend(backend) {
       }
     );
   }
-  if (backend.executeStatement === void 0) {
+  if (!statementExecutionVerdict(backend).supported) {
     throw new ConfigurationError(
       "history: true requires a backend that supports executeStatement.",
       { dialect: backend.dialect },
@@ -818,7 +819,7 @@ function assertRevisionTrackableBackend(backend) {
       }
     );
   }
-  if (backend.executeStatement === void 0) {
+  if (!statementExecutionVerdict(backend).supported) {
     throw new ConfigurationError(
       "revisionTracking: true requires a backend that supports executeStatement.",
       { dialect: backend.dialect },
@@ -836,7 +837,7 @@ function assertRevisionTrackableBackend(backend) {
       }
     );
   }
-  if (backend.ensureRevisionOriginsTable === void 0) {
+  if (!recordedRevisionOriginsVerdict(backend).supported) {
     throw new ConfigurationError(
       "revisionTracking: true requires a backend that can bootstrap revision origins.",
       { dialect: backend.dialect },
@@ -852,10 +853,6 @@ var RECORDED_MIN_REVISION = 0;
 var RECORDED_MIN_TIME = "1970-01-01T00:00:00.000Z";
 var RECORDED_CLOCK_ADVISORY_LOCK_NAMESPACE = "typegraph:recorded-clock";
 var RECORDED_GRAPH_WRITE_ADVISORY_LOCK_NAMESPACE = "typegraph:recorded-graph-write";
-var USES_RECORDED_GRAPH_ADVISORY_LOCK = {
-  postgres: true,
-  sqlite: false
-};
 function graphAdvisoryLockSql(namespace, graphId) {
   return sql`
     SELECT pg_advisory_xact_lock(
@@ -893,8 +890,16 @@ async function acquireRecordedGraphWriteLock(target, graphId) {
   );
 }
 async function lockRecordedGraphWrite(target, graphId, memo) {
-  if (!USES_RECORDED_GRAPH_ADVISORY_LOCK[target.dialect]) {
-    return graphWriteLockEvidence();
+  const plan = resolveWriteFencePlan(target);
+  const fence = requireWriteFence(
+    plan,
+    "recorded graph write",
+    "advisory-lock"
+  );
+  switch (fence.kind) {
+    case "engine-serialized": {
+      return graphWriteLockEvidence();
+    }
   }
   const effectiveMemo = memo ?? recordedGraphLockMemos.get(target);
   if (effectiveMemo === void 0) {
@@ -989,9 +994,8 @@ async function readRevisionOrigin(target, schema, graphId) {
   }
   return first.origin;
 }
-async function ensureRevisionOrigin(target, schema, graphId) {
-  const ensureTable = target.ensureRevisionOriginsTable;
-  if (ensureTable === void 0) {
+async function ensureRevisionOrigin(target, verdict, schema, graphId) {
+  if (!verdict.supported) {
     throw new ConfigurationError(
       "Revision tracking requires a backend that can bootstrap revision origins.",
       { dialect: target.dialect },
@@ -1000,6 +1004,7 @@ async function ensureRevisionOrigin(target, schema, graphId) {
       }
     );
   }
+  const { ensureRevisionOriginsTable: ensureTable } = recordedRevisionOriginsMembers(target, verdict);
   await ensureTable();
   const existing = await readRevisionOrigin(target, schema, graphId);
   if (existing !== void 0) return existing;
@@ -1042,14 +1047,20 @@ async function assertRecordedClockAdvanced(target, schema, graphId, revision) {
   );
 }
 async function lockRecordedClock(target, schema, graphId, ownsWriteLock) {
-  switch (target.dialect) {
-    case "postgres": {
+  const plan = resolveWriteFencePlan(target);
+  const fence = requireWriteFence(
+    plan,
+    "recorded clock allocation",
+    "advisory-lock"
+  );
+  switch (fence.kind) {
+    case "lock": {
       await target.execute(
         asCompiledRowsSql(recordedClockAdvisoryLockSql(graphId))
       );
       return;
     }
-    case "sqlite": {
+    case "engine-serialized": {
       if (ownsWriteLock) return;
       await executeStatement(
         target,
@@ -1061,9 +1072,6 @@ async function lockRecordedClock(target, schema, graphId, ownsWriteLock) {
       );
       return;
     }
-    default: {
-      target.dialect;
-    }
   }
 }
 async function allocateRecordedCommit(target, schema, graphId, ownsWriteLock, previousRevision) {
@@ -1241,6 +1249,10 @@ function identityAssertionSnapshotSource(schema, graphId, coordinate, relation)
   `;
 }
 function historicalIdentityReconstructionCtes(input) {
+  assertRecursiveTraversal(
+    input.recursiveTraversal,
+    "historical identity class read"
+  );
   const nodes = identityNodeSnapshotSource(
     input.schema,
     input.graphId,
@@ -1297,6 +1309,10 @@ var IDENTITY_PEER_CLASS_COLUMNS = sql.raw(
   ["seed_kind", "seed_id", "kind", "id"].join(", ")
 );
 function historicalIdentityPeerClassQuery(input) {
+  assertRecursiveTraversal(
+    input.recursiveTraversal,
+    "historical identity expansion"
+  );
   const reconstruction = historicalIdentityReconstructionCtes({
     ...input,
     seedSource: sql`SELECT DISTINCT a_kind, a_id FROM identity_edges`
@@ -1514,6 +1530,22 @@ function compileParameterizedStringPattern(op, parameter) {
     }
   }
 }
+function requireRecursiveTraversalVerdict(ctx, operation) {
+  const verdict = ctx.recursiveTraversal;
+  if (verdict === void 0) {
+    throw new CompilerInvariantError(
+      "recursive traversal verdict missing from compiler context",
+      { operation }
+    );
+  }
+  return verdict;
+}
+function assertRecursiveTraversalSupported(ctx, operation) {
+  assertRecursiveTraversal(
+    requireRecursiveTraversalVerdict(ctx, operation),
+    operation
+  );
+}
 function compilePredicateExpression(expr, ctx) {
   const { dialect } = ctx;
   const cteColumnPrefix = ctx.cteColumnPrefix;
@@ -2032,17 +2064,27 @@ async function getRowsByIds(ids, policy) {
 }
 
 // src/store/edge-fetch.ts
-async function getEdgeRowsByIds(backend, graphId, ids) {
+async function getEdgeRowsByIds(backend, verdict, graphId, ids) {
+  const bound = bindExtraIfReachable(
+    backend,
+    verdict.extras.getEdges,
+    BATCH_POINT_READ.id
+  );
   return getRowsByIds(ids, {
-    batch: backend.getEdges === void 0 ? void 0 : (batchIds) => requireDefined(backend.getEdges)(graphId, batchIds),
+    batch: bound === void 0 ? void 0 : ((batchIds) => bound.getEdges(graphId, batchIds)),
     one: (id) => backend.getEdge(graphId, id)
   });
 }
 
 // src/store/node-fetch.ts
-async function getNodeRowsByIds(backend, graphId, kind, ids) {
+async function getNodeRowsByIds(backend, verdict, graphId, kind, ids) {
+  const bound = bindExtraIfReachable(
+    backend,
+    verdict.extras.getNodes,
+    BATCH_POINT_READ.id
+  );
   return getRowsByIds(ids, {
-    batch: backend.getNodes === void 0 ? void 0 : (batchIds) => requireDefined(backend.getNodes)(graphId, kind, batchIds),
+    batch: bound === void 0 ? void 0 : ((batchIds) => bound.getNodes(graphId, kind, batchIds)),
     one: (id) => backend.getNode(graphId, kind, id)
   });
 }
@@ -2320,7 +2362,7 @@ function recordedInsertsFor(afterById, closed) {
     operation: recordedOp(closed.has(row.id), closed.get(row.id) ?? false, row)
   }));
 }
-async function flushNodes(target, schema, graphId, entities, recordedRevision) {
+async function flushNodes(target, batchPointRead, schema, graphId, entities, recordedRevision) {
   const chunkSize = recordedNodeChunkSize(target);
   for (const [kind, group] of groupNodesByKind(entities)) {
     for (const entityChunk of chunk(group, chunkSize)) {
@@ -2335,7 +2377,7 @@ async function flushNodes(target, schema, graphId, entities, recordedRevision) {
       );
       const afterById = await resolveAfterImages(
         entityChunk,
-        (missing) => getNodeRowsByIds(target, graphId, kind, missing)
+        (missing) => getNodeRowsByIds(target, batchPointRead, graphId, kind, missing)
       );
       await insertRecordedNodeRows(
         target,
@@ -2346,7 +2388,7 @@ async function flushNodes(target, schema, graphId, entities, recordedRevision) {
     }
   }
 }
-async function flushEdges(target, schema, graphId, entities, recordedRevision) {
+async function flushEdges(target, batchPointRead, schema, graphId, entities, recordedRevision) {
   const chunkSize = recordedEdgeChunkSize(target);
   for (const entityChunk of chunk(entities, chunkSize)) {
     const ids = entityChunk.map((entity) => entity.id);
@@ -2359,7 +2401,7 @@ async function flushEdges(target, schema, graphId, entities, recordedRevision) {
     );
     const afterById = await resolveAfterImages(
       entityChunk,
-      (missing) => getEdgeRowsByIds(target, graphId, missing)
+      (missing) => getEdgeRowsByIds(target, batchPointRead, graphId, missing)
     );
     await insertRecordedEdgeRows(
       target,
@@ -2675,7 +2717,7 @@ function createRecordedCaptureSession() {
       if (sealed) throw recordedCaptureSealedError({ graphId });
       forcedGraphRevisions.add(graphId);
     },
-    async flush(target, schema, ownsWriteLock) {
+    async flush(target, batchPointRead, schema, ownsWriteLock) {
       if (sealed) {
         throw new ConfigurationError(
           "Recorded-time capture session was already flushed.",
@@ -2712,6 +2754,7 @@ function createRecordedCaptureSession() {
         );
         await flushNodes(
           target,
+          batchPointRead,
           schema,
           graphId,
           nodes,
@@ -2719,6 +2762,7 @@ function createRecordedCaptureSession() {
         );
         await flushEdges(
           target,
+          batchPointRead,
           schema,
           graphId,
           edges,
@@ -2947,7 +2991,7 @@ function createRecordedTransactionBackend(target, session, schema) {
   recordedRevisionBindings.set(overlay, session);
   return overlay;
 }
-function createRecordedTransactionScope(target, schema, ownsWriteLock = false) {
+function createRecordedTransactionScope(target, batchPointRead, schema, ownsWriteLock = false) {
   requireCaptureStatements(target);
   const session = createRecordedCaptureSession();
   const resolvedSchema = schema ?? requireRecordedSchema(target);
@@ -2955,17 +2999,22 @@ function createRecordedTransactionScope(target, schema, ownsWriteLock = false) {
     backend: createRecordedTransactionBackend(target, session, resolvedSchema),
     async flush() {
       return withRecordedRelationsPrecondition(
-        session.flush(target, resolvedSchema, ownsWriteLock),
+        session.flush(target, batchPointRead, resolvedSchema, ownsWriteLock),
         { dialect: target.dialect, surface: "capture-flush" }
       );
     }
   };
 }
-async function runCapturedAutocommit(backend, schema, fn, options) {
+async function runCapturedAutocommit(backend, schema, batchPointRead, fn, options) {
   assertRequestedRecordedIsolation(backend, options);
   return backend.transaction(async (target) => {
     await assertRecordedCaptureTransactionIsolation(target);
-    const scope = createRecordedTransactionScope(target, schema, true);
+    const scope = createRecordedTransactionScope(
+      target,
+      batchPointRead,
+      schema,
+      true
+    );
     const result = await fn(scope.backend);
     await scope.flush();
     return result;
@@ -2973,7 +3022,8 @@ async function runCapturedAutocommit(backend, schema, fn, options) {
 }
 function createRecordedBackend(backend, schema) {
   assertCapturableBackend(backend);
-  const capture = (fn) => runCapturedAutocommit(backend, schema, fn);
+  const batchPointRead = batchPointReadVerdict(backend);
+  const capture = (fn) => runCapturedAutocommit(backend, schema, batchPointRead, fn);
   const projectedBackend = projectGraphBackend(backend);
   return deriveBackend(projectedBackend, {
     ...rawWriteGuards(backend, "backend"),
@@ -3078,7 +3128,12 @@ function createRecordedBackend(backend, schema) {
       return backend.transaction(async (target) => {
         await assertRecordedCaptureTransactionIsolation(target, backendOptions);
         const readOnly = backendOptions?.accessMode === "read_only";
-        const scope = createRecordedTransactionScope(target, schema, !readOnly);
+        const scope = createRecordedTransactionScope(
+          target,
+          batchPointRead,
+          schema,
+          !readOnly
+        );
         const result = await fn(scope.backend);
         const instants = await scope.flush();
         observer?.(instants);
@@ -3278,6 +3333,6 @@ function runHookedWriteOperation(ctx, opContext, backend, body, options) {
   );
 }
 
-export { CURRENT_READ_INSTANT_PLACEHOLDER, IDENTITY_ASSERTION_COLUMNS, IDENTITY_PEER_CLASS_COLUMNS, advanceRevisionClock, arrayField, assertCurrentRecordedSchema, assertRecordedCaptureTransactionIsolation, assertRevisionTrackableBackend, baseField, buildFieldBuilderForTypeInfo, buildPredicateIndex, closeRecordedHardDeletedKind, compileFieldValue, compileKindFilter, compilePredicateClauses, compilePredicateExpression, compileTemporalFilter, constraintFenceRefusal, createFulltextAccessor, createRecordedBackend, createRecordedTransactionScope, createValidationError, currentReadInstant, currentReadInstantFor, dateField, edgeInsertDispatch, ensureRevisionOrigin, exists, extractFulltextMatchPredicates, extractTemporalOptions, extractVectorSimilarityPredicates, fieldRef, forceRecordedGraphRevision, forceWriteTransactionRevision, generateId, getEdgeRowsByIds, getFieldPointer, getHybridTargetAlias, getNodeKindsForAlias, getNodeRowsByIds, getPredicatesForAlias, historicalIdentityPeerClassQuery, historicalIdentityReconstructionCtes, identityAssertionSnapshotSource, identityNodeSnapshotSource, identityNodeVisibilitySql, identitySqlCoordinate, inSubquery, isParameterRef, lockRecordedGraphWrite, lockSchemaVersionForStoreWrite, nodeInsertDispatch, notExists, notInSubquery, numberField, objectField, param, readRecordedClock, readRevisionOrigin, recordedBindParamBudget, recordedCaptureRequiresCallbackTransactionError, resolveParameterValueType, runHookedWriteOperation, runInWriteTransaction, runInsertBatch, runInsertBatchReturning, runInsertNoReturn, sqlValueList, stringField, throwHistoryUnsafeSqlAccess, throwRevisionTrackingUnsafeSqlAccess, validateEdgeProps, validateNodeProps, validateProps, withPinnedReadInstant, withRecordedFlushObserver, withRecordedIdentityMutationTarget, withWriteTransactionSession, wrapZodError };
-//# sourceMappingURL=chunk-FX5ZW6PN.js.map
-//# sourceMappingURL=chunk-FX5ZW6PN.js.map
+export { CURRENT_READ_INSTANT_PLACEHOLDER, IDENTITY_ASSERTION_COLUMNS, IDENTITY_PEER_CLASS_COLUMNS, advanceRevisionClock, arrayField, assertCurrentRecordedSchema, assertRecordedCaptureTransactionIsolation, assertRecursiveTraversalSupported, assertRevisionTrackableBackend, baseField, buildFieldBuilderForTypeInfo, buildPredicateIndex, closeRecordedHardDeletedKind, compileFieldValue, compileKindFilter, compilePredicateClauses, compilePredicateExpression, compileTemporalFilter, constraintFenceRefusal, createFulltextAccessor, createRecordedBackend, createRecordedTransactionScope, createValidationError, currentReadInstant, currentReadInstantFor, dateField, edgeInsertDispatch, ensureRevisionOrigin, exists, extractFulltextMatchPredicates, extractTemporalOptions, extractVectorSimilarityPredicates, fieldRef, forceRecordedGraphRevision, forceWriteTransactionRevision, generateId, getEdgeRowsByIds, getFieldPointer, getHybridTargetAlias, getNodeKindsForAlias, getNodeRowsByIds, getPredicatesForAlias, historicalIdentityPeerClassQuery, historicalIdentityReconstructionCtes, identityAssertionSnapshotSource, identityNodeSnapshotSource, identityNodeVisibilitySql, identitySqlCoordinate, inSubquery, isParameterRef, lockRecordedGraphWrite, lockSchemaVersionForStoreWrite, nodeInsertDispatch, notExists, notInSubquery, numberField, objectField, param, readRecordedClock, readRevisionOrigin, recordedBindParamBudget, recordedCaptureRequiresCallbackTransactionError, requireRecursiveTraversalVerdict, resolveParameterValueType, runHookedWriteOperation, runInWriteTransaction, runInsertBatch, runInsertBatchReturning, runInsertNoReturn, sqlValueList, stringField, throwHistoryUnsafeSqlAccess, throwRevisionTrackingUnsafeSqlAccess, validateEdgeProps, validateNodeProps, validateProps, withPinnedReadInstant, withRecordedFlushObserver, withRecordedIdentityMutationTarget, withWriteTransactionSession, wrapZodError };
+//# sourceMappingURL=chunk-VAAC7L57.js.map
+//# sourceMappingURL=chunk-VAAC7L57.js.map