@nicia-ai/typegraph 0.3.1 → 0.5.0

package/dist/index.js

@@ -1,9 +1,9 @@
-import { META_EDGE_BRAND, META_EDGE_SUB_CLASS_OF, META_EDGE_NARROWER, META_EDGE_BROADER, META_EDGE_RELATED_TO, META_EDGE_EQUIVALENT_TO, META_EDGE_SAME_AS, META_EDGE_DIFFERENT_FROM, META_EDGE_DISJOINT_WITH, META_EDGE_HAS_PART, META_EDGE_PART_OF, META_EDGE_INVERSE_OF, META_EDGE_IMPLIES, ensureSchema, computeClosuresFromOntology, createEmptyClosures, KindRegistry, validateNodeProps, validateEdgeProps } from './chunk-NP4G4ZKM.js';
-export { isMetaEdge } from './chunk-NP4G4ZKM.js';
-import { NODE_TYPE_BRAND, EDGE_TYPE_BRAND, nowIso, validateOptionalIsoDate, getNodeKinds, getEdgeKinds } from './chunk-XDTYTNYL.js';
-export { defineGraph, getEdgeKinds, getNodeKinds, isEdgeType, isEdgeTypeWithEndpoints, isGraphDef, isNodeType } from './chunk-XDTYTNYL.js';
-import { ConfigurationError, UnsupportedPredicateError, ValidationError, CompilerInvariantError, KindNotFoundError, RestrictedDeleteError, NodeNotFoundError, DatabaseOperationError, EdgeNotFoundError, UniquenessError, EndpointNotFoundError, EndpointError, DisjointError, CardinalityError } from './chunk-O5XPCJLF.js';
-export { CardinalityError, CompilerInvariantError, ConfigurationError, DatabaseOperationError, DisjointError, EdgeNotFoundError, EndpointError, EndpointNotFoundError, KindNotFoundError, MigrationError, NodeNotFoundError, RestrictedDeleteError, SchemaMismatchError, TypeGraphError, UniquenessError, UnsupportedPredicateError, ValidationError, VersionConflictError, getErrorSuggestion, isConstraintError, isSystemError, isTypeGraphError, isUserRecoverable } from './chunk-O5XPCJLF.js';
+import { META_EDGE_BRAND, META_EDGE_SUB_CLASS_OF, META_EDGE_NARROWER, META_EDGE_BROADER, META_EDGE_RELATED_TO, META_EDGE_EQUIVALENT_TO, META_EDGE_SAME_AS, META_EDGE_DIFFERENT_FROM, META_EDGE_DISJOINT_WITH, META_EDGE_HAS_PART, META_EDGE_PART_OF, META_EDGE_INVERSE_OF, META_EDGE_IMPLIES, ensureSchema, computeClosuresFromOntology, createEmptyClosures, KindRegistry, validateNodeProps, validateEdgeProps } from './chunk-M5SOQ7UV.js';
+export { isMetaEdge } from './chunk-M5SOQ7UV.js';
+import { NODE_TYPE_BRAND, EDGE_TYPE_BRAND, nowIso, validateOptionalIsoDate, getNodeKinds, getEdgeKinds } from './chunk-TGDFBLGS.js';
+export { defineGraph, getEdgeKinds, getNodeKinds, isEdgeType, isEdgeTypeWithEndpoints, isGraphDef, isNodeType } from './chunk-TGDFBLGS.js';
+import { ConfigurationError, UnsupportedPredicateError, ValidationError, CompilerInvariantError, KindNotFoundError, RestrictedDeleteError, NodeNotFoundError, DatabaseOperationError, EdgeNotFoundError, NodeConstraintNotFoundError, UniquenessError, EndpointNotFoundError, CardinalityError, EndpointError, DisjointError } from './chunk-SJ2QMDXY.js';
+export { CardinalityError, CompilerInvariantError, ConfigurationError, DatabaseOperationError, DisjointError, EdgeNotFoundError, EndpointError, EndpointNotFoundError, KindNotFoundError, MigrationError, NodeConstraintNotFoundError, NodeNotFoundError, RestrictedDeleteError, SchemaMismatchError, TypeGraphError, UniquenessError, UnsupportedPredicateError, ValidationError, VersionConflictError, getErrorSuggestion, isConstraintError, isSystemError, isTypeGraphError, isUserRecoverable } from './chunk-SJ2QMDXY.js';
 import { getDialect, NODE_META_KEYS, EDGE_META_KEYS } from './chunk-54WJF3DW.js';
 import { jsonPointer, parseJsonPointer, createSchemaIntrospector, normalizeJsonPointer, joinJsonPointers, resolveFieldTypeInfoAtJsonPointer, getEmbeddingDimensions, isEmbeddingSchema } from './chunk-K7SQ3SWP.js';
 export { MAX_JSON_POINTER_DEPTH, embedding, getEmbeddingDimensions, isEmbeddingSchema, joinJsonPointers, jsonPointer, normalizeJsonPointer, parseJsonPointer } from './chunk-K7SQ3SWP.js';
@@ -8452,7 +8452,7 @@ function createEdgeCollection(config) {
       const results = await executeEdgeCreateBatch2(batchInputs, backend);
       return narrowEdges(results);
     },
-    async bulkUpsert(items) {
+    async bulkUpsertById(items) {
       if (items.length === 0) return [];
       const upsertAll = async (target) => {
         const ids = items.map((item) => item.id);
@@ -8478,7 +8478,7 @@ function createEdgeCollection(config) {
           if (existing) {
             const input = {
               id: item.id,
-              props: item.props ?? {}
+              props: item.props
             };
             if (item.validTo !== void 0) input.validTo = item.validTo;
             toUpdate.push({
@@ -8494,7 +8494,7 @@ function createEdgeCollection(config) {
               fromId: item.from.id,
               toKind: item.to.kind,
               toId: item.to.id,
-              props: item.props ?? {}
+              props: item.props
             };
             if (item.validFrom !== void 0) input.validFrom = item.validFrom;
             if (item.validTo !== void 0) input.validTo = item.validTo;
@@ -8548,6 +8548,74 @@ function createEdgeCollection(config) {
         return;
       }
       await deleteAll(backend);
+    },
+    async findByEndpoints(from, to, options) {
+      const findOptions = {};
+      if (options?.matchOn !== void 0)
+        findOptions.matchOn = options.matchOn;
+      if (options?.props !== void 0)
+        findOptions.props = options.props;
+      const result = await config.executeFindByEndpoints(
+        kind,
+        from.kind,
+        from.id,
+        to.kind,
+        to.id,
+        backend,
+        findOptions
+      );
+      return result === void 0 ? void 0 : narrowEdge(result);
+    },
+    async getOrCreateByEndpoints(from, to, props, options) {
+      const getOrCreateOptions = {};
+      if (options?.matchOn !== void 0)
+        getOrCreateOptions.matchOn = options.matchOn;
+      if (options?.ifExists !== void 0)
+        getOrCreateOptions.ifExists = options.ifExists;
+      const result = await config.executeGetOrCreateByEndpoints(
+        kind,
+        from.kind,
+        from.id,
+        to.kind,
+        to.id,
+        props,
+        backend,
+        getOrCreateOptions
+      );
+      return { edge: narrowEdge(result.edge), action: result.action };
+    },
+    async bulkGetOrCreateByEndpoints(items, options) {
+      if (items.length === 0) return [];
+      const mappedItems = items.map((item) => ({
+        fromKind: item.from.kind,
+        fromId: item.from.id,
+        toKind: item.to.kind,
+        toId: item.to.id,
+        props: item.props
+      }));
+      const getOrCreateOptions = {};
+      if (options?.matchOn !== void 0)
+        getOrCreateOptions.matchOn = options.matchOn;
+      if (options?.ifExists !== void 0)
+        getOrCreateOptions.ifExists = options.ifExists;
+      const getOrCreateAll = async (target) => {
+        const results = await config.executeBulkGetOrCreateByEndpoints(
+          kind,
+          mappedItems,
+          target,
+          getOrCreateOptions
+        );
+        return results.map((result) => ({
+          edge: narrowEdge(result.edge),
+          action: result.action
+        }));
+      };
+      if (backend.capabilities.transactions && "transaction" in backend) {
+        return backend.transaction(
+          async (txBackend) => getOrCreateAll(txBackend)
+        );
+      }
+      return getOrCreateAll(backend);
     }
   };
 }
@@ -8586,7 +8654,11 @@ function createNodeCollection(config) {
     executeDelete: executeNodeDelete2,
     executeHardDelete: executeNodeHardDelete2,
     matchesTemporalMode,
-    createQuery
+    createQuery,
+    executeGetOrCreateByConstraint,
+    executeBulkGetOrCreateByConstraint,
+    executeFindByConstraint,
+    executeBulkFindByConstraint
   } = config;
   return {
     async create(props, options) {
@@ -8696,7 +8768,7 @@ function createNodeCollection(config) {
       }
       return backend.countNodesByKind(params);
     },
-    async upsert(id, props, options) {
+    async upsertById(id, props, options) {
       const existing = await backend.getNode(graphId, kind, id);
       if (existing) {
         const input = {
@@ -8737,7 +8809,7 @@ function createNodeCollection(config) {
       const results = await executeNodeCreateBatch2(batchInputs, backend);
       return narrowNodes(results);
     },
-    async bulkUpsert(items) {
+    async bulkUpsertById(items) {
       if (items.length === 0) return [];
       const upsertAll = async (target) => {
         const ids = items.map((item) => item.id);
@@ -8834,6 +8906,68 @@ function createNodeCollection(config) {
         return;
       }
       await deleteAll(backend);
+    },
+    async findByConstraint(constraintName, props) {
+      const result = await executeFindByConstraint(
+        kind,
+        constraintName,
+        props,
+        backend
+      );
+      return result === void 0 ? void 0 : narrowNode(result);
+    },
+    async bulkFindByConstraint(constraintName, items) {
+      if (items.length === 0) return [];
+      const mappedItems = items.map((item) => ({
+        props: item.props
+      }));
+      const results = await executeBulkFindByConstraint(
+        kind,
+        constraintName,
+        mappedItems,
+        backend
+      );
+      return results.map(
+        (result) => result === void 0 ? void 0 : narrowNode(result)
+      );
+    },
+    async getOrCreateByConstraint(constraintName, props, options) {
+      const execute = async (target) => {
+        const result = await executeGetOrCreateByConstraint(
+          kind,
+          constraintName,
+          props,
+          target,
+          options
+        );
+        return result;
+      };
+      if (backend.capabilities.transactions && "transaction" in backend) {
+        return backend.transaction(async (txBackend) => execute(txBackend));
+      }
+      return execute(backend);
+    },
+    async bulkGetOrCreateByConstraint(constraintName, items, options) {
+      if (items.length === 0) return [];
+      const mappedItems = items.map((item) => ({
+        props: item.props
+      }));
+      const getOrCreateAll = async (target) => {
+        const results = await executeBulkGetOrCreateByConstraint(
+          kind,
+          constraintName,
+          mappedItems,
+          target,
+          options
+        );
+        return results;
+      };
+      if (backend.capabilities.transactions && "transaction" in backend) {
+        return backend.transaction(
+          async (txBackend) => getOrCreateAll(txBackend)
+        );
+      }
+      return getOrCreateAll(backend);
     }
   };
 }
@@ -8891,16 +9025,18 @@ function createEdgeCollectionsProxy(graph, graphId, registry, backend, operation
 }
 
 // src/constraints/index.ts
+var UNIQUE_KEY_SEPARATOR = "";
+var UNIQUE_KEY_NULL_MARKER = "";
 function computeUniqueKey(props, fields, collation) {
   const values = fields.map((field2) => {
     const value = props[field2];
     if (value === void 0 || value === null) {
-      return "\0";
+      return UNIQUE_KEY_NULL_MARKER;
     }
     const stringValue = typeof value === "string" ? value : typeof value === "number" || typeof value === "boolean" ? value.toString() : JSON.stringify(value);
     return collation === "caseInsensitive" ? stringValue.toLowerCase() : stringValue;
   });
-  return values.join("\0");
+  return values.join(UNIQUE_KEY_SEPARATOR);
 }
 function checkWherePredicate(constraint, props) {
   if (!constraint.where) {
@@ -9577,6 +9713,343 @@ async function executeEdgeHardDelete(ctx, id, backend) {
     });
   });
 }
+var RECORD_SEP = "";
+var UNIT_SEP = "";
+var UNDEFINED_SENTINEL = "";
+function validateMatchOnFields(schema, matchOn, edgeKind) {
+  if (matchOn.length === 0) return;
+  const shape = schema.shape;
+  if (shape === void 0) {
+    throw new ValidationError(
+      `Edge kind "${edgeKind}" has no schema shape to validate matchOn fields against`,
+      {
+        kind: edgeKind,
+        operation: "create",
+        issues: matchOn.map((field2) => ({
+          path: field2,
+          message: `Field "${field2}" does not exist in edge schema`
+        }))
+      }
+    );
+  }
+  const invalidFields = matchOn.filter((field2) => !(field2 in shape));
+  if (invalidFields.length > 0) {
+    throw new ValidationError(
+      `Invalid matchOn fields for edge kind "${edgeKind}": ${invalidFields.join(", ")}`,
+      {
+        kind: edgeKind,
+        operation: "create",
+        issues: invalidFields.map((field2) => ({
+          path: field2,
+          message: `Field "${field2}" does not exist in edge schema`
+        }))
+      }
+    );
+  }
+}
+function stableStringify(value) {
+  if (value === void 0) return UNDEFINED_SENTINEL;
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => stableStringify(item)).join(",")}]`;
+  }
+  const sorted = Object.keys(value).toSorted();
+  const entries = sorted.map(
+    (key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`
+  );
+  return `{${entries.join(",")}}`;
+}
+function buildEdgeCompositeKey(fromKind, fromId, toKind, toId, props, matchOn) {
+  const endpointPart = `${fromKind}${RECORD_SEP}${fromId}${RECORD_SEP}${toKind}${RECORD_SEP}${toId}`;
+  if (matchOn.length === 0) return endpointPart;
+  const sortedFields = [...matchOn].toSorted();
+  const propertyParts = sortedFields.map(
+    (field2) => `${RECORD_SEP}${field2}${UNIT_SEP}${stableStringify(props[field2])}`
+  );
+  return endpointPart + propertyParts.join("");
+}
+function buildEndpointPairKey(fromKind, fromId, toKind, toId) {
+  return `${fromKind}${RECORD_SEP}${fromId}${RECORD_SEP}${toKind}${RECORD_SEP}${toId}`;
+}
+function findMatchingEdge(rows, matchOn, inputProps) {
+  let liveRow;
+  let deletedRow;
+  for (const row of rows) {
+    if (matchOn.length > 0) {
+      const rowProps = JSON.parse(row.props);
+      const matches = matchOn.every(
+        (field2) => stableStringify(rowProps[field2]) === stableStringify(inputProps[field2])
+      );
+      if (!matches) continue;
+    }
+    if (row.deleted_at === void 0) {
+      liveRow ??= row;
+    } else {
+      deletedRow ??= row;
+    }
+    if (liveRow !== void 0) break;
+  }
+  return { liveRow, deletedRow };
+}
+async function executeEdgeFindByEndpoints(ctx, kind, fromKind, fromId, toKind, toId, backend, options) {
+  const matchOn = options?.matchOn ?? [];
+  const props = options?.props ?? {};
+  const registration = getEdgeRegistration(ctx.graph, kind);
+  const edgeKind = registration.type;
+  if (matchOn.length > 0) {
+    validateMatchOnFields(edgeKind.schema, matchOn, kind);
+  }
+  const candidateRows = await backend.findEdgesByKind({
+    graphId: ctx.graphId,
+    kind,
+    fromKind,
+    fromId,
+    toKind,
+    toId,
+    excludeDeleted: true
+  });
+  if (candidateRows.length === 0) return void 0;
+  if (matchOn.length === 0) return rowToEdge(candidateRows[0]);
+  const { liveRow } = findMatchingEdge(candidateRows, matchOn, props);
+  return liveRow === void 0 ? void 0 : rowToEdge(liveRow);
+}
+async function executeEdgeGetOrCreateByEndpoints(ctx, kind, fromKind, fromId, toKind, toId, props, backend, options) {
+  const ifExists = options?.ifExists ?? "return";
+  const matchOn = options?.matchOn ?? [];
+  const registration = getEdgeRegistration(ctx.graph, kind);
+  const edgeKind = registration.type;
+  const validatedProps = validateEdgeProps(edgeKind.schema, props, {
+    kind,
+    operation: "create"
+  });
+  validateMatchOnFields(edgeKind.schema, matchOn, kind);
+  const candidateRows = await backend.findEdgesByKind({
+    graphId: ctx.graphId,
+    kind,
+    fromKind,
+    fromId,
+    toKind,
+    toId,
+    excludeDeleted: false,
+    temporalMode: "includeTombstones"
+  });
+  const { liveRow, deletedRow } = findMatchingEdge(
+    candidateRows,
+    matchOn,
+    validatedProps
+  );
+  if (liveRow === void 0 && deletedRow === void 0) {
+    const input = {
+      kind,
+      fromKind,
+      fromId,
+      toKind,
+      toId,
+      props: validatedProps
+    };
+    const edge2 = await executeEdgeCreate(ctx, input, backend);
+    return { edge: edge2, action: "created" };
+  }
+  if (liveRow !== void 0) {
+    if (ifExists === "return") {
+      return { edge: rowToEdge(liveRow), action: "found" };
+    }
+    const edge2 = await executeEdgeUpsertUpdate(
+      ctx,
+      { id: liveRow.id, props: validatedProps },
+      backend
+    );
+    return { edge: edge2, action: "updated" };
+  }
+  const cardinality = registration.cardinality ?? "many";
+  const matchedDeletedRow = deletedRow;
+  const effectiveValidTo = matchedDeletedRow.valid_to;
+  const constraintContext = {
+    graphId: ctx.graphId,
+    registry: ctx.registry,
+    backend
+  };
+  await checkCardinalityConstraint(
+    constraintContext,
+    kind,
+    cardinality,
+    fromKind,
+    fromId,
+    toKind,
+    toId,
+    effectiveValidTo
+  );
+  const edge = await executeEdgeUpsertUpdate(
+    ctx,
+    { id: matchedDeletedRow.id, props: validatedProps },
+    backend,
+    { clearDeleted: true }
+  );
+  return { edge, action: "resurrected" };
+}
+async function executeEdgeBulkGetOrCreateByEndpoints(ctx, kind, items, backend, options) {
+  if (items.length === 0) return [];
+  const ifExists = options?.ifExists ?? "return";
+  const matchOn = options?.matchOn ?? [];
+  const registration = getEdgeRegistration(ctx.graph, kind);
+  const edgeKind = registration.type;
+  const cardinality = registration.cardinality ?? "many";
+  validateMatchOnFields(edgeKind.schema, matchOn, kind);
+  const validated = [];
+  for (const item of items) {
+    const validatedProps = validateEdgeProps(edgeKind.schema, item.props, {
+      kind,
+      operation: "create"
+    });
+    const compositeKey = buildEdgeCompositeKey(
+      item.fromKind,
+      item.fromId,
+      item.toKind,
+      item.toId,
+      validatedProps,
+      matchOn
+    );
+    const endpointKey = buildEndpointPairKey(
+      item.fromKind,
+      item.fromId,
+      item.toKind,
+      item.toId
+    );
+    validated.push({
+      fromKind: item.fromKind,
+      fromId: item.fromId,
+      toKind: item.toKind,
+      toId: item.toId,
+      validatedProps,
+      compositeKey,
+      endpointKey
+    });
+  }
+  const uniqueEndpoints = /* @__PURE__ */ new Map();
+  for (const entry of validated) {
+    if (!uniqueEndpoints.has(entry.endpointKey)) {
+      uniqueEndpoints.set(entry.endpointKey, {
+        fromKind: entry.fromKind,
+        fromId: entry.fromId,
+        toKind: entry.toKind,
+        toId: entry.toId
+      });
+    }
+  }
+  const rowsByEndpoint = /* @__PURE__ */ new Map();
+  for (const [endpointKey, endpoint] of uniqueEndpoints) {
+    const rows = await backend.findEdgesByKind({
+      graphId: ctx.graphId,
+      kind,
+      fromKind: endpoint.fromKind,
+      fromId: endpoint.fromId,
+      toKind: endpoint.toKind,
+      toId: endpoint.toId,
+      excludeDeleted: false,
+      temporalMode: "includeTombstones"
+    });
+    rowsByEndpoint.set(endpointKey, rows);
+  }
+  const toCreate = [];
+  const toFetch = [];
+  const duplicateOf = [];
+  const seenKeys = /* @__PURE__ */ new Map();
+  for (const [index, entry] of validated.entries()) {
+    const previousIndex = seenKeys.get(entry.compositeKey);
+    if (previousIndex !== void 0) {
+      duplicateOf.push({ index, sourceIndex: previousIndex });
+      continue;
+    }
+    seenKeys.set(entry.compositeKey, index);
+    const candidateRows = rowsByEndpoint.get(entry.endpointKey) ?? [];
+    const { liveRow, deletedRow } = findMatchingEdge(
+      candidateRows,
+      matchOn,
+      entry.validatedProps
+    );
+    if (liveRow === void 0 && deletedRow === void 0) {
+      toCreate.push({
+        index,
+        input: {
+          kind,
+          fromKind: entry.fromKind,
+          fromId: entry.fromId,
+          toKind: entry.toKind,
+          toId: entry.toId,
+          props: entry.validatedProps
+        }
+      });
+    } else {
+      const bestRow = liveRow ?? deletedRow;
+      toFetch.push({
+        index,
+        row: bestRow,
+        isDeleted: liveRow === void 0,
+        validatedProps: entry.validatedProps,
+        fromKind: entry.fromKind,
+        fromId: entry.fromId,
+        toKind: entry.toKind,
+        toId: entry.toId
+      });
+    }
+  }
+  const results = Array.from({ length: items.length });
+  if (toCreate.length > 0) {
+    const createInputs = toCreate.map((entry) => entry.input);
+    const createdEdges = await executeEdgeCreateBatch(
+      ctx,
+      createInputs,
+      backend
+    );
+    for (const [batchIndex, entry] of toCreate.entries()) {
+      results[entry.index] = {
+        edge: createdEdges[batchIndex],
+        action: "created"
+      };
+    }
+  }
+  for (const entry of toFetch) {
+    if (entry.isDeleted) {
+      const effectiveValidTo = entry.row.valid_to;
+      const constraintContext = {
+        graphId: ctx.graphId,
+        registry: ctx.registry,
+        backend
+      };
+      await checkCardinalityConstraint(
+        constraintContext,
+        kind,
+        cardinality,
+        entry.fromKind,
+        entry.fromId,
+        entry.toKind,
+        entry.toId,
+        effectiveValidTo
+      );
+      const edge = await executeEdgeUpsertUpdate(
+        ctx,
+        { id: entry.row.id, props: entry.validatedProps },
+        backend,
+        { clearDeleted: true }
+      );
+      results[entry.index] = { edge, action: "resurrected" };
+    } else if (ifExists === "update") {
+      const edge = await executeEdgeUpsertUpdate(
+        ctx,
+        { id: entry.row.id, props: entry.validatedProps },
+        backend
+      );
+      results[entry.index] = { edge, action: "updated" };
+    } else {
+      results[entry.index] = { edge: rowToEdge(entry.row), action: "found" };
+    }
+  }
+  for (const { index, sourceIndex } of duplicateOf) {
+    const sourceResult = results[sourceIndex];
+    results[index] = { edge: sourceResult.edge, action: "found" };
+  }
+  return results;
+}
 
 // src/store/embedding-sync.ts
 function getEmbeddingFields(schema) {
@@ -10359,6 +10832,371 @@ async function executeNodeHardDelete(ctx, kind, id, backend) {
     await ("transaction" in backend && backend.capabilities.transactions ? backend.transaction(async (tx) => hardDelete(tx)) : hardDelete(backend));
   });
 }
+function resolveConstraint(graph, kind, constraintName) {
+  const registration = getNodeRegistration(graph, kind);
+  const constraints = registration.unique ?? [];
+  const constraint = constraints.find((c) => c.name === constraintName);
+  if (constraint === void 0) {
+    throw new NodeConstraintNotFoundError(constraintName, kind);
+  }
+  return constraint;
+}
+async function executeNodeGetOrCreateByConstraint(ctx, kind, constraintName, props, backend, options) {
+  const ifExists = options?.ifExists ?? "return";
+  const registration = getNodeRegistration(ctx.graph, kind);
+  const nodeKind = registration.type;
+  const validatedProps = validateNodeProps(nodeKind.schema, props, {
+    kind,
+    operation: "create"
+  });
+  const constraint = resolveConstraint(ctx.graph, kind, constraintName);
+  if (!checkWherePredicate(constraint, validatedProps)) {
+    const input = { kind, props: validatedProps };
+    const node = await executeNodeCreate(ctx, input, backend);
+    return { node, action: "created" };
+  }
+  const key = computeUniqueKey(
+    validatedProps,
+    constraint.fields,
+    constraint.collation
+  );
+  const kindsToCheck = getKindsForUniquenessCheck(
+    kind,
+    constraint.scope,
+    ctx.registry
+  );
+  let existingUniqueRow;
+  for (const kindToCheck of kindsToCheck) {
+    const row = await backend.checkUnique({
+      graphId: ctx.graphId,
+      nodeKind: kindToCheck,
+      constraintName: constraint.name,
+      key,
+      includeDeleted: true
+    });
+    if (row !== void 0) {
+      existingUniqueRow = row;
+      break;
+    }
+  }
+  if (existingUniqueRow === void 0) {
+    const input = { kind, props: validatedProps };
+    const node = await executeNodeCreate(ctx, input, backend);
+    return { node, action: "created" };
+  }
+  const existingRow = await backend.getNode(
+    ctx.graphId,
+    existingUniqueRow.concrete_kind,
+    existingUniqueRow.node_id
+  );
+  if (existingRow === void 0) {
+    const input = { kind, props: validatedProps };
+    const node = await executeNodeCreate(ctx, input, backend);
+    return { node, action: "created" };
+  }
+  const isSoftDeleted = existingRow.deleted_at !== void 0;
+  if (isSoftDeleted || ifExists === "update") {
+    const concreteKind = existingUniqueRow.concrete_kind;
+    const node = await executeNodeUpsertUpdate(
+      ctx,
+      {
+        kind: concreteKind,
+        id: existingRow.id,
+        props: validatedProps
+      },
+      backend,
+      { clearDeleted: isSoftDeleted }
+    );
+    return { node, action: isSoftDeleted ? "resurrected" : "updated" };
+  }
+  return { node: rowToNode(existingRow), action: "found" };
+}
+async function executeNodeFindByConstraint(ctx, kind, constraintName, props, backend) {
+  const registration = getNodeRegistration(ctx.graph, kind);
+  const nodeKind = registration.type;
+  const validatedProps = validateNodeProps(nodeKind.schema, props, {
+    kind,
+    operation: "create"
+  });
+  const constraint = resolveConstraint(ctx.graph, kind, constraintName);
+  if (!checkWherePredicate(constraint, validatedProps)) return void 0;
+  const key = computeUniqueKey(
+    validatedProps,
+    constraint.fields,
+    constraint.collation
+  );
+  const kindsToCheck = getKindsForUniquenessCheck(
+    kind,
+    constraint.scope,
+    ctx.registry
+  );
+  let existingUniqueRow;
+  for (const kindToCheck of kindsToCheck) {
+    const row = await backend.checkUnique({
+      graphId: ctx.graphId,
+      nodeKind: kindToCheck,
+      constraintName: constraint.name,
+      key,
+      includeDeleted: false
+    });
+    if (row !== void 0) {
+      existingUniqueRow = row;
+      break;
+    }
+  }
+  if (existingUniqueRow === void 0) return void 0;
+  const existingRow = await backend.getNode(
+    ctx.graphId,
+    existingUniqueRow.concrete_kind,
+    existingUniqueRow.node_id
+  );
+  if (existingRow === void 0 || existingRow.deleted_at !== void 0)
+    return void 0;
+  return rowToNode(existingRow);
+}
+async function executeNodeBulkFindByConstraint(ctx, kind, constraintName, items, backend) {
+  if (items.length === 0) return [];
+  const registration = getNodeRegistration(ctx.graph, kind);
+  const nodeKind = registration.type;
+  const constraint = resolveConstraint(ctx.graph, kind, constraintName);
+  const validated = [];
+  for (const item of items) {
+    const validatedProps = validateNodeProps(nodeKind.schema, item.props, {
+      kind,
+      operation: "create"
+    });
+    const applies = checkWherePredicate(constraint, validatedProps);
+    const key = applies ? computeUniqueKey(
+      validatedProps,
+      constraint.fields,
+      constraint.collation
+    ) : void 0;
+    validated.push({ validatedProps, key });
+  }
+  const uniqueKeys = [
+    ...new Set(
+      validated.map((v) => v.key).filter((k) => k !== void 0)
+    )
+  ];
+  const kindsToCheck = getKindsForUniquenessCheck(
+    kind,
+    constraint.scope,
+    ctx.registry
+  );
+  const existingByKey = /* @__PURE__ */ new Map();
+  if (uniqueKeys.length > 0) {
+    for (const kindToCheck of kindsToCheck) {
+      if (backend.checkUniqueBatch === void 0) {
+        for (const key of uniqueKeys) {
+          if (existingByKey.has(key)) continue;
+          const row = await backend.checkUnique({
+            graphId: ctx.graphId,
+            nodeKind: kindToCheck,
+            constraintName: constraint.name,
+            key,
+            includeDeleted: false
+          });
+          if (row !== void 0) {
+            existingByKey.set(row.key, row);
+          }
+        }
+      } else {
+        const rows = await backend.checkUniqueBatch({
+          graphId: ctx.graphId,
+          nodeKind: kindToCheck,
+          constraintName: constraint.name,
+          keys: uniqueKeys,
+          includeDeleted: false
+        });
+        for (const row of rows) {
+          if (!existingByKey.has(row.key)) {
+            existingByKey.set(row.key, row);
+          }
+        }
+      }
+    }
+  }
+  const results = Array.from({ length: items.length });
+  const seenKeys = /* @__PURE__ */ new Map();
+  for (const [index, { key }] of validated.entries()) {
+    if (key === void 0) {
+      results[index] = void 0;
+      continue;
+    }
+    const previousIndex = seenKeys.get(key);
+    if (previousIndex !== void 0) {
+      results[index] = results[previousIndex];
+      continue;
+    }
+    seenKeys.set(key, index);
+    const existing = existingByKey.get(key);
+    if (existing === void 0) {
+      results[index] = void 0;
+      continue;
+    }
+    const existingRow = await backend.getNode(
+      ctx.graphId,
+      existing.concrete_kind,
+      existing.node_id
+    );
+    if (existingRow === void 0 || existingRow.deleted_at !== void 0) {
+      results[index] = void 0;
+      continue;
+    }
+    results[index] = rowToNode(existingRow);
+  }
+  return results;
+}
+async function executeNodeBulkGetOrCreateByConstraint(ctx, kind, constraintName, items, backend, options) {
+  if (items.length === 0) return [];
+  const ifExists = options?.ifExists ?? "return";
+  const registration = getNodeRegistration(ctx.graph, kind);
+  const nodeKind = registration.type;
+  const constraint = resolveConstraint(ctx.graph, kind, constraintName);
+  const validated = [];
+  for (const item of items) {
+    const validatedProps = validateNodeProps(nodeKind.schema, item.props, {
+      kind,
+      operation: "create"
+    });
+    const applies = checkWherePredicate(constraint, validatedProps);
+    const key = applies ? computeUniqueKey(
+      validatedProps,
+      constraint.fields,
+      constraint.collation
+    ) : void 0;
+    validated.push({ validatedProps, key });
+  }
+  const uniqueKeys = [
+    ...new Set(
+      validated.map((v) => v.key).filter((k) => k !== void 0)
+    )
+  ];
+  const kindsToCheck = getKindsForUniquenessCheck(
+    kind,
+    constraint.scope,
+    ctx.registry
+  );
+  const existingByKey = /* @__PURE__ */ new Map();
+  if (uniqueKeys.length > 0) {
+    for (const kindToCheck of kindsToCheck) {
+      if (backend.checkUniqueBatch === void 0) {
+        for (const key of uniqueKeys) {
+          if (existingByKey.has(key)) continue;
+          const row = await backend.checkUnique({
+            graphId: ctx.graphId,
+            nodeKind: kindToCheck,
+            constraintName: constraint.name,
+            key,
+            includeDeleted: true
+          });
+          if (row !== void 0) {
+            existingByKey.set(row.key, row);
+          }
+        }
+      } else {
+        const rows = await backend.checkUniqueBatch({
+          graphId: ctx.graphId,
+          nodeKind: kindToCheck,
+          constraintName: constraint.name,
+          keys: uniqueKeys,
+          includeDeleted: true
+        });
+        for (const row of rows) {
+          if (!existingByKey.has(row.key)) {
+            existingByKey.set(row.key, row);
+          }
+        }
+      }
+    }
+  }
+  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,
+      backend
+    );
+    for (const [batchIndex, entry] of toCreate.entries()) {
+      results[entry.index] = {
+        node: 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 input = { kind, props: validatedProps };
+      const node = await executeNodeCreate(ctx, input, backend);
+      results[index] = { node, action: "created" };
+      continue;
+    }
+    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 = results[sourceIndex];
+    results[index] = { node: sourceResult.node, action: "found" };
+  }
+  return results;
+}
 
 // src/store/store.ts
 var Store = class {
@@ -10472,7 +11310,31 @@ var Store = class {
       executeDelete: (kind, id, backend) => executeNodeDelete(ctx, kind, id, backend),
       executeHardDelete: (kind, id, backend) => executeNodeHardDelete(ctx, kind, id, backend),
       matchesTemporalMode: (row, options) => this.#matchesTemporalMode(row, options),
-      createQuery: () => this.query()
+      createQuery: () => this.query(),
+      executeGetOrCreateByConstraint: (kind, constraintName, props, backend, options) => executeNodeGetOrCreateByConstraint(
+        ctx,
+        kind,
+        constraintName,
+        props,
+        backend,
+        options
+      ),
+      executeBulkGetOrCreateByConstraint: (kind, constraintName, items, backend, options) => executeNodeBulkGetOrCreateByConstraint(
+        ctx,
+        kind,
+        constraintName,
+        items,
+        backend,
+        options
+      ),
+      executeFindByConstraint: (kind, constraintName, props, backend) => executeNodeFindByConstraint(ctx, kind, constraintName, props, backend),
+      executeBulkFindByConstraint: (kind, constraintName, items, backend) => executeNodeBulkFindByConstraint(
+        ctx,
+        kind,
+        constraintName,
+        items,
+        backend
+      )
     };
   }
   /**
@@ -10491,7 +11353,35 @@ var Store = class {
       executeDelete: (id, backend) => executeEdgeDelete(ctx, id, backend),
       executeHardDelete: (id, backend) => executeEdgeHardDelete(ctx, id, backend),
       matchesTemporalMode: (row, options) => this.#matchesTemporalMode(row, options),
-      createQuery: () => this.query()
+      createQuery: () => this.query(),
+      executeGetOrCreateByEndpoints: (kind, fromKind, fromId, toKind, toId, props, backend, options) => executeEdgeGetOrCreateByEndpoints(
+        ctx,
+        kind,
+        fromKind,
+        fromId,
+        toKind,
+        toId,
+        props,
+        backend,
+        options
+      ),
+      executeBulkGetOrCreateByEndpoints: (kind, items, backend, options) => executeEdgeBulkGetOrCreateByEndpoints(
+        ctx,
+        kind,
+        items,
+        backend,
+        options
+      ),
+      executeFindByEndpoints: (kind, fromKind, fromId, toKind, toId, backend, options) => executeEdgeFindByEndpoints(
+        ctx,
+        kind,
+        fromKind,
+        fromId,
+        toKind,
+        toId,
+        backend,
+        options
+      )
     };
   }
   // === Query Builder ===
@@ -10558,6 +11448,24 @@ var Store = class {
       return fn({ nodes, edges });
     });
   }
+  // === Graph Lifecycle ===
+  /**
+   * Hard-deletes all data for this graph from the database.
+   *
+   * Removes all nodes, edges, uniqueness entries, embeddings, and schema versions
+   * for this graph's ID. No hooks, no per-row logic. Wrapped in a transaction
+   * when the backend supports it.
+   *
+   * The store is usable after clearing — new data can be created immediately.
+   */
+  async clear() {
+    const doClear = async (target) => {
+      await target.clearGraph(this.graphId);
+    };
+    await (this.#backend.capabilities.transactions ? this.#backend.transaction(async (tx) => doClear(tx)) : doClear(this.#backend));
+    this.#nodeCollections = void 0;
+    this.#edgeCollections = void 0;
+  }
   // === Lifecycle ===
   /**
    * Closes the store and releases underlying resources.