@nicia-ai/typegraph 0.46.1 → 0.47.0

package/dist/{chunk-S6PW7VV5.js → chunk-DJZTXBWY.js}

@@ -1,30 +1,31 @@
-import { createEdgeRowMapper, createNodeRowMapper, SQLITE_ROW_MAPPER_CONFIG, POSTGRES_ROW_MAPPER_CONFIG } from './chunk-NMWDXFPH.js';
-import { rowToNode, executeNodeBulkFindByIndex, executeNodeBulkFindByConstraint, executeNodeFindByConstraint, executeNodeBulkGetOrCreateByConstraint, executeNodeGetOrCreateByConstraint, executeNodeHardDelete, executeNodeDeleteBatch, executeNodeDelete, nodeUpsertDirtyCheck, executeNodeUpsertUpdate, executeNodeUpdateWhere, executeNodeUpdate, executeNodeCreateNoReturnBatch, executeNodeCreateBatch, executeNodeCreate, rowToEdge, checkCardinalityConstraint, edgeWriteNeedsConstraintFence, withAlreadyExistsTranslation, rowToNodeMeta, rowToEdgeMeta } from './chunk-L65OU2U3.js';
-import { storeRuntime, STORE_RUNTIME, TRANSACTION_RUNTIME, AUTO_REFRESH_STATISTICS_ROW_THRESHOLD, getEmbeddingFields, computeFulltextContent } from './chunk-M3WP7RQZ.js';
-import { loadAndMergeGraphExtensionDocument, serializeSchema, buildKindRegistry, ensureIdentitySchemaStorage, loadAndVerifyGraph, identitySchemaCommitPreflight, getSchemaChanges, requiresMigration, mergeGraphExtension, commitNewSchemaVersion, commitNewSchemaVersionWithPreflight, planRemovals, stripGraphExtension, applyDeprecatedKinds, identityKindCascadeNeeded, ensureSchema, loadActiveSchemaWithBootstrap, parseSerializedSchema, extensionKindNames, serializeSchemaProperties, buildGraphExtensionOntologyKeySet, compileTimeOntologyKey, commitNewSchemaVersionIfKindsEmpty, serializeIndexDeclaration } from './chunk-LGHCOKTT.js';
-import { getTypeName } from './chunk-JXA2ZP2Q.js';
-import { rebuildIdentityClosureForContext, loadCurrentStructuralClasses, loadAssertionsByIds, toTransferAssertion, liveNodeKindsSharingIds, createIdentityFacade, createIdentityReadFacade, runInWriteTransaction, validateIdentityForContext, removeIdentityKindsForContext, readIdentityAssertionsForInterchange, readIdentityAssertionPageAtTarget, lockIdentityGraph, foldIdentityForCreatedNodes, importIdentityAssertionsIntoTarget, assertAffectedIdentityClassesConsistent, applyIdentityChangesForContext, withWriteTransactionSession, lockSchemaVersionForStoreWrite, refKey, detachIdentityForNode, validateEdgeProps, runHookedWriteOperation, encodeTupleKey } from './chunk-GF3KXUTW.js';
-import { isParameterRef, resolveParameterValueType, fieldRef, compareStrings, buildFieldBuilderForTypeInfo, stringField, createFulltextAccessor, CURRENT_READ_INSTANT_PLACEHOLDER, withPinnedReadInstant, compareCodePoints, assertRevisionTrackableBackend, createRecordedBackend, createRecordedTransactionScope, readRecordedClock, ensureRevisionOrigin, withRecordedFlushObserver, recordedCaptureRequiresCallbackTransactionError, assertRecordedCaptureTransactionIsolation, lockRecordedGraphWrite, createGraphBackendProjection, generateId, assertCurrentRecordedSchema, baseField, objectField, arrayField, dateField, numberField, advanceRevisionClock, runInsertBatch, edgeInsertDispatch, runInsertBatchReturning, projectBackendMembers, sqlValueList, getNodeRowsByIds, getEdgeRowsByIds, compileKindFilter, runInsertNoReturn, currentReadInstant, compileTemporalFilter, closeRecordedHardDeletedKind, buildPredicateIndex, historicalIdentityPeerClassQuery, IDENTITY_PEER_CLASS_COLUMNS, compileFieldValue, recordedBindParamBudget, extractVectorSimilarityPredicates, extractFulltextMatchPredicates, currentReadInstantFor, extractTemporalOptions, compilePredicateExpression, getPredicatesForAlias, getFieldPointer, getNodeKindsForAlias, getHybridTargetAlias, throwHistoryUnsafeSqlAccess, throwRevisionTrackingUnsafeSqlAccess, compilePredicateClauses } from './chunk-NLI2AVEF.js';
+import { createEdgeRowMapper, createNodeRowMapper, SQLITE_ROW_MAPPER_CONFIG, POSTGRES_ROW_MAPPER_CONFIG, normalizeRowTimestamp, normalizeRequiredRowTimestamp } from './chunk-LEWHMOUY.js';
+import { rowToNode, executeNodeBulkFindByIndex, executeNodeBulkFindByConstraint, executeNodeFindByConstraint, executeNodeBulkGetOrCreateByConstraint, executeNodeGetOrCreateByConstraint, executeNodeHardDelete, executeNodeDeleteBatch, executeNodeDelete, nodeUpsertDirtyCheck, executeNodeUpsertUpdate, executeNodeUpdateWhere, executeNodeUpdate, executeNodeCreateNoReturnBatch, executeNodeCreateBatch, executeNodeCreate, rowToEdge, assertValidityEndMutation, assertClearValidToSupported, edgeWriteNeedsConstraintFence, withAlreadyExistsTranslation, rowToNodeMeta, rowToEdgeMeta, validityEndAfterMutation, checkCardinalityConstraint } from './chunk-SE6EGQSD.js';
+import { storeRuntime, STORE_RUNTIME, TRANSACTION_RUNTIME, AUTO_REFRESH_STATISTICS_ROW_THRESHOLD, getEmbeddingFields, computeFulltextContent } from './chunk-FNOMT74T.js';
+import { loadAndMergeGraphExtensionDocument, serializeSchema, buildKindRegistry, ensureIdentitySchemaStorage, loadAndVerifyGraph, identitySchemaCommitPreflight, getSchemaChanges, requiresMigration, mergeGraphExtension, commitNewSchemaVersion, commitNewSchemaVersionWithPreflight, planRemovals, stripGraphExtension, applyDeprecatedKinds, identityKindCascadeNeeded, ensureSchema, loadActiveSchemaWithBootstrap, parseSerializedSchema, extensionKindNames, serializeSchemaProperties, buildGraphExtensionOntologyKeySet, compileTimeOntologyKey, commitNewSchemaVersionIfKindsEmpty, serializeIndexDeclaration } from './chunk-XYBQI6LE.js';
+import { getTypeName } from './chunk-SHFBB23Q.js';
+import { rebuildIdentityClosureForContext, loadCurrentStructuralClasses, loadAssertionsByIds, toTransferAssertion, liveNodeKindsSharingIds, createIdentityFacade, createIdentityReadFacade, runInWriteTransaction, validateIdentityForContext, removeIdentityKindsForContext, readIdentityAssertionsForInterchange, readIdentityAssertionPageAtTarget, lockIdentityGraph, foldIdentityForCreatedNodes, importIdentityAssertionsIntoTarget, assertAffectedIdentityClassesConsistent, applyIdentityChangesForContext, withWriteTransactionSession, lockSchemaVersionForStoreWrite, refKey, requireNodeValidityEndCompatible, detachIdentityForNode, validateEdgeProps, runHookedWriteOperation, encodeTupleKey } from './chunk-NNQ6A3RM.js';
+import { isParameterRef, resolveParameterValueType, fieldRef, compareStrings, buildFieldBuilderForTypeInfo, stringField, createFulltextAccessor, CURRENT_READ_INSTANT_PLACEHOLDER, withPinnedReadInstant, compareCodePoints, assertRevisionTrackableBackend, createRecordedBackend, createRecordedTransactionScope, readRecordedClock, ensureRevisionOrigin, withRecordedFlushObserver, recordedCaptureRequiresCallbackTransactionError, assertRecordedCaptureTransactionIsolation, lockRecordedGraphWrite, createGraphBackendProjection, generateId, assertCurrentRecordedSchema, baseField, objectField, arrayField, dateField, numberField, advanceRevisionClock, runInsertBatch, edgeInsertDispatch, runInsertBatchReturning, projectBackendMembers, sqlValueList, getNodeRowsByIds, getEdgeRowsByIds, compileKindFilter, runInsertNoReturn, currentReadInstant, compileTemporalFilter, closeRecordedHardDeletedKind, buildPredicateIndex, historicalIdentityPeerClassQuery, IDENTITY_PEER_CLASS_COLUMNS, compileFieldValue, recordedBindParamBudget, extractVectorSimilarityPredicates, extractFulltextMatchPredicates, currentReadInstantFor, extractTemporalOptions, compilePredicateExpression, getPredicatesForAlias, getFieldPointer, getNodeKindsForAlias, getHybridTargetAlias, throwHistoryUnsafeSqlAccess, throwRevisionTrackingUnsafeSqlAccess, compilePredicateClauses } from './chunk-AVGUJWVX.js';
 import { canonicalEqual, sortedReplacer } from './chunk-JBQQ7THH.js';
-import { withRecordedRelationsPrecondition, chunk, postgresReadWriteRefusedSqlState, isMissingTableError, groupBy, postgresTemporaryTableUnavailableSqlState } from './chunk-JZUR7ZWE.js';
-import { createSqlSchema, requireSqlSchema, DEFAULT_SQL_SCHEMA, recordedReadSchemaFor, requireExternalRecordedReadSource, createRecordedReadBinding, vectorSlotKey, recordedReadSqlSchema, requireRecordedReadBinding, ALIAS_CTE_PREFIX, EMBEDDINGS_CTE_ALIAS, FULLTEXT_CTE_ALIAS, HYBRID_CANDIDATES_CTE_ALIAS } from './chunk-MSY7FSX4.js';
-import { runOptionallyInTransaction, createTransactionReadBackend, createBackendOverlay, rowPropsToObject, INTERNAL_TEMPORARY_WRITES } from './chunk-AKLS3BYZ.js';
-import { isKnownKind } from './chunk-775A4ZMN.js';
-import { validateEdgeEndpoints } from './chunk-WDGA7IYB.js';
-import { resolveReadCoordinate, withRecordedCoordinate, describeCoordinate, coordinateContext, nowIso, recordedInstantWallTime, asRecordedInstant, validateOptionalCanonicalIsoDate, assertOrderedValidityWindow, assertWritableValidityWindow, assertValidRecordedInstant, optionalRecordedInstantParts, preservesImmutableLowerBound, isCanonicalIsoDate, statedBoundMatchesStored } from './chunk-XL7SLCXS.js';
-import { generateIndexDDL } from './chunk-DCQVHAYQ.js';
-import { SYSTEM_INDEX_DECLARATIONS, resolveSystemIndexTableName, systemIndexName, resolveSystemIndexNames, generateSystemIndexDDL } from './chunk-CBTIUB76.js';
-import { NODE_META_KEYS, EDGE_META_KEYS } from './chunk-I5MOXA4H.js';
+import { withRecordedRelationsPrecondition, chunk, postgresReadWriteRefusedSqlState, isMissingTableError, groupBy, postgresTemporaryTableUnavailableSqlState, isPostgresConcurrentDdlRaceError } from './chunk-NAZ2RA4L.js';
+import { createSqlSchema, requireSqlSchema, DEFAULT_SQL_SCHEMA, recordedReadSchemaFor, requireExternalRecordedReadSource, createRecordedReadBinding, vectorSlotKey, recordedReadSqlSchema, requireRecordedReadBinding, ALIAS_CTE_PREFIX, EMBEDDINGS_CTE_ALIAS, FULLTEXT_CTE_ALIAS, HYBRID_CANDIDATES_CTE_ALIAS } from './chunk-NVY5CJFP.js';
+import { runOptionallyInTransaction, createTransactionReadBackend, createBackendOverlay, rowPropsToObject, INTERNAL_TEMPORARY_WRITES } from './chunk-SHSSRCFR.js';
+import { isKnownKind } from './chunk-HEV35TGT.js';
+import { validateEdgeEndpoints } from './chunk-GLHXM7C4.js';
+import { resolveReadCoordinate, withRecordedCoordinate, describeCoordinate, coordinateContext, recordedInstantWallTime, asRecordedInstant, assertValidRecordedInstant, optionalRecordedInstantParts } from './chunk-XY5OMOJD.js';
+import { nowIso, validateOptionalCanonicalIsoDate, assertOrderedValidityWindow, preservesImmutableLowerBound, assertWritableValidityWindow, isCanonicalIsoDate, statedBoundMatchesStored } from './chunk-NG2RB5WL.js';
+import { generateIndexDDL } from './chunk-KKBDXCLQ.js';
+import { SYSTEM_INDEX_DECLARATIONS, resolveSystemIndexTableName, systemIndexName, resolveSystemIndexNames, generateSystemIndexDDL } from './chunk-SDBBMD4N.js';
+import { NODE_META_KEYS, EDGE_META_KEYS } from './chunk-P6YLZTRE.js';
 import { sha256Hex, fnv1aBase36 } from './chunk-K34OPSJK.js';
 import { DEFAULT_PAGINATION_LIMIT, DEFAULT_STREAM_BATCH_SIZE, SQLITE_PATH_DELIMITER, PG_ARRAY_START, PG_ARRAY_END, PG_PATH_ELEMENT_SEPARATOR, MAX_PG_IDENTIFIER_LENGTH } from './chunk-2EBMPJBO.js';
-import { getDialect, assertVectorMinScore, assertApproximateMetricSupported, vectorScoreExpression, vectorMinScoreCondition } from './chunk-YDFDBE6D.js';
-import { isSqlPlaceholder, bindSqlValue, markAnnIndexScan, asCompiledSelectSql, isRawExecutable, renderSql, annIndexScanTypes, sql, asCompiledRowsSql, markForceCustomPlan, asCompiledStatementSql, asCompiledTemporaryStatementSql } from './chunk-PQBQG7IM.js';
+import { getDialect, assertVectorMinScore, assertApproximateMetricSupported, vectorScoreExpression, vectorMinScoreCondition } from './chunk-ZDKTPBGV.js';
+import { isSqlPlaceholder, bindSqlValue, markAnnIndexScan, asCompiledSelectSql, isRawExecutable, renderSql, annIndexScanTypes, sql, asCompiledRowsSql, markForceCustomPlan, asCompiledStatementSql, asCompiledTemporaryStatementSql } from './chunk-3DMMGT6S.js';
 import { createSchemaIntrospector } from './chunk-AMKPPFUO.js';
 import { resolveEmbeddingFields, resolveGraphVectorSlots, resolveDeclaredFulltextLanguage, getSearchableFields } from './chunk-PC2UBAUB.js';
-import { IncompatibleChangeError } from './chunk-T4XNKYXB.js';
+import { IncompatibleChangeError } from './chunk-D5R42W5D.js';
 import { META_EDGE_DISJOINT_WITH, META_EDGE_EQUIVALENT_TO, META_EDGE_SAME_AS, META_EDGE_SUB_CLASS_OF } from './chunk-JXXDZTMN.js';
-import { validateProjectionField } from './chunk-K5ELX2GT.js';
-import { ConfigurationError, UnsupportedPredicateError, ValidationError, KindNotFoundError, EndpointError, EagerMaterializationError, ContributionRebuildUnsupportedError, CompilerInvariantError, CardinalityError, DatabaseOperationError, EdgeNotFoundError, MigrationError, EDGE_IDENTITY_MISMATCH_CODE, UnsupportedBackendCapabilityError, EndpointNotFoundError, GraphAlgorithmConvergenceError, InvalidEdgeWeightError } from './chunk-J3WZ3FA2.js';
+import { validateProjectionField } from './chunk-XVWOYKIK.js';
+import { ConfigurationError, UnsupportedPredicateError, ValidationError, KindNotFoundError, EndpointError, EagerMaterializationError, ContributionRebuildUnsupportedError, CompilerInvariantError, CardinalityError, DatabaseOperationError, EdgeNotFoundError, MigrationError, EDGE_IDENTITY_MISMATCH_CODE, UnsupportedBackendCapabilityError, EndpointNotFoundError, GraphAlgorithmConvergenceError, InvalidEdgeWeightError } from './chunk-ZLONH2UD.js';
 import { jsonPointer, parseJsonPointer, resolveJsonPointer } from './chunk-FWJKWH6U.js';
 import { readOwnProperty, requireDefined, createDataKeyedBag, isInteropProbeKey, hasOwnKey, isPresent } from './chunk-DYATYRY4.js';
 
@@ -5279,9 +5280,6 @@ var RESERVED_EDGE_KEYS = /* @__PURE__ */ new Set([
   "toId",
   "meta"
 ]);
-function nullToUndefined2(value) {
-  return value === null ? void 0 : value;
-}
 function propsExcludingReserved(props, reservedKeys) {
   const kept = createDataKeyedBag();
   for (const [key, value] of Object.entries(props)) {
@@ -5297,14 +5295,25 @@ function buildSelectableNode(row, alias) {
   const propsRaw = row[`${alias}_props`];
   const rawProps = typeof propsRaw === "string" ? JSON.parse(propsRaw) : propsRaw ?? {};
   const version = row[`${alias}_version`];
-  const validFrom = nullToUndefined2(
-    row[`${alias}_valid_from`]
+  const validFrom = normalizeRowTimestamp(
+    row[`${alias}_valid_from`],
+    `${alias}_valid_from`
+  );
+  const validTo = normalizeRowTimestamp(
+    row[`${alias}_valid_to`],
+    `${alias}_valid_to`
+  );
+  const createdAt = normalizeRequiredRowTimestamp(
+    row[`${alias}_created_at`],
+    `${alias}_created_at`
+  );
+  const updatedAt = normalizeRequiredRowTimestamp(
+    row[`${alias}_updated_at`],
+    `${alias}_updated_at`
   );
-  const validTo = nullToUndefined2(row[`${alias}_valid_to`]);
-  const createdAt = row[`${alias}_created_at`];
-  const updatedAt = row[`${alias}_updated_at`];
-  const deletedAt = nullToUndefined2(
-    row[`${alias}_deleted_at`]
+  const deletedAt = normalizeRowTimestamp(
+    row[`${alias}_deleted_at`],
+    `${alias}_deleted_at`
   );
   const result = {
     id,
@@ -5338,14 +5347,25 @@ function buildSelectableEdge(row, alias) {
   const toId = row[`${alias}_to_id`];
   const propsRaw = row[`${alias}_props`];
   const rawProps = typeof propsRaw === "string" ? JSON.parse(propsRaw) : propsRaw ?? {};
-  const validFrom = nullToUndefined2(
-    row[`${alias}_valid_from`]
+  const validFrom = normalizeRowTimestamp(
+    row[`${alias}_valid_from`],
+    `${alias}_valid_from`
   );
-  const validTo = nullToUndefined2(row[`${alias}_valid_to`]);
-  const createdAt = row[`${alias}_created_at`];
-  const updatedAt = row[`${alias}_updated_at`];
-  const deletedAt = nullToUndefined2(
-    row[`${alias}_deleted_at`]
+  const validTo = normalizeRowTimestamp(
+    row[`${alias}_valid_to`],
+    `${alias}_valid_to`
+  );
+  const createdAt = normalizeRequiredRowTimestamp(
+    row[`${alias}_created_at`],
+    `${alias}_created_at`
+  );
+  const updatedAt = normalizeRequiredRowTimestamp(
+    row[`${alias}_updated_at`],
+    `${alias}_updated_at`
+  );
+  const deletedAt = normalizeRowTimestamp(
+    row[`${alias}_deleted_at`],
+    `${alias}_deleted_at`
   );
   const result = {
     id,
@@ -5915,6 +5935,14 @@ var MissingSelectiveFieldError = class extends Error {
     this.field = field2;
   }
 };
+function normalizeMetaValue(value, metaKey, alias) {
+  if (metaKey === "version") return nullToUndefined(value);
+  const field2 = `${alias}_${metaKey}`;
+  if (metaKey === "createdAt" || metaKey === "updatedAt") {
+    return normalizeRequiredRowTimestamp(value, field2);
+  }
+  return normalizeRowTimestamp(value, field2);
+}
 var SELECTABLE_ALIAS_MARKER = /* @__PURE__ */ Symbol("selectable_alias_marker");
 function isSelectableAliasObject(value) {
   return typeof value === "object" && value !== null && SELECTABLE_ALIAS_MARKER in value;
@@ -6080,7 +6108,11 @@ function buildRequiredAliasValue(row, plan) {
   if (plan.metaFields.length > 0) {
     const meta = createDataKeyedBag();
     for (const field2 of plan.metaFields) {
-      meta[field2.metaKey] = nullToUndefined(row[field2.outputName]);
+      meta[field2.metaKey] = normalizeMetaValue(
+        row[field2.outputName],
+        field2.metaKey,
+        plan.alias
+      );
     }
     base["meta"] = createGuardedProxy(meta, `${plan.alias}.meta`);
   }
@@ -13951,15 +13983,18 @@ function lowerBoundRequiresWrite(requested, stored) {
   return requestedValidFrom !== void 0 && !isCanonicalIsoDate(requestedValidFrom);
 }
 function upsertWindowChanges(requested, current) {
-  return lowerBoundRequiresWrite(requested, current.valid_from) || windowFieldChanges(requested?.validTo, current.valid_to);
+  return lowerBoundRequiresWrite(requested, current.valid_from) || requested?.clearValidTo === true && validityEndAfterMutation(requested, current.valid_to) !== current.valid_to || requested?.clearValidTo === true && requested.validTo !== void 0 || windowFieldChanges(requested?.validTo, current.valid_to);
 }
 function windowAfterUpsertCreate(requested) {
-  return { valid_from: requested.validFrom, valid_to: requested.validTo };
+  return {
+    valid_from: requested.validFrom,
+    valid_to: validityEndAfterMutation(requested, void 0)
+  };
 }
 function windowAfterUpsertUpdate(current, requested) {
   return {
     valid_from: current.valid_from,
-    valid_to: requested.validTo ?? current.valid_to
+    valid_to: validityEndAfterMutation(requested, current.valid_to)
   };
 }
 function shouldCoalesceUpsert(existing, options, runDirtyCheck) {
@@ -13998,6 +14033,7 @@ function buildCreateEdgeInput(kind, from, to, props, options) {
 function buildUpdateEdgeInput(kind, id, props, options) {
   const input = { id, identity: { kind }, props };
   if (options?.validTo !== void 0) input.validTo = options.validTo;
+  if (options?.clearValidTo === true) input.clearValidTo = true;
   return input;
 }
 function buildUpsertUpdateEdgeInput(kind, id, from, to, props, options) {
@@ -14014,6 +14050,7 @@ function buildUpsertUpdateEdgeInput(kind, id, from, to, props, options) {
   };
   if (options?.validFrom !== void 0) input.validFrom = options.validFrom;
   if (options?.validTo !== void 0) input.validTo = options.validTo;
+  if (options?.clearValidTo === true) input.clearValidTo = true;
   return input;
 }
 function endpointKey(endpointKind, id) {
@@ -14267,6 +14304,16 @@ function createEdgeCollection(config) {
     },
     async bulkUpsertById(items) {
       if (items.length === 0) return [];
+      for (const item of items) {
+        assertValidityEndMutation(item, {
+          entityType: "edge",
+          kind,
+          id: item.id
+        });
+        if (item.clearValidTo === true) {
+          assertClearValidToSupported(backend, "edge");
+        }
+      }
       const upsertAll = async (target) => {
         const ids = items.map((item) => item.id);
         const existingMap = await getEdgeRowsByIds(target, graphId, ids);
@@ -14439,6 +14486,10 @@ function createEdgeCollection(config) {
       return result === void 0 ? void 0 : narrowEdge(result);
     },
     async getOrCreateByEndpoints(from, to, props, options) {
+      assertValidityEndMutation(options ?? {}, {
+        entityType: "edge",
+        kind
+      });
       const getOrCreateOptions = {
         ...options?.matchOn !== void 0 && {
           matchOn: options.matchOn
@@ -14449,7 +14500,11 @@ function createEdgeCollection(config) {
         ...options?.validFrom !== void 0 && {
           validFrom: options.validFrom
         },
-        ...options?.validTo !== void 0 && { validTo: options.validTo }
+        ...options?.validTo !== void 0 && { validTo: options.validTo },
+        ...options?.clearValidTo === true && { clearValidTo: true },
+        ...options?.onImmutableLowerBound !== void 0 && {
+          onImmutableLowerBound: options.onImmutableLowerBound
+        }
       };
       const result = await config.executeGetOrCreateByEndpoints(
         kind,
@@ -14465,6 +14520,12 @@ function createEdgeCollection(config) {
     },
     async bulkGetOrCreateByEndpoints(items, options) {
       if (items.length === 0) return [];
+      for (const item of items) {
+        assertValidityEndMutation(item, {
+          entityType: "edge",
+          kind
+        });
+      }
       const mappedItems = items.map((item) => ({
         fromKind: item.from.kind,
         fromId: item.from.id,
@@ -14472,7 +14533,11 @@ function createEdgeCollection(config) {
         toId: item.to.id,
         props: item.props,
         ...item.validFrom !== void 0 && { validFrom: item.validFrom },
-        ...item.validTo !== void 0 && { validTo: item.validTo }
+        ...item.validTo !== void 0 && { validTo: item.validTo },
+        ...item.clearValidTo === true && { clearValidTo: true },
+        ...item.onImmutableLowerBound !== void 0 && {
+          onImmutableLowerBound: item.onImmutableLowerBound
+        }
       }));
       const getOrCreateOptions = {
         ...options?.matchOn !== void 0 && {
@@ -14549,12 +14614,14 @@ function buildCreateInput(kind, props, options) {
 function buildUpdateInput(kind, id, props, options) {
   const input = { kind, id, props };
   if (options?.validTo !== void 0) input.validTo = options.validTo;
+  if (options?.clearValidTo === true) input.clearValidTo = true;
   return input;
 }
 function buildUpsertUpdateInput(kind, id, props, options) {
   const input = { kind, id, props };
   if (options?.validFrom !== void 0) input.validFrom = options.validFrom;
   if (options?.validTo !== void 0) input.validTo = options.validTo;
+  if (options?.clearValidTo === true) input.clearValidTo = true;
   if (options?.onImmutableLowerBound !== void 0) {
     input.onImmutableLowerBound = options.onImmutableLowerBound;
   }
@@ -14747,6 +14814,14 @@ function createNodeCollection(config) {
       return this.upsertByIdFromRecord(id, props, options);
     },
     async upsertByIdFromRecord(id, data, options) {
+      assertValidityEndMutation(options ?? {}, {
+        entityType: "node",
+        kind,
+        id
+      });
+      if (options?.clearValidTo === true) {
+        assertClearValidToSupported(backend, "node");
+      }
       const existing = await backend.getNode(graphId, kind, id);
       const coalesces = (row) => {
         const runDirtyCheck = config.upsertDirtyCheck && (() => requireDefined(config.upsertDirtyCheck)(
@@ -14796,6 +14871,16 @@ function createNodeCollection(config) {
     },
     async bulkUpsertById(items) {
       if (items.length === 0) return [];
+      for (const item of items) {
+        assertValidityEndMutation(item, {
+          entityType: "node",
+          kind,
+          id: item.id
+        });
+        if (item.clearValidTo === true) {
+          assertClearValidToSupported(backend, "node");
+        }
+      }
       const upsertAll = async (target) => {
         const ids = items.map((item) => item.id);
         const existingMap = /* @__PURE__ */ new Map();
@@ -15243,6 +15328,7 @@ async function runBucketedMaterialization(items, options, bucketKey, runOne) {
 var CLAIM_LEASE_MS = 15 * 6e4;
 var CLAIM_RETRY_DELAY_MS = 200;
 var CLAIM_WAIT_TIMEOUT_MS = CLAIM_LEASE_MS + 6e4;
+var TRIGRAM_EXTENSION_DDL = "CREATE EXTENSION IF NOT EXISTS pg_trgm;";
 var INDEX_DIALECT_BEHAVIOR = {
   postgres: {
     concurrentBuilds: true,
@@ -15263,6 +15349,19 @@ function delay(ms) {
     setTimeout(resolve, ms);
   });
 }
+async function ensureTrigramExtension(backend) {
+  if (backend.ensureTrigramExtension !== void 0) {
+    await backend.ensureTrigramExtension();
+    return;
+  }
+  const executeDdl = requireDefined(backend.executeDdl);
+  try {
+    await executeDdl(TRIGRAM_EXTENSION_DDL);
+  } catch (error) {
+    if (!isPostgresConcurrentDdlRaceError(error)) throw error;
+    await executeDdl(TRIGRAM_EXTENSION_DDL);
+  }
+}
 async function materializeIndexes(context, options = {}) {
   const { graph, graphId, backend, schemaVersion } = context;
   assertBackendSupportsIndexMaterialization(
@@ -15402,9 +15501,7 @@ async function materializeRelationalIndex(declaration, backend, dialect, ddlOpti
     driftLabel: "Index",
     run: async () => {
       if (declaration.method === "trigram") {
-        await requireDefined(backend.executeDdl)(
-          "CREATE EXTENSION IF NOT EXISTS pg_trgm;"
-        );
+        await ensureTrigramExtension(backend);
       }
       await requireDefined(backend.executeDdl)(ddl);
     },
@@ -16776,6 +16873,11 @@ function edgeUpsertDirtyCheck(ctx, kind, id, existingProps, inputProps) {
 }
 async function performEdgeUpdate(ctx, input, target, options) {
   const id = input.id;
+  assertValidityEndMutation(input, {
+    entityType: "edge",
+    kind: input.identity.kind,
+    id
+  });
   const existing = await target.getEdge(ctx.graphId, id);
   if (!existing || !options?.clearDeleted && existing.deleted_at) {
     throw new EdgeNotFoundError(input.identity.kind, id);
@@ -16787,14 +16889,39 @@ async function performEdgeUpdate(ctx, input, target, options) {
     "update"
   );
   const { validatedProps } = resolveEdgeUpdateProps(ctx, existing, input.props);
-  const validFrom = validateOptionalCanonicalIsoDate(
+  const statedValidFrom = validateOptionalCanonicalIsoDate(
     input.validFrom,
     "validFrom"
   );
+  const preservesLiveLowerBound = options?.clearDeleted !== true && preservesImmutableLowerBound(input.onImmutableLowerBound);
+  const appliedValidFrom = preservesLiveLowerBound ? void 0 : statedValidFrom;
   const validTo = validateOptionalCanonicalIsoDate(input.validTo, "validTo");
+  const effectiveValidTo = options?.clearDeleted === true && appliedValidFrom !== void 0 ? validTo : validityEndAfterMutation(
+    input.clearValidTo === true ? { clearValidTo: true } : validTo === void 0 ? {} : { validTo },
+    existing.valid_to
+  );
+  const cardinality = edgeCardinality(ctx, input.identity.kind);
+  const reentersLivePopulation = options?.clearDeleted === true && existing.deleted_at !== void 0;
+  const reentersActivePopulation = cardinality === "oneActive" && effectiveValidTo === void 0 && (existing.deleted_at !== void 0 || existing.valid_to !== void 0);
+  if (reentersLivePopulation || reentersActivePopulation) {
+    await checkCardinalityConstraint(
+      {
+        graphId: ctx.graphId,
+        registry: ctx.registry,
+        backend: target
+      },
+      input.identity.kind,
+      cardinality,
+      existing.from_kind,
+      existing.from_id,
+      existing.to_kind,
+      existing.to_id,
+      effectiveValidTo
+    );
+  }
   const windowVerdict = assertWritableValidityWindow(
     `edge "${id}"`,
-    validFrom,
+    appliedValidFrom,
     {
       effectiveValidFrom: existing.valid_from,
       appliesStatedValidFrom: options?.clearDeleted === true,
@@ -16828,23 +16955,30 @@ async function performEdgeUpdate(ctx, input, target, options) {
   if (input.identity.toId !== void 0) {
     updateParams.toId = input.identity.toId;
   }
-  if (validFrom !== void 0) updateParams.validFrom = validFrom;
-  if (validTo !== void 0) updateParams.validTo = validTo;
+  if (appliedValidFrom !== void 0) {
+    updateParams.validFrom = appliedValidFrom;
+  }
+  if (reentersActivePopulation && existing.valid_to !== void 0) {
+    updateParams.expectedValidTo = existing.valid_to;
+  }
   if (options?.clearDeleted) updateParams.clearDeleted = true;
   const row = await withUnmatchedEdgeUpdateRefusal(
     ctx,
     target,
     id,
     input.identity,
-    updateParams.expectedValidFrom !== void 0,
-    () => target.updateEdge(updateParams)
+    updateParams.expectedValidFrom !== void 0 || updateParams.expectedValidTo !== void 0,
+    () => target.updateEdge({
+      ...updateParams,
+      ...input.clearValidTo === true ? { clearValidTo: true } : validTo === void 0 ? {} : { validTo }
+    })
   );
   return rowToEdge(row);
 }
 function isEdgeUpdateNoRowError(error) {
   return error instanceof DatabaseOperationError && error.details.operation === "update" && error.details.entity === "edge" && error.details.reason === "no_row_returned";
 }
-async function withUnmatchedEdgeUpdateRefusal(ctx, target, id, expected, assertedValidFrom, write) {
+async function withUnmatchedEdgeUpdateRefusal(ctx, target, id, expected, assertedWindowState, write) {
   try {
     return await write();
   } catch (error) {
@@ -16857,7 +16991,7 @@ async function withUnmatchedEdgeUpdateRefusal(ctx, target, id, expected, asserte
         edgeIdentityFromRow(current),
         "update"
       );
-      if (assertedValidFrom && current.deleted_at === void 0) {
+      if (assertedWindowState && current.deleted_at === void 0) {
         throw new EdgeUpdateTargetMoved(expected.kind, id);
       }
     }
@@ -16907,40 +17041,73 @@ async function executeEdgeUpdate(ctx, input, backend) {
     ctx,
     opContext,
     backend,
-    (target) => performEdgeUpdateConverging(ctx, input, target)
+    (target) => {
+      if (input.clearValidTo === true) {
+        assertClearValidToSupported(backend, "edge");
+      }
+      return performEdgeUpdateConverging(ctx, input, target);
+    },
+    {
+      fencesConstraintProbe: input.clearValidTo === true && edgeCardinality(ctx, gate.kind) === "oneActive" ? edgeWriteNeedsConstraintFence("oneActive") : void 0
+    }
   );
 }
-async function executeEdgeUpsertUpdate(ctx, input, backend, options) {
-  const resurrectCardinality = options?.resurrectCardinality;
+async function executeEdgeUpsertUpdateWithOutcome(ctx, input, backend, options) {
+  if (input.clearValidTo === true) {
+    assertClearValidToSupported(backend, "edge");
+  }
   return runInWriteTransaction(
     ctx,
     backend,
     async (target) => {
-      if (resurrectCardinality !== void 0) {
-        await checkCardinalityConstraint(
-          {
-            graphId: ctx.graphId,
-            registry: ctx.registry,
-            backend: target
-          },
-          input.identity.kind,
-          resurrectCardinality.cardinality,
-          resurrectCardinality.fromKind,
-          resurrectCardinality.fromId,
-          resurrectCardinality.toKind,
-          resurrectCardinality.toId,
-          resurrectCardinality.effectiveValidTo
-        );
+      if (options?.coalesceUnchanged === true && !options.clearDeleted) {
+        const existing = options.coalesceCandidate ?? await target.getEdge(ctx.graphId, input.id);
+        if (existing !== void 0 && existing.deleted_at === void 0) {
+          assertEdgeIdentityMatches(
+            input.id,
+            input.identity,
+            edgeIdentityFromRow(existing),
+            "update"
+          );
+          const runDirtyCheck = () => edgeUpsertDirtyCheck(
+            ctx,
+            existing.kind,
+            existing.id,
+            rowPropsToObject(existing.props),
+            input.props
+          );
+          if (shouldCoalesceUpsert(existing, input, runDirtyCheck)) {
+            return { edge: rowToEdge(existing), wrote: false };
+          }
+        }
       }
-      return performEdgeUpdateConverging(ctx, input, target, options);
+      const edge = await performEdgeUpdateConverging(
+        ctx,
+        input,
+        target,
+        options
+      );
+      return { edge, wrote: true };
     },
     {
       // An in-place props update re-derives no constraint verdict: endpoints
       // are immutable, so cardinality cannot change under it.
-      fencesConstraintProbe: resurrectCardinality === void 0 ? void 0 : edgeWriteNeedsConstraintFence(resurrectCardinality.cardinality)
+      fencesConstraintProbe: options?.coalesceUnchanged === true ? "edgeMatchKeyConvergence" : input.clearValidTo === true || options?.clearDeleted === true ? edgeWriteNeedsConstraintFence(
+        edgeCardinality(ctx, input.identity.kind)
+      ) : void 0,
+      didWrite: (outcome) => outcome.wrote
     }
   );
 }
+async function executeEdgeUpsertUpdate(ctx, input, backend, options) {
+  const outcome = await executeEdgeUpsertUpdateWithOutcome(
+    ctx,
+    input,
+    backend,
+    options
+  );
+  return outcome.edge;
+}
 async function executeEdgeDelete(ctx, expectedKind, id, backend) {
   const gate = await backend.getEdge(ctx.graphId, id);
   if (!gate) return;
@@ -17112,11 +17279,29 @@ async function executeEdgeFindByEndpoints(ctx, kind, fromKind, fromId, toKind, t
   const { liveRow } = findMatchingEdge(candidateRows, matchOn, props);
   return liveRow === void 0 ? void 0 : rowToEdge(liveRow);
 }
+function defersEndpointWindowOrdering(ifExists, onImmutableLowerBound) {
+  return ifExists === "update" && preservesImmutableLowerBound(onImmutableLowerBound);
+}
+function assertEndpointClearCanApply(ifExists, clearValidTo, kind) {
+  if (ifExists !== "return" || clearValidTo !== true) return;
+  throw new ConfigurationError(
+    `clearValidTo requires ifExists: "update" for getOrCreateByEndpoints on edge kind "${kind}"; ifExists: "return" never mutates a matching edge.`,
+    {
+      code: "CLEAR_VALID_TO_REQUIRES_UPDATE",
+      kind,
+      ifExists
+    }
+  );
+}
 async function executeEdgeGetOrCreateByEndpoints(ctx, kind, fromKind, fromId, toKind, toId, props, backend, options) {
   const ifExists = options?.ifExists ?? "return";
   const matchOn = options?.matchOn ?? [];
   const registration = getEdgeRegistration(ctx.graph, kind);
   const edgeKind = registration.type;
+  assertValidityEndMutation(options ?? {}, { entityType: "edge", kind });
+  if (options?.clearValidTo === true) {
+    assertClearValidToSupported(backend, "edge");
+  }
   const validatedProps = validateEdgeProps(edgeKind.schema, props, {
     kind,
     operation: "create"
@@ -17127,11 +17312,13 @@ async function executeEdgeGetOrCreateByEndpoints(ctx, kind, fromKind, fromId, to
     "validFrom"
   );
   const validTo = validateOptionalCanonicalIsoDate(options?.validTo, "validTo");
-  assertOrderedValidityWindow(
-    `${kind} edge between ${fromKind} "${fromId}" and ${toKind} "${toId}"`,
-    validFrom,
-    validTo
-  );
+  if (!defersEndpointWindowOrdering(ifExists, options?.onImmutableLowerBound)) {
+    assertOrderedValidityWindow(
+      `${kind} edge between ${fromKind} "${fromId}" and ${toKind} "${toId}"`,
+      validFrom,
+      validTo
+    );
+  }
   if (ifExists === "return") {
     const probeRows = await backend.findEdgesByKind({
       graphId: ctx.graphId,
@@ -17149,6 +17336,7 @@ async function executeEdgeGetOrCreateByEndpoints(ctx, kind, fromKind, fromId, to
       validatedProps
     );
     if (probedLiveRow !== void 0) {
+      assertEndpointClearCanApply(ifExists, options?.clearValidTo, kind);
       return { edge: rowToEdge(probedLiveRow), action: "found" };
     }
   }
@@ -17193,27 +17381,48 @@ async function executeEdgeGetOrCreateByEndpoints(ctx, kind, fromKind, fromId, to
     }
     if (liveRow !== void 0) {
       if (ifExists === "return") {
+        assertEndpointClearCanApply(ifExists, options?.clearValidTo, kind);
         return { edge: rowToEdge(liveRow), action: "found" };
       }
-      const edge2 = await executeEdgeUpsertUpdate(
+      const outcome = await executeEdgeUpsertUpdateWithOutcome(
         ctx,
         {
           id: liveRow.id,
           identity: { kind, fromKind, fromId, toKind, toId },
           props: validatedProps,
           ...validFrom !== void 0 && { validFrom },
-          ...validTo !== void 0 && { validTo }
+          ...validTo !== void 0 && { validTo },
+          ...options?.clearValidTo === true && {
+            clearValidTo: true
+          },
+          ...options?.onImmutableLowerBound !== void 0 && {
+            onImmutableLowerBound: options.onImmutableLowerBound
+          }
         },
-        backend
+        backend,
+        {
+          coalesceUnchanged: ctx.coalesceUnchangedUpsertsEnabled && shouldCoalesceUpsert(
+            liveRow,
+            options,
+            () => edgeUpsertDirtyCheck(
+              ctx,
+              liveRow.kind,
+              liveRow.id,
+              rowPropsToObject(liveRow.props),
+              validatedProps
+            )
+          )
+        }
       );
-      return { edge: edge2, action: "updated" };
+      return {
+        edge: outcome.edge,
+        action: outcome.wrote ? "updated" : "found"
+      };
     }
-    const cardinality = registration.cardinality ?? "many";
     if (deletedRow === void 0) {
       throw new Error("Expected deletedRow to be defined");
     }
     const matchedDeletedRow = deletedRow;
-    const effectiveValidTo = validTo ?? matchedDeletedRow.valid_to;
     const edge = await executeEdgeUpsertUpdate(
       ctx,
       {
@@ -17221,20 +17430,16 @@ async function executeEdgeGetOrCreateByEndpoints(ctx, kind, fromKind, fromId, to
         identity: { kind, fromKind, fromId, toKind, toId },
         props: validatedProps,
         ...validFrom !== void 0 && { validFrom },
-        ...validTo !== void 0 && { validTo }
+        ...validTo !== void 0 && { validTo },
+        ...options?.clearValidTo === true && {
+          clearValidTo: true
+        },
+        ...options?.onImmutableLowerBound !== void 0 && {
+          onImmutableLowerBound: options.onImmutableLowerBound
+        }
       },
       backend,
-      {
-        clearDeleted: true,
-        resurrectCardinality: {
-          cardinality,
-          fromKind,
-          fromId,
-          toKind,
-          toId,
-          effectiveValidTo
-        }
-      }
+      { clearDeleted: true }
     );
     return { edge, action: "resurrected" };
   }
@@ -17265,10 +17470,13 @@ async function executeEdgeBulkGetOrCreateByEndpoints(ctx, kind, items, backend,
   const matchOn = options?.matchOn ?? [];
   const registration = getEdgeRegistration(ctx.graph, kind);
   const edgeKind = registration.type;
-  const cardinality = registration.cardinality ?? "many";
   validateMatchOnFields(edgeKind.schema, matchOn, kind);
   const validated = [];
   for (const item of items) {
+    assertValidityEndMutation(item, { entityType: "edge", kind });
+    if (item.clearValidTo === true) {
+      assertClearValidToSupported(backend, "edge");
+    }
     const validatedProps = validateEdgeProps(edgeKind.schema, item.props, {
       kind,
       operation: "create"
@@ -17278,11 +17486,13 @@ async function executeEdgeBulkGetOrCreateByEndpoints(ctx, kind, items, backend,
       "validFrom"
     );
     const validTo = validateOptionalCanonicalIsoDate(item.validTo, "validTo");
-    assertOrderedValidityWindow(
-      `${kind} edge between ${item.fromKind} "${item.fromId}" and ${item.toKind} "${item.toId}"`,
-      validFrom,
-      validTo
-    );
+    if (!defersEndpointWindowOrdering(ifExists, item.onImmutableLowerBound)) {
+      assertOrderedValidityWindow(
+        `${kind} edge between ${item.fromKind} "${item.fromId}" and ${item.toKind} "${item.toId}"`,
+        validFrom,
+        validTo
+      );
+    }
     const compositeKey = buildEdgeCompositeKey(
       item.fromKind,
       item.fromId,
@@ -17306,7 +17516,11 @@ async function executeEdgeBulkGetOrCreateByEndpoints(ctx, kind, items, backend,
       compositeKey,
       endpointKey: endpointKey2,
       ...validFrom !== void 0 && { validFrom },
-      ...validTo !== void 0 && { validTo }
+      ...validTo !== void 0 && { validTo },
+      ...item.clearValidTo === true && { clearValidTo: true },
+      ...item.onImmutableLowerBound !== void 0 && {
+        onImmutableLowerBound: item.onImmutableLowerBound
+      }
     });
   }
   const uniqueEndpoints = /* @__PURE__ */ new Map();
@@ -17345,6 +17559,13 @@ async function executeEdgeBulkGetOrCreateByEndpoints(ctx, kind, items, backend,
     for (const [index, entry2] of validated.entries()) {
       const previousIndex = seenKeys.get(entry2.compositeKey);
       if (previousIndex !== void 0) {
+        if (preservesImmutableLowerBound(entry2.onImmutableLowerBound)) {
+          assertOrderedValidityWindow(
+            `${kind} edge between ${entry2.fromKind} "${entry2.fromId}" and ${entry2.toKind} "${entry2.toId}"`,
+            entry2.validFrom,
+            entry2.validTo
+          );
+        }
         duplicateOf.push({ index, sourceIndex: previousIndex });
         continue;
       }
@@ -17388,7 +17609,13 @@ async function executeEdgeBulkGetOrCreateByEndpoints(ctx, kind, items, backend,
           ...entry2.validFrom !== void 0 && {
             validFrom: entry2.validFrom
           },
-          ...entry2.validTo !== void 0 && { validTo: entry2.validTo }
+          ...entry2.validTo !== void 0 && { validTo: entry2.validTo },
+          ...entry2.clearValidTo === true && {
+            clearValidTo: true
+          },
+          ...entry2.onImmutableLowerBound !== void 0 && {
+            onImmutableLowerBound: entry2.onImmutableLowerBound
+          }
         });
       }
     }
@@ -17400,6 +17627,7 @@ async function executeEdgeBulkGetOrCreateByEndpoints(ctx, kind, items, backend,
     if (allFoundLive) {
       const found = Array.from({ length: items.length });
       for (const entry2 of probe.toFetch) {
+        assertEndpointClearCanApply(ifExists, entry2.clearValidTo, kind);
         found[entry2.index] = { edge: rowToEdge(entry2.row), action: "found" };
       }
       for (const { index, sourceIndex } of probe.duplicateOf) {
@@ -17420,6 +17648,7 @@ async function executeEdgeBulkGetOrCreateByEndpoints(ctx, kind, items, backend,
           await fetchRowsByEndpoint(target)
         );
         const results = Array.from({ length: items.length });
+        let writes = 0;
         if (toCreate.length > 0) {
           const createInputs = toCreate.map((entry2) => entry2.input);
           const createdEdges = await executeEdgeCreateBatch(
@@ -17433,6 +17662,7 @@ async function executeEdgeBulkGetOrCreateByEndpoints(ctx, kind, items, backend,
               action: "created"
             };
           }
+          writes += toCreate.length;
         }
         for (const entry2 of toFetch) {
           if (entry2.isDeleted) {
@@ -17451,24 +17681,21 @@ async function executeEdgeBulkGetOrCreateByEndpoints(ctx, kind, items, backend,
                 ...entry2.validFrom !== void 0 && {
                   validFrom: entry2.validFrom
                 },
-                ...entry2.validTo !== void 0 && { validTo: entry2.validTo }
+                ...entry2.validTo !== void 0 && { validTo: entry2.validTo },
+                ...entry2.clearValidTo === true && {
+                  clearValidTo: true
+                },
+                ...entry2.onImmutableLowerBound !== void 0 && {
+                  onImmutableLowerBound: entry2.onImmutableLowerBound
+                }
               },
               target,
-              {
-                clearDeleted: true,
-                resurrectCardinality: {
-                  cardinality,
-                  fromKind: entry2.fromKind,
-                  fromId: entry2.fromId,
-                  toKind: entry2.toKind,
-                  toId: entry2.toId,
-                  effectiveValidTo: entry2.validTo ?? entry2.row.valid_to
-                }
-              }
+              { clearDeleted: true }
             );
             results[entry2.index] = { edge, action: "resurrected" };
+            writes += 1;
           } else if (ifExists === "update") {
-            const edge = await executeEdgeUpsertUpdate(
+            const outcome = await executeEdgeUpsertUpdateWithOutcome(
               ctx,
               {
                 id: entry2.row.id,
@@ -17483,12 +17710,27 @@ async function executeEdgeBulkGetOrCreateByEndpoints(ctx, kind, items, backend,
                 ...entry2.validFrom !== void 0 && {
                   validFrom: entry2.validFrom
                 },
-                ...entry2.validTo !== void 0 && { validTo: entry2.validTo }
+                ...entry2.validTo !== void 0 && { validTo: entry2.validTo },
+                ...entry2.clearValidTo === true && {
+                  clearValidTo: true
+                },
+                ...entry2.onImmutableLowerBound !== void 0 && {
+                  onImmutableLowerBound: entry2.onImmutableLowerBound
+                }
               },
-              target
+              target,
+              {
+                coalesceUnchanged: ctx.coalesceUnchangedUpsertsEnabled,
+                coalesceCandidate: entry2.row
+              }
             );
-            results[entry2.index] = { edge, action: "updated" };
+            results[entry2.index] = {
+              edge: outcome.edge,
+              action: outcome.wrote ? "updated" : "found"
+            };
+            if (outcome.wrote) writes += 1;
           } else {
+            assertEndpointClearCanApply(ifExists, entry2.clearValidTo, kind);
             results[entry2.index] = {
               edge: rowToEdge(entry2.row),
               action: "found"
@@ -17497,21 +17739,35 @@ async function executeEdgeBulkGetOrCreateByEndpoints(ctx, kind, items, backend,
         }
         for (const { index, sourceIndex } of duplicateOf) {
           const sourceResult = requireDefined(results[sourceIndex]);
+          if (sourceResult.action === "found") {
+            assertEndpointClearCanApply(
+              ifExists,
+              items[index]?.clearValidTo,
+              kind
+            );
+          }
           results[index] = { edge: sourceResult.edge, action: "found" };
         }
-        return results;
+        return { results, writes };
       },
       // A bulk getOrCreate always converges on a match key no database key
       // backs, whatever its cardinality — the same reason the single-item path
       // fences unconditionally.
-      { fencesConstraintProbe: "edgeMatchKeyConvergence" }
+      {
+        fencesConstraintProbe: "edgeMatchKeyConvergence",
+        didWrite: (outcome) => outcome.writes > 0
+      }
     );
   }
+  async function runBatchResults() {
+    const outcome = await runBatch();
+    return outcome.results;
+  }
   try {
-    return await runBatch();
+    return await runBatchResults();
   } catch (error) {
     if (!(error instanceof CardinalityError)) throw error;
-    return runBatch();
+    return runBatchResults();
   }
 }
 
@@ -18295,7 +18551,7 @@ var StoreImplementation = class _StoreImplementation {
       lockIdentityImportTarget: (target) => this.lockIdentityImportTarget(target),
       foldImportedIdentityNodes: (target, references) => this.foldImportedIdentityNodes(target, references),
       importIdentityAssertionsAtTarget: (target, assertions, mode) => this.importIdentityAssertionsAtTarget(target, assertions, mode),
-      applyIdentityMergeAtTarget: (target, retractionIds, assertions) => this.applyIdentityMergeAtTarget(target, retractionIds, assertions),
+      applyIdentityMergeAtTarget: (target, retractions, assertions) => this.applyIdentityMergeAtTarget(target, retractions, assertions),
       assertIdentityClassesConsistentAtTarget: (target, seeds) => this.assertIdentityClassesConsistentAtTarget(target, seeds)
     };
     Object.defineProperty(this, STORE_RUNTIME, {
@@ -18514,8 +18770,8 @@ var StoreImplementation = class _StoreImplementation {
     );
   }
   /** @internal Mechanical graph-merge apply through the mutation coordinator. */
-  applyIdentityMergeAtTarget(target, retractionIds, assertions) {
-    if (retractionIds.length === 0 && assertions.length === 0) {
+  applyIdentityMergeAtTarget(target, retractions, assertions) {
+    if (retractions.length === 0 && assertions.length === 0) {
       return Promise.resolve({ created: 0, retracted: 0 });
     }
     if (this.#graph.identity === void 0) {
@@ -18526,7 +18782,7 @@ var StoreImplementation = class _StoreImplementation {
     }
     return applyIdentityChangesForContext(
       this.#identityContext(target),
-      retractionIds,
+      retractions,
       assertions
     );
   }
@@ -18898,7 +19154,7 @@ var StoreImplementation = class _StoreImplementation {
         options
       ),
       // Present only when opted in; its absence is the coalesce off switch.
-      ...this.#options?.coalesceUnchangedUpserts === true && {
+      ...ctx.coalesceUnchangedUpsertsEnabled && {
         upsertDirtyCheck: (kind, id, existingProps, inputProps) => nodeUpsertDirtyCheck(ctx, kind, id, existingProps, inputProps)
       },
       executeDelete: (kind, id, backend) => executeNodeDelete(ctx, kind, id, backend),
@@ -18957,7 +19213,7 @@ var StoreImplementation = class _StoreImplementation {
       executeUpdate: (input, backend) => executeEdgeUpdate(ctx, input, backend),
       executeUpsertUpdate: (input, backend, options) => executeEdgeUpsertUpdate(ctx, input, backend, options),
       // Present only when opted in; its absence is the coalesce off switch.
-      ...this.#options?.coalesceUnchangedUpserts === true && {
+      ...ctx.coalesceUnchangedUpsertsEnabled && {
         upsertDirtyCheck: (kind, id, existingProps, inputProps) => edgeUpsertDirtyCheck(ctx, kind, id, existingProps, inputProps)
       },
       executeDelete: (kind, id, backend) => executeEdgeDelete(ctx, kind, id, backend),
@@ -20477,8 +20733,9 @@ var StoreImplementation = class _StoreImplementation {
    * path. The cost is that a database whose contribution tables were dropped
    * out of band (a partial restore, a hand-run `DROP`, a schema-scoped
    * restore that missed them) opens completely clean and then fails at the
-   * first read of the affected slot. This is the explicit, operator-invoked
-   * check for that state; it is not, and should not become, a boot step.
+   * first read or write that depends on the affected slot. This is the
+   * explicit, operator-invoked check for that state; it is not, and should not
+   * become, a boot step.
    *
    * Purely read-only: one existence query per distinct contribution table
    * plus one marker read per graph, no DDL and no writes, so it is safe to
@@ -20556,8 +20813,8 @@ var StoreImplementation = class _StoreImplementation {
     return repair(this.graphId, vectorSlots);
   }
   /**
-   * Read-only readiness check for the search projections: is search
-   * coherent with the graph right now, or is a query about to hit a
+   * Read-only readiness check for the search projections: are dependent reads
+   * and writes coherent with the graph right now, or are they about to hit a
    * degraded index?
    *
    * The read-only half of {@link Store.repairContributions}, and the
@@ -21013,6 +21270,7 @@ var StoreImplementation = class _StoreImplementation {
       schemaVersion: this.#schemaMetadata.schemaVersion,
       historyEnabled: this.#captureEnabled,
       revisionTrackingEnabled: this.#revisionTrackingEnabled,
+      coalesceUnchangedUpsertsEnabled: this.#coalescesUnchangedUpserts(),
       revisionSchema: this.#sqlSchema(),
       registry: this.#registry,
       ...identityConfig === void 0 ? {} : {
@@ -21037,6 +21295,15 @@ var StoreImplementation = class _StoreImplementation {
             target,
             ref,
             mode
+          ),
+          requireValidityEndCompatible: (target, ref, validTo) => requireNodeValidityEndCompatible(
+            {
+              graphId: this.graphId,
+              schema: this.#sqlSchema()
+            },
+            target,
+            ref,
+            validTo
           )
         }
       },
@@ -21058,12 +21325,17 @@ var StoreImplementation = class _StoreImplementation {
       schemaVersion: this.#schemaMetadata.schemaVersion,
       historyEnabled: this.#captureEnabled,
       revisionTrackingEnabled: this.#revisionTrackingEnabled,
+      coalesceUnchangedUpsertsEnabled: this.#coalescesUnchangedUpserts(),
       revisionSchema: this.#sqlSchema(),
       registry: this.#registry,
       createOperationContext: (operation, entity, kind, id) => this.#createOperationContext(operation, entity, kind, id),
       withOperationHooks: runHooks
     };
   }
+  /** The single owner of the store-wide unchanged-upsert enablement decision. */
+  #coalescesUnchangedUpserts() {
+    return this.#options?.coalesceUnchangedUpserts === true;
+  }
   // === Internal: Hook Helpers ===
   /**
    * Decorates the query execution port so hooks observe each statement the
@@ -21675,5 +21947,5 @@ async function createVerifiedAdapterStore(graph, backend, options) {
 }
 
 export { ExecutableAggregateQuery, ExecutableQuery, MAX_EXPLICIT_RECURSIVE_DEPTH, MAX_RECURSIVE_DEPTH, PreparedQuery, QueryBuilder, RecordedStoreView, StoreSearch, StoreView, UnionableQuery, avg, composeFragments, count, countDistinct, countDistinctEdges, countEdges, createAdapterStore, createAdapterStoreWithSchema, createFragment, createQueryBuilder, createStore, createStoreWithSchema, createVerifiedAdapterStore, createVerifiedStore, defineSubgraphProject, field, having, havingEq, havingGt, havingGte, havingLt, havingLte, limitFragment, max, min, offsetFragment, orderByFragment, sum };
-//# sourceMappingURL=chunk-S6PW7VV5.js.map
-//# sourceMappingURL=chunk-S6PW7VV5.js.map
+//# sourceMappingURL=chunk-DJZTXBWY.js.map
+//# sourceMappingURL=chunk-DJZTXBWY.js.map