@nicia-ai/typegraph 0.32.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 (158) hide show
  1. package/README.md +31 -0
  2. package/dist/backend/postgres/index.cjs +28 -15
  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 +6 -5
  6. package/dist/backend/postgres/pglite.cjs +10 -9
  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 +6 -5
  11. package/dist/backend/postgres/pglite.js.map +1 -1
  12. package/dist/backend/sqlite/index.cjs +27 -14
  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 +6 -5
  16. package/dist/backend/sqlite/libsql.cjs +9 -8
  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 +6 -5
  21. package/dist/backend/sqlite/libsql.js.map +1 -1
  22. package/dist/backend/sqlite/local.cjs +10 -9
  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 +6 -5
  27. package/dist/backend/sqlite/local.js.map +1 -1
  28. package/dist/{chunk-CAMMC3E4.cjs → chunk-3642VBVC.cjs} +65 -63
  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-JKRKIEVA.cjs → chunk-4RBAJVEC.cjs} +125 -3
  35. package/dist/chunk-4RBAJVEC.cjs.map +1 -0
  36. package/dist/{chunk-IJORSAC3.js → chunk-6NRFUHMS.js} +4 -3
  37. package/dist/chunk-6NRFUHMS.js.map +1 -0
  38. package/dist/{chunk-YL4F3CMD.cjs → chunk-BF3ZDEUE.cjs} +96 -64
  39. package/dist/chunk-BF3ZDEUE.cjs.map +1 -0
  40. package/dist/{chunk-2LAT5BIK.cjs → chunk-D3EWZ67S.cjs} +2820 -1947
  41. package/dist/chunk-D3EWZ67S.cjs.map +1 -0
  42. package/dist/{chunk-XQFAJVYW.js → chunk-DJYRRDHA.js} +123 -4
  43. package/dist/chunk-DJYRRDHA.js.map +1 -0
  44. package/dist/{chunk-YQGLVWB2.cjs → chunk-EF3Z645U.cjs} +2 -52
  45. package/dist/chunk-EF3Z645U.cjs.map +1 -0
  46. package/dist/chunk-GYVBEZAO.js +120 -0
  47. package/dist/chunk-GYVBEZAO.js.map +1 -0
  48. package/dist/chunk-I4W7MKVG.cjs +1526 -0
  49. package/dist/chunk-I4W7MKVG.cjs.map +1 -0
  50. package/dist/{chunk-MXE2U3EX.js → chunk-IZ4PCL47.js} +3 -52
  51. package/dist/chunk-IZ4PCL47.js.map +1 -0
  52. package/dist/{chunk-7WW3WL6E.js → chunk-JHOBXD7O.js} +9 -7
  53. package/dist/chunk-JHOBXD7O.js.map +1 -0
  54. package/dist/{chunk-3HQDMOBK.cjs → chunk-KY5SDVA7.cjs} +619 -578
  55. package/dist/chunk-KY5SDVA7.cjs.map +1 -0
  56. package/dist/{chunk-EEYV6UOE.cjs → chunk-MBLXCV2Y.cjs} +2 -2
  57. package/dist/{chunk-EEYV6UOE.cjs.map → chunk-MBLXCV2Y.cjs.map} +1 -1
  58. package/dist/{chunk-LAZGHOZW.cjs → chunk-NG5N7R45.cjs} +28 -28
  59. package/dist/{chunk-LAZGHOZW.cjs.map → chunk-NG5N7R45.cjs.map} +1 -1
  60. package/dist/chunk-OIE2UPVG.cjs +126 -0
  61. package/dist/chunk-OIE2UPVG.cjs.map +1 -0
  62. package/dist/{chunk-NDM5PXEH.js → chunk-OS6KS3HV.js} +41 -9
  63. package/dist/chunk-OS6KS3HV.js.map +1 -0
  64. package/dist/chunk-PYD3UCDU.js +1480 -0
  65. package/dist/chunk-PYD3UCDU.js.map +1 -0
  66. package/dist/{chunk-W4ZX2GCP.js → chunk-QBYTJSAY.js} +2 -2
  67. package/dist/{chunk-W4ZX2GCP.js.map → chunk-QBYTJSAY.js.map} +1 -1
  68. package/dist/{chunk-HFBRAOF7.js → chunk-SPT5JMME.js} +3 -3
  69. package/dist/{chunk-HFBRAOF7.js.map → chunk-SPT5JMME.js.map} +1 -1
  70. package/dist/{chunk-SB65GJNY.cjs → chunk-SST7XDY6.cjs} +11 -11
  71. package/dist/{chunk-SB65GJNY.cjs.map → chunk-SST7XDY6.cjs.map} +1 -1
  72. package/dist/{chunk-TUA3MEJJ.js → chunk-UPDMJEW6.js} +606 -561
  73. package/dist/chunk-UPDMJEW6.js.map +1 -0
  74. package/dist/{chunk-WNORITK6.js → chunk-WLP6TKFB.js} +2691 -1817
  75. package/dist/chunk-WLP6TKFB.js.map +1 -0
  76. package/dist/chunk-XLUNB2TZ.js +53 -0
  77. package/dist/chunk-XLUNB2TZ.js.map +1 -0
  78. package/dist/{chunk-2BVHPOIG.js → chunk-XVUJY72M.js} +6 -6
  79. package/dist/{chunk-2BVHPOIG.js.map → chunk-XVUJY72M.js.map} +1 -1
  80. package/dist/{ddl-C8e8zDAE.d.ts → ddl-CVnHJcar.d.ts} +3 -3
  81. package/dist/{ddl-CwyG4HoQ.d.cts → ddl-Dxt_fBHr.d.cts} +3 -3
  82. package/dist/{extension-types-D1k0inWU.d.cts → extension-types-YGFJPrzK.d.cts} +1 -1
  83. package/dist/{extension-types-D1k0inWU.d.ts → extension-types-YGFJPrzK.d.ts} +1 -1
  84. package/dist/graph-extension/index.d.cts +4 -4
  85. package/dist/graph-extension/index.d.ts +4 -4
  86. package/dist/graph-merge/index.cjs +24 -23
  87. package/dist/graph-merge/index.cjs.map +1 -1
  88. package/dist/graph-merge/index.d.cts +6 -6
  89. package/dist/graph-merge/index.d.ts +6 -6
  90. package/dist/graph-merge/index.js +9 -8
  91. package/dist/graph-merge/index.js.map +1 -1
  92. package/dist/{index-BEK0VtNB.d.ts → index-DGX6D9j1.d.ts} +2 -2
  93. package/dist/{index-C8sSTErx.d.cts → index-SEvUHDA6.d.cts} +2 -2
  94. package/dist/index.cjs +129 -104
  95. package/dist/index.cjs.map +1 -1
  96. package/dist/index.d.cts +25 -55
  97. package/dist/index.d.ts +25 -55
  98. package/dist/index.js +12 -10
  99. package/dist/index.js.map +1 -1
  100. package/dist/indexes/index.cjs +5 -4
  101. package/dist/indexes/index.d.cts +5 -5
  102. package/dist/indexes/index.d.ts +5 -5
  103. package/dist/indexes/index.js +3 -2
  104. package/dist/interchange/index.cjs +15 -15
  105. package/dist/interchange/index.d.cts +5 -5
  106. package/dist/interchange/index.d.ts +5 -5
  107. package/dist/interchange/index.js +2 -2
  108. package/dist/{manager-aVgxbGt-.d.cts → manager-BYl_zyZR.d.cts} +2 -2
  109. package/dist/{manager-8htmuGr-.d.ts → manager-C0_r0ALf.d.ts} +2 -2
  110. package/dist/{materialize-indexes-CAGhqPHQ.d.ts → materialize-indexes-CAkIYFV-.d.ts} +1 -1
  111. package/dist/{materialize-indexes-DEYkU-wr.d.cts → materialize-indexes-D20xNluI.d.cts} +1 -1
  112. package/dist/{postgres-jgXmD45C.d.cts → postgres-MzBPkYzq.d.ts} +2651 -596
  113. package/dist/{postgres-Dhom7iiX.d.ts → postgres-_9psmVGm.d.cts} +2651 -596
  114. package/dist/profiler/index.cjs +4 -3
  115. package/dist/profiler/index.cjs.map +1 -1
  116. package/dist/profiler/index.d.cts +7 -7
  117. package/dist/profiler/index.d.ts +7 -7
  118. package/dist/profiler/index.js +2 -1
  119. package/dist/profiler/index.js.map +1 -1
  120. package/dist/schema/index.cjs +30 -29
  121. package/dist/schema/index.cjs.map +1 -1
  122. package/dist/schema/index.d.cts +7 -7
  123. package/dist/schema/index.d.ts +7 -7
  124. package/dist/schema/index.js +7 -6
  125. package/dist/schema/index.js.map +1 -1
  126. package/dist/{sqlite-BfLsCEqO.d.ts → sqlite-BfksSb45.d.cts} +2726 -455
  127. package/dist/{sqlite-DcQ_BCUW.d.cts → sqlite-gm44dShb.d.ts} +2726 -455
  128. package/dist/{store-view-pBOUrQte.d.ts → store-view-9jQ2rPum.d.cts} +437 -129
  129. package/dist/{store-view-lTcb_cnp.d.cts → store-view-FfE5_7eo.d.ts} +437 -129
  130. package/dist/{types-5RQwzWXx.d.cts → types-B6mhrcLv.d.cts} +2 -2
  131. package/dist/{types-Dk8r09KY.d.ts → types-C_UnQOQp.d.cts} +154 -23
  132. package/dist/{types-DGDiXAYc.d.ts → types-CdWxK-nD.d.ts} +2 -2
  133. package/dist/{types-Dvmn-eal.d.cts → types-DGylBhWo.d.ts} +154 -23
  134. package/dist/{where-Cx_glEEB.d.cts → where-Bpp2ul_z.d.cts} +2 -2
  135. package/dist/{where-CHZFELX0.d.ts → where-BsEXraKW.d.ts} +2 -2
  136. package/package.json +1 -1
  137. package/dist/chunk-2LAT5BIK.cjs.map +0 -1
  138. package/dist/chunk-3HQDMOBK.cjs.map +0 -1
  139. package/dist/chunk-6G35I3VW.cjs +0 -40
  140. package/dist/chunk-6G35I3VW.cjs.map +0 -1
  141. package/dist/chunk-6RMLO5O4.cjs.map +0 -1
  142. package/dist/chunk-7WW3WL6E.js.map +0 -1
  143. package/dist/chunk-CAMMC3E4.cjs.map +0 -1
  144. package/dist/chunk-IJORSAC3.js.map +0 -1
  145. package/dist/chunk-JKRKIEVA.cjs.map +0 -1
  146. package/dist/chunk-M6OC455F.js +0 -65
  147. package/dist/chunk-M6OC455F.js.map +0 -1
  148. package/dist/chunk-MXE2U3EX.js.map +0 -1
  149. package/dist/chunk-NDM5PXEH.js.map +0 -1
  150. package/dist/chunk-RP7YITHX.cjs +0 -70
  151. package/dist/chunk-RP7YITHX.cjs.map +0 -1
  152. package/dist/chunk-SAJSMR2B.js +0 -35
  153. package/dist/chunk-SAJSMR2B.js.map +0 -1
  154. package/dist/chunk-TUA3MEJJ.js.map +0 -1
  155. package/dist/chunk-WNORITK6.js.map +0 -1
  156. package/dist/chunk-XQFAJVYW.js.map +0 -1
  157. package/dist/chunk-YL4F3CMD.cjs.map +0 -1
  158. package/dist/chunk-YQGLVWB2.cjs.map +0 -1
@@ -1,5 +1,5 @@
1
- import { K as KindEntity } from './extension-types-D1k0inWU.cjs';
2
- import { J as JsonPointer } from './types-Dvmn-eal.cjs';
1
+ import { K as KindEntity } from './extension-types-YGFJPrzK.cjs';
2
+ import { J as JsonPointer } from './types-C_UnQOQp.cjs';
3
3
 
4
4
  /**
5
5
  * QueryProfiler types.
@@ -1,5 +1,5 @@
1
1
  import { z } from 'zod';
2
- import { N as NodeType, g as EdgeType, U as UniquenessScope, C as Collation, D as DeleteBehavior, f as KindAnnotations, m as Cardinality, n as EndpointExistence, T as TemporalMode, G as GraphExtension, I as IndexEntity, K as KindEntity, a as NullCheckOp, A as AnyEdgeType } from './extension-types-D1k0inWU.js';
2
+ import { N as NodeType, g as EdgeType, s as UniquenessScope, n as Collation, D as DeleteBehavior, f as KindAnnotations, m as Cardinality, q as EndpointExistence, T as TemporalMode, G as GraphExtension, I as IndexEntity, K as KindEntity, a as NullCheckOp, A as AnyEdgeType } from './extension-types-YGFJPrzK.cjs';
3
3
  import { SQL } from 'drizzle-orm';
4
4
  import { PgDatabase, PgQueryResultHKT } from 'drizzle-orm/pg-core';
5
5
  import { BaseSQLiteDatabase } from 'drizzle-orm/sqlite-core';
@@ -120,25 +120,68 @@ type SqlTableNames = Readonly<{
120
120
  nodes: string;
121
121
  /** Edges table name (default: "typegraph_edges") */
122
122
  edges: string;
123
+ /** Recorded node relation table name (default: "typegraph_recorded_nodes") */
124
+ recordedNodes?: string | undefined;
125
+ /** Recorded edge relation table name (default: "typegraph_recorded_edges") */
126
+ recordedEdges?: string | undefined;
127
+ /** Recorded-time commit clock table name (default: "typegraph_recorded_clock") */
128
+ recordedClock?: string | undefined;
123
129
  /** Node fulltext table name (default: "typegraph_node_fulltext") */
124
130
  fulltext: string;
125
131
  /** Node uniques table name (default: "typegraph_node_uniques") */
126
132
  uniques: string;
127
133
  }>;
128
- /**
129
- * SQL schema configuration for query compilation.
130
- * Contains table identifiers and utility methods for generating SQL references.
131
- */
132
- type SqlSchema = Readonly<{
134
+ type ResolvedSqlTableNames = Readonly<{
135
+ /** Nodes table name */
136
+ nodes: string;
137
+ /** Edges table name */
138
+ edges: string;
139
+ /** Recorded node relation table name */
140
+ recordedNodes: string;
141
+ /** Recorded edge relation table name */
142
+ recordedEdges: string;
143
+ /** Recorded-time commit clock table name */
144
+ recordedClock: string;
145
+ /** Node fulltext table name */
146
+ fulltext: string;
147
+ /** Node uniques table name */
148
+ uniques: string;
149
+ }>;
150
+ type SqlSchemaFields = Readonly<{
133
151
  /** Table names */
134
- tables: SqlTableNames;
152
+ tables: ResolvedSqlTableNames;
135
153
  /** Get a SQL reference to the nodes table */
136
154
  nodesTable: SQL;
137
155
  /** Get a SQL reference to the edges table */
138
156
  edgesTable: SQL;
157
+ /** Get a SQL reference to the recorded node relation */
158
+ recordedNodesTable: SQL;
159
+ /** Get a SQL reference to the recorded edge relation */
160
+ recordedEdgesTable: SQL;
161
+ /** Get a SQL reference to the recorded-time commit clock */
162
+ recordedClockTable: SQL;
139
163
  /** Get a SQL reference to the fulltext table */
140
164
  fulltextTable: SQL;
141
165
  }>;
166
+ /**
167
+ * SQL schema configuration for query compilation.
168
+ * Contains table identifiers and utility methods for generating SQL references.
169
+ *
170
+ * Branded and frozen by {@link createSqlSchema}; callers should not construct
171
+ * schema-shaped objects by hand.
172
+ */
173
+ type SqlSchema = SqlSchemaDescriptor;
174
+ declare class SqlSchemaDescriptor implements SqlSchemaFields {
175
+ #private;
176
+ readonly tables: ResolvedSqlTableNames;
177
+ readonly nodesTable: SQL;
178
+ readonly edgesTable: SQL;
179
+ readonly recordedNodesTable: SQL;
180
+ readonly recordedEdgesTable: SQL;
181
+ readonly recordedClockTable: SQL;
182
+ readonly fulltextTable: SQL;
183
+ constructor(fields: SqlSchemaFields);
184
+ }
142
185
  /**
143
186
  * Creates a SqlSchema configuration from table names.
144
187
  *
@@ -163,6 +206,34 @@ type SqlSchema = Readonly<{
163
206
  * ```
164
207
  */
165
208
  declare function createSqlSchema(names?: Partial<SqlTableNames>): SqlSchema;
209
+ /**
210
+ * The recorded/system-time relation a read coordinate may reconstruct from.
211
+ *
212
+ * TypeGraph's built-in capture relation is bound by `createStore(..., {
213
+ * history: true })`. Hosts can also bind externally populated row-compatible
214
+ * recorded relations through `recordedRelation({ schema })`. Keeping both as
215
+ * explicit values separates the read contract from the write-capture mechanism
216
+ * so future external/TMS-owned recorded relations can feed the same query
217
+ * machinery without changing StoreView or ReadCoordinate.
218
+ */
219
+ declare const EXTERNAL_RECORDED_READ_SOURCE: unique symbol;
220
+ type ExternalRecordedReadSource = Readonly<{
221
+ source: "external";
222
+ schema: SqlSchema;
223
+ [EXTERNAL_RECORDED_READ_SOURCE]: true;
224
+ }>;
225
+ declare const TYPEGRAPH_RECORDED_READ_SOURCE: unique symbol;
226
+ type TypeGraphRecordedReadSource = Readonly<{
227
+ source: "typegraph-capture";
228
+ schema: SqlSchema;
229
+ [TYPEGRAPH_RECORDED_READ_SOURCE]: true;
230
+ }>;
231
+ type RecordedReadSource = ExternalRecordedReadSource | TypeGraphRecordedReadSource;
232
+ type RecordedReadBinding = RecordedReadSource;
233
+ type RecordedRelationOptions = Readonly<{
234
+ schema: SqlSchema;
235
+ }>;
236
+ declare function recordedRelation(options: RecordedRelationOptions): ExternalRecordedReadSource;
166
237
  /**
167
238
  * Default SqlSchema using standard TypeGraph table names.
168
239
  */
@@ -527,6 +598,18 @@ interface VectorStrategy {
527
598
  buildDropIndex?(slot: VectorSlot): SQL | undefined;
528
599
  }
529
600
 
601
+ declare const SqlIntentBrand: unique symbol;
602
+ type SqlIntent = "rows" | "statement";
603
+ type IntentSql<I extends SqlIntent> = SQL & Readonly<{
604
+ [SqlIntentBrand]: I;
605
+ }>;
606
+ type CompiledRowsSql = IntentSql<"rows">;
607
+ type CompiledSelectSql = CompiledRowsSql;
608
+ type CompiledStatementSql = IntentSql<"statement">;
609
+ declare function asCompiledRowsSql(query: SQL): CompiledRowsSql;
610
+ declare function asCompiledSelectSql(query: SQL): CompiledSelectSql;
611
+ declare function asCompiledStatementSql(query: SQL): CompiledStatementSql;
612
+
530
613
  /**
531
614
  * SQL Dialect Abstraction Layer
532
615
  *
@@ -801,6 +884,26 @@ type BackendCapabilities = Readonly<{
801
884
  transactions: boolean;
802
885
  /** Whether the backend supports SQL window functions such as ROW_NUMBER() */
803
886
  windowFunctions: boolean;
887
+ /**
888
+ * Whether the backend's `execute()` supports `UPDATE … RETURNING`. Absent or
889
+ * `true` means supported (every engine TypeGraph ships — SQLite ≥ 3.35,
890
+ * PostgreSQL ≥ 8.2 — supports it). A custom backend whose engine cannot run
891
+ * `RETURNING` must set this to `false` so recorded-time history capture
892
+ * (`history: true`), which relies on `UPDATE … RETURNING` on its hot path,
893
+ * is refused up front instead of failing mid-flush.
894
+ */
895
+ returning?: boolean;
896
+ /**
897
+ * Maximum number of bound parameters the engine accepts in one statement.
898
+ * SQLite defaults to 999 (raisable at compile time via
899
+ * `SQLITE_MAX_VARIABLE_NUMBER`); PostgreSQL's wire protocol caps it at 65535.
900
+ * Recorded-time capture and recorded point reads size their multi-row
901
+ * statements to this ceiling — the same budget the backend's own batched
902
+ * inserts use — instead of a conservative dialect-blind constant. A custom
903
+ * build that raises the SQLite limit can override this here. Absent means the
904
+ * recorded-time fallback budget applies.
905
+ */
906
+ maxBindParameters?: number;
804
907
  /** Vector search capabilities (undefined if not configured) */
805
908
  vector?: VectorCapabilities | undefined;
806
909
  /** Fulltext search capabilities (undefined if not configured) */
@@ -1327,20 +1430,6 @@ type TransactionOptions = Readonly<{
1327
1430
  * relational writes share one Postgres/SQLite transaction (#134).
1328
1431
  */
1329
1432
  type AdoptedTransaction = AnyPgDatabase | AnySqliteDatabase;
1330
- /**
1331
- * Transaction backend — a backend scoped to a transaction.
1332
- *
1333
- * `commitSchemaVersion` and `setActiveVersion` are intentionally omitted:
1334
- * the atomicity / CAS guarantees of those primitives depend on
1335
- * dialect-specific write-locking (BEGIN IMMEDIATE on SQLite,
1336
- * `pg_advisory_xact_lock` on Postgres) acquired by the top-level
1337
- * backend wrappers, not the transaction itself. Calling them from a
1338
- * user-supplied `backend.transaction(...)` callback would bypass that
1339
- * locking and silently weaken the orphan-row crash window the primitive
1340
- * exists to eliminate. Schema commits go through the top-level backend
1341
- * methods only.
1342
- */
1343
- type TransactionBackend = Omit<GraphBackend, "transaction" | "adoptTransaction" | "close" | "refreshStatistics" | "commitSchemaVersion" | "setActiveVersion">;
1344
1433
  /**
1345
1434
  * The GraphBackend interface abstracts database operations.
1346
1435
  *
@@ -1637,7 +1726,14 @@ type GraphBackend = Readonly<{
1637
1726
  * sizes this library is designed for.
1638
1727
  */
1639
1728
  refreshStatistics: () => Promise<void>;
1640
- execute: <T>(query: SQL) => Promise<readonly T[]>;
1729
+ execute: <T>(query: CompiledRowsSql) => Promise<readonly T[]>;
1730
+ /**
1731
+ * Execute a non-row-returning SQL statement bound to this backend or
1732
+ * transaction. Optional because custom backends may only expose the public
1733
+ * row-returning query path; features that need statement execution must
1734
+ * capability-check and fail loudly.
1735
+ */
1736
+ executeStatement?: (query: CompiledStatementSql) => Promise<void>;
1641
1737
  /** Execute pre-compiled SQL text with bound parameters. Available on sync SQLite and pg backends. */
1642
1738
  executeRaw?: <T>(sqlText: string, params: readonly unknown[]) => Promise<readonly T[]>;
1643
1739
  /** Compile a Drizzle SQL object to { sql, params } without executing. */
@@ -1699,6 +1795,39 @@ type GraphBackend = Readonly<{
1699
1795
  adoptTransaction?: (externalTx: AdoptedTransaction) => TransactionBackend;
1700
1796
  close: () => Promise<void>;
1701
1797
  }>;
1798
+ type BackendIdentity = Pick<GraphBackend, "dialect" | "capabilities" | "tableNames" | "fulltextStrategy" | "vectorStrategy">;
1799
+ type NodeEntityReadBackend = Pick<GraphBackend, "getNode" | "getNodes" | "findNodesByKind" | "countNodesByKind">;
1800
+ type NodeEntityWriteBackend = Pick<GraphBackend, "insertNode" | "insertNodeNoReturn" | "insertNodesBatch" | "insertNodesBatchReturning" | "updateNode" | "deleteNode" | "hardDeleteNode">;
1801
+ type EdgeEntityReadBackend = Pick<GraphBackend, "getEdge" | "getEdges" | "countEdgesFrom" | "edgeExistsBetween" | "findEdgesConnectedTo" | "findEdgesByKind" | "countEdgesByKind">;
1802
+ type EdgeEntityWriteBackend = Pick<GraphBackend, "insertEdge" | "insertEdgeNoReturn" | "insertEdgesBatch" | "insertEdgesBatchReturning" | "updateEdge" | "deleteEdge" | "hardDeleteEdge">;
1803
+ type GraphEntityReadBackend = NodeEntityReadBackend & EdgeEntityReadBackend;
1804
+ type GraphEntityWriteBackend = NodeEntityWriteBackend & EdgeEntityWriteBackend;
1805
+ type UniqueConstraintBackend = Pick<GraphBackend, "insertUnique" | "deleteUnique" | "checkUnique" | "checkUniqueBatch">;
1806
+ type SchemaReadBackend = Pick<GraphBackend, "getActiveSchema" | "getSchemaVersion">;
1807
+ type SchemaCommitBackend = Pick<GraphBackend, "commitSchemaVersion" | "setActiveVersion">;
1808
+ type VectorOperationBackend = Pick<GraphBackend, "upsertEmbedding" | "deleteEmbedding" | "vectorSearch" | "createVectorIndex" | "dropVectorIndex">;
1809
+ type FulltextOperationBackend = Pick<GraphBackend, "upsertFulltext" | "deleteFulltext" | "upsertFulltextBatch" | "deleteFulltextBatch" | "fulltextSearch">;
1810
+ type IndexMaterializationBackend = Pick<GraphBackend, "ensureIndexMaterializationsTable" | "getIndexMaterialization" | "getIndexMaterializations" | "recordIndexMaterialization">;
1811
+ type ContributionMaterializationBackend = Pick<GraphBackend, "ensureContributionMaterializationsTable" | "getContributionMaterialization" | "recordContributionMaterialization" | "assertRuntimeContributionsInitialized" | "ensureRuntimeContributions" | "ensureFulltextTable">;
1812
+ type RemovalMaterializationBackend = Pick<GraphBackend, "ensureKindRemovalsTable" | "getPendingKindRemovals" | "getAllKindRemovals" | "recordKindRemoval" | "ensureReconciliationMarkersTable" | "getReconciliationMarker" | "setReconciliationMarker">;
1813
+ type GraphLifecycleBackend = Pick<GraphBackend, "clearGraph" | "bootstrapTables">;
1814
+ type QueryExecutionBackend = Pick<GraphBackend, "execute">;
1815
+ type RawQueryExecutionBackend = Pick<GraphBackend, "executeRaw" | "compileSql">;
1816
+ type RawStatementExecutionBackend = Pick<GraphBackend, "executeStatement" | "executeDdl">;
1817
+ type BackendMaintenance = Pick<GraphBackend, "refreshStatistics">;
1818
+ type BackendTransactions = Pick<GraphBackend, "transaction" | "adoptTransaction">;
1819
+ type BackendLifecycle = Pick<GraphBackend, "close">;
1820
+ /**
1821
+ * Transaction backend — a backend scoped to a transaction.
1822
+ *
1823
+ * This is an explicit facet composition, not `Omit<GraphBackend, ...>`.
1824
+ * New top-level-only backend methods therefore do not silently appear on
1825
+ * transaction-scoped backends. `commitSchemaVersion`, `setActiveVersion`,
1826
+ * `refreshStatistics`, `transaction`, `adoptTransaction`, and `close` stay
1827
+ * deliberately absent: their guarantees depend on the top-level backend or
1828
+ * lifecycle owner rather than an already-open transaction.
1829
+ */
1830
+ type TransactionBackend = Readonly<BackendIdentity & GraphEntityReadBackend & GraphEntityWriteBackend & UniqueConstraintBackend & SchemaReadBackend & VectorOperationBackend & FulltextOperationBackend & IndexMaterializationBackend & ContributionMaterializationBackend & RemovalMaterializationBackend & GraphLifecycleBackend & QueryExecutionBackend & RawQueryExecutionBackend & RawStatementExecutionBackend>;
1702
1831
  /**
1703
1832
  * Parameters for inserting a unique constraint entry.
1704
1833
  */
@@ -2330,6 +2459,8 @@ type QueryAst = Readonly<{
2330
2459
  predicates: readonly NodePredicate[];
2331
2460
  projection: Projection;
2332
2461
  temporalMode: TemporalOptions;
2462
+ /** Recorded/system-time timestamp for recorded-pinned reads. */
2463
+ recordedAsOf?: string;
2333
2464
  orderBy?: readonly OrderSpec[];
2334
2465
  limit?: number;
2335
2466
  offset?: number;
@@ -2618,4 +2749,4 @@ type RelationalIndexDeclaration = NodeIndexDeclaration | EdgeIndexDeclaration;
2618
2749
  type IndexDeclaration = RelationalIndexDeclaration | VectorIndexDeclaration;
2619
2750
  type SystemColumnName = "graph_id" | "kind" | "id" | "from_kind" | "from_id" | "to_kind" | "to_id" | "deleted_at" | "valid_from" | "valid_to" | "created_at" | "updated_at" | "version";
2620
2751
 
2621
- export { type FulltextBatchRow as $, type AnySqliteDatabase as A, type BackendCapabilities as B, type VectorIndexMetric as C, type VectorIndexParams as D, type EdgeIndexConfig as E, type FulltextStrategy as F, type GraphBackend as G, type SchemaVersionRow as H, type IndexDeclaration as I, type JsonPointer as J, type InferenceType as K, type AggregateExpr as L, type MetaEdge as M, type NodeIndexConfig as N, type OntologyRelation as O, type FieldRef as P, type QueryAst as Q, type RelationalIndexDeclaration as R, type SqliteExecutionProfileHints as S, type ComparisonOp as T, type AggregateComparisonPredicate as U, type VectorStrategy as V, type AdoptedTransaction as W, type CommitSchemaVersionExpected as X, type CommitSchemaVersionParams as Y, DEFAULT_SQL_SCHEMA as Z, type DeleteFulltextBatchParams as _, type SqliteTransactionMode as a, type FulltextCapabilities as a0, type FulltextQueryMode as a1, type FulltextSearchParams as a2, type FulltextSearchResult as a3, type HybridFusionOptions as a4, type JsonPointerFor as a5, type JsonPointerInput as a6, type JsonPointerSegment as a7, type JsonPointerSegments as a8, type JsonPointerSegmentsFor as a9, type ValueType as aA, type PredicateExpression as aB, type VectorMetricType as aC, type Traversal as aD, type NodePredicate as aE, type ProjectedField as aF, type GroupBySpec as aG, type RecursiveCyclePolicy as aH, type TraversalDirection as aI, type EdgeRow as aJ, type NodeRow as aK, type VectorSlotMap as aL, type SelectiveField as aM, type ComposableQuery as aN, type SetOperationType as aO, type SetOperation as aP, type VectorMetric as aQ, type TransactionOptions as aR, MAX_JSON_POINTER_DEPTH as aa, type MetaEdgeProperties as ab, type OrderSpec as ac, type ParameterRef as ad, type ResolveJsonPointer as ae, type ResolveJsonPointerSegments as af, type SetActiveVersionParams as ag, type SortDirection as ah, type SqlSchema as ai, type SqlTableNames as aj, type StrategyTableContribution as ak, type TableContribution as al, type TransactionBackend as am, type TraversalExpansion as an, type UpsertFulltextBatchParams as ao, type VectorCapabilities as ap, type VectorSlot as aq, buildVectorCapabilities as ar, createSqlSchema as as, fts5Strategy as at, isMetaEdge as au, joinJsonPointers as av, jsonPointer as aw, normalizeJsonPointer as ax, parseJsonPointer as ay, tsvectorStrategy as az, type AnyPgDatabase as b, type EdgeIndexDeclaration as c, type NodeIndexDeclaration as d, type IndexWhereExpression as e, type SerializedNodeDef as f, type SerializedEdgeDef as g, type SerializedMetaEdge as h, type SerializedOntologyRelation as i, type SerializedClosures as j, type SerializedSchema as k, type SchemaHash as l, type JsonSchema as m, type SerializedOntology as n, type SerializedUniqueConstraint as o, type SqlDialect as p, type EdgeIndexDirection as q, type EdgeIndexWhereBuilder as r, type IndexOrigin as s, type IndexScope as t, type IndexWhereFieldBuilder as u, type IndexWhereInput as v, type NodeIndexWhereBuilder as w, type SystemColumnName as x, type VectorIndexDeclaration as y, type VectorIndexImplementation as z };
2752
+ export { type BackendTransactions as $, type AnySqliteDatabase as A, type BackendCapabilities as B, type VectorIndexMetric as C, type VectorIndexParams as D, type EdgeIndexConfig as E, type FulltextStrategy as F, type GraphBackend as G, type SchemaVersionRow as H, type IndexDeclaration as I, type JsonPointer as J, type InferenceType as K, type AggregateExpr as L, type MetaEdge as M, type NodeIndexConfig as N, type OntologyRelation as O, type FieldRef as P, type QueryAst as Q, type RelationalIndexDeclaration as R, type SqliteExecutionProfileHints as S, type ComparisonOp as T, type AggregateComparisonPredicate as U, type VectorStrategy as V, type TraversalDirection as W, type AdoptedTransaction as X, type BackendIdentity as Y, type BackendLifecycle as Z, type BackendMaintenance as _, type SqliteTransactionMode as a, fts5Strategy as a$, type CommitSchemaVersionExpected as a0, type CommitSchemaVersionParams as a1, type CompiledRowsSql as a2, type CompiledSelectSql as a3, type CompiledStatementSql as a4, type ContributionMaterializationBackend as a5, DEFAULT_SQL_SCHEMA as a6, type DeleteFulltextBatchParams as a7, type EdgeEntityReadBackend as a8, type EdgeEntityWriteBackend as a9, type RawStatementExecutionBackend as aA, type RecordedRelationOptions as aB, type RemovalMaterializationBackend as aC, type ResolveJsonPointer as aD, type ResolveJsonPointerSegments as aE, type ResolvedSqlTableNames as aF, type SchemaCommitBackend as aG, type SchemaReadBackend as aH, type SetActiveVersionParams as aI, type SortDirection as aJ, type SqlIntent as aK, type SqlSchema as aL, type SqlTableNames as aM, type StrategyTableContribution as aN, type TableContribution as aO, type TransactionBackend as aP, type TraversalExpansion as aQ, type UniqueConstraintBackend as aR, type UpsertFulltextBatchParams as aS, type VectorCapabilities as aT, type VectorOperationBackend as aU, type VectorSlot as aV, asCompiledRowsSql as aW, asCompiledSelectSql as aX, asCompiledStatementSql as aY, buildVectorCapabilities as aZ, createSqlSchema as a_, type ExternalRecordedReadSource as aa, type FulltextBatchRow as ab, type FulltextCapabilities as ac, type FulltextOperationBackend as ad, type FulltextQueryMode as ae, type FulltextSearchParams as af, type FulltextSearchResult as ag, type GraphEntityReadBackend as ah, type GraphEntityWriteBackend as ai, type GraphLifecycleBackend as aj, type HybridFusionOptions as ak, type IndexMaterializationBackend as al, type IntentSql as am, type JsonPointerFor as an, type JsonPointerInput as ao, type JsonPointerSegment as ap, type JsonPointerSegments as aq, type JsonPointerSegmentsFor as ar, MAX_JSON_POINTER_DEPTH as as, type MetaEdgeProperties as at, type NodeEntityReadBackend as au, type NodeEntityWriteBackend as av, type OrderSpec as aw, type ParameterRef as ax, type QueryExecutionBackend as ay, type RawQueryExecutionBackend as az, type AnyPgDatabase as b, isMetaEdge as b0, joinJsonPointers as b1, jsonPointer as b2, normalizeJsonPointer as b3, parseJsonPointer as b4, recordedRelation as b5, tsvectorStrategy as b6, type ValueType as b7, type PredicateExpression as b8, type VectorMetricType as b9, type Traversal as ba, type NodePredicate as bb, type ProjectedField as bc, type GroupBySpec as bd, type RecursiveCyclePolicy as be, type EdgeRow as bf, type NodeRow as bg, type VectorSlotMap as bh, type RecordedReadBinding as bi, type SelectiveField as bj, type ComposableQuery as bk, type SetOperationType as bl, type SetOperation as bm, type VectorMetric as bn, type TransactionOptions as bo, type EdgeIndexDeclaration as c, type NodeIndexDeclaration as d, type IndexWhereExpression as e, type SerializedNodeDef as f, type SerializedEdgeDef as g, type SerializedMetaEdge as h, type SerializedOntologyRelation as i, type SerializedClosures as j, type SerializedSchema as k, type SchemaHash as l, type JsonSchema as m, type SerializedOntology as n, type SerializedUniqueConstraint as o, type SqlDialect as p, type EdgeIndexDirection as q, type EdgeIndexWhereBuilder as r, type IndexOrigin as s, type IndexScope as t, type IndexWhereFieldBuilder as u, type IndexWhereInput as v, type NodeIndexWhereBuilder as w, type SystemColumnName as x, type VectorIndexDeclaration as y, type VectorIndexImplementation as z };
@@ -1,5 +1,5 @@
1
- import { K as KindEntity } from './extension-types-D1k0inWU.js';
2
- import { J as JsonPointer } from './types-Dk8r09KY.js';
1
+ import { K as KindEntity } from './extension-types-YGFJPrzK.js';
2
+ import { J as JsonPointer } from './types-DGylBhWo.js';
3
3
 
4
4
  /**
5
5
  * QueryProfiler types.
@@ -1,5 +1,5 @@
1
1
  import { z } from 'zod';
2
- import { N as NodeType, g as EdgeType, U as UniquenessScope, C as Collation, D as DeleteBehavior, f as KindAnnotations, m as Cardinality, n as EndpointExistence, T as TemporalMode, G as GraphExtension, I as IndexEntity, K as KindEntity, a as NullCheckOp, A as AnyEdgeType } from './extension-types-D1k0inWU.cjs';
2
+ import { N as NodeType, g as EdgeType, s as UniquenessScope, n as Collation, D as DeleteBehavior, f as KindAnnotations, m as Cardinality, q as EndpointExistence, T as TemporalMode, G as GraphExtension, I as IndexEntity, K as KindEntity, a as NullCheckOp, A as AnyEdgeType } from './extension-types-YGFJPrzK.js';
3
3
  import { SQL } from 'drizzle-orm';
4
4
  import { PgDatabase, PgQueryResultHKT } from 'drizzle-orm/pg-core';
5
5
  import { BaseSQLiteDatabase } from 'drizzle-orm/sqlite-core';
@@ -120,25 +120,68 @@ type SqlTableNames = Readonly<{
120
120
  nodes: string;
121
121
  /** Edges table name (default: "typegraph_edges") */
122
122
  edges: string;
123
+ /** Recorded node relation table name (default: "typegraph_recorded_nodes") */
124
+ recordedNodes?: string | undefined;
125
+ /** Recorded edge relation table name (default: "typegraph_recorded_edges") */
126
+ recordedEdges?: string | undefined;
127
+ /** Recorded-time commit clock table name (default: "typegraph_recorded_clock") */
128
+ recordedClock?: string | undefined;
123
129
  /** Node fulltext table name (default: "typegraph_node_fulltext") */
124
130
  fulltext: string;
125
131
  /** Node uniques table name (default: "typegraph_node_uniques") */
126
132
  uniques: string;
127
133
  }>;
128
- /**
129
- * SQL schema configuration for query compilation.
130
- * Contains table identifiers and utility methods for generating SQL references.
131
- */
132
- type SqlSchema = Readonly<{
134
+ type ResolvedSqlTableNames = Readonly<{
135
+ /** Nodes table name */
136
+ nodes: string;
137
+ /** Edges table name */
138
+ edges: string;
139
+ /** Recorded node relation table name */
140
+ recordedNodes: string;
141
+ /** Recorded edge relation table name */
142
+ recordedEdges: string;
143
+ /** Recorded-time commit clock table name */
144
+ recordedClock: string;
145
+ /** Node fulltext table name */
146
+ fulltext: string;
147
+ /** Node uniques table name */
148
+ uniques: string;
149
+ }>;
150
+ type SqlSchemaFields = Readonly<{
133
151
  /** Table names */
134
- tables: SqlTableNames;
152
+ tables: ResolvedSqlTableNames;
135
153
  /** Get a SQL reference to the nodes table */
136
154
  nodesTable: SQL;
137
155
  /** Get a SQL reference to the edges table */
138
156
  edgesTable: SQL;
157
+ /** Get a SQL reference to the recorded node relation */
158
+ recordedNodesTable: SQL;
159
+ /** Get a SQL reference to the recorded edge relation */
160
+ recordedEdgesTable: SQL;
161
+ /** Get a SQL reference to the recorded-time commit clock */
162
+ recordedClockTable: SQL;
139
163
  /** Get a SQL reference to the fulltext table */
140
164
  fulltextTable: SQL;
141
165
  }>;
166
+ /**
167
+ * SQL schema configuration for query compilation.
168
+ * Contains table identifiers and utility methods for generating SQL references.
169
+ *
170
+ * Branded and frozen by {@link createSqlSchema}; callers should not construct
171
+ * schema-shaped objects by hand.
172
+ */
173
+ type SqlSchema = SqlSchemaDescriptor;
174
+ declare class SqlSchemaDescriptor implements SqlSchemaFields {
175
+ #private;
176
+ readonly tables: ResolvedSqlTableNames;
177
+ readonly nodesTable: SQL;
178
+ readonly edgesTable: SQL;
179
+ readonly recordedNodesTable: SQL;
180
+ readonly recordedEdgesTable: SQL;
181
+ readonly recordedClockTable: SQL;
182
+ readonly fulltextTable: SQL;
183
+ constructor(fields: SqlSchemaFields);
184
+ }
142
185
  /**
143
186
  * Creates a SqlSchema configuration from table names.
144
187
  *
@@ -163,6 +206,34 @@ type SqlSchema = Readonly<{
163
206
  * ```
164
207
  */
165
208
  declare function createSqlSchema(names?: Partial<SqlTableNames>): SqlSchema;
209
+ /**
210
+ * The recorded/system-time relation a read coordinate may reconstruct from.
211
+ *
212
+ * TypeGraph's built-in capture relation is bound by `createStore(..., {
213
+ * history: true })`. Hosts can also bind externally populated row-compatible
214
+ * recorded relations through `recordedRelation({ schema })`. Keeping both as
215
+ * explicit values separates the read contract from the write-capture mechanism
216
+ * so future external/TMS-owned recorded relations can feed the same query
217
+ * machinery without changing StoreView or ReadCoordinate.
218
+ */
219
+ declare const EXTERNAL_RECORDED_READ_SOURCE: unique symbol;
220
+ type ExternalRecordedReadSource = Readonly<{
221
+ source: "external";
222
+ schema: SqlSchema;
223
+ [EXTERNAL_RECORDED_READ_SOURCE]: true;
224
+ }>;
225
+ declare const TYPEGRAPH_RECORDED_READ_SOURCE: unique symbol;
226
+ type TypeGraphRecordedReadSource = Readonly<{
227
+ source: "typegraph-capture";
228
+ schema: SqlSchema;
229
+ [TYPEGRAPH_RECORDED_READ_SOURCE]: true;
230
+ }>;
231
+ type RecordedReadSource = ExternalRecordedReadSource | TypeGraphRecordedReadSource;
232
+ type RecordedReadBinding = RecordedReadSource;
233
+ type RecordedRelationOptions = Readonly<{
234
+ schema: SqlSchema;
235
+ }>;
236
+ declare function recordedRelation(options: RecordedRelationOptions): ExternalRecordedReadSource;
166
237
  /**
167
238
  * Default SqlSchema using standard TypeGraph table names.
168
239
  */
@@ -527,6 +598,18 @@ interface VectorStrategy {
527
598
  buildDropIndex?(slot: VectorSlot): SQL | undefined;
528
599
  }
529
600
 
601
+ declare const SqlIntentBrand: unique symbol;
602
+ type SqlIntent = "rows" | "statement";
603
+ type IntentSql<I extends SqlIntent> = SQL & Readonly<{
604
+ [SqlIntentBrand]: I;
605
+ }>;
606
+ type CompiledRowsSql = IntentSql<"rows">;
607
+ type CompiledSelectSql = CompiledRowsSql;
608
+ type CompiledStatementSql = IntentSql<"statement">;
609
+ declare function asCompiledRowsSql(query: SQL): CompiledRowsSql;
610
+ declare function asCompiledSelectSql(query: SQL): CompiledSelectSql;
611
+ declare function asCompiledStatementSql(query: SQL): CompiledStatementSql;
612
+
530
613
  /**
531
614
  * SQL Dialect Abstraction Layer
532
615
  *
@@ -801,6 +884,26 @@ type BackendCapabilities = Readonly<{
801
884
  transactions: boolean;
802
885
  /** Whether the backend supports SQL window functions such as ROW_NUMBER() */
803
886
  windowFunctions: boolean;
887
+ /**
888
+ * Whether the backend's `execute()` supports `UPDATE … RETURNING`. Absent or
889
+ * `true` means supported (every engine TypeGraph ships — SQLite ≥ 3.35,
890
+ * PostgreSQL ≥ 8.2 — supports it). A custom backend whose engine cannot run
891
+ * `RETURNING` must set this to `false` so recorded-time history capture
892
+ * (`history: true`), which relies on `UPDATE … RETURNING` on its hot path,
893
+ * is refused up front instead of failing mid-flush.
894
+ */
895
+ returning?: boolean;
896
+ /**
897
+ * Maximum number of bound parameters the engine accepts in one statement.
898
+ * SQLite defaults to 999 (raisable at compile time via
899
+ * `SQLITE_MAX_VARIABLE_NUMBER`); PostgreSQL's wire protocol caps it at 65535.
900
+ * Recorded-time capture and recorded point reads size their multi-row
901
+ * statements to this ceiling — the same budget the backend's own batched
902
+ * inserts use — instead of a conservative dialect-blind constant. A custom
903
+ * build that raises the SQLite limit can override this here. Absent means the
904
+ * recorded-time fallback budget applies.
905
+ */
906
+ maxBindParameters?: number;
804
907
  /** Vector search capabilities (undefined if not configured) */
805
908
  vector?: VectorCapabilities | undefined;
806
909
  /** Fulltext search capabilities (undefined if not configured) */
@@ -1327,20 +1430,6 @@ type TransactionOptions = Readonly<{
1327
1430
  * relational writes share one Postgres/SQLite transaction (#134).
1328
1431
  */
1329
1432
  type AdoptedTransaction = AnyPgDatabase | AnySqliteDatabase;
1330
- /**
1331
- * Transaction backend — a backend scoped to a transaction.
1332
- *
1333
- * `commitSchemaVersion` and `setActiveVersion` are intentionally omitted:
1334
- * the atomicity / CAS guarantees of those primitives depend on
1335
- * dialect-specific write-locking (BEGIN IMMEDIATE on SQLite,
1336
- * `pg_advisory_xact_lock` on Postgres) acquired by the top-level
1337
- * backend wrappers, not the transaction itself. Calling them from a
1338
- * user-supplied `backend.transaction(...)` callback would bypass that
1339
- * locking and silently weaken the orphan-row crash window the primitive
1340
- * exists to eliminate. Schema commits go through the top-level backend
1341
- * methods only.
1342
- */
1343
- type TransactionBackend = Omit<GraphBackend, "transaction" | "adoptTransaction" | "close" | "refreshStatistics" | "commitSchemaVersion" | "setActiveVersion">;
1344
1433
  /**
1345
1434
  * The GraphBackend interface abstracts database operations.
1346
1435
  *
@@ -1637,7 +1726,14 @@ type GraphBackend = Readonly<{
1637
1726
  * sizes this library is designed for.
1638
1727
  */
1639
1728
  refreshStatistics: () => Promise<void>;
1640
- execute: <T>(query: SQL) => Promise<readonly T[]>;
1729
+ execute: <T>(query: CompiledRowsSql) => Promise<readonly T[]>;
1730
+ /**
1731
+ * Execute a non-row-returning SQL statement bound to this backend or
1732
+ * transaction. Optional because custom backends may only expose the public
1733
+ * row-returning query path; features that need statement execution must
1734
+ * capability-check and fail loudly.
1735
+ */
1736
+ executeStatement?: (query: CompiledStatementSql) => Promise<void>;
1641
1737
  /** Execute pre-compiled SQL text with bound parameters. Available on sync SQLite and pg backends. */
1642
1738
  executeRaw?: <T>(sqlText: string, params: readonly unknown[]) => Promise<readonly T[]>;
1643
1739
  /** Compile a Drizzle SQL object to { sql, params } without executing. */
@@ -1699,6 +1795,39 @@ type GraphBackend = Readonly<{
1699
1795
  adoptTransaction?: (externalTx: AdoptedTransaction) => TransactionBackend;
1700
1796
  close: () => Promise<void>;
1701
1797
  }>;
1798
+ type BackendIdentity = Pick<GraphBackend, "dialect" | "capabilities" | "tableNames" | "fulltextStrategy" | "vectorStrategy">;
1799
+ type NodeEntityReadBackend = Pick<GraphBackend, "getNode" | "getNodes" | "findNodesByKind" | "countNodesByKind">;
1800
+ type NodeEntityWriteBackend = Pick<GraphBackend, "insertNode" | "insertNodeNoReturn" | "insertNodesBatch" | "insertNodesBatchReturning" | "updateNode" | "deleteNode" | "hardDeleteNode">;
1801
+ type EdgeEntityReadBackend = Pick<GraphBackend, "getEdge" | "getEdges" | "countEdgesFrom" | "edgeExistsBetween" | "findEdgesConnectedTo" | "findEdgesByKind" | "countEdgesByKind">;
1802
+ type EdgeEntityWriteBackend = Pick<GraphBackend, "insertEdge" | "insertEdgeNoReturn" | "insertEdgesBatch" | "insertEdgesBatchReturning" | "updateEdge" | "deleteEdge" | "hardDeleteEdge">;
1803
+ type GraphEntityReadBackend = NodeEntityReadBackend & EdgeEntityReadBackend;
1804
+ type GraphEntityWriteBackend = NodeEntityWriteBackend & EdgeEntityWriteBackend;
1805
+ type UniqueConstraintBackend = Pick<GraphBackend, "insertUnique" | "deleteUnique" | "checkUnique" | "checkUniqueBatch">;
1806
+ type SchemaReadBackend = Pick<GraphBackend, "getActiveSchema" | "getSchemaVersion">;
1807
+ type SchemaCommitBackend = Pick<GraphBackend, "commitSchemaVersion" | "setActiveVersion">;
1808
+ type VectorOperationBackend = Pick<GraphBackend, "upsertEmbedding" | "deleteEmbedding" | "vectorSearch" | "createVectorIndex" | "dropVectorIndex">;
1809
+ type FulltextOperationBackend = Pick<GraphBackend, "upsertFulltext" | "deleteFulltext" | "upsertFulltextBatch" | "deleteFulltextBatch" | "fulltextSearch">;
1810
+ type IndexMaterializationBackend = Pick<GraphBackend, "ensureIndexMaterializationsTable" | "getIndexMaterialization" | "getIndexMaterializations" | "recordIndexMaterialization">;
1811
+ type ContributionMaterializationBackend = Pick<GraphBackend, "ensureContributionMaterializationsTable" | "getContributionMaterialization" | "recordContributionMaterialization" | "assertRuntimeContributionsInitialized" | "ensureRuntimeContributions" | "ensureFulltextTable">;
1812
+ type RemovalMaterializationBackend = Pick<GraphBackend, "ensureKindRemovalsTable" | "getPendingKindRemovals" | "getAllKindRemovals" | "recordKindRemoval" | "ensureReconciliationMarkersTable" | "getReconciliationMarker" | "setReconciliationMarker">;
1813
+ type GraphLifecycleBackend = Pick<GraphBackend, "clearGraph" | "bootstrapTables">;
1814
+ type QueryExecutionBackend = Pick<GraphBackend, "execute">;
1815
+ type RawQueryExecutionBackend = Pick<GraphBackend, "executeRaw" | "compileSql">;
1816
+ type RawStatementExecutionBackend = Pick<GraphBackend, "executeStatement" | "executeDdl">;
1817
+ type BackendMaintenance = Pick<GraphBackend, "refreshStatistics">;
1818
+ type BackendTransactions = Pick<GraphBackend, "transaction" | "adoptTransaction">;
1819
+ type BackendLifecycle = Pick<GraphBackend, "close">;
1820
+ /**
1821
+ * Transaction backend — a backend scoped to a transaction.
1822
+ *
1823
+ * This is an explicit facet composition, not `Omit<GraphBackend, ...>`.
1824
+ * New top-level-only backend methods therefore do not silently appear on
1825
+ * transaction-scoped backends. `commitSchemaVersion`, `setActiveVersion`,
1826
+ * `refreshStatistics`, `transaction`, `adoptTransaction`, and `close` stay
1827
+ * deliberately absent: their guarantees depend on the top-level backend or
1828
+ * lifecycle owner rather than an already-open transaction.
1829
+ */
1830
+ type TransactionBackend = Readonly<BackendIdentity & GraphEntityReadBackend & GraphEntityWriteBackend & UniqueConstraintBackend & SchemaReadBackend & VectorOperationBackend & FulltextOperationBackend & IndexMaterializationBackend & ContributionMaterializationBackend & RemovalMaterializationBackend & GraphLifecycleBackend & QueryExecutionBackend & RawQueryExecutionBackend & RawStatementExecutionBackend>;
1702
1831
  /**
1703
1832
  * Parameters for inserting a unique constraint entry.
1704
1833
  */
@@ -2330,6 +2459,8 @@ type QueryAst = Readonly<{
2330
2459
  predicates: readonly NodePredicate[];
2331
2460
  projection: Projection;
2332
2461
  temporalMode: TemporalOptions;
2462
+ /** Recorded/system-time timestamp for recorded-pinned reads. */
2463
+ recordedAsOf?: string;
2333
2464
  orderBy?: readonly OrderSpec[];
2334
2465
  limit?: number;
2335
2466
  offset?: number;
@@ -2618,4 +2749,4 @@ type RelationalIndexDeclaration = NodeIndexDeclaration | EdgeIndexDeclaration;
2618
2749
  type IndexDeclaration = RelationalIndexDeclaration | VectorIndexDeclaration;
2619
2750
  type SystemColumnName = "graph_id" | "kind" | "id" | "from_kind" | "from_id" | "to_kind" | "to_id" | "deleted_at" | "valid_from" | "valid_to" | "created_at" | "updated_at" | "version";
2620
2751
 
2621
- export { type FulltextBatchRow as $, type AnySqliteDatabase as A, type BackendCapabilities as B, type VectorIndexMetric as C, type VectorIndexParams as D, type EdgeIndexConfig as E, type FulltextStrategy as F, type GraphBackend as G, type SchemaVersionRow as H, type IndexDeclaration as I, type JsonPointer as J, type InferenceType as K, type AggregateExpr as L, type MetaEdge as M, type NodeIndexConfig as N, type OntologyRelation as O, type FieldRef as P, type QueryAst as Q, type RelationalIndexDeclaration as R, type SqliteExecutionProfileHints as S, type ComparisonOp as T, type AggregateComparisonPredicate as U, type VectorStrategy as V, type AdoptedTransaction as W, type CommitSchemaVersionExpected as X, type CommitSchemaVersionParams as Y, DEFAULT_SQL_SCHEMA as Z, type DeleteFulltextBatchParams as _, type SqliteTransactionMode as a, type FulltextCapabilities as a0, type FulltextQueryMode as a1, type FulltextSearchParams as a2, type FulltextSearchResult as a3, type HybridFusionOptions as a4, type JsonPointerFor as a5, type JsonPointerInput as a6, type JsonPointerSegment as a7, type JsonPointerSegments as a8, type JsonPointerSegmentsFor as a9, type ValueType as aA, type PredicateExpression as aB, type VectorMetricType as aC, type Traversal as aD, type NodePredicate as aE, type ProjectedField as aF, type GroupBySpec as aG, type RecursiveCyclePolicy as aH, type TraversalDirection as aI, type EdgeRow as aJ, type NodeRow as aK, type VectorSlotMap as aL, type SelectiveField as aM, type ComposableQuery as aN, type SetOperationType as aO, type SetOperation as aP, type VectorMetric as aQ, type TransactionOptions as aR, MAX_JSON_POINTER_DEPTH as aa, type MetaEdgeProperties as ab, type OrderSpec as ac, type ParameterRef as ad, type ResolveJsonPointer as ae, type ResolveJsonPointerSegments as af, type SetActiveVersionParams as ag, type SortDirection as ah, type SqlSchema as ai, type SqlTableNames as aj, type StrategyTableContribution as ak, type TableContribution as al, type TransactionBackend as am, type TraversalExpansion as an, type UpsertFulltextBatchParams as ao, type VectorCapabilities as ap, type VectorSlot as aq, buildVectorCapabilities as ar, createSqlSchema as as, fts5Strategy as at, isMetaEdge as au, joinJsonPointers as av, jsonPointer as aw, normalizeJsonPointer as ax, parseJsonPointer as ay, tsvectorStrategy as az, type AnyPgDatabase as b, type EdgeIndexDeclaration as c, type NodeIndexDeclaration as d, type IndexWhereExpression as e, type SerializedNodeDef as f, type SerializedEdgeDef as g, type SerializedMetaEdge as h, type SerializedOntologyRelation as i, type SerializedClosures as j, type SerializedSchema as k, type SchemaHash as l, type JsonSchema as m, type SerializedOntology as n, type SerializedUniqueConstraint as o, type SqlDialect as p, type EdgeIndexDirection as q, type EdgeIndexWhereBuilder as r, type IndexOrigin as s, type IndexScope as t, type IndexWhereFieldBuilder as u, type IndexWhereInput as v, type NodeIndexWhereBuilder as w, type SystemColumnName as x, type VectorIndexDeclaration as y, type VectorIndexImplementation as z };
2752
+ export { type BackendTransactions as $, type AnySqliteDatabase as A, type BackendCapabilities as B, type VectorIndexMetric as C, type VectorIndexParams as D, type EdgeIndexConfig as E, type FulltextStrategy as F, type GraphBackend as G, type SchemaVersionRow as H, type IndexDeclaration as I, type JsonPointer as J, type InferenceType as K, type AggregateExpr as L, type MetaEdge as M, type NodeIndexConfig as N, type OntologyRelation as O, type FieldRef as P, type QueryAst as Q, type RelationalIndexDeclaration as R, type SqliteExecutionProfileHints as S, type ComparisonOp as T, type AggregateComparisonPredicate as U, type VectorStrategy as V, type TraversalDirection as W, type AdoptedTransaction as X, type BackendIdentity as Y, type BackendLifecycle as Z, type BackendMaintenance as _, type SqliteTransactionMode as a, fts5Strategy as a$, type CommitSchemaVersionExpected as a0, type CommitSchemaVersionParams as a1, type CompiledRowsSql as a2, type CompiledSelectSql as a3, type CompiledStatementSql as a4, type ContributionMaterializationBackend as a5, DEFAULT_SQL_SCHEMA as a6, type DeleteFulltextBatchParams as a7, type EdgeEntityReadBackend as a8, type EdgeEntityWriteBackend as a9, type RawStatementExecutionBackend as aA, type RecordedRelationOptions as aB, type RemovalMaterializationBackend as aC, type ResolveJsonPointer as aD, type ResolveJsonPointerSegments as aE, type ResolvedSqlTableNames as aF, type SchemaCommitBackend as aG, type SchemaReadBackend as aH, type SetActiveVersionParams as aI, type SortDirection as aJ, type SqlIntent as aK, type SqlSchema as aL, type SqlTableNames as aM, type StrategyTableContribution as aN, type TableContribution as aO, type TransactionBackend as aP, type TraversalExpansion as aQ, type UniqueConstraintBackend as aR, type UpsertFulltextBatchParams as aS, type VectorCapabilities as aT, type VectorOperationBackend as aU, type VectorSlot as aV, asCompiledRowsSql as aW, asCompiledSelectSql as aX, asCompiledStatementSql as aY, buildVectorCapabilities as aZ, createSqlSchema as a_, type ExternalRecordedReadSource as aa, type FulltextBatchRow as ab, type FulltextCapabilities as ac, type FulltextOperationBackend as ad, type FulltextQueryMode as ae, type FulltextSearchParams as af, type FulltextSearchResult as ag, type GraphEntityReadBackend as ah, type GraphEntityWriteBackend as ai, type GraphLifecycleBackend as aj, type HybridFusionOptions as ak, type IndexMaterializationBackend as al, type IntentSql as am, type JsonPointerFor as an, type JsonPointerInput as ao, type JsonPointerSegment as ap, type JsonPointerSegments as aq, type JsonPointerSegmentsFor as ar, MAX_JSON_POINTER_DEPTH as as, type MetaEdgeProperties as at, type NodeEntityReadBackend as au, type NodeEntityWriteBackend as av, type OrderSpec as aw, type ParameterRef as ax, type QueryExecutionBackend as ay, type RawQueryExecutionBackend as az, type AnyPgDatabase as b, isMetaEdge as b0, joinJsonPointers as b1, jsonPointer as b2, normalizeJsonPointer as b3, parseJsonPointer as b4, recordedRelation as b5, tsvectorStrategy as b6, type ValueType as b7, type PredicateExpression as b8, type VectorMetricType as b9, type Traversal as ba, type NodePredicate as bb, type ProjectedField as bc, type GroupBySpec as bd, type RecursiveCyclePolicy as be, type EdgeRow as bf, type NodeRow as bg, type VectorSlotMap as bh, type RecordedReadBinding as bi, type SelectiveField as bj, type ComposableQuery as bk, type SetOperationType as bl, type SetOperation as bm, type VectorMetric as bn, type TransactionOptions as bo, type EdgeIndexDeclaration as c, type NodeIndexDeclaration as d, type IndexWhereExpression as e, type SerializedNodeDef as f, type SerializedEdgeDef as g, type SerializedMetaEdge as h, type SerializedOntologyRelation as i, type SerializedClosures as j, type SerializedSchema as k, type SchemaHash as l, type JsonSchema as m, type SerializedOntology as n, type SerializedUniqueConstraint as o, type SqlDialect as p, type EdgeIndexDirection as q, type EdgeIndexWhereBuilder as r, type IndexOrigin as s, type IndexScope as t, type IndexWhereFieldBuilder as u, type IndexWhereInput as v, type NodeIndexWhereBuilder as w, type SystemColumnName as x, type VectorIndexDeclaration as y, type VectorIndexImplementation as z };
@@ -1,5 +1,5 @@
1
- import { A as AnyEdgeType, N as NodeType } from './extension-types-D1k0inWU.cjs';
2
- import { E as EdgeIndexConfig, c as EdgeIndexDeclaration, N as NodeIndexConfig, d as NodeIndexDeclaration, e as IndexWhereExpression } from './types-Dvmn-eal.cjs';
1
+ import { A as AnyEdgeType, N as NodeType } from './extension-types-YGFJPrzK.cjs';
2
+ import { E as EdgeIndexConfig, c as EdgeIndexDeclaration, N as NodeIndexConfig, d as NodeIndexDeclaration, e as IndexWhereExpression } from './types-C_UnQOQp.cjs';
3
3
 
4
4
  declare function defineNodeIndex<N extends NodeType>(node: N, config: NodeIndexConfig<N>): NodeIndexDeclaration;
5
5
  declare function defineEdgeIndex<E extends AnyEdgeType>(edge: E, config: EdgeIndexConfig<E>): EdgeIndexDeclaration;
@@ -1,5 +1,5 @@
1
- import { A as AnyEdgeType, N as NodeType } from './extension-types-D1k0inWU.js';
2
- import { E as EdgeIndexConfig, c as EdgeIndexDeclaration, N as NodeIndexConfig, d as NodeIndexDeclaration, e as IndexWhereExpression } from './types-Dk8r09KY.js';
1
+ import { A as AnyEdgeType, N as NodeType } from './extension-types-YGFJPrzK.js';
2
+ import { E as EdgeIndexConfig, c as EdgeIndexDeclaration, N as NodeIndexConfig, d as NodeIndexDeclaration, e as IndexWhereExpression } from './types-DGylBhWo.js';
3
3
 
4
4
  declare function defineNodeIndex<N extends NodeType>(node: N, config: NodeIndexConfig<N>): NodeIndexDeclaration;
5
5
  declare function defineEdgeIndex<E extends AnyEdgeType>(edge: E, config: EdgeIndexConfig<E>): EdgeIndexDeclaration;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@nicia-ai/typegraph",
3
- "version": "0.32.0",
3
+ "version": "0.33.0",
4
4
  "description": "TypeScript-first embedded knowledge graph library with ontological reasoning",
5
5
  "type": "module",
6
6
  "main": "./dist/index.cjs",