@nicia-ai/typegraph 0.65.0 → 0.66.1

package/dist/{chunk-BWQA3POT.cjs → chunk-6B3LQUYG.cjs}

@@ -1,8 +1,8 @@
 'use strict';
 
-var chunkJRWKRBI5_cjs = require('./chunk-JRWKRBI5.cjs');
-var chunkDHRLOQLQ_cjs = require('./chunk-DHRLOQLQ.cjs');
-var chunkOC5ROP7V_cjs = require('./chunk-OC5ROP7V.cjs');
+var chunk5JOCIMQ3_cjs = require('./chunk-5JOCIMQ3.cjs');
+var chunk7LQTDGV5_cjs = require('./chunk-7LQTDGV5.cjs');
+var chunk6JRVV2SS_cjs = require('./chunk-6JRVV2SS.cjs');
 var chunkL4L4AV6F_cjs = require('./chunk-L4L4AV6F.cjs');
 var chunkXPSPDFKO_cjs = require('./chunk-XPSPDFKO.cjs');
 var chunkBXHAPCQG_cjs = require('./chunk-BXHAPCQG.cjs');
@@ -100,6 +100,78 @@ function transactionNodeOperationHookRunner(transaction) {
   }
   return runtime.runNodeOperationHooks;
 }
+
+// src/errors/validation.ts
+function zodIssuesToValidationIssues(error) {
+  return error.issues.map((issue) => ({
+    path: issue.path.join("."),
+    message: issue.message,
+    code: issue.code
+  }));
+}
+function buildLocationString(context) {
+  if (context.id) {
+    return `${context.kind}/${context.id}`;
+  }
+  return `new ${context.kind}`;
+}
+function validateProps(schema, props, context) {
+  const result = schema.safeParse(props);
+  if (result.success) {
+    return result.data;
+  }
+  const issues = zodIssuesToValidationIssues(result.error);
+  const location = buildLocationString(context);
+  throw new chunk7XYPLAPL_cjs.ValidationError(
+    `Invalid ${context.entityType} props for ${location}: ${result.error.message}`,
+    {
+      entityType: context.entityType,
+      kind: context.kind,
+      operation: context.operation,
+      ...context.id !== void 0 && { id: context.id },
+      issues
+    },
+    { cause: result.error }
+  );
+}
+function validateNodeProps(schema, props, context) {
+  return validateProps(schema, props, {
+    entityType: "node",
+    ...context
+  });
+}
+function validateEdgeProps(schema, props, context) {
+  return validateProps(schema, props, {
+    entityType: "edge",
+    ...context
+  });
+}
+function wrapZodError(error, context) {
+  const issues = zodIssuesToValidationIssues(error);
+  const location = buildLocationString(context);
+  return new chunk7XYPLAPL_cjs.ValidationError(
+    `Validation failed for ${context.entityType} ${location}: ${error.message}`,
+    {
+      entityType: context.entityType,
+      kind: context.kind,
+      operation: context.operation,
+      ...context.id !== void 0 && { id: context.id },
+      issues
+    },
+    { cause: error }
+  );
+}
+function createValidationError(message, issues, context) {
+  return new chunk7XYPLAPL_cjs.ValidationError(message, {
+    ...context?.entityType !== void 0 && {
+      entityType: context.entityType
+    },
+    ...context?.kind !== void 0 && { kind: context.kind },
+    ...context?.operation !== void 0 && { operation: context.operation },
+    ...context?.id !== void 0 && { id: context.id },
+    issues
+  });
+}
 function generateId() {
   return nanoid.nanoid();
 }
@@ -119,7 +191,7 @@ function requireRecordedSchema(target) {
       }
     );
   }
-  return chunkOC5ROP7V_cjs.createSqlSchema(target.tableNames);
+  return chunk6JRVV2SS_cjs.createSqlSchema(target.tableNames);
 }
 function requireCaptureStatements(target) {
   if (target.executeStatement === void 0) {
@@ -159,12 +231,12 @@ async function assertRecordedCaptureTransactionIsolation(target, options) {
   if (!RECORDED_ISOLATION_REQUIRES_POSTGRES_CHECK[target.dialect]) return;
   if (options?.accessMode === "read_only") return;
   if (target.fenceSql === void 0) {
-    chunkOC5ROP7V_cjs.refuseFenceSqlSessionFactUnavailable(target.dialect);
+    chunk6JRVV2SS_cjs.refuseFenceSqlSessionFactUnavailable(target.dialect);
   }
   const rows = await target.execute(
-    chunkXPSPDFKO_cjs.asCompiledRowsSql(chunkOC5ROP7V_cjs.resolveFenceStatements(target.fenceSql).isolationFact())
+    chunkXPSPDFKO_cjs.asCompiledRowsSql(chunk6JRVV2SS_cjs.resolveFenceStatements(target.fenceSql).isolationFact())
   );
-  const isolationLevel = chunkOC5ROP7V_cjs.normalizeGraphCommandIsolation(
+  const isolationLevel = chunk6JRVV2SS_cjs.normalizeGraphCommandIsolation(
     rows[0]?.transaction_isolation
   );
   if (isolationLevel === "read_committed") return;
@@ -230,19 +302,19 @@ function rawWriteGuards(target, prefix) {
 }
 function assertCapturableBackend(backend) {
   if (!backend.capabilities.execution.interactiveTransactions) {
-    const verdict = chunkJRWKRBI5_cjs.resolveBatchWriteVerdict(backend, { needs: "history" });
+    const verdict = chunk5JOCIMQ3_cjs.resolveBatchWriteVerdict(backend, { needs: "history" });
     throw new chunk7XYPLAPL_cjs.ConfigurationError(
-      "history: true requires a backend with transaction support." + chunkJRWKRBI5_cjs.batchRefusalSuffix(verdict),
+      "history: true requires a backend with transaction support." + chunk5JOCIMQ3_cjs.batchRefusalSuffix(verdict),
       {
         dialect: backend.dialect,
-        ...chunkJRWKRBI5_cjs.batchRefusalDetails(verdict)
+        ...chunk5JOCIMQ3_cjs.batchRefusalDetails(verdict)
       },
       {
         suggestion: "Use a transactional SQLite/PostgreSQL backend or disable recorded-time capture for this store."
       }
     );
   }
-  if (!chunkDHRLOQLQ_cjs.statementExecutionVerdict(backend).supported) {
+  if (!chunk7LQTDGV5_cjs.statementExecutionVerdict(backend).supported) {
     throw new chunk7XYPLAPL_cjs.ConfigurationError(
       "history: true requires a backend that supports executeStatement.",
       { dialect: backend.dialect },
@@ -272,19 +344,19 @@ function assertCapturableBackend(backend) {
 }
 function assertRevisionTrackableBackend(backend) {
   if (!backend.capabilities.execution.interactiveTransactions) {
-    const verdict = chunkJRWKRBI5_cjs.resolveBatchWriteVerdict(backend, { needs: "history" });
+    const verdict = chunk5JOCIMQ3_cjs.resolveBatchWriteVerdict(backend, { needs: "history" });
     throw new chunk7XYPLAPL_cjs.ConfigurationError(
-      "revisionTracking: true requires a backend with transaction support." + chunkJRWKRBI5_cjs.batchRefusalSuffix(verdict),
+      "revisionTracking: true requires a backend with transaction support." + chunk5JOCIMQ3_cjs.batchRefusalSuffix(verdict),
       {
         dialect: backend.dialect,
-        ...chunkJRWKRBI5_cjs.batchRefusalDetails(verdict)
+        ...chunk5JOCIMQ3_cjs.batchRefusalDetails(verdict)
       },
       {
         suggestion: "Use a transactional SQLite/PostgreSQL backend or leave revision tracking disabled."
       }
     );
   }
-  if (!chunkDHRLOQLQ_cjs.statementExecutionVerdict(backend).supported) {
+  if (!chunk7LQTDGV5_cjs.statementExecutionVerdict(backend).supported) {
     throw new chunk7XYPLAPL_cjs.ConfigurationError(
       "revisionTracking: true requires a backend that supports executeStatement.",
       { dialect: backend.dialect },
@@ -302,7 +374,7 @@ function assertRevisionTrackableBackend(backend) {
       }
     );
   }
-  if (!chunkDHRLOQLQ_cjs.recordedRevisionOriginsVerdict(backend).supported) {
+  if (!chunk7LQTDGV5_cjs.recordedRevisionOriginsVerdict(backend).supported) {
     throw new chunk7XYPLAPL_cjs.ConfigurationError(
       "revisionTracking: true requires a backend that can bootstrap revision origins.",
       { dialect: backend.dialect },
@@ -317,13 +389,13 @@ function assertRevisionTrackableBackend(backend) {
 var RECORDED_MIN_REVISION = 0;
 var RECORDED_MIN_TIME = "1970-01-01T00:00:00.000Z";
 var RECORDED_CLOCK_ADVISORY_LOCK_NAMESPACE = "typegraph:recorded-clock";
-chunkOC5ROP7V_cjs.resolveFenceStatements(chunkJRWKRBI5_cjs.postgresFenceSql);
+chunk6JRVV2SS_cjs.resolveFenceStatements(chunk5JOCIMQ3_cjs.postgresFenceSql);
 var UNCOORDINATED_GRAPH_WRITE_LOCK = Object.freeze({
   coordination: void 0
 });
 function acquiredGraphWriteLock(target, graphId, isolation) {
   return Object.freeze({
-    coordination: chunkOC5ROP7V_cjs.mintGraphCommandCoordination(
+    coordination: chunk6JRVV2SS_cjs.mintGraphCommandCoordination(
       target.commands,
       graphId,
       isolation
@@ -352,16 +424,16 @@ async function acquireRecordedGraphWriteLock(target, fenceSql, graphId) {
   const rows = await target.execute(
     chunkXPSPDFKO_cjs.asCompiledRowsSql(
       fenceSql.acquireKeyedWithIsolation(
-        chunkJRWKRBI5_cjs.RECORDED_GRAPH_WRITE_ADVISORY_LOCK_NAMESPACE,
+        chunk5JOCIMQ3_cjs.RECORDED_GRAPH_WRITE_ADVISORY_LOCK_NAMESPACE,
         graphId
       )
     )
   );
-  return chunkOC5ROP7V_cjs.normalizeGraphCommandIsolation(rows[0]?.transaction_isolation);
+  return chunk6JRVV2SS_cjs.normalizeGraphCommandIsolation(rows[0]?.transaction_isolation);
 }
 async function lockRecordedGraphWrite(target, graphId, memo) {
-  const plan = chunkOC5ROP7V_cjs.resolveWriteFencePlan(target);
-  const fence = chunkOC5ROP7V_cjs.requireWriteFence(plan, "recorded graph write", "keyed");
+  const plan = chunk6JRVV2SS_cjs.resolveWriteFencePlan(target);
+  const fence = chunk6JRVV2SS_cjs.requireWriteFence(plan, "recorded graph write", "keyed");
   switch (fence.kind) {
     case "engine-serialized":
     case "caller-serialized": {
@@ -476,7 +548,7 @@ async function ensureRevisionOriginsRelation(target, verdict) {
     );
   }
   if (ENSURED_ORIGINS_RELATIONS.has(target)) return;
-  const { ensureRevisionOriginsTable: ensureTable } = chunkOC5ROP7V_cjs.recordedRevisionOriginsMembers(target, verdict);
+  const { ensureRevisionOriginsTable: ensureTable } = chunk6JRVV2SS_cjs.recordedRevisionOriginsMembers(target, verdict);
   await ensureTable();
   ENSURED_ORIGINS_RELATIONS.add(target);
 }
@@ -533,8 +605,8 @@ async function assertRecordedClockAdvanced(target, schema, graphId, revision) {
   );
 }
 async function lockRecordedClock(target, schema, graphId, ownsWriteLock) {
-  const plan = chunkOC5ROP7V_cjs.resolveWriteFencePlan(target);
-  const fence = chunkOC5ROP7V_cjs.requireWriteFence(plan, "recorded clock allocation", "keyed");
+  const plan = chunk6JRVV2SS_cjs.resolveWriteFencePlan(target);
+  const fence = chunk6JRVV2SS_cjs.requireWriteFence(plan, "recorded clock allocation", "keyed");
   switch (fence.kind) {
     case "lock":
     case "row": {
@@ -765,7 +837,7 @@ function identityAssertionSnapshotSource(schema, graphId, coordinate, relation)
   `;
 }
 function historicalIdentityReconstructionCtes(input) {
-  chunkOC5ROP7V_cjs.assertRecursiveTraversal(
+  chunk6JRVV2SS_cjs.assertRecursiveTraversal(
     input.recursiveTraversal,
     "historical identity class read"
   );
@@ -825,7 +897,7 @@ var IDENTITY_PEER_CLASS_COLUMNS = chunkXPSPDFKO_cjs.sql.raw(
   ["seed_kind", "seed_id", "kind", "id"].join(", ")
 );
 function historicalIdentityPeerClassQuery(input) {
-  chunkOC5ROP7V_cjs.assertRecursiveTraversal(
+  chunk6JRVV2SS_cjs.assertRecursiveTraversal(
     input.recursiveTraversal,
     "historical identity expansion"
   );
@@ -864,10 +936,10 @@ async function getRowsByIds(ids, policy) {
 
 // src/store/edge-fetch.ts
 async function getEdgeRowsByIds(backend, verdict, graphId, ids) {
-  const bound = chunkOC5ROP7V_cjs.bindExtraIfReachable(
+  const bound = chunk6JRVV2SS_cjs.bindExtraIfReachable(
     backend,
     verdict.extras.getEdges,
-    chunkOC5ROP7V_cjs.BATCH_POINT_READ.id
+    chunk6JRVV2SS_cjs.BATCH_POINT_READ.id
   );
   return getRowsByIds(ids, {
     batch: bound === void 0 ? void 0 : ((batchIds) => bound.getEdges(graphId, batchIds)),
@@ -877,10 +949,10 @@ async function getEdgeRowsByIds(backend, verdict, graphId, ids) {
 
 // src/store/node-fetch.ts
 async function getNodeRowsByIds(backend, verdict, graphId, kind, ids) {
-  const bound = chunkOC5ROP7V_cjs.bindExtraIfReachable(
+  const bound = chunk6JRVV2SS_cjs.bindExtraIfReachable(
     backend,
     verdict.extras.getNodes,
-    chunkOC5ROP7V_cjs.BATCH_POINT_READ.id
+    chunk6JRVV2SS_cjs.BATCH_POINT_READ.id
   );
   return getRowsByIds(ids, {
     batch: bound === void 0 ? void 0 : ((batchIds) => bound.getNodes(graphId, kind, batchIds)),
@@ -984,7 +1056,7 @@ function recordedCommonCells() {
     graph_id: (row) => chunkXPSPDFKO_cjs.sql`${row.graph_id}`,
     id: (row) => chunkXPSPDFKO_cjs.sql`${row.id}`,
     kind: (row) => chunkXPSPDFKO_cjs.sql`${row.kind}`,
-    props: (row) => chunkXPSPDFKO_cjs.sql`${chunkOC5ROP7V_cjs.rowPropsToJsonText(row.props)}`,
+    props: (row) => chunkXPSPDFKO_cjs.sql`${chunk6JRVV2SS_cjs.rowPropsToJsonText(row.props)}`,
     valid_from: (row) => chunkXPSPDFKO_cjs.sql`${sqlNull(row.valid_from)}`,
     valid_to: (row) => chunkXPSPDFKO_cjs.sql`${sqlNull(row.valid_to)}`,
     created_at: (row) => chunkXPSPDFKO_cjs.sql`${row.created_at}`,
@@ -1120,7 +1192,7 @@ async function closeOpenReturning(target, table, graphId, ids, recordedRevision,
       WHERE graph_id = ${graphId}
         ${kindFilter}
         AND recorded_to = ${chunkL4L4AV6F_cjs.RECORDED_MAX_REVISION}
-        AND id IN (${chunkJRWKRBI5_cjs.sqlValueList(ids)})
+        AND id IN (${chunk5JOCIMQ3_cjs.sqlValueList(ids)})
       RETURNING id, deleted_at
     `)
   );
@@ -1164,7 +1236,7 @@ function recordedInsertsFor(afterById, closed) {
 async function flushNodes(target, batchPointRead, schema, graphId, entities, recordedRevision) {
   const chunkSize = recordedNodeChunkSize(target);
   for (const [kind, group] of groupNodesByKind(entities)) {
-    for (const entityChunk of chunkJRWKRBI5_cjs.chunk(group, chunkSize)) {
+    for (const entityChunk of chunk5JOCIMQ3_cjs.chunk(group, chunkSize)) {
       const ids = entityChunk.map((entity) => entity.id);
       const closed = await closeOpenReturning(
         target,
@@ -1189,7 +1261,7 @@ async function flushNodes(target, batchPointRead, schema, graphId, entities, rec
 }
 async function flushEdges(target, batchPointRead, schema, graphId, entities, recordedRevision) {
   const chunkSize = recordedEdgeChunkSize(target);
-  for (const entityChunk of chunkJRWKRBI5_cjs.chunk(entities, chunkSize)) {
+  for (const entityChunk of chunk5JOCIMQ3_cjs.chunk(entities, chunkSize)) {
     const ids = entityChunk.map((entity) => entity.id);
     const closed = await closeOpenReturning(
       target,
@@ -1217,7 +1289,7 @@ async function getIdentityAssertionRowsByIds(target, schema, graphId, ids) {
       SELECT ${IDENTITY_ASSERTION_COLUMNS}
       FROM ${schema.identityAssertionsTable}
       WHERE graph_id = ${graphId}
-        AND id IN (${chunkJRWKRBI5_cjs.sqlValueList(ids)})
+        AND id IN (${chunk5JOCIMQ3_cjs.sqlValueList(ids)})
     `)
   );
   return new Map(rows.map((row) => [row.id, row]));
@@ -1225,7 +1297,7 @@ async function getIdentityAssertionRowsByIds(target, schema, graphId, ids) {
 async function flushIdentityAssertions(target, schema, graphId, entities, recordedRevision) {
   if (entities.length === 0) return;
   const chunkSize = recordedIdentityAssertionChunkSize(target);
-  for (const entityChunk of chunkJRWKRBI5_cjs.chunk(entities, chunkSize)) {
+  for (const entityChunk of chunk5JOCIMQ3_cjs.chunk(entities, chunkSize)) {
     const ids = entityChunk.map((entity) => entity.id);
     const closed = await closeOpenReturning(
       target,
@@ -1421,6 +1493,18 @@ function buildRecordedWriteMembers(target, sink, hooks = {}) {
       sink.touchNode(params.graphId, params.kind, params.id, row);
       return row;
     },
+    ...target.upsertHeterogeneousNodes === void 0 ? {} : {
+      async upsertHeterogeneousNodes(params) {
+        await hooks.beforeOne?.(params.schemaFence.graphId);
+        const rows = await chunkBXHAPCQG_cjs.requireDefined(target.upsertHeterogeneousNodes)(
+          params
+        );
+        for (const row of rows) {
+          sink.touchNode(row.graph_id, row.kind, row.id, row);
+        }
+        return rows;
+      }
+    },
     ...target.updateResolvedNodesBatch === void 0 ? {} : {
       async updateResolvedNodesBatch(params) {
         if (params.entries.length === 0) return [];
@@ -1562,7 +1646,7 @@ function buildRecordedCommandsPort(target, sink, hooks = {}) {
     execute: async (command, context) => {
       await hooks.beforeOne?.(command.plan.params.graphId);
       const result = await target.commands.execute(command, context);
-      chunkOC5ROP7V_cjs.assertCommandResultMatchesCommand(command, result);
+      chunk6JRVV2SS_cjs.assertCommandResultMatchesCommand(command, result);
       if (result.outcome === "created") {
         if (result.entity === "node") {
           sink.touchNode(
@@ -1598,7 +1682,7 @@ function createMutationWitness() {
   };
   return {
     wrap(target) {
-      return chunkOC5ROP7V_cjs.deriveBackend(target, {
+      return chunk6JRVV2SS_cjs.deriveBackend(target, {
         ...buildRecordedWriteMembers(target, sink),
         commands: buildRecordedCommandsPort(target, sink)
       });
@@ -1764,12 +1848,12 @@ function resolveLineage(store) {
 
 // src/store/recorded-capture/schema-version.ts
 async function readColumnTypes(backend, table) {
-  const catalog = chunkDHRLOQLQ_cjs.requireCatalog(backend, "assertCurrentRecordedSchema");
+  const catalog = chunk7LQTDGV5_cjs.requireCatalog(backend, "assertCurrentRecordedSchema");
   const columns = await catalog.columnTypes(table);
   return new Map(columns.map((column) => [column.name, column]));
 }
 function isCompatibleColumnKind(kind, actual) {
-  const allowed = kind === "revision" ? chunkDHRLOQLQ_cjs.REVISION_COLUMN_KINDS : chunkDHRLOQLQ_cjs.WALL_TIME_COLUMN_KINDS;
+  const allowed = kind === "revision" ? chunk7LQTDGV5_cjs.REVISION_COLUMN_KINDS : chunk7LQTDGV5_cjs.WALL_TIME_COLUMN_KINDS;
   return allowed.includes(actual);
 }
 function requiredRecordedColumns(schema, includeIdentity) {
@@ -1951,7 +2035,7 @@ function createRecordedCaptureSession() {
       if (touched.size === 0 && forcedGraphRevisions.size === 0)
         return /* @__PURE__ */ new Map();
       const recordedByGraph = /* @__PURE__ */ new Map();
-      const byGraph = chunkJRWKRBI5_cjs.groupBy(touched.values(), (entity) => entity.graphId);
+      const byGraph = chunk5JOCIMQ3_cjs.groupBy(touched.values(), (entity) => entity.graphId);
       for (const graphId of forcedGraphRevisions) {
         if (!byGraph.has(graphId)) byGraph.set(graphId, []);
       }
@@ -2005,7 +2089,7 @@ function createRecordedCaptureSession() {
 var recordedTransactionBindings = /* @__PURE__ */ new WeakMap();
 var recordedRevisionBindings = /* @__PURE__ */ new WeakMap();
 function inheritRecordedTransactionBindings(source, derived, assertScopeOpen) {
-  if (!chunkOC5ROP7V_cjs.isBackendDerivedFrom(derived, source)) {
+  if (!chunk6JRVV2SS_cjs.isBackendDerivedFrom(derived, source)) {
     throw new TypeError("Capture bindings require a derived backend.");
   }
   const binding = recordedTransactionBindings.get(source);
@@ -2028,7 +2112,7 @@ async function runRecordedTransactionSavepoint(target, statementExecution, savep
   const binding = recordedTransactionBindings.get(target);
   binding?.assertOpen();
   const rawTarget = binding?.target ?? target;
-  const { executeStatement: executeStatement2 } = chunkOC5ROP7V_cjs.statementExecutionMembers(
+  const { executeStatement: executeStatement2 } = chunk6JRVV2SS_cjs.statementExecutionMembers(
     rawTarget,
     statementExecution
   );
@@ -2116,6 +2200,23 @@ function registerRecordedIdentityMutationWitness(overlay, target, sink) {
   recordedTransactionBindings.set(overlay, binding);
   recordedTransactionBindings.set(target, binding);
 }
+async function withRecordedNodeMutationTarget(target, graphId, run) {
+  const binding = recordedTransactionBindings.get(target);
+  if (binding === void 0) return run(target);
+  binding.assertOpen();
+  if (binding.capture !== void 0) {
+    await lockRecordedGraphWrite(
+      binding.target,
+      graphId,
+      binding.capture.graphLocks
+    );
+  }
+  const rows = await run(binding.target);
+  for (const row of rows) {
+    binding.sink.touchNode(row.graph_id, row.kind, row.id, row);
+  }
+  return rows;
+}
 function createRecordedTransactionBackend(target, session, schema) {
   const graphLocks = createRecordedGraphLockMemo();
   async function lockGraph(graphId) {
@@ -2145,7 +2246,7 @@ function createRecordedTransactionBackend(target, session, schema) {
     },
     connectedEdgeIdsForHardDelete: (params) => queryConnectedEdgeIds(target, schema, params)
   };
-  const overlay = chunkOC5ROP7V_cjs.deriveBackend(target, {
+  const overlay = chunk6JRVV2SS_cjs.deriveBackend(target, {
     ...rawWriteGuards(target, "tx.backend"),
     ...buildRecordedWriteMembers(target, sink, hooks),
     commands: buildRecordedCommandsPort(target, sink, hooks)
@@ -2169,7 +2270,7 @@ function createRecordedTransactionScope(target, batchPointRead, schema, ownsWrit
   return {
     backend: createRecordedTransactionBackend(target, session, resolvedSchema),
     async flush() {
-      return chunkOC5ROP7V_cjs.withRecordedRelationsPrecondition(
+      return chunk6JRVV2SS_cjs.withRecordedRelationsPrecondition(
         session.flush(target, batchPointRead, resolvedSchema, ownsWriteLock),
         { dialect: target.dialect, surface: "capture-flush" }
       );
@@ -2193,10 +2294,10 @@ async function runCapturedAutocommit(backend, schema, batchPointRead, fn, option
 }
 function createRecordedBackend(backend, schema) {
   assertCapturableBackend(backend);
-  const batchPointRead = chunkDHRLOQLQ_cjs.batchPointReadVerdict(backend);
+  const batchPointRead = chunk7LQTDGV5_cjs.batchPointReadVerdict(backend);
   const capture = (fn) => runCapturedAutocommit(backend, schema, batchPointRead, fn);
-  const projectedBackend = chunkOC5ROP7V_cjs.projectGraphBackend(backend);
-  return chunkOC5ROP7V_cjs.deriveBackend(projectedBackend, {
+  const projectedBackend = chunk6JRVV2SS_cjs.projectGraphBackend(backend);
+  return chunk6JRVV2SS_cjs.deriveBackend(projectedBackend, {
     ...rawWriteGuards(backend, "backend"),
     async insertNode(params) {
       return capture((target) => target.insertNode(params));
@@ -2231,7 +2332,7 @@ function createRecordedBackend(backend, schema) {
     commands: {
       session: "root",
       execute: async (command, context) => {
-        chunkOC5ROP7V_cjs.assertGraphCommandExecutionContext(context);
+        chunk6JRVV2SS_cjs.assertGraphCommandExecutionContext(context);
         if (context.session !== "root") {
           throw new chunk7XYPLAPL_cjs.CompilerInvariantError(
             "A recorded root command received a transaction execution context.",
@@ -2239,7 +2340,7 @@ function createRecordedBackend(backend, schema) {
           );
         }
         const result = await capture(
-          (target) => chunkOC5ROP7V_cjs.executeAuthoritativeGraphCommand(target.commands, command)
+          (target) => chunk6JRVV2SS_cjs.executeAuthoritativeGraphCommand(target.commands, command)
         );
         return result;
       }
@@ -2268,6 +2369,20 @@ function createRecordedBackend(backend, schema) {
     async updateNode(params) {
       return capture((target) => target.updateNode(params));
     },
+    ...backend.upsertHeterogeneousNodes === void 0 ? {} : {
+      async upsertHeterogeneousNodes(params) {
+        return capture((target) => {
+          const upsert = target.upsertHeterogeneousNodes;
+          if (upsert === void 0) {
+            throw new chunk7XYPLAPL_cjs.ConfigurationError(
+              "Recorded heterogeneous node upsert capability disappeared inside a transaction.",
+              { operation: "upsertHeterogeneousNodes" }
+            );
+          }
+          return upsert(params);
+        });
+      }
+    },
     ...backend.updateResolvedNodesBatch === void 0 ? {} : {
       async updateResolvedNodesBatch(params) {
         return capture((target) => {
@@ -2392,78 +2507,6 @@ function createRecordedBackend(backend, schema) {
   });
 }
 
-// src/errors/validation.ts
-function zodIssuesToValidationIssues(error) {
-  return error.issues.map((issue) => ({
-    path: issue.path.join("."),
-    message: issue.message,
-    code: issue.code
-  }));
-}
-function buildLocationString(context) {
-  if (context.id) {
-    return `${context.kind}/${context.id}`;
-  }
-  return `new ${context.kind}`;
-}
-function validateProps(schema, props, context) {
-  const result = schema.safeParse(props);
-  if (result.success) {
-    return result.data;
-  }
-  const issues = zodIssuesToValidationIssues(result.error);
-  const location = buildLocationString(context);
-  throw new chunk7XYPLAPL_cjs.ValidationError(
-    `Invalid ${context.entityType} props for ${location}: ${result.error.message}`,
-    {
-      entityType: context.entityType,
-      kind: context.kind,
-      operation: context.operation,
-      ...context.id !== void 0 && { id: context.id },
-      issues
-    },
-    { cause: result.error }
-  );
-}
-function validateNodeProps(schema, props, context) {
-  return validateProps(schema, props, {
-    entityType: "node",
-    ...context
-  });
-}
-function validateEdgeProps(schema, props, context) {
-  return validateProps(schema, props, {
-    entityType: "edge",
-    ...context
-  });
-}
-function wrapZodError(error, context) {
-  const issues = zodIssuesToValidationIssues(error);
-  const location = buildLocationString(context);
-  return new chunk7XYPLAPL_cjs.ValidationError(
-    `Validation failed for ${context.entityType} ${location}: ${error.message}`,
-    {
-      entityType: context.entityType,
-      kind: context.kind,
-      operation: context.operation,
-      ...context.id !== void 0 && { id: context.id },
-      issues
-    },
-    { cause: error }
-  );
-}
-function createValidationError(message, issues, context) {
-  return new chunk7XYPLAPL_cjs.ValidationError(message, {
-    ...context?.entityType !== void 0 && {
-      entityType: context.entityType
-    },
-    ...context?.kind !== void 0 && { kind: context.kind },
-    ...context?.operation !== void 0 && { operation: context.operation },
-    ...context?.id !== void 0 && { id: context.id },
-    issues
-  });
-}
-
 // src/store/operations/write-transaction.ts
 var writeTransactionSessions = /* @__PURE__ */ new WeakMap();
 var leasedSchemaFences = /* @__PURE__ */ new WeakMap();
@@ -2485,7 +2528,7 @@ function memoizeLeasedSchemaFence(ctx, target) {
 }
 async function withTransactionSchemaFenceLease(ctx, target, fn) {
   const expectedVersion = ctx.schemaVersion;
-  if (expectedVersion === void 0 || !chunkOC5ROP7V_cjs.isFirstPartyFactory(target)) {
+  if (expectedVersion === void 0 || !chunk6JRVV2SS_cjs.isFirstPartyFactory(target)) {
     return fn();
   }
   leasedSchemaFences.set(target, /* @__PURE__ */ new Map());
@@ -2495,16 +2538,39 @@ async function withTransactionSchemaFenceLease(ctx, target, fn) {
     leasedSchemaFences.delete(target);
   }
 }
+async function withPreAcquiredTransactionSchemaFenceLease(ctx, targets, fn) {
+  const expectedVersion = ctx.schemaVersion;
+  if (expectedVersion === void 0) return fn();
+  const leases = /* @__PURE__ */ new Map([
+    [schemaFenceLeaseKey(ctx.graphId, expectedVersion), Promise.resolve()]
+  ]);
+  const uniqueTargets = [...new Set(targets)];
+  const previousLeases = /* @__PURE__ */ new Map();
+  for (const target of uniqueTargets) {
+    previousLeases.set(target, leasedSchemaFences.get(target));
+    leasedSchemaFences.set(target, leases);
+  }
+  try {
+    return await fn();
+  } finally {
+    for (const target of uniqueTargets) {
+      if (leasedSchemaFences.get(target) !== leases) continue;
+      const previous = previousLeases.get(target);
+      if (previous === void 0) leasedSchemaFences.delete(target);
+      else leasedSchemaFences.set(target, previous);
+    }
+  }
+}
 function hasPendingWriteTransactionRevision(target) {
   return writeTransactionSessions.get(target)?.wrote === true;
 }
 async function ensureEngineSerializedWriterSlot(target, schema, statementExecution) {
-  const { executeStatement: executeStatement2 } = chunkOC5ROP7V_cjs.statementExecutionMembers(
+  const { executeStatement: executeStatement2 } = chunk6JRVV2SS_cjs.statementExecutionMembers(
     recordedTransactionControlTarget(target),
     statementExecution
   );
   await executeStatement2(
-    chunkJRWKRBI5_cjs.engineSerializedWriterSlotStatement(schema.nodesTable)
+    chunk5JOCIMQ3_cjs.engineSerializedWriterSlotStatement(schema.nodesTable)
   );
 }
 function forceWriteTransactionRevision(target) {
@@ -2528,7 +2594,7 @@ function adoptedConstraintWriterSlotError(ctx, cause) {
   );
 }
 async function ensureAdoptedConstraintWriterSlot(ctx, target, transactionMode, fenceReason) {
-  if (fenceReason === void 0 || transactionMode !== "existing" || writeTransactionSessions.has(target) || chunkOC5ROP7V_cjs.resolveWriteFencePlan(target).kind !== "engine-serialized") {
+  if (fenceReason === void 0 || transactionMode !== "existing" || writeTransactionSessions.has(target) || chunk6JRVV2SS_cjs.resolveWriteFencePlan(target).kind !== "engine-serialized") {
     return;
   }
   const statementExecution = ctx.statementExecution;
@@ -2552,7 +2618,7 @@ async function ensureAdoptedConstraintWriterSlot(ctx, target, transactionMode, f
       statementExecution
     );
   } catch (error) {
-    if (!chunkOC5ROP7V_cjs.isSqliteStaleSnapshotError(error)) throw error;
+    if (!chunk6JRVV2SS_cjs.isSqliteStaleSnapshotError(error)) throw error;
     throw adoptedConstraintWriterSlotError(ctx, error);
   }
 }
@@ -2633,7 +2699,7 @@ function resolveWriteTransactionMode(backend) {
   return backend.capabilities.execution.interactiveTransactions ? "opened" : "none";
 }
 function requiresOptimisticRetryUnit(backend) {
-  return chunkJRWKRBI5_cjs.isOptimisticRetryTier(backend) && resolveWriteTransactionMode(backend) === "opened";
+  return chunk5JOCIMQ3_cjs.isOptimisticRetryTier(backend) && resolveWriteTransactionMode(backend) === "opened";
 }
 var CONSTRAINT_FENCE_ADVICE = {
   edgeCardinality: 'declare the edge `cardinality: "many"` and enforce the limit in application code',
@@ -2646,16 +2712,16 @@ function constraintFenceRefusal(ctx, backend, reason) {
   if (!("transaction" in backend) || backend.capabilities.execution.interactiveTransactions) {
     return void 0;
   }
-  const verdict = chunkJRWKRBI5_cjs.resolveBatchWriteVerdict(backend, {
+  const verdict = chunk5JOCIMQ3_cjs.resolveBatchWriteVerdict(backend, {
     needs: "constraint-needs-probe"
   });
   return new chunk7XYPLAPL_cjs.ConfigurationError(
-    "This backend cannot fence a constrained write: enforcing a declared constraint requires a transaction \u2014 to scope the per-graph write lock to, and to commit a reservation row together with the row it gates \u2014 and this backend has no transactions." + chunkJRWKRBI5_cjs.batchRefusalSuffix(verdict),
+    "This backend cannot fence a constrained write: enforcing a declared constraint requires a transaction \u2014 to scope the per-graph write lock to, and to commit a reservation row together with the row it gates \u2014 and this backend has no transactions." + chunk5JOCIMQ3_cjs.batchRefusalSuffix(verdict),
     {
       code: "CONSTRAINT_WRITE_FENCE_UNSUPPORTED",
       graphId: ctx.graphId,
       constraint: reason,
-      ...chunkJRWKRBI5_cjs.batchRefusalDetails(verdict)
+      ...chunk5JOCIMQ3_cjs.batchRefusalDetails(verdict)
     },
     {
       suggestion: `Use a transactional backend, or ${CONSTRAINT_FENCE_ADVICE[reason]}. Unconstrained writes need no fence and keep working on this backend.`
@@ -2669,10 +2735,10 @@ function runInWriteTransaction(ctx, backend, fn, options) {
   if (refusal !== void 0) return Promise.reject(refusal);
   const attempt = () => runInWriteTransactionAttempt(ctx, backend, fn, options, transactionMode);
   if (!requiresOptimisticRetryUnit(backend)) return attempt();
-  return chunkJRWKRBI5_cjs.runRetriedUnit(
+  return chunk5JOCIMQ3_cjs.runRetriedUnit(
     {
       operation: "runInWriteTransaction",
-      attempts: chunkJRWKRBI5_cjs.OPTIMISTIC_RETRY_ATTEMPTS,
+      attempts: chunk5JOCIMQ3_cjs.OPTIMISTIC_RETRY_ATTEMPTS,
       target: backend
     },
     attempt
@@ -2682,7 +2748,7 @@ function runInWriteTransactionAttempt(ctx, backend, fn, options, transactionMode
   const ownsWriteLock = transactionMode === "opened";
   const fenceReason = options?.fencesConstraintProbe;
   const needsGraphWriteLock = ctx.historyEnabled || ctx.revisionTrackingEnabled || fenceReason !== void 0;
-  return chunkOC5ROP7V_cjs.runOptionallyInTransaction(backend, async (target) => {
+  return chunk6JRVV2SS_cjs.runOptionallyInTransaction(backend, async (target) => {
     await ensureAdoptedConstraintWriterSlot(
       ctx,
       target,
@@ -2695,7 +2761,7 @@ function runInWriteTransactionAttempt(ctx, backend, fn, options, transactionMode
     const acquiresLock = needsGraphWriteLock && session?.lock === void 0 && !held.has(ctx.graphId);
     if (acquiresLock) held.add(ctx.graphId);
     const expectedSchemaVersion = ctx.schemaVersion;
-    const combinedSchemaGraphFence = !options?.schemaFenceInFirstWrite && expectedSchemaVersion !== void 0 && acquiresLock && !("transaction" in target) ? {
+    const combinedSchemaGraphFence = !options?.schemaFenceInFirstWrite && expectedSchemaVersion !== void 0 && acquiresLock && !("transaction" in target) && !hasLeasedSchemaFence(ctx, target) ? {
       acquire: target.lockSchemaVersionAndGraphWrite,
       params: {
         graphId: ctx.graphId,
@@ -2822,10 +2888,12 @@ exports.uncapturedGraphWriteLock = uncapturedGraphWriteLock;
 exports.validateEdgeProps = validateEdgeProps;
 exports.validateNodeProps = validateNodeProps;
 exports.validateProps = validateProps;
+exports.withPreAcquiredTransactionSchemaFenceLease = withPreAcquiredTransactionSchemaFenceLease;
 exports.withRecordedFlushObserver = withRecordedFlushObserver;
 exports.withRecordedIdentityMutationTarget = withRecordedIdentityMutationTarget;
+exports.withRecordedNodeMutationTarget = withRecordedNodeMutationTarget;
 exports.withTransactionSchemaFenceLease = withTransactionSchemaFenceLease;
 exports.withWriteTransactionSession = withWriteTransactionSession;
 exports.wrapZodError = wrapZodError;
-//# sourceMappingURL=chunk-BWQA3POT.cjs.map
-//# sourceMappingURL=chunk-BWQA3POT.cjs.map
+//# sourceMappingURL=chunk-6B3LQUYG.cjs.map
+//# sourceMappingURL=chunk-6B3LQUYG.cjs.map