@nicia-ai/typegraph 0.38.0 → 0.39.0

package/dist/{chunk-A2FGSWMQ.js → chunk-CBK2IVI2.js}

@@ -1,15 +1,15 @@
 import { compareStrings, compareCodePoints } from './chunk-DRACN6XG.js';
 import { createEdgeRowMapper, createNodeRowMapper, SQLITE_ROW_MAPPER_CONFIG, POSTGRES_ROW_MAPPER_CONFIG } from './chunk-AOL64O4Z.js';
-import { rowToNode, executeNodeBulkFindByIndex, executeNodeBulkFindByConstraint, executeNodeFindByConstraint, executeNodeBulkGetOrCreateByConstraint, executeNodeGetOrCreateByConstraint, executeNodeHardDelete, executeNodeDelete, nodeUpsertDirtyCheck, executeNodeUpsertUpdate, executeNodeUpdate, executeNodeCreateNoReturnBatch, executeNodeCreateBatch, executeNodeCreate, rowToEdge, runInWriteTransaction, checkCardinalityConstraint, runHookedWriteOperation, rowToNodeMeta, rowToEdgeMeta } from './chunk-UPXDVI3T.js';
-import { isParameterRef, fieldRef, buildFieldBuilderForTypeInfo, stringField, createFulltextAccessor, storeRuntime, CURRENT_READ_INSTANT_PLACEHOLDER, DEFAULT_SQL_SCHEMA, requireSqlSchema, recordedReadSchemaFor, withPinnedReadInstant, STORE_RUNTIME, assertRevisionTrackableBackend, createSqlSchema, requireExternalRecordedReadSource, createRecordedReadBinding, createRecordedBackend, readRecordedClock, ensureRevisionOrigin, TRANSACTION_RUNTIME, withRecordedFlushObserver, recordedCaptureRequiresCallbackTransactionError, assertRecordedCaptureTransactionIsolation, createRecordedTransactionScope, lockRecordedGraphWrite, generateId, createGraphBackendProjection, vectorSlotKey, baseField, objectField, arrayField, dateField, numberField, computeFulltextContent, AUTO_REFRESH_STATISTICS_ROW_THRESHOLD, throwHistoryUnsafeSqlAccess, throwRevisionTrackingUnsafeSqlAccess, advanceRevisionClock, recordedReadSqlSchema, requireRecordedReadBinding, runInsertBatch, edgeInsertDispatch, runInsertBatchReturning, projectBackendMembers, sqlValueList, getEmbeddingFields, getNodeRowsByIds, getEdgeRowsByIds, compileKindFilter, currentReadInstant, compileTemporalFilter, validateEdgeEndpoints, buildPredicateIndex, compileFieldValue, recordedBindParamBudget, extractVectorSimilarityPredicates, extractFulltextMatchPredicates, currentReadInstantFor, extractTemporalOptions, compilePredicateExpression, getPredicatesForAlias, getFieldPointer, getNodeKindsForAlias, getHybridTargetAlias, closeRecordedHardDeletedKind, compilePredicateClauses, ALIAS_CTE_PREFIX, EMBEDDINGS_CTE_ALIAS, FULLTEXT_CTE_ALIAS, HYBRID_CANDIDATES_CTE_ALIAS } from './chunk-RQPRCEIO.js';
+import { rowToNode, executeNodeBulkFindByIndex, executeNodeBulkFindByConstraint, executeNodeFindByConstraint, executeNodeBulkGetOrCreateByConstraint, executeNodeGetOrCreateByConstraint, executeNodeHardDelete, executeNodeDelete, nodeUpsertDirtyCheck, executeNodeUpsertUpdate, executeNodeUpdate, executeNodeCreateNoReturnBatch, executeNodeCreateBatch, executeNodeCreate, rowToEdge, runInWriteTransaction, checkCardinalityConstraint, runHookedWriteOperation, rowToNodeMeta, rowToEdgeMeta } from './chunk-3SK4SVTW.js';
+import { isParameterRef, fieldRef, buildFieldBuilderForTypeInfo, stringField, createFulltextAccessor, storeRuntime, CURRENT_READ_INSTANT_PLACEHOLDER, DEFAULT_SQL_SCHEMA, requireSqlSchema, recordedReadSchemaFor, withPinnedReadInstant, STORE_RUNTIME, assertRevisionTrackableBackend, createSqlSchema, requireExternalRecordedReadSource, createRecordedReadBinding, createRecordedBackend, readRecordedClock, ensureRevisionOrigin, TRANSACTION_RUNTIME, withRecordedFlushObserver, recordedCaptureRequiresCallbackTransactionError, assertRecordedCaptureTransactionIsolation, createRecordedTransactionScope, lockRecordedGraphWrite, generateId, createGraphBackendProjection, vectorSlotKey, baseField, objectField, arrayField, dateField, numberField, computeFulltextContent, AUTO_REFRESH_STATISTICS_ROW_THRESHOLD, advanceRevisionClock, recordedReadSqlSchema, requireRecordedReadBinding, runInsertBatch, edgeInsertDispatch, runInsertBatchReturning, projectBackendMembers, sqlValueList, getEmbeddingFields, getNodeRowsByIds, getEdgeRowsByIds, compileKindFilter, currentReadInstant, compileTemporalFilter, validateEdgeEndpoints, buildPredicateIndex, compileFieldValue, recordedBindParamBudget, extractVectorSimilarityPredicates, extractFulltextMatchPredicates, currentReadInstantFor, extractTemporalOptions, compilePredicateExpression, getPredicatesForAlias, getFieldPointer, getNodeKindsForAlias, getHybridTargetAlias, closeRecordedHardDeletedKind, throwHistoryUnsafeSqlAccess, throwRevisionTrackingUnsafeSqlAccess, compilePredicateClauses, ALIAS_CTE_PREFIX, EMBEDDINGS_CTE_ALIAS, FULLTEXT_CTE_ALIAS, HYBRID_CANDIDATES_CTE_ALIAS } from './chunk-IFDXG2YJ.js';
 import { chunk } from './chunk-35S6P5ZU.js';
 import { runOptionallyInTransaction, createTransactionReadBackend, rowPropsToObject, createBackendOverlay, INTERNAL_TEMPORARY_WRITES } from './chunk-PZHC5GCD.js';
 import { resolveReadCoordinate, withRecordedCoordinate, describeCoordinate, coordinateContext, asRecordedInstant, assertValidRecordedInstant } from './chunk-J6IJARLG.js';
-import { loadAndMergeGraphExtensionDocument, ensureSchema, loadAndVerifyGraph, buildKindRegistry, mergeGraphExtension, commitNewSchemaVersion, applyDeprecatedKinds, loadActiveSchemaWithBootstrap, parseSerializedSchema, extensionKindNames, serializeSchemaProperties, buildGraphExtensionOntologyKeySet, compileTimeOntologyKey, serializeIndexDeclaration } from './chunk-VBH7ZXSZ.js';
+import { loadAndMergeGraphExtensionDocument, ensureSchema, loadAndVerifyGraph, buildKindRegistry, mergeGraphExtension, commitNewSchemaVersion, applyDeprecatedKinds, loadActiveSchemaWithBootstrap, parseSerializedSchema, extensionKindNames, serializeSchemaProperties, buildGraphExtensionOntologyKeySet, compileTimeOntologyKey, serializeIndexDeclaration } from './chunk-SU7VQOJ3.js';
 import { getTypeName } from './chunk-76HE7DJP.js';
 import { validateEdgeProps } from './chunk-ZE6NVENI.js';
 import { canonicalEqual, sortedReplacer } from './chunk-UR7W5YQK.js';
-import { withRecordedRelationsPrecondition, isMissingTableError } from './chunk-KFLXWVUJ.js';
+import { withRecordedRelationsPrecondition, isMissingTableError } from './chunk-UUIBACKJ.js';
 import { isKnownKind } from './chunk-PH4IJ3V5.js';
 import { nowIso, validateOptionalCanonicalIsoDate } from './chunk-I6FX7AAG.js';
 import { generateIndexDDL } from './chunk-U4JDJKPD.js';
@@ -183,7 +183,7 @@ function createBatchReadRefusal(entity, method, coordinate) {
 function createRecordedUnsupportedRefusal(entity, method, coordinate) {
   return () => Promise.reject(
     new ConfigurationError(
-      `'${method}' is not available on a RecordedStoreView (${describeCoordinate(coordinate)}). Recorded-time reads are reconstructing reads; this view exposes only query, subgraph, graph algorithms, and point getById/getByIds collection reads.`,
+      `'${method}' is not available on a RecordedStoreView (${describeCoordinate(coordinate)}). Recorded-time reads are reconstructing reads; this view exposes only query, subgraph, graph algorithms, and collection getById/getByIds/scan reads.`,
       {
         code: "RECORDED_STORE_VIEW_UNSUPPORTED",
         entity,
@@ -314,14 +314,16 @@ function pinnedEdgeCollectionsFor(store, coordinate, wrap) {
 function recordedNodeCollection(store, kind, live, coordinate) {
   const reads = {
     getById: (id) => storeRuntime(store).recordedNodeGetById(kind, id, coordinate),
-    getByIds: (ids) => storeRuntime(store).recordedNodeGetByIds(kind, ids, coordinate)
+    getByIds: (ids) => storeRuntime(store).recordedNodeGetByIds(kind, ids, coordinate),
+    scan: (options) => storeRuntime(store).recordedNodeScan(kind, coordinate, options)
   };
   return recordedCollectionProxy(reads, live, coordinate, "node");
 }
 function recordedEdgeCollection(store, kind, live, coordinate) {
   const reads = {
     getById: (id) => storeRuntime(store).recordedEdgeGetById(kind, id, coordinate),
-    getByIds: (ids) => storeRuntime(store).recordedEdgeGetByIds(kind, ids, coordinate)
+    getByIds: (ids) => storeRuntime(store).recordedEdgeGetByIds(kind, ids, coordinate),
+    scan: (options) => storeRuntime(store).recordedEdgeScan(kind, coordinate, options)
   };
   return recordedCollectionProxy(reads, live, coordinate, "edge");
 }
@@ -619,7 +621,7 @@ var RecordedStoreView = class extends CoordinatePinnedView {
     }
     return recorded.asOf;
   }
-  /** Recorded-time node point-read collections. */
+  /** Recorded-time node reconstructing-read collections. */
   get nodes() {
     this.#nodes ??= pinnedNodeCollectionsFor(
       this.store,
@@ -628,7 +630,7 @@ var RecordedStoreView = class extends CoordinatePinnedView {
     );
     return this.#nodes;
   }
-  /** Recorded-time edge point-read collections. */
+  /** Recorded-time edge reconstructing-read collections. */
   get edges() {
     this.#edges ??= pinnedEdgeCollectionsFor(
       this.store,
@@ -16352,6 +16354,7 @@ async function executeEdgeBulkGetOrCreateByEndpoints(ctx, kind, items, backend,
 
 // src/store/recorded-read-service.ts
 var RECORDED_POINT_READ_FIXED_BIND_PARAMS = 8;
+var RECORDED_SCAN_LIMIT = 1e3;
 function recordedPointReadIdChunk(backend) {
   const budget = recordedBindParamBudget(backend);
   return Math.max(1, budget - RECORDED_POINT_READ_FIXED_BIND_PARAMS);
@@ -16396,7 +16399,7 @@ function recordedTemporalFilter(backend, coordinate, tableAlias) {
 }
 function recordedRelationInvariantError(params) {
   return new ConfigurationError(
-    "Recorded relation invariant violation: more than one recorded row matched the requested point read.",
+    "Recorded relation invariant violation: more than one recorded row matched the requested read.",
     {
       code: "RECORDED_RELATION_INVARIANT_VIOLATION",
       graphId: params.graphId,
@@ -16412,6 +16415,57 @@ function recordedRelationInvariantError(params) {
     }
   );
 }
+function validateRecordedScanLimit(limit) {
+  if (limit === void 0) return RECORDED_SCAN_LIMIT;
+  if (!Number.isInteger(limit) || limit <= 0 || limit > RECORDED_SCAN_LIMIT) {
+    throw new ValidationError(
+      `Recorded scan limit must be an integer between 1 and ${RECORDED_SCAN_LIMIT}, got: ${String(limit)}`,
+      {
+        issues: [
+          {
+            path: "limit",
+            message: `Must be an integer between 1 and ${RECORDED_SCAN_LIMIT}.`
+          }
+        ]
+      }
+    );
+  }
+  return limit;
+}
+function recordedScanCursorScope(graphId, entity, kind, coordinate) {
+  return JSON.stringify([
+    "recorded-scan",
+    graphId,
+    entity,
+    kind,
+    coordinate.valid.mode,
+    coordinate.valid.asOf,
+    coordinate.recorded?.asOf
+  ]);
+}
+function invalidRecordedScanCursor() {
+  return new ValidationError(
+    "Recorded scan cursor does not match this graph, collection, or temporal coordinate.",
+    {
+      issues: [
+        {
+          path: "after",
+          message: "Use a cursor returned by the same recorded collection scan."
+        }
+      ]
+    }
+  );
+}
+function decodeRecordedScanCursor(cursor, expectedScope) {
+  const decoded = decodeCursor(cursor);
+  if (decoded.d !== "f" || decoded.cols.length !== 1 || decoded.cols[0] !== expectedScope || decoded.vals.length !== 1 || typeof decoded.vals[0] !== "string") {
+    throw invalidRecordedScanCursor();
+  }
+  return decoded.vals[0];
+}
+function encodeRecordedScanCursor(id, scope) {
+  return encodeCursor({ v: 1, d: "f", vals: [id], cols: [scope] });
+}
 function createRecordedReadService(params) {
   const {
     graphId,
@@ -16421,6 +16475,11 @@ function createRecordedReadService(params) {
     mapRecordedEdgeRow
   } = params;
   const recordedSchema = recordedReadBinding === void 0 ? void 0 : recordedReadSqlSchema(recordedReadBinding);
+  function schemaForRecordedRead(surface) {
+    return recordedSchema ?? recordedReadSqlSchema(
+      requireRecordedReadBinding(recordedReadBinding, surface)
+    );
+  }
   async function recordedGetByIds(read) {
     const { table, alias, kind, ids, coordinate, toEntity, entity } = read;
     if (ids.length === 0) return [];
@@ -16463,10 +16522,51 @@ function createRecordedReadService(params) {
     }
     return ids.map((id) => byId.get(id));
   }
+  async function recordedScan(scan) {
+    const { table, alias, kind, coordinate, options, toEntity, entity } = scan;
+    const limit = validateRecordedScanLimit(options?.limit);
+    const scope = recordedScanCursorScope(graphId, entity, kind, coordinate);
+    const after = options?.after === void 0 ? void 0 : decodeRecordedScanCursor(options.after, scope);
+    const aliasSql = sql.raw(alias);
+    const temporalFilter = recordedTemporalFilter(backend, coordinate, alias);
+    const rows = await withRelationsPrecondition(
+      backend,
+      backend.execute(
+        asCompiledRowsSql(sql`
+          SELECT * FROM ${table} ${aliasSql}
+          WHERE ${aliasSql}.graph_id = ${graphId}
+            AND ${aliasSql}.kind = ${kind}
+            ${after === void 0 ? sql.raw("") : sql`AND ${aliasSql}.id > ${after}`}
+            AND ${temporalFilter}
+          ORDER BY ${aliasSql}.id ASC, ${aliasSql}.recorded_from ASC
+          LIMIT ${limit + 1}
+        `)
+      ),
+      "recorded-scan"
+    );
+    const entities = rows.map((row) => toEntity(row));
+    for (let index = 1; index < entities.length; index += 1) {
+      const previous = requireDefined(entities[index - 1]);
+      const current = requireDefined(entities[index]);
+      if (previous.id !== current.id) continue;
+      throw recordedRelationInvariantError({
+        graphId,
+        entity,
+        kind,
+        id: current.id,
+        coordinate
+      });
+    }
+    const hasNextPage = entities.length > limit;
+    const data = hasNextPage ? entities.slice(0, limit) : entities;
+    return {
+      data,
+      nextCursor: hasNextPage ? encodeRecordedScanCursor(requireDefined(data.at(-1)).id, scope) : void 0,
+      hasNextPage
+    };
+  }
   function nodeGetByIds(kind, ids, coordinate) {
-    const schema = recordedSchema ?? recordedReadSqlSchema(
-      requireRecordedReadBinding(recordedReadBinding, "recorded-point-read")
-    );
+    const schema = schemaForRecordedRead("recorded-point-read");
     return recordedGetByIds({
       entity: "node",
       table: schema.nodesTable,
@@ -16478,9 +16578,7 @@ function createRecordedReadService(params) {
     });
   }
   function edgeGetByIds(kind, ids, coordinate) {
-    const schema = recordedSchema ?? recordedReadSqlSchema(
-      requireRecordedReadBinding(recordedReadBinding, "recorded-point-read")
-    );
+    const schema = schemaForRecordedRead("recorded-point-read");
     return recordedGetByIds({
       entity: "edge",
       table: schema.edgesTable,
@@ -16491,6 +16589,30 @@ function createRecordedReadService(params) {
       toEntity: (row) => rowToEdge(mapRecordedEdgeRow(row))
     });
   }
+  function nodeScan(kind, coordinate, options) {
+    const schema = schemaForRecordedRead("recorded-scan");
+    return recordedScan({
+      entity: "node",
+      table: schema.nodesTable,
+      alias: "n",
+      kind,
+      coordinate,
+      options,
+      toEntity: (row) => rowToNode(mapRecordedNodeRow(row))
+    });
+  }
+  function edgeScan(kind, coordinate, options) {
+    const schema = schemaForRecordedRead("recorded-scan");
+    return recordedScan({
+      entity: "edge",
+      table: schema.edgesTable,
+      alias: "e",
+      kind,
+      coordinate,
+      options,
+      toEntity: (row) => rowToEdge(mapRecordedEdgeRow(row))
+    });
+  }
   return {
     backendForCoordinate(coordinate, surface) {
       if (coordinate.recorded === void 0) return backend;
@@ -16502,11 +16624,13 @@ function createRecordedReadService(params) {
       return results[0];
     },
     nodeGetByIds,
+    nodeScan,
     async edgeGetById(kind, id, coordinate) {
       const results = await edgeGetByIds(kind, [id], coordinate);
       return results[0];
     },
-    edgeGetByIds
+    edgeGetByIds,
+    edgeScan
   };
 }
 
@@ -16732,6 +16856,13 @@ function overlayPropertyDescriptors(base, overlay) {
     ...Object.getOwnPropertyDescriptors(overlay)
   });
 }
+function defineUnavailableSqlGuard(context, guard) {
+  Object.defineProperty(context, "sql", {
+    configurable: false,
+    enumerable: true,
+    get: guard
+  });
+}
 function syncStoreReplacementRef(ref, replacement) {
   if (ref === void 0) return;
   ref.current = replacement;
@@ -16810,8 +16941,10 @@ var StoreImplementation = class _StoreImplementation {
       sealedQuery: (coordinate) => this.sealedQuery(coordinate),
       recordedNodeGetById: (kind, id, coordinate) => this.recordedNodeGetById(kind, id, coordinate),
       recordedNodeGetByIds: (kind, ids, coordinate) => this.recordedNodeGetByIds(kind, ids, coordinate),
+      recordedNodeScan: (kind, coordinate, options2) => this.recordedNodeScan(kind, coordinate, options2),
       recordedEdgeGetById: (kind, id, coordinate) => this.recordedEdgeGetById(kind, id, coordinate),
       recordedEdgeGetByIds: (kind, ids, coordinate) => this.recordedEdgeGetByIds(kind, ids, coordinate),
+      recordedEdgeScan: (kind, coordinate, options2) => this.recordedEdgeScan(kind, coordinate, options2),
       subgraphAtCoordinate: (rootId, subgraphOptions) => this.subgraphAtCoordinate(rootId, subgraphOptions),
       algorithmsAtCoordinate: (coordinate) => this.algorithmsAtCoordinate(coordinate)
     };
@@ -17287,6 +17420,10 @@ var StoreImplementation = class _StoreImplementation {
   async recordedNodeGetByIds(kind, ids, coordinate) {
     return this.#recordedReads.nodeGetByIds(kind, ids, coordinate);
   }
+  /** @internal Bounded recorded-time node enumeration for RecordedStoreView. */
+  async recordedNodeScan(kind, coordinate, options) {
+    return this.#recordedReads.nodeScan(kind, coordinate, options);
+  }
   /**
    * Internal seam for {@link RecordedStoreView}: reconstruct an edge point read
    * from the recorded-time relation while preserving live getById behavior.
@@ -17305,6 +17442,10 @@ var StoreImplementation = class _StoreImplementation {
   async recordedEdgeGetByIds(kind, ids, coordinate) {
     return this.#recordedReads.edgeGetByIds(kind, ids, coordinate);
   }
+  /** @internal Bounded recorded-time edge enumeration for RecordedStoreView. */
+  async recordedEdgeScan(kind, coordinate, options) {
+    return this.#recordedReads.edgeScan(kind, coordinate, options);
+  }
   // === Temporal Views ===
   /**
    * Returns a read-only {@link StoreView} pinned to a valid-time instant.
@@ -17950,19 +18091,18 @@ var StoreImplementation = class _StoreImplementation {
     if (this.#captureEnabled) {
       withSql = {
         ...base,
-        sqlAvailability: "history",
-        get sql() {
-          return throwHistoryUnsafeSqlAccess();
-        }
+        sqlAvailability: "history"
       };
+      defineUnavailableSqlGuard(withSql, () => throwHistoryUnsafeSqlAccess());
     } else if (this.#revisionTrackingEnabled) {
       withSql = {
         ...base,
-        sqlAvailability: "revisionTracking",
-        get sql() {
-          return throwRevisionTrackingUnsafeSqlAccess();
-        }
+        sqlAvailability: "revisionTracking"
       };
+      defineUnavailableSqlGuard(
+        withSql,
+        () => throwRevisionTrackingUnsafeSqlAccess()
+      );
     } else if (sql2 === void 0) {
       withSql = { ...base, sqlAvailability: "unavailable" };
     } else {
@@ -19055,5 +19195,5 @@ async function createVerifiedAdapterStore(graph, backend, options) {
 }
 
 export { ExecutableAggregateQuery, ExecutableQuery, MAX_EXPLICIT_RECURSIVE_DEPTH, MAX_RECURSIVE_DEPTH, PreparedQuery, QueryBuilder, RecordedStoreView, StoreSearch, StoreView, UnionableQuery, avg, composeFragments, count, countDistinct, countDistinctEdges, countEdges, createAdapterStore, createAdapterStoreWithSchema, createFragment, createQueryBuilder, createStore, createStoreWithSchema, createVerifiedAdapterStore, createVerifiedStore, defineSubgraphProject, field, having, havingEq, havingGt, havingGte, havingLt, havingLte, limitFragment, max, min, offsetFragment, orderByFragment, sum };
-//# sourceMappingURL=chunk-A2FGSWMQ.js.map
-//# sourceMappingURL=chunk-A2FGSWMQ.js.map
+//# sourceMappingURL=chunk-CBK2IVI2.js.map
+//# sourceMappingURL=chunk-CBK2IVI2.js.map