@nicia-ai/typegraph 0.35.0 → 0.36.0

package/dist/{chunk-UES55P7G.js → chunk-5DIPR3L3.js}

@@ -1,23 +1,23 @@
-import { createEdgeRowMapper, createNodeRowMapper, POSTGRES_ROW_MAPPER_CONFIG, SQLITE_ROW_MAPPER_CONFIG, quoteIdentifier, EMPTY_REQUIRED_COLUMNS, addRequiredColumn, mapSelectiveSystemFieldToColumn, markFieldRefAsRequired, findSelectivePropsFieldForFieldRef, markSelectiveFieldAsRequired, NODE_COLUMNS, shouldProjectColumn, isIdFieldRef, isAggregateExpr, EDGE_COLUMNS } from './chunk-55MZDDZV.js';
-import { rowToNode, executeNodeBulkFindByIndex, executeNodeBulkFindByConstraint, executeNodeFindByConstraint, executeNodeBulkGetOrCreateByConstraint, executeNodeGetOrCreateByConstraint, executeNodeHardDelete, executeNodeDelete, executeNodeUpsertUpdate, executeNodeUpdate, executeNodeCreateNoReturnBatch, executeNodeCreateBatch, executeNodeCreate, rowToEdge, runInWriteTransaction, checkCardinalityConstraint, runHookedWriteOperation, rowToNodeMeta, rowToEdgeMeta } from './chunk-QNKSQTKQ.js';
-import { loadAndMergeGraphExtensionDocument, ensureSchema, loadAndVerifyGraph, buildKindRegistry, mergeGraphExtension, commitNewSchemaVersion, applyDeprecatedKinds, loadActiveSchemaWithBootstrap, parseSerializedSchema, extensionKindNames, serializeSchemaProperties, buildGraphExtensionOntologyKeySet, compileTimeOntologyKey, getTypeName, serializeIndexDeclaration } from './chunk-K3PPLHY7.js';
-import { sortedReplacer, canonicalEqual } from './chunk-UR7W5YQK.js';
-import { isKnownKind, validateEdgeProps } from './chunk-QWEUYILR.js';
+import { createEdgeRowMapper, createNodeRowMapper, POSTGRES_ROW_MAPPER_CONFIG, SQLITE_ROW_MAPPER_CONFIG, quoteIdentifier, EMPTY_REQUIRED_COLUMNS, addRequiredColumn, mapSelectiveSystemFieldToColumn, markFieldRefAsRequired, findSelectivePropsFieldForFieldRef, markSelectiveFieldAsRequired, NODE_COLUMNS, shouldProjectColumn, isIdFieldRef, isAggregateExpr, EDGE_COLUMNS } from './chunk-RAXU3RMB.js';
+import { rowToNode, executeNodeBulkFindByIndex, executeNodeBulkFindByConstraint, executeNodeFindByConstraint, executeNodeBulkGetOrCreateByConstraint, executeNodeGetOrCreateByConstraint, executeNodeHardDelete, executeNodeDelete, nodeUpsertDirtyCheck, executeNodeUpsertUpdate, executeNodeUpdate, executeNodeCreateNoReturnBatch, executeNodeCreateBatch, executeNodeCreate, rowToEdge, runInWriteTransaction, checkCardinalityConstraint, runHookedWriteOperation, rowToNodeMeta, rowToEdgeMeta } from './chunk-DN5VP4JC.js';
+import { loadAndMergeGraphExtensionDocument, ensureSchema, loadAndVerifyGraph, buildKindRegistry, mergeGraphExtension, commitNewSchemaVersion, applyDeprecatedKinds, loadActiveSchemaWithBootstrap, parseSerializedSchema, extensionKindNames, serializeSchemaProperties, buildGraphExtensionOntologyKeySet, compileTimeOntologyKey, getTypeName, serializeIndexDeclaration } from './chunk-M75SUBFG.js';
+import { isKnownKind, validateEdgeProps } from './chunk-SKCOUWAX.js';
+import { canonicalEqual, sortedReplacer } from './chunk-UR7W5YQK.js';
 import { generateIndexDDL } from './chunk-UZV3AZKF.js';
 import { NODE_META_KEYS, EDGE_META_KEYS } from './chunk-OR5ZA5WP.js';
 import { sha256Hex, fnv1aBase36 } from './chunk-W63OVYY4.js';
 import { getDialect, assertVectorMinScore, vectorScoreExpression, vectorMinScoreCondition } from './chunk-FPIZFYHE.js';
 import { createSchemaIntrospector } from './chunk-5SEGFTZX.js';
-import { IncompatibleChangeError, RemoveCompileTimeKindError, KindHasReferentsError } from './chunk-QOTI55H7.js';
-import { validateProjectionField } from './chunk-RGPG7EOJ.js';
+import { IncompatibleChangeError, RemoveCompileTimeKindError, KindHasReferentsError } from './chunk-SXGE7ITL.js';
+import { validateProjectionField } from './chunk-S5F7ZLP2.js';
 import { compareStrings, compareCodePoints } from './chunk-BYPOGQWK.js';
-import { resolveReadCoordinate, withRecordedCoordinate, describeCoordinate, coordinateContext, DEFAULT_SQL_SCHEMA, requireSqlSchema, recordedReadSchemaFor, assertRevisionTrackableBackend, createSqlSchema, requireExternalRecordedReadSource, createRecordedReadBinding, createRecordedBackend, readRecordedClock, asRecordedInstant, ensureRevisionOrigin, withRecordedFlushObserver, recordedCaptureRequiresCallbackTransactionError, assertRecordedCaptureTransactionIsolation, createRecordedTransactionScope, lockRecordedGraphWrite, createHistoryUnsafeSqlRef, createRevisionTrackingUnsafeSqlRef, generateId, vectorSlotKey, computeFulltextContent, advanceRevisionClock, recordedReadSqlSchema, requireRecordedReadBinding, runInsertBatch, edgeInsertDispatch, runInsertBatchReturning, getEmbeddingFields, getNodeRowsByIds, getEdgeRowsByIds, assertValidRecordedInstant, validateEdgeEndpoints, recordedBindParamBudget, closeRecordedHardDeletedKind, ALIAS_CTE_PREFIX, EMBEDDINGS_CTE_ALIAS, FULLTEXT_CTE_ALIAS, HYBRID_CANDIDATES_CTE_ALIAS } from './chunk-CZQ3FO2Q.js';
+import { resolveReadCoordinate, withRecordedCoordinate, describeCoordinate, coordinateContext, DEFAULT_SQL_SCHEMA, requireSqlSchema, recordedReadSchemaFor, assertRevisionTrackableBackend, createSqlSchema, requireExternalRecordedReadSource, createRecordedReadBinding, createRecordedBackend, readRecordedClock, asRecordedInstant, ensureRevisionOrigin, withRecordedFlushObserver, recordedCaptureRequiresCallbackTransactionError, assertRecordedCaptureTransactionIsolation, createRecordedTransactionScope, lockRecordedGraphWrite, createHistoryUnsafeSqlRef, createRevisionTrackingUnsafeSqlRef, generateId, vectorSlotKey, computeFulltextContent, advanceRevisionClock, recordedReadSqlSchema, requireRecordedReadBinding, runInsertBatch, edgeInsertDispatch, runInsertBatchReturning, getEmbeddingFields, getNodeRowsByIds, getEdgeRowsByIds, assertValidRecordedInstant, validateEdgeEndpoints, recordedBindParamBudget, closeRecordedHardDeletedKind, ALIAS_CTE_PREFIX, EMBEDDINGS_CTE_ALIAS, FULLTEXT_CTE_ALIAS, HYBRID_CANDIDATES_CTE_ALIAS } from './chunk-5VTR2F2K.js';
 import { markAnnIndexScan, asCompiledSelectSql, isRawExecutable, annIndexScanTypes, asCompiledRowsSql, markForceCustomPlan, asCompiledStatementSql } from './chunk-UT3S4SEN.js';
-import { isParameterRef, fieldRef, buildFieldBuilderForTypeInfo, stringField, createFulltextAccessor, CURRENT_READ_INSTANT_PLACEHOLDER, withPinnedReadInstant, runOptionallyInTransaction, baseField, objectField, arrayField, dateField, numberField, rowPropsToObject, createBackendOverlay, compileKindFilter, currentReadInstant, compileTemporalFilter, sqlValueList, chunk, buildPredicateIndex, compileFieldValue, extractVectorSimilarityPredicates, extractFulltextMatchPredicates, currentReadInstantFor, extractTemporalOptions, compilePredicateExpression, getPredicatesForAlias, getNodeKindsForAlias, getHybridTargetAlias, compilePredicateClauses } from './chunk-JBTOYDMN.js';
-import { withRecordedRelationsPrecondition, nowIso, validateOptionalCanonicalIsoDate, isMissingTableError } from './chunk-I7ZUZKFD.js';
+import { isParameterRef, fieldRef, buildFieldBuilderForTypeInfo, stringField, createFulltextAccessor, CURRENT_READ_INSTANT_PLACEHOLDER, withPinnedReadInstant, runOptionallyInTransaction, baseField, objectField, arrayField, dateField, numberField, rowPropsToObject, createBackendOverlay, compileKindFilter, currentReadInstant, compileTemporalFilter, sqlValueList, chunk, buildPredicateIndex, compileFieldValue, extractVectorSimilarityPredicates, extractFulltextMatchPredicates, currentReadInstantFor, extractTemporalOptions, compilePredicateExpression, getPredicatesForAlias, getNodeKindsForAlias, getHybridTargetAlias, compilePredicateClauses } from './chunk-IU46OHVW.js';
+import { withRecordedRelationsPrecondition, nowIso, validateOptionalCanonicalIsoDate, isMissingTableError } from './chunk-JFUPDJXD.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-OHMP6N2J.js';
 import { getSearchableFields, resolveEmbeddingFields, resolveDeclaredFulltextLanguage } from './chunk-KBGQIPRQ.js';
-import { ConfigurationError, UnsupportedPredicateError, ValidationError, KindNotFoundError, EndpointError, EagerMaterializationError, CompilerInvariantError, CardinalityError, EdgeNotFoundError, DatabaseOperationError, EndpointNotFoundError } from './chunk-MP2JQKSG.js';
+import { ConfigurationError, UnsupportedPredicateError, ValidationError, KindNotFoundError, EndpointError, EagerMaterializationError, CompilerInvariantError, CardinalityError, EdgeNotFoundError, DatabaseOperationError, EndpointNotFoundError } from './chunk-WI7ISNQF.js';
 import { jsonPointer, parseJsonPointer, resolveJsonPointer } from './chunk-G6Q5UM7U.js';
 import { Placeholder, sql } from 'drizzle-orm';
 
@@ -10955,32 +10955,70 @@ function createEdgeCollection(config) {
       const upsertAll = async (target) => {
         const ids = items.map((item) => item.id);
         const existingMap = await getEdgeRowsByIds(target, graphId, ids);
+        const results2 = Array.from({ length: items.length });
         const toCreate = [];
         const toUpdate = [];
+        const pending = /* @__PURE__ */ new Map();
+        const deferred = [];
         let itemIndex = 0;
         for (const item of items) {
-          const existing = existingMap.get(item.id);
-          if (existing) {
-            toUpdate.push({
-              index: itemIndex,
-              input: buildUpdateEdgeInput(item.id, item.props ?? {}, item),
-              clearDeleted: existing.deleted_at !== void 0
-            });
-          } else {
+          const pendingEntry = pending.get(item.id);
+          const original = existingMap.get(item.id);
+          const inputProps = item.props ?? {};
+          if (pendingEntry === void 0 && original === void 0) {
             toCreate.push({
               index: itemIndex,
               input: buildCreateEdgeInput(
                 kind,
                 item.from,
                 item.to,
-                item.props ?? {},
+                inputProps,
                 item
               )
             });
+            itemIndex++;
+            continue;
+          }
+          const deletedAt = pendingEntry === void 0 ? original.deleted_at : void 0;
+          let dirty;
+          if (config.upsertDirtyCheck !== void 0) {
+            const currentProps = pendingEntry?.props ?? rowPropsToObject(original.props);
+            try {
+              dirty = config.upsertDirtyCheck(
+                original?.kind ?? kind,
+                item.id,
+                currentProps,
+                inputProps
+              );
+            } catch {
+              dirty = void 0;
+            }
+          }
+          const coalesce = dirty?.unchanged === true && deletedAt === void 0 && item.validFrom === void 0 && item.validTo === void 0;
+          if (coalesce) {
+            if (pendingEntry === void 0) {
+              results2[itemIndex] = narrowEdge(rowToEdge2(original));
+            } else {
+              deferred.push({
+                index: itemIndex,
+                sourceIndex: pendingEntry.sourceIndex
+              });
+            }
+          } else {
+            toUpdate.push({
+              index: itemIndex,
+              input: buildUpdateEdgeInput(item.id, inputProps, item),
+              clearDeleted: deletedAt !== void 0
+            });
+            if (dirty !== void 0) {
+              pending.set(item.id, {
+                props: dirty.validatedProps,
+                sourceIndex: itemIndex
+              });
+            }
           }
           itemIndex++;
         }
-        const results2 = Array.from({ length: items.length });
         if (toCreate.length > 0) {
           const createInputs = toCreate.map((entry2) => entry2.input);
           const created = await executeEdgeCreateBatch2(createInputs, target);
@@ -10994,10 +11032,13 @@ function createEdgeCollection(config) {
           });
           results2[entry2.index] = narrowEdge(result);
         }
-        return results2;
+        for (const { index, sourceIndex } of deferred) {
+          results2[index] = results2[sourceIndex];
+        }
+        return { results: results2, mutations: toCreate.length + toUpdate.length };
       };
-      const results = backend.capabilities.transactions && "transaction" in backend ? await backend.transaction(async (txBackend) => upsertAll(txBackend)) : await upsertAll(backend);
-      await config.maybeRefreshStatisticsAfterBulk?.(results.length);
+      const { results, mutations } = backend.capabilities.transactions && "transaction" in backend ? await backend.transaction(async (txBackend) => upsertAll(txBackend)) : await upsertAll(backend);
+      await config.maybeRefreshStatisticsAfterBulk?.(mutations);
       return results;
     },
     async bulkInsert(items) {
@@ -11091,6 +11132,18 @@ function createEdgeCollection(config) {
   };
 }
 
+// src/store/collections/coalesce.ts
+function shouldCoalesceUpsert(existing, options, runDirtyCheck) {
+  if (runDirtyCheck === void 0 || existing.deleted_at !== void 0 || options?.validFrom !== void 0 || options?.validTo !== void 0) {
+    return false;
+  }
+  try {
+    return runDirtyCheck().unchanged;
+  } catch {
+    return false;
+  }
+}
+
 // src/store/collections/node-collection.ts
 function narrowNode(node) {
   return node;
@@ -11218,11 +11271,19 @@ function createNodeCollection(config) {
     async upsertByIdFromRecord(id, data, options) {
       const existing = await backend.getNode(graphId, kind, id);
       if (existing) {
-        const clearDeleted = existing.deleted_at !== void 0;
+        const runDirtyCheck = config.upsertDirtyCheck && (() => config.upsertDirtyCheck(
+          kind,
+          id,
+          rowPropsToObject(existing.props),
+          data
+        ));
+        if (shouldCoalesceUpsert(existing, options, runDirtyCheck)) {
+          return narrowNode(rowToNode2(existing));
+        }
         const result2 = await executeNodeUpdate2(
           buildUpdateInput(kind, id, data, options),
           backend,
-          { clearDeleted }
+          { clearDeleted: existing.deleted_at !== void 0 }
         );
         return narrowNode(result2);
       }
@@ -11263,26 +11324,63 @@ function createNodeCollection(config) {
             existingMap.set(row.id, row);
           }
         }
+        const results2 = Array.from({ length: items.length });
         const toCreate = [];
         const toUpdate = [];
+        const pending = /* @__PURE__ */ new Map();
+        const deferred = [];
         let itemIndex = 0;
         for (const item of items) {
-          const existing = existingMap.get(item.id);
-          if (existing) {
-            toUpdate.push({
+          const pendingEntry = pending.get(item.id);
+          const original = existingMap.get(item.id);
+          if (pendingEntry === void 0 && original === void 0) {
+            toCreate.push({
               index: itemIndex,
-              input: buildUpdateInput(kind, item.id, item.props, item),
-              clearDeleted: existing.deleted_at !== void 0
+              input: buildCreateInput(kind, item.props, item)
             });
+            itemIndex++;
+            continue;
+          }
+          const deletedAt = pendingEntry === void 0 ? original.deleted_at : void 0;
+          let dirty;
+          if (config.upsertDirtyCheck !== void 0) {
+            const currentProps = pendingEntry?.props ?? rowPropsToObject(original.props);
+            try {
+              dirty = config.upsertDirtyCheck(
+                kind,
+                item.id,
+                currentProps,
+                item.props
+              );
+            } catch {
+              dirty = void 0;
+            }
+          }
+          const coalesce = dirty?.unchanged === true && deletedAt === void 0 && item.validFrom === void 0 && item.validTo === void 0;
+          if (coalesce) {
+            if (pendingEntry === void 0) {
+              results2[itemIndex] = narrowNode(rowToNode2(original));
+            } else {
+              deferred.push({
+                index: itemIndex,
+                sourceIndex: pendingEntry.sourceIndex
+              });
+            }
           } else {
-            toCreate.push({
+            toUpdate.push({
               index: itemIndex,
-              input: buildCreateInput(kind, item.props, item)
+              input: buildUpdateInput(kind, item.id, item.props, item),
+              clearDeleted: deletedAt !== void 0
             });
+            if (dirty !== void 0) {
+              pending.set(item.id, {
+                props: dirty.validatedProps,
+                sourceIndex: itemIndex
+              });
+            }
           }
           itemIndex++;
         }
-        const results2 = Array.from({ length: items.length });
         if (toCreate.length > 0) {
           const createInputs = toCreate.map((entry2) => entry2.input);
           const created = await executeNodeCreateBatch2(createInputs, target);
@@ -11296,10 +11394,13 @@ function createNodeCollection(config) {
           });
           results2[entry2.index] = narrowNode(result);
         }
-        return results2;
+        for (const { index, sourceIndex } of deferred) {
+          results2[index] = results2[sourceIndex];
+        }
+        return { results: results2, mutations: toCreate.length + toUpdate.length };
       };
-      const results = backend.capabilities.transactions && "transaction" in backend ? await backend.transaction(async (txBackend) => upsertAll(txBackend)) : await upsertAll(backend);
-      await config.maybeRefreshStatisticsAfterBulk?.(results.length);
+      const { results, mutations } = backend.capabilities.transactions && "transaction" in backend ? await backend.transaction(async (txBackend) => upsertAll(txBackend)) : await upsertAll(backend);
+      await config.maybeRefreshStatisticsAfterBulk?.(mutations);
       return results;
     },
     async bulkInsert(items) {
@@ -12697,21 +12798,45 @@ async function executeEdgeCreateBatch(ctx, inputs, backend) {
     return rows.map((row) => rowToEdge(row));
   });
 }
+function computeEdgeUpdate(ctx, kind, id, existingProps, inputProps) {
+  const registration = getEdgeRegistration(ctx.graph, kind);
+  return validateEdgeProps(
+    registration.type.schema,
+    { ...existingProps, ...inputProps },
+    { kind, operation: "update", id }
+  );
+}
+function resolveEdgeUpdateProps(ctx, existing, inputProps) {
+  const existingProps = rowPropsToObject(existing.props);
+  const validatedProps = computeEdgeUpdate(
+    ctx,
+    existing.kind,
+    existing.id,
+    existingProps,
+    inputProps
+  );
+  return { existingProps, validatedProps };
+}
+function edgeUpsertDirtyCheck(ctx, kind, id, existingProps, inputProps) {
+  const validatedProps = computeEdgeUpdate(
+    ctx,
+    kind,
+    id,
+    existingProps,
+    inputProps
+  );
+  return {
+    validatedProps,
+    unchanged: canonicalEqual(validatedProps, existingProps)
+  };
+}
 async function performEdgeUpdate(ctx, input, target, options) {
   const id = input.id;
   const existing = await target.getEdge(ctx.graphId, id);
   if (!existing || !options?.clearDeleted && existing.deleted_at) {
     throw new EdgeNotFoundError("unknown", id);
   }
-  const registration = getEdgeRegistration(ctx.graph, existing.kind);
-  const edgeKind = registration.type;
-  const existingProps = rowPropsToObject(existing.props);
-  const mergedProps = { ...existingProps, ...input.props };
-  const validatedProps = validateEdgeProps(edgeKind.schema, mergedProps, {
-    kind: existing.kind,
-    operation: "update",
-    id
-  });
+  const { validatedProps } = resolveEdgeUpdateProps(ctx, existing, input.props);
   const validTo = validateOptionalCanonicalIsoDate(input.validTo, "validTo");
   const updateParams = {
     graphId: ctx.graphId,
@@ -13369,27 +13494,48 @@ function increment(counts, kind, count2) {
   counts[kind] = (counts[kind] ?? 0) + count2;
 }
 function createTransactionReceiptRecorder() {
-  const nodes = createCountBucket();
-  const edges = createCountBucket();
-  let total = 0;
+  const counters = {
+    nodes: createCountBucket(),
+    edges: createCountBucket(),
+    total: 0
+  };
+  let sealed = false;
   return {
     recordNode(kind, count2) {
-      increment(nodes, kind, count2);
-      total += count2;
+      increment(counters.nodes, kind, count2);
+      counters.total += count2;
     },
     recordEdge(kind, count2) {
-      increment(edges, kind, count2);
-      total += count2;
+      increment(counters.edges, kind, count2);
+      counters.total += count2;
     },
     snapshot(recorded) {
       return Object.freeze({
         writes: Object.freeze({
-          nodes: Object.freeze(Object.assign(createCountBucket(), nodes)),
-          edges: Object.freeze(Object.assign(createCountBucket(), edges)),
-          total
+          nodes: Object.freeze(
+            Object.assign(createCountBucket(), counters.nodes)
+          ),
+          edges: Object.freeze(
+            Object.assign(createCountBucket(), counters.edges)
+          ),
+          total: counters.total
         }),
         ...recorded === void 0 ? {} : { recorded }
       });
+    },
+    seal() {
+      sealed = true;
+    },
+    assertWritable() {
+      if (sealed) {
+        throw new ConfigurationError(
+          "Transaction context is sealed: a write happened through the receipt-tracked collections after the transaction callback returned.",
+          {},
+          {
+            suggestion: "Perform all writes inside the transactionWithReceipt / withRecordedTransaction callback; do not reuse the transaction context after it returns."
+          }
+        );
+      }
     }
   };
 }
@@ -13423,7 +13569,7 @@ function memoizedProxyGet(target, shouldWrap, wrap) {
     }
   });
 }
-function wrapWriteCollection(collection, kind, surface, record) {
+function wrapWriteCollection(collection, kind, surface, record, assertWritable) {
   return memoizedProxyGet(
     collection,
     (property) => surface.methodNames.has(property),
@@ -13431,6 +13577,7 @@ function wrapWriteCollection(collection, kind, surface, record) {
       if (!isWrappedMethod(value)) return value;
       const method = property;
       const wrapped = async (...args) => {
+        assertWritable();
         const count2 = surface.counters[method](args);
         const result = await Reflect.apply(value, collection, args);
         record(kind, count2);
@@ -13455,7 +13602,8 @@ function wrapTransactionCollections(nodes, edges, recorder) {
         collection,
         kind,
         NODE_WRITE_SURFACE,
-        recorder.recordNode
+        recorder.recordNode,
+        recorder.assertWritable
       )
     ),
     edges: wrapCollections(
@@ -13464,7 +13612,8 @@ function wrapTransactionCollections(nodes, edges, recorder) {
         collection,
         kind,
         EDGE_WRITE_SURFACE,
-        recorder.recordEdge
+        recorder.recordEdge,
+        recorder.assertWritable
       )
     )
   };
@@ -13505,6 +13654,7 @@ function rowMapperConfigFor(backend) {
 function asError(error) {
   return error instanceof Error ? error : new Error(String(error));
 }
+var EMPTY_RECORDED_FLUSH_INSTANTS = /* @__PURE__ */ new Map();
 function transactionOutcome(result, recorder, recordedByGraph, graphId) {
   const recorded = recordedByGraph?.get(graphId);
   return {
@@ -13899,6 +14049,10 @@ var Store = class _Store {
         backend,
         options
       ),
+      // Present only when opted in; its absence is the coalesce off switch.
+      ...this.#options?.coalesceUnchangedUpserts === true && {
+        upsertDirtyCheck: (kind, id, existingProps, inputProps) => nodeUpsertDirtyCheck(ctx, kind, id, existingProps, inputProps)
+      },
       executeDelete: (kind, id, backend) => executeNodeDelete(ctx, kind, id, backend),
       executeHardDelete: (kind, id, backend) => executeNodeHardDelete(ctx, kind, id, backend),
       temporalRowMatcher: (options) => this.#temporalRowMatcher(options),
@@ -13953,6 +14107,10 @@ var Store = class _Store {
       executeCreateNoReturnBatch: (inputs, backend) => executeEdgeCreateNoReturnBatch(ctx, inputs, backend),
       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 && {
+        upsertDirtyCheck: (kind, id, existingProps, inputProps) => edgeUpsertDirtyCheck(ctx, kind, id, existingProps, inputProps)
+      },
       executeDelete: (id, backend) => executeEdgeDelete(ctx, id, backend),
       executeHardDelete: (id, backend) => executeEdgeHardDelete(ctx, id, backend),
       temporalRowMatcher: (options) => this.#temporalRowMatcher(options),
@@ -14422,9 +14580,11 @@ var Store = class _Store {
           receiptRecorder
         ));
       }
-      const result = await invoke({
+      const fallbackContext = {
         nodes,
         edges,
+        // No real transaction: `tx.sql` is absent and there is no atomicity.
+        sqlAvailability: "unavailable",
         backend: this.#backend,
         getNodeCollection: (kind) => this.#resolveDynamicNodeCollection(nodes, kind),
         // No transaction, no deferral: operations apply as they happen, so
@@ -14433,7 +14593,10 @@ var Store = class _Store {
           this.#createOperationContext(operation, "node", kind, id),
           hookedFunction
         )
-      });
+      };
+      const result = await invoke(
+        receiptRecorder === void 0 ? fallbackContext : this.#attachMeasure(fallbackContext)
+      );
       return { result, recordedByGraph: void 0 };
     }
     const pending = [];
@@ -14468,83 +14631,9 @@ var Store = class _Store {
       throw error;
     }
   }
-  /**
-   * Adopts a caller-owned, already-open Drizzle transaction so the graph
-   * store and the caller's relational writes commit or roll back as one
-   * Postgres/SQLite transaction (#134).
-   *
-   * Use this when the **relational layer owns the transaction**: the
-   * caller has opened a transaction and needs TypeGraph writes enlisted
-   * on the *same* connection. Unlike {@link transaction}, this opens no
-   * transaction — the caller's transaction is the single commit/rollback
-   * boundary.
-   *
-   * `withTransaction` is driver-agnostic; how the caller opens the
-   * transaction is not. **Async drivers** (node-postgres,
-   * `neon-serverless` Pool, libsql) use `db.transaction(async …)`.
-   * **Synchronous `better-sqlite3`** cannot — its driver rejects an
-   * `async` transaction callback (`Transaction function cannot return a
-   * promise`) and the async continuation would run outside the
-   * rolled-back transaction — so the caller opens the transaction with
-   * explicit `BEGIN`/`COMMIT`/`ROLLBACK` on the single connection
-   * instead. See the "Cross-Store Transactions" recipe for both shapes.
-   *
-   * The returned context reuses this store's already-resolved
-   * schema/registry: it runs **no** schema bootstrap, `evolve`, or
-   * migration, and emits **no DDL** inside the caller's transaction.
-   * Fulltext operations assert the durable materialization marker (a
-   * cached SELECT) and throw {@link StoreNotInitializedError} on a
-   * missing/stale/failed marker rather than migrating mid-transaction —
-   * so boot the parent store via `createStoreWithSchema` once at
-   * startup.
-   *
-   * @example
-   * ```typescript
-   * // Async driver (Postgres / libsql):
-   * await db.transaction(async (sqlTx) => {
-   *   const connector = await createConnectorRow(sqlTx, input); // Drizzle
-   *   const txStore = store.withTransaction(sqlTx);
-   *   await txStore.nodes.ArtifactSource.create({              // TypeGraph
-   *     connectorId: connector.id,
-   *   });
-   * }); // one COMMIT / ROLLBACK across both layers
-   * ```
-   *
-   * **The caller owns the connection — don't overlap writes on it.** The graph
-   * store and your Drizzle writes share the one connection the caller's
-   * transaction pinned. TypeGraph serializes the statements *its* collections
-   * issue, but your raw Drizzle statements (and any graph write run alongside
-   * them) are yours to sequence: a `Promise.all` mixing the two races two
-   * queries on that connection — the overlap Postgres removes in `pg@9`. Await
-   * each write before starting the next.
-   *
-   * Not available when the store was created with `{ history: true }`: a
-   * caller-owned transaction context would let writes happen after capture has
-   * lost its flush point, so this throws `ConfigurationError`
-   * (`RECORDED_CAPTURE_REQUIRES_CALLBACK_TRANSACTION`). Use
-   * {@link Store.withRecordedTransaction} on a history-enabled store, which
-   * adopts the same external transaction but flushes recorded-time capture
-   * before the caller commits.
-   *
-   * @throws {ConfigurationError} when the store has history capture enabled
-   *   (use {@link Store.withRecordedTransaction} instead), or when the backend
-   *   cannot adopt an external transaction — either it is not a Drizzle
-   *   Postgres/SQLite backend, or `backend.capabilities.transactions` is `false`
-   *   (`drizzle-orm/neon-http`, Cloudflare D1, SQLite
-   *   `transactionMode: "none"`). A non-atomic fallback is deliberately
-   *   not offered here: the caller's relational write *would* still
-   *   commit, defeating the purpose of cross-store atomicity.
-   * @throws {StoreNotInitializedError} at point of use, when a fulltext
-   *   operation on the returned context observes a missing/stale/failed
-   *   durable materialization marker (parent store not booted via
-   *   `createStoreWithSchema`). Rolls back the caller's transaction
-   *   without emitting any DDL.
-   */
   withTransaction(externalTx) {
     if (this.#captureEnabled) {
-      throw recordedCaptureRequiresCallbackTransactionError({
-        code: "RECORDED_CAPTURE_REQUIRES_CALLBACK_TRANSACTION"
-      });
+      throw recordedCaptureRequiresCallbackTransactionError();
     }
     const adopt = this.#backend.adoptTransaction;
     if (!adopt) {
@@ -14572,17 +14661,62 @@ var Store = class _Store {
     }
     const scope = this.#captureEnabled ? createRecordedTransactionScope(txBackend, this.#sqlSchema()) : {
       backend: txBackend,
-      flush: () => Promise.resolve()
+      flush: () => Promise.resolve(EMPTY_RECORDED_FLUSH_INSTANTS)
     };
     if (this.#captureEnabled) {
       await lockRecordedGraphWrite(scope.backend, this.graphId);
     }
+    const receiptRecorder = createTransactionReceiptRecorder();
     const invoke = fn;
     const result = await invoke(
-      this.#buildTransactionContext(scope.backend, externalTx)
+      this.#buildTransactionContext(
+        scope.backend,
+        externalTx,
+        void 0,
+        receiptRecorder
+      )
     );
-    await scope.flush();
-    return result;
+    const recordedByGraph = await scope.flush();
+    if (!this.#captureEnabled) receiptRecorder.seal();
+    return transactionOutcome(
+      result,
+      receiptRecorder,
+      recordedByGraph,
+      this.graphId
+    );
+  }
+  /**
+   * Decorates a receipt-enabled transaction `context` with `measure`.
+   * Attribution is structural: `measure` wraps the context's *own* (already
+   * outer-recording) collections a second time with a fresh scope recorder, so a
+   * write through the scoped context counts in the scope and — via the inner
+   * wrapper it delegates to — the outer receipt, while a write through the outer
+   * `context` never reaches the scope recorder. This makes overlapping/concurrent
+   * measures safe by construction (each holds its own scope recorder) and lets
+   * scopes nest: the scoped context is itself decorated, so `scoped.measure(...)`
+   * chains one more wrapper. The scoped context's `getNodeCollection` resolves
+   * against the scope-wrapped map too, so dynamic-kind writes are attributed like
+   * `scoped.nodes.<Kind>`. The scope receipt's `recorded` is always undefined —
+   * the recorded instant is a whole-transaction flush concern.
+   */
+  #attachMeasure(context) {
+    const measure = async (fn) => {
+      const scopeRecorder = createTransactionReceiptRecorder();
+      const { nodes, edges } = wrapTransactionCollections(
+        context.nodes,
+        context.edges,
+        scopeRecorder
+      );
+      const scoped = this.#attachMeasure({
+        ...context,
+        nodes,
+        edges,
+        getNodeCollection: (kind) => this.#resolveDynamicNodeCollection(nodes, kind)
+      });
+      const result = await fn(scoped);
+      return { result, receipt: scopeRecorder.snapshot() };
+    };
+    return { ...context, measure };
   }
   /**
    * Builds the `{ nodes, edges, sql }` projection bound to a
@@ -14628,24 +14762,20 @@ var Store = class _Store {
       ));
     }
     const getNodeCollection = (kind) => this.#resolveDynamicNodeCollection(nodes, kind);
-    if (sql17 === void 0) {
-      return {
-        nodes,
-        edges,
-        backend: txBackend,
-        getNodeCollection,
-        runNodeOperationHooks
-      };
-    }
-    const exposedSql = this.#captureEnabled ? createHistoryUnsafeSqlRef() : this.#revisionTrackingEnabled ? createRevisionTrackingUnsafeSqlRef() : sql17;
-    return {
+    const sqlAvailability = this.#captureEnabled ? "history" : this.#revisionTrackingEnabled ? "revisionTracking" : sql17 === void 0 ? "unavailable" : "available";
+    const base = {
       nodes,
       edges,
-      sql: exposedSql,
+      sqlAvailability,
       backend: txBackend,
       getNodeCollection,
       runNodeOperationHooks
     };
+    const withSql = sql17 === void 0 ? base : {
+      ...base,
+      sql: this.#captureEnabled ? createHistoryUnsafeSqlRef() : this.#revisionTrackingEnabled ? createRevisionTrackingUnsafeSqlRef() : sql17
+    };
+    return receiptRecorder === void 0 ? withSql : this.#attachMeasure(withSql);
   }
   // === Graph Lifecycle ===
   /**
@@ -15512,5 +15642,5 @@ async function createVerifiedStore(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, createFragment, createQueryBuilder, createStore, createStoreWithSchema, createVerifiedStore, defineSubgraphProject, field, having, havingEq, havingGt, havingGte, havingLt, havingLte, limitFragment, max, min, offsetFragment, orderByFragment, sum };
-//# sourceMappingURL=chunk-UES55P7G.js.map
-//# sourceMappingURL=chunk-UES55P7G.js.map
+//# sourceMappingURL=chunk-5DIPR3L3.js.map
+//# sourceMappingURL=chunk-5DIPR3L3.js.map