@nicia-ai/typegraph 0.44.0 → 0.46.0

package/dist/{chunk-SBPC5IP3.js → chunk-QWX5YA3K.js}

@@ -1,15 +1,18 @@
-import { lockRecordedGraphWrite, uncapturedGraphWriteLock, advanceRevisionClock, checkCardinality, checkUniqueEdge, checkWherePredicate, computeUniqueKey, getKindsForUniquenessCheck, runInsertBatch, nodeInsertDispatch, runInsertBatchReturning, applyNodeSoftDelete, createNodeWriteContext, applyNodeHardDelete, getNodeRowsByIds, generateId, runInsertNoReturn, applyNodeInsertSideEffectsBatch, applyNodeUpdate, applyNodeInsertSideEffects, checkUniquenessConstraints, createUniquenessContext, checkDisjointness } from './chunk-FSXTPBRN.js';
-import { createSqlSchema, DEFAULT_SQL_SCHEMA } from './chunk-MIJKEVV7.js';
-import { rowPropsToObject, runOptionallyInTransaction, createBackendOverlay, isLiveNodeRow } from './chunk-FMMIX6N4.js';
-import { validateNodeProps } from './chunk-DK2S42XB.js';
-import { canonicalEqual } from './chunk-UR7W5YQK.js';
-import { validateOptionalCanonicalIsoDate } from './chunk-KCO5EFJU.js';
-import { getDialect, compileNodeIndexFieldKeys, compileIndexWhere } from './chunk-K3BUWSFR.js';
-import { sql, asCompiledRowsSql } from './chunk-6DCB664D.js';
-import { requireDefined } from './chunk-QMQLUA66.js';
-import { filterReservedKeys, RESERVED_NODE_KEYS, RESERVED_EDGE_KEYS } from './chunk-TVLKA4AY.js';
-import { ConfigurationError, DatabaseOperationError, UniquenessError, ValidationError, NodeNotFoundError, KindNotFoundError, NodeConstraintNotFoundError, NodeIndexNotFoundError } from './chunk-4MB3AQAQ.js';
-import { resolveJsonPointer } from './chunk-G6Q5UM7U.js';
+import { getEmbeddingFields, applyNodeInsertSideEffectsBatch, createNodeWriteContext, applyNodeSoftDelete, applyNodeHardDelete, applyNodeUpdate, applyNodeInsertSideEffects, checkUniquenessConstraints, createUniquenessContext } from './chunk-WEVQJ5LH.js';
+import { encodeTupleKey, runInWriteTransaction, refKey, runHookedWriteOperation, validateNodeProps } from './chunk-JIVMTW7W.js';
+import { runInsertBatch, nodeInsertDispatch, runInsertBatchReturning, getNodeRowsByIds, generateId, runInsertNoReturn } from './chunk-NQ6BRJBE.js';
+import { canonicalEqual } from './chunk-JBQQ7THH.js';
+import { createSqlSchema, DEFAULT_SQL_SCHEMA } from './chunk-MSY7FSX4.js';
+import { rowPropsToObject, createBackendOverlay, isLiveNodeRow } from './chunk-AKLS3BYZ.js';
+import { checkCardinality, checkUniqueEdge, checkWherePredicate, computeUniqueKey, getKindsForUniquenessCheck, checkDisjointness } from './chunk-WDGA7IYB.js';
+import { validateOptionalCanonicalIsoDate, assertOrderedValidityWindow, nowIso, assertWritableValidityWindow } from './chunk-DLNROMQ7.js';
+import { getDialect, compileNodeIndexFieldKeys, compileIndexWhere } from './chunk-YDFDBE6D.js';
+import { sql, asCompiledRowsSql } from './chunk-PQBQG7IM.js';
+import { getSearchableFields } from './chunk-PC2UBAUB.js';
+import { filterReservedKeys, RESERVED_NODE_KEYS, RESERVED_EDGE_KEYS, assertJsonValue } from './chunk-K5ELX2GT.js';
+import { DatabaseOperationError, ConfigurationError, ValidationError, UniquenessError, NodeNotFoundError, KindNotFoundError, NodeConstraintNotFoundError, NodeIndexNotFoundError, ENTITY_ALREADY_EXISTS_CODE } from './chunk-J3WZ3FA2.js';
+import { resolveJsonPointer } from './chunk-FWJKWH6U.js';
+import { requireDefined, createDataKeyedBag, hasOwnKey } from './chunk-DYATYRY4.js';
 
 // src/store/row-mappers.ts
 function nullToUndefined(value) {
@@ -59,59 +62,19 @@ function rowToEdgeMeta(row) {
   };
 }
 
-// src/store/operations/write-transaction.ts
-async function lockSchemaVersionForStoreWrite(ctx, backend) {
-  const expectedVersion = ctx.schemaVersion;
-  if (expectedVersion === void 0) return;
-  if ("transaction" in backend && !backend.capabilities.transactions) {
-    throw new ConfigurationError(
-      "Schema-managed Store writes require a transactional backend so schema changes and entity writes can share one fence.",
-      {
-        code: "SCHEMA_WRITE_FENCE_UNSUPPORTED",
-        graphId: ctx.graphId
-      }
-    );
-  }
-  const lockSchemaVersionForWrite = backend.lockSchemaVersionForWrite;
-  if (lockSchemaVersionForWrite === void 0) {
-    throw new ConfigurationError(
-      "This backend cannot fence schema-managed Store writes against a concurrent schema change.",
-      {
-        code: "SCHEMA_WRITE_FENCE_UNSUPPORTED",
-        graphId: ctx.graphId
-      }
-    );
-  }
-  await lockSchemaVersionForWrite({
-    graphId: ctx.graphId,
-    expectedVersion
-  });
-}
-function runInWriteTransaction(ctx, backend, fn) {
-  const ownsWriteLock = "transaction" in backend && backend.capabilities.transactions;
-  return runOptionallyInTransaction(backend, async (target) => {
-    await lockSchemaVersionForStoreWrite(ctx, target);
-    const lock = ctx.historyEnabled || ctx.revisionTrackingEnabled ? await lockRecordedGraphWrite(target, ctx.graphId) : uncapturedGraphWriteLock();
-    const result = await fn(target, lock);
-    if (ctx.revisionTrackingEnabled && !ctx.historyEnabled) {
-      await advanceRevisionClock(
-        target,
-        ctx.revisionSchema,
-        ctx.graphId,
-        ownsWriteLock
-      );
-    }
-    return result;
-  });
+// src/store/constraints.ts
+function edgeWriteNeedsConstraintFence(cardinality) {
+  return cardinality === "many" ? void 0 : "edgeCardinality";
 }
-function runHookedWriteOperation(ctx, opContext, backend, body) {
-  return ctx.withOperationHooks(
-    opContext,
-    () => runInWriteTransaction(ctx, backend, body)
+function nodeWriteNeedsConstraintFence(registry, kind, uniqueConstraints, operation) {
+  if (operation === "create" && registry.getDisjointKinds(kind).length > 0) {
+    return "nodeDisjointness";
+  }
+  const sharedScope = uniqueConstraints.some(
+    (constraint) => getKindsForUniquenessCheck(kind, constraint.scope, registry).length > 1
   );
+  return sharedScope ? "nodeUniquenessScope" : void 0;
 }
-
-// src/store/constraints.ts
 async function checkDisjointnessConstraint(ctx, kind, id) {
   const disjointKinds = ctx.registry.getDisjointKinds(kind);
   for (const disjointKind of disjointKinds) {
@@ -190,31 +153,98 @@ async function checkCardinalityConstraint(ctx, edgeKind, cardinality, fromKind,
   }
 }
 
+// src/store/operations/already-exists.ts
+var ENTITY_LABELS = {
+  node: { title: "Node", article: "A node" },
+  edge: { title: "Edge", article: "An edge" }
+};
+function alreadyExistsError(entity, kind, id, detail, cause) {
+  const label = ENTITY_LABELS[entity];
+  return new ValidationError(
+    `${label.title} already exists: ${detail}`,
+    {
+      entityType: entity,
+      kind,
+      operation: "create",
+      ...id === void 0 ? {} : { id },
+      issues: [
+        {
+          path: "id",
+          code: ENTITY_ALREADY_EXISTS_CODE,
+          message: `${label.article} with this ID already exists`
+        }
+      ]
+    },
+    {
+      suggestion: `Use a different ID or update the existing ${entity}.`,
+      ...cause === void 0 ? {} : { cause }
+    }
+  );
+}
+function createAlreadyExistsError(entity, kind, id) {
+  return alreadyExistsError(entity, kind, id, `${kind}/${id}`, void 0);
+}
+function isDuplicateKeyInsertError(error, entity) {
+  return error instanceof DatabaseOperationError && error.details.operation === "insert" && error.details.entity === entity && error.details.reason === "duplicate_key";
+}
+function rethrowAsAlreadyExists(error, entity) {
+  if (!isDuplicateKeyInsertError(error, entity)) throw error;
+  const attempted = error.details.attempted ?? [];
+  const first = attempted[0];
+  if (first === void 0) throw error;
+  if (attempted.length === 1) {
+    throw alreadyExistsError(
+      entity,
+      first.kind,
+      first.id,
+      `${first.kind}/${first.id}`,
+      error
+    );
+  }
+  throw alreadyExistsError(
+    entity,
+    first.kind,
+    void 0,
+    `one of the ${attempted.length} ${first.kind} ids in the refused insert`,
+    error
+  );
+}
+async function withAlreadyExistsTranslation(entity, run) {
+  try {
+    return await run();
+  } catch (error) {
+    rethrowAsAlreadyExists(error, entity);
+  }
+}
+
 // src/store/operations/node-operations.ts
 function getNodeRegistration(graph, kind) {
+  if (!hasOwnKey(graph.nodes, kind)) throw new KindNotFoundError(kind, "node");
   const registration = graph.nodes[kind];
   if (registration === void 0) throw new KindNotFoundError(kind, "node");
   return registration;
 }
-var CACHE_KEY_SEPARATOR = "\0";
+function nodeFencesConstraintProbe(ctx, kind, operation) {
+  if (!hasOwnKey(ctx.graph.nodes, kind)) return void 0;
+  return nodeWriteNeedsConstraintFence(
+    ctx.registry,
+    kind,
+    getNodeRegistration(ctx.graph, kind).unique ?? [],
+    operation
+  );
+}
+function nodeBatchFencesConstraintProbe(ctx, inputs, operation) {
+  for (const input of inputs) {
+    const reason = nodeFencesConstraintProbe(ctx, input.kind, operation);
+    if (reason !== void 0) return reason;
+  }
+  return void 0;
+}
 function buildNodeCacheKey(graphId, kind, id) {
-  return `${graphId}${CACHE_KEY_SEPARATOR}${kind}${CACHE_KEY_SEPARATOR}${id}`;
+  return encodeTupleKey([graphId, kind, id]);
 }
 function buildUniqueCacheKey(graphId, nodeKind, constraintName, key) {
-  return `${graphId}${CACHE_KEY_SEPARATOR}${nodeKind}${CACHE_KEY_SEPARATOR}${constraintName}${CACHE_KEY_SEPARATOR}${key}`;
-}
-function createNodeAlreadyExistsError(kind, id) {
-  return new ValidationError(
-    `Node already exists: ${kind}/${id}`,
-    {
-      entityType: "node",
-      kind,
-      operation: "create",
-      id,
-      issues: [{ path: "id", message: "A node with this ID already exists" }]
-    },
-    { suggestion: `Use a different ID or update the existing node.` }
-  );
+  return encodeTupleKey([graphId, nodeKind, constraintName, key]);
 }
 function buildInsertNodeParams(graphId, kind, id, props, validFrom, validTo) {
   const insertParams = {
@@ -405,21 +435,28 @@ function draftNodeCreate(ctx, input, id, options) {
     kind,
     operation: "create"
   });
+  const validFrom = validateOptionalCanonicalIsoDate(
+    input.validFrom,
+    "validFrom"
+  );
+  const validTo = validateOptionalCanonicalIsoDate(input.validTo, "validTo");
+  assertOrderedValidityWindow(`${kind} "${id}"`, validFrom, validTo);
   return {
     kind,
     id,
+    idProvided: input.id !== void 0,
     nodeKind,
     uniqueConstraints: registration.unique ?? [],
     validatedProps,
-    validFrom: validateOptionalCanonicalIsoDate(input.validFrom, "validFrom"),
-    validTo: validateOptionalCanonicalIsoDate(input.validTo, "validTo")
+    validFrom,
+    validTo
   };
 }
 async function finishNodeCreatePreparation(ctx, draft, backend) {
   const { kind, id, validatedProps, uniqueConstraints } = draft;
   const existingNode = await backend.getNode(ctx.graphId, kind, id);
   if (existingNode && !existingNode.deleted_at) {
-    throw createNodeAlreadyExistsError(kind, id);
+    throw createAlreadyExistsError("node", kind, id);
   }
   const constraintContext = {
     graphId: ctx.graphId,
@@ -437,6 +474,8 @@ async function finishNodeCreatePreparation(ctx, draft, backend) {
   return {
     kind,
     id,
+    idProvided: draft.idProvided,
+    tombstone: existingNode,
     nodeKind: draft.nodeKind,
     validatedProps,
     uniqueConstraints,
@@ -470,6 +509,9 @@ async function finalizeNodeCreateBatch(ctx, preparedCreates, backend, lock) {
     backend
   );
 }
+function foldReferences(preparedCreates) {
+  return preparedCreates.filter((prepared) => prepared.idProvided).map((prepared) => ({ kind: prepared.kind, id: prepared.id }));
+}
 async function finalizeNodeCreate(ctx, prepared, backend, lock) {
   await applyNodeInsertSideEffects(
     createNodeWriteContext(ctx.graphId, ctx.registry, lock),
@@ -526,13 +568,46 @@ async function performNodeUpdate(ctx, input, backend, lock, options) {
     input.props
   );
   const nodeKind = registration.type;
+  const validFrom = validateOptionalCanonicalIsoDate(
+    input.validFrom,
+    "validFrom"
+  );
   const validTo = validateOptionalCanonicalIsoDate(input.validTo, "validTo");
+  const resurrectionInstant = options?.clearDeleted === true && existing.deleted_at !== void 0 ? nowIso() : void 0;
+  const windowVerdict = assertWritableValidityWindow(
+    `${kind} "${id}"`,
+    validFrom,
+    resurrectionInstant === void 0 ? {
+      effectiveValidFrom: existing.valid_from,
+      appliesStatedValidFrom: false,
+      effectiveBoundIsStored: true
+    } : {
+      effectiveValidFrom: resurrectionInstant,
+      appliesStatedValidFrom: true,
+      // The instant this write is about to stamp, not a bound the row holds.
+      effectiveBoundIsStored: false
+    },
+    validTo
+  );
   const writeContext = createNodeWriteContext(ctx.graphId, ctx.registry, lock);
+  const effectiveValidFrom = validFrom ?? resurrectionInstant;
   const shared = {
     schema: nodeKind.schema,
     validatedProps,
     uniqueConstraints: registration.unique ?? [],
-    ...validTo !== void 0 && { validTo }
+    ...effectiveValidFrom !== void 0 && { validFrom: effectiveValidFrom },
+    ...validTo !== void 0 && { validTo },
+    // The bound the verdict above READ, carried into the UPDATE's own `WHERE`
+    // so the row this writes is the row that was judged. The verdict hands over
+    // the predicate rather than a flag, so both conditions that decide it — did
+    // the verdict consult the effective bound, and WAS that bound the row's
+    // stored one — are answered where they are known. A plain
+    // `update({ props })` states no window, reads no bound, and stays unfenced:
+    // the same rule `UpdateEdgeParams`'s identity components follow, for the
+    // same reason. The resurrecting leg is judged against `resurrectionInstant`
+    // and so fences on `deleted_at IS NOT NULL` alone, converging through the
+    // recovery below.
+    ...windowVerdict.storedLowerBoundFence
   };
   if (options?.clearDeleted) {
     const row2 = await applyNodeUpdate(
@@ -550,6 +625,41 @@ async function performNodeUpdate(ctx, input, backend, lock, options) {
   );
   return rowToNode(row);
 }
+var NODE_UPDATE_ATTEMPTS = 2;
+async function performNodeUpdateWithResurrectionRecovery(ctx, input, target, lock, options) {
+  for (let attempt = 1; attempt <= NODE_UPDATE_ATTEMPTS; attempt += 1) {
+    try {
+      return await performNodeUpdate(
+        ctx,
+        input,
+        target,
+        lock,
+        attempt === 1 ? options : void 0
+      );
+    } catch (error) {
+      if (!isNodeUpdateNoRowError(error) || attempt === NODE_UPDATE_ATTEMPTS) {
+        throw nodeUpdateRaceError(input, error);
+      }
+      const current = await target.getNode(ctx.graphId, input.kind, input.id);
+      if (current === void 0 || current.deleted_at !== void 0) {
+        throw new NodeNotFoundError(input.kind, input.id);
+      }
+    }
+  }
+  throw new NodeNotFoundError(input.kind, input.id);
+}
+function nodeUpdateRaceError(input, error) {
+  if (!isNodeUpdateNoRowError(error)) return error;
+  return new DatabaseOperationError(
+    `Node update for ${input.kind} "${input.id}" could not be applied to a stable row after ${NODE_UPDATE_ATTEMPTS} attempts: the row was removed and recreated between each read and its write. A concurrent writer is replacing this node faster than it can be read; serialize the writers, or retry.`,
+    {
+      operation: "update",
+      entity: "node",
+      attempted: [{ kind: input.kind, id: input.id }]
+    },
+    { cause: error }
+  );
+}
 async function primeBatchValidationCaches(ctx, drafts, backend, seams) {
   if (backend.getNodes !== void 0) {
     const idsByKind = /* @__PURE__ */ new Map();
@@ -583,7 +693,7 @@ async function primeBatchValidationCaches(ctx, drafts, backend, seams) {
           ctx.registry
         );
         for (const kindToCheck of kindsToCheck) {
-          const groupKey = kindToCheck + CACHE_KEY_SEPARATOR + constraint.name;
+          const groupKey = encodeTupleKey([kindToCheck, constraint.name]);
           const group = groups.get(groupKey) ?? {
             nodeKind: kindToCheck,
             constraintName: constraint.name,
@@ -645,10 +755,60 @@ async function prepareBatchCreates(ctx, inputs, backend, options) {
       prepared.uniqueConstraints
     );
   }
-  const batchInsertParams = preparedCreates.map(
-    (prepared) => prepared.insertParams
-  );
-  return { preparedCreates, batchInsertParams };
+  return preparedCreates;
+}
+function partitionCreates(preparedCreates) {
+  const inserts = [];
+  const resurrections = [];
+  for (const prepared of preparedCreates) {
+    if (prepared.tombstone === void 0) {
+      inserts.push(prepared);
+    } else {
+      resurrections.push(prepared);
+    }
+  }
+  return { inserts, resurrections };
+}
+function isNodeUpdateNoRowError(error) {
+  return error instanceof DatabaseOperationError && error.details.operation === "update" && error.details.entity === "node" && error.details.reason === "no_row_returned";
+}
+async function resurrectPreparedNode(ctx, target, lock, prepared) {
+  const current = await target.getNode(ctx.graphId, prepared.kind, prepared.id);
+  if (current === void 0) {
+    throw new DatabaseOperationError(
+      `Node tombstone disappeared before resurrection: ${prepared.kind} ${prepared.id}`,
+      { operation: "update", entity: "node" }
+    );
+  }
+  if (current.deleted_at === void 0) {
+    throw createAlreadyExistsError("node", prepared.kind, prepared.id);
+  }
+  try {
+    return await applyNodeUpdate(
+      createNodeWriteContext(ctx.graphId, ctx.registry, lock),
+      {
+        existing: current,
+        clearDeleted: true,
+        schema: prepared.nodeKind.schema,
+        validatedProps: prepared.validatedProps,
+        uniqueConstraints: prepared.uniqueConstraints,
+        ...prepared.insertParams.validFrom === void 0 ? {} : { validFrom: prepared.insertParams.validFrom },
+        ...prepared.insertParams.validTo === void 0 ? {} : { validTo: prepared.insertParams.validTo }
+      },
+      target
+    );
+  } catch (error) {
+    if (!isNodeUpdateNoRowError(error)) throw error;
+    const afterFailure = await target.getNode(
+      ctx.graphId,
+      prepared.kind,
+      prepared.id
+    );
+    if (afterFailure !== void 0 && afterFailure.deleted_at === void 0) {
+      throw createAlreadyExistsError("node", prepared.kind, prepared.id);
+    }
+    throw error;
+  }
 }
 async function findUniqueRowAcrossKinds(backend, graphId, constraintName, key, kindsToCheck, includeDeleted) {
   for (const kindToCheck of kindsToCheck) {
@@ -707,6 +867,8 @@ async function executeNodeCreateInternal(ctx, input, backend, options) {
     opContext,
     backend,
     async (target, lock) => {
+      const identity = ctx.identity;
+      if (identity !== void 0) await identity.lock(target);
       const prepared = await validateAndPrepareNodeCreate(
         ctx,
         input,
@@ -714,18 +876,36 @@ async function executeNodeCreateInternal(ctx, input, backend, options) {
         target,
         options
       );
-      let row;
-      if (shouldReturnRow) {
-        row = await target.insertNode(prepared.insertParams);
-      } else {
+      const existing = prepared.tombstone;
+      if (existing !== void 0) {
+        const resurrected = await resurrectPreparedNode(
+          ctx,
+          target,
+          lock,
+          prepared
+        );
+        if (identity !== void 0) {
+          await identity.foldCreated(target, foldReferences([prepared]));
+        }
+        return shouldReturnRow ? rowToNode(resurrected) : void 0;
+      }
+      const row = await withAlreadyExistsTranslation("node", async () => {
+        if (shouldReturnRow) return target.insertNode(prepared.insertParams);
         await runInsertNoReturn(
           nodeInsertDispatch(target),
           prepared.insertParams
         );
-      }
+        return;
+      });
       await finalizeNodeCreate(ctx, prepared, target, lock);
+      if (identity !== void 0) {
+        await identity.foldCreated(target, foldReferences([prepared]));
+      }
       if (row === void 0) return;
       return rowToNode(row);
+    },
+    {
+      fencesConstraintProbe: nodeFencesConstraintProbe(ctx, kind, "create")
     }
   );
 }
@@ -744,32 +924,92 @@ async function executeNodeCreate(ctx, input, backend, options) {
 }
 async function executeNodeCreateNoReturnBatch(ctx, inputs, backend) {
   if (inputs.length === 0) return;
-  await runInWriteTransaction(ctx, backend, async (target, lock) => {
-    const { preparedCreates, batchInsertParams } = await prepareBatchCreates(
-      ctx,
-      inputs,
-      target
-    );
-    await runInsertBatch(nodeInsertDispatch(target), batchInsertParams);
-    await finalizeNodeCreateBatch(ctx, preparedCreates, target, lock);
-  });
+  await runInWriteTransaction(
+    ctx,
+    backend,
+    async (target, lock) => {
+      const identity = ctx.identity;
+      if (identity !== void 0) await identity.lock(target);
+      const preparedCreates = await prepareBatchCreates(ctx, inputs, target);
+      const partition = partitionCreates(preparedCreates);
+      await withAlreadyExistsTranslation(
+        "node",
+        () => runInsertBatch(
+          nodeInsertDispatch(target),
+          partition.inserts.map((prepared) => prepared.insertParams)
+        )
+      );
+      for (const prepared of partition.resurrections) {
+        await resurrectPreparedNode(ctx, target, lock, prepared);
+      }
+      await finalizeNodeCreateBatch(ctx, partition.inserts, target, lock);
+      if (identity !== void 0) {
+        await identity.foldCreated(target, foldReferences(preparedCreates));
+      }
+    },
+    {
+      fencesConstraintProbe: nodeBatchFencesConstraintProbe(
+        ctx,
+        inputs,
+        "create"
+      )
+    }
+  );
 }
 async function executeNodeCreateBatch(ctx, inputs, backend, options) {
   if (inputs.length === 0) return [];
-  return runInWriteTransaction(ctx, backend, async (target, lock) => {
-    const { preparedCreates, batchInsertParams } = await prepareBatchCreates(
-      ctx,
-      inputs,
-      target,
-      options
-    );
-    const rows = await runInsertBatchReturning(
-      nodeInsertDispatch(target),
-      batchInsertParams
-    );
-    await finalizeNodeCreateBatch(ctx, preparedCreates, target, lock);
-    return rows.map((row) => rowToNode(row));
-  });
+  return runInWriteTransaction(
+    ctx,
+    backend,
+    async (target, lock) => {
+      const identity = ctx.identity;
+      if (identity !== void 0) await identity.lock(target);
+      const preparedCreates = await prepareBatchCreates(
+        ctx,
+        inputs,
+        target,
+        options
+      );
+      const partition = partitionCreates(preparedCreates);
+      const inserted = await withAlreadyExistsTranslation(
+        "node",
+        () => runInsertBatchReturning(
+          nodeInsertDispatch(target),
+          partition.inserts.map((prepared) => prepared.insertParams)
+        )
+      );
+      const resurrected = [];
+      for (const prepared of partition.resurrections) {
+        resurrected.push(
+          await resurrectPreparedNode(ctx, target, lock, prepared)
+        );
+      }
+      await finalizeNodeCreateBatch(ctx, partition.inserts, target, lock);
+      const byReference = new Map(
+        [...inserted, ...resurrected].map((row) => [
+          refKey({ kind: row.kind, id: row.id }),
+          row
+        ])
+      );
+      const rows = preparedCreates.map(
+        (prepared) => requireDefined(
+          byReference.get(refKey({ kind: prepared.kind, id: prepared.id })),
+          `Missing written row for ${prepared.kind} ${prepared.id}`
+        )
+      );
+      if (identity !== void 0) {
+        await identity.foldCreated(target, foldReferences(preparedCreates));
+      }
+      return rows.map((row) => rowToNode(row));
+    },
+    {
+      fencesConstraintProbe: nodeBatchFencesConstraintProbe(
+        ctx,
+        inputs,
+        "create"
+      )
+    }
+  );
 }
 async function executeNodeUpdate(ctx, input, backend, options) {
   const opContext = ctx.createOperationContext(
@@ -782,14 +1022,301 @@ async function executeNodeUpdate(ctx, input, backend, options) {
     ctx,
     opContext,
     backend,
-    (target, lock) => performNodeUpdate(ctx, input, target, lock, options)
+    async (target, lock) => {
+      const identity = ctx.identity;
+      if (options?.clearDeleted && identity !== void 0) {
+        await identity.lock(target);
+      }
+      const node = await performNodeUpdateWithResurrectionRecovery(
+        ctx,
+        input,
+        target,
+        lock,
+        options
+      );
+      if (options?.clearDeleted && identity !== void 0) {
+        await identity.foldCreated(target, [
+          { kind: input.kind, id: input.id }
+        ]);
+      }
+      return node;
+    },
+    {
+      fencesConstraintProbe: nodeFencesConstraintProbe(
+        ctx,
+        input.kind,
+        "update"
+      )
+    }
+  );
+}
+async function executeNodeUpdateWhere(ctx, kind, inputPatch, candidateIds, candidateIdColumn, backend) {
+  const registration = getNodeRegistration(ctx.graph, kind);
+  const schema = registration.type.schema;
+  const uniqueConstraints = registration.unique ?? [];
+  if (!backend.capabilities.transactions) {
+    throw new ConfigurationError(
+      "updateWhere() requires a transactional backend so validation and sidecars are atomic",
+      { code: "SET_UPDATE_TRANSACTIONS_REQUIRED", kind }
+    );
+  }
+  if (backend.updateNodeSet === void 0) {
+    throw new ConfigurationError(
+      "This backend does not support set-based node updates",
+      { code: "SET_UPDATE_UNSUPPORTED", kind }
+    );
+  }
+  if (Object.keys(inputPatch).length === 0) {
+    throw new ValidationError("updateWhere() patch must not be empty", {
+      entityType: "node",
+      kind,
+      operation: "update",
+      issues: [{ path: "patch", message: "Provide at least one property" }]
+    });
+  }
+  const unknownProperty = Object.keys(inputPatch).find(
+    (property) => !Object.hasOwn(schema.shape, property)
+  );
+  if (unknownProperty !== void 0) {
+    throw new ValidationError(
+      `Unknown ${kind} property in updateWhere() patch: ${unknownProperty}`,
+      {
+        entityType: "node",
+        kind,
+        operation: "update",
+        issues: [
+          {
+            path: unknownProperty,
+            message: "Property is not declared by the node schema"
+          }
+        ]
+      }
+    );
+  }
+  const parsedPatch = validateNodeProps(schema.partial(), inputPatch, {
+    kind,
+    operation: "update"
+  });
+  const patch = createDataKeyedBag();
+  const unsetProperties = [];
+  for (const [property, value] of Object.entries(parsedPatch)) {
+    if (value === void 0) {
+      unsetProperties.push(property);
+      continue;
+    }
+    assertJsonValue(value, property, `Node "${kind}" updateWhere patch`);
+    patch[property] = value;
+  }
+  if (Object.keys(patch).length === 0 && unsetProperties.length === 0) {
+    throw new ValidationError(
+      "updateWhere() patch has no recognized properties",
+      {
+        entityType: "node",
+        kind,
+        operation: "update",
+        issues: [
+          { path: "patch", message: "Provide a declared node property" }
+        ]
+      }
+    );
+  }
+  if (uniqueConstraints.length > 0 && (backend.hardDeleteUniquesByNodeIds === void 0 || backend.insertUniqueBatch === void 0 || backend.checkUniqueBatch === void 0)) {
+    throw new ConfigurationError(
+      "updateWhere() requires batched uniqueness sidecar operations for constrained nodes",
+      { code: "SET_UPDATE_UNIQUENESS_UNSUPPORTED", kind }
+    );
+  }
+  if (getSearchableFields(schema).length > 0 && (backend.upsertFulltext === void 0 || backend.deleteFulltext === void 0 || backend.upsertFulltextBatch === void 0 || backend.deleteFulltextBatch === void 0)) {
+    throw new ConfigurationError(
+      "updateWhere() requires batched fulltext sidecar operations for searchable nodes",
+      { code: "SET_UPDATE_FULLTEXT_UNSUPPORTED", kind }
+    );
+  }
+  if (getEmbeddingFields(schema).length > 0 && (backend.upsertEmbedding === void 0 || backend.deleteEmbedding === void 0 || backend.upsertEmbeddingBatch === void 0 || backend.deleteEmbeddingBatch === void 0)) {
+    throw new ConfigurationError(
+      "updateWhere() requires batched vector sidecar operations for embedded nodes",
+      { code: "SET_UPDATE_VECTOR_UNSUPPORTED", kind }
+    );
+  }
+  const hookContext = ctx.createBulkOperationContext("updateWhere", kind);
+  return ctx.withBulkOperationHooks(
+    hookContext,
+    () => runInWriteTransaction(
+      ctx,
+      backend,
+      async (target, lock) => {
+        const updateNodeSet = target.updateNodeSet;
+        if (updateNodeSet === void 0) {
+          throw new ConfigurationError(
+            "The transaction backend does not support set-based node updates",
+            { code: "SET_UPDATE_UNSUPPORTED", kind }
+          );
+        }
+        const hardDeleteUniquesByNodeIds = target.hardDeleteUniquesByNodeIds;
+        if (uniqueConstraints.length > 0 && (hardDeleteUniquesByNodeIds === void 0 || target.insertUniqueBatch === void 0 || target.checkUniqueBatch === void 0)) {
+          throw new ConfigurationError(
+            "The transaction backend lacks batched uniqueness operations",
+            { code: "SET_UPDATE_UNIQUENESS_UNSUPPORTED", kind }
+          );
+        }
+        if (getSearchableFields(schema).length > 0 && (target.upsertFulltext === void 0 || target.deleteFulltext === void 0 || target.upsertFulltextBatch === void 0 || target.deleteFulltextBatch === void 0)) {
+          throw new ConfigurationError(
+            "The transaction backend lacks batched fulltext operations",
+            { code: "SET_UPDATE_FULLTEXT_UNSUPPORTED", kind }
+          );
+        }
+        if (getEmbeddingFields(schema).length > 0 && (target.upsertEmbedding === void 0 || target.deleteEmbedding === void 0 || target.upsertEmbeddingBatch === void 0 || target.deleteEmbeddingBatch === void 0)) {
+          throw new ConfigurationError(
+            "The transaction backend lacks batched vector operations",
+            { code: "SET_UPDATE_VECTOR_UNSUPPORTED", kind }
+          );
+        }
+        const result = await updateNodeSet({
+          graphId: ctx.graphId,
+          kind,
+          patch,
+          unsetProperties,
+          candidateIds,
+          candidateIdColumn
+        });
+        if (result.affectedCount === 0) return { affectedCount: 0 };
+        const sidecarItems = result.rows.map((row) => {
+          const props = rowPropsToObject(row.props);
+          const validatedProps = validateNodeProps(schema, props, {
+            kind,
+            operation: "update",
+            id: row.id
+          });
+          if (!canonicalEqual(validatedProps, props)) {
+            throw new ValidationError(
+              `Set update would persist a non-canonical ${kind} row`,
+              {
+                entityType: "node",
+                kind,
+                operation: "update",
+                id: row.id,
+                issues: [
+                  {
+                    path: "props",
+                    message: "The complete row requires schema normalization"
+                  }
+                ]
+              }
+            );
+          }
+          return {
+            kind,
+            id: row.id,
+            schema,
+            props: validatedProps,
+            uniqueConstraints
+          };
+        });
+        if (uniqueConstraints.length > 0) {
+          const affectedIds = new Set(result.rows.map((row) => row.id));
+          for (const constraint of uniqueConstraints) {
+            const keyToId = /* @__PURE__ */ new Map();
+            for (const item of sidecarItems) {
+              if (!checkWherePredicate(constraint, item.props)) continue;
+              const key = computeUniqueKey(
+                item.props,
+                constraint.fields,
+                constraint.collation
+              );
+              const priorId = keyToId.get(key);
+              if (priorId !== void 0 && priorId !== item.id) {
+                throw new UniquenessError({
+                  constraintName: constraint.name,
+                  kind,
+                  existingId: priorId,
+                  newId: item.id,
+                  fields: constraint.fields
+                });
+              }
+              keyToId.set(key, item.id);
+            }
+            const keys = [...keyToId.keys()];
+            if (keys.length === 0) continue;
+            for (const kindToCheck of getKindsForUniquenessCheck(
+              kind,
+              constraint.scope,
+              ctx.registry
+            )) {
+              const existingRows = await requireDefined(
+                target.checkUniqueBatch
+              )({
+                graphId: ctx.graphId,
+                nodeKind: kindToCheck,
+                constraintName: constraint.name,
+                keys
+              });
+              for (const existing of existingRows) {
+                if (existing.concrete_kind === kind && affectedIds.has(existing.node_id)) {
+                  continue;
+                }
+                throw new UniquenessError({
+                  constraintName: constraint.name,
+                  kind: kindToCheck,
+                  existingId: existing.node_id,
+                  newId: requireDefined(keyToId.get(existing.key)),
+                  fields: constraint.fields
+                });
+              }
+            }
+          }
+          await requireDefined(hardDeleteUniquesByNodeIds)({
+            graphId: ctx.graphId,
+            concreteKind: kind,
+            nodeIds: result.rows.map((row) => row.id)
+          });
+        }
+        await applyNodeInsertSideEffectsBatch(
+          createNodeWriteContext(ctx.graphId, ctx.registry, lock),
+          sidecarItems,
+          target
+        );
+        return { affectedCount: result.affectedCount };
+      },
+      {
+        didWrite: (result) => result.affectedCount > 0,
+        // The set update re-checks every changed unique key across the
+        // constraint's scope before rebuilding the sidecars, so a shared-scope
+        // constraint makes it a constrained write like any other update.
+        fencesConstraintProbe: nodeFencesConstraintProbe(ctx, kind, "update")
+      }
+    )
   );
 }
 async function executeNodeUpsertUpdate(ctx, input, backend, options) {
   return runInWriteTransaction(
     ctx,
     backend,
-    (target, lock) => performNodeUpdate(ctx, input, target, lock, options)
+    async (target, lock) => {
+      const identity = ctx.identity;
+      if (options?.clearDeleted && identity !== void 0) {
+        await identity.lock(target);
+      }
+      const node = await performNodeUpdateWithResurrectionRecovery(
+        ctx,
+        input,
+        target,
+        lock,
+        options
+      );
+      if (options?.clearDeleted && identity !== void 0) {
+        await identity.foldCreated(target, [
+          { kind: input.kind, id: input.id }
+        ]);
+      }
+      return node;
+    },
+    {
+      fencesConstraintProbe: nodeFencesConstraintProbe(
+        ctx,
+        input.kind,
+        "update"
+      )
+    }
   );
 }
 async function executeNodeDelete(ctx, kind, id, backend) {
@@ -801,6 +1328,8 @@ async function executeNodeDelete(ctx, kind, id, backend) {
     opContext,
     backend,
     async (target, lock) => {
+      const identity = ctx.identity;
+      if (identity !== void 0) await identity.lock(target);
       const registration = getNodeRegistration(ctx.graph, kind);
       const preflight = await target.getNode(ctx.graphId, kind, id);
       if (!preflight || !isLiveNodeRow(preflight)) return;
@@ -814,9 +1343,49 @@ async function executeNodeDelete(ctx, kind, id, backend) {
         },
         target
       );
+      if (identity !== void 0) {
+        await identity.detachDeleted(target, { kind, id }, "soft");
+      }
     }
   );
 }
+async function executeNodeDeleteBatch(ctx, kind, ids, backend) {
+  await runInWriteTransaction(
+    ctx,
+    backend,
+    async (target, lock) => {
+      const identity = ctx.identity;
+      if (identity !== void 0) await identity.lock(target);
+      const registration = getNodeRegistration(ctx.graph, kind);
+      const writeContext = createNodeWriteContext(
+        ctx.graphId,
+        ctx.registry,
+        lock
+      );
+      let affectedCount = 0;
+      for (const id of ids) {
+        const preflight = await target.getNode(ctx.graphId, kind, id);
+        if (!preflight || !isLiveNodeRow(preflight)) continue;
+        await applyNodeSoftDelete(
+          writeContext,
+          {
+            existing: preflight,
+            schema: registration.type.schema,
+            uniqueConstraints: registration.unique ?? [],
+            onDelete: registration.onDelete
+          },
+          target
+        );
+        if (identity !== void 0) {
+          await identity.detachDeleted(target, { kind, id }, "soft");
+        }
+        affectedCount += 1;
+      }
+      return affectedCount;
+    },
+    { didWrite: (affectedCount) => affectedCount > 0 }
+  );
+}
 async function executeNodeHardDelete(ctx, kind, id, backend) {
   const gate = await backend.getNode(ctx.graphId, kind, id);
   if (!gate) return;
@@ -826,6 +1395,8 @@ async function executeNodeHardDelete(ctx, kind, id, backend) {
     opContext,
     backend,
     async (target, lock) => {
+      const identity = ctx.identity;
+      if (identity !== void 0) await identity.lock(target);
       const registration = getNodeRegistration(ctx.graph, kind);
       await applyNodeHardDelete(
         createNodeWriteContext(ctx.graphId, ctx.registry, lock),
@@ -837,6 +1408,9 @@ async function executeNodeHardDelete(ctx, kind, id, backend) {
         },
         target
       );
+      if (identity !== void 0) {
+        await identity.detachDeleted(target, { kind, id }, "hard");
+      }
     }
   );
 }
@@ -1272,101 +1846,109 @@ async function executeNodeBulkGetOrCreateByConstraint(ctx, kind, constraintName,
     constraint.scope,
     ctx.registry
   );
-  const existingByKey = uniqueKeys.length > 0 ? await batchCheckUniqueAcrossKinds(
-    backend,
-    ctx.graphId,
-    constraint.name,
-    uniqueKeys,
-    kindsToCheck,
-    true
-  ) : /* @__PURE__ */ new Map();
-  const toCreate = [];
-  const toFetch = [];
-  const duplicateOf = [];
-  const seenKeys = /* @__PURE__ */ new Map();
-  for (const [index, { validatedProps, key }] of validated.entries()) {
-    if (key === void 0) {
-      toCreate.push({ index, input: { kind, props: validatedProps } });
-      continue;
-    }
-    const previousIndex = seenKeys.get(key);
-    if (previousIndex !== void 0) {
-      duplicateOf.push({ index, sourceIndex: previousIndex });
-      continue;
-    }
-    seenKeys.set(key, index);
-    const existing = existingByKey.get(key);
-    if (existing === void 0) {
-      toCreate.push({ index, input: { kind, props: validatedProps } });
-    } else {
-      toFetch.push({
-        index,
-        nodeId: existing.node_id,
-        concreteKind: existing.concrete_kind,
-        validatedProps,
-        isSoftDeleted: existing.deleted_at !== void 0
-      });
-    }
-  }
-  const results = Array.from({ length: items.length });
-  if (toCreate.length > 0) {
-    const createInputs = toCreate.map((entry) => entry.input);
-    const createdNodes = await executeNodeCreateBatch(
-      ctx,
-      createInputs,
+  async function attempt() {
+    const existingByKey = uniqueKeys.length > 0 ? await batchCheckUniqueAcrossKinds(
       backend,
-      { propsPreValidated: true }
-    );
-    for (const [batchIndex, entry] of toCreate.entries()) {
-      results[entry.index] = {
-        node: requireDefined(createdNodes[batchIndex]),
-        action: "created"
-      };
-    }
-  }
-  for (const entry of toFetch) {
-    const { index, concreteKind, validatedProps, isSoftDeleted, nodeId } = entry;
-    const existingRow = await backend.getNode(
       ctx.graphId,
-      concreteKind,
-      nodeId
-    );
-    if (existingRow === void 0) {
-      const node = await executeNodeCreate(
+      constraint.name,
+      uniqueKeys,
+      kindsToCheck,
+      true
+    ) : /* @__PURE__ */ new Map();
+    const toCreate = [];
+    const toFetch = [];
+    const duplicateOf = [];
+    const seenKeys = /* @__PURE__ */ new Map();
+    for (const [index, { validatedProps, key }] of validated.entries()) {
+      if (key === void 0) {
+        toCreate.push({ index, input: { kind, props: validatedProps } });
+        continue;
+      }
+      const previousIndex = seenKeys.get(key);
+      if (previousIndex !== void 0) {
+        duplicateOf.push({ index, sourceIndex: previousIndex });
+        continue;
+      }
+      seenKeys.set(key, index);
+      const existing = existingByKey.get(key);
+      if (existing === void 0) {
+        toCreate.push({ index, input: { kind, props: validatedProps } });
+      } else {
+        toFetch.push({
+          index,
+          nodeId: existing.node_id,
+          concreteKind: existing.concrete_kind,
+          validatedProps
+        });
+      }
+    }
+    const results = Array.from({ length: items.length });
+    if (toCreate.length > 0) {
+      const createInputs = toCreate.map((entry) => entry.input);
+      const createdNodes = await executeNodeCreateBatch(
         ctx,
-        { kind, props: validatedProps },
+        createInputs,
         backend,
         { propsPreValidated: true }
       );
-      results[index] = { node, action: "created" };
-      continue;
+      for (const [batchIndex, entry] of toCreate.entries()) {
+        results[entry.index] = {
+          node: requireDefined(createdNodes[batchIndex]),
+          action: "created"
+        };
+      }
     }
-    if (isSoftDeleted || ifExists === "update") {
-      const node = await executeNodeUpsertUpdate(
-        ctx,
-        {
-          kind: concreteKind,
-          id: existingRow.id,
-          props: validatedProps
-        },
-        backend,
-        { clearDeleted: isSoftDeleted }
+    for (const entry of toFetch) {
+      const { index, concreteKind, validatedProps, nodeId } = entry;
+      const existingRow = await backend.getNode(
+        ctx.graphId,
+        concreteKind,
+        nodeId
       );
-      results[index] = {
-        node,
-        action: isSoftDeleted ? "resurrected" : "updated"
-      };
-    } else {
-      results[index] = { node: rowToNode(existingRow), action: "found" };
+      if (existingRow === void 0) {
+        const node = await executeNodeCreate(
+          ctx,
+          { kind, props: validatedProps },
+          backend,
+          { propsPreValidated: true }
+        );
+        results[index] = { node, action: "created" };
+        continue;
+      }
+      const isSoftDeleted = existingRow.deleted_at !== void 0;
+      if (isSoftDeleted || ifExists === "update") {
+        const node = await executeNodeUpsertUpdate(
+          ctx,
+          {
+            kind: concreteKind,
+            id: existingRow.id,
+            props: validatedProps
+          },
+          backend,
+          { clearDeleted: isSoftDeleted }
+        );
+        results[index] = {
+          node,
+          action: isSoftDeleted ? "resurrected" : "updated"
+        };
+      } else {
+        results[index] = { node: rowToNode(existingRow), action: "found" };
+      }
     }
+    for (const { index, sourceIndex } of duplicateOf) {
+      const sourceResult = requireDefined(results[sourceIndex]);
+      results[index] = { node: sourceResult.node, action: "found" };
+    }
+    return results;
   }
-  for (const { index, sourceIndex } of duplicateOf) {
-    const sourceResult = requireDefined(results[sourceIndex]);
-    results[index] = { node: sourceResult.node, action: "found" };
+  try {
+    return await attempt();
+  } catch (error) {
+    if (!(error instanceof UniquenessError)) throw error;
+    return attempt();
   }
-  return results;
 }
 
-export { checkCardinalityConstraint, createNodeBatchValidationBackend, executeNodeBulkFindByConstraint, executeNodeBulkFindByIndex, executeNodeBulkGetOrCreateByConstraint, executeNodeCreate, executeNodeCreateBatch, executeNodeCreateNoReturnBatch, executeNodeDelete, executeNodeFindByConstraint, executeNodeGetOrCreateByConstraint, executeNodeHardDelete, executeNodeUpdate, executeNodeUpsertUpdate, lockSchemaVersionForStoreWrite, nodeUpsertDirtyCheck, primeBatchValidationCaches, rowToEdge, rowToEdgeMeta, rowToNode, rowToNodeMeta, runHookedWriteOperation, runInWriteTransaction };
-//# sourceMappingURL=chunk-SBPC5IP3.js.map
-//# sourceMappingURL=chunk-SBPC5IP3.js.map
+export { checkCardinalityConstraint, createNodeBatchValidationBackend, edgeWriteNeedsConstraintFence, executeNodeBulkFindByConstraint, executeNodeBulkFindByIndex, executeNodeBulkGetOrCreateByConstraint, executeNodeCreate, executeNodeCreateBatch, executeNodeCreateNoReturnBatch, executeNodeDelete, executeNodeDeleteBatch, executeNodeFindByConstraint, executeNodeGetOrCreateByConstraint, executeNodeHardDelete, executeNodeUpdate, executeNodeUpdateWhere, executeNodeUpsertUpdate, nodeUpsertDirtyCheck, primeBatchValidationCaches, rowToEdge, rowToEdgeMeta, rowToNode, rowToNodeMeta, withAlreadyExistsTranslation };
+//# sourceMappingURL=chunk-QWX5YA3K.js.map
+//# sourceMappingURL=chunk-QWX5YA3K.js.map