@nicia-ai/typegraph 0.31.0 → 0.33.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (188) hide show
  1. package/README.md +31 -0
  2. package/dist/backend/postgres/index.cjs +31 -18
  3. package/dist/backend/postgres/index.d.cts +6 -6
  4. package/dist/backend/postgres/index.d.ts +6 -6
  5. package/dist/backend/postgres/index.js +9 -8
  6. package/dist/backend/postgres/pglite.cjs +13 -12
  7. package/dist/backend/postgres/pglite.cjs.map +1 -1
  8. package/dist/backend/postgres/pglite.d.cts +3 -3
  9. package/dist/backend/postgres/pglite.d.ts +3 -3
  10. package/dist/backend/postgres/pglite.js +9 -8
  11. package/dist/backend/postgres/pglite.js.map +1 -1
  12. package/dist/backend/sqlite/index.cjs +29 -16
  13. package/dist/backend/sqlite/index.d.cts +7 -7
  14. package/dist/backend/sqlite/index.d.ts +7 -7
  15. package/dist/backend/sqlite/index.js +8 -7
  16. package/dist/backend/sqlite/libsql.cjs +13 -12
  17. package/dist/backend/sqlite/libsql.cjs.map +1 -1
  18. package/dist/backend/sqlite/libsql.d.cts +3 -3
  19. package/dist/backend/sqlite/libsql.d.ts +3 -3
  20. package/dist/backend/sqlite/libsql.js +9 -8
  21. package/dist/backend/sqlite/libsql.js.map +1 -1
  22. package/dist/backend/sqlite/local.cjs +14 -13
  23. package/dist/backend/sqlite/local.cjs.map +1 -1
  24. package/dist/backend/sqlite/local.d.cts +3 -3
  25. package/dist/backend/sqlite/local.d.ts +3 -3
  26. package/dist/backend/sqlite/local.js +9 -8
  27. package/dist/backend/sqlite/local.js.map +1 -1
  28. package/dist/{chunk-SFFJ2IKN.cjs → chunk-3642VBVC.cjs} +70 -68
  29. package/dist/chunk-3642VBVC.cjs.map +1 -0
  30. package/dist/chunk-3E7SNSIA.cjs +55 -0
  31. package/dist/chunk-3E7SNSIA.cjs.map +1 -0
  32. package/dist/{chunk-6RMLO5O4.cjs → chunk-3IR2GEMJ.cjs} +8 -7
  33. package/dist/chunk-3IR2GEMJ.cjs.map +1 -0
  34. package/dist/{chunk-6SA7UIQJ.cjs → chunk-3QRBXYT5.cjs} +6 -6
  35. package/dist/{chunk-6SA7UIQJ.cjs.map → chunk-3QRBXYT5.cjs.map} +1 -1
  36. package/dist/{chunk-54JVNOAQ.cjs → chunk-4RBAJVEC.cjs} +128 -6
  37. package/dist/chunk-4RBAJVEC.cjs.map +1 -0
  38. package/dist/{chunk-IJORSAC3.js → chunk-6NRFUHMS.js} +4 -3
  39. package/dist/chunk-6NRFUHMS.js.map +1 -0
  40. package/dist/{chunk-FLOI7QOT.cjs → chunk-BF3ZDEUE.cjs} +104 -72
  41. package/dist/chunk-BF3ZDEUE.cjs.map +1 -0
  42. package/dist/{chunk-2HZGWCB4.js → chunk-C4C4Q7A6.js} +3 -3
  43. package/dist/chunk-C4C4Q7A6.js.map +1 -0
  44. package/dist/{chunk-O4VUR6SI.js → chunk-CEF2QOTO.js} +3 -3
  45. package/dist/{chunk-O4VUR6SI.js.map → chunk-CEF2QOTO.js.map} +1 -1
  46. package/dist/{chunk-V4IQYOQ4.cjs → chunk-CFNT3ITG.cjs} +3 -3
  47. package/dist/chunk-CFNT3ITG.cjs.map +1 -0
  48. package/dist/{chunk-LJLMDDCW.js → chunk-CWFPJ3RC.js} +3 -3
  49. package/dist/{chunk-LJLMDDCW.js.map → chunk-CWFPJ3RC.js.map} +1 -1
  50. package/dist/{chunk-RZ4DH4E7.cjs → chunk-D3EWZ67S.cjs} +3348 -2030
  51. package/dist/chunk-D3EWZ67S.cjs.map +1 -0
  52. package/dist/{chunk-GKFWM3DS.js → chunk-DJYRRDHA.js} +124 -5
  53. package/dist/chunk-DJYRRDHA.js.map +1 -0
  54. package/dist/{chunk-YQGLVWB2.cjs → chunk-EF3Z645U.cjs} +2 -52
  55. package/dist/chunk-EF3Z645U.cjs.map +1 -0
  56. package/dist/{chunk-ASYQDPPU.cjs → chunk-FDN43KXV.cjs} +19 -19
  57. package/dist/{chunk-ASYQDPPU.cjs.map → chunk-FDN43KXV.cjs.map} +1 -1
  58. package/dist/chunk-GYVBEZAO.js +120 -0
  59. package/dist/chunk-GYVBEZAO.js.map +1 -0
  60. package/dist/chunk-I4W7MKVG.cjs +1526 -0
  61. package/dist/chunk-I4W7MKVG.cjs.map +1 -0
  62. package/dist/{chunk-MXE2U3EX.js → chunk-IZ4PCL47.js} +3 -52
  63. package/dist/chunk-IZ4PCL47.js.map +1 -0
  64. package/dist/{chunk-4A4GUZTQ.js → chunk-JHOBXD7O.js} +10 -8
  65. package/dist/chunk-JHOBXD7O.js.map +1 -0
  66. package/dist/{chunk-CIINW6PS.cjs → chunk-KY5SDVA7.cjs} +676 -635
  67. package/dist/chunk-KY5SDVA7.cjs.map +1 -0
  68. package/dist/{chunk-N2MBPTAF.cjs → chunk-LM2IC4ZJ.cjs} +14 -14
  69. package/dist/{chunk-N2MBPTAF.cjs.map → chunk-LM2IC4ZJ.cjs.map} +1 -1
  70. package/dist/{chunk-7JGLPAFV.cjs → chunk-MBLXCV2Y.cjs} +16 -16
  71. package/dist/chunk-MBLXCV2Y.cjs.map +1 -0
  72. package/dist/{chunk-5DTPBFX5.cjs → chunk-NG5N7R45.cjs} +28 -28
  73. package/dist/{chunk-5DTPBFX5.cjs.map → chunk-NG5N7R45.cjs.map} +1 -1
  74. package/dist/chunk-OIE2UPVG.cjs +126 -0
  75. package/dist/chunk-OIE2UPVG.cjs.map +1 -0
  76. package/dist/{chunk-STP7QVUB.js → chunk-OS6KS3HV.js} +43 -11
  77. package/dist/chunk-OS6KS3HV.js.map +1 -0
  78. package/dist/{chunk-2ZY4K43M.js → chunk-PIHXFF73.js} +3 -3
  79. package/dist/{chunk-2ZY4K43M.js.map → chunk-PIHXFF73.js.map} +1 -1
  80. package/dist/{chunk-ATTXBMAX.js → chunk-PRMKPFN5.js} +3 -3
  81. package/dist/{chunk-ATTXBMAX.js.map → chunk-PRMKPFN5.js.map} +1 -1
  82. package/dist/chunk-PYD3UCDU.js +1480 -0
  83. package/dist/chunk-PYD3UCDU.js.map +1 -0
  84. package/dist/{chunk-MAQJYNJR.js → chunk-QBYTJSAY.js} +14 -16
  85. package/dist/chunk-QBYTJSAY.js.map +1 -0
  86. package/dist/{chunk-THX25XW6.js → chunk-SPT5JMME.js} +27 -7
  87. package/dist/chunk-SPT5JMME.js.map +1 -0
  88. package/dist/{chunk-3JBJEYWE.cjs → chunk-SST7XDY6.cjs} +32 -12
  89. package/dist/chunk-SST7XDY6.cjs.map +1 -0
  90. package/dist/{chunk-VZX2KSY3.js → chunk-UPDMJEW6.js} +608 -563
  91. package/dist/chunk-UPDMJEW6.js.map +1 -0
  92. package/dist/{chunk-UIFEEPME.js → chunk-WLP6TKFB.js} +3141 -1823
  93. package/dist/chunk-WLP6TKFB.js.map +1 -0
  94. package/dist/{chunk-VMEWZU2N.cjs → chunk-WWVV44DY.cjs} +11 -11
  95. package/dist/{chunk-VMEWZU2N.cjs.map → chunk-WWVV44DY.cjs.map} +1 -1
  96. package/dist/{chunk-UJ4V3YUQ.js → chunk-XKNAK27R.js} +3 -3
  97. package/dist/{chunk-UJ4V3YUQ.js.map → chunk-XKNAK27R.js.map} +1 -1
  98. package/dist/chunk-XLUNB2TZ.js +53 -0
  99. package/dist/chunk-XLUNB2TZ.js.map +1 -0
  100. package/dist/{chunk-XKJQQQVR.js → chunk-XVUJY72M.js} +6 -6
  101. package/dist/{chunk-XKJQQQVR.js.map → chunk-XVUJY72M.js.map} +1 -1
  102. package/dist/{chunk-5CN7B4CZ.cjs → chunk-YW7GHMF4.cjs} +17 -17
  103. package/dist/{chunk-5CN7B4CZ.cjs.map → chunk-YW7GHMF4.cjs.map} +1 -1
  104. package/dist/{ddl-BJcPrB4L.d.ts → ddl-CVnHJcar.d.ts} +3 -3
  105. package/dist/{ddl-CPZ7mB7X.d.cts → ddl-Dxt_fBHr.d.cts} +3 -3
  106. package/dist/{extension-types-D1k0inWU.d.cts → extension-types-YGFJPrzK.d.cts} +1 -1
  107. package/dist/{extension-types-D1k0inWU.d.ts → extension-types-YGFJPrzK.d.ts} +1 -1
  108. package/dist/graph-extension/index.d.cts +4 -4
  109. package/dist/graph-extension/index.d.ts +4 -4
  110. package/dist/graph-merge/index.cjs +200 -55
  111. package/dist/graph-merge/index.cjs.map +1 -1
  112. package/dist/graph-merge/index.d.cts +6 -6
  113. package/dist/graph-merge/index.d.ts +6 -6
  114. package/dist/graph-merge/index.js +185 -40
  115. package/dist/graph-merge/index.js.map +1 -1
  116. package/dist/{index-BEK0VtNB.d.ts → index-DGX6D9j1.d.ts} +2 -2
  117. package/dist/{index-C8sSTErx.d.cts → index-SEvUHDA6.d.cts} +2 -2
  118. package/dist/index.cjs +145 -116
  119. package/dist/index.cjs.map +1 -1
  120. package/dist/index.d.cts +25 -55
  121. package/dist/index.d.ts +25 -55
  122. package/dist/index.js +19 -17
  123. package/dist/index.js.map +1 -1
  124. package/dist/indexes/index.cjs +15 -14
  125. package/dist/indexes/index.d.cts +5 -5
  126. package/dist/indexes/index.d.ts +5 -5
  127. package/dist/indexes/index.js +6 -5
  128. package/dist/interchange/index.cjs +15 -15
  129. package/dist/interchange/index.d.cts +9 -9
  130. package/dist/interchange/index.d.ts +9 -9
  131. package/dist/interchange/index.js +2 -2
  132. package/dist/{manager-Np7VVSlE.d.cts → manager-BYl_zyZR.d.cts} +2 -2
  133. package/dist/{manager-By-WEd8M.d.ts → manager-C0_r0ALf.d.ts} +2 -2
  134. package/dist/{materialize-indexes-CAGhqPHQ.d.ts → materialize-indexes-CAkIYFV-.d.ts} +1 -1
  135. package/dist/{materialize-indexes-DEYkU-wr.d.cts → materialize-indexes-D20xNluI.d.cts} +1 -1
  136. package/dist/{postgres-4J2tmauh.d.cts → postgres-MzBPkYzq.d.ts} +2651 -596
  137. package/dist/{postgres-BdIb7tS_.d.ts → postgres-_9psmVGm.d.cts} +2651 -596
  138. package/dist/profiler/index.cjs +4 -3
  139. package/dist/profiler/index.cjs.map +1 -1
  140. package/dist/profiler/index.d.cts +7 -7
  141. package/dist/profiler/index.d.ts +7 -7
  142. package/dist/profiler/index.js +2 -1
  143. package/dist/profiler/index.js.map +1 -1
  144. package/dist/schema/index.cjs +30 -29
  145. package/dist/schema/index.cjs.map +1 -1
  146. package/dist/schema/index.d.cts +7 -7
  147. package/dist/schema/index.d.ts +7 -7
  148. package/dist/schema/index.js +7 -6
  149. package/dist/schema/index.js.map +1 -1
  150. package/dist/{sqlite-aM_PAz-O.d.ts → sqlite-BfksSb45.d.cts} +2726 -455
  151. package/dist/{sqlite-Gatk_iw_.d.cts → sqlite-gm44dShb.d.ts} +2726 -455
  152. package/dist/{store-DuCbdqsh.d.cts → store-view-9jQ2rPum.d.cts} +1101 -465
  153. package/dist/{store-MloRPwb9.d.ts → store-view-FfE5_7eo.d.ts} +1101 -465
  154. package/dist/{types-DoByHGyU.d.cts → types-B6mhrcLv.d.cts} +2 -2
  155. package/dist/{types-C1CYxWrL.d.cts → types-C_UnQOQp.d.cts} +154 -23
  156. package/dist/{types-K3vpaJAL.d.ts → types-CdWxK-nD.d.ts} +2 -2
  157. package/dist/{types-BKQljXom.d.ts → types-DGylBhWo.d.ts} +154 -23
  158. package/dist/{where-DydZjGOb.d.cts → where-Bpp2ul_z.d.cts} +2 -2
  159. package/dist/{where-Dt49bvo6.d.ts → where-BsEXraKW.d.ts} +2 -2
  160. package/package.json +2 -2
  161. package/dist/chunk-2HZGWCB4.js.map +0 -1
  162. package/dist/chunk-3JBJEYWE.cjs.map +0 -1
  163. package/dist/chunk-4A4GUZTQ.js.map +0 -1
  164. package/dist/chunk-54JVNOAQ.cjs.map +0 -1
  165. package/dist/chunk-6G35I3VW.cjs +0 -40
  166. package/dist/chunk-6G35I3VW.cjs.map +0 -1
  167. package/dist/chunk-6RMLO5O4.cjs.map +0 -1
  168. package/dist/chunk-7JGLPAFV.cjs.map +0 -1
  169. package/dist/chunk-CIINW6PS.cjs.map +0 -1
  170. package/dist/chunk-FLOI7QOT.cjs.map +0 -1
  171. package/dist/chunk-GKFWM3DS.js.map +0 -1
  172. package/dist/chunk-IJORSAC3.js.map +0 -1
  173. package/dist/chunk-M6OC455F.js +0 -65
  174. package/dist/chunk-M6OC455F.js.map +0 -1
  175. package/dist/chunk-MAQJYNJR.js.map +0 -1
  176. package/dist/chunk-MXE2U3EX.js.map +0 -1
  177. package/dist/chunk-RP7YITHX.cjs +0 -70
  178. package/dist/chunk-RP7YITHX.cjs.map +0 -1
  179. package/dist/chunk-RZ4DH4E7.cjs.map +0 -1
  180. package/dist/chunk-SAJSMR2B.js +0 -35
  181. package/dist/chunk-SAJSMR2B.js.map +0 -1
  182. package/dist/chunk-SFFJ2IKN.cjs.map +0 -1
  183. package/dist/chunk-STP7QVUB.js.map +0 -1
  184. package/dist/chunk-THX25XW6.js.map +0 -1
  185. package/dist/chunk-UIFEEPME.js.map +0 -1
  186. package/dist/chunk-V4IQYOQ4.cjs.map +0 -1
  187. package/dist/chunk-VZX2KSY3.js.map +0 -1
  188. package/dist/chunk-YQGLVWB2.cjs.map +0 -1
@@ -1,9 +1,8 @@
1
+ import { K as KindRegistry, G as GraphDef, w as EdgeKinds, t as NodeKinds, v as AllNodeTypes, c as SchemaManagerOptions, d as SchemaValidationResult } from './manager-BYl_zyZR.cjs';
2
+ import { T as TemporalMode, A as AnyEdgeType, N as NodeType, g as EdgeType, E as EdgeRegistration, e as EdgeId, d as NodeId, b as NodeRegistration, K as KindEntity, m as Cardinality, q as EndpointExistence, f as KindAnnotations, s as UniquenessScope, n as Collation, G as GraphExtension } from './extension-types-YGFJPrzK.cjs';
1
3
  import { z } from 'zod';
2
- import { aA as ValueType, aB as PredicateExpression, aC as VectorMetricType, a1 as FulltextQueryMode, Q as QueryAst, J as JsonPointer, P as FieldRef, ad as ParameterRef, G as GraphBackend, am as TransactionBackend, a6 as JsonPointerInput, an as TraversalExpansion, p as SqlDialect, ai as SqlSchema, aD as Traversal, aE as NodePredicate, aF as ProjectedField, ac as OrderSpec, aG as GroupBySpec, a4 as HybridFusionOptions, aH as RecursiveCyclePolicy, aI as TraversalDirection$1, aJ as EdgeRow, aK as NodeRow, W as AdoptedTransaction, L as AggregateExpr, F as FulltextStrategy, V as VectorStrategy, aL as VectorSlotMap, aM as SelectiveField, aN as ComposableQuery, aO as SetOperationType, aP as SetOperation, ah as SortDirection, m as JsonSchema, aQ as VectorMetric } from './types-C1CYxWrL.cjs';
3
- import { K as KindRegistry, G as GraphDef, w as EdgeKinds, t as NodeKinds, v as AllNodeTypes, c as SchemaManagerOptions, d as SchemaValidationResult } from './manager-Np7VVSlE.cjs';
4
- import { A as AnyEdgeType, N as NodeType, T as TemporalMode, g as EdgeType, E as EdgeRegistration, e as EdgeId, d as NodeId, b as NodeRegistration, K as KindEntity, m as Cardinality, n as EndpointExistence, f as KindAnnotations, U as UniquenessScope, C as Collation, G as GraphExtension } from './extension-types-D1k0inWU.cjs';
5
- import { SQL } from 'drizzle-orm';
6
- import { b as MaterializeIndexesOptions, M as MaterializeIndexesResult } from './materialize-indexes-DEYkU-wr.cjs';
4
+ import { b7 as ValueType, b8 as PredicateExpression, b9 as VectorMetricType, ae as FulltextQueryMode, Q as QueryAst, J as JsonPointer, P as FieldRef, ax as ParameterRef, G as GraphBackend, aP as TransactionBackend, ao as JsonPointerInput, aQ as TraversalExpansion, p as SqlDialect, aL as SqlSchema, ba as Traversal, bb as NodePredicate, bc as ProjectedField, aw as OrderSpec, bd as GroupBySpec, ak as HybridFusionOptions, be as RecursiveCyclePolicy, W as TraversalDirection$1, bf as EdgeRow, bg as NodeRow, aa as ExternalRecordedReadSource, X as AdoptedTransaction, L as AggregateExpr, a3 as CompiledSelectSql, F as FulltextStrategy, V as VectorStrategy, bh as VectorSlotMap, bi as RecordedReadBinding, bj as SelectiveField, bk as ComposableQuery, bl as SetOperationType, bm as SetOperation, aJ as SortDirection, bn as VectorMetric, m as JsonSchema, bo as TransactionOptions } from './types-C_UnQOQp.cjs';
5
+ import { b as MaterializeIndexesOptions, M as MaterializeIndexesResult } from './materialize-indexes-D20xNluI.cjs';
7
6
 
8
7
  /**
9
8
  * Embedding type for vector search.
@@ -216,6 +215,60 @@ declare function searchable(options?: SearchableOptions): SearchableSchema;
216
215
  declare function isSearchableSchema(value: unknown): value is SearchableSchema;
217
216
  declare function getSearchableMetadata(schema: z.ZodType): SearchableMetadata | undefined;
218
217
 
218
+ declare const RECORDED_INSTANT_BRAND: unique symbol;
219
+ /**
220
+ * A canonical UTC ISO-8601 recorded-time instant (`YYYY-MM-DDTHH:mm:ss.sssZ`),
221
+ * nominally branded so it can only originate from a recorded-time source —
222
+ * {@link Store.recordedNow} or an explicit {@link asRecordedInstant} — never an
223
+ * ad-hoc wall-clock string.
224
+ *
225
+ * The recorded commit clock is a logical, monotonic per-graph instant that can
226
+ * run briefly ahead of wall time under bursty same-millisecond writes, so a raw
227
+ * `new Date().toISOString()` may sort *before* the most recent commits and
228
+ * silently omit them. The brand turns that footgun into a compile error:
229
+ * `store.asOfRecorded` accepts only a `RecordedInstant`, so a bare wall-clock
230
+ * string no longer type-checks — callers reach for `await store.recordedNow()`
231
+ * (the monotonic high-water mark) or {@link asRecordedInstant} instead.
232
+ */
233
+ type RecordedInstant = string & {
234
+ readonly [RECORDED_INSTANT_BRAND]: "RecordedInstant";
235
+ };
236
+ /**
237
+ * Brands a canonical UTC ISO-8601 string as a {@link RecordedInstant}.
238
+ *
239
+ * The escape hatch for an instant that round-trips through untyped storage:
240
+ * captured from {@link Store.recordedNow}, persisted as a plain string, read
241
+ * back, and replayed into `asOfRecorded`. Validates the canonical form eagerly —
242
+ * the same check `asOfRecorded` applies — so a malformed value fails here, at the
243
+ * brand site, rather than deeper in a read. Does *not* assert the instant is a
244
+ * real captured commit; it only guarantees the value is well-formed enough to
245
+ * compare correctly against the recorded relations.
246
+ *
247
+ * @throws {ValidationError} when `value` is not a canonical UTC ISO-8601 string.
248
+ */
249
+ declare function asRecordedInstant(value: string): RecordedInstant;
250
+ /**
251
+ * The single opaque temporal coordinate every pinned read is resolved
252
+ * against. It carries the valid-time axis plus an optional recorded/system-time
253
+ * axis, so every surface can inject one coordinate object instead of threading
254
+ * each temporal dimension separately.
255
+ */
256
+ type ReadCoordinate = Readonly<{
257
+ /**
258
+ * The valid-time axis: a resolved temporal mode and (only for `"asOf"`) the
259
+ * instant it is pinned to.
260
+ */
261
+ valid: Readonly<{
262
+ mode: TemporalMode;
263
+ /** Defined only when `mode` is `"asOf"`. */
264
+ asOf?: string;
265
+ }>;
266
+ /** The recorded/system-time axis. Defined only for recorded-pinned views. */
267
+ recorded?: Readonly<{
268
+ asOf: RecordedInstant;
269
+ }>;
270
+ }>;
271
+
219
272
  type FieldTypeInfo = Readonly<{
220
273
  valueType: ValueType;
221
274
  elementType?: ValueType | undefined;
@@ -498,6 +551,7 @@ type DynamicSelectableEdge = Readonly<{
498
551
  * and ExecutableQuery classes.
499
552
  */
500
553
 
554
+ type QueryCoordinateState = "open" | "sealed";
501
555
  /**
502
556
  * A query that can be executed within a `store.batch()` call.
503
557
  *
@@ -540,6 +594,7 @@ type NodeAlias<K extends NodeType = NodeType, Optional extends boolean = false>
540
594
  * A map of alias names to their node aliases.
541
595
  */
542
596
  type AliasMap = Readonly<Record<string, NodeAlias<NodeType, boolean>>>;
597
+ type EmptyAliasMap = Readonly<Record<never, never>>;
543
598
  /**
544
599
  * An edge alias with its associated type and optional flag.
545
600
  */
@@ -552,6 +607,7 @@ type EdgeAlias<E extends AnyEdgeType = EdgeType, Optional extends boolean = fals
552
607
  * A map of alias names to their edge aliases.
553
608
  */
554
609
  type EdgeAliasMap = Readonly<Record<string, EdgeAlias<EdgeType, boolean>>>;
610
+ type EmptyEdgeAliasMap = Readonly<Record<never, never>>;
555
611
  /**
556
612
  * A recursive alias marker with its associated type (depth or path).
557
613
  */
@@ -562,6 +618,7 @@ type RecursiveAlias<T extends "depth" | "path"> = Readonly<{
562
618
  * A map of recursive alias names to their types.
563
619
  */
564
620
  type RecursiveAliasMap = Readonly<Record<string, RecursiveAlias<"depth" | "path">>>;
621
+ type EmptyRecursiveAliasMap = Readonly<Record<never, never>>;
565
622
  /**
566
623
  * Resolves a recursive alias marker to its runtime value type.
567
624
  */
@@ -841,7 +898,7 @@ type QueryBuilderConfig = Readonly<{
841
898
  defaultTraversalExpansion: TraversalExpansion;
842
899
  backend?: GraphBackend;
843
900
  dialect?: SqlDialect;
844
- /** SQL schema configuration for custom table names. */
901
+ /** SQL schema configuration from createSqlSchema(...) for custom table names. */
845
902
  schema?: SqlSchema;
846
903
  }>;
847
904
  /**
@@ -861,6 +918,7 @@ type QueryBuilderState = Readonly<{
861
918
  offset: number | undefined;
862
919
  temporalMode: TemporalMode;
863
920
  asOf: string | undefined;
921
+ recordedAsOf?: RecordedInstant | undefined;
864
922
  groupBy: GroupBySpec | undefined;
865
923
  having: PredicateExpression | undefined;
866
924
  fusion: HybridFusionOptions | undefined;
@@ -881,12 +939,43 @@ type CreateQueryBuilderOptions = Readonly<{
881
939
  backend?: GraphBackend;
882
940
  /** SQL dialect for compilation */
883
941
  dialect?: SqlDialect;
884
- /** SQL schema configuration for custom table names */
942
+ /** SQL schema configuration from createSqlSchema(...) for custom table names */
885
943
  schema?: SqlSchema;
886
944
  /** Default traversal ontology expansion mode (default: "inverse"). */
887
945
  defaultTraversalExpansion?: TraversalExpansion;
888
946
  }>;
889
947
 
948
+ /**
949
+ * StoreView collection surface buckets.
950
+ *
951
+ * The live NodeCollection / EdgeCollection partition into buckets a StoreView
952
+ * treats differently:
953
+ *
954
+ * - temporal reads honor the pinned coordinate;
955
+ * - current reads have no temporal axis and are refused on temporal pins;
956
+ * - writes are never available on a read-only view; and
957
+ * - batch reads require store.batch() and are absent from a view.
958
+ *
959
+ * These arrays are the single runtime source of truth for the proxy routing and
960
+ * the type-level source for the derived StoreView collection types. The
961
+ * StoreView surface-classification test asserts they exactly partition the live
962
+ * collection methods so new collection methods cannot be silently omitted.
963
+ */
964
+ /** Temporal-aware node read method names. */
965
+ declare const NODE_TEMPORAL_READ_NAMES: readonly ["getById", "getByIds", "find", "count"];
966
+ /** Current-state-only node reads (constraint / index lookups). */
967
+ declare const CURRENT_ONLY_READ_NAMES: readonly ["findByConstraint", "bulkFindByConstraint", "bulkFindByIndex"];
968
+ /** Node write method names: never available on a read-only StoreView. */
969
+ declare const NODE_WRITE_NAMES: readonly ["create", "createFromRecord", "update", "delete", "hardDelete", "upsertById", "upsertByIdFromRecord", "bulkCreate", "bulkUpsertById", "bulkInsert", "bulkDelete", "getOrCreateByConstraint", "bulkGetOrCreateByConstraint"];
970
+ /** Temporal-aware edge read method names. */
971
+ declare const EDGE_TEMPORAL_READ_NAMES: readonly ["getById", "getByIds", "find", "count", "findFrom", "findTo", "findByEndpoints"];
972
+ /** Deferred edge batch-read method names. */
973
+ declare const EDGE_BATCH_READ_NAMES: readonly ["batchFindFrom", "batchFindTo", "batchFindByEndpoints"];
974
+ /** Edge write method names: never available on a read-only StoreView. */
975
+ declare const EDGE_WRITE_NAMES: readonly ["create", "update", "delete", "hardDelete", "bulkCreate", "bulkUpsertById", "bulkInsert", "bulkDelete", "getOrCreateByEndpoints", "bulkGetOrCreateByEndpoints"];
976
+ /** Recorded-time collection point reads that reconstruct safely by id. */
977
+ declare const RECORDED_POINT_READ_NAMES: readonly ["getById", "getByIds"];
978
+
890
979
  /**
891
980
  * Store types for TypeGraph operations.
892
981
  */
@@ -1003,7 +1092,15 @@ type UpdateEdgeInput<E extends AnyEdgeType = EdgeType> = Readonly<{
1003
1092
  /**
1004
1093
  * Options for node and edge queries.
1005
1094
  */
1006
- type QueryOptions = Readonly<{
1095
+ type NoRecordedCoordinate = Readonly<{
1096
+ /**
1097
+ * Recorded/system-time coordinates are internal-only and supplied by
1098
+ * RecordedStoreView. A public options object carrying this key is a type
1099
+ * error even when the object is pre-bound before the call site.
1100
+ */
1101
+ recordedAsOf?: never;
1102
+ }>;
1103
+ type QueryOptions = NoRecordedCoordinate & Readonly<{
1007
1104
  /** Temporal mode for the query */
1008
1105
  temporalMode?: TemporalMode;
1009
1106
  /** Specific timestamp for asOf queries */
@@ -1083,13 +1180,10 @@ type StoreHooks = Readonly<{
1083
1180
  /** Called when an error occurs */
1084
1181
  onError?: (ctx: HookContext, error: Error) => void;
1085
1182
  }>;
1086
- /**
1087
- * Options for creating a store.
1088
- */
1089
- type StoreOptions = Readonly<{
1183
+ type BaseStoreOptions = Readonly<{
1090
1184
  /** Observability hooks for monitoring */
1091
1185
  hooks?: StoreHooks;
1092
- /** SQL schema configuration for custom table names */
1186
+ /** SQL schema configuration from createSqlSchema(...) for custom table names */
1093
1187
  schema?: SqlSchema;
1094
1188
  /** Query default behaviors. */
1095
1189
  queryDefaults?: Readonly<{
@@ -1097,6 +1191,28 @@ type StoreOptions = Readonly<{
1097
1191
  traversalExpansion?: TraversalExpansion;
1098
1192
  }>;
1099
1193
  }>;
1194
+ /**
1195
+ * Store options without built-in recorded-time capture. A recorded read relation
1196
+ * can still be bound explicitly for hosts that populate history externally.
1197
+ */
1198
+ type LiveStoreOptions = BaseStoreOptions & Readonly<{
1199
+ history?: false | undefined;
1200
+ recordedRead?: ExternalRecordedReadSource | undefined;
1201
+ }>;
1202
+ /**
1203
+ * Store options with TypeGraph-managed recorded-time capture. `history: true`
1204
+ * captures TypeGraph writes and binds TypeGraph's built-in recorded relation
1205
+ * internally. Externally populated recorded read sources are read-only bindings
1206
+ * and are intentionally accepted only by {@link LiveStoreOptions}.
1207
+ */
1208
+ type HistoryStoreOptions = BaseStoreOptions & Readonly<{
1209
+ history: true;
1210
+ recordedRead?: never;
1211
+ }>;
1212
+ /**
1213
+ * Options for creating a store.
1214
+ */
1215
+ type StoreOptions = LiveStoreOptions | HistoryStoreOptions;
1100
1216
  /**
1101
1217
  * A mutable handle to the current `Store`, used by `store.evolve(...)`
1102
1218
  * so long-lived consumers can dereference through the ref and pick up
@@ -1174,7 +1290,7 @@ type EdgeGetOrCreateByEndpointsResult<E extends AnyEdgeType, From extends NodeTy
1174
1290
  type EdgeFindByEndpointsOptions<E extends AnyEdgeType> = Readonly<{
1175
1291
  /**
1176
1292
  * Edge property fields to include in the match alongside the (from, to) endpoints.
1177
- * When omitted, matches on endpoints only (returns first live edge).
1293
+ * When omitted, matches on endpoints only (returns the first edge at the read coordinate).
1178
1294
  */
1179
1295
  matchOn?: readonly (keyof z.input<E["schema"]>)[];
1180
1296
  /** Property values to match against when matchOn is specified. */
@@ -1232,15 +1348,13 @@ type NodeCollection<N extends NodeType, CN extends string = string> = Readonly<{
1232
1348
  * Supports predicate filtering via the `where` option for SQL-level filtering.
1233
1349
  * For simple queries. Use store.query() for complex traversals.
1234
1350
  */
1235
- find: (options?: Readonly<{
1351
+ find: (filter?: Readonly<{
1236
1352
  where?: (accessor: NodeAccessor<N>) => Predicate;
1237
1353
  limit?: number;
1238
1354
  offset?: number;
1239
- temporalMode?: TemporalMode;
1240
- asOf?: string;
1241
- }>) => Promise<Node<N>[]>;
1355
+ }>, temporal?: QueryOptions) => Promise<Node<N>[]>;
1242
1356
  /** Count nodes matching criteria */
1243
- count: (options?: QueryOptions) => Promise<number>;
1357
+ count: (temporal?: QueryOptions) => Promise<number>;
1244
1358
  /**
1245
1359
  * Create a node from untyped data, relying on runtime Zod validation.
1246
1360
  *
@@ -1451,29 +1565,43 @@ type EdgeCollection<E extends AnyEdgeType, From extends NodeType = NodeType, To
1451
1565
  update: (id: EdgeId<E>, props: Partial<z.input<E["schema"]>>, options?: Readonly<{
1452
1566
  validTo?: string;
1453
1567
  }>) => Promise<Edge<E, From, To>>;
1454
- /** Find edges from a specific node */
1455
- findFrom: (from: NodeRef<From>) => Promise<Edge<E, From, To>[]>;
1456
- /** Find edges to a specific node */
1457
- findTo: (to: NodeRef<To>) => Promise<Edge<E, From, To>[]>;
1568
+ /**
1569
+ * Find edges from a specific node.
1570
+ *
1571
+ * Honors the same temporal model as `getById` / `find`: with no
1572
+ * `options`, the graph's default `temporalMode` applies (excluding
1573
+ * soft-deleted edges and, in `current` / `asOf` modes, edges outside
1574
+ * their validity window). Pass `temporalMode` / `asOf` to read the
1575
+ * endpoint's edges at another temporal coordinate.
1576
+ */
1577
+ findFrom: (from: NodeRef<From>, options?: QueryOptions) => Promise<Edge<E, From, To>[]>;
1578
+ /**
1579
+ * Find edges to a specific node.
1580
+ *
1581
+ * Temporal semantics mirror {@link EdgeCollection.findFrom}.
1582
+ */
1583
+ findTo: (to: NodeRef<To>, options?: QueryOptions) => Promise<Edge<E, From, To>[]>;
1458
1584
  /**
1459
1585
  * Deferred variant of `findFrom` for use with `store.batch()`.
1460
1586
  *
1461
- * Returns a `BatchableQuery` instead of executing immediately.
1587
+ * Returns a `BatchableQuery` instead of executing immediately. Accepts
1588
+ * the same temporal `options` as {@link EdgeCollection.findFrom}.
1462
1589
  */
1463
- batchFindFrom: (from: NodeRef<From>) => BatchableQuery<Edge<E, From, To>>;
1590
+ batchFindFrom: (from: NodeRef<From>, options?: QueryOptions) => BatchableQuery<Edge<E, From, To>>;
1464
1591
  /**
1465
1592
  * Deferred variant of `findTo` for use with `store.batch()`.
1466
1593
  *
1467
- * Returns a `BatchableQuery` instead of executing immediately.
1594
+ * Returns a `BatchableQuery` instead of executing immediately. Accepts
1595
+ * the same temporal `options` as {@link EdgeCollection.findTo}.
1468
1596
  */
1469
- batchFindTo: (to: NodeRef<To>) => BatchableQuery<Edge<E, From, To>>;
1597
+ batchFindTo: (to: NodeRef<To>, options?: QueryOptions) => BatchableQuery<Edge<E, From, To>>;
1470
1598
  /**
1471
1599
  * Deferred variant of `findByEndpoints` for use with `store.batch()`.
1472
1600
  *
1473
1601
  * Returns a `BatchableQuery` that yields a 0-or-1 element array
1474
1602
  * (matching `findByEndpoints`' at-most-one semantics).
1475
1603
  */
1476
- batchFindByEndpoints: (from: NodeRef<From>, to: NodeRef<To>, options?: EdgeFindByEndpointsOptions<E>) => BatchableQuery<Edge<E, From, To>>;
1604
+ batchFindByEndpoints: (from: NodeRef<From>, to: NodeRef<To>, options?: EdgeFindByEndpointsOptions<E>, temporal?: QueryOptions) => BatchableQuery<Edge<E, From, To>>;
1477
1605
  /** Delete an edge (soft delete - sets deletedAt timestamp) */
1478
1606
  delete: (id: EdgeId<E>) => Promise<void>;
1479
1607
  /**
@@ -1487,21 +1615,17 @@ type EdgeCollection<E extends AnyEdgeType, From extends NodeType = NodeType, To
1487
1615
  */
1488
1616
  hardDelete: (id: EdgeId<E>) => Promise<void>;
1489
1617
  /** Find edges matching endpoint and pagination criteria */
1490
- find: (options?: Readonly<{
1618
+ find: (filter?: Readonly<{
1491
1619
  from?: NodeRef<From>;
1492
1620
  to?: NodeRef<To>;
1493
1621
  limit?: number;
1494
1622
  offset?: number;
1495
- temporalMode?: TemporalMode;
1496
- asOf?: string;
1497
- }>) => Promise<Edge<E, From, To>[]>;
1623
+ }>, temporal?: QueryOptions) => Promise<Edge<E, From, To>[]>;
1498
1624
  /** Count edges matching criteria */
1499
- count: (options?: Readonly<{
1625
+ count: (filter?: Readonly<{
1500
1626
  from?: NodeRef<From>;
1501
1627
  to?: NodeRef<To>;
1502
- temporalMode?: TemporalMode;
1503
- asOf?: string;
1504
- }>) => Promise<number>;
1628
+ }>, temporal?: QueryOptions) => Promise<number>;
1505
1629
  /**
1506
1630
  * Create multiple edges in a batch.
1507
1631
  *
@@ -1553,16 +1677,22 @@ type EdgeCollection<E extends AnyEdgeType, From extends NodeType = NodeType, To
1553
1677
  */
1554
1678
  bulkDelete: (ids: readonly EdgeId<E>[]) => Promise<void>;
1555
1679
  /**
1556
- * Find a live edge by endpoints and optional property fields.
1680
+ * Find an edge by endpoints and optional property fields.
1557
1681
  *
1558
- * Returns the first matching live edge, or undefined.
1559
- * Soft-deleted edges are excluded.
1682
+ * Returns the first matching edge at the read coordinate, or undefined.
1683
+ * Honors the temporal model like `findFrom` / `findTo`: by default
1684
+ * (`current` mode) soft-deleted and out-of-window edges are excluded; under
1685
+ * `includeTombstones` a soft-deleted edge can be returned.
1560
1686
  *
1561
1687
  * @param from - Source node
1562
1688
  * @param to - Target node
1563
1689
  * @param options - Match criteria (matchOn fields and property values)
1690
+ * @param temporal - Temporal coordinate. With no `temporal`, the graph's
1691
+ * default `temporalMode` applies (so under the default `"current"` mode,
1692
+ * edges outside their validity window are excluded). Pass
1693
+ * `temporalMode` / `asOf` to read the edge as of another coordinate.
1564
1694
  */
1565
- findByEndpoints: (from: NodeRef<From>, to: NodeRef<To>, options?: EdgeFindByEndpointsOptions<E>) => Promise<Edge<E, From, To> | undefined>;
1695
+ findByEndpoints: (from: NodeRef<From>, to: NodeRef<To>, options?: EdgeFindByEndpointsOptions<E>, temporal?: QueryOptions) => Promise<Edge<E, From, To> | undefined>;
1566
1696
  /**
1567
1697
  * Get an existing edge by endpoints and optional property fields, or create a new one.
1568
1698
  *
@@ -1619,6 +1749,105 @@ type GraphNodeCollections<G extends GraphDef> = {
1619
1749
  type GraphEdgeCollections<G extends GraphDef> = {
1620
1750
  [K in keyof G["edges"] & string]-?: TypedEdgeCollection<G["edges"][K]>;
1621
1751
  };
1752
+ /** Temporal-aware node reads — a {@link StoreView} pins these. */
1753
+ type NodeTemporalReads<N extends NodeType, CN extends string = string> = Pick<NodeCollection<N, CN>, (typeof NODE_TEMPORAL_READ_NAMES)[number]>;
1754
+ /**
1755
+ * Current-state-only node reads (constraint / index lookups). No temporal
1756
+ * axis, so a {@link StoreView} delegates them on a `current` pin and refuses
1757
+ * them on a temporal pin.
1758
+ */
1759
+ type NodeCurrentReads<N extends NodeType, CN extends string = string> = Pick<NodeCollection<N, CN>, (typeof CURRENT_ONLY_READ_NAMES)[number]>;
1760
+ /** Node writes — never available on a read-only {@link StoreView}. */
1761
+ type NodeWrites<N extends NodeType, CN extends string = string> = Pick<NodeCollection<N, CN>, (typeof NODE_WRITE_NAMES)[number]>;
1762
+ /** Temporal-aware edge reads — a {@link StoreView} pins these. */
1763
+ type EdgeTemporalReads<E extends AnyEdgeType, From extends NodeType = NodeType, To extends NodeType = NodeType> = Pick<EdgeCollection<E, From, To>, (typeof EDGE_TEMPORAL_READ_NAMES)[number]>;
1764
+ /**
1765
+ * Deferred edge reads for `store.batch()` — absent from a {@link StoreView},
1766
+ * which has no batch context.
1767
+ */
1768
+ type EdgeBatchReads<E extends AnyEdgeType, From extends NodeType = NodeType, To extends NodeType = NodeType> = Pick<EdgeCollection<E, From, To>, (typeof EDGE_BATCH_READ_NAMES)[number]>;
1769
+ /** Edge writes — never available on a read-only {@link StoreView}. */
1770
+ type EdgeWrites<E extends AnyEdgeType, From extends NodeType = NodeType, To extends NodeType = NodeType> = Pick<EdgeCollection<E, From, To>, (typeof EDGE_WRITE_NAMES)[number]>;
1771
+ /**
1772
+ * The read-only node surface a {@link StoreView} exposes for one node kind.
1773
+ * The temporal reads drop the per-call temporal argument — the pin owns the
1774
+ * axis; the current reads ({@link NodeCurrentReads}) are exposed as-is
1775
+ * (delegated on a `current` view, refused on a temporal pin). Writes live on
1776
+ * the live `Store`. The conformance test asserts the temporal part equals the
1777
+ * pinned form of {@link NodeTemporalReads}.
1778
+ */
1779
+ type StoreViewNodeCollection<N extends NodeType, CN extends string = string> = Readonly<{
1780
+ /** Get a node by ID at the view's pinned coordinate. */
1781
+ getById: (id: NodeId<N>) => Promise<Node<N> | undefined>;
1782
+ /** Get multiple nodes by ID, preserving input order (undefined for missing). */
1783
+ getByIds: (ids: readonly NodeId<N>[]) => Promise<readonly (Node<N> | undefined)[]>;
1784
+ /** Find nodes matching criteria at the view's pinned coordinate. */
1785
+ find: (filter?: Readonly<{
1786
+ where?: (accessor: NodeAccessor<N>) => Predicate;
1787
+ limit?: number;
1788
+ offset?: number;
1789
+ }>) => Promise<Node<N>[]>;
1790
+ /** Count nodes at the view's pinned coordinate. */
1791
+ count: () => Promise<number>;
1792
+ }> & NodeCurrentReads<N, CN>;
1793
+ /**
1794
+ * The read-only edge surface a {@link StoreView} exposes for one edge
1795
+ * kind, mirroring {@link StoreViewNodeCollection}. Every edge read —
1796
+ * including `findByEndpoints` — honors the pin via the same temporal model,
1797
+ * so (unlike nodes) there are no current-state-only edge reads.
1798
+ */
1799
+ type StoreViewEdgeCollection<E extends AnyEdgeType, From extends NodeType = NodeType, To extends NodeType = NodeType> = Readonly<{
1800
+ /** Get an edge by ID at the view's pinned coordinate. */
1801
+ getById: (id: EdgeId<E>) => Promise<Edge<E, From, To> | undefined>;
1802
+ /** Get multiple edges by ID, preserving input order (undefined for missing). */
1803
+ getByIds: (ids: readonly EdgeId<E>[]) => Promise<readonly (Edge<E, From, To> | undefined)[]>;
1804
+ /** Find edges matching endpoint and pagination criteria. */
1805
+ find: (filter?: Readonly<{
1806
+ from?: NodeRef<From>;
1807
+ to?: NodeRef<To>;
1808
+ limit?: number;
1809
+ offset?: number;
1810
+ }>) => Promise<Edge<E, From, To>[]>;
1811
+ /** Count edges matching criteria at the view's pinned coordinate. */
1812
+ count: (filter?: Readonly<{
1813
+ from?: NodeRef<From>;
1814
+ to?: NodeRef<To>;
1815
+ }>) => Promise<number>;
1816
+ /** Find edges from a specific node at the view's pinned coordinate. */
1817
+ findFrom: (from: NodeRef<From>) => Promise<Edge<E, From, To>[]>;
1818
+ /** Find edges to a specific node at the view's pinned coordinate. */
1819
+ findTo: (to: NodeRef<To>) => Promise<Edge<E, From, To>[]>;
1820
+ /** Find the edge between two endpoints at the view's pinned coordinate. */
1821
+ findByEndpoints: (from: NodeRef<From>, to: NodeRef<To>, options?: EdgeFindByEndpointsOptions<E>) => Promise<Edge<E, From, To> | undefined>;
1822
+ }>;
1823
+ /**
1824
+ * Read-only view edge collection derived from an `EdgeRegistration`,
1825
+ * extracting the edge type and from/to node types — the read-only
1826
+ * counterpart of {@link TypedEdgeCollection}.
1827
+ */
1828
+ type TypedStoreViewEdgeCollection<R extends EdgeRegistration> = StoreViewEdgeCollection<R["type"], EdgeFromTypes<R> extends NodeType ? EdgeFromTypes<R> : NodeType, EdgeToTypes<R> extends NodeType ? EdgeToTypes<R> : NodeType>;
1829
+ /** Mapped type of all read-only view node collections for a graph. */
1830
+ type StoreViewNodeCollections<G extends GraphDef> = {
1831
+ [K in keyof G["nodes"] & string]-?: StoreViewNodeCollection<G["nodes"][K]["type"]>;
1832
+ };
1833
+ /** Mapped type of all read-only view edge collections for a graph. */
1834
+ type StoreViewEdgeCollections<G extends GraphDef> = {
1835
+ [K in keyof G["edges"] & string]-?: TypedStoreViewEdgeCollection<G["edges"][K]>;
1836
+ };
1837
+ /** Recorded-time node point reads for one node kind. */
1838
+ type RecordedStoreViewNodeCollection<N extends NodeType> = Pick<StoreViewNodeCollection<N>, (typeof RECORDED_POINT_READ_NAMES)[number]>;
1839
+ /** Recorded-time edge point reads for one edge kind. */
1840
+ type RecordedStoreViewEdgeCollection<E extends AnyEdgeType, From extends NodeType = NodeType, To extends NodeType = NodeType> = Pick<StoreViewEdgeCollection<E, From, To>, (typeof RECORDED_POINT_READ_NAMES)[number]>;
1841
+ /** Recorded-time edge collection derived from an `EdgeRegistration`. */
1842
+ type TypedRecordedStoreViewEdgeCollection<R extends EdgeRegistration> = RecordedStoreViewEdgeCollection<R["type"], EdgeFromTypes<R> extends NodeType ? EdgeFromTypes<R> : NodeType, EdgeToTypes<R> extends NodeType ? EdgeToTypes<R> : NodeType>;
1843
+ /** Mapped type of all recorded-time node point-read collections. */
1844
+ type RecordedStoreViewNodeCollections<G extends GraphDef> = {
1845
+ [K in keyof G["nodes"] & string]-?: RecordedStoreViewNodeCollection<G["nodes"][K]["type"]>;
1846
+ };
1847
+ /** Mapped type of all recorded-time edge point-read collections. */
1848
+ type RecordedStoreViewEdgeCollections<G extends GraphDef> = {
1849
+ [K in keyof G["edges"] & string]-?: TypedRecordedStoreViewEdgeCollection<G["edges"][K]>;
1850
+ };
1622
1851
  /**
1623
1852
  * A typed transaction context with collection API.
1624
1853
  *
@@ -1660,6 +1889,12 @@ type GraphEdgeCollections<G extends GraphDef> = {
1660
1889
  * Its type is the `AdoptedTransaction` union; cast to your concrete
1661
1890
  * Drizzle database type at the call site.
1662
1891
  *
1892
+ * When the store was created with `{ history: true }`, `tx.sql` is present but
1893
+ * replaced by a fail-loud guard because raw SQL would bypass recorded-time
1894
+ * capture. Use the typed `tx.nodes` / `tx.edges` collections inside
1895
+ * `transaction()`, or use `store.withRecordedTransaction(externalTx, fn)` when
1896
+ * the relational layer owns the transaction boundary.
1897
+ *
1663
1898
  * @example
1664
1899
  * ```typescript
1665
1900
  * await store.transaction(async (tx) => {
@@ -1673,6 +1908,13 @@ type TransactionContext<G extends GraphDef> = Readonly<{
1673
1908
  nodes: GraphNodeCollections<G>;
1674
1909
  edges: GraphEdgeCollections<G>;
1675
1910
  sql?: AdoptedTransaction;
1911
+ /**
1912
+ * The transaction-scoped backend the collections are bound to, for advanced
1913
+ * raw reads that must observe the transaction's snapshot (e.g. graph-merge's
1914
+ * in-transaction base@V re-validation). On the non-transactional fallback it
1915
+ * is the store's plain backend — reads work, but there is no snapshot.
1916
+ */
1917
+ backend: TransactionBackend;
1676
1918
  }>;
1677
1919
  /**
1678
1920
  * Replace branded `NodeId` / `EdgeId` with plain `string` in each
@@ -1758,268 +2000,70 @@ type StoreProjection<G extends GraphDef, N extends keyof G["nodes"] & string = n
1758
2000
  }>;
1759
2001
 
1760
2002
  /**
1761
- * Discriminated union of all Node runtime types in a graph.
1762
- *
1763
- * Unlike `AllNodeTypes<G>` which gives the union of *type definitions*,
1764
- * `AnyNode<G>` gives the union of *runtime node instances*.
1765
- */
1766
- type AnyNode<G extends GraphDef> = {
1767
- [K in NodeKinds<G>]: Node<G["nodes"][K]["type"]>;
1768
- }[NodeKinds<G>];
1769
- /**
1770
- * Discriminated union of all Edge runtime types in a graph.
2003
+ * ExecutableAggregateQuery - A query with aggregate functions that can be executed.
1771
2004
  */
1772
- type AnyEdge<G extends GraphDef> = {
1773
- [K in EdgeKinds<G>]: Edge<G["edges"][K]["type"]>;
1774
- }[EdgeKinds<G>];
2005
+
1775
2006
  /**
1776
- * Discriminated union of Node runtime types narrowed to a subset of kinds.
2007
+ * Result type for aggregate queries.
2008
+ * Maps field refs to their value types and aggregates to numbers.
1777
2009
  */
1778
- type SubsetNode<G extends GraphDef, K extends NodeKinds<G>> = {
1779
- [Kind in K]: Node<G["nodes"][Kind]["type"]>;
1780
- }[K];
2010
+ type AggregateResult<R extends Record<string, FieldRef | AggregateExpr>> = {
2011
+ [K in keyof R]: R[K] extends AggregateExpr ? number : R[K] extends FieldRef ? unknown : never;
2012
+ };
1781
2013
  /**
1782
- * Discriminated union of Edge runtime types narrowed to a subset of kinds.
2014
+ * An aggregate query that can be executed.
1783
2015
  */
1784
- type SubsetEdge<G extends GraphDef, K extends EdgeKinds<G>> = {
1785
- [Kind in K]: Edge<G["edges"][Kind]["type"]>;
1786
- }[K];
1787
- type EmptyShape = Readonly<Record<never, never>>;
1788
- type NodeProjectionPropertyKey<N extends NodeType> = Exclude<keyof Node<N>, "id" | "kind" | "meta"> & string;
1789
- type EdgeProjectionPropertyKey<E extends AnyEdgeType> = Exclude<keyof Edge<E>, "id" | "kind" | "fromKind" | "fromId" | "toKind" | "toId" | "meta"> & string;
1790
- type SubgraphNodeProjectionField<N extends NodeType = NodeType> = NodeProjectionPropertyKey<N> | "meta";
1791
- type SubgraphEdgeProjectionField<E extends AnyEdgeType = AnyEdgeType> = EdgeProjectionPropertyKey<E> | "meta";
1792
- type SubgraphNodeProjectionMap<G extends GraphDef, NK extends NodeKinds<G> = NodeKinds<G>> = Readonly<{
1793
- [K in NodeKinds<G>]?: K extends NK ? readonly SubgraphNodeProjectionField<G["nodes"][K]["type"]>[] : never;
1794
- }>;
1795
- type SubgraphEdgeProjectionMap<G extends GraphDef, EK extends EdgeKinds<G> = EdgeKinds<G>> = Readonly<{
1796
- [K in EdgeKinds<G>]?: K extends EK ? readonly SubgraphEdgeProjectionField<G["edges"][K]["type"]>[] : never;
1797
- }>;
1798
- type SubgraphProject<G extends GraphDef, NK extends NodeKinds<G> = NodeKinds<G>, EK extends EdgeKinds<G> = EdgeKinds<G>> = Readonly<{
2016
+ declare class ExecutableAggregateQuery<G extends GraphDef, Aliases extends AliasMap, R extends Record<string, FieldRef | AggregateExpr>> {
2017
+ #private;
2018
+ constructor(config: QueryBuilderConfig, state: QueryBuilderState, fields: R);
1799
2019
  /**
1800
- * Node fields to keep per kind.
1801
- *
1802
- * Projected nodes always retain `kind` and `id`.
1803
- * Use `"meta"` to include the full metadata object; omit it to exclude metadata entirely.
1804
- * Only kinds present in `includeKinds` (or all node kinds when omitted) are valid keys.
2020
+ * Builds the query AST.
1805
2021
  */
1806
- nodes?: SubgraphNodeProjectionMap<G, NK>;
2022
+ toAst(): QueryAst;
1807
2023
  /**
1808
- * Edge fields to keep per kind.
1809
- *
1810
- * Projected edges always retain `id`, `kind`, `fromKind`, `fromId`,
1811
- * `toKind`, and `toId`.
1812
- * Use `"meta"` to include the full metadata object; omit it to exclude metadata entirely.
1813
- * Only edge kinds listed in `edges` are valid keys.
2024
+ * Limits the number of results.
1814
2025
  */
1815
- edges?: SubgraphEdgeProjectionMap<G, EK>;
1816
- }>;
1817
- /**
1818
- * Identity function that preserves literal types for reusable projection configs.
1819
- *
1820
- * Without this helper, storing a projection in a typed variable widens the
1821
- * field arrays to `string[]`, defeating compile-time narrowing on results.
1822
- *
1823
- * @example
1824
- * ```ts
1825
- * const project = defineSubgraphProject(graph)({
1826
- * nodes: { Task: ["title", "meta"] },
1827
- * edges: { uses_skill: [] },
1828
- * });
1829
- * const result = await store.subgraph(rootId, { edges: ["uses_skill"], project });
1830
- * // result.nodes narrowed correctly — task.status is a type error
1831
- * ```
1832
- */
1833
- declare function defineSubgraphProject<G extends GraphDef>(_graph: G): <const P extends SubgraphProject<G>>(project: P) => P;
1834
- type HasMeta<Selection extends readonly string[] | undefined> = Selection extends readonly string[] ? "meta" extends Selection[number] ? true : false : false;
1835
- type SelectedNodeProps<N extends NodeType, Selection extends readonly string[] | undefined> = Selection extends readonly string[] ? Pick<Node<N>, Extract<Selection[number], NodeProjectionPropertyKey<N>>> : EmptyShape;
1836
- type SelectedEdgeProps<E extends AnyEdgeType, Selection extends readonly string[] | undefined> = Selection extends readonly string[] ? Pick<Edge<E>, Extract<Selection[number], EdgeProjectionPropertyKey<E>>> : EmptyShape;
1837
- type ProjectedNodeResult<N extends NodeType, Selection extends readonly string[] | undefined> = Readonly<Pick<Node<N>, "id" | "kind">> & Readonly<SelectedNodeProps<N, Selection>> & (HasMeta<Selection> extends true ? Readonly<{
1838
- meta: NodeMeta;
1839
- }> : EmptyShape);
1840
- type ProjectedEdgeResult<E extends AnyEdgeType, Selection extends readonly string[] | undefined> = Readonly<Pick<Edge<E>, "id" | "kind" | "fromKind" | "fromId" | "toKind" | "toId">> & Readonly<SelectedEdgeProps<E, Selection>> & (HasMeta<Selection> extends true ? Readonly<{
1841
- meta: EdgeMeta;
1842
- }> : EmptyShape);
1843
- type ProjectionSelection<P, Key extends "nodes" | "edges", Kind extends string> = P extends Readonly<{
1844
- [K in Key]?: infer Map;
1845
- }> ? Map extends Readonly<Record<string, readonly string[] | undefined>> ? Kind extends keyof Map ? Map[Kind] : undefined : undefined : undefined;
1846
- type SubgraphNodeResultForKind<G extends GraphDef, Kind extends NodeKinds<G>, P> = ProjectionSelection<P, "nodes", Kind> extends readonly string[] ? ProjectedNodeResult<G["nodes"][Kind]["type"], ProjectionSelection<P, "nodes", Kind>> : Node<G["nodes"][Kind]["type"]>;
1847
- type SubgraphEdgeResultForKind<G extends GraphDef, Kind extends EdgeKinds<G>, P> = ProjectionSelection<P, "edges", Kind> extends readonly string[] ? ProjectedEdgeResult<G["edges"][Kind]["type"], ProjectionSelection<P, "edges", Kind>> : Edge<G["edges"][Kind]["type"]>;
1848
- type SubgraphOptions<G extends GraphDef, EK extends EdgeKinds<G>, NK extends NodeKinds<G>, P extends SubgraphProject<G, NK, EK> | undefined = undefined> = Readonly<{
1849
- /** Edge kinds to follow during traversal. Edges not listed are not traversed. */
1850
- edges: readonly EK[];
1851
- /** Maximum traversal depth from root (default: 10). */
1852
- maxDepth?: number;
2026
+ limit(n: number): ExecutableAggregateQuery<G, Aliases, R>;
1853
2027
  /**
1854
- * Node kinds to include in the result. Nodes of other kinds are still
1855
- * traversed through but omitted from the output. When omitted, all
1856
- * reachable node kinds are included.
2028
+ * Offsets the results.
1857
2029
  */
1858
- includeKinds?: readonly NK[];
1859
- /** Exclude the root node from the result (default: false). */
1860
- excludeRoot?: boolean;
2030
+ offset(n: number): ExecutableAggregateQuery<G, Aliases, R>;
1861
2031
  /**
1862
- * Edge direction policy (default: "out").
1863
- * - "out": follow edges in their defined direction only
1864
- * - "both": follow edges in both directions (undirected traversal)
2032
+ * Compiles the query and returns the SQL text and parameters.
2033
+ *
2034
+ * Requires a backend to be configured (the backend determines the SQL dialect).
2035
+ * Use this for debugging, logging, or running the query with a custom executor.
1865
2036
  */
1866
- direction?: "out" | "both";
1867
- /** Cycle policy — reuse RecursiveCyclePolicy (default: "prevent"). */
1868
- cyclePolicy?: RecursiveCyclePolicy;
2037
+ toSQL(): Readonly<{
2038
+ sql: string;
2039
+ params: readonly unknown[];
2040
+ }>;
1869
2041
  /**
1870
- * Temporal mode applied to both nodes and edges along the traversal and in
1871
- * the hydrated result. Defaults to `graph.defaults.temporalMode`.
2042
+ * Compiles the query to a Drizzle SQL object.
1872
2043
  */
1873
- temporalMode?: TemporalMode;
1874
- /** ISO-8601 timestamp used when `temporalMode === "asOf"`. */
1875
- asOf?: string;
2044
+ compile(): CompiledSelectSql;
1876
2045
  /**
1877
- * Optional field-level projection per node/edge kind.
1878
- *
1879
- * Projected nodes keep `kind` and `id`; projected edges keep their structural
1880
- * endpoint fields. Kinds omitted from `project` remain fully hydrated.
1881
- * Projection applies to every returned entity, including the root node.
2046
+ * Executes the query and returns typed results.
1882
2047
  *
1883
- * Only kinds present in `includeKinds` (nodes) or `edges` (edges) are valid
1884
- * projection keys. Specifying a kind outside those sets is a compile-time error.
2048
+ * @throws Error if no backend is configured
1885
2049
  */
1886
- project?: P;
1887
- }>;
1888
- /**
1889
- * Union of all node result types in a subgraph, respecting projection.
1890
- */
1891
- type SubgraphNodeResult<G extends GraphDef, NK extends NodeKinds<G> = NodeKinds<G>, P = undefined> = {
1892
- [Kind in NK]: SubgraphNodeResultForKind<G, Kind, P>;
1893
- }[NK];
1894
- /**
1895
- * Union of all edge result types in a subgraph, respecting projection.
1896
- */
1897
- type SubgraphEdgeResult<G extends GraphDef, EK extends EdgeKinds<G> = EdgeKinds<G>, P = undefined> = {
1898
- [Kind in EK]: SubgraphEdgeResultForKind<G, Kind, P>;
1899
- }[EK];
1900
- type SubgraphResult<G extends GraphDef, NK extends NodeKinds<G> = NodeKinds<G>, EK extends EdgeKinds<G> = EdgeKinds<G>, P extends SubgraphProject<G, NK, EK> | undefined = undefined> = Readonly<{
1901
- /** The root node, or undefined if the root was not found or excluded. */
1902
- root: SubgraphNodeResult<G, NK, P> | undefined;
1903
- nodes: ReadonlyMap<string, SubgraphNodeResult<G, NK, P>>;
1904
- /** Forward adjacency: fromId → edgeKind → edges to targets. */
1905
- adjacency: ReadonlyMap<string, ReadonlyMap<EK, readonly SubgraphEdgeResult<G, EK, P>[]>>;
1906
- /** Reverse adjacency: toId → edgeKind → edges from sources. */
1907
- reverseAdjacency: ReadonlyMap<string, ReadonlyMap<EK, readonly SubgraphEdgeResult<G, EK, P>[]>>;
1908
- }>;
2050
+ execute(): Promise<readonly AggregateResult<R>[]>;
2051
+ }
1909
2052
 
1910
2053
  /**
1911
- * Data-cleanup phase for `store.removeKinds()`.
2054
+ * Query Compiler Module
1912
2055
  *
1913
- * The removeKinds verb commits the new schema atomically (millisecond
1914
- * budget); the data deletion happens here, scoped per-deployment via
1915
- * the `typegraph_kind_removals` status table. Splitting the verbs
1916
- * mirrors how `materializeIndexes` complements `evolve`: schema
1917
- * commits are atomic and fast, data work is bounded by row count and
1918
- * deferrable / parallelizable.
2056
+ * Main entry point for compiling query ASTs to SQL.
2057
+ * Re-exports individual compiler modules and provides the main compile functions.
1919
2058
  */
1920
2059
 
1921
- type MaterializeRemovalsOptions = Readonly<{
1922
- /** Restrict to specific kind names. */
1923
- kinds?: readonly string[];
1924
- /** Halt on first failure. Default: false (best-effort). */
1925
- stopOnError?: boolean;
1926
- }>;
1927
- type MaterializeRemovalsEntry = Readonly<{
1928
- kind: string;
1929
- entity: KindEntity;
1930
- status: "removed" | "failed";
1931
- error?: Error;
1932
- }>;
1933
2060
  /**
1934
- * Outcome of reclaiming one per-`(graphId, kind, field)` vector table that
1935
- * was orphaned when its embedding field was dropped from a *surviving*
1936
- * kind's schema. Distinct from {@link MaterializeRemovalsEntry} (whole
1937
- * kinds) because the unit is a single embedding field, not a kind.
1938
- */
1939
- type ReclaimedVectorFieldEntry = Readonly<{
1940
- kind: string;
1941
- fieldPath: string;
1942
- status: "reclaimed" | "failed";
1943
- error?: Error;
1944
- }>;
1945
- type MaterializeRemovalsResult = Readonly<{
1946
- results: readonly MaterializeRemovalsEntry[];
1947
- /**
1948
- * Embedding fields removed from a *surviving* kind whose per-field vector
1949
- * table this pass dropped (or confirmed already absent). Empty when the
1950
- * backend has no vector strategy or no embedding field has ever been
1951
- * dropped. Re-derived from immutable schema history each call, so it lists
1952
- * the same removed fields on repeat passes — the underlying drop is
1953
- * idempotent (`DROP ... IF EXISTS`). See {@link reclaimRemovedVectorFieldTables}.
1954
- */
1955
- reclaimedVectorFields: readonly ReclaimedVectorFieldEntry[];
1956
- }>;
1957
-
1958
- /**
1959
- * ExecutableAggregateQuery - A query with aggregate functions that can be executed.
1960
- */
1961
-
1962
- /**
1963
- * Result type for aggregate queries.
1964
- * Maps field refs to their value types and aggregates to numbers.
1965
- */
1966
- type AggregateResult<R extends Record<string, FieldRef | AggregateExpr>> = {
1967
- [K in keyof R]: R[K] extends AggregateExpr ? number : R[K] extends FieldRef ? unknown : never;
1968
- };
1969
- /**
1970
- * An aggregate query that can be executed.
1971
- */
1972
- declare class ExecutableAggregateQuery<G extends GraphDef, Aliases extends AliasMap, R extends Record<string, FieldRef | AggregateExpr>> {
1973
- #private;
1974
- constructor(config: QueryBuilderConfig, state: QueryBuilderState, fields: R);
1975
- /**
1976
- * Builds the query AST.
1977
- */
1978
- toAst(): QueryAst;
1979
- /**
1980
- * Limits the number of results.
1981
- */
1982
- limit(n: number): ExecutableAggregateQuery<G, Aliases, R>;
1983
- /**
1984
- * Offsets the results.
1985
- */
1986
- offset(n: number): ExecutableAggregateQuery<G, Aliases, R>;
1987
- /**
1988
- * Compiles the query and returns the SQL text and parameters.
1989
- *
1990
- * Requires a backend to be configured (the backend determines the SQL dialect).
1991
- * Use this for debugging, logging, or running the query with a custom executor.
1992
- */
1993
- toSQL(): Readonly<{
1994
- sql: string;
1995
- params: readonly unknown[];
1996
- }>;
1997
- /**
1998
- * Compiles the query to a Drizzle SQL object.
1999
- */
2000
- compile(): SQL;
2001
- /**
2002
- * Executes the query and returns typed results.
2003
- *
2004
- * @throws Error if no backend is configured
2005
- */
2006
- execute(): Promise<readonly AggregateResult<R>[]>;
2007
- }
2008
-
2009
- /**
2010
- * Query Compiler Module
2011
- *
2012
- * Main entry point for compiling query ASTs to SQL.
2013
- * Re-exports individual compiler modules and provides the main compile functions.
2014
- */
2015
-
2016
- /**
2017
- * Options for query compilation.
2061
+ * Options for query compilation.
2018
2062
  */
2019
2063
  type CompileQueryOptions = Readonly<{
2020
2064
  /** SQL dialect ("sqlite" or "postgres"). Defaults to "sqlite". */
2021
2065
  dialect?: SqlDialect | undefined;
2022
- /** SQL schema configuration for table names. Defaults to standard names. */
2066
+ /** SQL schema configuration from createSqlSchema(...). Defaults to standard names. */
2023
2067
  schema?: SqlSchema | undefined;
2024
2068
  /**
2025
2069
  * Fulltext strategy override. When set, overrides the dialect's
@@ -2048,6 +2092,13 @@ type CompileQueryOptions = Readonly<{
2048
2092
  * declare the field. Callers build it from the graph's node schemas.
2049
2093
  */
2050
2094
  vectorSlots?: VectorSlotMap | undefined;
2095
+ /**
2096
+ * Recorded read relation to use when the AST carries `recordedAsOf`.
2097
+ * Supplying a recorded timestamp without this binding is rejected so the
2098
+ * compiler never silently swaps to TypeGraph's built-in history tables when
2099
+ * the store was only configured for live/valid-time reads.
2100
+ */
2101
+ recordedReadBinding?: RecordedReadBinding | undefined;
2051
2102
  }>;
2052
2103
 
2053
2104
  type PreparedQueryConfig<R> = Readonly<{
@@ -2164,7 +2215,7 @@ declare class UnionableQuery<G extends GraphDef, R> {
2164
2215
  /**
2165
2216
  * Compiles the set operation to SQL.
2166
2217
  */
2167
- compile(): SQL;
2218
+ compile(): CompiledSelectSql;
2168
2219
  /**
2169
2220
  * Executes the combined query.
2170
2221
  */
@@ -2256,7 +2307,7 @@ declare class ExecutableQuery<G extends GraphDef, Aliases extends AliasMap, Edge
2256
2307
  * Returns a Drizzle SQL object that can be executed directly
2257
2308
  * with db.all(), db.get(), etc.
2258
2309
  */
2259
- compile(): SQL;
2310
+ compile(): CompiledSelectSql;
2260
2311
  /**
2261
2312
  * Creates a prepared (pre-compiled) query that can be executed
2262
2313
  * multiple times with different parameter bindings.
@@ -2355,7 +2406,7 @@ interface VariableLengthState {
2355
2406
  * Type parameters track the edge kind and direction to constrain
2356
2407
  * which node kinds are valid targets in the `to()` method.
2357
2408
  */
2358
- declare class TraversalBuilder<G extends GraphDef, Aliases extends AliasMap, EdgeAliases extends EdgeAliasMap = {}, EK extends keyof G["edges"] & string = keyof G["edges"] & string, EA extends string = string, Dir extends TraversalDirection$1 = "out", Optional extends boolean = false, DC extends boolean | string = false, PC extends boolean | string = false, RecAliases extends RecursiveAliasMap = {}> {
2409
+ declare class TraversalBuilder<G extends GraphDef, Aliases extends AliasMap, EdgeAliases extends EdgeAliasMap = EmptyEdgeAliasMap, EK extends keyof G["edges"] & string = keyof G["edges"] & string, EA extends string = string, Dir extends TraversalDirection$1 = "out", Optional extends boolean = false, DC extends boolean | string = false, PC extends boolean | string = false, RecAliases extends RecursiveAliasMap = EmptyRecursiveAliasMap, CoordinateState extends QueryCoordinateState = "open"> {
2359
2410
  #private;
2360
2411
  constructor(config: QueryBuilderConfig, state: QueryBuilderState, edgeKinds: readonly string[], edgeAlias: EA, direction: Dir, fromAlias: string, inverseEdgeKinds?: readonly string[], optional?: Optional, variableLength?: VariableLengthState, pendingEdgePredicates?: readonly NodePredicate[]);
2361
2412
  /**
@@ -2367,14 +2418,14 @@ declare class TraversalBuilder<G extends GraphDef, Aliases extends AliasMap, Edg
2367
2418
  depth: infer D extends boolean | string;
2368
2419
  } ? D : DC, O extends {
2369
2420
  path: infer P extends boolean | string;
2370
- } ? P : PC, RecAliases>;
2421
+ } ? P : PC, RecAliases, CoordinateState>;
2371
2422
  /**
2372
2423
  * Adds a WHERE clause for the edge being traversed.
2373
2424
  *
2374
2425
  * @param alias - The edge alias to filter on (must be the current edge alias)
2375
2426
  * @param predicateFunction - A function that builds predicates using the edge accessor
2376
2427
  */
2377
- whereEdge(alias: EA, predicateFunction: (edge: EdgeAccessor<EdgeTypeForKey<G, EK>>) => Predicate): TraversalBuilder<G, Aliases, EdgeAliases, EK, EA, Dir, Optional, DC, PC, RecAliases>;
2428
+ whereEdge(alias: EA, predicateFunction: (edge: EdgeAccessor<EdgeTypeForKey<G, EK>>) => Predicate): TraversalBuilder<G, Aliases, EdgeAliases, EK, EA, Dir, Optional, DC, PC, RecAliases, CoordinateState>;
2378
2429
  /**
2379
2430
  * Specifies the target node kind.
2380
2431
  *
@@ -2387,23 +2438,24 @@ declare class TraversalBuilder<G extends GraphDef, Aliases extends AliasMap, Edg
2387
2438
  */
2388
2439
  to<K extends ValidEdgeTargets<G, EK, Dir>, A extends string>(kind: K, alias: UniqueAlias<A, Aliases>, options?: {
2389
2440
  includeSubClasses?: false;
2390
- }): QueryBuilder<G, Aliases & Record<A, NodeAlias<G["nodes"][K]["type"], Optional>>, EdgeAliases & Record<EA, EdgeAlias<G["edges"][EK]["type"], Optional>>, RecAliases & BuildRecursiveAliases<DC, PC, A>>;
2441
+ }): QueryBuilder<G, Aliases & Record<A, NodeAlias<G["nodes"][K]["type"], Optional>>, EdgeAliases & Record<EA, EdgeAlias<G["edges"][EK]["type"], Optional>>, RecAliases & BuildRecursiveAliases<DC, PC, A>, CoordinateState>;
2391
2442
  to<K extends ValidEdgeTargets<G, EK, Dir>, A extends string>(kind: K, alias: UniqueAlias<A, Aliases>, options: {
2392
2443
  includeSubClasses: true;
2393
- }): QueryBuilder<G, Aliases & Record<A, NodeAlias<NodeType, Optional>>, EdgeAliases & Record<EA, EdgeAlias<G["edges"][EK]["type"], Optional>>, RecAliases & BuildRecursiveAliases<DC, PC, A>>;
2444
+ }): QueryBuilder<G, Aliases & Record<A, NodeAlias<NodeType, Optional>>, EdgeAliases & Record<EA, EdgeAlias<G["edges"][EK]["type"], Optional>>, RecAliases & BuildRecursiveAliases<DC, PC, A>, CoordinateState>;
2394
2445
  /**
2395
2446
  * String-keyed sibling of `to` for runtime-declared target kinds.
2396
2447
  * Throws `KindNotFoundError` if the kind is not registered.
2397
2448
  */
2398
2449
  toDynamic<A extends string>(kind: string, alias: UniqueAlias<A, Aliases>, options?: {
2399
2450
  includeSubClasses?: boolean;
2400
- }): QueryBuilder<G, Aliases & Record<A, NodeAlias<DynamicNodeType, Optional>>, EdgeAliases & Record<EA, EdgeAlias<EdgeTypeForKey<G, EK>, Optional>>, RecAliases & BuildRecursiveAliases<DC, PC, A>>;
2451
+ }): QueryBuilder<G, Aliases & Record<A, NodeAlias<DynamicNodeType, Optional>>, EdgeAliases & Record<EA, EdgeAlias<EdgeTypeForKey<G, EK>, Optional>>, RecAliases & BuildRecursiveAliases<DC, PC, A>, CoordinateState>;
2401
2452
  }
2402
2453
 
2403
2454
  /**
2404
2455
  * QueryBuilder - The fluent query builder.
2405
2456
  */
2406
2457
 
2458
+ type TemporalMethod<G extends GraphDef, Aliases extends AliasMap, EdgeAliases extends EdgeAliasMap, RecursiveAliases extends RecursiveAliasMap, CoordinateState extends QueryCoordinateState> = CoordinateState extends "open" ? (mode: TemporalMode, asOf?: string) => QueryBuilder<G, Aliases, EdgeAliases, RecursiveAliases, "open"> : never;
2407
2459
  /**
2408
2460
  * The fluent query builder.
2409
2461
  *
@@ -2412,8 +2464,9 @@ declare class TraversalBuilder<G extends GraphDef, Aliases extends AliasMap, Edg
2412
2464
  * - Aliases: Map of alias names to their node kinds
2413
2465
  * - EdgeAliases: Map of alias names to their edge kinds (accumulated during traversals)
2414
2466
  */
2415
- declare class QueryBuilder<G extends GraphDef, Aliases extends AliasMap = {}, EdgeAliases extends EdgeAliasMap = {}, RecursiveAliases extends RecursiveAliasMap = {}> {
2467
+ declare class QueryBuilder<G extends GraphDef, Aliases extends AliasMap = EmptyAliasMap, EdgeAliases extends EdgeAliasMap = EmptyEdgeAliasMap, RecursiveAliases extends RecursiveAliasMap = EmptyRecursiveAliasMap, CoordinateState extends QueryCoordinateState = "open"> {
2416
2468
  #private;
2469
+ readonly temporal: TemporalMethod<G, Aliases, EdgeAliases, RecursiveAliases, CoordinateState>;
2417
2470
  constructor(config: QueryBuilderConfig, state: QueryBuilderState);
2418
2471
  /**
2419
2472
  * Starts a query from a node kind.
@@ -2423,10 +2476,10 @@ declare class QueryBuilder<G extends GraphDef, Aliases extends AliasMap = {}, Ed
2423
2476
  */
2424
2477
  from<K extends keyof G["nodes"] & string, A extends string>(kind: K, alias: UniqueAlias<A, Aliases>, options?: {
2425
2478
  includeSubClasses?: false;
2426
- }): QueryBuilder<G, Aliases & Record<A, NodeAlias<G["nodes"][K]["type"]>>, EdgeAliases, RecursiveAliases>;
2479
+ }): QueryBuilder<G, Aliases & Record<A, NodeAlias<G["nodes"][K]["type"]>>, EdgeAliases, RecursiveAliases, CoordinateState>;
2427
2480
  from<K extends keyof G["nodes"] & string, A extends string>(kind: K, alias: UniqueAlias<A, Aliases>, options: {
2428
2481
  includeSubClasses: true;
2429
- }): QueryBuilder<G, Aliases & Record<A, NodeAlias>, EdgeAliases, RecursiveAliases>;
2482
+ }): QueryBuilder<G, Aliases & Record<A, NodeAlias>, EdgeAliases, RecursiveAliases, CoordinateState>;
2430
2483
  /**
2431
2484
  * String-keyed sibling of `from` for runtime-declared kinds. Throws
2432
2485
  * `KindNotFoundError` if the kind is not registered. Predicates use
@@ -2434,18 +2487,18 @@ declare class QueryBuilder<G extends GraphDef, Aliases extends AliasMap = {}, Ed
2434
2487
  */
2435
2488
  fromDynamic<A extends string>(kind: string, alias: UniqueAlias<A, Aliases>, options?: {
2436
2489
  includeSubClasses?: boolean;
2437
- }): QueryBuilder<G, Aliases & Record<A, NodeAlias<DynamicNodeType>>, EdgeAliases, RecursiveAliases>;
2490
+ }): QueryBuilder<G, Aliases & Record<A, NodeAlias<DynamicNodeType>>, EdgeAliases, RecursiveAliases, CoordinateState>;
2438
2491
  /**
2439
2492
  * Adds a WHERE clause for a node.
2440
2493
  */
2441
- whereNode<A extends keyof Aliases & string>(alias: A, predicateFunction: (n: NodeAccessor<Aliases[A]["type"]>) => Predicate): QueryBuilder<G, Aliases, EdgeAliases, RecursiveAliases>;
2494
+ whereNode<A extends keyof Aliases & string>(alias: A, predicateFunction: (n: NodeAccessor<Aliases[A]["type"]>) => Predicate): QueryBuilder<G, Aliases, EdgeAliases, RecursiveAliases, CoordinateState>;
2442
2495
  /**
2443
2496
  * Adds a WHERE clause for an edge.
2444
2497
  *
2445
2498
  * @param alias - The edge alias to filter on
2446
2499
  * @param predicateFunction - A function that builds predicates using the edge accessor
2447
2500
  */
2448
- whereEdge<EA extends keyof EdgeAliases & string>(alias: EA, predicateFunction: (edge: EdgeAccessor<EdgeAliases[EA]["type"]>) => Predicate): QueryBuilder<G, Aliases, EdgeAliases, RecursiveAliases>;
2501
+ whereEdge<EA extends keyof EdgeAliases & string>(alias: EA, predicateFunction: (edge: EdgeAccessor<EdgeAliases[EA]["type"]>) => Predicate): QueryBuilder<G, Aliases, EdgeAliases, RecursiveAliases, CoordinateState>;
2449
2502
  /**
2450
2503
  * Traverses an edge to another node (outgoing direction).
2451
2504
  *
@@ -2459,7 +2512,7 @@ declare class QueryBuilder<G extends GraphDef, Aliases extends AliasMap = {}, Ed
2459
2512
  direction?: "out";
2460
2513
  expand?: TraversalExpansion;
2461
2514
  from?: keyof Aliases & string;
2462
- }): TraversalBuilder<G, Aliases, EdgeAliases, EK, EA, "out", false, false, false, RecursiveAliases>;
2515
+ }): TraversalBuilder<G, Aliases, EdgeAliases, EK, EA, "out", false, false, false, RecursiveAliases, CoordinateState>;
2463
2516
  /**
2464
2517
  * Traverses an edge to another node (incoming direction).
2465
2518
  *
@@ -2474,7 +2527,7 @@ declare class QueryBuilder<G extends GraphDef, Aliases extends AliasMap = {}, Ed
2474
2527
  direction: "in";
2475
2528
  expand?: TraversalExpansion;
2476
2529
  from?: keyof Aliases & string;
2477
- }): TraversalBuilder<G, Aliases, EdgeAliases, EK, EA, "in", false, false, false, RecursiveAliases>;
2530
+ }): TraversalBuilder<G, Aliases, EdgeAliases, EK, EA, "in", false, false, false, RecursiveAliases, CoordinateState>;
2478
2531
  /**
2479
2532
  * String-keyed sibling of `traverse` for runtime-declared edge kinds.
2480
2533
  * Throws `KindNotFoundError` if the edge kind is not registered.
@@ -2483,7 +2536,7 @@ declare class QueryBuilder<G extends GraphDef, Aliases extends AliasMap = {}, Ed
2483
2536
  direction?: TraversalDirection$1;
2484
2537
  expand?: TraversalExpansion;
2485
2538
  from?: keyof Aliases & string;
2486
- }): TraversalBuilder<G, Aliases, EdgeAliases & Record<EA, EdgeAlias<DynamicEdgeType>>, string, EA, TraversalDirection$1, false, false, false, RecursiveAliases>;
2539
+ }): TraversalBuilder<G, Aliases, EdgeAliases & Record<EA, EdgeAlias<DynamicEdgeType>>, string, EA, TraversalDirection$1, false, false, false, RecursiveAliases, CoordinateState>;
2487
2540
  /**
2488
2541
  * Optionally traverses an edge to another node (LEFT JOIN semantics).
2489
2542
  * If no matching edge/node exists, the result will include null values.
@@ -2499,12 +2552,12 @@ declare class QueryBuilder<G extends GraphDef, Aliases extends AliasMap = {}, Ed
2499
2552
  direction?: "out";
2500
2553
  expand?: TraversalExpansion;
2501
2554
  from?: keyof Aliases & string;
2502
- }): TraversalBuilder<G, Aliases, EdgeAliases, EK, EA, "out", true, false, false, RecursiveAliases>;
2555
+ }): TraversalBuilder<G, Aliases, EdgeAliases, EK, EA, "out", true, false, false, RecursiveAliases, CoordinateState>;
2503
2556
  optionalTraverse<EK extends keyof G["edges"] & string, EA extends string>(edgeKind: EK, edgeAlias: EA, options: {
2504
2557
  direction: "in";
2505
2558
  expand?: TraversalExpansion;
2506
2559
  from?: keyof Aliases & string;
2507
- }): TraversalBuilder<G, Aliases, EdgeAliases, EK, EA, "in", true, false, false, RecursiveAliases>;
2560
+ }): TraversalBuilder<G, Aliases, EdgeAliases, EK, EA, "in", true, false, false, RecursiveAliases, CoordinateState>;
2508
2561
  /**
2509
2562
  * String-keyed sibling of `optionalTraverse` for runtime-declared edge
2510
2563
  * kinds. LEFT JOIN semantics — non-matching rows produce a null edge
@@ -2515,7 +2568,7 @@ declare class QueryBuilder<G extends GraphDef, Aliases extends AliasMap = {}, Ed
2515
2568
  direction?: TraversalDirection$1;
2516
2569
  expand?: TraversalExpansion;
2517
2570
  from?: keyof Aliases & string;
2518
- }): TraversalBuilder<G, Aliases, EdgeAliases & Record<EA, EdgeAlias<DynamicEdgeType, true>>, string, EA, TraversalDirection$1, true, false, false, RecursiveAliases>;
2571
+ }): TraversalBuilder<G, Aliases, EdgeAliases & Record<EA, EdgeAlias<DynamicEdgeType, true>>, string, EA, TraversalDirection$1, true, false, false, RecursiveAliases, CoordinateState>;
2519
2572
  /**
2520
2573
  * Selects fields to return.
2521
2574
  */
@@ -2530,23 +2583,15 @@ declare class QueryBuilder<G extends GraphDef, Aliases extends AliasMap = {}, Ed
2530
2583
  /**
2531
2584
  * Orders results.
2532
2585
  */
2533
- orderBy<A extends (keyof Aliases | keyof EdgeAliases) & string>(alias: A, field: string, direction?: SortDirection): QueryBuilder<G, Aliases, EdgeAliases, RecursiveAliases>;
2586
+ orderBy<A extends (keyof Aliases | keyof EdgeAliases) & string>(alias: A, field: string, direction?: SortDirection): QueryBuilder<G, Aliases, EdgeAliases, RecursiveAliases, CoordinateState>;
2534
2587
  /**
2535
2588
  * Limits the number of results.
2536
2589
  */
2537
- limit(n: number): QueryBuilder<G, Aliases, EdgeAliases, RecursiveAliases>;
2590
+ limit(n: number): QueryBuilder<G, Aliases, EdgeAliases, RecursiveAliases, CoordinateState>;
2538
2591
  /**
2539
2592
  * Offsets the results.
2540
2593
  */
2541
- offset(n: number): QueryBuilder<G, Aliases, EdgeAliases, RecursiveAliases>;
2542
- /**
2543
- * Sets temporal mode.
2544
- *
2545
- * @param mode - The temporal mode to use
2546
- * @param asOf - Required timestamp for "asOf" mode (ISO 8601 string)
2547
- * @throws ValidationError if mode is "asOf" but no timestamp is provided
2548
- */
2549
- temporal(mode: TemporalMode, asOf?: string): QueryBuilder<G, Aliases, EdgeAliases, RecursiveAliases>;
2594
+ offset(n: number): QueryBuilder<G, Aliases, EdgeAliases, RecursiveAliases, CoordinateState>;
2550
2595
  /**
2551
2596
  * Groups results by the specified field.
2552
2597
  * Use with aggregate functions like COUNT, SUM, AVG in select().
@@ -2554,21 +2599,21 @@ declare class QueryBuilder<G extends GraphDef, Aliases extends AliasMap = {}, Ed
2554
2599
  * @param alias - The node alias to group by
2555
2600
  * @param field - The field name to group by
2556
2601
  */
2557
- groupBy<A extends keyof Aliases & string>(alias: A, field: string): QueryBuilder<G, Aliases, EdgeAliases, RecursiveAliases>;
2602
+ groupBy<A extends keyof Aliases & string>(alias: A, field: string): QueryBuilder<G, Aliases, EdgeAliases, RecursiveAliases, CoordinateState>;
2558
2603
  /**
2559
2604
  * Groups results by the node ID.
2560
2605
  * Use when you want to group by a complete node rather than a specific field.
2561
2606
  *
2562
2607
  * @param alias - The node alias to group by (uses the node's ID)
2563
2608
  */
2564
- groupByNode<A extends keyof Aliases & string>(alias: A): QueryBuilder<G, Aliases, EdgeAliases, RecursiveAliases>;
2609
+ groupByNode<A extends keyof Aliases & string>(alias: A): QueryBuilder<G, Aliases, EdgeAliases, RecursiveAliases, CoordinateState>;
2565
2610
  /**
2566
2611
  * Filters grouped results using aggregate conditions (HAVING clause).
2567
2612
  * Use after groupBy() to filter based on aggregate values.
2568
2613
  *
2569
2614
  * @param predicate - A predicate expression to filter groups
2570
2615
  */
2571
- having(predicate: PredicateExpression): QueryBuilder<G, Aliases, EdgeAliases, RecursiveAliases>;
2616
+ having(predicate: PredicateExpression): QueryBuilder<G, Aliases, EdgeAliases, RecursiveAliases, CoordinateState>;
2572
2617
  /**
2573
2618
  * Sets fusion parameters for hybrid (vector + fulltext) queries.
2574
2619
  *
@@ -2592,7 +2637,7 @@ declare class QueryBuilder<G extends GraphDef, Aliases extends AliasMap = {}, Ed
2592
2637
  * .execute();
2593
2638
  * ```
2594
2639
  */
2595
- fuseWith(options: HybridFusionOptions): QueryBuilder<G, Aliases, EdgeAliases, RecursiveAliases>;
2640
+ fuseWith(options: HybridFusionOptions): QueryBuilder<G, Aliases, EdgeAliases, RecursiveAliases, CoordinateState>;
2596
2641
  /**
2597
2642
  * Applies a query fragment to transform this builder.
2598
2643
  *
@@ -2618,9 +2663,22 @@ declare class QueryBuilder<G extends GraphDef, Aliases extends AliasMap = {}, Ed
2618
2663
  * @param fragment - A function that transforms the builder
2619
2664
  * @returns The transformed builder
2620
2665
  */
2621
- pipe<OutAliases extends AliasMap, OutEdgeAliases extends EdgeAliasMap = EdgeAliases, OutRecAliases extends RecursiveAliasMap = RecursiveAliases>(fragment: (builder: QueryBuilder<G, Aliases, EdgeAliases, RecursiveAliases>) => QueryBuilder<G, OutAliases, OutEdgeAliases, OutRecAliases>): QueryBuilder<G, OutAliases, OutEdgeAliases, OutRecAliases>;
2666
+ pipe<OutAliases extends AliasMap, OutEdgeAliases extends EdgeAliasMap = EdgeAliases, OutRecAliases extends RecursiveAliasMap = RecursiveAliases>(fragment: (builder: QueryBuilder<G, Aliases, EdgeAliases, RecursiveAliases, CoordinateState>) => QueryBuilder<G, OutAliases, OutEdgeAliases, OutRecAliases, CoordinateState>): QueryBuilder<G, OutAliases, OutEdgeAliases, OutRecAliases, CoordinateState>;
2622
2667
  }
2623
2668
 
2669
+ /**
2670
+ * Fluent query builder for TypeGraph.
2671
+ *
2672
+ * Provides a type-safe, chainable API for building queries.
2673
+ * Each method returns a new builder instance with expanded type information.
2674
+ *
2675
+ * This module re-exports from the builder submodules and provides the
2676
+ * createQueryBuilder factory function.
2677
+ */
2678
+
2679
+ type InitialQueryBuilder<G extends GraphDef, CoordinateState extends QueryCoordinateState = "open"> = QueryBuilder<G, EmptyAliasMap, EmptyEdgeAliasMap, EmptyRecursiveAliasMap, CoordinateState>;
2680
+ declare function createQueryBuilder<G extends GraphDef>(graphId: string, registry: KindRegistry, options?: CreateQueryBuilderOptions): InitialQueryBuilder<G>;
2681
+
2624
2682
  /**
2625
2683
  * Shared types for Tier 1 graph algorithms.
2626
2684
  *
@@ -2652,18 +2710,22 @@ type AlgorithmCyclePolicy = RecursiveCyclePolicy;
2652
2710
  *
2653
2711
  * Algorithms honor the same temporal model as the rest of the store: both
2654
2712
  * nodes and edges are filtered according to the resolved mode. `asOf` is
2655
- * only consulted when the resolved mode is `"asOf"`. If neither option is
2656
- * supplied, the algorithm falls back to `graph.defaults.temporalMode`.
2713
+ * required when the resolved mode is `"asOf"` and rejected for every other
2714
+ * mode. If neither option is supplied, the algorithm falls back to
2715
+ * `graph.defaults.temporalMode`.
2657
2716
  */
2658
- type TemporalAlgorithmOptions = Readonly<{
2717
+ type TemporalAlgorithmOptions = NoRecordedCoordinate & Readonly<{
2659
2718
  /** Temporal mode. Defaults to the graph's configured default. */
2660
2719
  temporalMode?: TemporalMode;
2661
2720
  /**
2662
- * ISO-8601 timestamp used when `temporalMode` is `"asOf"`. Required in that
2663
- * mode; ignored in all others.
2721
+ * ISO-8601 timestamp pinning the read. Required when `temporalMode` is
2722
+ * `"asOf"`; rejected (throws `ValidationError`) for every other mode.
2664
2723
  */
2665
2724
  asOf?: string;
2666
2725
  }>;
2726
+ type InternalTemporalAlgorithmOptions = Omit<TemporalAlgorithmOptions, "recordedAsOf"> & Readonly<{
2727
+ recordedAsOf?: RecordedInstant;
2728
+ }>;
2667
2729
  /**
2668
2730
  * Base options for traversal-style algorithms.
2669
2731
  */
@@ -2680,6 +2742,7 @@ type BaseTraversalOptions<G extends GraphDef> = TemporalAlgorithmOptions & Reado
2680
2742
  /** Cycle policy (default: `"prevent"`). */
2681
2743
  cyclePolicy?: AlgorithmCyclePolicy;
2682
2744
  }>;
2745
+ type InternalBaseTraversalOptions<G extends GraphDef> = InternalTemporalAlgorithmOptions & Omit<BaseTraversalOptions<G>, keyof TemporalAlgorithmOptions>;
2683
2746
  /**
2684
2747
  * A node reached during traversal, annotated with the shortest depth at which
2685
2748
  * it was first discovered.
@@ -2712,6 +2775,7 @@ type ShortestPathResult = Readonly<{
2712
2775
  * care about the first time a target is reached.
2713
2776
  */
2714
2777
  type ShortestPathOptions<G extends GraphDef> = BaseTraversalOptions<G>;
2778
+ type InternalShortestPathOptions<G extends GraphDef> = InternalBaseTraversalOptions<G>;
2715
2779
  /**
2716
2780
  * Options for `reachable`.
2717
2781
  *
@@ -2723,6 +2787,7 @@ type ReachableOptions<G extends GraphDef> = BaseTraversalOptions<G> & Readonly<{
2723
2787
  /** Exclude the source node from the result set (default: `false`). */
2724
2788
  excludeSource?: boolean;
2725
2789
  }>;
2790
+ type InternalReachableOptions<G extends GraphDef> = InternalBaseTraversalOptions<G> & Omit<ReachableOptions<G>, keyof BaseTraversalOptions<G>>;
2726
2791
  /**
2727
2792
  * Options for `neighbors`.
2728
2793
  *
@@ -2740,6 +2805,7 @@ type NeighborsOptions<G extends GraphDef> = TemporalAlgorithmOptions & Readonly<
2740
2805
  /** Cycle policy (default: `"prevent"`). */
2741
2806
  cyclePolicy?: AlgorithmCyclePolicy;
2742
2807
  }>;
2808
+ type InternalNeighborsOptions<G extends GraphDef> = InternalTemporalAlgorithmOptions & Omit<NeighborsOptions<G>, keyof TemporalAlgorithmOptions>;
2743
2809
  /**
2744
2810
  * Options for `degree`.
2745
2811
  *
@@ -2755,6 +2821,7 @@ type DegreeOptions<G extends GraphDef> = TemporalAlgorithmOptions & Readonly<{
2755
2821
  /** Direction (default: `"both"`). */
2756
2822
  direction?: TraversalDirection;
2757
2823
  }>;
2824
+ type InternalDegreeOptions<G extends GraphDef> = InternalTemporalAlgorithmOptions & Omit<DegreeOptions<G>, keyof TemporalAlgorithmOptions>;
2758
2825
 
2759
2826
  /**
2760
2827
  * Raw node id or any object with an `id: string` field. Covers `Node`,
@@ -2812,80 +2879,12 @@ type GraphAlgorithms<G extends GraphDef> = Readonly<{
2812
2879
  */
2813
2880
  degree: (node: NodeIdentifier, options?: DegreeOptions<G>) => Promise<number>;
2814
2881
  }>;
2815
-
2816
- /**
2817
- * `store.introspect()` — unified read of the merged schema.
2818
- *
2819
- * Returns a coherent snapshot of "what does my schema look like right
2820
- * now" suitable for schema-management UIs, codegen, and IDE plugins.
2821
- * The previous surface was fragmented across `registry.hasNodeType`,
2822
- * `store.deprecatedKinds`, and direct graph poking; `introspect()`
2823
- * unifies them with explicit `origin` markers distinguishing
2824
- * compile-time from runtime declarations.
2825
- *
2826
- * Pure read — no I/O. Built from the in-memory `GraphDef` and the
2827
- * persisted-but-already-merged `extension`. `schemaVersion` /
2828
- * `schemaHash` are populated when the loader cached them at
2829
- * construction time and `undefined` otherwise; consumers needing a
2830
- * fresh read should call `backend.getActiveSchema(graphId)` directly.
2831
- */
2832
-
2833
- type SchemaIntrospection = Readonly<{
2834
- graphId: string;
2835
- /** Active schema version on the backend, when known to the caller. */
2836
- schemaVersion: number | undefined;
2837
- /** Hash of the active schema document, when known to the caller. */
2838
- schemaHash: string | undefined;
2839
- kinds: readonly KindIntrospection[];
2840
- edges: readonly EdgeIntrospection[];
2841
- ontology: readonly OntologyIntrospection[];
2842
- deprecatedKinds: ReadonlySet<string>;
2843
- /**
2844
- * The persisted graph extension, or `undefined` when the store has
2845
- * no extensions. Round-trips: passing this value to
2846
- * `defineGraphExtension` and `evolve` against an empty graph yields
2847
- * a graph with the same extension kinds.
2848
- */
2849
- extension: GraphExtension | undefined;
2850
- }>;
2851
- type KindIntrospection = Readonly<{
2852
- name: string;
2853
- origin: "compile-time" | "runtime";
2854
- description: string | undefined;
2855
- annotations: KindAnnotations | undefined;
2856
- deprecated: boolean;
2857
- /**
2858
- * JSON-Schema view of the kind's properties. For extension kinds the
2859
- * lower-level `ExtensionPropertyType` shape (with first-class
2860
- * `searchable` / `embedding` modifiers) is reachable via
2861
- * `introspection.extension.nodes[name].properties`.
2862
- */
2863
- properties: JsonSchema;
2864
- unique: readonly UniqueIntrospection[];
2865
- }>;
2866
- type EdgeIntrospection = Readonly<{
2867
- name: string;
2868
- origin: "compile-time" | "runtime";
2869
- description: string | undefined;
2870
- from: readonly string[];
2871
- to: readonly string[];
2872
- cardinality: Cardinality;
2873
- endpointExistence: EndpointExistence;
2874
- properties: JsonSchema;
2875
- annotations: KindAnnotations | undefined;
2876
- deprecated: boolean;
2877
- }>;
2878
- type OntologyIntrospection = Readonly<{
2879
- metaEdge: string;
2880
- from: string;
2881
- to: string;
2882
- origin: "compile-time" | "runtime";
2883
- }>;
2884
- type UniqueIntrospection = Readonly<{
2885
- name: string;
2886
- fields: readonly string[];
2887
- scope: UniquenessScope;
2888
- collation: Collation;
2882
+ type InternalGraphAlgorithms<G extends GraphDef> = Readonly<{
2883
+ shortestPath: (from: NodeIdentifier, to: NodeIdentifier, options: InternalShortestPathOptions<G>) => Promise<ShortestPathResult | undefined>;
2884
+ reachable: (from: NodeIdentifier, options: InternalReachableOptions<G>) => Promise<readonly ReachableNode[]>;
2885
+ canReach: (from: NodeIdentifier, to: NodeIdentifier, options: InternalBaseTraversalOptions<G>) => Promise<boolean>;
2886
+ neighbors: (node: NodeIdentifier, options: InternalNeighborsOptions<G>) => Promise<readonly ReachableNode[]>;
2887
+ degree: (node: NodeIdentifier, options?: InternalDegreeOptions<G>) => Promise<number>;
2889
2888
  }>;
2890
2889
 
2891
2890
  type RebuildFulltextOptions = Readonly<{
@@ -3175,90 +3174,376 @@ declare class StoreSearch<G extends GraphDef> {
3175
3174
  }
3176
3175
 
3177
3176
  /**
3178
- * Main Store implementation for TypeGraph.
3177
+ * `store.introspect()` — unified read of the merged schema.
3179
3178
  *
3180
- * The Store is the primary interface for interacting with a TypeGraph.
3181
- * It coordinates:
3182
- * - Node and edge CRUD operations
3183
- * - Constraint validation
3184
- * - Schema management
3185
- * - Transaction handling
3179
+ * Returns a coherent snapshot of "what does my schema look like right
3180
+ * now" suitable for schema-management UIs, codegen, and IDE plugins.
3181
+ * The previous surface was fragmented across `registry.hasNodeType`,
3182
+ * `store.deprecatedKinds`, and direct graph poking; `introspect()`
3183
+ * unifies them with explicit `origin` markers distinguishing
3184
+ * compile-time from runtime declarations.
3185
+ *
3186
+ * Pure read — no I/O. Built from the in-memory `GraphDef` and the
3187
+ * persisted-but-already-merged `extension`. `schemaVersion` /
3188
+ * `schemaHash` are populated when the loader cached them at
3189
+ * construction time and `undefined` otherwise; consumers needing a
3190
+ * fresh read should call `backend.getActiveSchema(graphId)` directly.
3186
3191
  */
3187
3192
 
3188
- type StoreSchemaMetadata = Readonly<{
3193
+ type SchemaIntrospection = Readonly<{
3194
+ graphId: string;
3195
+ /** Active schema version on the backend, when known to the caller. */
3189
3196
  schemaVersion: number | undefined;
3197
+ /** Hash of the active schema document, when known to the caller. */
3190
3198
  schemaHash: string | undefined;
3191
- }>;
3192
- /**
3193
- * The Store provides typed access to a TypeGraph database.
3194
- *
3195
- * @example
3196
- * ```typescript
3197
- * const store = createStore(myGraph, backend);
3198
- *
3199
- * // Create nodes using collection API
3200
- * const person = await store.nodes.Person.create({
3201
- * name: "Alice",
3202
- * email: "alice@example.com",
3203
- * });
3204
- *
3205
- * const company = await store.nodes.Company.create({
3206
- * name: "Acme",
3207
- * industry: "Technology",
3208
- * });
3209
- *
3210
- * // Create edges
3211
- * await store.edges.worksAt.create(
3212
- * { kind: "Person", id: person.id },
3213
- * { kind: "Company", id: company.id },
3214
- * { role: "Engineer" }
3215
- * );
3216
- *
3217
- * // Query with the fluent API
3218
- * const results = await store.query()
3219
- * .from("Person", "p")
3220
- * .whereNode("p", (p) => p.name.eq("Alice"))
3221
- * .select((ctx) => ctx.p)
3222
- * .execute();
3223
- * ```
3224
- */
3225
- /**
3226
- * Optional embedder for {@link Store.reembedVectorField}. Receives a batch of
3227
- * the kind's nodes and returns a map of `nodeId → new embedding vector` (omit
3228
- * an id to leave that node without an embedding). Called once per page; the
3229
- * page size is `batchSize`.
3230
- */
3231
- type ReembedFunction = (nodes: readonly Node[]) => Promise<ReadonlyMap<string, readonly number[]>> | ReadonlyMap<string, readonly number[]>;
3232
- /** Options for {@link Store.reembedVectorField}. */
3233
- type ReembedVectorFieldOptions = Readonly<{
3199
+ kinds: readonly KindIntrospection[];
3200
+ edges: readonly EdgeIntrospection[];
3201
+ ontology: readonly OntologyIntrospection[];
3202
+ deprecatedKinds: ReadonlySet<string>;
3234
3203
  /**
3235
- * When supplied, drives a batched re-embed loop after recreating storage:
3236
- * pages the kind's nodes, calls `embed(batch)`, and upserts the returned
3237
- * vectors. When omitted, storage is recreated empty and the caller
3238
- * re-embeds via normal `update()` / `upsertEmbedding` writes.
3204
+ * The persisted graph extension, or `undefined` when the store has
3205
+ * no extensions. Round-trips: passing this value to
3206
+ * `defineGraphExtension` and `evolve` against an empty graph yields
3207
+ * a graph with the same extension kinds.
3239
3208
  */
3240
- embed?: ReembedFunction;
3241
- /** Re-embed page size. Default 200. */
3242
- batchSize?: number;
3243
- }>;
3244
- /** Result of {@link Store.reembedVectorField}. */
3245
- type ReembedVectorFieldResult = Readonly<{
3246
- /** Whether the per-field storage was dropped and recreated. */
3247
- recreated: boolean;
3248
- /** Number of nodes whose embedding was re-written (0 without `embed`). */
3249
- reembedded: number;
3209
+ extension: GraphExtension | undefined;
3250
3210
  }>;
3251
- declare class Store<G extends GraphDef> {
3252
- #private;
3253
- constructor(graph: G, backend: GraphBackend, options?: StoreOptions, schemaMetadata?: StoreSchemaMetadata);
3254
- /** The graph definition */
3255
- get graph(): G;
3211
+ type KindIntrospection = Readonly<{
3212
+ name: string;
3213
+ origin: "compile-time" | "runtime";
3214
+ description: string | undefined;
3215
+ annotations: KindAnnotations | undefined;
3216
+ deprecated: boolean;
3217
+ /**
3218
+ * JSON-Schema view of the kind's properties. For extension kinds the
3219
+ * lower-level `ExtensionPropertyType` shape (with first-class
3220
+ * `searchable` / `embedding` modifiers) is reachable via
3221
+ * `introspection.extension.nodes[name].properties`.
3222
+ */
3223
+ properties: JsonSchema;
3224
+ unique: readonly UniqueIntrospection[];
3225
+ }>;
3226
+ type EdgeIntrospection = Readonly<{
3227
+ name: string;
3228
+ origin: "compile-time" | "runtime";
3229
+ description: string | undefined;
3230
+ from: readonly string[];
3231
+ to: readonly string[];
3232
+ cardinality: Cardinality;
3233
+ endpointExistence: EndpointExistence;
3234
+ properties: JsonSchema;
3235
+ annotations: KindAnnotations | undefined;
3236
+ deprecated: boolean;
3237
+ }>;
3238
+ type OntologyIntrospection = Readonly<{
3239
+ metaEdge: string;
3240
+ from: string;
3241
+ to: string;
3242
+ origin: "compile-time" | "runtime";
3243
+ }>;
3244
+ type UniqueIntrospection = Readonly<{
3245
+ name: string;
3246
+ fields: readonly string[];
3247
+ scope: UniquenessScope;
3248
+ collation: Collation;
3249
+ }>;
3250
+
3251
+ type MaterializeRemovalsOptions = Readonly<{
3252
+ /** Restrict to specific kind names. */
3253
+ kinds?: readonly string[];
3254
+ /** Halt on first failure. Default: false (best-effort). */
3255
+ stopOnError?: boolean;
3256
+ }>;
3257
+ type MaterializeRemovalsEntry = Readonly<{
3258
+ kind: string;
3259
+ entity: KindEntity;
3260
+ status: "removed" | "failed";
3261
+ error?: Error;
3262
+ }>;
3263
+ /**
3264
+ * Outcome of reclaiming one per-`(graphId, kind, field)` vector table that
3265
+ * was orphaned when its embedding field was dropped from a *surviving*
3266
+ * kind's schema. Distinct from {@link MaterializeRemovalsEntry} (whole
3267
+ * kinds) because the unit is a single embedding field, not a kind.
3268
+ */
3269
+ type ReclaimedVectorFieldEntry = Readonly<{
3270
+ kind: string;
3271
+ fieldPath: string;
3272
+ status: "reclaimed" | "failed";
3273
+ error?: Error;
3274
+ }>;
3275
+ type MaterializeRemovalsResult = Readonly<{
3276
+ results: readonly MaterializeRemovalsEntry[];
3277
+ /**
3278
+ * Embedding fields removed from a *surviving* kind whose per-field vector
3279
+ * table this pass dropped (or confirmed already absent). Empty when the
3280
+ * backend has no vector strategy or no embedding field has ever been
3281
+ * dropped. Re-derived from immutable schema history each call, so it lists
3282
+ * the same removed fields on repeat passes — the underlying drop is
3283
+ * idempotent (`DROP ... IF EXISTS`). See {@link reclaimRemovedVectorFieldTables}.
3284
+ */
3285
+ reclaimedVectorFields: readonly ReclaimedVectorFieldEntry[];
3286
+ }>;
3287
+
3288
+ /**
3289
+ * Discriminated union of all Node runtime types in a graph.
3290
+ *
3291
+ * Unlike `AllNodeTypes<G>` which gives the union of *type definitions*,
3292
+ * `AnyNode<G>` gives the union of *runtime node instances*.
3293
+ */
3294
+ type AnyNode<G extends GraphDef> = {
3295
+ [K in NodeKinds<G>]: Node<G["nodes"][K]["type"]>;
3296
+ }[NodeKinds<G>];
3297
+ /**
3298
+ * Discriminated union of all Edge runtime types in a graph.
3299
+ */
3300
+ type AnyEdge<G extends GraphDef> = {
3301
+ [K in EdgeKinds<G>]: Edge<G["edges"][K]["type"]>;
3302
+ }[EdgeKinds<G>];
3303
+ /**
3304
+ * Discriminated union of Node runtime types narrowed to a subset of kinds.
3305
+ */
3306
+ type SubsetNode<G extends GraphDef, K extends NodeKinds<G>> = {
3307
+ [Kind in K]: Node<G["nodes"][Kind]["type"]>;
3308
+ }[K];
3309
+ /**
3310
+ * Discriminated union of Edge runtime types narrowed to a subset of kinds.
3311
+ */
3312
+ type SubsetEdge<G extends GraphDef, K extends EdgeKinds<G>> = {
3313
+ [Kind in K]: Edge<G["edges"][Kind]["type"]>;
3314
+ }[K];
3315
+ type EmptyShape = Readonly<Record<never, never>>;
3316
+ type NodeProjectionPropertyKey<N extends NodeType> = Exclude<keyof Node<N>, "id" | "kind" | "meta"> & string;
3317
+ type EdgeProjectionPropertyKey<E extends AnyEdgeType> = Exclude<keyof Edge<E>, "id" | "kind" | "fromKind" | "fromId" | "toKind" | "toId" | "meta"> & string;
3318
+ type SubgraphNodeProjectionField<N extends NodeType = NodeType> = NodeProjectionPropertyKey<N> | "meta";
3319
+ type SubgraphEdgeProjectionField<E extends AnyEdgeType = AnyEdgeType> = EdgeProjectionPropertyKey<E> | "meta";
3320
+ type SubgraphNodeProjectionMap<G extends GraphDef, NK extends NodeKinds<G> = NodeKinds<G>> = Readonly<{
3321
+ [K in NodeKinds<G>]?: K extends NK ? readonly SubgraphNodeProjectionField<G["nodes"][K]["type"]>[] : never;
3322
+ }>;
3323
+ type SubgraphEdgeProjectionMap<G extends GraphDef, EK extends EdgeKinds<G> = EdgeKinds<G>> = Readonly<{
3324
+ [K in EdgeKinds<G>]?: K extends EK ? readonly SubgraphEdgeProjectionField<G["edges"][K]["type"]>[] : never;
3325
+ }>;
3326
+ type SubgraphProject<G extends GraphDef, NK extends NodeKinds<G> = NodeKinds<G>, EK extends EdgeKinds<G> = EdgeKinds<G>> = Readonly<{
3327
+ /**
3328
+ * Node fields to keep per kind.
3329
+ *
3330
+ * Projected nodes always retain `kind` and `id`.
3331
+ * Use `"meta"` to include the full metadata object; omit it to exclude metadata entirely.
3332
+ * Only kinds present in `includeKinds` (or all node kinds when omitted) are valid keys.
3333
+ */
3334
+ nodes?: SubgraphNodeProjectionMap<G, NK>;
3335
+ /**
3336
+ * Edge fields to keep per kind.
3337
+ *
3338
+ * Projected edges always retain `id`, `kind`, `fromKind`, `fromId`,
3339
+ * `toKind`, and `toId`.
3340
+ * Use `"meta"` to include the full metadata object; omit it to exclude metadata entirely.
3341
+ * Only edge kinds listed in `edges` are valid keys.
3342
+ */
3343
+ edges?: SubgraphEdgeProjectionMap<G, EK>;
3344
+ }>;
3345
+ /**
3346
+ * Identity function that preserves literal types for reusable projection configs.
3347
+ *
3348
+ * Without this helper, storing a projection in a typed variable widens the
3349
+ * field arrays to `string[]`, defeating compile-time narrowing on results.
3350
+ *
3351
+ * @example
3352
+ * ```ts
3353
+ * const project = defineSubgraphProject(graph)({
3354
+ * nodes: { Task: ["title", "meta"] },
3355
+ * edges: { uses_skill: [] },
3356
+ * });
3357
+ * const result = await store.subgraph(rootId, { edges: ["uses_skill"], project });
3358
+ * // result.nodes narrowed correctly — task.status is a type error
3359
+ * ```
3360
+ */
3361
+ declare function defineSubgraphProject<G extends GraphDef>(_graph: G): <const P extends SubgraphProject<G>>(project: P) => P;
3362
+ type HasMeta<Selection extends readonly string[] | undefined> = Selection extends readonly string[] ? "meta" extends Selection[number] ? true : false : false;
3363
+ type SelectedNodeProps<N extends NodeType, Selection extends readonly string[] | undefined> = Selection extends readonly string[] ? Pick<Node<N>, Extract<Selection[number], NodeProjectionPropertyKey<N>>> : EmptyShape;
3364
+ type SelectedEdgeProps<E extends AnyEdgeType, Selection extends readonly string[] | undefined> = Selection extends readonly string[] ? Pick<Edge<E>, Extract<Selection[number], EdgeProjectionPropertyKey<E>>> : EmptyShape;
3365
+ type ProjectedNodeResult<N extends NodeType, Selection extends readonly string[] | undefined> = Readonly<Pick<Node<N>, "id" | "kind">> & Readonly<SelectedNodeProps<N, Selection>> & (HasMeta<Selection> extends true ? Readonly<{
3366
+ meta: NodeMeta;
3367
+ }> : EmptyShape);
3368
+ type ProjectedEdgeResult<E extends AnyEdgeType, Selection extends readonly string[] | undefined> = Readonly<Pick<Edge<E>, "id" | "kind" | "fromKind" | "fromId" | "toKind" | "toId">> & Readonly<SelectedEdgeProps<E, Selection>> & (HasMeta<Selection> extends true ? Readonly<{
3369
+ meta: EdgeMeta;
3370
+ }> : EmptyShape);
3371
+ type ProjectionSelection<P, Key extends "nodes" | "edges", Kind extends string> = P extends Readonly<{
3372
+ [K in Key]?: infer Map;
3373
+ }> ? Map extends Readonly<Record<string, readonly string[] | undefined>> ? Kind extends keyof Map ? Map[Kind] : undefined : undefined : undefined;
3374
+ type SubgraphNodeResultForKind<G extends GraphDef, Kind extends NodeKinds<G>, P> = ProjectionSelection<P, "nodes", Kind> extends readonly string[] ? ProjectedNodeResult<G["nodes"][Kind]["type"], ProjectionSelection<P, "nodes", Kind>> : Node<G["nodes"][Kind]["type"]>;
3375
+ type SubgraphEdgeResultForKind<G extends GraphDef, Kind extends EdgeKinds<G>, P> = ProjectionSelection<P, "edges", Kind> extends readonly string[] ? ProjectedEdgeResult<G["edges"][Kind]["type"], ProjectionSelection<P, "edges", Kind>> : Edge<G["edges"][Kind]["type"]>;
3376
+ type SubgraphOptions<G extends GraphDef, EK extends EdgeKinds<G>, NK extends NodeKinds<G>, P extends SubgraphProject<G, NK, EK> | undefined = undefined> = Readonly<{
3377
+ /** Edge kinds to follow during traversal. Edges not listed are not traversed. */
3378
+ edges: readonly EK[];
3379
+ /** Maximum traversal depth from root (default: 10). */
3380
+ maxDepth?: number;
3381
+ /**
3382
+ * Node kinds to include in the result. Nodes of other kinds are still
3383
+ * traversed through but omitted from the output. When omitted, all
3384
+ * reachable node kinds are included.
3385
+ */
3386
+ includeKinds?: readonly NK[];
3387
+ /** Exclude the root node from the result (default: false). */
3388
+ excludeRoot?: boolean;
3389
+ /**
3390
+ * Edge direction policy (default: "out").
3391
+ * - "out": follow edges in their defined direction only
3392
+ * - "both": follow edges in both directions (undirected traversal)
3393
+ */
3394
+ direction?: "out" | "both";
3395
+ /** Cycle policy — reuse RecursiveCyclePolicy (default: "prevent"). */
3396
+ cyclePolicy?: RecursiveCyclePolicy;
3397
+ /**
3398
+ * Temporal mode applied to both nodes and edges along the traversal and in
3399
+ * the hydrated result. Defaults to `graph.defaults.temporalMode`.
3400
+ */
3401
+ temporalMode?: TemporalMode;
3402
+ /** ISO-8601 timestamp used when `temporalMode === "asOf"`. */
3403
+ asOf?: string;
3404
+ /** @internal Recorded coordinates are supplied by StoreView only. */
3405
+ recordedAsOf?: never;
3406
+ /**
3407
+ * Optional field-level projection per node/edge kind.
3408
+ *
3409
+ * Projected nodes keep `kind` and `id`; projected edges keep their structural
3410
+ * endpoint fields. Kinds omitted from `project` remain fully hydrated.
3411
+ * Projection applies to every returned entity, including the root node.
3412
+ *
3413
+ * Only kinds present in `includeKinds` (nodes) or `edges` (edges) are valid
3414
+ * projection keys. Specifying a kind outside those sets is a compile-time error.
3415
+ */
3416
+ project?: P;
3417
+ }>;
3418
+ /**
3419
+ * Subgraph options as seen by the internal executor: identical to the public
3420
+ * {@link SubgraphOptions} except the recorded/system-time pin is a branded
3421
+ * instant the StoreView seam supplies. The public surface keeps
3422
+ * `recordedAsOf?: never`;
3423
+ * recorded reads reach the executor only through `store.subgraphAtCoordinate`.
3424
+ */
3425
+ type InternalSubgraphOptions<G extends GraphDef, EK extends EdgeKinds<G>, NK extends NodeKinds<G>, P extends SubgraphProject<G, NK, EK> | undefined = undefined> = Omit<SubgraphOptions<G, EK, NK, P>, "recordedAsOf"> & Readonly<{
3426
+ recordedAsOf?: RecordedInstant;
3427
+ }>;
3428
+ /**
3429
+ * Union of all node result types in a subgraph, respecting projection.
3430
+ */
3431
+ type SubgraphNodeResult<G extends GraphDef, NK extends NodeKinds<G> = NodeKinds<G>, P = undefined> = {
3432
+ [Kind in NK]: SubgraphNodeResultForKind<G, Kind, P>;
3433
+ }[NK];
3434
+ /**
3435
+ * Union of all edge result types in a subgraph, respecting projection.
3436
+ */
3437
+ type SubgraphEdgeResult<G extends GraphDef, EK extends EdgeKinds<G> = EdgeKinds<G>, P = undefined> = {
3438
+ [Kind in EK]: SubgraphEdgeResultForKind<G, Kind, P>;
3439
+ }[EK];
3440
+ type SubgraphResult<G extends GraphDef, NK extends NodeKinds<G> = NodeKinds<G>, EK extends EdgeKinds<G> = EdgeKinds<G>, P extends SubgraphProject<G, NK, EK> | undefined = undefined> = Readonly<{
3441
+ /** The root node, or undefined if the root was not found or excluded. */
3442
+ root: SubgraphNodeResult<G, NK, P> | undefined;
3443
+ nodes: ReadonlyMap<string, SubgraphNodeResult<G, NK, P>>;
3444
+ /** Forward adjacency: fromId → edgeKind → edges to targets. */
3445
+ adjacency: ReadonlyMap<string, ReadonlyMap<EK, readonly SubgraphEdgeResult<G, EK, P>[]>>;
3446
+ /** Reverse adjacency: toId → edgeKind → edges from sources. */
3447
+ reverseAdjacency: ReadonlyMap<string, ReadonlyMap<EK, readonly SubgraphEdgeResult<G, EK, P>[]>>;
3448
+ }>;
3449
+
3450
+ /**
3451
+ * Main Store implementation for TypeGraph.
3452
+ *
3453
+ * The Store is the primary interface for interacting with a TypeGraph.
3454
+ * It coordinates:
3455
+ * - Node and edge CRUD operations
3456
+ * - Constraint validation
3457
+ * - Schema management
3458
+ * - Transaction handling
3459
+ */
3460
+
3461
+ type StoreSchemaMetadata = Readonly<{
3462
+ schemaVersion: number | undefined;
3463
+ schemaHash: string | undefined;
3464
+ }>;
3465
+ /**
3466
+ * The Store provides typed access to a TypeGraph database.
3467
+ *
3468
+ * @example
3469
+ * ```typescript
3470
+ * const store = createStore(myGraph, backend);
3471
+ *
3472
+ * // Create nodes using collection API
3473
+ * const person = await store.nodes.Person.create({
3474
+ * name: "Alice",
3475
+ * email: "alice@example.com",
3476
+ * });
3477
+ *
3478
+ * const company = await store.nodes.Company.create({
3479
+ * name: "Acme",
3480
+ * industry: "Technology",
3481
+ * });
3482
+ *
3483
+ * // Create edges
3484
+ * await store.edges.worksAt.create(
3485
+ * { kind: "Person", id: person.id },
3486
+ * { kind: "Company", id: company.id },
3487
+ * { role: "Engineer" }
3488
+ * );
3489
+ *
3490
+ * // Query with the fluent API
3491
+ * const results = await store.query()
3492
+ * .from("Person", "p")
3493
+ * .whereNode("p", (p) => p.name.eq("Alice"))
3494
+ * .select((ctx) => ctx.p)
3495
+ * .execute();
3496
+ * ```
3497
+ */
3498
+ /**
3499
+ * Optional embedder for {@link Store.reembedVectorField}. Receives a batch of
3500
+ * the kind's nodes and returns a map of `nodeId → new embedding vector` (omit
3501
+ * an id to leave that node without an embedding). Called once per page; the
3502
+ * page size is `batchSize`.
3503
+ */
3504
+ type ReembedFunction = (nodes: readonly Node[]) => Promise<ReadonlyMap<string, readonly number[]>> | ReadonlyMap<string, readonly number[]>;
3505
+ /** Options for {@link Store.reembedVectorField}. */
3506
+ type ReembedVectorFieldOptions = Readonly<{
3507
+ /**
3508
+ * When supplied, drives a batched re-embed loop after recreating storage:
3509
+ * pages the kind's nodes, calls `embed(batch)`, and upserts the returned
3510
+ * vectors. When omitted, storage is recreated empty and the caller
3511
+ * re-embeds via normal `update()` / `upsertEmbedding` writes.
3512
+ */
3513
+ embed?: ReembedFunction;
3514
+ /** Re-embed page size. Default 200. */
3515
+ batchSize?: number;
3516
+ }>;
3517
+ /** Result of {@link Store.reembedVectorField}. */
3518
+ type ReembedVectorFieldResult = Readonly<{
3519
+ /** Whether the per-field storage was dropped and recreated. */
3520
+ recreated: boolean;
3521
+ /** Number of nodes whose embedding was re-written (0 without `embed`). */
3522
+ reembedded: number;
3523
+ }>;
3524
+ declare class Store<G extends GraphDef> {
3525
+ #private;
3526
+ constructor(graph: G, backend: GraphBackend, options?: StoreOptions, schemaMetadata?: StoreSchemaMetadata);
3527
+ /** The graph definition */
3528
+ get graph(): G;
3256
3529
  /** The graph ID */
3257
3530
  get graphId(): string;
3258
3531
  /** The kind registry for ontology lookups */
3259
3532
  get registry(): KindRegistry;
3260
3533
  /** The database backend */
3261
3534
  get backend(): GraphBackend;
3535
+ /**
3536
+ * Whether recorded-time capture is enabled for this store.
3537
+ *
3538
+ * @internal
3539
+ */
3540
+ get historyEnabled(): boolean;
3541
+ /**
3542
+ * Whether this store has a recorded read relation bound for reconstruction.
3543
+ *
3544
+ * @internal
3545
+ */
3546
+ get recordedReadBound(): boolean;
3262
3547
  /**
3263
3548
  * Node collections for ergonomic CRUD operations.
3264
3549
  *
@@ -3399,7 +3684,140 @@ declare class Store<G extends GraphDef> {
3399
3684
  * .execute();
3400
3685
  * ```
3401
3686
  */
3402
- query(): QueryBuilder<G>;
3687
+ query(): InitialQueryBuilder<G, "open">;
3688
+ /**
3689
+ * Internal seam for {@link StoreView.query}: a query builder pinned to a
3690
+ * view's {@link ReadCoordinate} with its temporal axis sealed
3691
+ * (`.temporal()` throws). Not part of the stable public API — construct a
3692
+ * view via {@link Store.view} / {@link Store.asOf} and call `.query()`.
3693
+ */
3694
+ sealedQuery(coordinate: ReadCoordinate): InitialQueryBuilder<G, "sealed">;
3695
+ /**
3696
+ * Internal seam for {@link RecordedStoreView}: reconstruct a node point read
3697
+ * from the recorded-time relation while preserving live getById ordering and
3698
+ * duplicate-input behavior.
3699
+ *
3700
+ * @internal
3701
+ */
3702
+ recordedNodeGetById<N extends NodeType>(kind: string, id: NodeId<N>, coordinate: ReadCoordinate): Promise<Node<N> | undefined>;
3703
+ /**
3704
+ * Internal seam for {@link RecordedStoreView}: reconstruct node point reads
3705
+ * from the recorded-time relation while preserving input order.
3706
+ *
3707
+ * @internal
3708
+ */
3709
+ recordedNodeGetByIds<N extends NodeType>(kind: string, ids: readonly NodeId<N>[], coordinate: ReadCoordinate): Promise<readonly (Node<N> | undefined)[]>;
3710
+ /**
3711
+ * Internal seam for {@link RecordedStoreView}: reconstruct an edge point read
3712
+ * from the recorded-time relation while preserving live getById behavior.
3713
+ *
3714
+ * @internal
3715
+ */
3716
+ recordedEdgeGetById<E extends AnyEdgeType>(kind: string, id: EdgeId<E>, coordinate: ReadCoordinate): Promise<Edge<E> | undefined>;
3717
+ /**
3718
+ * Internal seam for {@link RecordedStoreView}: reconstruct edge point reads
3719
+ * from the recorded-time relation while preserving input order.
3720
+ *
3721
+ * @internal
3722
+ */
3723
+ recordedEdgeGetByIds<E extends AnyEdgeType>(kind: string, ids: readonly EdgeId<E>[], coordinate: ReadCoordinate): Promise<readonly (Edge<E> | undefined)[]>;
3724
+ /**
3725
+ * Returns a read-only {@link StoreView} pinned to a valid-time instant.
3726
+ *
3727
+ * The view routes every supported read — `nodes` / `edges` collections,
3728
+ * `query()`, `subgraph()`, and the graph algorithms — through the
3729
+ * `asOf` coordinate, so they observe the graph as it was valid at `T`.
3730
+ * Writes stay on the live `Store`. Mirrors Datomic's `(d/as-of db t)`.
3731
+ *
3732
+ * @example
3733
+ * ```typescript
3734
+ * const past = store.asOf("2026-01-01T00:00:00.000Z");
3735
+ * const alice = await past.nodes.Person.getById(aliceId);
3736
+ * const names = await past
3737
+ * .query()
3738
+ * .from("Person", "p")
3739
+ * .whereNode("p", (p) => p.name.eq("Alice"))
3740
+ * .select((ctx) => ctx.p.name)
3741
+ * .execute();
3742
+ * ```
3743
+ *
3744
+ * @param asOf - ISO-8601 timestamp to pin the valid-time coordinate to.
3745
+ */
3746
+ asOf(asOf: string): StoreView<G>;
3747
+ /**
3748
+ * Returns a narrow read-only view pinned to a recorded/system-time instant.
3749
+ *
3750
+ * Direct `store.asOfRecorded(T)` is diagonal bitemporal sugar: it reads the
3751
+ * recorded-time relation as of `T` and uses the same `T` for the valid-time
3752
+ * axis. Use `store.asOf(validT).asOfRecorded(recordedT)` when the valid and
3753
+ * recorded axes should differ.
3754
+ *
3755
+ * The returned view exposes only reconstructing-safe reads: query,
3756
+ * subgraph, graph algorithms, and collection point reads.
3757
+ *
3758
+ * Prefer `await store.recordedNow()` as the anchor over a wall-clock
3759
+ * timestamp: recorded instants are monotonic and can run briefly ahead of the
3760
+ * wall clock under bursty writes, so a `new Date().toISOString()` passed here
3761
+ * may sort before the most recent commits and silently omit them.
3762
+ */
3763
+ asOfRecorded(recordedAsOf: RecordedInstant): RecordedStoreView<G>;
3764
+ /**
3765
+ * Returns the latest recorded-time instant captured for this graph — the
3766
+ * recorded high-water mark. After guarding the `undefined` case,
3767
+ * `store.asOfRecorded(checkpoint)` reconstructs everything committed so far, a
3768
+ * deterministic anchor that avoids guessing with the wall clock (recorded
3769
+ * instants are monotonic and can run briefly ahead of wall-clock time under
3770
+ * bursty writes). Capture each anchor right after the writes it should cover.
3771
+ *
3772
+ * Returns `undefined` until the first write has been captured, so on a
3773
+ * brand-new graph guard the composition — `asOfRecorded(undefined)` rejects
3774
+ * (an instant is required) rather than reconstructing an empty view. Read the
3775
+ * value first and only pass it to `asOfRecorded` once it is defined.
3776
+ *
3777
+ * **Graph-global, not caller-scoped.** This is the single high-water mark for
3778
+ * the whole graph, advanced by every committed capture from any writer — not
3779
+ * a per-write or per-caller value. An advance between two reads means
3780
+ * "something committed to this graph in between," *not* "the write this caller
3781
+ * just made landed." Do not use a `recordedNow()` advance as a "did my write
3782
+ * succeed?" signal: under any concurrent writer to the same graph it both
3783
+ * misses dropped writes and misfires on no-op writes. Confirm a specific write
3784
+ * by observing the write itself (its return value, or `store.transaction(...)`
3785
+ * success), not the global clock.
3786
+ */
3787
+ recordedNow(): Promise<RecordedInstant | undefined>;
3788
+ /**
3789
+ * Returns a read-only {@link StoreView} pinned to an arbitrary public
3790
+ * temporal mode. Use {@link Store.asOf} for the common valid-time case;
3791
+ * reach for `view` to pin `"current"`, `"includeEnded"`, or
3792
+ * `"includeTombstones"`.
3793
+ *
3794
+ * @example
3795
+ * ```typescript
3796
+ * const withTombstones = store.view({ mode: "includeTombstones" });
3797
+ * const everyEverVersion = await withTombstones.nodes.Person.find();
3798
+ * ```
3799
+ *
3800
+ * @param coordinate - The `(mode, asOf)` coordinate to pin. `asOf` is
3801
+ * required when `mode` is `"asOf"` and rejected for every other mode.
3802
+ */
3803
+ view(coordinate: StoreViewCoordinate): StoreView<G>;
3804
+ /**
3805
+ * Returns a read-only {@link StoreView} pinned to the current instant,
3806
+ * captured once at construction — a stable point-in-time snapshot. Unlike
3807
+ * `store.view({ mode: "current" })` (which tracks "now" live and can read
3808
+ * different surfaces against slightly different clocks), a snapshot pins one
3809
+ * `asOf` timestamp, so every surface observes the same instant. Sugar for
3810
+ * `store.asOf(new Date().toISOString())`; mirrors Datomic's `(d/db conn)`.
3811
+ *
3812
+ * @example
3813
+ * ```typescript
3814
+ * const snap = store.snapshot();
3815
+ * // Every read on `snap` sees the graph as of one fixed instant.
3816
+ * const a = await snap.nodes.Person.find();
3817
+ * const r = await snap.reachable(rootId, { edges: ["knows"] });
3818
+ * ```
3819
+ */
3820
+ snapshot(): StoreView<G>;
3403
3821
  /**
3404
3822
  * Search-related operations (fulltext, hybrid, and rebuild).
3405
3823
  *
@@ -3496,6 +3914,21 @@ declare class Store<G extends GraphDef> {
3496
3914
  * ```
3497
3915
  */
3498
3916
  subgraph<const EK extends EdgeKinds<G>, const NK extends NodeKinds<G> = NodeKinds<G>, const P extends SubgraphProject<G, NK, EK> | undefined = undefined>(rootId: NodeId<AllNodeTypes<G>>, options: SubgraphOptions<G, EK, NK, P>): Promise<SubgraphResult<G, NK, EK, P>>;
3917
+ /**
3918
+ * Internal seam for {@link StoreView} / {@link RecordedStoreView}: runs a
3919
+ * subgraph with a coordinate already flattened into the options (including a
3920
+ * recorded/system-time pin). Trusted caller — the public {@link Store.subgraph}
3921
+ * is the guarded entry point.
3922
+ *
3923
+ * @internal
3924
+ */
3925
+ subgraphAtCoordinate<const EK extends EdgeKinds<G>, const NK extends NodeKinds<G> = NodeKinds<G>, const P extends SubgraphProject<G, NK, EK> | undefined = undefined>(rootId: NodeId<AllNodeTypes<G>>, options: InternalSubgraphOptions<G, EK, NK, P>): Promise<SubgraphResult<G, NK, EK, P>>;
3926
+ /**
3927
+ * Internal seam for StoreView graph algorithms at a pinned coordinate.
3928
+ *
3929
+ * @internal
3930
+ */
3931
+ algorithmsAtCoordinate(coordinate: ReadCoordinate): InternalGraphAlgorithms<G>;
3499
3932
  /**
3500
3933
  * Executes a function within a transaction.
3501
3934
  *
@@ -3508,6 +3941,10 @@ declare class Store<G extends GraphDef> {
3508
3941
  * {@link Store.withTransaction}). See {@link TransactionContext}
3509
3942
  * for per-backend semantics; it is `undefined` only on the
3510
3943
  * non-transactional fallback.
3944
+ * When the store was created with `{ history: true }`, `tx.sql` is
3945
+ * replaced by a fail-loud guard because raw SQL would bypass
3946
+ * recorded-time capture; use the typed collections inside
3947
+ * `transaction()` or {@link Store.withRecordedTransaction}.
3511
3948
  *
3512
3949
  * @example
3513
3950
  * ```typescript
@@ -3546,8 +3983,17 @@ declare class Store<G extends GraphDef> {
3546
3983
  * // sequential, non-atomic — handle partial-failure recovery yourself
3547
3984
  * }
3548
3985
  * ```
3986
+ *
3987
+ * @param fn The callback run inside the transaction boundary.
3988
+ * @param options Optional {@link TransactionOptions} forwarded to the
3989
+ * backend (e.g. `isolationLevel: "serializable"` on Postgres). Backends
3990
+ * without isolation-level support ignore it; the non-transactional
3991
+ * fallback ignores it entirely. Stores created with `{ history: true }`
3992
+ * require read-committed semantics for PostgreSQL recorded-clock capture and
3993
+ * reject stronger snapshot isolation levels.
3549
3994
  */
3550
- transaction<T>(fn: (tx: TransactionContext<G>) => Promise<T>): Promise<T>;
3995
+ transaction<T>(this: HistoryStore<G>, fn: (tx: HistoryTransactionContext<G>) => Promise<T>, options?: TransactionOptions): Promise<T>;
3996
+ transaction<T>(fn: (tx: TransactionContext<G>) => Promise<T>, options?: TransactionOptions): Promise<T>;
3551
3997
  /**
3552
3998
  * Adopts a caller-owned, already-open Drizzle transaction so the graph
3553
3999
  * store and the caller's relational writes commit or roll back as one
@@ -3590,9 +4036,18 @@ declare class Store<G extends GraphDef> {
3590
4036
  * }); // one COMMIT / ROLLBACK across both layers
3591
4037
  * ```
3592
4038
  *
3593
- * @throws {ConfigurationError} when the backend cannot adopt an
3594
- * external transaction — either it is not a Drizzle Postgres/SQLite
3595
- * backend, or `backend.capabilities.transactions` is `false`
4039
+ * Not available when the store was created with `{ history: true }`: a
4040
+ * caller-owned transaction context would let writes happen after capture has
4041
+ * lost its flush point, so this throws `ConfigurationError`
4042
+ * (`RECORDED_CAPTURE_REQUIRES_CALLBACK_TRANSACTION`). Use
4043
+ * {@link Store.withRecordedTransaction} on a history-enabled store, which
4044
+ * adopts the same external transaction but flushes recorded-time capture
4045
+ * before the caller commits.
4046
+ *
4047
+ * @throws {ConfigurationError} when the store has history capture enabled
4048
+ * (use {@link Store.withRecordedTransaction} instead), or when the backend
4049
+ * cannot adopt an external transaction — either it is not a Drizzle
4050
+ * Postgres/SQLite backend, or `backend.capabilities.transactions` is `false`
3596
4051
  * (`drizzle-orm/neon-http`, Cloudflare D1, SQLite
3597
4052
  * `transactionMode: "none"`). A non-atomic fallback is deliberately
3598
4053
  * not offered here: the caller's relational write *would* still
@@ -3604,6 +4059,20 @@ declare class Store<G extends GraphDef> {
3604
4059
  * without emitting any DDL.
3605
4060
  */
3606
4061
  withTransaction(externalTx: AdoptedTransaction): TransactionContext<G>;
4062
+ /**
4063
+ * Adopts a caller-owned transaction while giving recorded-time capture a
4064
+ * flush point before the caller commits. Required when `history: true` is
4065
+ * enabled because returning a long-lived transaction context would let writes
4066
+ * happen after TypeGraph has lost the chance to close/open recorded rows.
4067
+ *
4068
+ * Capture flushes once, when `fn` resolves. The flush seals the capture
4069
+ * session, so a graph write made through the transaction context *after* `fn`
4070
+ * returns (e.g. retaining `tx` and writing once more before the caller's
4071
+ * COMMIT) throws rather than committing uncaptured — the post-flush write
4072
+ * cannot silently diverge history from live state.
4073
+ */
4074
+ withRecordedTransaction<T>(this: HistoryStore<G>, externalTx: AdoptedTransaction, fn: (tx: HistoryTransactionContext<G>) => Promise<T>): Promise<T>;
4075
+ withRecordedTransaction<T>(externalTx: AdoptedTransaction, fn: (tx: TransactionContext<G>) => Promise<T>): Promise<T>;
3607
4076
  /**
3608
4077
  * Hard-deletes all data for this graph from the database.
3609
4078
  *
@@ -3849,6 +4318,29 @@ declare class Store<G extends GraphDef> {
3849
4318
  */
3850
4319
  close(): Promise<void>;
3851
4320
  }
4321
+ type HistorySafeBackend = Omit<GraphBackend, "executeStatement" | "executeDdl"> & Readonly<{
4322
+ executeStatement?: never;
4323
+ executeDdl?: never;
4324
+ }>;
4325
+ type HistorySafeTransactionBackend = Omit<TransactionBackend, "executeStatement" | "executeDdl"> & Readonly<{
4326
+ executeStatement?: never;
4327
+ executeDdl?: never;
4328
+ }>;
4329
+ type HistoryTransactionContext<G extends GraphDef> = Omit<TransactionContext<G>, "backend" | "sql"> & Readonly<{
4330
+ backend: HistorySafeTransactionBackend;
4331
+ sql?: never;
4332
+ }>;
4333
+ type RecordedReadStore<G extends GraphDef> = Store<G> & Readonly<{
4334
+ recordedReadBound: true;
4335
+ }>;
4336
+ type HistoryStore<G extends GraphDef> = Store<G> & Readonly<{
4337
+ backend: HistorySafeBackend;
4338
+ historyEnabled: true;
4339
+ recordedReadBound: true;
4340
+ }>;
4341
+ type ExplicitRecordedReadLiveOptions = LiveStoreOptions & Readonly<{
4342
+ recordedRead: NonNullable<LiveStoreOptions["recordedRead"]>;
4343
+ }>;
3852
4344
  /**
3853
4345
  * Creates a new Store instance.
3854
4346
  *
@@ -3878,6 +4370,8 @@ declare class Store<G extends GraphDef> {
3878
4370
  * });
3879
4371
  * ```
3880
4372
  */
4373
+ declare function createStore<G extends GraphDef>(graph: G, backend: GraphBackend, options: HistoryStoreOptions): HistoryStore<G>;
4374
+ declare function createStore<G extends GraphDef>(graph: G, backend: GraphBackend, options: ExplicitRecordedReadLiveOptions): RecordedReadStore<G>;
3881
4375
  declare function createStore<G extends GraphDef>(graph: G, backend: GraphBackend, options?: StoreOptions): Store<G>;
3882
4376
 
3883
4377
  /**
@@ -3908,6 +4402,8 @@ declare function createStore<G extends GraphDef>(graph: G, backend: GraphBackend
3908
4402
  * }
3909
4403
  * ```
3910
4404
  */
4405
+ declare function createStoreWithSchema<G extends GraphDef>(graph: G, backend: GraphBackend, options: HistoryStoreOptions & SchemaManagerOptions): Promise<[HistoryStore<G>, SchemaValidationResult]>;
4406
+ declare function createStoreWithSchema<G extends GraphDef>(graph: G, backend: GraphBackend, options: ExplicitRecordedReadLiveOptions & SchemaManagerOptions): Promise<[RecordedReadStore<G>, SchemaValidationResult]>;
3911
4407
  declare function createStoreWithSchema<G extends GraphDef>(graph: G, backend: GraphBackend, options?: StoreOptions & SchemaManagerOptions): Promise<[Store<G>, SchemaValidationResult]>;
3912
4408
  /**
3913
4409
  * Creates a Store after **verifying** that the database is at the same
@@ -3950,6 +4446,146 @@ declare function createStoreWithSchema<G extends GraphDef>(graph: G, backend: Gr
3950
4446
  * @throws StoreNotInitializedError if runtime-contribution markers are
3951
4447
  * missing/stale/failed for this graph on this connection.
3952
4448
  */
4449
+ declare function createVerifiedStore<G extends GraphDef>(graph: G, backend: GraphBackend, options: HistoryStoreOptions): Promise<[HistoryStore<G>, SchemaValidationResult]>;
4450
+ declare function createVerifiedStore<G extends GraphDef>(graph: G, backend: GraphBackend, options: ExplicitRecordedReadLiveOptions): Promise<[RecordedReadStore<G>, SchemaValidationResult]>;
3953
4451
  declare function createVerifiedStore<G extends GraphDef>(graph: G, backend: GraphBackend, options?: StoreOptions): Promise<[Store<G>, SchemaValidationResult]>;
3954
4452
 
3955
- export { type HybridVectorOptions as $, type AliasMap as A, type BaseTraversalOptions as B, type CreateQueryBuilderOptions as C, DEFAULT_SEARCHABLE_LANGUAGE as D, type EmbeddingMetric as E, type EdgeGetOrCreateByEndpointsResult as F, type EdgeIntrospection as G, type EmbeddingSchema as H, type EmbeddingValue as I, ExecutableAggregateQuery as J, ExecutableQuery as K, type FieldAccessor as L, type FulltextSearchHit as M, type Node as N, type FulltextSearchOptions as O, type GetOrCreateAction as P, QueryBuilder as Q, type GraphAlgorithms as R, Store as S, TraversalBuilder as T, type UniqueIntrospection as U, type GraphEdgeCollections as V, type GraphNodeCollections as W, type HookContext as X, type HybridFulltextOptions as Y, type HybridSearchHit as Z, type HybridSearchOptions as _, type EmbeddingIndexType as a, createStore as a$, type IfExistsMode as a0, type KindIntrospection as a1, type MaterializeRemovalsEntry as a2, type MaterializeRemovalsOptions as a3, type MaterializeRemovalsResult as a4, type NeighborsOptions as a5, type NodeAccessor as a6, type NodeAlias as a7, type NodeBulkFindByIndexOptions as a8, type NodeCollection as a9, type SearchableSchema as aA, type SelectContext as aB, type SelectableEdge as aC, type SelectableNode as aD, type ShortestPathOptions as aE, type ShortestPathResult as aF, type StoreHooks as aG, type StoreOptions as aH, type StoreProjection as aI, type StoreRef as aJ, StoreSearch as aK, type StreamOptions as aL, type SubgraphEdgeResult as aM, type SubgraphNodeResult as aN, type SubgraphOptions as aO, type SubgraphResult as aP, type SubsetEdge as aQ, type SubsetNode as aR, type TemporalAlgorithmOptions as aS, type TransactionContext as aT, type TraversalDirection as aU, type TypedEdgeCollection as aV, UnionableQuery as aW, type UpdateEdgeInput as aX, type UpdateNodeInput as aY, type VectorSearchHit as aZ, type VectorSearchOptions as a_, type NodeGetOrCreateByConstraintOptions as aa, type NodeGetOrCreateByConstraintResult as ab, type NodeIdentifier as ac, type NodeRef as ad, type OntologyIntrospection as ae, type OperationHookContext as af, type PaginateOptions as ag, type PaginatedResult as ah, type PathNode as ai, type Predicate as aj, PreparedQuery as ak, type PropsAccessor as al, type QueryHookContext as am, type QueryOptions as an, type ReachableNode as ao, type ReachableOptions as ap, type RebuildFulltextOptions as aq, type RebuildFulltextResult as ar, type ReclaimedVectorFieldEntry as as, type RecursiveTraversalOptions as at, type ReembedFunction as au, type ReembedVectorFieldOptions as av, type ReembedVectorFieldResult as aw, type SchemaIntrospection as ax, type SearchableMetadata as ay, type SearchableOptions as az, type EdgeAliasMap as b, createStoreWithSchema as b0, createVerifiedStore as b1, defineSubgraphProject as b2, embedding as b3, exists as b4, fieldRef as b5, getEmbeddingDimensions as b6, getSearchableMetadata as b7, inSubquery as b8, isEmbeddingSchema as b9, isParameterRef as ba, isSearchableSchema as bb, notExists as bc, notInSubquery as bd, param as be, searchable as bf, type AggregateResult as c, type AlgorithmCyclePolicy as d, type AnyEdge as e, type AnyNode as f, type BatchResults as g, type BatchableQuery as h, type ConstraintNames as i, type CreateEdgeInput as j, type CreateNodeInput as k, type DegreeOptions as l, type DynamicEdgeAccessor as m, type DynamicEdgeCollection as n, type DynamicEdgeType as o, type DynamicFieldBuilder as p, type DynamicNodeAccessor as q, type DynamicNodeCollection as r, type DynamicNodeType as s, type DynamicSelectableEdge as t, type DynamicSelectableNode as u, type Edge as v, type EdgeAccessor as w, type EdgeCollection as x, type EdgeFindByEndpointsOptions as y, type EdgeGetOrCreateByEndpointsOptions as z };
4453
+ /**
4454
+ * StoreView — a read-only `(mode, asOf)` lens over a {@link Store}.
4455
+ *
4456
+ * A `StoreView` pins a temporal coordinate and routes every supported
4457
+ * read through it, mirroring Datomic's `(d/as-of db t)` database value
4458
+ * and SQL:2011 `FOR SYSTEM_TIME AS OF`. It is *read-only by
4459
+ * construction*: mutating "the graph as of last Tuesday" is incoherent,
4460
+ * so writes stay on the live `Store`.
4461
+ *
4462
+ * The view is an explicit read context, not a single default flip — the
4463
+ * temporal seam is not uniform across surfaces (the query builder
4464
+ * hardcodes `"current"`, `subgraph` reads `graph.defaults` directly,
4465
+ * collections apply a per-call default). The view therefore injects its
4466
+ * pinned {@link ReadCoordinate} into each surface it hands out through one
4467
+ * helper ({@link withCoordinate}), so a future temporal axis (recorded
4468
+ * time) lands on every surface at once instead of splitting by surface.
4469
+ *
4470
+ * Built on the public `Store` surface (plus one internal sealed-query
4471
+ * seam), so it composes the same reads `branch()` / `merge()` consume.
4472
+ */
4473
+
4474
+ /**
4475
+ * The temporal coordinate a {@link StoreView} pins. A discriminated union on
4476
+ * `mode`: `asOf` is *required* for `"asOf"` and *rejected* (`never`) for every
4477
+ * other mode, so the type mirrors the runtime contract. `view({ mode: "asOf" })`
4478
+ * (missing timestamp) and `view({ mode: "current", asOf })` (pinning an instant
4479
+ * outside `"asOf"`) are both compile errors, not merely runtime
4480
+ * `ValidationError`s.
4481
+ */
4482
+ type StoreViewCoordinate = Readonly<{
4483
+ mode: "asOf";
4484
+ asOf: string;
4485
+ }> | Readonly<{
4486
+ mode: Exclude<TemporalMode, "asOf">;
4487
+ asOf?: never;
4488
+ }>;
4489
+ /**
4490
+ * {@link Store.subgraph} options with the temporal axis removed — the
4491
+ * view's pinned coordinate supplies it.
4492
+ */
4493
+ type StoreViewSubgraphOptions<G extends GraphDef, EK extends EdgeKinds<G>, NK extends NodeKinds<G>, P extends SubgraphProject<G, NK, EK> | undefined = undefined> = Omit<SubgraphOptions<G, EK, NK, P>, "temporalMode" | "asOf" | "recordedAsOf">;
4494
+ /** `reachable` options with the temporal axis removed (the pin supplies it). */
4495
+ type StoreViewReachableOptions<G extends GraphDef> = Omit<ReachableOptions<G>, keyof TemporalAlgorithmOptions>;
4496
+ /** `shortestPath` options with the temporal axis removed (the pin supplies it). */
4497
+ type StoreViewShortestPathOptions<G extends GraphDef> = Omit<ShortestPathOptions<G>, keyof TemporalAlgorithmOptions>;
4498
+ /** `canReach` options with the temporal axis removed (the pin supplies it). */
4499
+ type StoreViewCanReachOptions<G extends GraphDef> = Omit<BaseTraversalOptions<G>, keyof TemporalAlgorithmOptions>;
4500
+ /** `neighbors` options with the temporal axis removed (the pin supplies it). */
4501
+ type StoreViewNeighborsOptions<G extends GraphDef> = Omit<NeighborsOptions<G>, keyof TemporalAlgorithmOptions>;
4502
+ /** `degree` options with the temporal axis removed (the pin supplies it). */
4503
+ type StoreViewDegreeOptions<G extends GraphDef> = Omit<DegreeOptions<G>, keyof TemporalAlgorithmOptions>;
4504
+ /**
4505
+ * Shared base for the read-only views. Holds the pinned {@link ReadCoordinate}
4506
+ * and delegates the graph algorithms, `subgraph`, and `query` to the live store
4507
+ * with that coordinate flattened into each call. {@link StoreView} (valid-time)
4508
+ * and {@link RecordedStoreView} (recorded-time) extend it; only the surfaces
4509
+ * that genuinely differ — collections, search, and the coordinate-changing
4510
+ * helpers — live on the subclasses.
4511
+ */
4512
+ declare abstract class CoordinatePinnedView<G extends GraphDef> {
4513
+ #private;
4514
+ protected readonly store: Store<G>;
4515
+ protected readonly coordinate: ReadCoordinate;
4516
+ constructor(store: Store<G>, coordinate: ReadCoordinate);
4517
+ /** The temporal mode this view reads in. */
4518
+ get mode(): TemporalMode;
4519
+ /** The pinned valid-time `asOf` timestamp, or `undefined` for other modes. */
4520
+ get asOf(): string | undefined;
4521
+ /**
4522
+ * A query builder pinned to this view's coordinate. The temporal axis is
4523
+ * sealed: calling `.temporal(...)` on the returned builder throws, so the
4524
+ * view's coordinate cannot be overridden on a per-query basis.
4525
+ */
4526
+ query(): InitialQueryBuilder<G, "sealed">;
4527
+ protected algorithms(): InternalGraphAlgorithms<G>;
4528
+ /** Extracts a subgraph at this view's pinned coordinate. */
4529
+ subgraph<const EK extends EdgeKinds<G>, const NK extends NodeKinds<G> = NodeKinds<G>, const P extends SubgraphProject<G, NK, EK> | undefined = undefined>(rootId: NodeId<AllNodeTypes<G>>, options: StoreViewSubgraphOptions<G, EK, NK, P>): Promise<SubgraphResult<G, NK, EK, P>>;
4530
+ /** Shortest path between two nodes at this view's pinned coordinate. */
4531
+ shortestPath(from: NodeIdentifier, to: NodeIdentifier, options: StoreViewShortestPathOptions<G>): Promise<ShortestPathResult | undefined>;
4532
+ /** Nodes reachable from `from` at this view's pinned coordinate. */
4533
+ reachable(from: NodeIdentifier, options: StoreViewReachableOptions<G>): Promise<readonly ReachableNode[]>;
4534
+ /** Whether `to` is reachable from `from` at this view's pinned coordinate. */
4535
+ canReach(from: NodeIdentifier, to: NodeIdentifier, options: StoreViewCanReachOptions<G>): Promise<boolean>;
4536
+ /** The k-hop neighborhood of `node` at this view's pinned coordinate. */
4537
+ neighbors(node: NodeIdentifier, options: StoreViewNeighborsOptions<G>): Promise<readonly ReachableNode[]>;
4538
+ /** Counts active edges incident to `node` at this view's pinned coordinate. */
4539
+ degree(node: NodeIdentifier, options?: StoreViewDegreeOptions<G>): Promise<number>;
4540
+ }
4541
+ /**
4542
+ * A read-only `(mode, asOf)` lens over a {@link Store}. Construct one via
4543
+ * {@link Store.asOf} (valid-time) or {@link Store.view} (any public
4544
+ * mode), never directly.
4545
+ *
4546
+ * @example
4547
+ * ```typescript
4548
+ * const past = store.asOf("2026-01-01T00:00:00.000Z");
4549
+ * const alice = await past.nodes.Person.getById(aliceId);
4550
+ * const jobs = await past.edges.worksAt.findFrom(alice!);
4551
+ * const reach = await past.reachable(alice!, { edges: ["knows"] });
4552
+ * ```
4553
+ */
4554
+ declare class StoreView<G extends GraphDef> extends CoordinatePinnedView<G> {
4555
+ #private;
4556
+ constructor(store: Store<G>, coordinate: StoreViewCoordinate | ReadCoordinate);
4557
+ /** Adds a recorded-time pin, returning the narrow reconstructing view. */
4558
+ asOfRecorded(recordedAsOf: RecordedInstant): RecordedStoreView<G>;
4559
+ /** Read-only node collections pinned to this view's coordinate. */
4560
+ get nodes(): StoreViewNodeCollections<G>;
4561
+ /** Read-only edge collections pinned to this view's coordinate. */
4562
+ get edges(): StoreViewEdgeCollections<G>;
4563
+ /**
4564
+ * Read-only search facade. On a `current` view the read methods
4565
+ * (`fulltext` / `vector` / `hybrid`) delegate to the live `store.search`,
4566
+ * while the mutating `rebuildFulltext` is refused — the view is read-only.
4567
+ * On any non-`current` pin every search method refuses: the fulltext /
4568
+ * vector index reflects current state only, so historical relevance is
4569
+ * out of scope.
4570
+ */
4571
+ get search(): StoreSearch<G>;
4572
+ }
4573
+ /**
4574
+ * A narrow recorded-time read lens. It preserves the valid-time coordinate
4575
+ * carried by the source view and adds a recorded/system-time pin. Collection
4576
+ * reads are intentionally limited to point reconstruction; broad collection
4577
+ * predicates, endpoint reads, search, and further coordinate changes are absent
4578
+ * from the typed surface and refused by the runtime proxies for JS callers.
4579
+ */
4580
+ declare class RecordedStoreView<G extends GraphDef> extends CoordinatePinnedView<G> {
4581
+ #private;
4582
+ constructor(store: Store<G>, coordinate: ReadCoordinate);
4583
+ /** The recorded/system-time timestamp this view reconstructs. */
4584
+ get asOfRecorded(): string;
4585
+ /** Recorded-time node point-read collections. */
4586
+ get nodes(): RecordedStoreViewNodeCollections<G>;
4587
+ /** Recorded-time edge point-read collections. */
4588
+ get edges(): RecordedStoreViewEdgeCollections<G>;
4589
+ }
4590
+
4591
+ export { type GraphAlgorithms as $, type AliasMap as A, type BaseTraversalOptions as B, type ConstraintNames as C, DEFAULT_SEARCHABLE_LANGUAGE as D, type EmbeddingMetric as E, type EdgeFindByEndpointsOptions as F, type EdgeGetOrCreateByEndpointsOptions as G, type EdgeGetOrCreateByEndpointsResult as H, type EdgeIntrospection as I, type EdgeTemporalReads as J, type EdgeWrites as K, type EmbeddingSchema as L, type EmbeddingValue as M, type Node as N, type EmptyAliasMap as O, type EmptyEdgeAliasMap as P, type QueryCoordinateState as Q, type RecursiveAliasMap as R, Store as S, TraversalBuilder as T, type UniqueIntrospection as U, ExecutableAggregateQuery as V, ExecutableQuery as W, type FieldAccessor as X, type FulltextSearchHit as Y, type FulltextSearchOptions as Z, type GetOrCreateAction as _, type EmbeddingIndexType as a, type SelectableEdge as a$, type GraphEdgeCollections as a0, type GraphNodeCollections as a1, type HistorySafeBackend as a2, type HistorySafeTransactionBackend as a3, type HistoryStore as a4, type HistoryStoreOptions as a5, type HistoryTransactionContext as a6, type HookContext as a7, type HybridFulltextOptions as a8, type HybridSearchHit as a9, type PathNode as aA, type Predicate as aB, PreparedQuery as aC, type PropsAccessor as aD, type QueryHookContext as aE, type QueryOptions as aF, type ReachableNode as aG, type ReachableOptions as aH, type RebuildFulltextOptions as aI, type RebuildFulltextResult as aJ, type ReclaimedVectorFieldEntry as aK, type RecordedInstant as aL, type RecordedReadStore as aM, RecordedStoreView as aN, type RecordedStoreViewEdgeCollection as aO, type RecordedStoreViewEdgeCollections as aP, type RecordedStoreViewNodeCollection as aQ, type RecordedStoreViewNodeCollections as aR, type RecursiveTraversalOptions as aS, type ReembedFunction as aT, type ReembedVectorFieldOptions as aU, type ReembedVectorFieldResult as aV, type SchemaIntrospection as aW, type SearchableMetadata as aX, type SearchableOptions as aY, type SearchableSchema as aZ, type SelectContext as a_, type HybridSearchOptions as aa, type HybridVectorOptions as ab, type IfExistsMode as ac, type InitialQueryBuilder as ad, type KindIntrospection as ae, type LiveStoreOptions as af, type MaterializeRemovalsEntry as ag, type MaterializeRemovalsOptions as ah, type MaterializeRemovalsResult as ai, type NeighborsOptions as aj, type NoRecordedCoordinate as ak, type NodeAccessor as al, type NodeAlias as am, type NodeBulkFindByIndexOptions as an, type NodeCollection as ao, type NodeCurrentReads as ap, type NodeGetOrCreateByConstraintOptions as aq, type NodeGetOrCreateByConstraintResult as ar, type NodeIdentifier as as, type NodeRef as at, type NodeTemporalReads as au, type NodeWrites as av, type OntologyIntrospection as aw, type OperationHookContext as ax, type PaginateOptions as ay, type PaginatedResult as az, type EdgeAliasMap as b, type SelectableNode as b0, type ShortestPathOptions as b1, type ShortestPathResult as b2, type StoreHooks as b3, type StoreOptions as b4, type StoreProjection as b5, type StoreRef as b6, StoreSearch as b7, StoreView as b8, type StoreViewCanReachOptions as b9, type VectorSearchHit as bA, type VectorSearchOptions as bB, asRecordedInstant as bC, createQueryBuilder as bD, createStore as bE, createStoreWithSchema as bF, createVerifiedStore as bG, defineSubgraphProject as bH, embedding as bI, exists as bJ, fieldRef as bK, getEmbeddingDimensions as bL, getSearchableMetadata as bM, inSubquery as bN, isEmbeddingSchema as bO, isParameterRef as bP, isSearchableSchema as bQ, notExists as bR, notInSubquery as bS, param as bT, searchable as bU, type StoreViewCoordinate as ba, type StoreViewDegreeOptions as bb, type StoreViewEdgeCollection as bc, type StoreViewEdgeCollections as bd, type StoreViewNeighborsOptions as be, type StoreViewNodeCollection as bf, type StoreViewNodeCollections as bg, type StoreViewReachableOptions as bh, type StoreViewShortestPathOptions as bi, type StoreViewSubgraphOptions as bj, type StreamOptions as bk, type SubgraphEdgeResult as bl, type SubgraphNodeResult as bm, type SubgraphOptions as bn, type SubgraphResult as bo, type SubsetEdge as bp, type SubsetNode as bq, type TemporalAlgorithmOptions as br, type TransactionContext as bs, type TraversalDirection as bt, type TypedEdgeCollection as bu, type TypedRecordedStoreViewEdgeCollection as bv, type TypedStoreViewEdgeCollection as bw, UnionableQuery as bx, type UpdateEdgeInput as by, type UpdateNodeInput as bz, QueryBuilder as c, type EmptyRecursiveAliasMap as d, type AggregateResult as e, type AlgorithmCyclePolicy as f, type AnyEdge as g, type AnyNode as h, type BatchResults as i, type BatchableQuery as j, type CreateEdgeInput as k, type CreateNodeInput as l, type DegreeOptions as m, type DynamicEdgeAccessor as n, type DynamicEdgeCollection as o, type DynamicEdgeType as p, type DynamicFieldBuilder as q, type DynamicNodeAccessor as r, type DynamicNodeCollection as s, type DynamicNodeType as t, type DynamicSelectableEdge as u, type DynamicSelectableNode as v, type Edge as w, type EdgeAccessor as x, type EdgeBatchReads as y, type EdgeCollection as z };