@nicia-ai/typegraph 0.46.1 → 0.47.0

package/dist/{chunk-GF3KXUTW.js → chunk-NNQ6A3RM.js}

@@ -1,10 +1,10 @@
-import { advanceRevisionClock, lockRecordedGraphWrite, uncapturedGraphWriteLock, identityAssertionSnapshotSource, identitySqlCoordinate, IDENTITY_ASSERTION_COLUMNS, compareCodePoints, withRecordedIdentityMutationTarget, recordedBindParamBudget, identityNodeVisibilitySql, historicalIdentityReconstructionCtes, generateId, identityNodeSnapshotSource } from './chunk-NLI2AVEF.js';
-import { chunk, isSqliteStaleSnapshotError, isMissingTableError } from './chunk-JZUR7ZWE.js';
-import { runOptionallyInTransaction } from './chunk-AKLS3BYZ.js';
-import { nowIso, canonicalizeDatabaseTimestamp } from './chunk-XL7SLCXS.js';
-import { getDialect } from './chunk-YDFDBE6D.js';
-import { asCompiledRowsSql, sql, asCompiledStatementSql } from './chunk-PQBQG7IM.js';
-import { ValidationError, ConfigurationError, NodeNotFoundError, KindNotFoundError, IdentityContradictionError, IdentitySeparationViolationError } from './chunk-J3WZ3FA2.js';
+import { advanceRevisionClock, lockRecordedGraphWrite, uncapturedGraphWriteLock, identityAssertionSnapshotSource, identitySqlCoordinate, IDENTITY_ASSERTION_COLUMNS, compareCodePoints, withRecordedIdentityMutationTarget, recordedBindParamBudget, identityNodeVisibilitySql, historicalIdentityReconstructionCtes, generateId, identityNodeSnapshotSource } from './chunk-AVGUJWVX.js';
+import { chunk, isSqliteStaleSnapshotError, isMissingTableError } from './chunk-NAZ2RA4L.js';
+import { runOptionallyInTransaction } from './chunk-SHSSRCFR.js';
+import { nowIso, canonicalizeDatabaseTimestamp, validateOptionalCanonicalIsoDate } from './chunk-NG2RB5WL.js';
+import { getDialect } from './chunk-ZDKTPBGV.js';
+import { asCompiledRowsSql, sql, asCompiledStatementSql } from './chunk-3DMMGT6S.js';
+import { ValidationError, ConfigurationError, IdentityEndpointValidityError, NodeNotFoundError, KindNotFoundError, IdentityValidityWindowError, IdentityContradictionError, IdentitySeparationViolationError } from './chunk-ZLONH2UD.js';
 import { requireDefined } from './chunk-DYATYRY4.js';
 
 // src/errors/validation.ts
@@ -684,6 +684,12 @@ async function readIdentityAssertionsForInterchange(ctx, mode, options) {
 
 // src/store/operations/write-transaction.ts
 var writeTransactionSessions = /* @__PURE__ */ new WeakMap();
+function forceWriteTransactionRevision(target) {
+  const session = writeTransactionSessions.get(target);
+  if (session === void 0) return false;
+  session.wrote = true;
+  return true;
+}
 var heldGraphWriteLocks = /* @__PURE__ */ new WeakMap();
 async function withWriteTransactionSession(target, ctx, fn) {
   const session = {
@@ -1490,6 +1496,51 @@ function separationMismatchError(graphId, detail) {
   );
 }
 
+// src/identity/validity-window.ts
+function hasExplicitIdentityValidityWindow(window) {
+  return window?.validFrom !== void 0 || window?.validTo !== void 0;
+}
+function resolveIdentityValidityWindow(window, operationInstant) {
+  const validFrom = validateOptionalCanonicalIsoDate(window?.validFrom, "validFrom") ?? operationInstant;
+  const validTo = validateOptionalCanonicalIsoDate(window?.validTo, "validTo");
+  if (compareCodePoints(validFrom, operationInstant) > 0) {
+    throw new IdentityValidityWindowError({
+      reason: "future-valid-from",
+      validFrom,
+      ...validTo === void 0 ? {} : { validTo },
+      operationInstant
+    });
+  }
+  if (validTo !== void 0 && compareCodePoints(validTo, operationInstant) > 0) {
+    throw new IdentityValidityWindowError({
+      reason: "future-valid-to",
+      validFrom,
+      validTo,
+      operationInstant
+    });
+  }
+  if (validTo !== void 0 && compareCodePoints(validTo, validFrom) < 0) {
+    throw new IdentityValidityWindowError({
+      reason: "inverted",
+      validFrom,
+      validTo,
+      operationInstant
+    });
+  }
+  const effective = validTo === validFrom ? "empty" : validTo === void 0 ? "current" : "historical";
+  return {
+    validFrom,
+    ...validTo === void 0 ? {} : { validTo },
+    effective
+  };
+}
+function identityValidityWindowsOverlap(left, right) {
+  if (left.validFrom === left.validTo || right.validFrom === right.validTo) {
+    return false;
+  }
+  return (right.validTo === void 0 || left.validFrom < right.validTo) && (left.validTo === void 0 || right.validFrom < left.validTo);
+}
+
 // src/identity/service-mutation.ts
 async function validateCurrentRelation(ctx, target, relation, operation, a, b) {
   const classes = await loadCurrentStructuralClasses(
@@ -1557,23 +1608,50 @@ async function currentAssertionForPair(target, schema, graphId, relation, a, b)
   );
   return rows[0] === void 0 ? void 0 : normalizeIdentityAssertionRow(rows[0]);
 }
-async function insertAssertion(target, schema, graphId, relation, a, b, timestamp, touch, preserved) {
-  const row = buildAssertionRow(graphId, relation, a, b, timestamp, preserved);
+async function assertionForExactWindow(target, schema, graphId, relation, a, b, window) {
+  const validToMatch = window.validTo === void 0 ? sql`valid_to IS NULL` : sql`valid_to = ${window.validTo}`;
+  const rows = await target.execute(
+    asCompiledRowsSql(sql`
+      SELECT ${IDENTITY_ASSERTION_COLUMNS}
+      FROM ${schema.identityAssertionsTable}
+      WHERE graph_id = ${graphId}
+        AND rel = ${relation}
+        AND a_kind = ${a.kind}
+        AND a_id = ${a.id}
+        AND b_kind = ${b.kind}
+        AND b_id = ${b.id}
+        AND valid_from = ${window.validFrom}
+        AND ${validToMatch}
+        AND deleted_at IS NULL
+      LIMIT 1
+    `)
+  );
+  return rows[0] === void 0 ? void 0 : normalizeIdentityAssertionRow(rows[0]);
+}
+async function insertAssertion(target, schema, graphId, relation, a, b, operationInstant, touch, options) {
+  const row = buildAssertionRow(
+    graphId,
+    relation,
+    a,
+    b,
+    operationInstant,
+    options
+  );
   await insertAssertionRows(target, schema, [row]);
   touch(graphId, row.id, row);
   return row;
 }
-function buildAssertionRow(graphId, relation, a, b, timestamp, preserved) {
+function buildAssertionRow(graphId, relation, a, b, timestamp, options) {
   return {
     graph_id: graphId,
-    id: preserved?.id ?? generateId(),
+    id: options?.id ?? generateId(),
     rel: relation,
     a_kind: a.kind,
     a_id: a.id,
     b_kind: b.kind,
     b_id: b.id,
-    valid_from: preserved?.validFrom ?? timestamp,
-    valid_to: void 0,
+    valid_from: options?.validFrom ?? timestamp,
+    valid_to: options?.validTo,
     created_at: timestamp,
     updated_at: timestamp,
     deleted_at: void 0,
@@ -1581,6 +1659,329 @@ function buildAssertionRow(graphId, relation, a, b, timestamp, preserved) {
     ended_by_id: void 0
   };
 }
+function canonicalEndpointTimestamp(value) {
+  if (value === void 0 || value === null) return void 0;
+  return canonicalizeDatabaseTimestamp(value);
+}
+async function requireEndpointsCoverIdentityWindow(target, graphId, references, window) {
+  for (const ref of references) {
+    const row = await target.getNode(graphId, ref.kind, ref.id);
+    if (row === void 0) throw new NodeNotFoundError(ref.kind, ref.id);
+    if (window.effective === "empty") continue;
+    const validFrom = canonicalEndpointTimestamp(row.valid_from);
+    const validTo = canonicalEndpointTimestamp(row.valid_to);
+    const deletedAt = canonicalEndpointTimestamp(row.deleted_at);
+    const endpointWindow = {
+      ...validFrom === void 0 ? {} : { validFrom },
+      ...validTo === void 0 ? {} : { validTo },
+      ...deletedAt === void 0 ? {} : { deletedAt }
+    };
+    const startsTooLate = endpointWindow.validFrom !== void 0 && endpointWindow.validFrom > window.validFrom;
+    const effectiveEnd = [endpointWindow.validTo, endpointWindow.deletedAt].filter((value) => value !== void 0).toSorted()[0];
+    const endsTooEarly = window.validTo === void 0 ? effectiveEnd !== void 0 : effectiveEnd !== void 0 && effectiveEnd < window.validTo;
+    if (!startsTooLate && !endsTooEarly) continue;
+    throw new IdentityEndpointValidityError({
+      endpoint: ref,
+      assertionWindow: {
+        validFrom: window.validFrom,
+        ...window.validTo === void 0 ? {} : { validTo: window.validTo }
+      },
+      endpointWindow
+    });
+  }
+}
+function windowOverlapSql(alias, lowerBoundary, upperBoundary) {
+  const column = (name) => sql`${sql.identifier(alias)}.${sql.identifier(name)}`;
+  return sql`
+    ${column("deleted_at")} IS NULL
+    AND ${column("valid_from")} <= ${upperBoundary}
+    AND (${column("valid_to")} IS NULL OR ${column("valid_to")} > ${lowerBoundary})
+  `;
+}
+async function loadIdentityWindowLedger(target, schema, graphId, requests, operationInstant, sameIdAcrossKinds) {
+  const activeRequests = requests.filter(
+    (request) => request.window.effective !== "empty"
+  );
+  if (activeRequests.length === 0) return { nodes: [], assertions: [] };
+  const referencesByKey = /* @__PURE__ */ new Map();
+  for (const request of activeRequests) {
+    for (const reference of request.references) {
+      referencesByKey.set(refKey(reference), reference);
+    }
+  }
+  const references = [...referencesByKey.values()];
+  const lowerBoundary = requireDefined(
+    activeRequests.map((request) => request.window.validFrom).toSorted()[0]
+  );
+  const upperBoundary = requireDefined(
+    activeRequests.map((request) => request.window.validTo ?? operationInstant).toSorted().at(-1)
+  );
+  const seedChunkSize = identityChunkSize(target, {
+    fixedParameters: 20,
+    maxItems: MAX_REFERENCE_CHUNK_SIZE,
+    parametersPerItem: 2
+  });
+  const rows = [];
+  for (const referenceChunk of chunk(references, seedChunkSize)) {
+    const seedRows = sql.join(
+      referenceChunk.map(
+        (reference) => sql`(${reference.kind}, ${reference.id})`
+      ),
+      sql`, `
+    );
+    const component = sameIdAcrossKinds === "fold" ? sql`
+          neighbor_modes(mode) AS (
+            VALUES ('assertion'), ('fold')
+          ),
+          component(kind, id) AS (
+            SELECT seed_kind, seed_id FROM seeds
+            UNION
+            SELECT CASE
+                     WHEN neighbor_modes.mode = 'fold' THEN folded.kind
+                     WHEN assertion.a_kind = component.kind AND assertion.a_id = component.id
+                       THEN assertion.b_kind
+                     ELSE assertion.a_kind
+                   END,
+                   CASE
+                     WHEN neighbor_modes.mode = 'fold' THEN folded.id
+                     WHEN assertion.a_kind = component.kind AND assertion.a_id = component.id
+                       THEN assertion.b_id
+                     ELSE assertion.a_id
+                   END
+            FROM component
+            JOIN neighbor_modes ON 1 = 1
+            LEFT JOIN ${schema.identityAssertionsTable} assertion
+              ON neighbor_modes.mode = 'assertion'
+             AND assertion.graph_id = ${graphId}
+             AND assertion.rel = 'same'
+             AND ${windowOverlapSql("assertion", lowerBoundary, upperBoundary)}
+             AND ((assertion.a_kind = component.kind AND assertion.a_id = component.id)
+               OR (assertion.b_kind = component.kind AND assertion.b_id = component.id))
+            LEFT JOIN ${schema.nodesTable} folded
+              ON neighbor_modes.mode = 'fold'
+             AND folded.graph_id = ${graphId}
+             AND folded.id = component.id
+            WHERE assertion.id IS NOT NULL OR folded.id IS NOT NULL
+          )
+        ` : sql`
+        component(kind, id) AS (
+          SELECT seed_kind, seed_id FROM seeds
+          UNION
+          SELECT CASE
+                   WHEN assertion.a_kind = component.kind AND assertion.a_id = component.id
+                     THEN assertion.b_kind
+                   ELSE assertion.a_kind
+                 END,
+                 CASE
+                   WHEN assertion.a_kind = component.kind AND assertion.a_id = component.id
+                     THEN assertion.b_id
+                   ELSE assertion.a_id
+                 END
+          FROM component
+          JOIN ${schema.identityAssertionsTable} assertion
+            ON assertion.graph_id = ${graphId}
+           AND assertion.rel = 'same'
+           AND ${windowOverlapSql("assertion", lowerBoundary, upperBoundary)}
+           AND ((assertion.a_kind = component.kind AND assertion.a_id = component.id)
+             OR (assertion.b_kind = component.kind AND assertion.b_id = component.id))
+        )
+      `;
+    rows.push(
+      ...await target.execute(
+        asCompiledRowsSql(sql`
+          WITH RECURSIVE
+          seeds(seed_kind, seed_id) AS (VALUES ${seedRows}),
+          ${component},
+          selected_assertions AS (
+            SELECT DISTINCT assertion.*
+            FROM ${schema.identityAssertionsTable} assertion
+            JOIN component
+              ON (assertion.a_kind = component.kind AND assertion.a_id = component.id)
+              OR (assertion.b_kind = component.kind AND assertion.b_id = component.id)
+            WHERE assertion.graph_id = ${graphId}
+              AND ${windowOverlapSql("assertion", lowerBoundary, upperBoundary)}
+          )
+          SELECT 'assertion' AS row_type, ${IDENTITY_ASSERTION_COLUMNS},
+                 NULL AS node_kind, NULL AS node_id,
+                 NULL AS node_created_at, NULL AS node_deleted_at
+          FROM selected_assertions
+          UNION ALL
+          SELECT 'node', NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL,
+                 NULL, NULL, NULL, NULL, NULL,
+                 node.kind, node.id, node.created_at, node.deleted_at
+          FROM ${schema.nodesTable} node
+          JOIN component ON component.kind = node.kind AND component.id = node.id
+          WHERE node.graph_id = ${graphId}
+        `)
+      )
+    );
+  }
+  const nodesByKey = /* @__PURE__ */ new Map();
+  const assertionsById = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    if (row.row_type === "assertion") {
+      const assertion = normalizeIdentityAssertionRow(row);
+      assertionsById.set(assertion.id, assertion);
+      continue;
+    }
+    if (typeof row.node_kind !== "string" || typeof row.node_id !== "string")
+      continue;
+    const createdAt = canonicalEndpointTimestamp(row.node_created_at);
+    if (createdAt === void 0) continue;
+    const deletedAt = canonicalEndpointTimestamp(row.node_deleted_at);
+    const node = {
+      ref: { kind: row.node_kind, id: row.node_id },
+      createdAt,
+      ...deletedAt === void 0 ? {} : { deletedAt }
+    };
+    nodesByKey.set(refKey(node.ref), node);
+  }
+  return {
+    nodes: [...nodesByKey.values()],
+    assertions: [...assertionsById.values()]
+  };
+}
+function identityWindowCheckpoints(window, operationInstant, nodes, assertions) {
+  if (window.effective === "empty") return [];
+  const checkpoints = /* @__PURE__ */ new Set([window.validFrom]);
+  if (window.validTo === void 0) checkpoints.add(operationInstant);
+  for (const row of [...assertions, ...nodes]) {
+    for (const value of [
+      "valid_from" in row ? row.valid_from : void 0,
+      "valid_to" in row ? row.valid_to : void 0,
+      "createdAt" in row ? row.createdAt : void 0,
+      "deletedAt" in row ? row.deletedAt : void 0
+    ]) {
+      const boundary = canonicalEndpointTimestamp(value);
+      if (boundary === void 0 || boundary < window.validFrom) continue;
+      if (window.validTo !== void 0 && boundary >= window.validTo) continue;
+      if (boundary > operationInstant) continue;
+      checkpoints.add(boundary);
+    }
+  }
+  return [...checkpoints].toSorted();
+}
+function validateRelationAgainstLedger(ctx, nodes, assertions, relation, operation, a, b, window, operationInstant) {
+  const checkpoints = identityWindowCheckpoints(
+    window,
+    operationInstant,
+    nodes,
+    assertions
+  );
+  for (const instant of checkpoints) {
+    const structuralNodes = nodes.map((node) => node.ref);
+    const activeAssertions = assertions.filter(
+      (assertion) => assertion.deleted_at === void 0 && assertion.valid_from <= instant && (assertion.valid_to === void 0 || assertion.valid_to > instant)
+    );
+    const activeFoldReferences = nodes.filter(
+      (node) => node.createdAt <= instant && (node.deletedAt === void 0 || node.deletedAt > instant)
+    ).map((node) => node.ref);
+    const foldAssertions = [];
+    if (ctx.sameIdAcrossKinds === "fold") {
+      const byId = /* @__PURE__ */ new Map();
+      for (const reference of activeFoldReferences) {
+        const sameId = byId.get(reference.id) ?? [];
+        sameId.push(reference);
+        byId.set(reference.id, sameId);
+      }
+      for (const sameId of byId.values()) {
+        const first = sameId[0];
+        if (first === void 0) continue;
+        for (const other of sameId.slice(1)) {
+          foldAssertions.push({
+            rel: "same",
+            a_kind: first.kind,
+            a_id: first.id,
+            b_kind: other.kind,
+            b_id: other.id
+          });
+        }
+      }
+    }
+    const components = buildComponents(
+      structuralNodes,
+      [...activeAssertions, ...foldAssertions],
+      "ignore"
+    );
+    const aClass = components.get(refKey(a)) ?? [];
+    const bClass = components.get(refKey(b)) ?? [];
+    if (relation === "different") {
+      if (!containsRef(aClass, b)) continue;
+      throw new IdentityContradictionError({
+        operation,
+        a,
+        b,
+        reason: "same-class"
+      });
+    }
+    const different = spanningDifferentAssertion(
+      activeAssertions,
+      aClass,
+      bClass
+    );
+    if (different !== void 0) {
+      throw new IdentityContradictionError({
+        operation,
+        a,
+        b,
+        reason: "different-assertion",
+        conflictingAssertionId: different.id
+      });
+    }
+    const disjointKinds = classHasDisjointKinds(ctx.registry, aClass, bClass);
+    if (disjointKinds === void 0) continue;
+    throw new IdentityContradictionError({
+      operation,
+      a,
+      b,
+      reason: "disjoint-kinds",
+      conflictingKinds: disjointKinds
+    });
+  }
+}
+async function createIdentityWindowValidator(ctx, target, requests, operationInstant, ignoredAssertionIds = /* @__PURE__ */ new Set()) {
+  const ledger = await loadIdentityWindowLedger(
+    target,
+    ctx.schema,
+    ctx.graphId,
+    requests,
+    operationInstant,
+    ctx.sameIdAcrossKinds
+  );
+  if (ignoredAssertionIds.size > 0) {
+    const retained = ledger.assertions.filter(
+      (assertion) => !ignoredAssertionIds.has(assertion.id)
+    );
+    ledger.assertions.splice(0, ledger.assertions.length, ...retained);
+  }
+  return {
+    validate(relation, operation, a, b, window) {
+      validateRelationAgainstLedger(
+        ctx,
+        ledger.nodes,
+        ledger.assertions,
+        relation,
+        operation,
+        a,
+        b,
+        window,
+        operationInstant
+      );
+    },
+    record(assertion) {
+      ledger.assertions.push(assertion);
+    }
+  };
+}
+async function validateRelationThroughoutIdentityWindow(ctx, target, relation, operation, a, b, window, operationInstant) {
+  const validator = await createIdentityWindowValidator(
+    ctx,
+    target,
+    [{ references: [a, b], window }],
+    operationInstant
+  );
+  validator.validate(relation, operation, a, b, window);
+}
 function nullableAssertionValue(value) {
   return value === void 0 ? sql`NULL` : sql`${value}`;
 }
@@ -1903,34 +2304,107 @@ async function mergeCurrentClasses(target, schema, graphId, a, b) {
   }
   await replaceSeparationForMembers(target, schema, graphId, fusedMembers);
 }
-async function assertPair(ctx, target, relation, firstInput, secondInput, touch) {
+async function assertPair(ctx, target, relation, firstInput, secondInput, touch, windowInput, operationInstant, windowValidator) {
   const first = registeredPlainRef(ctx, firstInput);
   const second = registeredPlainRef(ctx, secondInput);
   if (refKey(first) === refKey(second)) throw selfAssertionError(relation);
   const [a, b] = normalizePair(first, second);
-  await Promise.all([
-    requireLiveEndpoint(target, ctx.graphId, a),
-    requireLiveEndpoint(target, ctx.graphId, b)
-  ]);
-  const existing = await currentAssertionForPair(
+  if (windowInput === void 0) {
+    const current = await currentAssertionForPair(
+      target,
+      ctx.schema,
+      ctx.graphId,
+      relation,
+      a,
+      b
+    );
+    if (current !== void 0) {
+      return assertionResult(publicAssertion(current), "existing");
+    }
+    await Promise.all([
+      requireLiveEndpoint(target, ctx.graphId, a),
+      requireLiveEndpoint(target, ctx.graphId, b)
+    ]);
+    await validateCurrentRelation(
+      ctx,
+      target,
+      relation,
+      relation === "same" ? "assertSame" : "assertDifferent",
+      a,
+      b
+    );
+    const row2 = await insertAssertion(
+      target,
+      ctx.schema,
+      ctx.graphId,
+      relation,
+      a,
+      b,
+      operationInstant,
+      touch
+    );
+    windowValidator?.record(row2);
+    if (relation === "same") {
+      await mergeCurrentClasses(target, ctx.schema, ctx.graphId, a, b);
+    } else {
+      await replaceSeparationForReferences(target, ctx.schema, ctx.graphId, [
+        a,
+        b
+      ]);
+    }
+    return assertionResult(publicAssertion(row2), "created");
+  }
+  const window = resolveIdentityValidityWindow(windowInput, operationInstant);
+  await requireEndpointsCoverIdentityWindow(
+    target,
+    ctx.graphId,
+    [a, b],
+    window
+  );
+  const existing = await assertionForExactWindow(
     target,
     ctx.schema,
     ctx.graphId,
     relation,
     a,
-    b
+    b,
+    window
   );
   if (existing !== void 0) {
     return assertionResult(publicAssertion(existing), "existing");
   }
-  await validateCurrentRelation(
-    ctx,
-    target,
-    relation,
-    relation === "same" ? "assertSame" : "assertDifferent",
-    a,
-    b
-  );
+  if (window.effective === "current") {
+    const current = await currentAssertionForPair(
+      target,
+      ctx.schema,
+      ctx.graphId,
+      relation,
+      a,
+      b
+    );
+    if (current !== void 0) {
+      throw new IdentityValidityWindowError({
+        reason: "overlapping-open-window",
+        validFrom: window.validFrom,
+        operationInstant
+      });
+    }
+  }
+  const operation = relation === "same" ? "assertSame" : "assertDifferent";
+  if (windowValidator === void 0) {
+    await validateRelationThroughoutIdentityWindow(
+      ctx,
+      target,
+      relation,
+      operation,
+      a,
+      b,
+      window,
+      operationInstant
+    );
+  } else {
+    windowValidator.validate(relation, operation, a, b, window);
+  }
   const row = await insertAssertion(
     target,
     ctx.schema,
@@ -1938,9 +2412,17 @@ async function assertPair(ctx, target, relation, firstInput, secondInput, touch)
     relation,
     a,
     b,
-    nowIso(),
-    touch
+    operationInstant,
+    touch,
+    {
+      validFrom: window.validFrom,
+      ...window.validTo === void 0 ? {} : { validTo: window.validTo }
+    }
   );
+  windowValidator?.record(row);
+  if (window.effective !== "current") {
+    return assertionResult(publicAssertion(row), "created");
+  }
   if (relation === "same") {
     await mergeCurrentClasses(target, ctx.schema, ctx.graphId, a, b);
   } else {
@@ -2145,6 +2627,40 @@ async function bulkAssertPairs(ctx, target, relation, pairs, touch) {
   }
   return results;
 }
+async function bulkAssertWindowedPairs(ctx, target, relation, pairs, touch, operationInstant) {
+  const windowRequests = pairs.map((pair) => {
+    const first = registeredPlainRef(ctx, pair.a);
+    const second = registeredPlainRef(ctx, pair.b);
+    return {
+      references: normalizePair(first, second),
+      window: resolveIdentityValidityWindow(pair, operationInstant)
+    };
+  });
+  const windowValidator = await createIdentityWindowValidator(
+    ctx,
+    target,
+    windowRequests,
+    operationInstant
+  );
+  const results = [];
+  for (const pair of pairs) {
+    const window = hasExplicitIdentityValidityWindow(pair) ? pair : void 0;
+    results.push(
+      await assertPair(
+        ctx,
+        target,
+        relation,
+        pair.a,
+        pair.b,
+        touch,
+        window,
+        operationInstant,
+        windowValidator
+      )
+    );
+  }
+  return results;
+}
 async function findCurrentAssertionById(target, schema, graphId, id) {
   const rows = await target.execute(
     asCompiledRowsSql(sql`
@@ -2183,7 +2699,7 @@ async function retractById(ctx, target, id, touch) {
   touch(ctx.graphId, id, ended);
   return ended;
 }
-async function retractByIds(ctx, target, ids, touch) {
+async function retractCurrentAssertions(ctx, target, ids, touch, resolveValidTo) {
   const uniqueIds = [...new Set(ids)];
   if (uniqueIds.length === 0) return [];
   const current = [];
@@ -2210,11 +2726,11 @@ async function retractByIds(ctx, target, ids, touch) {
     current.push(...rows.map((row) => normalizeIdentityAssertionRow(row)));
   }
   if (current.length === 0) return [];
-  const now = nowIso();
+  const operationInstant = nowIso();
   const byValidTo = /* @__PURE__ */ new Map();
   const endedById = /* @__PURE__ */ new Map();
   for (const row of current) {
-    const validTo = clampValidTo(now, row.valid_from);
+    const validTo = resolveValidTo(row, operationInstant);
     endedById.set(row.id, validTo);
     const group = byValidTo.get(validTo) ?? [];
     group.push(row.id);
@@ -2235,7 +2751,7 @@ async function retractByIds(ctx, target, ids, touch) {
         target,
         sql`
           UPDATE ${ctx.schema.identityAssertionsTable}
-          SET valid_to = ${validTo}, updated_at = ${now}
+          SET valid_to = ${validTo}, updated_at = ${operationInstant}
           WHERE graph_id = ${ctx.graphId}
             AND id IN (${placeholders})
             AND valid_to IS NULL
@@ -2251,7 +2767,7 @@ async function retractByIds(ctx, target, ids, touch) {
       {
         ...row,
         valid_to: requireDefined(endedById.get(row.id)),
-        updated_at: now
+        updated_at: operationInstant
       }
     ];
   });
@@ -2260,6 +2776,44 @@ async function retractByIds(ctx, target, ids, touch) {
   }
   return ended;
 }
+async function retractByIds(ctx, target, ids, touch) {
+  return retractCurrentAssertions(
+    ctx,
+    target,
+    ids,
+    touch,
+    (row, operationInstant) => clampValidTo(operationInstant, row.valid_from)
+  );
+}
+async function retractPlannedAssertions(ctx, target, retractions, touch) {
+  const retractionById = new Map(
+    retractions.map((retraction) => [retraction.id, retraction])
+  );
+  return retractCurrentAssertions(
+    ctx,
+    target,
+    retractions.map((retraction) => retraction.id),
+    touch,
+    (row, operationInstant) => {
+      const retraction = requireDefined(retractionById.get(row.id));
+      if (retraction.validTo === void 0) {
+        throw new ConfigurationError(
+          `Identity merge retraction ${retraction.id} is missing validTo.`,
+          {
+            code: "IDENTITY_MERGE_RETRACTION_REQUIRES_END",
+            assertionId: retraction.id
+          }
+        );
+      }
+      return requireDefined(
+        resolveIdentityValidityWindow(
+          { validFrom: row.valid_from, validTo: retraction.validTo },
+          operationInstant
+        ).validTo
+      );
+    }
+  );
+}
 async function runIdentityMutation(ctx, fn) {
   let touched = false;
   return runInWriteTransaction(
@@ -2421,29 +2975,65 @@ function partitionRetractedEndpoints(retracted) {
 function createIdentityFacade(ctx) {
   return {
     ...createIdentityReadFacade(ctx),
-    assertSame(a, b) {
-      return runIdentityMutation(
-        ctx,
-        (target, touch) => assertPair(ctx, target, "same", a, b, touch)
-      );
+    assertSame(a, b, window) {
+      return runIdentityMutation(ctx, (target, touch) => {
+        const operationInstant = nowIso();
+        return assertPair(
+          ctx,
+          target,
+          "same",
+          a,
+          b,
+          touch,
+          hasExplicitIdentityValidityWindow(window) ? window : void 0,
+          operationInstant
+        );
+      });
     },
-    assertDifferent(a, b) {
-      return runIdentityMutation(
-        ctx,
-        (target, touch) => assertPair(ctx, target, "different", a, b, touch)
-      );
+    assertDifferent(a, b, window) {
+      return runIdentityMutation(ctx, (target, touch) => {
+        const operationInstant = nowIso();
+        return assertPair(
+          ctx,
+          target,
+          "different",
+          a,
+          b,
+          touch,
+          hasExplicitIdentityValidityWindow(window) ? window : void 0,
+          operationInstant
+        );
+      });
     },
     bulkAssertSame(pairs) {
-      return runIdentityMutation(
-        ctx,
-        (target, touch) => bulkAssertPairs(ctx, target, "same", pairs, touch)
-      );
+      return runIdentityMutation(ctx, (target, touch) => {
+        if (!pairs.some((pair) => hasExplicitIdentityValidityWindow(pair))) {
+          return bulkAssertPairs(ctx, target, "same", pairs, touch);
+        }
+        return bulkAssertWindowedPairs(
+          ctx,
+          target,
+          "same",
+          pairs,
+          touch,
+          nowIso()
+        );
+      });
     },
     bulkAssertDifferent(pairs) {
-      return runIdentityMutation(
-        ctx,
-        (target, touch) => bulkAssertPairs(ctx, target, "different", pairs, touch)
-      );
+      return runIdentityMutation(ctx, (target, touch) => {
+        if (!pairs.some((pair) => hasExplicitIdentityValidityWindow(pair))) {
+          return bulkAssertPairs(ctx, target, "different", pairs, touch);
+        }
+        return bulkAssertWindowedPairs(
+          ctx,
+          target,
+          "different",
+          pairs,
+          touch,
+          nowIso()
+        );
+      });
     },
     retractAssertion(id) {
       return runIdentityMutation(ctx, async (target, touch) => {
@@ -2560,7 +3150,7 @@ function transferShapeError(assertion, message, issue) {
     ]
   });
 }
-function validateTransferShape(ctx, assertion, mode) {
+function validateTransferShape(ctx, assertion, mode, operationInstant) {
   if (!ctx.registry.nodeKinds.has(assertion.a.kind) || !ctx.registry.nodeKinds.has(assertion.b.kind)) {
     throw transferShapeError(
       assertion,
@@ -2602,25 +3192,31 @@ function validateTransferShape(ctx, assertion, mode) {
       }
     );
   }
-  const now = nowIso();
-  if (assertion.validTo === void 0 && compareCodePoints(assertion.validFrom, now) > 0) {
-    throw transferShapeError(
-      assertion,
-      "Identity import cannot contain future-dated open assertions.",
+  let window;
+  try {
+    window = resolveIdentityValidityWindow(
       {
-        message: `Assertion ${assertion.id} validFrom is in the future`,
-        code: "IDENTITY_IMPORT_FUTURE_VALID_FROM"
-      }
+        validFrom: assertion.validFrom,
+        ...assertion.validTo === void 0 ? {} : { validTo: assertion.validTo }
+      },
+      operationInstant
     );
-  }
-  if (assertion.validTo !== void 0 && compareCodePoints(assertion.validTo, assertion.validFrom) < 0) {
+  } catch (error) {
+    if (!(error instanceof IdentityValidityWindowError)) throw error;
+    const issue = error.details.reason === "future-valid-from" ? {
+      code: "IDENTITY_IMPORT_FUTURE_VALID_FROM",
+      message: `Assertion ${assertion.id} validFrom is in the future`
+    } : error.details.reason === "future-valid-to" ? {
+      code: "IDENTITY_IMPORT_FUTURE_VALID_TO",
+      message: `Assertion ${assertion.id} validTo is in the future`
+    } : {
+      code: "IDENTITY_IMPORT_INVALID_WINDOW",
+      message: `Assertion ${assertion.id} validTo must not precede validFrom`
+    };
     throw transferShapeError(
       assertion,
-      "Identity assertion validity window is empty.",
-      {
-        message: `Assertion ${assertion.id} validTo must not precede validFrom`,
-        code: "IDENTITY_IMPORT_INVALID_WINDOW"
-      }
+      "Identity import contains an unsupported validity window.",
+      issue
     );
   }
   if (assertion.endedBy !== void 0) {
@@ -2646,17 +3242,7 @@ function validateTransferShape(ctx, assertion, mode) {
       );
     }
   }
-  if (assertion.validTo !== void 0 && compareCodePoints(assertion.validTo, now) > 0) {
-    throw transferShapeError(
-      assertion,
-      "Identity import cannot contain assertions that end in the future.",
-      {
-        message: `Assertion ${assertion.id} validTo is in the future`,
-        code: "IDENTITY_IMPORT_FUTURE_VALID_TO"
-      }
-    );
-  }
-  return normalized;
+  return { endpoints: normalized, window };
 }
 var IDENTITY_IMPORT_FAILED_ASSERTION = /* @__PURE__ */ Symbol(
   "typegraph.identity.failedAssertionId"
@@ -2679,13 +3265,14 @@ function rethrowTaggedWithAssertion(error, assertionId, progress) {
   }
   throw error;
 }
-async function importIdentityAssertionsIntoTarget(ctx, target, assertions, mode) {
+async function importIdentityAssertionsIntoTarget(ctx, target, assertions, mode, ignoredAssertionIds = /* @__PURE__ */ new Set()) {
   let created = 0;
   let skipped = 0;
   await withRecordedIdentityMutationTarget(target, async (rawTarget, touch) => {
+    const operationInstant = nowIso();
     const normalized = assertions.map((assertion) => ({
       assertion,
-      endpoints: validateTransferShape(ctx, assertion, mode)
+      ...validateTransferShape(ctx, assertion, mode, operationInstant)
     }));
     const existingById = await loadAssertionsByIds(
       rawTarget,
@@ -2740,7 +3327,17 @@ async function importIdentityAssertionsIntoTarget(ctx, target, assertions, mode)
     } catch (error) {
       attributeMissingEndpoint(error, true);
     }
-    for (const { assertion, endpoints } of normalized) {
+    const windowValidator = await createIdentityWindowValidator(
+      ctx,
+      rawTarget,
+      normalized.map(({ endpoints, window }) => ({
+        references: endpoints,
+        window
+      })),
+      operationInstant,
+      ignoredAssertionIds
+    );
+    for (const { assertion, endpoints, window } of normalized) {
       const [a, b] = endpoints;
       try {
         const sameId = existingById.get(assertion.id);
@@ -2759,73 +3356,102 @@ async function importIdentityAssertionsIntoTarget(ctx, target, assertions, mode)
             }
           );
         }
-        if (assertion.validTo !== void 0) {
-          const timestamp = assertion.validFrom;
-          const row = {
-            graph_id: ctx.graphId,
-            id: assertion.id,
-            rel: assertion.relation,
-            a_kind: a.kind,
-            a_id: a.id,
-            b_kind: b.kind,
-            b_id: b.id,
-            valid_from: assertion.validFrom,
-            valid_to: assertion.validTo,
-            created_at: timestamp,
-            updated_at: assertion.validTo,
-            deleted_at: void 0,
-            ended_by_kind: assertion.endedBy?.kind,
-            ended_by_id: assertion.endedBy?.id
-          };
-          await insertAssertionRows(rawTarget, ctx.schema, [row]);
-          touch(ctx.graphId, row.id, row);
-          existingById.set(row.id, row);
-          created += 1;
-          continue;
-        }
-        const existing = await currentAssertionForPair(
+        const exactWindow = await assertionForExactWindow(
           rawTarget,
           ctx.schema,
           ctx.graphId,
           assertion.relation,
           a,
-          b
+          b,
+          window
         );
-        if (existing !== void 0) {
+        if (exactWindow !== void 0) {
           skipped += 1;
           continue;
         }
-        await validateCurrentRelation(
-          ctx,
-          rawTarget,
-          assertion.relation,
-          "import",
-          a,
-          b
-        );
-        const inserted = await insertAssertion(
-          rawTarget,
-          ctx.schema,
-          ctx.graphId,
-          assertion.relation,
-          a,
-          b,
-          nowIso(),
-          touch,
-          { id: assertion.id, validFrom: assertion.validFrom }
-        );
-        existingById.set(inserted.id, inserted);
-        created += 1;
-        if (assertion.relation === "same") {
-          await mergeCurrentClasses(rawTarget, ctx.schema, ctx.graphId, a, b);
-        } else {
-          await replaceSeparationForReferences(
+        if (window.effective === "current") {
+          const current = await currentAssertionForPair(
+            rawTarget,
+            ctx.schema,
+            ctx.graphId,
+            assertion.relation,
+            a,
+            b
+          );
+          if (current !== void 0) {
+            skipped += 1;
+            continue;
+          }
+          await requireEndpointsCoverIdentityWindow(
+            rawTarget,
+            ctx.graphId,
+            [a, b],
+            window
+          );
+          windowValidator.validate(assertion.relation, "import", a, b, window);
+          await validateCurrentRelation(
+            ctx,
+            rawTarget,
+            assertion.relation,
+            "import",
+            a,
+            b
+          );
+          const inserted = await insertAssertion(
             rawTarget,
             ctx.schema,
             ctx.graphId,
-            [a, b]
+            assertion.relation,
+            a,
+            b,
+            operationInstant,
+            touch,
+            { id: assertion.id, validFrom: window.validFrom }
           );
+          existingById.set(inserted.id, inserted);
+          windowValidator.record(inserted);
+          created += 1;
+          if (assertion.relation === "same") {
+            await mergeCurrentClasses(rawTarget, ctx.schema, ctx.graphId, a, b);
+          } else {
+            await replaceSeparationForReferences(
+              rawTarget,
+              ctx.schema,
+              ctx.graphId,
+              [a, b]
+            );
+          }
+          continue;
         }
+        await requireEndpointsCoverIdentityWindow(
+          rawTarget,
+          ctx.graphId,
+          [a, b],
+          window
+        );
+        windowValidator.validate(assertion.relation, "import", a, b, window);
+        const timestamp = window.validFrom;
+        const row = {
+          graph_id: ctx.graphId,
+          id: assertion.id,
+          rel: assertion.relation,
+          a_kind: a.kind,
+          a_id: a.id,
+          b_kind: b.kind,
+          b_id: b.id,
+          valid_from: window.validFrom,
+          valid_to: window.validTo,
+          created_at: timestamp,
+          updated_at: window.validTo ?? window.validFrom,
+          deleted_at: void 0,
+          ended_by_kind: assertion.endedBy?.kind,
+          ended_by_id: assertion.endedBy?.id
+        };
+        await insertAssertionRows(rawTarget, ctx.schema, [row]);
+        touch(ctx.graphId, row.id, row);
+        existingById.set(row.id, row);
+        windowValidator.record(row);
+        created += 1;
       } catch (error) {
         rethrowTaggedWithAssertion(error, assertion.id, { created, skipped });
       }
@@ -2833,12 +3459,17 @@ async function importIdentityAssertionsIntoTarget(ctx, target, assertions, mode)
   });
   return { created, skipped };
 }
-async function applyIdentityChangesForContext(ctx, retractionIds, assertions) {
-  if (retractionIds.length === 0 && assertions.length === 0) {
+async function applyIdentityChangesForContext(ctx, retractions, assertions) {
+  if (retractions.length === 0 && assertions.length === 0) {
     return { created: 0, retracted: 0 };
   }
   return runIdentityMutation(ctx, async (target, touch, markWritten) => {
-    const retracted = await retractByIds(ctx, target, retractionIds, touch);
+    const retracted = await retractPlannedAssertions(
+      ctx,
+      target,
+      retractions,
+      touch
+    );
     const { closureReferences, separationReferences } = partitionRetractedEndpoints(retracted);
     if (closureReferences.length > 0) {
       await replaceAffectedClosure(
@@ -2859,7 +3490,8 @@ async function applyIdentityChangesForContext(ctx, retractionIds, assertions) {
       ctx,
       target,
       assertions,
-      "state"
+      "archival",
+      new Set(retracted.map((assertion) => assertion.id))
     );
     if (summary.created > 0) markWritten();
     return { created: summary.created, retracted: retracted.length };
@@ -3310,6 +3942,34 @@ async function readNodeDeletionInstant(target, schema, graphId, ref) {
   const row = rows.at(0);
   return row === void 0 ? void 0 : optionalIdentityTimestamp(row.deleted_at);
 }
+async function requireNodeValidityEndCompatible(ctx, target, ref, validTo) {
+  const rows = await target.execute(
+    asCompiledRowsSql(sql`
+      SELECT ${IDENTITY_ASSERTION_COLUMNS}
+      FROM ${ctx.schema.identityAssertionsTable}
+      WHERE graph_id = ${ctx.graphId}
+        AND deleted_at IS NULL
+        AND (valid_to IS NULL OR valid_to > ${validTo})
+        AND (
+          (a_kind = ${ref.kind} AND a_id = ${ref.id})
+          OR (b_kind = ${ref.kind} AND b_id = ${ref.id})
+        )
+      ORDER BY id
+      LIMIT 1
+    `)
+  );
+  const row = rows.at(0);
+  if (row === void 0) return;
+  const assertion = normalizeIdentityAssertionRow(row);
+  throw new IdentityEndpointValidityError({
+    endpoint: ref,
+    assertionWindow: {
+      validFrom: assertion.valid_from,
+      ...assertion.valid_to === void 0 ? {} : { validTo: assertion.valid_to }
+    },
+    endpointWindow: { validTo }
+  });
+}
 async function detachIdentityForNode(ctx, target, ref, mode) {
   await lockIdentityGraph(target, ctx.graphId);
   await withRecordedIdentityMutationTarget(target, async (rawTarget, touch) => {
@@ -3388,6 +4048,6 @@ async function detachIdentityForNode(ctx, target, ref, mode) {
   });
 }
 
-export { IDENTITY_IMPORT_FAILED_ASSERTION, IDENTITY_IMPORT_PROGRESS, applyIdentityChangesForContext, assertAffectedIdentityClassesConsistent, createIdentityFacade, createIdentityReadFacade, createValidationError, deleteAssertionsTouchingKinds, detachIdentityForNode, encodeTupleKey, foldIdentityForCreatedNodes, hasAssertionsTouchingKinds, identityAssertionSemanticKey, identityReferenceKey, importIdentityAssertionsIntoTarget, liveNodeKindsSharingIds, loadAssertionsByIds, loadCurrentStructuralClasses, lockIdentityEnablementNodes, lockIdentityGraph, lockSchemaVersionForStoreWrite, normalizeIdentityPair, purgeAssertionsWithUnregisteredKinds, readIdentityAssertionPageAtTarget, readIdentityAssertionsForInterchange, rebuildIdentityClosureForContext, refKey, removeIdentityKindsForContext, runHookedWriteOperation, runInWriteTransaction, separationRebuildRequired, toTransferAssertion, validateEdgeProps, validateIdentityForContext, validateNodeProps, validateProps, withWriteTransactionSession, wrapZodError };
-//# sourceMappingURL=chunk-GF3KXUTW.js.map
-//# sourceMappingURL=chunk-GF3KXUTW.js.map
+export { IDENTITY_IMPORT_FAILED_ASSERTION, IDENTITY_IMPORT_PROGRESS, applyIdentityChangesForContext, assertAffectedIdentityClassesConsistent, createIdentityFacade, createIdentityReadFacade, createValidationError, deleteAssertionsTouchingKinds, detachIdentityForNode, encodeTupleKey, foldIdentityForCreatedNodes, forceWriteTransactionRevision, hasAssertionsTouchingKinds, identityAssertionSemanticKey, identityReferenceKey, identityValidityWindowsOverlap, importIdentityAssertionsIntoTarget, liveNodeKindsSharingIds, loadAssertionsByIds, loadCurrentStructuralClasses, lockIdentityEnablementNodes, lockIdentityGraph, lockSchemaVersionForStoreWrite, normalizeIdentityPair, purgeAssertionsWithUnregisteredKinds, readIdentityAssertionPageAtTarget, readIdentityAssertionsForInterchange, rebuildIdentityClosureForContext, refKey, removeIdentityKindsForContext, requireNodeValidityEndCompatible, runHookedWriteOperation, runInWriteTransaction, separationRebuildRequired, toTransferAssertion, validateEdgeProps, validateIdentityForContext, validateNodeProps, validateProps, withWriteTransactionSession, wrapZodError };
+//# sourceMappingURL=chunk-NNQ6A3RM.js.map
+//# sourceMappingURL=chunk-NNQ6A3RM.js.map