@typicalday/firegraph 0.11.2 → 0.13.0

package/dist/{chunk-NJSOD64C.js → chunk-WRTFC5NG.js}

@@ -6,8 +6,10 @@ import {
   QuerySafetyError,
   RegistryScopeError,
   RegistryViolationError,
-  ValidationError
-} from "./chunk-R7CRGYY4.js";
+  ValidationError,
+  assertNoDeleteSentinels,
+  flattenPatch
+} from "./chunk-TK64DNVK.js";
 
 // src/internal/constants.ts
 var NODE_RELATION = "is";
@@ -649,7 +651,7 @@ function hashSource(source) {
 var _serializationModule = null;
 async function loadSerialization() {
   if (_serializationModule) return _serializationModule;
-  _serializationModule = await import("./serialization-ZZ7RSDRX.js");
+  _serializationModule = await import("./serialization-OE2PFZMY.js");
   return _serializationModule;
 }
 function defaultExecutor(source) {
@@ -969,6 +971,19 @@ var GraphBatchImpl = class {
     this.scopePath = scopePath;
   }
   async putNode(aType, uid, data) {
+    this.writeNode(aType, uid, data, "merge");
+  }
+  async putEdge(aType, aUid, axbType, bType, bUid, data) {
+    this.writeEdge(aType, aUid, axbType, bType, bUid, data, "merge");
+  }
+  async replaceNode(aType, uid, data) {
+    this.writeNode(aType, uid, data, "replace");
+  }
+  async replaceEdge(aType, aUid, axbType, bType, bUid, data) {
+    this.writeEdge(aType, aUid, axbType, bType, bUid, data, "replace");
+  }
+  writeNode(aType, uid, data, mode) {
+    assertNoDeleteSentinels(data, mode === "replace" ? "replaceNode" : "putNode");
     if (this.registry) {
       this.registry.validate(aType, NODE_RELATION, aType, data, this.scopePath);
     }
@@ -980,9 +995,10 @@ var GraphBatchImpl = class {
         record.v = entry.schemaVersion;
       }
     }
-    this.backend.setDoc(docId, record);
+    this.backend.setDoc(docId, record, mode);
   }
-  async putEdge(aType, aUid, axbType, bType, bUid, data) {
+  writeEdge(aType, aUid, axbType, bType, bUid, data, mode) {
+    assertNoDeleteSentinels(data, mode === "replace" ? "replaceEdge" : "putEdge");
     if (this.registry) {
       this.registry.validate(aType, axbType, bType, data, this.scopePath);
     }
@@ -994,11 +1010,15 @@ var GraphBatchImpl = class {
         record.v = entry.schemaVersion;
       }
     }
-    this.backend.setDoc(docId, record);
+    this.backend.setDoc(docId, record, mode);
   }
   async updateNode(uid, data) {
     const docId = computeNodeDocId(uid);
-    this.backend.updateDoc(docId, { dataFields: data });
+    this.backend.updateDoc(docId, { dataOps: flattenPatch(data) });
+  }
+  async updateEdge(aUid, axbType, bUid, data) {
+    const docId = computeEdgeDocId(aUid, axbType, bUid);
+    this.backend.updateDoc(docId, { dataOps: flattenPatch(data) });
   }
   async removeNode(uid) {
     const docId = computeNodeDocId(uid);
@@ -1107,6 +1127,19 @@ var GraphTransactionImpl = class {
     return results.map((r) => r.record);
   }
   async putNode(aType, uid, data) {
+    await this.writeNode(aType, uid, data, "merge");
+  }
+  async putEdge(aType, aUid, axbType, bType, bUid, data) {
+    await this.writeEdge(aType, aUid, axbType, bType, bUid, data, "merge");
+  }
+  async replaceNode(aType, uid, data) {
+    await this.writeNode(aType, uid, data, "replace");
+  }
+  async replaceEdge(aType, aUid, axbType, bType, bUid, data) {
+    await this.writeEdge(aType, aUid, axbType, bType, bUid, data, "replace");
+  }
+  async writeNode(aType, uid, data, mode) {
+    assertNoDeleteSentinels(data, mode === "replace" ? "replaceNode" : "putNode");
     if (this.registry) {
       this.registry.validate(aType, NODE_RELATION, aType, data, this.scopePath);
     }
@@ -1118,9 +1151,10 @@ var GraphTransactionImpl = class {
         record.v = entry.schemaVersion;
       }
     }
-    await this.backend.setDoc(docId, record);
+    await this.backend.setDoc(docId, record, mode);
   }
-  async putEdge(aType, aUid, axbType, bType, bUid, data) {
+  async writeEdge(aType, aUid, axbType, bType, bUid, data, mode) {
+    assertNoDeleteSentinels(data, mode === "replace" ? "replaceEdge" : "putEdge");
     if (this.registry) {
       this.registry.validate(aType, axbType, bType, data, this.scopePath);
     }
@@ -1132,11 +1166,15 @@ var GraphTransactionImpl = class {
         record.v = entry.schemaVersion;
       }
     }
-    await this.backend.setDoc(docId, record);
+    await this.backend.setDoc(docId, record, mode);
   }
   async updateNode(uid, data) {
     const docId = computeNodeDocId(uid);
-    await this.backend.updateDoc(docId, { dataFields: data });
+    await this.backend.updateDoc(docId, { dataOps: flattenPatch(data) });
+  }
+  async updateEdge(aUid, axbType, bUid, data) {
+    const docId = computeEdgeDocId(aUid, axbType, bUid);
+    await this.backend.updateDoc(docId, { dataOps: flattenPatch(data) });
   }
   async removeNode(uid) {
     const docId = computeNodeDocId(uid);
@@ -1174,6 +1212,15 @@ var GraphClientImpl = class _GraphClientImpl {
     this.scanProtection = options?.scanProtection ?? "error";
   }
   scanProtection;
+  /**
+   * Capability set of the underlying backend. Mirrors `backend.capabilities`
+   * verbatim so callers can portability-check (`client.capabilities.has(
+   * 'query.join')`) without reaching for the backend handle. Static for the
+   * lifetime of the client.
+   */
+  get capabilities() {
+    return this.backend.capabilities;
+  }
   // Static mode
   staticRegistry;
   // Dynamic mode
@@ -1335,6 +1382,19 @@ var GraphClientImpl = class _GraphClientImpl {
   // GraphWriter
   // ---------------------------------------------------------------------------
   async putNode(aType, uid, data) {
+    await this.writeNode(aType, uid, data, "merge");
+  }
+  async putEdge(aType, aUid, axbType, bType, bUid, data) {
+    await this.writeEdge(aType, aUid, axbType, bType, bUid, data, "merge");
+  }
+  async replaceNode(aType, uid, data) {
+    await this.writeNode(aType, uid, data, "replace");
+  }
+  async replaceEdge(aType, aUid, axbType, bType, bUid, data) {
+    await this.writeEdge(aType, aUid, axbType, bType, bUid, data, "replace");
+  }
+  async writeNode(aType, uid, data, mode) {
+    assertNoDeleteSentinels(data, mode === "replace" ? "replaceNode" : "putNode");
     const registry = this.getRegistryForType(aType);
     if (registry) {
       registry.validate(aType, NODE_RELATION, aType, data, this.backend.scopePath);
@@ -1348,9 +1408,10 @@ var GraphClientImpl = class _GraphClientImpl {
         record.v = entry.schemaVersion;
       }
     }
-    await backend.setDoc(docId, record);
+    await backend.setDoc(docId, record, mode);
   }
-  async putEdge(aType, aUid, axbType, bType, bUid, data) {
+  async writeEdge(aType, aUid, axbType, bType, bUid, data, mode) {
+    assertNoDeleteSentinels(data, mode === "replace" ? "replaceEdge" : "putEdge");
     const registry = this.getRegistryForType(aType);
     if (registry) {
       registry.validate(aType, axbType, bType, data, this.backend.scopePath);
@@ -1364,11 +1425,15 @@ var GraphClientImpl = class _GraphClientImpl {
         record.v = entry.schemaVersion;
       }
     }
-    await backend.setDoc(docId, record);
+    await backend.setDoc(docId, record, mode);
   }
   async updateNode(uid, data) {
     const docId = computeNodeDocId(uid);
-    await this.backend.updateDoc(docId, { dataFields: data });
+    await this.backend.updateDoc(docId, { dataOps: flattenPatch(data) });
+  }
+  async updateEdge(aUid, axbType, bUid, data) {
+    const docId = computeEdgeDocId(aUid, axbType, bUid);
+    await this.backend.updateDoc(docId, { dataOps: flattenPatch(data) });
   }
   async removeNode(uid) {
     const docId = computeNodeDocId(uid);
@@ -1450,6 +1515,33 @@ var GraphClientImpl = class _GraphClientImpl {
     return this.applyMigrations(records);
   }
   // ---------------------------------------------------------------------------
+  // Aggregate query (capability: query.aggregate)
+  // ---------------------------------------------------------------------------
+  async aggregate(params) {
+    if (!this.backend.aggregate) {
+      throw new FiregraphError(
+        "aggregate() is not supported by the current storage backend.",
+        "UNSUPPORTED_OPERATION"
+      );
+    }
+    const hasAnyFilter = params.aType || params.aUid || params.axbType || params.bType || params.bUid || params.where && params.where.length > 0;
+    if (!hasAnyFilter) {
+      this.checkQuerySafety([], params.allowCollectionScan);
+      const result2 = await this.backend.aggregate(params.aggregates, []);
+      return result2;
+    }
+    const plan = buildEdgeQueryPlan(params);
+    if (plan.strategy === "get") {
+      throw new FiregraphError(
+        "aggregate() requires a query, not a direct document lookup. Omit one of aUid/axbType/bUid to force a query strategy.",
+        "INVALID_QUERY"
+      );
+    }
+    this.checkQuerySafety(plan.filters, params.allowCollectionScan);
+    const result = await this.backend.aggregate(params.aggregates, plan.filters);
+    return result;
+  }
+  // ---------------------------------------------------------------------------
   // Bulk operations
   // ---------------------------------------------------------------------------
   async removeNodeCascade(uid, options) {
@@ -1459,6 +1551,327 @@ var GraphClientImpl = class _GraphClientImpl {
     return this.backend.bulkRemoveEdges(params, this, options);
   }
   // ---------------------------------------------------------------------------
+  // Server-side DML (capability: query.dml)
+  // ---------------------------------------------------------------------------
+  /**
+   * Single-statement bulk DELETE. Translates `params` to a filter list via
+   * `buildEdgeQueryPlan` (the same plan `findEdges` uses) and dispatches to
+   * `backend.bulkDelete`. The fetch-then-delete loop in `bulkRemoveEdges`
+   * is the cap-less fallback; this method is the fast path on backends
+   * declaring `query.dml`.
+   *
+   * Scan-protection rules match `findEdges`: a query with no identifying
+   * fields requires `allowCollectionScan: true` to pass. A bare-empty
+   * filter set (no `aType`, `aUid`, etc., no `where`) is allowed at this
+   * layer — shared SQLite bounds the blast radius via its leading `scope`
+   * predicate — but the DO RPC backend rejects empty filters at the wire
+   * boundary as defense-in-depth. To wipe a routed subgraph DO, use
+   * `removeNodeCascade` on the parent node instead.
+   */
+  async bulkDelete(params, options) {
+    if (!this.backend.bulkDelete) {
+      throw new FiregraphError(
+        "bulkDelete() is not supported by the current storage backend. Fall back to bulkRemoveEdges() for backends without query.dml (e.g. Firestore Standard).",
+        "UNSUPPORTED_OPERATION"
+      );
+    }
+    const filters = this.buildDmlFilters(params);
+    return this.backend.bulkDelete(filters, options);
+  }
+  /**
+   * Single-statement bulk UPDATE. Same translation path as `bulkDelete`,
+   * but the patch is deep-merged into each matching row's `data` via the
+   * shared `flattenPatch` pipeline. Identifying columns are immutable
+   * through this path (see `BulkUpdatePatch` JSDoc).
+   *
+   * Empty-patch rejection happens inside the backend (`compileBulkUpdate`)
+   * — a `data: {}` payload would only rewrite `updated_at`, which is
+   * almost certainly a bug.
+   */
+  async bulkUpdate(params, patch, options) {
+    if (!this.backend.bulkUpdate) {
+      throw new FiregraphError(
+        "bulkUpdate() is not supported by the current storage backend.",
+        "UNSUPPORTED_OPERATION"
+      );
+    }
+    const filters = this.buildDmlFilters(params);
+    return this.backend.bulkUpdate(filters, patch, options);
+  }
+  // ---------------------------------------------------------------------------
+  // Multi-source fan-out (capability: query.join)
+  // ---------------------------------------------------------------------------
+  /**
+   * Fan out from `params.sources` over a single edge type in one round trip.
+   * On backends without `query.join`, throws `UNSUPPORTED_OPERATION` — the
+   * cap-less fallback is the per-source `findEdges` loop, which lives in
+   * `traverse.ts` (the higher-level traversal walker) rather than here.
+   *
+   * `expand()` is intentionally edge-type-only — the source set is a flat
+   * UID list and the hop matches one `axbType`. Multi-axbType expansions
+   * become multiple `expand()` calls, one per relation.
+   *
+   * `params.sources.length === 0` short-circuits to an empty result. The
+   * backend never sees the call. (`compileExpand` itself rejects empty
+   * because `IN ()` is not valid SQL.)
+   */
+  async expand(params) {
+    if (!this.backend.expand) {
+      throw new FiregraphError(
+        "expand() is not supported by the current storage backend. Backends without `query.join` can use createTraversal() instead \u2014 the per-hop loop is functionally equivalent (just slower).",
+        "UNSUPPORTED_OPERATION"
+      );
+    }
+    if (params.sources.length === 0) {
+      return params.hydrate ? { edges: [], targets: [] } : { edges: [] };
+    }
+    return this.backend.expand(params);
+  }
+  // ---------------------------------------------------------------------------
+  // Engine-level multi-hop traversal (capability: traversal.serverSide)
+  // ---------------------------------------------------------------------------
+  /**
+   * Compile a multi-hop traversal spec into one server-side nested
+   * Pipeline and dispatch a single round trip.
+   *
+   * Backends declaring `traversal.serverSide` (Firestore Enterprise
+   * today) install this method; everywhere else, it throws
+   * `UNSUPPORTED_OPERATION`. The capability gate matches the type-level
+   * surface — `GraphClient<C>` only exposes `runEngineTraversal` when
+   * `'traversal.serverSide' extends C`.
+   *
+   * Most callers should not invoke this method directly; the
+   * `createTraversal(...).run()` builder routes through it
+   * automatically when `engineTraversal: 'auto'` (the default) and
+   * the spec is eligible per `firestore-traverse-compiler.ts`. Calling
+   * directly is appropriate for benchmarking or for callers that have
+   * already shaped their hop chain into the strict
+   * `EngineTraversalParams` shape.
+   *
+   * `params.sources.length === 0` short-circuits to empty per-hop
+   * arrays. The backend never sees the call.
+   */
+  async runEngineTraversal(params) {
+    if (!this.backend.runEngineTraversal) {
+      throw new FiregraphError(
+        "runEngineTraversal() is not supported by the current storage backend. Backends without `traversal.serverSide` can use createTraversal() instead \u2014 the per-hop loop is functionally equivalent for in-graph specs (different round-trip profile).",
+        "UNSUPPORTED_OPERATION"
+      );
+    }
+    if (params.sources.length === 0) {
+      return {
+        hops: params.hops.map(() => ({ edges: [], sourceCount: 0 })),
+        totalReads: 0
+      };
+    }
+    return this.backend.runEngineTraversal(params);
+  }
+  // ---------------------------------------------------------------------------
+  // Server-side projection (capability: query.select)
+  // ---------------------------------------------------------------------------
+  /**
+   * Server-side projection — fetch only the requested fields from each
+   * matching edge. The backend translates the call into a projecting query
+   * (`SELECT json_extract(...)` on SQLite/DO, `Query.select(...)` on
+   * Firestore Standard, classic projection on Enterprise) so the wire
+   * payload is reduced to just the requested fields.
+   *
+   * Resolution rules for `select` (mirrored across all backends):
+   *
+   *   - Built-in envelope fields (`aType`, `aUid`, `axbType`, `bType`,
+   *     `bUid`, `createdAt`, `updatedAt`, `v`) → resolve to the typed
+   *     column / Firestore field directly.
+   *   - `'data'` literal → returns the whole user payload.
+   *   - `'data.<x>'` → explicit nested path, returned at the same shape.
+   *   - bare name → rewritten to `data.<name>` (the canonical "give me a
+   *     few keys out of the JSON payload" shape).
+   *
+   * Empty `select: []` is rejected with `INVALID_QUERY`. Duplicate entries
+   * are de-duped (first-occurrence order preserved); the result row carries
+   * one slot per unique field.
+   *
+   * Migrations are *not* applied to the result. The caller asked for a
+   * partial shape, and rehydrating it through the migration pipeline would
+   * require synthesising every absent field — see
+   * `StorageBackend.findEdgesProjected` for the rationale.
+   *
+   * Scan protection follows the `findEdges` rules: a query with no
+   * identifying fields requires `allowCollectionScan: true` to pass. The
+   * cap-less fallback would be `findEdges` + JS-side projection, but that
+   * defeats the wire-payload reduction; backends without `query.select`
+   * throw `UNSUPPORTED_OPERATION` rather than silently materialising full
+   * rows.
+   */
+  async findEdgesProjected(params) {
+    if (!this.backend.findEdgesProjected) {
+      throw new FiregraphError(
+        "findEdgesProjected() is not supported by the current storage backend. There is no client-side fallback because the wire-payload reduction is the entire point of the API \u2014 use findEdges() and project in JS if the backend does not declare `query.select`.",
+        "UNSUPPORTED_OPERATION"
+      );
+    }
+    if (params.select.length === 0) {
+      throw new FiregraphError(
+        "findEdgesProjected() requires a non-empty `select` list.",
+        "INVALID_QUERY"
+      );
+    }
+    const plan = buildEdgeQueryPlan(params);
+    let filters;
+    let options;
+    if (plan.strategy === "get") {
+      filters = [
+        { field: "aUid", op: "==", value: params.aUid },
+        { field: "axbType", op: "==", value: params.axbType },
+        { field: "bUid", op: "==", value: params.bUid }
+      ];
+      if (params.aType) filters.push({ field: "aType", op: "==", value: params.aType });
+      if (params.bType) filters.push({ field: "bType", op: "==", value: params.bType });
+      options = void 0;
+    } else {
+      filters = plan.filters;
+      options = plan.options;
+    }
+    this.checkQuerySafety(filters, params.allowCollectionScan);
+    const rows = await this.backend.findEdgesProjected(params.select, filters, options);
+    return rows;
+  }
+  /**
+   * Native vector / nearest-neighbour search (capability `search.vector`).
+   *
+   * Resolves to the top-K records by similarity, sorted nearest-first
+   * (`EUCLIDEAN` / `COSINE`) or highest-first (`DOT_PRODUCT`). The wrapper
+   * is intentionally thin: capability check, scan-protection, then forward
+   * `params` verbatim to the backend. All field-path normalisation and
+   * SDK-shape validation lives in the shared
+   * `runFirestoreFindNearest` helper that both Firestore editions call —
+   * keeping it there means the validation surface stays in lockstep with
+   * the SDK call site, regardless of which backend is plugged in.
+   *
+   * Migrations are NOT applied. The vector index walked the raw stored
+   * shape; rehydrating each row through the migration pipeline would
+   * change the candidate set the index already chose. If you need
+   * migrated shape, follow up with `getNode` / `findEdges` on the
+   * returned UIDs — those paths apply migrations normally.
+   *
+   * Scan-protection mirrors `findEdges`: if no identifying filters
+   * (`aType` / `axbType` / `bType`) and no `where` clauses are supplied,
+   * the request must opt in via `allowCollectionScan: true`. The ANN
+   * query still walks the candidate set the WHERE clause produces, so
+   * an unfiltered nearest-neighbour search over a million-row collection
+   * is the same scan trap as an unfiltered `findEdges`.
+   *
+   * Backends without `search.vector` throw `UNSUPPORTED_OPERATION` —
+   * there is no client-side fallback because emulating ANN over the
+   * generic backend surface (`findEdges` + JS-side cosine) doesn't scale
+   * past trivial datasets and would give callers the wrong mental model
+   * about cost.
+   */
+  async findNearest(params) {
+    if (!this.backend.findNearest) {
+      throw new FiregraphError(
+        "findNearest() is not supported by the current storage backend. Vector search requires a backend that declares `search.vector` (currently Firestore Standard and Enterprise). There is no client-side fallback because emulating ANN on top of the generic backend surface does not scale beyond toy datasets.",
+        "UNSUPPORTED_OPERATION"
+      );
+    }
+    const filters = [];
+    if (params.aType) filters.push({ field: "aType", op: "==", value: params.aType });
+    if (params.axbType) filters.push({ field: "axbType", op: "==", value: params.axbType });
+    if (params.bType) filters.push({ field: "bType", op: "==", value: params.bType });
+    if (params.where) filters.push(...params.where);
+    this.checkQuerySafety(filters, params.allowCollectionScan);
+    return this.backend.findNearest(params);
+  }
+  /**
+   * Native full-text search (capability `search.fullText`).
+   *
+   * Returns the top-N records by relevance, ordered by the search
+   * index's score. Only Firestore Enterprise declares this capability
+   * today — the underlying Pipelines `search({ query: documentMatches(...) })`
+   * stage requires Enterprise's FTS index. Standard does not declare
+   * the cap (FTS is an Enterprise-only product feature, not a
+   * typed-API gap), and the SQLite-shaped backends have no native
+   * FTS index. Backends without `search.fullText` throw
+   * `UNSUPPORTED_OPERATION` from this wrapper.
+   *
+   * Scan-protection mirrors `findNearest`: a search with no
+   * identifying filters (`aType` / `axbType` / `bType`) walks every
+   * row the index scored, so the request must opt in via
+   * `allowCollectionScan: true`.
+   *
+   * Migrations are NOT applied. The FTS index walked the raw stored
+   * shape; rehydrating each row through the migration pipeline would
+   * change the candidate set the index already scored. If you need
+   * migrated shape, follow up with `getNode` / `findEdges` on the
+   * returned UIDs.
+   */
+  async fullTextSearch(params) {
+    if (!this.backend.fullTextSearch) {
+      throw new FiregraphError(
+        "fullTextSearch() is not supported by the current storage backend. Full-text search requires a backend that declares `search.fullText` (currently Firestore Enterprise only \u2014 FTS is an Enterprise product feature). There is no client-side fallback because emulating FTS over the generic backend surface would not scale beyond toy datasets.",
+        "UNSUPPORTED_OPERATION"
+      );
+    }
+    const filters = [];
+    if (params.aType) filters.push({ field: "aType", op: "==", value: params.aType });
+    if (params.axbType) filters.push({ field: "axbType", op: "==", value: params.axbType });
+    if (params.bType) filters.push({ field: "bType", op: "==", value: params.bType });
+    this.checkQuerySafety(filters, params.allowCollectionScan);
+    return this.backend.fullTextSearch(params);
+  }
+  /**
+   * Native geospatial distance search (capability `search.geo`).
+   *
+   * Returns rows whose `geoField` lies within `radiusMeters` of
+   * `point`, ordered nearest-first by default. Only Firestore
+   * Enterprise declares this capability — same Enterprise-only
+   * gating as `fullTextSearch`. Backends without `search.geo` throw
+   * `UNSUPPORTED_OPERATION` from this wrapper.
+   *
+   * Scan-protection mirrors `findNearest` and `fullTextSearch`.
+   *
+   * Migrations are NOT applied — same rationale as the other search
+   * extensions.
+   */
+  async geoSearch(params) {
+    if (!this.backend.geoSearch) {
+      throw new FiregraphError(
+        "geoSearch() is not supported by the current storage backend. Geospatial search requires a backend that declares `search.geo` (currently Firestore Enterprise only \u2014 geo queries are an Enterprise product feature). There is no client-side fallback because emulating geo over the generic backend surface (haversine over `findEdges`) would not scale beyond trivial datasets.",
+        "UNSUPPORTED_OPERATION"
+      );
+    }
+    const filters = [];
+    if (params.aType) filters.push({ field: "aType", op: "==", value: params.aType });
+    if (params.axbType) filters.push({ field: "axbType", op: "==", value: params.axbType });
+    if (params.bType) filters.push({ field: "bType", op: "==", value: params.bType });
+    this.checkQuerySafety(filters, params.allowCollectionScan);
+    return this.backend.geoSearch(params);
+  }
+  /**
+   * Translate a `FindEdgesParams` into the `QueryFilter[]` shape the
+   * backend `bulkDelete` / `bulkUpdate` methods expect. Mirrors the
+   * `aggregate()` plan: a bare-empty params object becomes an empty
+   * filter list (after a scan-protection check); a GET-shape (all three
+   * identifiers) is rejected so we never silently turn a single-row
+   * lookup into a server-side DML; otherwise we run `buildEdgeQueryPlan`
+   * and surface its filters.
+   */
+  buildDmlFilters(params) {
+    const hasAnyFilter = params.aType || params.aUid || params.axbType || params.bType || params.bUid || params.where && params.where.length > 0;
+    if (!hasAnyFilter) {
+      this.checkQuerySafety([], params.allowCollectionScan);
+      return [];
+    }
+    const plan = buildEdgeQueryPlan(params);
+    if (plan.strategy === "get") {
+      throw new FiregraphError(
+        "bulkDelete() / bulkUpdate() require a query, not a direct document lookup. Use removeEdge() / updateEdge() for single-row operations, or omit one of aUid/axbType/bUid to force a query strategy.",
+        "INVALID_QUERY"
+      );
+    }
+    this.checkQuerySafety(plan.filters, params.allowCollectionScan);
+    return plan.filters;
+  }
+  // ---------------------------------------------------------------------------
   // Dynamic registry methods
   // ---------------------------------------------------------------------------
   async defineNodeType(name, jsonSchema, description, options) {
@@ -1598,21 +2011,16 @@ var GraphClientImpl = class _GraphClientImpl {
     };
   }
 };
-function createGraphClientFromBackend(backend, options, metaBackend) {
+function createGraphClient(backend, options, metaBackend) {
   return new GraphClientImpl(backend, options, metaBackend);
 }
+var createGraphClientFromBackend = createGraphClient;
 
-// src/default-indexes.ts
-var DEFAULT_CORE_INDEXES = Object.freeze([
-  { fields: ["aUid"] },
-  { fields: ["bUid"] },
-  { fields: ["aType"] },
-  { fields: ["bType"] },
-  { fields: ["aUid", "axbType"] },
-  { fields: ["axbType", "bUid"] },
-  { fields: ["aType", "axbType"] },
-  { fields: ["axbType", "bType"] }
-]);
+// src/id.ts
+import { nanoid } from "nanoid";
+function generateId() {
+  return nanoid();
+}
 
 export {
   NODE_RELATION,
@@ -1645,8 +2053,8 @@ export {
   buildEdgeQueryPlan,
   buildNodeQueryPlan,
   analyzeQuerySafety,
-  GraphClientImpl,
+  createGraphClient,
   createGraphClientFromBackend,
-  DEFAULT_CORE_INDEXES
+  generateId
 };
-//# sourceMappingURL=chunk-NJSOD64C.js.map
+//# sourceMappingURL=chunk-WRTFC5NG.js.map