@nicia-ai/typegraph 0.38.0 → 0.40.0

package/dist/chunk-ELA3V6UN.js

@@ -0,0 +1,601 @@
+import { createSqliteTables, sqliteContributions, createPostgresTables, postgresContributions } from './chunk-5J4VNCUD.js';
+import { createSqlSchema } from './chunk-YYLMXERH.js';
+import { asRecordedInstant, createRecordedInstant, RECORDED_MAX_REVISION } from './chunk-QOHTVDHU.js';
+import { canonicalizeDatabaseTimestamp } from './chunk-3SHAUJRB.js';
+import { shortHash } from './chunk-Y5UC3IXF.js';
+import { asCompiledRowsSql, sql, asCompiledStatementSql } from './chunk-6N7QBIWN.js';
+import { ConfigurationError, ValidationError } from './chunk-DPNA466P.js';
+
+// src/backend/migrate-recorded-time.ts
+var LEGACY_RECORDED_MAX = "9999-12-31T23:59:59.999Z";
+var MIGRATION_SUFFIX = "legacy_recorded_anchors";
+var RECORDED_NODE_COLUMNS = [
+  "history_id",
+  "graph_id",
+  "kind",
+  "id",
+  "props",
+  "version",
+  "valid_from",
+  "valid_to",
+  "created_at",
+  "updated_at",
+  "deleted_at",
+  "recorded_from",
+  "recorded_to",
+  "op",
+  "schema_version",
+  "tx_id",
+  "meta"
+];
+var RECORDED_EDGE_COLUMNS = [
+  "history_id",
+  "graph_id",
+  "id",
+  "kind",
+  "from_kind",
+  "from_id",
+  "to_kind",
+  "to_id",
+  "props",
+  "valid_from",
+  "valid_to",
+  "created_at",
+  "updated_at",
+  "deleted_at",
+  "recorded_from",
+  "recorded_to",
+  "op",
+  "schema_version",
+  "tx_id",
+  "meta"
+];
+function resolvedTableNames(backend, override) {
+  return createSqlSchema(override ?? backend.tableNames ?? {}).tables;
+}
+function shortenedIdentifier(value) {
+  if (value.length <= 63) return value;
+  return `${value.slice(0, 50)}_${shortHash(value)}`;
+}
+function mappingTableName(tables, override) {
+  const candidate = override ?? `${tables.recordedClock}_${MIGRATION_SUFFIX}`;
+  return createSqlSchema({
+    recordedClock: shortenedIdentifier(candidate)
+  }).tables.recordedClock;
+}
+function temporaryTableName(tableName, role) {
+  return shortenedIdentifier(`__tg_${role}_${shortHash(tableName)}`);
+}
+function requireStatements(target) {
+  if (target.executeStatement === void 0) {
+    throw new ConfigurationError(
+      "Recorded-time migration requires executeStatement support.",
+      { dialect: target.dialect },
+      { suggestion: "Use a built-in SQLite or PostgreSQL backend." }
+    );
+  }
+  return target.executeStatement;
+}
+async function executeStatement(target, statement) {
+  await requireStatements(target)(asCompiledStatementSql(statement));
+}
+async function executeDdl(target, ddl) {
+  await executeStatement(target, sql.raw(ddl));
+}
+function canonicalLegacyInstant(value) {
+  const canonical = canonicalizeDatabaseTimestamp(value);
+  if (canonical === void 0) {
+    throw new ConfigurationError(
+      "Legacy recorded-time relation contained an invalid timestamp.",
+      { value }
+    );
+  }
+  return canonical;
+}
+function safeRevision(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 < 1 || revision >= RECORDED_MAX_REVISION) {
+    throw new ConfigurationError(
+      "Recorded anchor mapping contained an invalid revision.",
+      { value }
+    );
+  }
+  return revision;
+}
+async function columnNames(target, tableName) {
+  const rows = target.dialect === "sqlite" ? await target.execute(
+    asCompiledRowsSql(sql`PRAGMA table_info(${sql.identifier(tableName)})`)
+  ) : await target.execute(
+    asCompiledRowsSql(sql`
+          SELECT column_name AS name
+          FROM information_schema.columns
+          WHERE table_schema = current_schema()
+            AND table_name = ${tableName}
+        `)
+  );
+  return new Set(
+    rows.flatMap((row) => typeof row.name === "string" ? [row.name] : [])
+  );
+}
+async function readLegacyInstants(target, tables) {
+  const rows = await target.execute(
+    asCompiledRowsSql(sql`
+      SELECT graph_id, recorded_from AS recorded_at
+      FROM ${sql.identifier(tables.recordedNodes)}
+      UNION
+      SELECT graph_id, recorded_to AS recorded_at
+      FROM ${sql.identifier(tables.recordedNodes)}
+      WHERE recorded_to <> ${LEGACY_RECORDED_MAX}
+      UNION
+      SELECT graph_id, recorded_from AS recorded_at
+      FROM ${sql.identifier(tables.recordedEdges)}
+      UNION
+      SELECT graph_id, recorded_to AS recorded_at
+      FROM ${sql.identifier(tables.recordedEdges)}
+      WHERE recorded_to <> ${LEGACY_RECORDED_MAX}
+      UNION
+      SELECT graph_id, recorded_at
+      FROM ${sql.identifier(tables.recordedClock)}
+    `)
+  );
+  const instants = rows.map((row) => {
+    if (typeof row.graph_id !== "string") {
+      throw new ConfigurationError(
+        "Legacy recorded-time relation contained an invalid graph id.",
+        { graphId: row.graph_id }
+      );
+    }
+    return {
+      graphId: row.graph_id,
+      recordedAt: canonicalLegacyInstant(row.recorded_at)
+    };
+  });
+  instants.sort((left, right) => {
+    if (left.graphId < right.graphId) return -1;
+    if (left.graphId > right.graphId) return 1;
+    if (left.recordedAt < right.recordedAt) return -1;
+    if (left.recordedAt > right.recordedAt) return 1;
+    return 0;
+  });
+  const mapping = [];
+  let graphId;
+  let revision = 0;
+  let previousInstant;
+  for (const instant of instants) {
+    if (instant.graphId !== graphId) {
+      graphId = instant.graphId;
+      revision = 0;
+      previousInstant = void 0;
+    }
+    if (instant.recordedAt === previousInstant) continue;
+    revision += 1;
+    mapping.push({
+      graphId: instant.graphId,
+      legacyRecordedAt: instant.recordedAt,
+      recordedAt: instant.recordedAt,
+      revision
+    });
+    previousInstant = instant.recordedAt;
+  }
+  return mapping;
+}
+function migrationMapDdl(dialect, table) {
+  const revisionType = dialect === "postgres" ? "BIGINT" : "INTEGER";
+  const recordedAtType = dialect === "postgres" ? "TIMESTAMPTZ" : "TEXT";
+  return `CREATE TABLE IF NOT EXISTS "${table}" (
+  graph_id TEXT NOT NULL,
+  legacy_recorded_at TEXT NOT NULL,
+  revision ${revisionType} NOT NULL,
+  recorded_at ${recordedAtType} NOT NULL,
+  PRIMARY KEY (graph_id, legacy_recorded_at)
+);`;
+}
+async function writeMappingRows(target, tableName, rows) {
+  await executeStatement(target, sql`DELETE FROM ${sql.identifier(tableName)}`);
+  const rowsPerStatement = Math.max(
+    1,
+    Math.floor((target.capabilities.maxBindParameters ?? 900) / 4)
+  );
+  for (let start = 0; start < rows.length; start += rowsPerStatement) {
+    const values = rows.slice(start, start + rowsPerStatement).map(
+      (row) => sql`(${row.graphId}, ${row.legacyRecordedAt}, ${row.revision}, ${row.recordedAt})`
+    );
+    await executeStatement(
+      target,
+      sql`
+        INSERT INTO ${sql.identifier(tableName)}
+          (graph_id, legacy_recorded_at, revision, recorded_at)
+        VALUES ${sql.join(values, sql`, `)}
+      `
+    );
+  }
+}
+function tableDdl(dialect, tables, temporary) {
+  if (dialect === "sqlite") {
+    const temporaryTables2 = createSqliteTables(temporary);
+    const finalTables2 = createSqliteTables(tables);
+    const temporaryContributions = sqliteContributions(temporaryTables2);
+    const finalContributions = sqliteContributions(finalTables2);
+    return ddlForRecordedTables(temporaryContributions, finalContributions);
+  }
+  const temporaryTables = createPostgresTables(temporary);
+  const finalTables = createPostgresTables(tables);
+  return ddlForRecordedTables(
+    postgresContributions(temporaryTables),
+    postgresContributions(finalTables)
+  );
+}
+function ddlForRecordedTables(temporary, final) {
+  function statements(logicalName) {
+    const temporaryDdl = temporary.find(
+      (entry) => entry.logicalName === logicalName
+    )?.createDdl;
+    const finalDdl = final.find(
+      (entry) => entry.logicalName === logicalName
+    )?.createDdl;
+    if (temporaryDdl === void 0 || finalDdl === void 0) {
+      throw new ConfigurationError(
+        `Could not generate migration DDL for ${logicalName}.`
+      );
+    }
+    const createTable = temporaryDdl[0];
+    if (createTable === void 0) {
+      throw new ConfigurationError(
+        `Could not generate migration table DDL for ${logicalName}.`
+      );
+    }
+    return [createTable, ...finalDdl.slice(1)];
+  }
+  return {
+    clock: statements("recordedClock"),
+    edges: statements("recordedEdges"),
+    nodes: statements("recordedNodes")
+  };
+}
+function migratedColumn(column, legacyAlias) {
+  if (column === "recorded_from") return sql`from_map.revision`;
+  if (column === "recorded_to") {
+    return sql`
+      CASE
+            WHEN ${sql.raw(legacyAlias)}.recorded_to = ${LEGACY_RECORDED_MAX}
+            THEN ${RECORDED_MAX_REVISION}
+            ELSE to_map.revision
+          END
+    `;
+  }
+  return sql`${sql.raw(legacyAlias)}.${sql.identifier(column)}`;
+}
+function mappingMatch(dialect, mappingAlias, legacyColumn) {
+  const mapping = sql.raw(mappingAlias);
+  const legacy = sql.raw(`legacy.${legacyColumn}`);
+  return dialect === "postgres" ? sql`${mapping}.recorded_at = ${legacy}` : sql`${mapping}.legacy_recorded_at = ${legacy}`;
+}
+function missingMappingCount(value, legacyTable) {
+  const count = Number(value);
+  if (!Number.isSafeInteger(count) || count < 0) {
+    throw new ConfigurationError(
+      "Recorded-time migration returned an invalid integrity-check count.",
+      { legacyTable, value }
+    );
+  }
+  return count;
+}
+async function assertRecordedRelationMappings(target, options) {
+  const fromMatch = mappingMatch(target.dialect, "from_map", "recorded_from");
+  const toMatch = mappingMatch(target.dialect, "to_map", "recorded_to");
+  const rows = await target.execute(
+    asCompiledRowsSql(sql`
+      SELECT COUNT(*) AS missing
+      FROM ${sql.identifier(options.legacyTable)} AS legacy
+      LEFT JOIN ${sql.identifier(options.mappingTable)} AS from_map
+        ON from_map.graph_id = legacy.graph_id AND ${fromMatch}
+      LEFT JOIN ${sql.identifier(options.mappingTable)} AS to_map
+        ON to_map.graph_id = legacy.graph_id AND ${toMatch}
+      WHERE from_map.revision IS NULL
+         OR (
+           legacy.recorded_to <> ${LEGACY_RECORDED_MAX}
+           AND to_map.revision IS NULL
+         )
+    `)
+  );
+  const missing = missingMappingCount(rows[0]?.missing, options.legacyTable);
+  if (missing === 0) return;
+  throw new ConfigurationError(
+    "Legacy recorded-time boundaries could not be mapped exactly.",
+    { legacyTable: options.legacyTable, missingRows: missing },
+    {
+      suggestion: "Ensure every legacy boundary is a valid millisecond-precision timestamp produced by the preview recorded clock before retrying the offline migration."
+    }
+  );
+}
+async function assertRecordedClockMappings(target, options) {
+  const match = mappingMatch(target.dialect, "anchor_map", "recorded_at");
+  const rows = await target.execute(
+    asCompiledRowsSql(sql`
+      SELECT COUNT(*) AS missing
+      FROM ${sql.identifier(options.legacyTable)} AS legacy
+      LEFT JOIN ${sql.identifier(options.mappingTable)} AS anchor_map
+        ON anchor_map.graph_id = legacy.graph_id AND ${match}
+      WHERE anchor_map.revision IS NULL
+    `)
+  );
+  const missing = missingMappingCount(rows[0]?.missing, options.legacyTable);
+  if (missing === 0) return;
+  throw new ConfigurationError(
+    "Legacy recorded clock values could not be mapped exactly.",
+    { legacyTable: options.legacyTable, missingRows: missing },
+    {
+      suggestion: "Ensure every legacy clock value is a valid millisecond-precision timestamp produced by the preview recorded clock before retrying the offline migration."
+    }
+  );
+}
+async function copyRecordedRelation(target, options) {
+  const columnList = options.columns.map((column) => sql.identifier(column));
+  const values = options.columns.map(
+    (column) => migratedColumn(column, "legacy")
+  );
+  await assertRecordedRelationMappings(target, options);
+  const fromMatch = mappingMatch(target.dialect, "from_map", "recorded_from");
+  const toMatch = mappingMatch(target.dialect, "to_map", "recorded_to");
+  await executeStatement(
+    target,
+    sql`
+      INSERT INTO ${sql.identifier(options.temporaryTable)}
+        (${sql.join(columnList, sql`, `)})
+      SELECT ${sql.join(values, sql`, `)}
+      FROM ${sql.identifier(options.legacyTable)} AS legacy
+      -- LEFT JOIN is deliberate: a missing mapping reaches the NOT NULL
+      -- revision columns and fails loud instead of silently dropping history.
+      LEFT JOIN ${sql.identifier(options.mappingTable)} AS from_map
+        ON from_map.graph_id = legacy.graph_id AND ${fromMatch}
+      LEFT JOIN ${sql.identifier(options.mappingTable)} AS to_map
+        ON to_map.graph_id = legacy.graph_id AND ${toMatch}
+    `
+  );
+}
+async function copyRecordedClock(target, options) {
+  await assertRecordedClockMappings(target, options);
+  const match = mappingMatch(target.dialect, "anchor_map", "recorded_at");
+  await executeStatement(
+    target,
+    sql`
+      INSERT INTO ${sql.identifier(options.temporaryTable)}
+        (graph_id, revision, recorded_at)
+      SELECT legacy.graph_id, anchor_map.revision, legacy.recorded_at
+      FROM ${sql.identifier(options.legacyTable)} AS legacy
+      -- Preserve fail-loud behavior if the preflight invariant changes later.
+      LEFT JOIN ${sql.identifier(options.mappingTable)} AS anchor_map
+        ON anchor_map.graph_id = legacy.graph_id AND ${match}
+    `
+  );
+}
+async function replaceLegacyTables(target, tables, mappingTable) {
+  const temporary = {
+    recordedNodes: temporaryTableName(tables.recordedNodes, "rn"),
+    recordedEdges: temporaryTableName(tables.recordedEdges, "re"),
+    recordedClock: temporaryTableName(tables.recordedClock, "rc")
+  };
+  const ddl = tableDdl(target.dialect, tables, temporary);
+  for (const table of Object.values(temporary)) {
+    await executeStatement(
+      target,
+      sql`DROP TABLE IF EXISTS ${sql.identifier(table)}`
+    );
+  }
+  await executeDdl(target, requireCreateTable(ddl.nodes));
+  await executeDdl(target, requireCreateTable(ddl.edges));
+  await executeDdl(target, requireCreateTable(ddl.clock));
+  await copyRecordedRelation(target, {
+    columns: RECORDED_NODE_COLUMNS,
+    legacyTable: tables.recordedNodes,
+    mappingTable,
+    temporaryTable: temporary.recordedNodes
+  });
+  await copyRecordedRelation(target, {
+    columns: RECORDED_EDGE_COLUMNS,
+    legacyTable: tables.recordedEdges,
+    mappingTable,
+    temporaryTable: temporary.recordedEdges
+  });
+  await copyRecordedClock(target, {
+    legacyTable: tables.recordedClock,
+    mappingTable,
+    temporaryTable: temporary.recordedClock
+  });
+  await executeStatement(
+    target,
+    sql`DROP TABLE ${sql.identifier(tables.recordedNodes)}`
+  );
+  await executeStatement(
+    target,
+    sql`DROP TABLE ${sql.identifier(tables.recordedEdges)}`
+  );
+  await executeStatement(
+    target,
+    sql`DROP TABLE ${sql.identifier(tables.recordedClock)}`
+  );
+  await renameTable(target, temporary.recordedNodes, tables.recordedNodes);
+  await renameTable(target, temporary.recordedEdges, tables.recordedEdges);
+  await renameTable(target, temporary.recordedClock, tables.recordedClock);
+  await renamePrimaryKeyConstraint(
+    target,
+    temporary.recordedNodes,
+    tables.recordedNodes
+  );
+  await renamePrimaryKeyConstraint(
+    target,
+    temporary.recordedEdges,
+    tables.recordedEdges
+  );
+  await renamePrimaryKeyConstraint(
+    target,
+    temporary.recordedClock,
+    tables.recordedClock
+  );
+  for (const statement of [
+    ...ddl.nodes.slice(1),
+    ...ddl.edges.slice(1),
+    ...ddl.clock.slice(1)
+  ]) {
+    await executeDdl(target, statement);
+  }
+}
+async function renamePrimaryKeyConstraint(target, temporaryTable, finalTable) {
+  if (target.dialect !== "postgres") return;
+  await executeStatement(
+    target,
+    sql`
+      ALTER TABLE ${sql.identifier(finalTable)}
+      RENAME CONSTRAINT ${sql.identifier(`${temporaryTable}_pkey`)}
+      TO ${sql.identifier(shortenedIdentifier(`${finalTable}_pkey`))}
+    `
+  );
+}
+function requireCreateTable(statements) {
+  const statement = statements[0];
+  if (statement === void 0) {
+    throw new ConfigurationError("Recorded migration table DDL was empty.");
+  }
+  return statement;
+}
+async function renameTable(target, from, to) {
+  try {
+    await executeStatement(
+      target,
+      sql`ALTER TABLE ${sql.identifier(from)} RENAME TO ${sql.identifier(to)}`
+    );
+  } catch (error) {
+    throw new ConfigurationError(
+      "Could not rename a migrated recorded-time table.",
+      { from, to },
+      { cause: error }
+    );
+  }
+}
+async function migrateLegacyRecordedTime(options) {
+  const tables = resolvedTableNames(options.backend, options.tableNames);
+  const mapTable = mappingTableName(tables, options.mappingTableName);
+  return options.backend.transaction(async (target) => {
+    const clockColumns = await columnNames(target, tables.recordedClock);
+    if (clockColumns.size === 0) {
+      return {
+        migrated: false,
+        graphs: 0,
+        anchors: 0,
+        mappingTableName: mapTable
+      };
+    }
+    if (clockColumns.has("revision")) {
+      const mapColumns = await columnNames(target, mapTable);
+      if (mapColumns.size === 0) {
+        return {
+          migrated: false,
+          graphs: 0,
+          anchors: 0,
+          mappingTableName: mapTable
+        };
+      }
+      const rows = await target.execute(
+        asCompiledRowsSql(sql`
+          SELECT COUNT(*) AS anchors, COUNT(DISTINCT graph_id) AS graphs
+          FROM ${sql.identifier(mapTable)}
+        `)
+      );
+      const anchors = Number(rows[0]?.anchors ?? 0);
+      const graphs = Number(rows[0]?.graphs ?? 0);
+      return {
+        migrated: false,
+        graphs: Number.isSafeInteger(graphs) ? graphs : 0,
+        anchors: Number.isSafeInteger(anchors) ? anchors : 0,
+        mappingTableName: mapTable
+      };
+    }
+    const nodeColumns = await columnNames(target, tables.recordedNodes);
+    const edgeColumns = await columnNames(target, tables.recordedEdges);
+    if (!nodeColumns.has("recorded_from") || !edgeColumns.has("recorded_from")) {
+      throw new ConfigurationError(
+        "Legacy recorded-time schema is incomplete.",
+        { tables }
+      );
+    }
+    await executeDdl(target, migrationMapDdl(target.dialect, mapTable));
+    const mapping = await readLegacyInstants(target, tables);
+    await writeMappingRows(target, mapTable, mapping);
+    await replaceLegacyTables(target, tables, mapTable);
+    return {
+      migrated: true,
+      graphs: new Set(mapping.map((row) => row.graphId)).size,
+      anchors: mapping.length,
+      mappingTableName: mapTable
+    };
+  });
+}
+async function migrateRecordedAnchor(options) {
+  try {
+    return asRecordedInstant(options.anchor);
+  } catch (error) {
+    if (!(error instanceof ValidationError)) throw error;
+  }
+  const legacyRecordedAt = canonicalLegacyInstant(options.anchor);
+  const tables = resolvedTableNames(options.backend, options.tableNames);
+  const mapTable = mappingTableName(tables, options.mappingTableName);
+  const rows = await options.backend.execute(
+    asCompiledRowsSql(sql`
+      SELECT revision, recorded_at
+      FROM ${sql.identifier(mapTable)}
+      WHERE graph_id = ${options.graphId}
+        AND legacy_recorded_at = ${legacyRecordedAt}
+    `)
+  );
+  const row = rows[0];
+  if (row === void 0) {
+    throw new ConfigurationError(
+      "No migrated recorded anchor matches this graph and legacy timestamp.",
+      { anchor: options.anchor, graphId: options.graphId },
+      {
+        suggestion: "Run migrateLegacyRecordedTime() before deleting its mapping rows, and pass the graph that produced the checkpoint."
+      }
+    );
+  }
+  return createRecordedInstant(
+    safeRevision(row.revision),
+    canonicalLegacyInstant(row.recorded_at)
+  );
+}
+async function deleteLegacyRecordedAnchorMap(options) {
+  if (options.backend.executeStatement === void 0) {
+    throw new ConfigurationError(
+      "Deleting a recorded anchor migration map requires executeStatement support.",
+      { dialect: options.backend.dialect }
+    );
+  }
+  const tables = resolvedTableNames(options.backend, options.tableNames);
+  const mapTable = mappingTableName(tables, options.mappingTableName);
+  await options.backend.transaction(async (target) => {
+    await executeStatement(
+      target,
+      sql`
+        DELETE FROM ${sql.identifier(mapTable)}
+        WHERE graph_id = ${options.graphId}
+      `
+    );
+    if (options.dropWhenEmpty !== true) return;
+    const rows = await target.execute(
+      asCompiledRowsSql(sql`
+        SELECT COUNT(*) AS anchors, COUNT(DISTINCT graph_id) AS graphs
+        FROM ${sql.identifier(mapTable)}
+      `)
+    );
+    const remaining = missingMappingCount(rows[0]?.anchors, mapTable);
+    if (remaining === 0) {
+      await executeStatement(
+        target,
+        sql`DROP TABLE ${sql.identifier(mapTable)}`
+      );
+    }
+  });
+}
+
+export { deleteLegacyRecordedAnchorMap, migrateLegacyRecordedTime, migrateRecordedAnchor };
+//# sourceMappingURL=chunk-ELA3V6UN.js.map
+//# sourceMappingURL=chunk-ELA3V6UN.js.map