@nicia-ai/typegraph 0.38.0 → 0.40.0

package/dist/{chunk-RQPRCEIO.js → chunk-JHK6NPFV.js}

@@ -1,11 +1,10 @@
 import { groupBy, chunk } from './chunk-35S6P5ZU.js';
-import { createBackendOverlay, rowPropsToObject, rowPropsToJsonText } from './chunk-PZHC5GCD.js';
-import { RECORDED_MAX } from './chunk-J6IJARLG.js';
-import { withRecordedRelationsPrecondition } from './chunk-KFLXWVUJ.js';
-import { nowIso } from './chunk-I6FX7AAG.js';
-import { MAX_PG_IDENTIFIER_LENGTH } from './chunk-2EBMPJBO.js';
-import { likeEscapeClause, LIKE_ESCAPE_CHARACTER } from './chunk-DDCIXXOO.js';
-import { typeGraphGlobalSymbol, sql, asCompiledRowsSql, isSqlFragment, asCompiledStatementSql } from './chunk-6XDBRDZE.js';
+import { createSqlSchema } from './chunk-YYLMXERH.js';
+import { createBackendOverlay, rowPropsToObject, rowPropsToJsonText } from './chunk-L5ET7FYQ.js';
+import { parseRecordedInstant, createRecordedInstant, RECORDED_MAX_REVISION } from './chunk-QOHTVDHU.js';
+import { withRecordedRelationsPrecondition } from './chunk-UUIBACKJ.js';
+import { nowIso, canonicalizeDatabaseTimestamp } from './chunk-3SHAUJRB.js';
+import { typeGraphGlobalSymbol, sql, asCompiledRowsSql, likeEscapeClause, asCompiledStatementSql, LIKE_ESCAPE_CHARACTER } from './chunk-6N7QBIWN.js';
 import { resolveFieldTypeInfoAtJsonPointer } from './chunk-SNXVDZAJ.js';
 import { requireDefined, isPresent } from './chunk-QMQLUA66.js';
 import { resolveEmbeddingFields, getSearchableFields, DEFAULT_SEARCHABLE_LANGUAGE } from './chunk-PC2UBAUB.js';
@@ -13,210 +12,6 @@ import { ConfigurationError, UnsupportedPredicateError, CompilerInvariantError,
 import { normalizeJsonPointer, joinJsonPointers, jsonPointer } from './chunk-G6Q5UM7U.js';
 import { nanoid } from 'nanoid';
 
-// src/query/compiler/schema.ts
-var SQL_SCHEMA_BRAND = typeGraphGlobalSymbol("sql-schema-v1");
-var SqlSchema = class {
-};
-var SqlSchemaDescriptor = class extends SqlSchema {
-  tables;
-  nodesTable;
-  edgesTable;
-  recordedNodesTable;
-  recordedEdgesTable;
-  recordedClockTable;
-  revisionOriginsTable;
-  fulltextTable;
-  constructor(fields) {
-    super();
-    Object.defineProperty(this, SQL_SCHEMA_BRAND, {
-      configurable: false,
-      enumerable: false,
-      value: true,
-      writable: false
-    });
-    this.tables = fields.tables;
-    this.nodesTable = fields.nodesTable;
-    this.edgesTable = fields.edgesTable;
-    this.recordedNodesTable = fields.recordedNodesTable;
-    this.recordedEdgesTable = fields.recordedEdgesTable;
-    this.recordedClockTable = fields.recordedClockTable;
-    this.revisionOriginsTable = fields.revisionOriginsTable;
-    this.fulltextTable = fields.fulltextTable;
-    Object.freeze(this);
-  }
-};
-var DEFAULT_TABLE_NAMES = {
-  nodes: "typegraph_nodes",
-  edges: "typegraph_edges",
-  recordedNodes: "typegraph_recorded_nodes",
-  recordedEdges: "typegraph_recorded_edges",
-  recordedClock: "typegraph_recorded_clock",
-  revisionOrigins: "typegraph_revision_origins",
-  fulltext: "typegraph_node_fulltext",
-  uniques: "typegraph_node_uniques"
-};
-function resolveTableNames(names) {
-  return {
-    nodes: names.nodes ?? DEFAULT_TABLE_NAMES.nodes,
-    edges: names.edges ?? DEFAULT_TABLE_NAMES.edges,
-    recordedNodes: names.recordedNodes ?? DEFAULT_TABLE_NAMES.recordedNodes,
-    recordedEdges: names.recordedEdges ?? DEFAULT_TABLE_NAMES.recordedEdges,
-    recordedClock: names.recordedClock ?? DEFAULT_TABLE_NAMES.recordedClock,
-    revisionOrigins: names.revisionOrigins ?? DEFAULT_TABLE_NAMES.revisionOrigins,
-    fulltext: names.fulltext ?? DEFAULT_TABLE_NAMES.fulltext,
-    uniques: names.uniques ?? DEFAULT_TABLE_NAMES.uniques
-  };
-}
-var VALID_IDENTIFIER_PATTERN = /^[a-z_][a-z0-9_$]*$/i;
-function validateTableName(name, label) {
-  if (!name || name.length === 0) {
-    throw new ConfigurationError(`${label} table name cannot be empty`);
-  }
-  if (name.length > MAX_PG_IDENTIFIER_LENGTH) {
-    throw new ConfigurationError(
-      `${label} table name exceeds maximum length of ${MAX_PG_IDENTIFIER_LENGTH} characters`
-    );
-  }
-  if (!VALID_IDENTIFIER_PATTERN.test(name)) {
-    throw new ConfigurationError(
-      `${label} table name "${name}" is not a valid SQL identifier. Table names must start with a letter or underscore and contain only letters, digits, underscores, or dollar signs.`
-    );
-  }
-}
-function freezeSqlSchema(fields) {
-  return new SqlSchemaDescriptor(fields);
-}
-function isSqlSchema(schema) {
-  if (typeof schema !== "object" || schema === null) return false;
-  const candidate = schema;
-  return candidate[SQL_SCHEMA_BRAND] === true && typeof candidate["tables"] === "object" && candidate["tables"] !== null && Object.isFrozen(candidate["tables"]) && isSqlFragment(candidate["nodesTable"]) && isSqlFragment(candidate["edgesTable"]) && isSqlFragment(candidate["recordedNodesTable"]) && isSqlFragment(candidate["recordedEdgesTable"]) && isSqlFragment(candidate["recordedClockTable"]) && isSqlFragment(candidate["revisionOriginsTable"]) && isSqlFragment(candidate["fulltextTable"]) && Object.isFrozen(candidate);
-}
-function requireSqlSchema(schema, surface = "SqlSchema") {
-  if (isSqlSchema(schema)) return schema;
-  throw new ConfigurationError(
-    `${surface} must be created with createSqlSchema(...).`,
-    { code: "INVALID_SQL_SCHEMA", surface },
-    {
-      suggestion: "Pass the result of createSqlSchema(...) instead of a plain schema-shaped object."
-    }
-  );
-}
-function createSqlSchema(names = {}) {
-  const tables = resolveTableNames(names);
-  validateTableName(tables.nodes, "nodes");
-  validateTableName(tables.edges, "edges");
-  validateTableName(tables.recordedNodes, "recordedNodes");
-  validateTableName(tables.recordedEdges, "recordedEdges");
-  validateTableName(tables.recordedClock, "recordedClock");
-  validateTableName(tables.revisionOrigins, "revisionOrigins");
-  validateTableName(tables.fulltext, "fulltext");
-  validateTableName(tables.uniques, "uniques");
-  return freezeSqlSchema({
-    tables: Object.freeze(tables),
-    nodesTable: sql.identifier(tables.nodes),
-    edgesTable: sql.identifier(tables.edges),
-    recordedNodesTable: sql.identifier(tables.recordedNodes),
-    recordedEdgesTable: sql.identifier(tables.recordedEdges),
-    recordedClockTable: sql.identifier(tables.recordedClock),
-    revisionOriginsTable: sql.identifier(tables.revisionOrigins),
-    fulltextTable: sql.identifier(tables.fulltext)
-  });
-}
-var EXTERNAL_RECORDED_READ_SOURCE = typeGraphGlobalSymbol(
-  "external-recorded-read-source-v1"
-);
-var TYPEGRAPH_RECORDED_READ_SOURCE = typeGraphGlobalSymbol(
-  "typegraph-recorded-read-source-v1"
-);
-function recordedRelation(options) {
-  const schema = requireSqlSchema(options.schema, "recordedRelation schema");
-  return Object.freeze({
-    source: "external",
-    schema,
-    [EXTERNAL_RECORDED_READ_SOURCE]: true
-  });
-}
-function requireExternalRecordedReadSource(source) {
-  if (source === void 0) return void 0;
-  if (isExternalRecordedReadSource(source)) return source;
-  throw new ConfigurationError(
-    "recordedRead must be created with recordedRelation({ schema }).",
-    { code: "INVALID_RECORDED_READ_SOURCE" },
-    {
-      suggestion: "Pass { recordedRead: recordedRelation({ schema }) } for an externally populated recorded relation. Use { history: true } when TypeGraph should capture writes."
-    }
-  );
-}
-function isExternalRecordedReadSource(source) {
-  if (typeof source !== "object" || source === null) return false;
-  const candidate = source;
-  return candidate.source === "external" && candidate[EXTERNAL_RECORDED_READ_SOURCE] === true && isSqlSchema(candidate.schema) && Object.isFrozen(candidate);
-}
-function createRecordedReadBinding(schema) {
-  const readSchema = requireSqlSchema(schema, "recorded read binding schema");
-  return Object.freeze({
-    source: "typegraph-capture",
-    schema: readSchema,
-    [TYPEGRAPH_RECORDED_READ_SOURCE]: true
-  });
-}
-function requireRecordedReadBinding(binding, surface) {
-  if (isRecordedReadBinding(binding)) return binding;
-  if (binding !== void 0) {
-    throw new ConfigurationError(
-      "Recorded-time reads require a recorded read relation created by TypeGraph.",
-      { code: "INVALID_RECORDED_READ_BINDING", surface },
-      {
-        suggestion: "Use createStore(graph, backend, { history: true }) or { recordedRead: recordedRelation({ schema }) } instead of passing a plain object."
-      }
-    );
-  }
-  throw new ConfigurationError(
-    "Recorded-time reads require a recorded read relation.",
-    { code: "RECORDED_READ_REQUIRES_BINDING", surface },
-    {
-      suggestion: "Create the store with createStore(graph, backend, { history: true }) to bind TypeGraph's built-in captured relation, or pass { recordedRead: recordedRelation({ schema }) } for an externally populated recorded relation."
-    }
-  );
-}
-function isTypeGraphRecordedReadSource(source) {
-  if (typeof source !== "object" || source === null) return false;
-  const candidate = source;
-  return candidate.source === "typegraph-capture" && candidate[TYPEGRAPH_RECORDED_READ_SOURCE] === true && isSqlSchema(candidate.schema) && Object.isFrozen(candidate);
-}
-function isRecordedReadBinding(binding) {
-  return isExternalRecordedReadSource(binding) || isTypeGraphRecordedReadSource(binding);
-}
-function recordedReadSqlSchema(binding) {
-  const { schema } = requireRecordedReadBinding(
-    binding,
-    "recorded-read-schema"
-  );
-  return freezeSqlSchema({
-    tables: schema.tables,
-    nodesTable: schema.recordedNodesTable,
-    edgesTable: schema.recordedEdgesTable,
-    recordedNodesTable: schema.recordedNodesTable,
-    recordedEdgesTable: schema.recordedEdgesTable,
-    recordedClockTable: schema.recordedClockTable,
-    revisionOriginsTable: schema.revisionOriginsTable,
-    fulltextTable: schema.fulltextTable
-  });
-}
-function recordedReadSchemaFor(schema, recordedAsOf, binding, surface) {
-  const baseSchema = requireSqlSchema(schema, `${surface} schema`);
-  if (recordedAsOf === void 0) return baseSchema;
-  return recordedReadSqlSchema(requireRecordedReadBinding(binding, surface));
-}
-var DEFAULT_SQL_SCHEMA = createSqlSchema();
-function vectorSlotKey(nodeKind, fieldPath) {
-  return `${nodeKind}\0${fieldPath}`;
-}
-var ALIAS_CTE_PREFIX = "cte_";
-var EMBEDDINGS_CTE_ALIAS = "cte_embeddings";
-var FULLTEXT_CTE_ALIAS = "cte_fulltext";
-var HYBRID_CANDIDATES_CTE_ALIAS = "cte_relevance_candidates";
-
 // src/store/types.ts
 var AUTO_REFRESH_STATISTICS_ROW_THRESHOLD = 1e3;
 var TRANSACTION_RUNTIME = typeGraphGlobalSymbol(
@@ -286,7 +81,7 @@ function compileTemporalFilter(options) {
   const validFilter = (() => {
     switch (mode) {
       case "current": {
-        const now = recordedAsOf === void 0 ? currentTimestamp ?? currentReadInstant() : sql`${recordedAsOf}`;
+        const now = recordedAsOf === void 0 ? currentTimestamp ?? currentReadInstant() : sql`${parseRecordedInstant(recordedAsOf, "recordedAsOf").recordedAt}`;
         return sql`${deletedAt} IS NULL AND (${validFrom} IS NULL OR ${validFrom} <= ${now}) AND (${validTo} IS NULL OR ${validTo} > ${now})`;
       }
       case "asOf": {
@@ -309,7 +104,11 @@ function compileTemporalFilter(options) {
   if (recordedAsOf === void 0) return validFilter;
   const recordedFrom = sql`${prefix}recorded_from`;
   const recordedTo = sql`${prefix}recorded_to`;
-  return sql`(${validFilter}) AND ${recordedFrom} <= ${recordedAsOf} AND ${recordedAsOf} < ${recordedTo}`;
+  const recordedRevision = parseRecordedInstant(
+    recordedAsOf,
+    "recordedAsOf"
+  ).revision;
+  return sql`(${validFilter}) AND ${recordedFrom} <= ${recordedRevision} AND ${recordedRevision} < ${recordedTo}`;
 }
 function extractTemporalOptions(ast, tableAlias) {
   return {
@@ -1073,8 +872,8 @@ function assertRevisionTrackableBackend(backend) {
 }
 
 // src/store/recorded-capture/clock.ts
-var RECORDED_MIN = "1970-01-01T00:00:00.000Z";
-var RECORDED_MAX_TIME = new Date(RECORDED_MAX).getTime();
+var RECORDED_MIN_REVISION = 0;
+var RECORDED_MIN_TIME = "1970-01-01T00:00:00.000Z";
 var RECORDED_CLOCK_ADVISORY_LOCK_NAMESPACE = "typegraph:recorded-clock";
 var RECORDED_GRAPH_WRITE_ADVISORY_LOCK_NAMESPACE = "typegraph:recorded-graph-write";
 var USES_RECORDED_GRAPH_ADVISORY_LOCK = {
@@ -1139,61 +938,62 @@ async function lockRecordedGraphWrite(target, graphId, memo) {
   await pending;
   return graphWriteLockEvidence();
 }
-function failInvalidClockTimestamp(value) {
+function failInvalidClock(value, cause) {
   throw new ConfigurationError(
-    "Recorded clock row contained an invalid timestamp",
-    { value }
+    "Recorded clock row contained an invalid revision or wall time",
+    { value },
+    {
+      cause,
+      suggestion: "Run migrateLegacyRecordedTime() before using recorded-time tables created by the timestamp-only preview schema."
+    }
   );
 }
-var ZONELESS_DATETIME_PATTERN = /^\d{4}-\d{2}-\d{2}[ T]\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?$/;
-var OFFSET_DATETIME_PATTERN = /^(\d{4}-\d{2}-\d{2})[ T](\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?)(Z|[+-]\d{2}(?::?\d{2})?)$/i;
-function normalizeOffsetDesignator(offset) {
-  if (offset.toUpperCase() === "Z") return "Z";
-  if (/^[+-]\d{2}$/.test(offset)) return `${offset}:00`;
-  if (/^[+-]\d{4}$/.test(offset)) {
-    return `${offset.slice(0, 3)}:${offset.slice(3)}`;
-  }
-  return offset;
-}
-function clockTimestampMs(value) {
-  if (ZONELESS_DATETIME_PATTERN.test(value)) {
-    return Date.parse(`${value.replace(" ", "T")}Z`);
-  }
-  const offsetMatch = OFFSET_DATETIME_PATTERN.exec(value);
-  if (offsetMatch) {
-    const [, date, time, offset] = offsetMatch;
-    return Date.parse(
-      `${date}T${time}${normalizeOffsetDesignator(requireDefined(offset))}`
-    );
+function recordedClockRevision(value) {
+  const revision = typeof value === "bigint" ? Number(value) : typeof value === "string" && /^\d+$/.test(value) ? Number(value) : value;
+  if (typeof revision !== "number" || !Number.isSafeInteger(revision) || revision < RECORDED_MIN_REVISION || revision >= RECORDED_MAX_REVISION) {
+    return failInvalidClock(value);
   }
-  return Date.parse(value);
+  return revision;
 }
-function toCanonicalIso(value) {
-  if (value instanceof Date) {
-    if (Number.isNaN(value.getTime())) return failInvalidClockTimestamp(value);
-    return value.toISOString();
-  }
-  if (typeof value === "string") {
-    const timestamp = clockTimestampMs(value);
-    if (Number.isNaN(timestamp)) return failInvalidClockTimestamp(value);
-    return new Date(timestamp).toISOString();
+function recordedClockWallTime(value) {
+  return canonicalizeDatabaseTimestamp(value) ?? failInvalidClock(value);
+}
+function recordedClockParts(row) {
+  const revision = recordedClockRevision(row.revision);
+  if (revision === RECORDED_MIN_REVISION) return void 0;
+  return { revision, recordedAt: recordedClockWallTime(row.recorded_at) };
+}
+function nextRecordedCommitParts(previous) {
+  const wallTime = nowIso();
+  if (previous === void 0) {
+    return { revision: 1, recordedAt: wallTime };
   }
-  return failInvalidClockTimestamp(value);
+  return {
+    revision: previous.revision + 1,
+    // Keep diagonal replay cumulative across backward clock corrections without
+    // manufacturing a new millisecond for same-ms commits. Throughput can make
+    // this component repeat, never run ahead of the greatest observed wall time.
+    recordedAt: nonDecreasingWallTime(wallTime, previous.recordedAt)
+  };
 }
-function nextRecordedCommitTime(previous) {
-  const wallTime = Date.parse(nowIso());
-  return previous === void 0 ? wallTime : Math.max(wallTime, Date.parse(previous) + 1);
+function nonDecreasingWallTime(current, previous) {
+  if (current < previous) return previous;
+  return current;
 }
 async function readRecordedClock(target, schema, graphId) {
+  const parts = await readRecordedClockParts(target, schema, graphId);
+  return parts === void 0 ? void 0 : createRecordedInstant(parts.revision, parts.recordedAt);
+}
+async function readRecordedClockParts(target, schema, graphId) {
   const rows = await target.execute(
     asCompiledRowsSql(sql`
-      SELECT recorded_at
+      SELECT revision, recorded_at
       FROM ${schema.recordedClockTable}
       WHERE graph_id = ${graphId}
     `)
   );
-  const first = rows[0];
-  return first === void 0 ? void 0 : toCanonicalIso(first.recorded_at);
+  const row = rows[0];
+  return row === void 0 ? void 0 : recordedClockParts(row);
 }
 async function readRevisionOrigin(target, schema, graphId) {
   const rows = await target.execute(
@@ -1242,13 +1042,14 @@ async function ensureRevisionOrigin(target, schema, graphId) {
     { graphId, dialect: target.dialect }
   );
 }
-async function writeRecordedClock(target, schema, graphId, recordedAt) {
+async function writeRecordedClock(target, schema, graphId, parts) {
   await executeStatement(
     target,
     sql`
-      INSERT INTO ${schema.recordedClockTable} (graph_id, recorded_at)
-      VALUES (${graphId}, ${recordedAt})
-      ON CONFLICT (graph_id) DO UPDATE SET recorded_at = ${recordedAt}
+      INSERT INTO ${schema.recordedClockTable} (graph_id, revision, recorded_at)
+      VALUES (${graphId}, ${parts.revision}, ${parts.recordedAt})
+      ON CONFLICT (graph_id) DO UPDATE
+      SET revision = ${parts.revision}, recorded_at = ${parts.recordedAt}
     `
   );
 }
@@ -1265,9 +1066,9 @@ async function lockRecordedClock(target, schema, graphId, ownsWriteLock) {
       await executeStatement(
         target,
         sql`
-          INSERT INTO ${schema.recordedClockTable} (graph_id, recorded_at)
-          VALUES (${graphId}, ${RECORDED_MIN})
-          ON CONFLICT (graph_id) DO UPDATE SET recorded_at = recorded_at
+          INSERT INTO ${schema.recordedClockTable} (graph_id, revision, recorded_at)
+          VALUES (${graphId}, ${RECORDED_MIN_REVISION}, ${RECORDED_MIN_TIME})
+          ON CONFLICT (graph_id) DO UPDATE SET revision = revision
         `
       );
       return;
@@ -1279,29 +1080,30 @@ async function lockRecordedClock(target, schema, graphId, ownsWriteLock) {
 }
 async function allocateRecordedCommit(target, schema, graphId, ownsWriteLock, previousRevision) {
   await lockRecordedClock(target, schema, graphId, ownsWriteLock);
-  const previous = previousRevision ?? await readRecordedClock(target, schema, graphId);
-  const recordedCommitTime = nextRecordedCommitTime(previous);
-  if (!Number.isFinite(recordedCommitTime) || recordedCommitTime >= RECORDED_MAX_TIME) {
+  const previous = previousRevision === void 0 ? await readRecordedClockParts(target, schema, graphId) : parseRecordedInstant(previousRevision, "previous recorded revision");
+  const { revision, recordedAt } = nextRecordedCommitParts(previous);
+  if (revision >= RECORDED_MAX_REVISION) {
     throw new ConfigurationError(
-      `Recorded commit clock reached the open sentinel ${RECORDED_MAX}`,
-      { graphId, recordedCommitTime },
+      `Recorded commit clock reached the open revision sentinel ${RECORDED_MAX_REVISION}`,
+      { graphId, revision },
       {
-        suggestion: "Use a graph with a normal recorded-time clock; the open sentinel is reserved for relation intervals."
+        suggestion: "Start a new graph before exhausting the per-graph recorded revision space."
       }
     );
   }
-  const recordedCommit = new Date(recordedCommitTime).toISOString();
-  await writeRecordedClock(target, schema, graphId, recordedCommit);
-  return recordedCommit;
+  const instant = createRecordedInstant(revision, recordedAt);
+  await writeRecordedClock(target, schema, graphId, { revision, recordedAt });
+  return { instant, revision, recordedAt };
 }
 async function advanceRevisionClock(target, schema, graphId, ownsWriteLock, previousRevision) {
-  return allocateRecordedCommit(
+  const commit = await allocateRecordedCommit(
     target,
     schema,
     graphId,
     ownsWriteLock,
     previousRevision
   );
+  return commit.instant;
 }
 
 // src/backend/graph-backend-projection.ts
@@ -2241,8 +2043,8 @@ function recordedCommonCells() {
     created_at: (row) => sql`${row.created_at}`,
     updated_at: (row) => sql`${row.updated_at}`,
     deleted_at: (row) => sql`${sqlNull(row.deleted_at)}`,
-    recorded_from: (_row, recordedCommit) => sql`${recordedCommit}`,
-    recorded_to: () => sql`${RECORDED_MAX}`,
+    recorded_from: (_row, recordedRevision) => sql`${recordedRevision}`,
+    recorded_to: () => sql`${RECORDED_MAX_REVISION}`,
     op: (_row, _recordedCommit, operation) => sql`${operation}`,
     schema_version: () => sql`NULL`,
     tx_id: () => sql`NULL`,
@@ -2260,20 +2062,20 @@ var recordedEdgeCells = {
   to_kind: (row) => sql`${row.to_kind}`,
   to_id: (row) => sql`${row.to_id}`
 };
-function recordedValuesTuple(columns, cells, row, recordedCommit, operation) {
+function recordedValuesTuple(columns, cells, row, recordedRevision, operation) {
   const tuple = columns.map(
-    (column) => cells[column](row, recordedCommit, operation)
+    (column) => cells[column](row, recordedRevision, operation)
   );
   return sql`(${sql.join(tuple, sql`, `)})`;
 }
-async function insertRecordedRows(target, table, columnList, columns, cells, inserts, recordedCommit) {
+async function insertRecordedRows(target, table, columnList, columns, cells, inserts, recordedRevision) {
   if (inserts.length === 0) return;
   const values = inserts.map(
     (insert) => recordedValuesTuple(
       columns,
       cells,
       insert.row,
-      recordedCommit,
+      recordedRevision,
       insert.operation
     )
   );
@@ -2291,7 +2093,7 @@ function recordedNodeChunkSize(target) {
 function recordedEdgeChunkSize(target) {
   return recordedChunkSize(target, RECORDED_EDGE_COLUMNS.length);
 }
-function insertRecordedNodeRows(target, table, inserts, recordedCommit) {
+function insertRecordedNodeRows(target, table, inserts, recordedRevision) {
   return insertRecordedRows(
     target,
     table,
@@ -2299,10 +2101,10 @@ function insertRecordedNodeRows(target, table, inserts, recordedCommit) {
     RECORDED_NODE_COLUMNS,
     recordedNodeCells,
     inserts,
-    recordedCommit
+    recordedRevision
   );
 }
-function insertRecordedEdgeRows(target, table, inserts, recordedCommit) {
+function insertRecordedEdgeRows(target, table, inserts, recordedRevision) {
   return insertRecordedRows(
     target,
     table,
@@ -2310,7 +2112,7 @@ function insertRecordedEdgeRows(target, table, inserts, recordedCommit) {
     RECORDED_EDGE_COLUMNS,
     recordedEdgeCells,
     inserts,
-    recordedCommit
+    recordedRevision
   );
 }
 
@@ -2325,15 +2127,15 @@ function entityKey(entity) {
     }
   }
 }
-async function closeOpenReturning(target, table, graphId, ids, recordedCommit, kind) {
+async function closeOpenReturning(target, table, graphId, ids, recordedRevision, kind) {
   const kindFilter = kind === void 0 ? sql`` : sql`AND kind = ${kind}`;
   const rows = await target.execute(
     asCompiledRowsSql(sql`
       UPDATE ${table}
-      SET recorded_to = ${recordedCommit}
+      SET recorded_to = ${recordedRevision}
       WHERE graph_id = ${graphId}
         ${kindFilter}
-        AND recorded_to = ${RECORDED_MAX}
+        AND recorded_to = ${RECORDED_MAX_REVISION}
         AND id IN (${sqlValueList(ids)})
       RETURNING id, deleted_at
     `)
@@ -2375,7 +2177,7 @@ function recordedInsertsFor(afterById, closed) {
     operation: recordedOp(closed.has(row.id), closed.get(row.id) ?? false, row)
   }));
 }
-async function flushNodes(target, schema, graphId, entities, recordedCommit) {
+async function flushNodes(target, schema, graphId, entities, recordedRevision) {
   const chunkSize = recordedNodeChunkSize(target);
   for (const [kind, group] of groupNodesByKind(entities)) {
     for (const entityChunk of chunk(group, chunkSize)) {
@@ -2385,7 +2187,7 @@ async function flushNodes(target, schema, graphId, entities, recordedCommit) {
         schema.recordedNodesTable,
         graphId,
         ids,
-        recordedCommit,
+        recordedRevision,
         kind
       );
       const afterById = await resolveAfterImages(
@@ -2396,12 +2198,12 @@ async function flushNodes(target, schema, graphId, entities, recordedCommit) {
         target,
         schema.recordedNodesTable,
         recordedInsertsFor(afterById, closed),
-        recordedCommit
+        recordedRevision
       );
     }
   }
 }
-async function flushEdges(target, schema, graphId, entities, recordedCommit) {
+async function flushEdges(target, schema, graphId, entities, recordedRevision) {
   const chunkSize = recordedEdgeChunkSize(target);
   for (const entityChunk of chunk(entities, chunkSize)) {
     const ids = entityChunk.map((entity) => entity.id);
@@ -2410,7 +2212,7 @@ async function flushEdges(target, schema, graphId, entities, recordedCommit) {
       schema.recordedEdgesTable,
       graphId,
       ids,
-      recordedCommit
+      recordedRevision
     );
     const afterById = await resolveAfterImages(
       entityChunk,
@@ -2420,31 +2222,31 @@ async function flushEdges(target, schema, graphId, entities, recordedCommit) {
       target,
       schema.recordedEdgesTable,
       recordedInsertsFor(afterById, closed),
-      recordedCommit
+      recordedRevision
     );
   }
 }
-async function closeOpenByKind(target, table, graphId, kind, recordedCommit) {
+async function closeOpenByKind(target, table, graphId, kind, recordedRevision) {
   await executeStatement(
     target,
     sql`
       UPDATE ${table}
-      SET recorded_to = ${recordedCommit}
+      SET recorded_to = ${recordedRevision}
       WHERE graph_id = ${graphId}
         AND kind = ${kind}
-        AND recorded_to = ${RECORDED_MAX}
+        AND recorded_to = ${RECORDED_MAX_REVISION}
     `
   );
 }
-async function closeOpenEdgesByNodeKind(target, schema, graphId, nodeKind, recordedCommit) {
+async function closeOpenEdgesByNodeKind(target, schema, graphId, nodeKind, recordedRevision) {
   await executeStatement(
     target,
     sql`
       UPDATE ${schema.recordedEdgesTable}
-      SET recorded_to = ${recordedCommit}
+      SET recorded_to = ${recordedRevision}
       WHERE graph_id = ${graphId}
         AND (from_kind = ${nodeKind} OR to_kind = ${nodeKind})
-        AND recorded_to = ${RECORDED_MAX}
+        AND recorded_to = ${RECORDED_MAX_REVISION}
     `
   );
 }
@@ -2461,14 +2263,14 @@ async function closeRecordedHardDeletedKind(target, schema, graphId, removal, ow
       schema.recordedNodesTable,
       graphId,
       removal.kind,
-      recordedCommit
+      recordedCommit.revision
     );
     await closeOpenEdgesByNodeKind(
       target,
       schema,
       graphId,
       removal.kind,
-      recordedCommit
+      recordedCommit.revision
     );
     return;
   }
@@ -2477,7 +2279,7 @@ async function closeRecordedHardDeletedKind(target, schema, graphId, removal, ow
     schema.recordedEdgesTable,
     graphId,
     removal.kind,
-    recordedCommit
+    recordedCommit.revision
   );
 }
 async function queryConnectedEdgeIds(target, schema, params) {
@@ -2495,6 +2297,104 @@ async function queryConnectedEdgeIds(target, schema, params) {
   return rows.map((row) => row.id);
 }
 
+// src/store/recorded-capture/schema-version.ts
+function normalizedColumnType(value) {
+  if (typeof value !== "string") return void 0;
+  const normalized = value.trim().toLowerCase();
+  return normalized.length === 0 ? void 0 : normalized;
+}
+async function readColumnTypes(backend, table) {
+  const rows = backend.dialect === "sqlite" ? await backend.execute(
+    asCompiledRowsSql(sql`PRAGMA table_info(${sql.identifier(table)})`)
+  ) : await backend.execute(
+    asCompiledRowsSql(sql`
+          SELECT column_name AS name, data_type AS type
+          FROM information_schema.columns
+          WHERE table_schema = current_schema()
+            AND table_name = ${table}
+        `)
+  );
+  return new Map(
+    rows.flatMap((row) => {
+      if (typeof row.name !== "string") return [];
+      const type = normalizedColumnType(row.type);
+      return type === void 0 ? [] : [[row.name, type]];
+    })
+  );
+}
+function hasSqliteAffinity(declaredType, kind) {
+  if (kind === "revision") return declaredType.includes("int");
+  return declaredType.includes("char") || declaredType.includes("clob") || declaredType.includes("text");
+}
+function isCompatibleColumnType(dialect, declaredType, kind) {
+  if (dialect === "sqlite") return hasSqliteAffinity(declaredType, kind);
+  return kind === "revision" ? declaredType === "bigint" : declaredType === "timestamp with time zone";
+}
+function requiredRecordedColumns(schema) {
+  return [
+    {
+      table: schema.tables.recordedNodes,
+      column: "recorded_from",
+      kind: "revision"
+    },
+    {
+      table: schema.tables.recordedNodes,
+      column: "recorded_to",
+      kind: "revision"
+    },
+    {
+      table: schema.tables.recordedEdges,
+      column: "recorded_from",
+      kind: "revision"
+    },
+    {
+      table: schema.tables.recordedEdges,
+      column: "recorded_to",
+      kind: "revision"
+    },
+    {
+      table: schema.tables.recordedClock,
+      column: "revision",
+      kind: "revision"
+    },
+    {
+      table: schema.tables.recordedClock,
+      column: "recorded_at",
+      kind: "wall-time"
+    }
+  ];
+}
+async function assertCurrentRecordedSchema(backend, schema) {
+  const requirements = requiredRecordedColumns(schema);
+  const tables = [...new Set(requirements.map((entry) => entry.table))];
+  const columnTypes = new Map(
+    await Promise.all(
+      tables.map(
+        async (table) => [table, await readColumnTypes(backend, table)]
+      )
+    )
+  );
+  const incompatible = requirements.flatMap((requirement) => {
+    const actual = columnTypes.get(requirement.table)?.get(requirement.column);
+    if (actual !== void 0 && isCompatibleColumnType(backend.dialect, actual, requirement.kind)) {
+      return [];
+    }
+    return [{ ...requirement, actual: actual ?? "missing" }];
+  });
+  if (incompatible.length === 0) return;
+  throw new ConfigurationError(
+    "Recorded-time schema is incompatible with history capture.",
+    {
+      code: "RECORDED_SCHEMA_INCOMPATIBLE",
+      dialect: backend.dialect,
+      incompatible
+    },
+    {
+      suggestion: "Run migrateLegacyRecordedTime({ backend }) before opening a store with history: true. If these are not preview-schema tables, provision the current recorded relations first."
+    }
+  );
+}
+
 // src/store/recorded-capture.ts
 var RECORDED_FLUSH_OBSERVER = /* @__PURE__ */ Symbol("typegraph.recordedFlushObserver");
 function readRecordedFlushObserver(options) {
@@ -2582,15 +2482,27 @@ function createRecordedCaptureSession() {
           graphId,
           ownsWriteLock
         );
-        recordedByGraph.set(graphId, recordedCommit);
+        recordedByGraph.set(graphId, recordedCommit.instant);
         const nodes = entities.filter(
           (entity) => entity.entity === "node"
         );
         const edges = entities.filter(
           (entity) => entity.entity === "edge"
         );
-        await flushNodes(target, schema, graphId, nodes, recordedCommit);
-        await flushEdges(target, schema, graphId, edges, recordedCommit);
+        await flushNodes(
+          target,
+          schema,
+          graphId,
+          nodes,
+          recordedCommit.revision
+        );
+        await flushEdges(
+          target,
+          schema,
+          graphId,
+          edges,
+          recordedCommit.revision
+        );
       }
       touched.clear();
       return recordedByGraph;
@@ -3683,6 +3595,6 @@ async function applyNodeResurrect(ctx, args, backend) {
   return row;
 }
 
-export { ALIAS_CTE_PREFIX, AUTO_REFRESH_STATISTICS_ROW_THRESHOLD, CURRENT_READ_INSTANT_PLACEHOLDER, DEFAULT_SQL_SCHEMA, EMBEDDINGS_CTE_ALIAS, FULLTEXT_CTE_ALIAS, HYBRID_CANDIDATES_CTE_ALIAS, STORE_RUNTIME, TRANSACTION_RUNTIME, advanceRevisionClock, applyNodeHardDelete, applyNodeInsertSideEffects, applyNodeInsertSideEffectsBatch, applyNodeResurrect, applyNodeSoftDelete, applyNodeUpdate, arrayField, assertRecordedCaptureTransactionIsolation, assertRevisionTrackableBackend, baseField, buildFieldBuilderForTypeInfo, buildPredicateIndex, checkCardinality, checkDisjointness, checkUniqueEdge, checkUniquenessConstraints, checkWherePredicate, closeRecordedHardDeletedKind, compileFieldValue, compileKindFilter, compilePredicateClauses, compilePredicateExpression, compileTemporalFilter, computeFulltextContent, computeUniqueKey, createFulltextAccessor, createGraphBackendProjection, createNodeWriteContext, createRecordedBackend, createRecordedReadBinding, createRecordedTransactionScope, createSqlSchema, createUniquenessContext, currentReadInstant, currentReadInstantFor, dateField, edgeInsertDispatch, ensureRevisionOrigin, exists, extractFulltextMatchPredicates, extractTemporalOptions, extractVectorSimilarityPredicates, fieldRef, generateId, getEdgeRowsByIds, getEmbeddingFields, getFieldPointer, getHybridTargetAlias, getKindsForUniquenessCheck, getNodeKindsForAlias, getNodeRowsByIds, getPredicatesForAlias, inSubquery, isParameterRef, lockRecordedGraphWrite, nodeInsertDispatch, notExists, notInSubquery, numberField, objectField, param, projectBackendMembers, readRecordedClock, readRevisionOrigin, recordedBindParamBudget, recordedCaptureRequiresCallbackTransactionError, recordedReadSchemaFor, recordedReadSqlSchema, recordedRelation, requireExternalRecordedReadSource, requireRecordedReadBinding, requireSqlSchema, runInsertBatch, runInsertBatchReturning, runInsertNoReturn, sqlValueList, storeBackend, storeRuntime, stringField, throwHistoryUnsafeSqlAccess, throwRevisionTrackingUnsafeSqlAccess, transactionBackend, transactionNodeOperationHookRunner, uncapturedGraphWriteLock, validateEdgeEndpoints, vectorSlotKey, withPinnedReadInstant, withRecordedFlushObserver };
-//# sourceMappingURL=chunk-RQPRCEIO.js.map
-//# sourceMappingURL=chunk-RQPRCEIO.js.map
+export { AUTO_REFRESH_STATISTICS_ROW_THRESHOLD, CURRENT_READ_INSTANT_PLACEHOLDER, STORE_RUNTIME, TRANSACTION_RUNTIME, advanceRevisionClock, applyNodeHardDelete, applyNodeInsertSideEffects, applyNodeInsertSideEffectsBatch, applyNodeResurrect, applyNodeSoftDelete, applyNodeUpdate, arrayField, assertCurrentRecordedSchema, assertRecordedCaptureTransactionIsolation, assertRevisionTrackableBackend, baseField, buildFieldBuilderForTypeInfo, buildPredicateIndex, checkCardinality, checkDisjointness, checkUniqueEdge, checkUniquenessConstraints, checkWherePredicate, closeRecordedHardDeletedKind, compileFieldValue, compileKindFilter, compilePredicateClauses, compilePredicateExpression, compileTemporalFilter, computeFulltextContent, computeUniqueKey, createFulltextAccessor, createGraphBackendProjection, createNodeWriteContext, createRecordedBackend, createRecordedTransactionScope, createUniquenessContext, currentReadInstant, currentReadInstantFor, dateField, edgeInsertDispatch, ensureRevisionOrigin, exists, extractFulltextMatchPredicates, extractTemporalOptions, extractVectorSimilarityPredicates, fieldRef, generateId, getEdgeRowsByIds, getEmbeddingFields, getFieldPointer, getHybridTargetAlias, getKindsForUniquenessCheck, getNodeKindsForAlias, getNodeRowsByIds, getPredicatesForAlias, inSubquery, isParameterRef, lockRecordedGraphWrite, nodeInsertDispatch, notExists, notInSubquery, numberField, objectField, param, projectBackendMembers, readRecordedClock, readRevisionOrigin, recordedBindParamBudget, recordedCaptureRequiresCallbackTransactionError, runInsertBatch, runInsertBatchReturning, runInsertNoReturn, sqlValueList, storeBackend, storeRuntime, stringField, throwHistoryUnsafeSqlAccess, throwRevisionTrackingUnsafeSqlAccess, transactionBackend, transactionNodeOperationHookRunner, uncapturedGraphWriteLock, validateEdgeEndpoints, withPinnedReadInstant, withRecordedFlushObserver };
+//# sourceMappingURL=chunk-JHK6NPFV.js.map
+//# sourceMappingURL=chunk-JHK6NPFV.js.map