@typicalday/firegraph 0.11.2 → 0.13.0

package/dist/firestore-enterprise/index.cjs

@@ -0,0 +1,3877 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/internal/serialization-tag.ts
+function isTaggedValue(value) {
+  if (value === null || typeof value !== "object") return false;
+  const tag = value[SERIALIZATION_TAG];
+  return typeof tag === "string" && KNOWN_TYPES.has(tag);
+}
+var SERIALIZATION_TAG, KNOWN_TYPES;
+var init_serialization_tag = __esm({
+  "src/internal/serialization-tag.ts"() {
+    "use strict";
+    SERIALIZATION_TAG = "__firegraph_ser__";
+    KNOWN_TYPES = /* @__PURE__ */ new Set(["Timestamp", "GeoPoint", "VectorValue", "DocumentReference"]);
+  }
+});
+
+// src/serialization.ts
+var serialization_exports = {};
+__export(serialization_exports, {
+  SERIALIZATION_TAG: () => SERIALIZATION_TAG,
+  deserializeFirestoreTypes: () => deserializeFirestoreTypes,
+  isTaggedValue: () => isTaggedValue,
+  serializeFirestoreTypes: () => serializeFirestoreTypes
+});
+function isTimestamp(value) {
+  return value instanceof import_firestore.Timestamp;
+}
+function isGeoPoint(value) {
+  return value instanceof import_firestore.GeoPoint;
+}
+function isDocumentReference(value) {
+  if (value === null || typeof value !== "object") return false;
+  const v = value;
+  return typeof v.path === "string" && v.firestore !== void 0 && typeof v.id === "string" && v.constructor?.name === "DocumentReference";
+}
+function isVectorValue(value) {
+  if (value === null || typeof value !== "object") return false;
+  const v = value;
+  return v.constructor?.name === "VectorValue" && Array.isArray(v._values);
+}
+function serializeFirestoreTypes(data) {
+  return serializeValue(data);
+}
+function serializeValue(value) {
+  if (value === null || value === void 0) return value;
+  if (typeof value !== "object") return value;
+  if (isTimestamp(value)) {
+    return {
+      [SERIALIZATION_TAG]: "Timestamp",
+      seconds: value.seconds,
+      nanoseconds: value.nanoseconds
+    };
+  }
+  if (isGeoPoint(value)) {
+    return {
+      [SERIALIZATION_TAG]: "GeoPoint",
+      latitude: value.latitude,
+      longitude: value.longitude
+    };
+  }
+  if (isDocumentReference(value)) {
+    return { [SERIALIZATION_TAG]: "DocumentReference", path: value.path };
+  }
+  if (isVectorValue(value)) {
+    const v = value;
+    const values = typeof v.toArray === "function" ? v.toArray() : v._values;
+    return { [SERIALIZATION_TAG]: "VectorValue", values: [...values] };
+  }
+  if (Array.isArray(value)) {
+    return value.map(serializeValue);
+  }
+  const result = {};
+  for (const key of Object.keys(value)) {
+    result[key] = serializeValue(value[key]);
+  }
+  return result;
+}
+function deserializeFirestoreTypes(data, db) {
+  return deserializeValue(data, db);
+}
+function deserializeValue(value, db) {
+  if (value === null || value === void 0) return value;
+  if (typeof value !== "object") return value;
+  if (isTimestamp(value) || isGeoPoint(value) || isDocumentReference(value) || isVectorValue(value)) {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return value.map((v) => deserializeValue(v, db));
+  }
+  const obj = value;
+  if (isTaggedValue(obj)) {
+    const tag = obj[SERIALIZATION_TAG];
+    switch (tag) {
+      case "Timestamp":
+        if (typeof obj.seconds !== "number" || typeof obj.nanoseconds !== "number") return obj;
+        return new import_firestore.Timestamp(obj.seconds, obj.nanoseconds);
+      case "GeoPoint":
+        if (typeof obj.latitude !== "number" || typeof obj.longitude !== "number") return obj;
+        return new import_firestore.GeoPoint(obj.latitude, obj.longitude);
+      case "VectorValue":
+        if (!Array.isArray(obj.values)) return obj;
+        return import_firestore.FieldValue.vector(obj.values);
+      case "DocumentReference":
+        if (typeof obj.path !== "string") return obj;
+        if (db) {
+          return db.doc(obj.path);
+        }
+        if (!_docRefWarned) {
+          _docRefWarned = true;
+          console.warn(
+            "[firegraph] DocumentReference encountered during migration deserialization but no Firestore instance available. The reference will remain as a tagged object with its path. Enable write-back for full reconstruction."
+          );
+        }
+        return obj;
+      default:
+        return obj;
+    }
+  }
+  const result = {};
+  for (const key of Object.keys(obj)) {
+    result[key] = deserializeValue(obj[key], db);
+  }
+  return result;
+}
+var import_firestore, _docRefWarned;
+var init_serialization = __esm({
+  "src/serialization.ts"() {
+    "use strict";
+    import_firestore = require("@google-cloud/firestore");
+    init_serialization_tag();
+    init_serialization_tag();
+    _docRefWarned = false;
+  }
+});
+
+// src/firestore-enterprise/index.ts
+var firestore_enterprise_exports = {};
+__export(firestore_enterprise_exports, {
+  META_EDGE_TYPE: () => META_EDGE_TYPE,
+  META_NODE_TYPE: () => META_NODE_TYPE,
+  createFirestoreEnterpriseBackend: () => createFirestoreEnterpriseBackend,
+  createGraphClient: () => createGraphClient,
+  createMergedRegistry: () => createMergedRegistry,
+  createRegistry: () => createRegistry,
+  generateId: () => generateId
+});
+module.exports = __toCommonJS(firestore_enterprise_exports);
+
+// src/docid.ts
+var import_node_crypto = require("crypto");
+
+// src/internal/constants.ts
+var NODE_RELATION = "is";
+var DEFAULT_QUERY_LIMIT = 500;
+var BUILTIN_FIELDS = /* @__PURE__ */ new Set([
+  "aType",
+  "aUid",
+  "axbType",
+  "bType",
+  "bUid",
+  "createdAt",
+  "updatedAt"
+]);
+var SHARD_SEPARATOR = ":";
+
+// src/docid.ts
+function computeNodeDocId(uid) {
+  return uid;
+}
+function computeEdgeDocId(aUid, axbType, bUid) {
+  const composite = `${aUid}${SHARD_SEPARATOR}${axbType}${SHARD_SEPARATOR}${bUid}`;
+  const hash = (0, import_node_crypto.createHash)("sha256").update(composite).digest("hex");
+  const shard = hash[0];
+  return `${shard}${SHARD_SEPARATOR}${aUid}${SHARD_SEPARATOR}${axbType}${SHARD_SEPARATOR}${bUid}`;
+}
+
+// src/internal/write-plan.ts
+init_serialization_tag();
+var DELETE_FIELD = /* @__PURE__ */ Symbol.for("firegraph.deleteField");
+function isDeleteSentinel(value) {
+  return value === DELETE_FIELD;
+}
+var FIRESTORE_TERMINAL_CTOR = /* @__PURE__ */ new Set([
+  "Timestamp",
+  "GeoPoint",
+  "VectorValue",
+  "DocumentReference",
+  "FieldValue",
+  "NumericIncrementTransform",
+  "ArrayUnionTransform",
+  "ArrayRemoveTransform",
+  "ServerTimestampTransform",
+  "DeleteTransform"
+]);
+function isTerminalValue(value) {
+  if (value === null) return true;
+  const t = typeof value;
+  if (t !== "object") return true;
+  if (Array.isArray(value)) return true;
+  if (isTaggedValue(value)) return true;
+  const proto = Object.getPrototypeOf(value);
+  if (proto === null || proto === Object.prototype) return false;
+  const ctor = value.constructor;
+  if (ctor && typeof ctor.name === "string" && FIRESTORE_TERMINAL_CTOR.has(ctor.name)) return true;
+  return true;
+}
+var SAFE_KEY_RE = /^[A-Za-z_][A-Za-z0-9_-]*$/;
+function assertUpdatePayloadExclusive(update) {
+  if (update.replaceData !== void 0 && update.dataOps !== void 0) {
+    throw new Error(
+      "firegraph: UpdatePayload cannot specify both `replaceData` and `dataOps`. Use one or the other \u2014 `replaceData` is the migration-write-back form, `dataOps` is the standard partial-update form."
+    );
+  }
+}
+function assertNoDeleteSentinels(data, callerLabel) {
+  walkForDeleteSentinels(data, [], { kind: "root" }, ({ path }) => {
+    const where = path.length === 0 ? "<root>" : path.map((p) => JSON.stringify(p)).join(" > ");
+    throw new Error(
+      `firegraph: ${callerLabel} payload contains a deleteField() sentinel at ${where}. deleteField() is only valid inside updateNode/updateEdge \u2014 full-data writes (put*, replace*) cannot delete individual fields. Use updateNode with a deleteField() value, or omit the field from the replace payload.`
+    );
+  });
+}
+function walkForDeleteSentinels(node, path, parent, visit) {
+  if (node === null || node === void 0) return;
+  if (isDeleteSentinel(node)) {
+    visit({ path, parent });
+    return;
+  }
+  if (typeof node !== "object") return;
+  if (isTaggedValue(node)) return;
+  if (Array.isArray(node)) {
+    for (let i = 0; i < node.length; i++) {
+      walkForDeleteSentinels(node[i], [...path, String(i)], { kind: "array", index: i }, visit);
+    }
+    return;
+  }
+  const proto = Object.getPrototypeOf(node);
+  if (proto !== null && proto !== Object.prototype) return;
+  const obj = node;
+  for (const key of Object.keys(obj)) {
+    walkForDeleteSentinels(obj[key], [...path, key], { kind: "object" }, visit);
+  }
+}
+function assertSafePath(path) {
+  for (const seg of path) {
+    if (!SAFE_KEY_RE.test(seg)) {
+      throw new Error(
+        `firegraph: unsafe object key ${JSON.stringify(seg)} at path ${path.map((p) => JSON.stringify(p)).join(" > ")}. Keys used inside update payloads must match /^[A-Za-z_][A-Za-z0-9_-]*$/ so they can be embedded safely in SQLite JSON paths.`
+      );
+    }
+  }
+}
+function flattenPatch(data) {
+  const ops = [];
+  walk(data, [], ops);
+  return ops;
+}
+function assertNoDeleteSentinelsInArrayValue(arr, arrayPath) {
+  walkForDeleteSentinels(arr, arrayPath, { kind: "root" }, ({ parent }) => {
+    const arrayPathStr = arrayPath.length === 0 ? "<root>" : arrayPath.map((p) => JSON.stringify(p)).join(" > ");
+    if (parent.kind === "array") {
+      throw new Error(
+        `firegraph: deleteField() sentinel at index ${parent.index} inside an array at path ${arrayPathStr}. Arrays are terminal in update payloads (replaced as a unit), so the sentinel would be silently dropped by JSON serialization. To remove the field entirely, pass deleteField() in place of the whole array.`
+      );
+    }
+    throw new Error(
+      `firegraph: deleteField() sentinel inside an array element at path ${arrayPathStr}. Arrays are terminal in update payloads \u2014 the sentinel would be silently dropped by JSON serialization.`
+    );
+  });
+}
+function walk(node, path, out) {
+  if (node === void 0) return;
+  if (isDeleteSentinel(node)) {
+    if (path.length === 0) {
+      throw new Error("firegraph: deleteField() cannot be the entire update payload.");
+    }
+    assertSafePath(path);
+    out.push({ path: [...path], value: void 0, delete: true });
+    return;
+  }
+  if (isTerminalValue(node)) {
+    if (path.length === 0) {
+      throw new Error(
+        "firegraph: update payload must be a plain object. Got " + (node === null ? "null" : Array.isArray(node) ? "array" : typeof node) + "."
+      );
+    }
+    if (Array.isArray(node)) {
+      assertNoDeleteSentinelsInArrayValue(node, path);
+    }
+    assertSafePath(path);
+    out.push({ path: [...path], value: node, delete: false });
+    return;
+  }
+  const obj = node;
+  const keys = Object.keys(obj);
+  if (keys.length === 0) {
+    if (path.length > 0) {
+      assertSafePath(path);
+      out.push({ path: [...path], value: {}, delete: false });
+    }
+    return;
+  }
+  for (const key of keys) {
+    if (key === SERIALIZATION_TAG) {
+      const where = path.length === 0 ? "<root>" : path.map((p) => JSON.stringify(p)).join(" > ");
+      throw new Error(
+        `firegraph: update payload contains a literal \`${SERIALIZATION_TAG}\` key at ${where}. That key is reserved for firegraph's serialization envelope and cannot appear on a plain object in user data. Use a different field name, or pass a recognized tagged value through replaceNode/replaceEdge instead.`
+      );
+    }
+    walk(obj[key], [...path, key], out);
+  }
+}
+
+// src/batch.ts
+function buildWritableNodeRecord(aType, uid, data) {
+  return { aType, aUid: uid, axbType: NODE_RELATION, bType: aType, bUid: uid, data };
+}
+function buildWritableEdgeRecord(aType, aUid, axbType, bType, bUid, data) {
+  return { aType, aUid, axbType, bType, bUid, data };
+}
+var GraphBatchImpl = class {
+  constructor(backend, registry, scopePath = "") {
+    this.backend = backend;
+    this.registry = registry;
+    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);
+    }
+    const docId = computeNodeDocId(uid);
+    const record = buildWritableNodeRecord(aType, uid, data);
+    if (this.registry) {
+      const entry = this.registry.lookup(aType, NODE_RELATION, aType);
+      if (entry?.schemaVersion && entry.schemaVersion > 0) {
+        record.v = entry.schemaVersion;
+      }
+    }
+    this.backend.setDoc(docId, record, mode);
+  }
+  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);
+    }
+    const docId = computeEdgeDocId(aUid, axbType, bUid);
+    const record = buildWritableEdgeRecord(aType, aUid, axbType, bType, bUid, data);
+    if (this.registry) {
+      const entry = this.registry.lookup(aType, axbType, bType);
+      if (entry?.schemaVersion && entry.schemaVersion > 0) {
+        record.v = entry.schemaVersion;
+      }
+    }
+    this.backend.setDoc(docId, record, mode);
+  }
+  async updateNode(uid, data) {
+    const docId = computeNodeDocId(uid);
+    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);
+    this.backend.deleteDoc(docId);
+  }
+  async removeEdge(aUid, axbType, bUid) {
+    const docId = computeEdgeDocId(aUid, axbType, bUid);
+    this.backend.deleteDoc(docId);
+  }
+  async commit() {
+    await this.backend.commit();
+  }
+};
+
+// src/dynamic-registry.ts
+var import_node_crypto3 = require("crypto");
+
+// src/errors.ts
+var FiregraphError = class extends Error {
+  constructor(message, code) {
+    super(message);
+    this.code = code;
+    this.name = "FiregraphError";
+  }
+};
+var ValidationError = class extends FiregraphError {
+  constructor(message, details) {
+    super(message, "VALIDATION_ERROR");
+    this.details = details;
+    this.name = "ValidationError";
+  }
+};
+var RegistryViolationError = class extends FiregraphError {
+  constructor(aType, axbType, bType) {
+    super(`Unregistered triple: (${aType}) -[${axbType}]-> (${bType})`, "REGISTRY_VIOLATION");
+    this.name = "RegistryViolationError";
+  }
+};
+var InvalidQueryError = class extends FiregraphError {
+  constructor(message) {
+    super(message, "INVALID_QUERY");
+    this.name = "InvalidQueryError";
+  }
+};
+var DynamicRegistryError = class extends FiregraphError {
+  constructor(message) {
+    super(message, "DYNAMIC_REGISTRY_ERROR");
+    this.name = "DynamicRegistryError";
+  }
+};
+var QuerySafetyError = class extends FiregraphError {
+  constructor(message) {
+    super(message, "QUERY_SAFETY");
+    this.name = "QuerySafetyError";
+  }
+};
+var RegistryScopeError = class extends FiregraphError {
+  constructor(aType, axbType, bType, scopePath, allowedIn) {
+    super(
+      `Type (${aType}) -[${axbType}]-> (${bType}) is not allowed at scope "${scopePath || "root"}". Allowed in: [${allowedIn.join(", ")}]`,
+      "REGISTRY_SCOPE"
+    );
+    this.name = "RegistryScopeError";
+  }
+};
+var MigrationError = class extends FiregraphError {
+  constructor(message) {
+    super(message, "MIGRATION_ERROR");
+    this.name = "MigrationError";
+  }
+};
+
+// src/json-schema.ts
+var import_json_schema = require("@cfworker/json-schema");
+var MAX_RENDERED_ERRORS = 20;
+function compileSchema(schema, label) {
+  const validator = new import_json_schema.Validator(schema, "2020-12", false);
+  return (data) => {
+    const result = validator.validate(data);
+    if (!result.valid) {
+      const total = result.errors.length;
+      const head = result.errors.slice(0, MAX_RENDERED_ERRORS).map(formatError).join("; ");
+      const overflow = total > MAX_RENDERED_ERRORS ? ` (+${total - MAX_RENDERED_ERRORS} more)` : "";
+      throw new ValidationError(
+        `Data validation failed${label ? " for " + label : ""}: ${head}${overflow}`,
+        result.errors
+      );
+    }
+  };
+}
+function formatError(err) {
+  const path = err.instanceLocation.replace(/^#/, "") || "/";
+  const keyword = err.keyword ? `[${err.keyword}] ` : "";
+  const detail = err.error ? `: ${keyword}${err.error}` : "";
+  return `${path}${detail}`;
+}
+
+// src/migration.ts
+async function applyMigrationChain(data, currentVersion, targetVersion, migrations) {
+  const sorted = [...migrations].sort((a, b) => a.fromVersion - b.fromVersion);
+  let result = { ...data };
+  let version = currentVersion;
+  for (const step of sorted) {
+    if (step.fromVersion === version) {
+      try {
+        result = await step.up(result);
+      } catch (err) {
+        if (err instanceof MigrationError) throw err;
+        throw new MigrationError(
+          `Migration from v${step.fromVersion} to v${step.toVersion} failed: ${err.message}`
+        );
+      }
+      if (!result || typeof result !== "object") {
+        throw new MigrationError(
+          `Migration from v${step.fromVersion} to v${step.toVersion} returned invalid data (expected object)`
+        );
+      }
+      version = step.toVersion;
+    }
+  }
+  if (version !== targetVersion) {
+    throw new MigrationError(
+      `Incomplete migration chain: reached v${version} but target is v${targetVersion}`
+    );
+  }
+  return result;
+}
+function validateMigrationChain(migrations, label) {
+  if (migrations.length === 0) return;
+  const seen = /* @__PURE__ */ new Set();
+  for (const step of migrations) {
+    if (step.toVersion <= step.fromVersion) {
+      throw new MigrationError(
+        `${label}: migration step has toVersion (${step.toVersion}) <= fromVersion (${step.fromVersion})`
+      );
+    }
+    if (seen.has(step.fromVersion)) {
+      throw new MigrationError(
+        `${label}: duplicate migration step for fromVersion ${step.fromVersion}`
+      );
+    }
+    seen.add(step.fromVersion);
+  }
+  const sorted = [...migrations].sort((a, b) => a.fromVersion - b.fromVersion);
+  const targetVersion = Math.max(...migrations.map((m) => m.toVersion));
+  let version = 0;
+  for (const step of sorted) {
+    if (step.fromVersion === version) {
+      version = step.toVersion;
+    } else if (step.fromVersion > version) {
+      throw new MigrationError(
+        `${label}: migration chain has a gap \u2014 no step covers v${version} \u2192 v${step.fromVersion}`
+      );
+    }
+  }
+  if (version !== targetVersion) {
+    throw new MigrationError(
+      `${label}: migration chain does not reach v${targetVersion} (stuck at v${version})`
+    );
+  }
+}
+async function migrateRecord(record, registry, globalWriteBack = "off") {
+  const entry = registry.lookup(record.aType, record.axbType, record.bType);
+  if (!entry?.migrations?.length || !entry.schemaVersion) {
+    return { record, migrated: false, writeBack: "off" };
+  }
+  const currentVersion = record.v ?? 0;
+  if (currentVersion >= entry.schemaVersion) {
+    return { record, migrated: false, writeBack: "off" };
+  }
+  const migratedData = await applyMigrationChain(
+    record.data,
+    currentVersion,
+    entry.schemaVersion,
+    entry.migrations
+  );
+  const writeBack = entry.migrationWriteBack ?? globalWriteBack ?? "off";
+  return {
+    record: { ...record, data: migratedData, v: entry.schemaVersion },
+    migrated: true,
+    writeBack
+  };
+}
+async function migrateRecords(records, registry, globalWriteBack = "off") {
+  return Promise.all(records.map((r) => migrateRecord(r, registry, globalWriteBack)));
+}
+
+// src/scope.ts
+function matchScope(scopePath, pattern) {
+  if (pattern === "root") return scopePath === "";
+  if (pattern === "**") return true;
+  const pathSegments = scopePath === "" ? [] : scopePath.split("/");
+  const patternSegments = pattern.split("/");
+  return matchSegments(pathSegments, 0, patternSegments, 0);
+}
+function matchScopeAny(scopePath, patterns) {
+  if (!patterns || patterns.length === 0) return true;
+  return patterns.some((p) => matchScope(scopePath, p));
+}
+function matchSegments(path, pi, pattern, qi) {
+  if (pi === path.length && qi === pattern.length) return true;
+  if (qi === pattern.length) return false;
+  const seg = pattern[qi];
+  if (seg === "**") {
+    if (qi === pattern.length - 1) return true;
+    for (let skip = 0; skip <= path.length - pi; skip++) {
+      if (matchSegments(path, pi + skip, pattern, qi + 1)) return true;
+    }
+    return false;
+  }
+  if (pi === path.length) return false;
+  if (seg === "*") {
+    return matchSegments(path, pi + 1, pattern, qi + 1);
+  }
+  if (path[pi] === seg) {
+    return matchSegments(path, pi + 1, pattern, qi + 1);
+  }
+  return false;
+}
+
+// src/registry.ts
+function tripleKey(aType, axbType, bType) {
+  return `${aType}:${axbType}:${bType}`;
+}
+function tripleKeyFor(e) {
+  return tripleKey(e.aType, e.axbType, e.bType);
+}
+function createRegistry(input) {
+  const map = /* @__PURE__ */ new Map();
+  let entries;
+  if (Array.isArray(input)) {
+    entries = input;
+  } else {
+    entries = discoveryToEntries(input);
+  }
+  const entryList = Object.freeze([...entries]);
+  for (const entry of entries) {
+    if (entry.targetGraph && entry.targetGraph.includes("/")) {
+      throw new ValidationError(
+        `Entry (${entry.aType}) -[${entry.axbType}]-> (${entry.bType}) has invalid targetGraph "${entry.targetGraph}" \u2014 must be a single segment (no "/")`
+      );
+    }
+    if (entry.migrations?.length) {
+      const label = `Entry (${entry.aType}) -[${entry.axbType}]-> (${entry.bType})`;
+      validateMigrationChain(entry.migrations, label);
+      entry.schemaVersion = Math.max(...entry.migrations.map((m) => m.toVersion));
+    } else {
+      entry.schemaVersion = void 0;
+    }
+    const key = tripleKey(entry.aType, entry.axbType, entry.bType);
+    const validator = entry.jsonSchema ? compileSchema(entry.jsonSchema, `(${entry.aType}) -[${entry.axbType}]-> (${entry.bType})`) : void 0;
+    map.set(key, { entry, validate: validator });
+  }
+  const axbIndex = /* @__PURE__ */ new Map();
+  const axbBuild = /* @__PURE__ */ new Map();
+  for (const entry of entries) {
+    const existing = axbBuild.get(entry.axbType);
+    if (existing) {
+      existing.push(entry);
+    } else {
+      axbBuild.set(entry.axbType, [entry]);
+    }
+  }
+  for (const [key, arr] of axbBuild) {
+    axbIndex.set(key, Object.freeze(arr));
+  }
+  const topologyIndex = /* @__PURE__ */ new Map();
+  const topologyBuild = /* @__PURE__ */ new Map();
+  const topologySeen = /* @__PURE__ */ new Map();
+  for (const entry of entries) {
+    if (!entry.targetGraph) continue;
+    let seen = topologySeen.get(entry.aType);
+    if (!seen) {
+      seen = /* @__PURE__ */ new Set();
+      topologySeen.set(entry.aType, seen);
+    }
+    if (seen.has(entry.targetGraph)) continue;
+    seen.add(entry.targetGraph);
+    const existing = topologyBuild.get(entry.aType);
+    if (existing) {
+      existing.push(entry);
+    } else {
+      topologyBuild.set(entry.aType, [entry]);
+    }
+  }
+  for (const [key, arr] of topologyBuild) {
+    topologyIndex.set(key, Object.freeze(arr));
+  }
+  return {
+    lookup(aType, axbType, bType) {
+      return map.get(tripleKey(aType, axbType, bType))?.entry;
+    },
+    lookupByAxbType(axbType) {
+      return axbIndex.get(axbType) ?? [];
+    },
+    getSubgraphTopology(aType) {
+      return topologyIndex.get(aType) ?? [];
+    },
+    validate(aType, axbType, bType, data, scopePath) {
+      const rec = map.get(tripleKey(aType, axbType, bType));
+      if (!rec) {
+        throw new RegistryViolationError(aType, axbType, bType);
+      }
+      if (scopePath !== void 0 && rec.entry.allowedIn && rec.entry.allowedIn.length > 0) {
+        if (!matchScopeAny(scopePath, rec.entry.allowedIn)) {
+          throw new RegistryScopeError(aType, axbType, bType, scopePath, rec.entry.allowedIn);
+        }
+      }
+      if (rec.validate) {
+        try {
+          rec.validate(data);
+        } catch (err) {
+          if (err instanceof ValidationError) throw err;
+          throw new ValidationError(
+            `Data validation failed for (${aType}) -[${axbType}]-> (${bType})`,
+            err
+          );
+        }
+      }
+    },
+    entries() {
+      return entryList;
+    }
+  };
+}
+function createMergedRegistry(base, extension) {
+  const baseKeys = new Set(base.entries().map(tripleKeyFor));
+  return {
+    lookup(aType, axbType, bType) {
+      return base.lookup(aType, axbType, bType) ?? extension.lookup(aType, axbType, bType);
+    },
+    lookupByAxbType(axbType) {
+      const baseResults = base.lookupByAxbType(axbType);
+      const extResults = extension.lookupByAxbType(axbType);
+      if (extResults.length === 0) return baseResults;
+      if (baseResults.length === 0) return extResults;
+      const seen = new Set(baseResults.map(tripleKeyFor));
+      const merged = [...baseResults];
+      for (const entry of extResults) {
+        if (!seen.has(tripleKeyFor(entry))) {
+          merged.push(entry);
+        }
+      }
+      return Object.freeze(merged);
+    },
+    getSubgraphTopology(aType) {
+      const baseResults = base.getSubgraphTopology(aType);
+      const extResults = extension.getSubgraphTopology(aType);
+      if (extResults.length === 0) return baseResults;
+      if (baseResults.length === 0) return extResults;
+      const seen = new Set(baseResults.map((e) => e.targetGraph));
+      const merged = [...baseResults];
+      for (const entry of extResults) {
+        if (!seen.has(entry.targetGraph)) {
+          seen.add(entry.targetGraph);
+          merged.push(entry);
+        }
+      }
+      return Object.freeze(merged);
+    },
+    validate(aType, axbType, bType, data, scopePath) {
+      if (baseKeys.has(tripleKey(aType, axbType, bType))) {
+        return base.validate(aType, axbType, bType, data, scopePath);
+      }
+      return extension.validate(aType, axbType, bType, data, scopePath);
+    },
+    entries() {
+      const extEntries = extension.entries();
+      if (extEntries.length === 0) return base.entries();
+      const merged = [...base.entries()];
+      for (const entry of extEntries) {
+        if (!baseKeys.has(tripleKeyFor(entry))) {
+          merged.push(entry);
+        }
+      }
+      return Object.freeze(merged);
+    }
+  };
+}
+function discoveryToEntries(discovery) {
+  const entries = [];
+  for (const [name, entity] of discovery.nodes) {
+    entries.push({
+      aType: name,
+      axbType: NODE_RELATION,
+      bType: name,
+      jsonSchema: entity.schema,
+      description: entity.description,
+      titleField: entity.titleField,
+      subtitleField: entity.subtitleField,
+      allowedIn: entity.allowedIn,
+      migrations: entity.migrations,
+      migrationWriteBack: entity.migrationWriteBack,
+      indexes: entity.indexes
+    });
+  }
+  for (const [axbType, entity] of discovery.edges) {
+    const topology = entity.topology;
+    if (!topology) continue;
+    const fromTypes = Array.isArray(topology.from) ? topology.from : [topology.from];
+    const toTypes = Array.isArray(topology.to) ? topology.to : [topology.to];
+    const resolvedTargetGraph = entity.targetGraph ?? topology.targetGraph;
+    if (resolvedTargetGraph && resolvedTargetGraph.includes("/")) {
+      throw new ValidationError(
+        `Edge "${axbType}" has invalid targetGraph "${resolvedTargetGraph}" \u2014 must be a single segment (no "/")`
+      );
+    }
+    for (const aType of fromTypes) {
+      for (const bType of toTypes) {
+        entries.push({
+          aType,
+          axbType,
+          bType,
+          jsonSchema: entity.schema,
+          description: entity.description,
+          inverseLabel: topology.inverseLabel,
+          titleField: entity.titleField,
+          subtitleField: entity.subtitleField,
+          allowedIn: entity.allowedIn,
+          targetGraph: resolvedTargetGraph,
+          migrations: entity.migrations,
+          migrationWriteBack: entity.migrationWriteBack,
+          indexes: entity.indexes
+        });
+      }
+    }
+  }
+  return entries;
+}
+
+// src/sandbox.ts
+var import_node_crypto2 = require("crypto");
+var import_meta = {};
+var _worker = null;
+var _requestId = 0;
+var _pending = /* @__PURE__ */ new Map();
+var WORKER_SOURCE = [
+  `'use strict';`,
+  `var _wt = require('node:worker_threads');`,
+  `var _mod = require('node:module');`,
+  `var _crypto = require('node:crypto');`,
+  `var parentPort = _wt.parentPort;`,
+  `var workerData = _wt.workerData;`,
+  ``,
+  `// Load SES using the parent module's resolution context`,
+  `var esmRequire = _mod.createRequire(workerData.parentUrl);`,
+  `esmRequire('ses');`,
+  ``,
+  `lockdown({`,
+  `  errorTaming: 'unsafe',`,
+  `  consoleTaming: 'unsafe',`,
+  `  evalTaming: 'safe-eval',`,
+  `  overrideTaming: 'moderate',`,
+  `  stackFiltering: 'verbose'`,
+  `});`,
+  ``,
+  `// Defense-in-depth: verify lockdown() actually hardened JSON.`,
+  `if (!Object.isFrozen(JSON)) {`,
+  `  throw new Error('SES lockdown failed: JSON is not frozen');`,
+  `}`,
+  ``,
+  `var cache = new Map();`,
+  ``,
+  `function hashSource(s) {`,
+  `  return _crypto.createHash('sha256').update(s).digest('hex');`,
+  `}`,
+  ``,
+  `function buildWrapper(source) {`,
+  `  return '(function() {' +`,
+  `    '  var fn = (' + source + ');\\n' +`,
+  `    '  if (typeof fn !== "function") return null;\\n' +`,
+  `    '  return function(jsonIn) {\\n' +`,
+  `    '    var data = JSON.parse(jsonIn);\\n' +`,
+  `    '    var result = fn(data);\\n' +`,
+  `    '    if (result !== null && typeof result === "object" && typeof result.then === "function") {\\n' +`,
+  `    '      return result.then(function(r) { return JSON.stringify(r); });\\n' +`,
+  `    '    }\\n' +`,
+  `    '    return JSON.stringify(result);\\n' +`,
+  `    '  };\\n' +`,
+  `    '})()';`,
+  `}`,
+  ``,
+  `function compileSource(source) {`,
+  `  var key = hashSource(source);`,
+  `  var cached = cache.get(key);`,
+  `  if (cached) return cached;`,
+  ``,
+  `  var compartmentFn;`,
+  `  try {`,
+  `    var c = new Compartment({ JSON: JSON });`,
+  `    compartmentFn = c.evaluate(buildWrapper(source));`,
+  `  } catch (err) {`,
+  `    throw new Error('Failed to compile migration source: ' + (err.message || String(err)));`,
+  `  }`,
+  ``,
+  `  if (typeof compartmentFn !== 'function') {`,
+  `    throw new Error('Migration source did not produce a function: ' + source.slice(0, 80));`,
+  `  }`,
+  ``,
+  `  cache.set(key, compartmentFn);`,
+  `  return compartmentFn;`,
+  `}`,
+  ``,
+  `parentPort.on('message', function(msg) {`,
+  `  var id = msg.id;`,
+  `  try {`,
+  `    if (msg.type === 'compile') {`,
+  `      compileSource(msg.source);`,
+  `      parentPort.postMessage({ id: id, type: 'compiled' });`,
+  `      return;`,
+  `    }`,
+  `    if (msg.type === 'execute') {`,
+  `      var fn = compileSource(msg.source);`,
+  `      var raw;`,
+  `      try {`,
+  `        raw = fn(msg.jsonData);`,
+  `      } catch (err) {`,
+  `        parentPort.postMessage({ id: id, type: 'error', message: 'Migration function threw: ' + (err.message || String(err)) });`,
+  `        return;`,
+  `      }`,
+  `      if (raw !== null && typeof raw === 'object' && typeof raw.then === 'function') {`,
+  `        raw.then(`,
+  `          function(jsonResult) {`,
+  `            if (jsonResult === undefined || jsonResult === null) {`,
+  `              parentPort.postMessage({ id: id, type: 'error', message: 'Migration returned a non-JSON-serializable value' });`,
+  `            } else {`,
+  `              parentPort.postMessage({ id: id, type: 'result', jsonResult: jsonResult });`,
+  `            }`,
+  `          },`,
+  `          function(err) {`,
+  `            parentPort.postMessage({ id: id, type: 'error', message: 'Async migration function threw: ' + (err.message || String(err)) });`,
+  `          }`,
+  `        );`,
+  `        return;`,
+  `      }`,
+  `      if (raw === undefined || raw === null) {`,
+  `        parentPort.postMessage({ id: id, type: 'error', message: 'Migration returned a non-JSON-serializable value' });`,
+  `      } else {`,
+  `        parentPort.postMessage({ id: id, type: 'result', jsonResult: raw });`,
+  `      }`,
+  `    }`,
+  `  } catch (err) {`,
+  `    parentPort.postMessage({ id: id, type: 'error', message: err.message || String(err) });`,
+  `  }`,
+  `});`
+].join("\n");
+var _WorkerCtor = null;
+async function loadWorkerCtor() {
+  if (_WorkerCtor) return _WorkerCtor;
+  const wt = await import("worker_threads");
+  _WorkerCtor = wt.Worker;
+  return _WorkerCtor;
+}
+async function ensureWorker() {
+  if (_worker) return _worker;
+  const Ctor = await loadWorkerCtor();
+  _worker = new Ctor(WORKER_SOURCE, {
+    eval: true,
+    workerData: { parentUrl: import_meta.url }
+  });
+  _worker.unref();
+  _worker.on("message", (msg) => {
+    if (msg.id === void 0) return;
+    const pending = _pending.get(msg.id);
+    if (!pending) return;
+    _pending.delete(msg.id);
+    if (msg.type === "error") {
+      pending.reject(new MigrationError(msg.message ?? "Unknown sandbox error"));
+    } else {
+      pending.resolve(msg);
+    }
+  });
+  _worker.on("error", (err) => {
+    for (const [, p] of _pending) {
+      p.reject(new MigrationError(`Sandbox worker error: ${err.message}`));
+    }
+    _pending.clear();
+    _worker = null;
+  });
+  _worker.on("exit", (code) => {
+    if (_pending.size > 0) {
+      for (const [, p] of _pending) {
+        p.reject(new MigrationError(`Sandbox worker exited with code ${code}`));
+      }
+      _pending.clear();
+    }
+    _worker = null;
+  });
+  return _worker;
+}
+async function sendToWorker(msg) {
+  const worker = await ensureWorker();
+  if (_requestId >= Number.MAX_SAFE_INTEGER) _requestId = 0;
+  const id = ++_requestId;
+  return new Promise((resolve, reject) => {
+    _pending.set(id, { resolve, reject });
+    worker.postMessage({ ...msg, id });
+  });
+}
+var compiledCache = /* @__PURE__ */ new WeakMap();
+function getExecutorCache(executor) {
+  let cache = compiledCache.get(executor);
+  if (!cache) {
+    cache = /* @__PURE__ */ new Map();
+    compiledCache.set(executor, cache);
+  }
+  return cache;
+}
+function hashSource(source) {
+  return (0, import_node_crypto2.createHash)("sha256").update(source).digest("hex");
+}
+var _serializationModule = null;
+async function loadSerialization() {
+  if (_serializationModule) return _serializationModule;
+  _serializationModule = await Promise.resolve().then(() => (init_serialization(), serialization_exports));
+  return _serializationModule;
+}
+function defaultExecutor(source) {
+  return (async (data) => {
+    const { serializeFirestoreTypes: serializeFirestoreTypes2, deserializeFirestoreTypes: deserializeFirestoreTypes2 } = await loadSerialization();
+    const jsonData = JSON.stringify(serializeFirestoreTypes2(data));
+    const response = await sendToWorker({ type: "execute", source, jsonData });
+    if (response.jsonResult === void 0 || response.jsonResult === null) {
+      throw new MigrationError("Migration returned a non-JSON-serializable value");
+    }
+    try {
+      return deserializeFirestoreTypes2(JSON.parse(response.jsonResult));
+    } catch {
+      throw new MigrationError("Migration returned a non-JSON-serializable value");
+    }
+  });
+}
+async function precompileSource(source, executor) {
+  if (executor && executor !== defaultExecutor) {
+    try {
+      executor(source);
+    } catch (err) {
+      if (err instanceof MigrationError) throw err;
+      throw new MigrationError(`Failed to compile migration source: ${err.message}`);
+    }
+    return;
+  }
+  await sendToWorker({ type: "compile", source });
+}
+function compileMigrationFn(source, executor = defaultExecutor) {
+  const cache = getExecutorCache(executor);
+  const key = hashSource(source);
+  const cached = cache.get(key);
+  if (cached) return cached;
+  try {
+    const fn = executor(source);
+    cache.set(key, fn);
+    return fn;
+  } catch (err) {
+    if (err instanceof MigrationError) throw err;
+    throw new MigrationError(`Failed to compile migration source: ${err.message}`);
+  }
+}
+function compileMigrations(stored, executor) {
+  return stored.map((step) => ({
+    fromVersion: step.fromVersion,
+    toVersion: step.toVersion,
+    up: compileMigrationFn(step.up, executor)
+  }));
+}
+
+// src/dynamic-registry.ts
+var META_NODE_TYPE = "nodeType";
+var META_EDGE_TYPE = "edgeType";
+var STORED_MIGRATION_STEP_SCHEMA = {
+  type: "object",
+  required: ["fromVersion", "toVersion", "up"],
+  properties: {
+    fromVersion: { type: "integer", minimum: 0 },
+    toVersion: { type: "integer", minimum: 1 },
+    up: { type: "string", minLength: 1 }
+  },
+  additionalProperties: false
+};
+var NODE_TYPE_SCHEMA = {
+  type: "object",
+  required: ["name", "jsonSchema"],
+  properties: {
+    name: { type: "string", minLength: 1 },
+    jsonSchema: { type: "object" },
+    description: { type: "string" },
+    titleField: { type: "string" },
+    subtitleField: { type: "string" },
+    viewTemplate: { type: "string" },
+    viewCss: { type: "string" },
+    allowedIn: { type: "array", items: { type: "string", minLength: 1 } },
+    schemaVersion: { type: "integer", minimum: 0 },
+    migrations: { type: "array", items: STORED_MIGRATION_STEP_SCHEMA },
+    migrationWriteBack: { type: "string", enum: ["off", "eager", "background"] }
+  },
+  additionalProperties: false
+};
+var EDGE_TYPE_SCHEMA = {
+  type: "object",
+  required: ["name", "from", "to"],
+  properties: {
+    name: { type: "string", minLength: 1 },
+    from: {
+      oneOf: [
+        { type: "string", minLength: 1 },
+        { type: "array", items: { type: "string", minLength: 1 }, minItems: 1 }
+      ]
+    },
+    to: {
+      oneOf: [
+        { type: "string", minLength: 1 },
+        { type: "array", items: { type: "string", minLength: 1 }, minItems: 1 }
+      ]
+    },
+    jsonSchema: { type: "object" },
+    inverseLabel: { type: "string" },
+    description: { type: "string" },
+    titleField: { type: "string" },
+    subtitleField: { type: "string" },
+    viewTemplate: { type: "string" },
+    viewCss: { type: "string" },
+    allowedIn: { type: "array", items: { type: "string", minLength: 1 } },
+    targetGraph: { type: "string", minLength: 1, pattern: "^[^/]+$" },
+    schemaVersion: { type: "integer", minimum: 0 },
+    migrations: { type: "array", items: STORED_MIGRATION_STEP_SCHEMA },
+    migrationWriteBack: { type: "string", enum: ["off", "eager", "background"] }
+  },
+  additionalProperties: false
+};
+var BOOTSTRAP_ENTRIES = [
+  {
+    aType: META_NODE_TYPE,
+    axbType: NODE_RELATION,
+    bType: META_NODE_TYPE,
+    jsonSchema: NODE_TYPE_SCHEMA,
+    description: "Meta-type: defines a node type"
+  },
+  {
+    aType: META_EDGE_TYPE,
+    axbType: NODE_RELATION,
+    bType: META_EDGE_TYPE,
+    jsonSchema: EDGE_TYPE_SCHEMA,
+    description: "Meta-type: defines an edge type"
+  }
+];
+var _bootstrapRegistry = null;
+function createBootstrapRegistry() {
+  if (_bootstrapRegistry) return _bootstrapRegistry;
+  _bootstrapRegistry = createRegistry([...BOOTSTRAP_ENTRIES]);
+  return _bootstrapRegistry;
+}
+function generateDeterministicUid(metaType, name) {
+  const hash = (0, import_node_crypto3.createHash)("sha256").update(`${metaType}:${name}`).digest("base64url");
+  return hash.slice(0, 21);
+}
+async function createRegistryFromGraph(reader, executor) {
+  const [nodeTypes, edgeTypes] = await Promise.all([
+    reader.findNodes({ aType: META_NODE_TYPE }),
+    reader.findNodes({ aType: META_EDGE_TYPE })
+  ]);
+  const entries = [...BOOTSTRAP_ENTRIES];
+  const prevalidations = [];
+  for (const record of nodeTypes) {
+    const data = record.data;
+    if (data.migrations) {
+      for (const m of data.migrations) {
+        prevalidations.push(precompileSource(m.up, executor));
+      }
+    }
+  }
+  for (const record of edgeTypes) {
+    const data = record.data;
+    if (data.migrations) {
+      for (const m of data.migrations) {
+        prevalidations.push(precompileSource(m.up, executor));
+      }
+    }
+  }
+  await Promise.all(prevalidations);
+  for (const record of nodeTypes) {
+    const data = record.data;
+    entries.push({
+      aType: data.name,
+      axbType: NODE_RELATION,
+      bType: data.name,
+      jsonSchema: data.jsonSchema,
+      description: data.description,
+      titleField: data.titleField,
+      subtitleField: data.subtitleField,
+      allowedIn: data.allowedIn,
+      migrations: data.migrations ? compileMigrations(data.migrations, executor) : void 0,
+      migrationWriteBack: data.migrationWriteBack
+    });
+  }
+  for (const record of edgeTypes) {
+    const data = record.data;
+    const fromTypes = Array.isArray(data.from) ? data.from : [data.from];
+    const toTypes = Array.isArray(data.to) ? data.to : [data.to];
+    const compiledMigrations = data.migrations ? compileMigrations(data.migrations, executor) : void 0;
+    for (const aType of fromTypes) {
+      for (const bType of toTypes) {
+        entries.push({
+          aType,
+          axbType: data.name,
+          bType,
+          jsonSchema: data.jsonSchema,
+          description: data.description,
+          inverseLabel: data.inverseLabel,
+          titleField: data.titleField,
+          subtitleField: data.subtitleField,
+          allowedIn: data.allowedIn,
+          targetGraph: data.targetGraph,
+          migrations: compiledMigrations,
+          migrationWriteBack: data.migrationWriteBack
+        });
+      }
+    }
+  }
+  return createRegistry(entries);
+}
+
+// src/query.ts
+function buildEdgeQueryPlan(params) {
+  const { aType, aUid, axbType, bType, bUid, limit, orderBy } = params;
+  if (aUid && axbType && bUid && !params.where?.length) {
+    return { strategy: "get", docId: computeEdgeDocId(aUid, axbType, bUid) };
+  }
+  const filters = [];
+  if (aType) filters.push({ field: "aType", op: "==", value: aType });
+  if (aUid) filters.push({ field: "aUid", op: "==", value: aUid });
+  if (axbType) filters.push({ field: "axbType", op: "==", value: axbType });
+  if (bType) filters.push({ field: "bType", op: "==", value: bType });
+  if (bUid) filters.push({ field: "bUid", op: "==", value: bUid });
+  if (params.where) {
+    for (const clause of params.where) {
+      const field = BUILTIN_FIELDS.has(clause.field) ? clause.field : clause.field.startsWith("data.") ? clause.field : `data.${clause.field}`;
+      filters.push({ field, op: clause.op, value: clause.value });
+    }
+  }
+  if (filters.length === 0) {
+    throw new InvalidQueryError("findEdges requires at least one filter parameter");
+  }
+  const effectiveLimit = limit === void 0 ? DEFAULT_QUERY_LIMIT : limit || void 0;
+  return { strategy: "query", filters, options: { limit: effectiveLimit, orderBy } };
+}
+function buildNodeQueryPlan(params) {
+  const { aType, limit, orderBy } = params;
+  const filters = [
+    { field: "aType", op: "==", value: aType },
+    { field: "axbType", op: "==", value: NODE_RELATION }
+  ];
+  if (params.where) {
+    for (const clause of params.where) {
+      const field = BUILTIN_FIELDS.has(clause.field) ? clause.field : clause.field.startsWith("data.") ? clause.field : `data.${clause.field}`;
+      filters.push({ field, op: clause.op, value: clause.value });
+    }
+  }
+  const effectiveLimit = limit === void 0 ? DEFAULT_QUERY_LIMIT : limit || void 0;
+  return { strategy: "query", filters, options: { limit: effectiveLimit, orderBy } };
+}
+
+// src/query-safety.ts
+var SAFE_INDEX_PATTERNS = [
+  /* @__PURE__ */ new Set(["aUid", "axbType"]),
+  /* @__PURE__ */ new Set(["axbType", "bUid"]),
+  /* @__PURE__ */ new Set(["aType", "axbType"]),
+  /* @__PURE__ */ new Set(["axbType", "bType"])
+];
+function analyzeQuerySafety(filters) {
+  const builtinFieldsPresent = /* @__PURE__ */ new Set();
+  let hasDataFilters = false;
+  for (const f of filters) {
+    if (BUILTIN_FIELDS.has(f.field)) {
+      builtinFieldsPresent.add(f.field);
+    } else {
+      hasDataFilters = true;
+    }
+  }
+  for (const pattern of SAFE_INDEX_PATTERNS) {
+    let matched = true;
+    for (const field of pattern) {
+      if (!builtinFieldsPresent.has(field)) {
+        matched = false;
+        break;
+      }
+    }
+    if (matched) {
+      return { safe: true };
+    }
+  }
+  const presentFields = [...builtinFieldsPresent];
+  if (presentFields.length === 0 && hasDataFilters) {
+    return {
+      safe: false,
+      reason: "Query filters only use data.* fields with no builtin field constraints. This requires a full collection scan. Add aType, aUid, axbType, bType, or bUid filters, or set allowCollectionScan: true."
+    };
+  }
+  if (hasDataFilters) {
+    return {
+      safe: false,
+      reason: `Query filters on [${presentFields.join(", ")}] do not match any indexed pattern. data.* filters without an indexed base require a full collection scan. Safe patterns: (aUid + axbType), (axbType + bUid), (aType + axbType), (axbType + bType). Set allowCollectionScan: true to override.`
+    };
+  }
+  return {
+    safe: false,
+    reason: `Query filters on [${presentFields.join(", ")}] do not match any indexed pattern. This may cause a full collection scan on Firestore Enterprise. Safe patterns: (aUid + axbType), (axbType + bUid), (aType + axbType), (axbType + bType). Set allowCollectionScan: true to override.`
+  };
+}
+
+// src/transaction.ts
+function buildWritableNodeRecord2(aType, uid, data) {
+  return { aType, aUid: uid, axbType: NODE_RELATION, bType: aType, bUid: uid, data };
+}
+function buildWritableEdgeRecord2(aType, aUid, axbType, bType, bUid, data) {
+  return { aType, aUid, axbType, bType, bUid, data };
+}
+var GraphTransactionImpl = class {
+  constructor(backend, registry, scanProtection = "error", scopePath = "", globalWriteBack = "off") {
+    this.backend = backend;
+    this.registry = registry;
+    this.scanProtection = scanProtection;
+    this.scopePath = scopePath;
+    this.globalWriteBack = globalWriteBack;
+  }
+  async getNode(uid) {
+    const docId = computeNodeDocId(uid);
+    const record = await this.backend.getDoc(docId);
+    if (!record || !this.registry) return record;
+    const result = await migrateRecord(record, this.registry, this.globalWriteBack);
+    if (result.migrated && result.writeBack !== "off") {
+      await this.backend.updateDoc(docId, {
+        replaceData: result.record.data,
+        v: result.record.v
+      });
+    }
+    return result.record;
+  }
+  async getEdge(aUid, axbType, bUid) {
+    const docId = computeEdgeDocId(aUid, axbType, bUid);
+    const record = await this.backend.getDoc(docId);
+    if (!record || !this.registry) return record;
+    const result = await migrateRecord(record, this.registry, this.globalWriteBack);
+    if (result.migrated && result.writeBack !== "off") {
+      await this.backend.updateDoc(docId, {
+        replaceData: result.record.data,
+        v: result.record.v
+      });
+    }
+    return result.record;
+  }
+  async edgeExists(aUid, axbType, bUid) {
+    const docId = computeEdgeDocId(aUid, axbType, bUid);
+    const record = await this.backend.getDoc(docId);
+    return record !== null;
+  }
+  checkQuerySafety(filters, allowCollectionScan) {
+    if (allowCollectionScan || this.scanProtection === "off") return;
+    const result = analyzeQuerySafety(filters);
+    if (result.safe) return;
+    if (this.scanProtection === "error") {
+      throw new QuerySafetyError(result.reason);
+    }
+    console.warn(`[firegraph] Query safety warning: ${result.reason}`);
+  }
+  async findEdges(params) {
+    const plan = buildEdgeQueryPlan(params);
+    let records;
+    if (plan.strategy === "get") {
+      const record = await this.backend.getDoc(plan.docId);
+      records = record ? [record] : [];
+    } else {
+      this.checkQuerySafety(plan.filters, params.allowCollectionScan);
+      records = await this.backend.query(plan.filters, plan.options);
+    }
+    return this.applyMigrations(records);
+  }
+  async findNodes(params) {
+    const plan = buildNodeQueryPlan(params);
+    let records;
+    if (plan.strategy === "get") {
+      const record = await this.backend.getDoc(plan.docId);
+      records = record ? [record] : [];
+    } else {
+      this.checkQuerySafety(plan.filters, params.allowCollectionScan);
+      records = await this.backend.query(plan.filters, plan.options);
+    }
+    return this.applyMigrations(records);
+  }
+  async applyMigrations(records) {
+    if (!this.registry || records.length === 0) return records;
+    const results = await migrateRecords(records, this.registry, this.globalWriteBack);
+    for (const result of results) {
+      if (result.migrated && result.writeBack !== "off") {
+        const docId = result.record.axbType === NODE_RELATION ? computeNodeDocId(result.record.aUid) : computeEdgeDocId(result.record.aUid, result.record.axbType, result.record.bUid);
+        await this.backend.updateDoc(docId, {
+          replaceData: result.record.data,
+          v: result.record.v
+        });
+      }
+    }
+    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);
+    }
+    const docId = computeNodeDocId(uid);
+    const record = buildWritableNodeRecord2(aType, uid, data);
+    if (this.registry) {
+      const entry = this.registry.lookup(aType, NODE_RELATION, aType);
+      if (entry?.schemaVersion && entry.schemaVersion > 0) {
+        record.v = entry.schemaVersion;
+      }
+    }
+    await this.backend.setDoc(docId, record, mode);
+  }
+  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);
+    }
+    const docId = computeEdgeDocId(aUid, axbType, bUid);
+    const record = buildWritableEdgeRecord2(aType, aUid, axbType, bType, bUid, data);
+    if (this.registry) {
+      const entry = this.registry.lookup(aType, axbType, bType);
+      if (entry?.schemaVersion && entry.schemaVersion > 0) {
+        record.v = entry.schemaVersion;
+      }
+    }
+    await this.backend.setDoc(docId, record, mode);
+  }
+  async updateNode(uid, data) {
+    const docId = computeNodeDocId(uid);
+    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);
+    await this.backend.deleteDoc(docId);
+  }
+  async removeEdge(aUid, axbType, bUid) {
+    const docId = computeEdgeDocId(aUid, axbType, bUid);
+    await this.backend.deleteDoc(docId);
+  }
+};
+
+// src/client.ts
+var RESERVED_TYPE_NAMES = /* @__PURE__ */ new Set([META_NODE_TYPE, META_EDGE_TYPE]);
+function buildWritableNodeRecord3(aType, uid, data) {
+  return { aType, aUid: uid, axbType: NODE_RELATION, bType: aType, bUid: uid, data };
+}
+function buildWritableEdgeRecord3(aType, aUid, axbType, bType, bUid, data) {
+  return { aType, aUid, axbType, bType, bUid, data };
+}
+var GraphClientImpl = class _GraphClientImpl {
+  constructor(backend, options, metaBackend) {
+    this.backend = backend;
+    this.globalWriteBack = options?.migrationWriteBack ?? "off";
+    this.migrationSandbox = options?.migrationSandbox;
+    if (options?.registryMode) {
+      this.dynamicConfig = options.registryMode;
+      this.bootstrapRegistry = createBootstrapRegistry();
+      if (options.registry) {
+        this.staticRegistry = options.registry;
+      }
+      this.metaBackend = metaBackend;
+    } else {
+      this.staticRegistry = options?.registry;
+    }
+    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
+  dynamicConfig;
+  bootstrapRegistry;
+  dynamicRegistry;
+  metaBackend;
+  // Migration settings
+  globalWriteBack;
+  migrationSandbox;
+  // ---------------------------------------------------------------------------
+  // Backend access (exposed for traversal helpers and subgraph cloning)
+  // ---------------------------------------------------------------------------
+  /** @internal */
+  getBackend() {
+    return this.backend;
+  }
+  /**
+   * Snapshot of the currently-effective registry. Returns the merged view
+   * used for domain-type validation and migration — in dynamic mode this is
+   * `dynamicRegistry ?? staticRegistry ?? bootstrapRegistry`, so callers see
+   * updates after `reloadRegistry()` without having to re-resolve anything.
+   *
+   * Exposed for backends that need topology access during bulk operations
+   * (e.g. the Cloudflare DO backend's cross-DO cascade). Not part of the
+   * public `GraphClient` surface.
+   *
+   * @internal
+   */
+  getRegistrySnapshot() {
+    return this.getCombinedRegistry();
+  }
+  // ---------------------------------------------------------------------------
+  // Registry routing
+  // ---------------------------------------------------------------------------
+  getRegistryForType(aType) {
+    if (!this.dynamicConfig) return this.staticRegistry;
+    if (aType === META_NODE_TYPE || aType === META_EDGE_TYPE) {
+      return this.bootstrapRegistry;
+    }
+    return this.dynamicRegistry ?? this.staticRegistry ?? this.bootstrapRegistry;
+  }
+  getBackendForType(aType) {
+    if (this.metaBackend && (aType === META_NODE_TYPE || aType === META_EDGE_TYPE)) {
+      return this.metaBackend;
+    }
+    return this.backend;
+  }
+  getCombinedRegistry() {
+    if (!this.dynamicConfig) return this.staticRegistry;
+    return this.dynamicRegistry ?? this.staticRegistry ?? this.bootstrapRegistry;
+  }
+  // ---------------------------------------------------------------------------
+  // Query safety
+  // ---------------------------------------------------------------------------
+  checkQuerySafety(filters, allowCollectionScan) {
+    if (allowCollectionScan || this.scanProtection === "off") return;
+    const result = analyzeQuerySafety(filters);
+    if (result.safe) return;
+    if (this.scanProtection === "error") {
+      throw new QuerySafetyError(result.reason);
+    }
+    console.warn(`[firegraph] Query safety warning: ${result.reason}`);
+  }
+  // ---------------------------------------------------------------------------
+  // Migration helpers
+  // ---------------------------------------------------------------------------
+  async applyMigration(record, docId) {
+    const registry = this.getCombinedRegistry();
+    if (!registry) return record;
+    const result = await migrateRecord(record, registry, this.globalWriteBack);
+    if (result.migrated) {
+      this.handleWriteBack(result, docId);
+    }
+    return result.record;
+  }
+  async applyMigrations(records) {
+    const registry = this.getCombinedRegistry();
+    if (!registry || records.length === 0) return records;
+    const results = await migrateRecords(records, registry, this.globalWriteBack);
+    for (const result of results) {
+      if (result.migrated) {
+        const docId = result.record.axbType === NODE_RELATION ? computeNodeDocId(result.record.aUid) : computeEdgeDocId(result.record.aUid, result.record.axbType, result.record.bUid);
+        this.handleWriteBack(result, docId);
+      }
+    }
+    return results.map((r) => r.record);
+  }
+  /**
+   * Fire-and-forget write-back for a migrated record. Both `'eager'` and
+   * `'background'` are non-blocking; the difference is the log level on
+   * failure. For synchronous write-back, use a transaction — see
+   * `GraphTransactionImpl`.
+   */
+  handleWriteBack(result, docId) {
+    if (result.writeBack === "off") return;
+    const doWriteBack = async () => {
+      try {
+        await this.backend.updateDoc(docId, {
+          replaceData: result.record.data,
+          v: result.record.v
+        });
+      } catch (err) {
+        const msg = `[firegraph] Migration write-back failed for ${docId}: ${err.message}`;
+        if (result.writeBack === "eager") {
+          console.error(msg);
+        } else {
+          console.warn(msg);
+        }
+      }
+    };
+    void doWriteBack();
+  }
+  // ---------------------------------------------------------------------------
+  // GraphReader
+  // ---------------------------------------------------------------------------
+  async getNode(uid) {
+    const docId = computeNodeDocId(uid);
+    const record = await this.backend.getDoc(docId);
+    if (!record) return null;
+    return this.applyMigration(record, docId);
+  }
+  async getEdge(aUid, axbType, bUid) {
+    const docId = computeEdgeDocId(aUid, axbType, bUid);
+    const record = await this.backend.getDoc(docId);
+    if (!record) return null;
+    return this.applyMigration(record, docId);
+  }
+  async edgeExists(aUid, axbType, bUid) {
+    const docId = computeEdgeDocId(aUid, axbType, bUid);
+    const record = await this.backend.getDoc(docId);
+    return record !== null;
+  }
+  async findEdges(params) {
+    const plan = buildEdgeQueryPlan(params);
+    let records;
+    if (plan.strategy === "get") {
+      const record = await this.backend.getDoc(plan.docId);
+      records = record ? [record] : [];
+    } else {
+      this.checkQuerySafety(plan.filters, params.allowCollectionScan);
+      records = await this.backend.query(plan.filters, plan.options);
+    }
+    return this.applyMigrations(records);
+  }
+  async findNodes(params) {
+    const plan = buildNodeQueryPlan(params);
+    let records;
+    if (plan.strategy === "get") {
+      const record = await this.backend.getDoc(plan.docId);
+      records = record ? [record] : [];
+    } else {
+      this.checkQuerySafety(plan.filters, params.allowCollectionScan);
+      records = await this.backend.query(plan.filters, plan.options);
+    }
+    return this.applyMigrations(records);
+  }
+  // ---------------------------------------------------------------------------
+  // 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);
+    }
+    const backend = this.getBackendForType(aType);
+    const docId = computeNodeDocId(uid);
+    const record = buildWritableNodeRecord3(aType, uid, data);
+    if (registry) {
+      const entry = registry.lookup(aType, NODE_RELATION, aType);
+      if (entry?.schemaVersion && entry.schemaVersion > 0) {
+        record.v = entry.schemaVersion;
+      }
+    }
+    await backend.setDoc(docId, record, mode);
+  }
+  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);
+    }
+    const backend = this.getBackendForType(aType);
+    const docId = computeEdgeDocId(aUid, axbType, bUid);
+    const record = buildWritableEdgeRecord3(aType, aUid, axbType, bType, bUid, data);
+    if (registry) {
+      const entry = registry.lookup(aType, axbType, bType);
+      if (entry?.schemaVersion && entry.schemaVersion > 0) {
+        record.v = entry.schemaVersion;
+      }
+    }
+    await backend.setDoc(docId, record, mode);
+  }
+  async updateNode(uid, data) {
+    const docId = computeNodeDocId(uid);
+    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);
+    await this.backend.deleteDoc(docId);
+  }
+  async removeEdge(aUid, axbType, bUid) {
+    const docId = computeEdgeDocId(aUid, axbType, bUid);
+    await this.backend.deleteDoc(docId);
+  }
+  // ---------------------------------------------------------------------------
+  // Transactions & Batches
+  // ---------------------------------------------------------------------------
+  async runTransaction(fn) {
+    return this.backend.runTransaction(async (txBackend) => {
+      const graphTx = new GraphTransactionImpl(
+        txBackend,
+        this.getCombinedRegistry(),
+        this.scanProtection,
+        this.backend.scopePath,
+        this.globalWriteBack
+      );
+      return fn(graphTx);
+    });
+  }
+  batch() {
+    return new GraphBatchImpl(
+      this.backend.createBatch(),
+      this.getCombinedRegistry(),
+      this.backend.scopePath
+    );
+  }
+  // ---------------------------------------------------------------------------
+  // Subgraph
+  // ---------------------------------------------------------------------------
+  subgraph(parentNodeUid, name = "graph") {
+    if (!parentNodeUid || parentNodeUid.includes("/")) {
+      throw new FiregraphError(
+        `Invalid parentNodeUid for subgraph: "${parentNodeUid}". Must be a non-empty string without "/".`,
+        "INVALID_SUBGRAPH"
+      );
+    }
+    if (name.includes("/")) {
+      throw new FiregraphError(
+        `Subgraph name must not contain "/": got "${name}". Use chained .subgraph() calls for nested subgraphs.`,
+        "INVALID_SUBGRAPH"
+      );
+    }
+    const childBackend = this.backend.subgraph(parentNodeUid, name);
+    return new _GraphClientImpl(
+      childBackend,
+      {
+        registry: this.getCombinedRegistry(),
+        scanProtection: this.scanProtection,
+        migrationWriteBack: this.globalWriteBack,
+        migrationSandbox: this.migrationSandbox
+      }
+      // Subgraphs do not have meta-backends; meta lives only at the root.
+    );
+  }
+  // ---------------------------------------------------------------------------
+  // Collection group query
+  // ---------------------------------------------------------------------------
+  async findEdgesGlobal(params, collectionName) {
+    if (!this.backend.findEdgesGlobal) {
+      throw new FiregraphError(
+        "findEdgesGlobal() is not supported by the current storage backend.",
+        "UNSUPPORTED_OPERATION"
+      );
+    }
+    const plan = buildEdgeQueryPlan(params);
+    if (plan.strategy === "get") {
+      throw new FiregraphError(
+        "findEdgesGlobal() 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 records = await this.backend.findEdgesGlobal(params, collectionName);
+    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) {
+    return this.backend.removeNodeCascade(uid, this, options);
+  }
+  async bulkRemoveEdges(params, options) {
+    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) {
+    if (!this.dynamicConfig) {
+      throw new DynamicRegistryError(
+        'defineNodeType() is only available in dynamic registry mode. Pass registryMode: { mode: "dynamic" } to createGraphClient().'
+      );
+    }
+    if (RESERVED_TYPE_NAMES.has(name)) {
+      throw new DynamicRegistryError(
+        `Cannot define type "${name}": this name is reserved for the meta-registry.`
+      );
+    }
+    if (this.staticRegistry?.lookup(name, NODE_RELATION, name)) {
+      throw new DynamicRegistryError(
+        `Cannot define node type "${name}": already defined in the static registry.`
+      );
+    }
+    const uid = generateDeterministicUid(META_NODE_TYPE, name);
+    const data = { name, jsonSchema };
+    if (description !== void 0) data.description = description;
+    if (options?.titleField !== void 0) data.titleField = options.titleField;
+    if (options?.subtitleField !== void 0) data.subtitleField = options.subtitleField;
+    if (options?.viewTemplate !== void 0) data.viewTemplate = options.viewTemplate;
+    if (options?.viewCss !== void 0) data.viewCss = options.viewCss;
+    if (options?.allowedIn !== void 0) data.allowedIn = options.allowedIn;
+    if (options?.migrationWriteBack !== void 0)
+      data.migrationWriteBack = options.migrationWriteBack;
+    if (options?.migrations !== void 0) {
+      data.migrations = await this.serializeMigrations(options.migrations);
+    }
+    await this.putNode(META_NODE_TYPE, uid, data);
+  }
+  async defineEdgeType(name, topology, jsonSchema, description, options) {
+    if (!this.dynamicConfig) {
+      throw new DynamicRegistryError(
+        'defineEdgeType() is only available in dynamic registry mode. Pass registryMode: { mode: "dynamic" } to createGraphClient().'
+      );
+    }
+    if (RESERVED_TYPE_NAMES.has(name)) {
+      throw new DynamicRegistryError(
+        `Cannot define type "${name}": this name is reserved for the meta-registry.`
+      );
+    }
+    if (this.staticRegistry) {
+      const fromTypes = Array.isArray(topology.from) ? topology.from : [topology.from];
+      const toTypes = Array.isArray(topology.to) ? topology.to : [topology.to];
+      for (const aType of fromTypes) {
+        for (const bType of toTypes) {
+          if (this.staticRegistry.lookup(aType, name, bType)) {
+            throw new DynamicRegistryError(
+              `Cannot define edge type "${name}" for (${aType}) -> (${bType}): already defined in the static registry.`
+            );
+          }
+        }
+      }
+    }
+    const uid = generateDeterministicUid(META_EDGE_TYPE, name);
+    const data = {
+      name,
+      from: topology.from,
+      to: topology.to
+    };
+    if (jsonSchema !== void 0) data.jsonSchema = jsonSchema;
+    if (topology.inverseLabel !== void 0) data.inverseLabel = topology.inverseLabel;
+    if (topology.targetGraph !== void 0) data.targetGraph = topology.targetGraph;
+    if (description !== void 0) data.description = description;
+    if (options?.titleField !== void 0) data.titleField = options.titleField;
+    if (options?.subtitleField !== void 0) data.subtitleField = options.subtitleField;
+    if (options?.viewTemplate !== void 0) data.viewTemplate = options.viewTemplate;
+    if (options?.viewCss !== void 0) data.viewCss = options.viewCss;
+    if (options?.allowedIn !== void 0) data.allowedIn = options.allowedIn;
+    if (options?.migrationWriteBack !== void 0)
+      data.migrationWriteBack = options.migrationWriteBack;
+    if (options?.migrations !== void 0) {
+      data.migrations = await this.serializeMigrations(options.migrations);
+    }
+    await this.putNode(META_EDGE_TYPE, uid, data);
+  }
+  async reloadRegistry() {
+    if (!this.dynamicConfig) {
+      throw new DynamicRegistryError(
+        'reloadRegistry() is only available in dynamic registry mode. Pass registryMode: { mode: "dynamic" } to createGraphClient().'
+      );
+    }
+    const reader = this.createMetaReader();
+    const dynamicOnly = await createRegistryFromGraph(reader, this.migrationSandbox);
+    if (this.staticRegistry) {
+      this.dynamicRegistry = createMergedRegistry(this.staticRegistry, dynamicOnly);
+    } else {
+      this.dynamicRegistry = dynamicOnly;
+    }
+  }
+  async serializeMigrations(migrations) {
+    const result = migrations.map((m) => {
+      const source = typeof m.up === "function" ? m.up.toString() : m.up;
+      return { fromVersion: m.fromVersion, toVersion: m.toVersion, up: source };
+    });
+    await Promise.all(result.map((m) => precompileSource(m.up, this.migrationSandbox)));
+    return result;
+  }
+  /**
+   * Build a `GraphReader` over the meta-backend. If meta lives in the same
+   * collection as the main backend, `this` is returned directly.
+   */
+  createMetaReader() {
+    if (!this.metaBackend) return this;
+    const backend = this.metaBackend;
+    const executeMetaQuery = (filters, options) => backend.query(filters, options);
+    return {
+      async getNode(uid) {
+        return backend.getDoc(computeNodeDocId(uid));
+      },
+      async getEdge(aUid, axbType, bUid) {
+        return backend.getDoc(computeEdgeDocId(aUid, axbType, bUid));
+      },
+      async edgeExists(aUid, axbType, bUid) {
+        const record = await backend.getDoc(computeEdgeDocId(aUid, axbType, bUid));
+        return record !== null;
+      },
+      async findEdges(params) {
+        const plan = buildEdgeQueryPlan(params);
+        if (plan.strategy === "get") {
+          const record = await backend.getDoc(plan.docId);
+          return record ? [record] : [];
+        }
+        return executeMetaQuery(plan.filters, plan.options);
+      },
+      async findNodes(params) {
+        const plan = buildNodeQueryPlan(params);
+        if (plan.strategy === "get") {
+          const record = await backend.getDoc(plan.docId);
+          return record ? [record] : [];
+        }
+        return executeMetaQuery(plan.filters, plan.options);
+      }
+    };
+  }
+};
+function createGraphClient(backend, options, metaBackend) {
+  return new GraphClientImpl(backend, options, metaBackend);
+}
+
+// src/id.ts
+var import_nanoid = require("nanoid");
+function generateId() {
+  return (0, import_nanoid.nanoid)();
+}
+
+// src/firestore-enterprise/backend.ts
+var import_firestore4 = require("@google-cloud/firestore");
+
+// src/bulk.ts
+var MAX_BATCH_SIZE = 500;
+var DEFAULT_MAX_RETRIES = 3;
+var BASE_DELAY_MS = 200;
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function chunk(arr, size) {
+  const chunks = [];
+  for (let i = 0; i < arr.length; i += size) {
+    chunks.push(arr.slice(i, i + size));
+  }
+  return chunks;
+}
+async function bulkDeleteDocIds(db, collectionPath, docIds, options) {
+  if (docIds.length === 0) {
+    return { deleted: 0, batches: 0, errors: [] };
+  }
+  const batchSize = Math.min(options?.batchSize ?? MAX_BATCH_SIZE, MAX_BATCH_SIZE);
+  const maxRetries = options?.maxRetries ?? DEFAULT_MAX_RETRIES;
+  const onProgress = options?.onProgress;
+  const chunks = chunk(docIds, batchSize);
+  const errors = [];
+  let deleted = 0;
+  let completedBatches = 0;
+  for (let i = 0; i < chunks.length; i++) {
+    const ids = chunks[i];
+    let committed = false;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      try {
+        const batch = db.batch();
+        const collectionRef = db.collection(collectionPath);
+        for (const id of ids) {
+          batch.delete(collectionRef.doc(id));
+        }
+        await batch.commit();
+        committed = true;
+        deleted += ids.length;
+        break;
+      } catch (err) {
+        if (attempt < maxRetries) {
+          const delay = BASE_DELAY_MS * Math.pow(2, attempt);
+          await sleep(delay);
+        } else {
+          errors.push({
+            batchIndex: i,
+            error: err instanceof Error ? err : new Error(String(err)),
+            operationCount: ids.length
+          });
+        }
+      }
+    }
+    if (committed) {
+      completedBatches++;
+    }
+    if (onProgress) {
+      onProgress({
+        completedBatches,
+        totalBatches: chunks.length,
+        deletedSoFar: deleted
+      });
+    }
+  }
+  return { deleted, batches: completedBatches, errors };
+}
+async function bulkRemoveEdges(db, collectionPath, reader, params, options) {
+  const effectiveParams = params.limit !== void 0 ? { ...params, allowCollectionScan: params.allowCollectionScan ?? true } : { ...params, limit: 0, allowCollectionScan: params.allowCollectionScan ?? true };
+  const edges = await reader.findEdges(effectiveParams);
+  const docIds = edges.map((e) => computeEdgeDocId(e.aUid, e.axbType, e.bUid));
+  return bulkDeleteDocIds(db, collectionPath, docIds, options);
+}
+async function deleteSubcollectionsRecursive(db, collectionPath, docId, options) {
+  const docRef = db.collection(collectionPath).doc(docId);
+  const subcollections = await docRef.listCollections();
+  if (subcollections.length === 0) return { deleted: 0, errors: [] };
+  let totalDeleted = 0;
+  const allErrors = [];
+  const subOptions = options ? { batchSize: options.batchSize, maxRetries: options.maxRetries } : void 0;
+  for (const subCollRef of subcollections) {
+    const subCollPath = subCollRef.path;
+    const snapshot = await subCollRef.select().get();
+    const subDocIds = snapshot.docs.map((d) => d.id);
+    for (const subDocId of subDocIds) {
+      const subResult = await deleteSubcollectionsRecursive(db, subCollPath, subDocId, subOptions);
+      totalDeleted += subResult.deleted;
+      allErrors.push(...subResult.errors);
+    }
+    if (subDocIds.length > 0) {
+      const result = await bulkDeleteDocIds(db, subCollPath, subDocIds, subOptions);
+      totalDeleted += result.deleted;
+      allErrors.push(...result.errors);
+    }
+  }
+  return { deleted: totalDeleted, errors: allErrors };
+}
+async function removeNodeCascade(db, collectionPath, reader, uid, options) {
+  const [outgoingRaw, incomingRaw] = await Promise.all([
+    reader.findEdges({ aUid: uid, allowCollectionScan: true, limit: 0 }),
+    reader.findEdges({ bUid: uid, allowCollectionScan: true, limit: 0 })
+  ]);
+  const outgoing = outgoingRaw.filter((e) => e.axbType !== NODE_RELATION);
+  const incoming = incomingRaw.filter((e) => e.axbType !== NODE_RELATION);
+  const edgeDocIdSet = /* @__PURE__ */ new Set();
+  const allEdges = [];
+  for (const edge of [...outgoing, ...incoming]) {
+    const docId = computeEdgeDocId(edge.aUid, edge.axbType, edge.bUid);
+    if (!edgeDocIdSet.has(docId)) {
+      edgeDocIdSet.add(docId);
+      allEdges.push(edge);
+    }
+  }
+  const shouldDeleteSubcollections = options?.deleteSubcollections !== false;
+  const nodeDocId = computeNodeDocId(uid);
+  let subcollectionResult = { deleted: 0, errors: [] };
+  if (shouldDeleteSubcollections) {
+    subcollectionResult = await deleteSubcollectionsRecursive(
+      db,
+      collectionPath,
+      nodeDocId,
+      options
+    );
+  }
+  const edgeDocIds = allEdges.map((e) => computeEdgeDocId(e.aUid, e.axbType, e.bUid));
+  const allDocIds = [...edgeDocIds, nodeDocId];
+  const batchSize = Math.min(options?.batchSize ?? MAX_BATCH_SIZE, MAX_BATCH_SIZE);
+  const result = await bulkDeleteDocIds(db, collectionPath, allDocIds, {
+    ...options,
+    batchSize
+  });
+  const totalChunks = Math.ceil(allDocIds.length / batchSize);
+  const nodeChunkIndex = totalChunks - 1;
+  const nodeDeleted = !result.errors.some((e) => e.batchIndex === nodeChunkIndex);
+  const topLevelEdgesDeleted = nodeDeleted ? result.deleted - 1 : result.deleted;
+  return {
+    deleted: result.deleted + subcollectionResult.deleted,
+    batches: result.batches,
+    errors: [...result.errors, ...subcollectionResult.errors],
+    edgesDeleted: topLevelEdgesDeleted,
+    nodeDeleted
+  };
+}
+
+// src/internal/backend.ts
+function createCapabilities(caps) {
+  return {
+    has: (capability) => caps.has(capability),
+    values: () => caps.values()
+  };
+}
+
+// src/internal/firestore-aggregate.ts
+var import_firestore2 = require("@google-cloud/firestore");
+function applyFiltersToQuery(base, filters) {
+  let q = base;
+  for (const f of filters) {
+    q = q.where(f.field, f.op, f.value);
+  }
+  return q;
+}
+async function runFirestoreAggregate(base, spec, filters, { edition }) {
+  if (Object.keys(spec).length === 0) {
+    throw new FiregraphError(
+      "aggregate() requires at least one aggregation in the `aggregates` map.",
+      "INVALID_QUERY"
+    );
+  }
+  const filtered = applyFiltersToQuery(base, filters);
+  const aggregations = {};
+  for (const [alias, { op, field }] of Object.entries(spec)) {
+    if (op === "count") {
+      if (field !== void 0) {
+        throw new FiregraphError(
+          `Aggregate '${alias}' op 'count' must not specify a field \u2014 count operates on rows, not a column expression.`,
+          "INVALID_QUERY"
+        );
+      }
+      aggregations[alias] = import_firestore2.AggregateField.count();
+      continue;
+    }
+    if (!field) {
+      throw new FiregraphError(
+        `Aggregate '${alias}' op '${op}' requires a field.`,
+        "INVALID_QUERY"
+      );
+    }
+    if (op === "sum") {
+      aggregations[alias] = import_firestore2.AggregateField.sum(field);
+    } else if (op === "avg") {
+      aggregations[alias] = import_firestore2.AggregateField.average(field);
+    } else {
+      const editionLabel = edition === "enterprise" ? "Firestore Enterprise" : "Firestore Standard";
+      throw new FiregraphError(
+        `Aggregate op '${op}' is not supported on ${editionLabel}. Both Firestore editions support count/sum/avg via the classic Query API; min/max requires a backend with SQL aggregation (SQLite or DO).`,
+        "UNSUPPORTED_AGGREGATE"
+      );
+    }
+  }
+  const snap = await filtered.aggregate(aggregations).get();
+  const data = snap.data();
+  const out = {};
+  for (const alias of Object.keys(spec)) {
+    const v = data[alias];
+    if (v === null || v === void 0) {
+      const op = spec[alias].op;
+      out[alias] = op === "avg" ? Number.NaN : 0;
+    } else {
+      out[alias] = v;
+    }
+  }
+  return out;
+}
+
+// src/internal/firestore-bulk-dml.ts
+var _Pipelines = null;
+var _Timestamp = null;
+async function getFirestoreSurface() {
+  if (!_Pipelines || !_Timestamp) {
+    const mod = await import("@google-cloud/firestore");
+    _Pipelines = mod.Pipelines;
+    _Timestamp = mod.Timestamp;
+  }
+  return { P: _Pipelines, Ts: _Timestamp };
+}
+function buildFilterExpression(P, filter) {
+  const { field: fieldName, op, value } = filter;
+  switch (op) {
+    case "==":
+      return P.equal(fieldName, value);
+    case "!=":
+      return P.notEqual(fieldName, value);
+    case "<":
+      return P.lessThan(fieldName, value);
+    case "<=":
+      return P.lessThanOrEqual(fieldName, value);
+    case ">":
+      return P.greaterThan(fieldName, value);
+    case ">=":
+      return P.greaterThanOrEqual(fieldName, value);
+    case "in":
+      return P.equalAny(fieldName, value);
+    case "not-in":
+      return P.notEqualAny(fieldName, value);
+    case "array-contains":
+      return P.arrayContains(fieldName, value);
+    case "array-contains-any":
+      return P.arrayContainsAny(fieldName, value);
+    default:
+      throw new FiregraphError(
+        `bulkDelete/bulkUpdate: unsupported filter op "${op}" for pipeline DML.`,
+        "INVALID_QUERY"
+      );
+  }
+}
+function applyWhere(P, pipeline, filters) {
+  const exprs = filters.map((f) => buildFilterExpression(P, f));
+  if (exprs.length === 1) {
+    return pipeline.where(exprs[0]);
+  }
+  const [first, second, ...rest] = exprs;
+  return pipeline.where(P.and(first, second, ...rest));
+}
+function assertNonEmptyFilters(filters, op) {
+  if (filters.length === 0) {
+    throw new FiregraphError(
+      `bulk${op === "delete" ? "Delete" : "Update"}() on Firestore requires at least one filter; an empty filter list would target the whole collection. To wipe a subgraph, use removeNodeCascade() on the parent node instead.`,
+      "INVALID_QUERY"
+    );
+  }
+}
+async function runFirestorePipelineDelete(db, collectionPath, filters, _options) {
+  assertNonEmptyFilters(filters, "delete");
+  const { P } = await getFirestoreSurface();
+  let pipeline = db.pipeline().collection(collectionPath);
+  pipeline = applyWhere(P, pipeline, filters);
+  const snap = await pipeline.delete().execute();
+  return {
+    deleted: snap.results.length,
+    batches: 1,
+    errors: []
+  };
+}
+async function runFirestorePipelineUpdate(db, collectionPath, filters, patch, _options) {
+  assertNonEmptyFilters(filters, "update");
+  const ops = flattenPatch(patch.data);
+  if (ops.length === 0) {
+    throw new FiregraphError(
+      "bulkUpdate(): patch.data produced no field updates. An empty patch would only stamp updatedAt, which is almost certainly a bug.",
+      "INVALID_QUERY"
+    );
+  }
+  for (const op of ops) {
+    if (op.delete) {
+      throw new FiregraphError(
+        `bulkUpdate(): preview Pipeline DML does not support deleteField() sentinels (no typed delete-transform on @google-cloud/firestore@8.5.0's Pipeline.update(AliasedExpression[])). Drop the delete from the patch or use replaceEdge/replaceNode for the affected rows.`,
+        "INVALID_QUERY"
+      );
+    }
+  }
+  const { P, Ts } = await getFirestoreSurface();
+  const transforms = ops.map((op) => {
+    const alias = `data.${op.path.join(".")}`;
+    return P.constant(op.value).as(alias);
+  });
+  transforms.push(P.constant(Ts.now()).as("updatedAt"));
+  let pipeline = db.pipeline().collection(collectionPath);
+  pipeline = applyWhere(P, pipeline, filters);
+  const snap = await pipeline.update(transforms).execute();
+  return {
+    deleted: snap.results.length,
+    batches: 1,
+    errors: []
+  };
+}
+
+// src/internal/firestore-classic-adapter.ts
+function createFirestoreAdapter(db, collectionPath) {
+  const collectionRef = db.collection(collectionPath);
+  return {
+    collectionPath,
+    async getDoc(docId) {
+      const snap = await collectionRef.doc(docId).get();
+      if (!snap.exists) return null;
+      return snap.data();
+    },
+    async setDoc(docId, data, options) {
+      if (options?.merge) {
+        await collectionRef.doc(docId).set(data, { merge: true });
+      } else {
+        await collectionRef.doc(docId).set(data);
+      }
+    },
+    async updateDoc(docId, data) {
+      await collectionRef.doc(docId).update(data);
+    },
+    async deleteDoc(docId) {
+      await collectionRef.doc(docId).delete();
+    },
+    async query(filters, options) {
+      let q = collectionRef;
+      for (const f of filters) {
+        q = q.where(f.field, f.op, f.value);
+      }
+      if (options?.orderBy) {
+        q = q.orderBy(options.orderBy.field, options.orderBy.direction ?? "asc");
+      }
+      if (options?.limit !== void 0) {
+        q = q.limit(options.limit);
+      }
+      const snap = await q.get();
+      return snap.docs.map((doc) => doc.data());
+    }
+  };
+}
+function createTransactionAdapter(db, collectionPath, tx) {
+  const collectionRef = db.collection(collectionPath);
+  return {
+    async getDoc(docId) {
+      const snap = await tx.get(collectionRef.doc(docId));
+      if (!snap.exists) return null;
+      return snap.data();
+    },
+    setDoc(docId, data, options) {
+      if (options?.merge) {
+        tx.set(collectionRef.doc(docId), data, { merge: true });
+      } else {
+        tx.set(collectionRef.doc(docId), data);
+      }
+    },
+    updateDoc(docId, data) {
+      tx.update(collectionRef.doc(docId), data);
+    },
+    deleteDoc(docId) {
+      tx.delete(collectionRef.doc(docId));
+    },
+    async query(filters, options) {
+      let q = collectionRef;
+      for (const f of filters) {
+        q = q.where(f.field, f.op, f.value);
+      }
+      if (options?.orderBy) {
+        q = q.orderBy(options.orderBy.field, options.orderBy.direction ?? "asc");
+      }
+      if (options?.limit !== void 0) {
+        q = q.limit(options.limit);
+      }
+      const snap = await tx.get(q);
+      return snap.docs.map((doc) => doc.data());
+    }
+  };
+}
+function createBatchAdapter(db, collectionPath) {
+  const collectionRef = db.collection(collectionPath);
+  const batch = db.batch();
+  return {
+    setDoc(docId, data, options) {
+      if (options?.merge) {
+        batch.set(collectionRef.doc(docId), data, { merge: true });
+      } else {
+        batch.set(collectionRef.doc(docId), data);
+      }
+    },
+    updateDoc(docId, data) {
+      batch.update(collectionRef.doc(docId), data);
+    },
+    deleteDoc(docId) {
+      batch.delete(collectionRef.doc(docId));
+    },
+    async commit() {
+      await batch.commit();
+    }
+  };
+}
+
+// src/internal/firestore-classic-expand.ts
+var FIRESTORE_CLASSIC_IN_CHUNK_SIZE = 30;
+function readField(record, path) {
+  if (!path.includes(".")) {
+    return record[path];
+  }
+  let cursor = record;
+  for (const seg of path.split(".")) {
+    if (cursor === null || typeof cursor !== "object") return void 0;
+    cursor = cursor[seg];
+  }
+  return cursor;
+}
+function compareFieldValues(a, b) {
+  if (a === b) return 0;
+  if (a === void 0 || a === null) return -1;
+  if (b === void 0 || b === null) return 1;
+  const ta = typeof a;
+  const tb = typeof b;
+  if (ta === tb) {
+    return a < b ? -1 : 1;
+  }
+  const sa = String(a);
+  const sb = String(b);
+  return sa < sb ? -1 : sa > sb ? 1 : 0;
+}
+async function runFirestoreClassicExpand(adapter, params) {
+  if (params.sources.length === 0) {
+    return params.hydrate ? { edges: [], targets: [] } : { edges: [] };
+  }
+  if (params.axbType.length === 0) {
+    throw new FiregraphError("expand(): axbType must be a non-empty string.", "INVALID_QUERY");
+  }
+  const direction = params.direction ?? "forward";
+  const sourceField = direction === "forward" ? "aUid" : "bUid";
+  const chunks = chunkUids(params.sources, FIRESTORE_CLASSIC_IN_CHUNK_SIZE);
+  const totalLimit = params.limitPerSource !== void 0 ? params.sources.length * params.limitPerSource : void 0;
+  const buildFilters = (chunk2) => {
+    const filters = [
+      { field: "axbType", op: "==", value: params.axbType },
+      { field: sourceField, op: "in", value: chunk2 }
+    ];
+    if (params.aType !== void 0) {
+      filters.push({ field: "aType", op: "==", value: params.aType });
+    }
+    if (params.bType !== void 0) {
+      filters.push({ field: "bType", op: "==", value: params.bType });
+    }
+    return filters;
+  };
+  const buildOptions = (chunk2) => {
+    const opts = {};
+    if (params.orderBy) opts.orderBy = params.orderBy;
+    if (params.limitPerSource !== void 0) {
+      opts.limit = chunk2.length * params.limitPerSource;
+    }
+    return opts;
+  };
+  const chunkResults = await Promise.all(
+    chunks.map((chunk2) => adapter.query(buildFilters(chunk2), buildOptions(chunk2)))
+  );
+  let edges = chunkResults.flat();
+  if (params.axbType === NODE_RELATION) {
+    edges = edges.filter((e) => e.aUid !== e.bUid);
+  }
+  if (params.orderBy) {
+    const sortField = params.orderBy.field;
+    const dir = params.orderBy.direction ?? "asc";
+    edges.sort((a, b) => {
+      const cmp = compareFieldValues(readField(a, sortField), readField(b, sortField));
+      return dir === "asc" ? cmp : -cmp;
+    });
+  }
+  if (totalLimit !== void 0 && edges.length > totalLimit) {
+    edges = edges.slice(0, totalLimit);
+  }
+  if (!params.hydrate) return { edges };
+  const targetUids = edges.map((e) => direction === "forward" ? e.bUid : e.aUid);
+  const uniqueTargets = [...new Set(targetUids)];
+  if (uniqueTargets.length === 0) {
+    return { edges, targets: [] };
+  }
+  const hydrateChunks = chunkUids(uniqueTargets, FIRESTORE_CLASSIC_IN_CHUNK_SIZE);
+  const hydrateResults = await Promise.all(
+    hydrateChunks.map(
+      (chunk2) => adapter.query([
+        { field: "axbType", op: "==", value: NODE_RELATION },
+        { field: "aUid", op: "in", value: chunk2 }
+      ])
+    )
+  );
+  const byUid = /* @__PURE__ */ new Map();
+  for (const row of hydrateResults.flat()) {
+    byUid.set(row.bUid, row);
+  }
+  const targets = targetUids.map((uid) => byUid.get(uid) ?? null);
+  return { edges, targets };
+}
+function chunkUids(uids, chunkSize) {
+  if (chunkSize <= 0) {
+    throw new FiregraphError(
+      `chunkUids: chunkSize must be positive (got ${chunkSize}).`,
+      "INVALID_QUERY"
+    );
+  }
+  const out = [];
+  for (let i = 0; i < uids.length; i += chunkSize) {
+    out.push(uids.slice(i, i + chunkSize));
+  }
+  return out;
+}
+
+// src/internal/firestore-expand.ts
+var _Pipelines2 = null;
+async function getPipelines() {
+  if (!_Pipelines2) {
+    const mod = await import("@google-cloud/firestore");
+    _Pipelines2 = mod.Pipelines;
+  }
+  return _Pipelines2;
+}
+async function runFirestorePipelineExpand(db, collectionPath, params) {
+  if (params.sources.length === 0) {
+    return params.hydrate ? { edges: [], targets: [] } : { edges: [] };
+  }
+  if (params.axbType.length === 0) {
+    throw new FiregraphError("expand(): axbType must be a non-empty string.", "INVALID_QUERY");
+  }
+  const direction = params.direction ?? "forward";
+  const sourceField = direction === "forward" ? "aUid" : "bUid";
+  const P = await getPipelines();
+  const exprs = [
+    P.equal("axbType", params.axbType),
+    P.equalAny(sourceField, params.sources)
+  ];
+  if (params.aType !== void 0) exprs.push(P.equal("aType", params.aType));
+  if (params.bType !== void 0) exprs.push(P.equal("bType", params.bType));
+  let pipeline = db.pipeline().collection(collectionPath);
+  if (exprs.length === 1) {
+    pipeline = pipeline.where(exprs[0]);
+  } else {
+    const [first, second, ...rest] = exprs;
+    pipeline = pipeline.where(P.and(first, second, ...rest));
+  }
+  if (params.orderBy) {
+    const f = P.field(params.orderBy.field);
+    const ordering = params.orderBy.direction === "desc" ? f.descending() : f.ascending();
+    pipeline = pipeline.sort(ordering);
+  }
+  const totalLimit = params.limitPerSource !== void 0 ? params.sources.length * params.limitPerSource : void 0;
+  if (totalLimit !== void 0) {
+    pipeline = pipeline.limit(totalLimit);
+  }
+  const snap = await pipeline.execute();
+  let edges = snap.results.map((r) => r.data());
+  if (params.axbType === NODE_RELATION) {
+    edges = edges.filter((e) => e.aUid !== e.bUid);
+  }
+  if (!params.hydrate) return { edges };
+  const targetUids = edges.map((e) => direction === "forward" ? e.bUid : e.aUid);
+  const uniqueTargets = [...new Set(targetUids)];
+  if (uniqueTargets.length === 0) {
+    return { edges, targets: [] };
+  }
+  const hydratePipeline = db.pipeline().collection(collectionPath).where(
+    P.and(P.equal("axbType", NODE_RELATION), P.equalAny("aUid", uniqueTargets))
+  );
+  const hydrateSnap = await hydratePipeline.execute();
+  const byUid = /* @__PURE__ */ new Map();
+  for (const r of hydrateSnap.results) {
+    const row = r.data();
+    byUid.set(row.bUid, row);
+  }
+  const targets = targetUids.map((uid) => byUid.get(uid) ?? null);
+  return { edges, targets };
+}
+
+// src/internal/firestore-fulltext.ts
+var ENVELOPE_FIELDS = /* @__PURE__ */ new Set([
+  "aType",
+  "aUid",
+  "axbType",
+  "bType",
+  "bUid",
+  "createdAt",
+  "updatedAt",
+  "v"
+]);
+function normalizeFullTextFieldPath(field) {
+  if (ENVELOPE_FIELDS.has(field)) {
+    throw new FiregraphError(
+      `fullTextSearch(): field '${field}' is a built-in envelope field \u2014 text-indexed fields must live under \`data.*\`. Use a path like 'data.${field}' if you really meant a nested data field.`,
+      "INVALID_QUERY"
+    );
+  }
+  if (field === "data" || field.startsWith("data.")) return field;
+  return `data.${field}`;
+}
+var _Pipelines3 = null;
+async function getPipelines2() {
+  if (!_Pipelines3) {
+    const mod = await import("@google-cloud/firestore");
+    _Pipelines3 = mod.Pipelines;
+  }
+  return _Pipelines3;
+}
+async function runFirestoreFullTextSearch(db, collectionPath, params) {
+  if (typeof params.query !== "string" || params.query.length === 0) {
+    throw new FiregraphError(
+      "fullTextSearch(): query must be a non-empty string.",
+      "INVALID_QUERY"
+    );
+  }
+  if (!Number.isInteger(params.limit) || params.limit <= 0) {
+    throw new FiregraphError(
+      `fullTextSearch(): limit must be a positive integer (got ${params.limit}).`,
+      "INVALID_QUERY"
+    );
+  }
+  const normalizedFields = params.fields?.map((f) => normalizeFullTextFieldPath(f));
+  const P = await getPipelines2();
+  if (normalizedFields !== void 0 && normalizedFields.length > 0) {
+    throw new FiregraphError(
+      "fullTextSearch(): the `fields` option is not yet supported \u2014 per-field text predicates are not available in @google-cloud/firestore@8.5.0. Omit `fields` to search all indexed fields.",
+      "INVALID_QUERY"
+    );
+  }
+  const searchQuery = P.documentMatches(params.query);
+  let pipeline = db.pipeline().collection(collectionPath).search({
+    query: searchQuery,
+    sort: P.score().descending()
+  });
+  const whereExprs = [];
+  if (params.aType) whereExprs.push(P.equal("aType", params.aType));
+  if (params.axbType) whereExprs.push(P.equal("axbType", params.axbType));
+  if (params.bType) whereExprs.push(P.equal("bType", params.bType));
+  if (whereExprs.length === 1) {
+    pipeline = pipeline.where(whereExprs[0]);
+  } else if (whereExprs.length > 1) {
+    const [first, second, ...rest] = whereExprs;
+    pipeline = pipeline.where(P.and(first, second, ...rest));
+  }
+  pipeline = pipeline.limit(params.limit);
+  const snap = await pipeline.execute();
+  return snap.results.map((r) => r.data());
+}
+
+// src/internal/firestore-geo.ts
+var import_firestore3 = require("@google-cloud/firestore");
+var ENVELOPE_FIELDS2 = /* @__PURE__ */ new Set([
+  "aType",
+  "aUid",
+  "axbType",
+  "bType",
+  "bUid",
+  "createdAt",
+  "updatedAt",
+  "v"
+]);
+function normalizeGeoFieldPath(field) {
+  if (ENVELOPE_FIELDS2.has(field)) {
+    throw new FiregraphError(
+      `geoSearch(): geoField '${field}' is a built-in envelope field \u2014 geo-indexed fields must live under \`data.*\`. Use a path like 'data.${field}' if you really meant a nested data field.`,
+      "INVALID_QUERY"
+    );
+  }
+  if (field === "data" || field.startsWith("data.")) return field;
+  return `data.${field}`;
+}
+function assertValidGeoPoint(lat, lng) {
+  if (!Number.isFinite(lat) || lat < -90 || lat > 90) {
+    throw new FiregraphError(
+      `geoSearch(): point.lat must be in [-90, 90] (got ${lat}).`,
+      "INVALID_QUERY"
+    );
+  }
+  if (!Number.isFinite(lng) || lng < -180 || lng > 180) {
+    throw new FiregraphError(
+      `geoSearch(): point.lng must be in [-180, 180] (got ${lng}).`,
+      "INVALID_QUERY"
+    );
+  }
+}
+var _Pipelines4 = null;
+async function getPipelines3() {
+  if (!_Pipelines4) {
+    const mod = await import("@google-cloud/firestore");
+    _Pipelines4 = mod.Pipelines;
+  }
+  return _Pipelines4;
+}
+async function runFirestoreGeoSearch(db, collectionPath, params) {
+  if (!Number.isFinite(params.radiusMeters) || params.radiusMeters <= 0) {
+    throw new FiregraphError(
+      `geoSearch(): radiusMeters must be a positive finite number (got ${params.radiusMeters}).`,
+      "INVALID_QUERY"
+    );
+  }
+  if (!Number.isInteger(params.limit) || params.limit <= 0) {
+    throw new FiregraphError(
+      `geoSearch(): limit must be a positive integer (got ${params.limit}).`,
+      "INVALID_QUERY"
+    );
+  }
+  assertValidGeoPoint(params.point.lat, params.point.lng);
+  const geoFieldPath = normalizeGeoFieldPath(params.geoField);
+  const center = new import_firestore3.GeoPoint(params.point.lat, params.point.lng);
+  const P = await getPipelines3();
+  const distanceQuery = P.geoDistance(geoFieldPath, center).lessThanOrEqual(params.radiusMeters);
+  const orderByDistance = params.orderByDistance !== false;
+  const opts = {
+    query: distanceQuery
+  };
+  if (orderByDistance) {
+    opts.sort = P.geoDistance(geoFieldPath, center).ascending();
+  }
+  let pipeline = db.pipeline().collection(collectionPath).search(opts);
+  const whereExprs = [];
+  if (params.aType) whereExprs.push(P.equal("aType", params.aType));
+  if (params.axbType) whereExprs.push(P.equal("axbType", params.axbType));
+  if (params.bType) whereExprs.push(P.equal("bType", params.bType));
+  if (whereExprs.length === 1) {
+    pipeline = pipeline.where(whereExprs[0]);
+  } else if (whereExprs.length > 1) {
+    const [first, second, ...rest] = whereExprs;
+    pipeline = pipeline.where(P.and(first, second, ...rest));
+  }
+  pipeline = pipeline.limit(params.limit);
+  const snap = await pipeline.execute();
+  return snap.results.map((r) => r.data());
+}
+
+// src/internal/projection.ts
+var PROJECTION_BUILTIN_FIELDS = /* @__PURE__ */ new Set([
+  "aType",
+  "aUid",
+  "axbType",
+  "bType",
+  "bUid",
+  "createdAt",
+  "updatedAt",
+  "v"
+]);
+function normalizeFirestoreProjectionField(field) {
+  if (PROJECTION_BUILTIN_FIELDS.has(field)) return field;
+  if (field === "data" || field.startsWith("data.")) return field;
+  return `data.${field}`;
+}
+function readProjectionPath(obj, path) {
+  if (obj === void 0 || obj === null) return null;
+  const raw = !path.includes(".") ? obj[path] : (() => {
+    const parts = path.split(".");
+    let cur = obj;
+    for (const part of parts) {
+      if (cur === void 0 || cur === null) return void 0;
+      if (typeof cur !== "object") return void 0;
+      cur = cur[part];
+    }
+    return cur;
+  })();
+  return raw === void 0 ? null : raw;
+}
+
+// src/internal/firestore-projection.ts
+async function runFirestoreFindEdgesProjected(base, select, filters, options) {
+  if (select.length === 0) {
+    throw new FiregraphError(
+      "findEdgesProjected requires a non-empty select list \u2014 an empty projection has no representation distinct from `findEdges`.",
+      "INVALID_QUERY"
+    );
+  }
+  const seen = /* @__PURE__ */ new Set();
+  const fields = [];
+  for (const f of select) {
+    if (!seen.has(f)) {
+      seen.add(f);
+      fields.push({ original: f, canonical: normalizeFirestoreProjectionField(f) });
+    }
+  }
+  let q = base;
+  for (const f of filters) {
+    q = q.where(f.field, f.op, f.value);
+  }
+  if (options?.orderBy) {
+    q = q.orderBy(options.orderBy.field, options.orderBy.direction ?? "asc");
+  }
+  if (options?.limit !== void 0) {
+    q = q.limit(options.limit);
+  }
+  q = q.select(...fields.map((p) => p.canonical));
+  const snap = await q.get();
+  return snap.docs.map((doc) => {
+    const data = doc.data();
+    const out = {};
+    for (const { original, canonical } of fields) {
+      out[original] = readProjectionPath(data, canonical);
+    }
+    return out;
+  });
+}
+
+// src/internal/firestore-traverse-compiler.ts
+var MAX_PIPELINE_DEPTH = 5;
+function compileEngineTraversal(params, opts) {
+  const maxDepth = opts?.maxDepth ?? MAX_PIPELINE_DEPTH;
+  const maxReads = opts?.maxReads ?? params.maxReads;
+  if (!Array.isArray(params.hops) || params.hops.length === 0) {
+    return { eligible: false, reason: "engine traversal requires at least one hop" };
+  }
+  if (params.hops.length > maxDepth) {
+    return {
+      eligible: false,
+      reason: `engine traversal depth ${params.hops.length} exceeds MAX_PIPELINE_DEPTH (${maxDepth})`
+    };
+  }
+  if (!Array.isArray(params.sources)) {
+    return { eligible: false, reason: "engine traversal requires a sources array" };
+  }
+  const normalizedHops = [];
+  for (let i = 0; i < params.hops.length; i++) {
+    const hop = params.hops[i];
+    if (!hop.axbType || hop.axbType.length === 0) {
+      return {
+        eligible: false,
+        reason: `engine traversal hop ${i} is missing axbType`
+      };
+    }
+    if (typeof hop.limitPerSource !== "number" || hop.limitPerSource <= 0 || !Number.isFinite(hop.limitPerSource)) {
+      return {
+        eligible: false,
+        reason: `engine traversal hop ${i} (${hop.axbType}) requires a positive limitPerSource`
+      };
+    }
+    normalizedHops.push({
+      ...hop,
+      axbType: hop.axbType,
+      direction: hop.direction ?? "forward",
+      limitPerSource: hop.limitPerSource
+    });
+  }
+  let estimatedReads = Math.max(1, params.sources.length);
+  for (const hop of normalizedHops) {
+    estimatedReads *= hop.limitPerSource;
+    if (estimatedReads > Number.MAX_SAFE_INTEGER) {
+      estimatedReads = Number.MAX_SAFE_INTEGER;
+      break;
+    }
+  }
+  if (maxReads !== void 0 && estimatedReads > maxReads) {
+    return {
+      eligible: false,
+      reason: `engine traversal worst-case response size ${estimatedReads} exceeds maxReads budget ${maxReads}`
+    };
+  }
+  return {
+    eligible: true,
+    normalized: {
+      sources: params.sources,
+      hops: normalizedHops,
+      estimatedReads
+    }
+  };
+}
+
+// src/internal/firestore-traverse.ts
+function childArrayKey(depth) {
+  return `hop_${depth}_children`;
+}
+function joinVarName(depth) {
+  return `hop_${depth}_join`;
+}
+var _Pipelines5 = null;
+async function getPipelines4() {
+  if (!_Pipelines5) {
+    const mod = await import("@google-cloud/firestore");
+    _Pipelines5 = mod.Pipelines;
+  }
+  return _Pipelines5;
+}
+function buildHopPredicates(P, hop, sourcePredicate) {
+  const exprs = [P.equal("axbType", hop.axbType), sourcePredicate];
+  if (hop.aType !== void 0) exprs.push(P.equal("aType", hop.aType));
+  if (hop.bType !== void 0) exprs.push(P.equal("bType", hop.bType));
+  const [first, second, ...rest] = exprs;
+  return P.and(first, second, ...rest);
+}
+function applyHopOrderingAndLimit(P, pipeline, hop, totalLimit) {
+  let p = pipeline;
+  if (hop.orderBy) {
+    const f = P.field(hop.orderBy.field);
+    const ordering = hop.orderBy.direction === "desc" ? f.descending() : f.ascending();
+    p = p.sort(ordering);
+  }
+  p = p.limit(totalLimit);
+  return p;
+}
+function buildSubPipeline(P, db, collectionPath, hops, depth) {
+  const hop = hops[depth];
+  const parentDepth = depth - 1;
+  const sourceField = hop.direction === "forward" ? "aUid" : "bUid";
+  const sourcePredicate = P.equal(
+    sourceField,
+    P.variable(joinVarName(parentDepth))
+  );
+  const where = buildHopPredicates(P, hop, sourcePredicate);
+  let pipeline = db.pipeline().collection(collectionPath).where(where);
+  pipeline = applyHopOrderingAndLimit(P, pipeline, hop, hop.limitPerSource);
+  if (depth + 1 < hops.length) {
+    const targetField = hop.direction === "forward" ? "bUid" : "aUid";
+    pipeline = pipeline.define(P.field(targetField).as(joinVarName(depth)));
+    const child = buildSubPipeline(P, db, collectionPath, hops, depth + 1);
+    pipeline = pipeline.addFields(child.toArrayExpression().as(childArrayKey(depth)));
+  }
+  return pipeline;
+}
+function buildRootPipeline(P, db, collectionPath, spec) {
+  const hop0 = spec.hops[0];
+  const sourceField = hop0.direction === "forward" ? "aUid" : "bUid";
+  const sourcePredicate = P.equalAny(
+    sourceField,
+    spec.sources
+  );
+  const where = buildHopPredicates(P, hop0, sourcePredicate);
+  let pipeline = db.pipeline().collection(collectionPath).where(where);
+  pipeline = applyHopOrderingAndLimit(P, pipeline, hop0, spec.sources.length * hop0.limitPerSource);
+  if (spec.hops.length > 1) {
+    const targetField = hop0.direction === "forward" ? "bUid" : "aUid";
+    pipeline = pipeline.define(P.field(targetField).as(joinVarName(0)));
+    const child = buildSubPipeline(P, db, collectionPath, spec.hops, 1);
+    pipeline = pipeline.addFields(child.toArrayExpression().as(childArrayKey(0)));
+  }
+  return pipeline;
+}
+function stripScaffolding(row, depth) {
+  const stripped = { ...row };
+  delete stripped[childArrayKey(depth)];
+  delete stripped[joinVarName(depth)];
+  return stripped;
+}
+function decodeTree(rootRows, hops) {
+  const out = [];
+  let frontier = rootRows;
+  for (let depth = 0; depth < hops.length; depth++) {
+    const hop = hops[depth];
+    const targetField = hop.direction === "forward" ? "bUid" : "aUid";
+    const seen = /* @__PURE__ */ new Set();
+    const edges = [];
+    const nextFrontier = [];
+    for (const row of frontier) {
+      const childKey = childArrayKey(depth);
+      const children = row[childKey];
+      if (Array.isArray(children)) {
+        for (const child of children) {
+          if (child && typeof child === "object") {
+            nextFrontier.push(child);
+          }
+        }
+      }
+      const stripped = stripScaffolding(row, depth);
+      if (hop.axbType === NODE_RELATION && stripped.aUid === stripped.bUid) continue;
+      const dedupKey = stripped[targetField];
+      if (typeof dedupKey !== "string" || seen.has(dedupKey)) continue;
+      seen.add(dedupKey);
+      edges.push(stripped);
+    }
+    out.push({ edges, sourceCount: depth === 0 ? -1 : out[depth - 1].edges.length });
+    frontier = nextFrontier;
+  }
+  return {
+    hops: out,
+    totalReads: 1
+  };
+}
+async function runFirestoreEngineTraversal(db, collectionPath, params) {
+  if (process.env.FIRESTORE_EMULATOR_HOST) {
+    throw new FiregraphError(
+      "engine traversal requires Pipelines \u2014 not supported on the Firestore emulator",
+      "UNSUPPORTED_OPERATION"
+    );
+  }
+  const compiled = compileEngineTraversal(params);
+  if (!compiled.eligible) {
+    throw new FiregraphError(
+      `engine traversal not eligible: ${compiled.reason}`,
+      "UNSUPPORTED_OPERATION"
+    );
+  }
+  const spec = compiled.normalized;
+  if (spec.sources.length === 0) {
+    return {
+      hops: spec.hops.map(() => ({ edges: [], sourceCount: 0 })),
+      totalReads: 0
+    };
+  }
+  const P = await getPipelines4();
+  const pipeline = buildRootPipeline(P, db, collectionPath, spec);
+  const snap = await pipeline.execute();
+  const rows = snap.results.map((r) => r.data());
+  const result = decodeTree(rows, spec.hops);
+  if (result.hops.length > 0) {
+    result.hops[0] = { ...result.hops[0], sourceCount: spec.sources.length };
+  }
+  return result;
+}
+
+// src/internal/firestore-vector.ts
+var ENVELOPE_FIELDS3 = /* @__PURE__ */ new Set([
+  "aType",
+  "aUid",
+  "axbType",
+  "bType",
+  "bUid",
+  "createdAt",
+  "updatedAt",
+  "v"
+]);
+function normalizeVectorFieldPath(label, field) {
+  if (ENVELOPE_FIELDS3.has(field)) {
+    throw new FiregraphError(
+      `findNearest(): ${label} '${field}' is a built-in envelope field \u2014 vectors must live under \`data.*\`. Use a path like 'data.${field}' if you really meant a nested data field.`,
+      "INVALID_QUERY"
+    );
+  }
+  if (field === "data" || field.startsWith("data.")) return field;
+  return `data.${field}`;
+}
+function buildVectorFilters(params) {
+  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);
+  return filters;
+}
+function toNumberArray(qv) {
+  if (Array.isArray(qv)) return qv;
+  if (typeof qv.toArray === "function") {
+    return qv.toArray();
+  }
+  throw new FiregraphError(
+    "findNearest(): queryVector must be a number[] or a Firestore VectorValue.",
+    "INVALID_QUERY"
+  );
+}
+async function runFirestoreFindNearest(base, params) {
+  const vec = toNumberArray(params.queryVector);
+  if (vec.length === 0) {
+    throw new FiregraphError(
+      "findNearest(): queryVector is empty \u2014 at least one dimension is required.",
+      "INVALID_QUERY"
+    );
+  }
+  if (!Number.isInteger(params.limit) || params.limit <= 0 || params.limit > 1e3) {
+    throw new FiregraphError(
+      `findNearest(): limit must be a positive integer \u2264 1000 (got ${params.limit}).`,
+      "INVALID_QUERY"
+    );
+  }
+  const vectorField = normalizeVectorFieldPath("vectorField", params.vectorField);
+  const distanceResultField = params.distanceResultField !== void 0 ? normalizeVectorFieldPath("distanceResultField", params.distanceResultField) : void 0;
+  const filtered = applyFiltersToQuery(base, buildVectorFilters(params));
+  const opts = {
+    vectorField,
+    queryVector: vec,
+    limit: params.limit,
+    distanceMeasure: params.distanceMeasure
+  };
+  if (params.distanceThreshold !== void 0) opts.distanceThreshold = params.distanceThreshold;
+  if (distanceResultField !== void 0) opts.distanceResultField = distanceResultField;
+  const snap = await filtered.findNearest(opts).get();
+  return snap.docs.map((doc) => doc.data());
+}
+
+// src/firestore-enterprise/backend.ts
+init_serialization();
+
+// src/firestore-enterprise/pipeline-adapter.ts
+var _Pipelines6 = null;
+async function getPipelines5() {
+  if (!_Pipelines6) {
+    const mod = await import("@google-cloud/firestore");
+    _Pipelines6 = mod.Pipelines;
+  }
+  return _Pipelines6;
+}
+function buildFilterExpression2(P, filter) {
+  const { field: fieldName, op, value } = filter;
+  switch (op) {
+    case "==":
+      return P.equal(fieldName, value);
+    case "!=":
+      return P.notEqual(fieldName, value);
+    case "<":
+      return P.lessThan(fieldName, value);
+    case "<=":
+      return P.lessThanOrEqual(fieldName, value);
+    case ">":
+      return P.greaterThan(fieldName, value);
+    case ">=":
+      return P.greaterThanOrEqual(fieldName, value);
+    case "in":
+      return P.equalAny(fieldName, value);
+    case "not-in":
+      return P.notEqualAny(fieldName, value);
+    case "array-contains":
+      return P.arrayContains(fieldName, value);
+    case "array-contains-any":
+      return P.arrayContainsAny(fieldName, value);
+    default:
+      throw new Error(`Unsupported filter op for pipeline mode: ${op}`);
+  }
+}
+function createPipelineQueryAdapter(db, collectionPath) {
+  return {
+    async query(filters, options) {
+      const P = await getPipelines5();
+      let pipeline = db.pipeline().collection(collectionPath);
+      if (filters.length === 1) {
+        pipeline = pipeline.where(buildFilterExpression2(P, filters[0]));
+      } else if (filters.length > 1) {
+        const [first, second, ...rest] = filters.map((f) => buildFilterExpression2(P, f));
+        pipeline = pipeline.where(P.and(first, second, ...rest));
+      }
+      if (options?.orderBy) {
+        const f = P.field(options.orderBy.field);
+        const ordering = options.orderBy.direction === "desc" ? f.descending() : f.ascending();
+        pipeline = pipeline.sort(ordering);
+      }
+      if (options?.limit !== void 0) {
+        pipeline = pipeline.limit(options.limit);
+      }
+      const snap = await pipeline.execute();
+      return snap.results.map((r) => r.data());
+    }
+  };
+}
+
+// src/firestore-enterprise/backend.ts
+var ENTERPRISE_BASE_CAPS = /* @__PURE__ */ new Set([
+  "core.read",
+  "core.write",
+  "core.transactions",
+  "core.batch",
+  "core.subgraph",
+  "query.aggregate",
+  "query.select",
+  "query.join",
+  "traversal.serverSide",
+  "search.vector",
+  "search.fullText",
+  "search.geo",
+  "raw.firestore"
+]);
+var _emulatorFallbackWarned = false;
+var _classicInProductionWarned = false;
+var _previewDmlWarned = false;
+function dottedDataPath(op) {
+  assertSafePath(op.path);
+  return `data.${op.path.join(".")}`;
+}
+function buildFirestoreUpdate(update, db) {
+  assertUpdatePayloadExclusive(update);
+  const out = {
+    updatedAt: import_firestore4.FieldValue.serverTimestamp()
+  };
+  if (update.replaceData) {
+    out.data = deserializeFirestoreTypes(update.replaceData, db);
+  } else if (update.dataOps) {
+    for (const op of update.dataOps) {
+      const key = dottedDataPath(op);
+      out[key] = op.delete ? import_firestore4.FieldValue.delete() : op.value;
+    }
+  }
+  if (update.v !== void 0) {
+    out.v = update.v;
+  }
+  return out;
+}
+function stampWritableRecord(record) {
+  const now = import_firestore4.FieldValue.serverTimestamp();
+  const out = {
+    aType: record.aType,
+    aUid: record.aUid,
+    axbType: record.axbType,
+    bType: record.bType,
+    bUid: record.bUid,
+    data: record.data,
+    createdAt: now,
+    updatedAt: now
+  };
+  if (record.v !== void 0) out.v = record.v;
+  return out;
+}
+var FirestoreEnterpriseTransactionBackend = class {
+  constructor(adapter, db) {
+    this.adapter = adapter;
+    this.db = db;
+  }
+  getDoc(docId) {
+    return this.adapter.getDoc(docId);
+  }
+  query(filters, options) {
+    return this.adapter.query(filters, options);
+  }
+  async setDoc(docId, record, mode) {
+    this.adapter.setDoc(
+      docId,
+      stampWritableRecord(record),
+      mode === "merge" ? { merge: true } : void 0
+    );
+  }
+  async updateDoc(docId, update) {
+    this.adapter.updateDoc(docId, buildFirestoreUpdate(update, this.db));
+  }
+  async deleteDoc(docId) {
+    this.adapter.deleteDoc(docId);
+  }
+};
+var FirestoreEnterpriseBatchBackend = class {
+  constructor(adapter, db) {
+    this.adapter = adapter;
+    this.db = db;
+  }
+  setDoc(docId, record, mode) {
+    this.adapter.setDoc(
+      docId,
+      stampWritableRecord(record),
+      mode === "merge" ? { merge: true } : void 0
+    );
+  }
+  updateDoc(docId, update) {
+    this.adapter.updateDoc(docId, buildFirestoreUpdate(update, this.db));
+  }
+  deleteDoc(docId) {
+    this.adapter.deleteDoc(docId);
+  }
+  commit() {
+    return this.adapter.commit();
+  }
+};
+var FirestoreEnterpriseBackendImpl = class _FirestoreEnterpriseBackendImpl {
+  constructor(db, collectionPath, queryMode, scopePath, previewDml) {
+    this.db = db;
+    this.queryMode = queryMode;
+    this.previewDml = previewDml;
+    this.collectionPath = collectionPath;
+    this.scopePath = scopePath;
+    this.adapter = createFirestoreAdapter(db, collectionPath);
+    if (queryMode === "pipeline") {
+      this.pipelineAdapter = createPipelineQueryAdapter(db, collectionPath);
+    }
+    const caps = previewDml ? /* @__PURE__ */ new Set([...ENTERPRISE_BASE_CAPS, "query.dml"]) : ENTERPRISE_BASE_CAPS;
+    this.capabilities = createCapabilities(caps);
+  }
+  capabilities;
+  collectionPath;
+  scopePath;
+  adapter;
+  pipelineAdapter;
+  // --- Reads ---
+  getDoc(docId) {
+    return this.adapter.getDoc(docId);
+  }
+  query(filters, options) {
+    if (this.pipelineAdapter) {
+      return this.pipelineAdapter.query(filters, options);
+    }
+    return this.adapter.query(filters, options);
+  }
+  // --- Writes ---
+  setDoc(docId, record, mode) {
+    return this.adapter.setDoc(
+      docId,
+      stampWritableRecord(record),
+      mode === "merge" ? { merge: true } : void 0
+    );
+  }
+  updateDoc(docId, update) {
+    return this.adapter.updateDoc(docId, buildFirestoreUpdate(update, this.db));
+  }
+  deleteDoc(docId) {
+    return this.adapter.deleteDoc(docId);
+  }
+  // --- Transactions / Batches ---
+  runTransaction(fn) {
+    return this.db.runTransaction(async (firestoreTx) => {
+      const txAdapter = createTransactionAdapter(this.db, this.collectionPath, firestoreTx);
+      return fn(new FirestoreEnterpriseTransactionBackend(txAdapter, this.db));
+    });
+  }
+  createBatch() {
+    const batchAdapter = createBatchAdapter(this.db, this.collectionPath);
+    return new FirestoreEnterpriseBatchBackend(batchAdapter, this.db);
+  }
+  // --- Subgraphs ---
+  subgraph(parentNodeUid, name) {
+    const subPath = `${this.collectionPath}/${parentNodeUid}/${name}`;
+    const newScope = this.scopePath ? `${this.scopePath}/${name}` : name;
+    return new _FirestoreEnterpriseBackendImpl(
+      this.db,
+      subPath,
+      this.queryMode,
+      newScope,
+      this.previewDml
+    );
+  }
+  // --- Cascade & bulk ---
+  removeNodeCascade(uid, reader, options) {
+    return removeNodeCascade(this.db, this.collectionPath, reader, uid, options);
+  }
+  bulkRemoveEdges(params, reader, options) {
+    return bulkRemoveEdges(this.db, this.collectionPath, reader, params, options);
+  }
+  // --- Cross-collection ---
+  async findEdgesGlobal(params, collectionName) {
+    const name = collectionName ?? this.collectionPath.split("/").pop();
+    const plan = buildEdgeQueryPlan(params);
+    if (plan.strategy === "get") {
+      throw new FiregraphError(
+        "findEdgesGlobal() requires a query, not a direct document lookup. Omit one of aUid/axbType/bUid to force a query strategy.",
+        "INVALID_QUERY"
+      );
+    }
+    const collectionGroupRef = this.db.collectionGroup(name);
+    let q = collectionGroupRef;
+    for (const f of plan.filters) {
+      q = q.where(f.field, f.op, f.value);
+    }
+    if (plan.options?.orderBy) {
+      q = q.orderBy(plan.options.orderBy.field, plan.options.orderBy.direction ?? "asc");
+    }
+    if (plan.options?.limit !== void 0) {
+      q = q.limit(plan.options.limit);
+    }
+    const snap = await q.get();
+    return snap.docs.map((doc) => doc.data());
+  }
+  // --- Aggregate ---
+  /**
+   * Aggregate via the classic `Query.aggregate()` API. Supports count/sum/avg
+   * — min/max throws `UNSUPPORTED_AGGREGATE`. The Pipelines `aggregate()`
+   * stage could in principle add min/max on Enterprise, but that is deferred
+   * to a future phase; both editions currently route through the same
+   * classic-API helper so capability semantics stay symmetric.
+   */
+  aggregate(spec, filters) {
+    return runFirestoreAggregate(this.db.collection(this.collectionPath), spec, filters, {
+      edition: "enterprise"
+    });
+  }
+  // --- Server-side projection (capability: query.select) ---
+  /**
+   * Run a projecting query via the shared classic-API helper. Enterprise and
+   * Standard delegate to the same implementation so the projection contract
+   * stays consistent.
+   *
+   * Why classic and not the pipeline `select()` stage: the byte-savings
+   * deliverable (the only reason `findEdgesProjected` exists) is achieved
+   * by either path; the classic API works on both editions today and
+   * sidesteps the pipeline-vs-emulator forking the rest of this backend has
+   * to manage. When pipeline `select()` becomes preferable for some other
+   * reason — e.g. composing with a future pipeline-only stage — swap the
+   * implementation behind `runFirestoreFindEdgesProjected`; callers and
+   * the capability declaration stay put.
+   */
+  findEdgesProjected(select, filters, options) {
+    return runFirestoreFindEdgesProjected(
+      this.db.collection(this.collectionPath),
+      select,
+      filters,
+      options
+    );
+  }
+  // --- Native vector / nearest-neighbour search (capability: search.vector) ---
+  /**
+   * Run a vector / nearest-neighbour query via the shared classic-API
+   * helper. Enterprise and Standard delegate to one implementation so the
+   * field-path normalisation, validation surface, and result shape stay
+   * consistent across editions.
+   *
+   * Why classic and not the pipeline `findNearest` stage: the deliverable
+   * (top-K by similarity) is achieved by either path; the classic API
+   * works identically on both editions today and sidesteps the
+   * pipeline-vs-emulator forking the rest of this backend has to manage.
+   * When pipeline `findNearest` becomes preferable for composing with
+   * other pipeline stages, swap the implementation behind
+   * `runFirestoreFindNearest`; callers and the capability declaration
+   * stay put.
+   *
+   * Index requirements are identical to Standard — single-field vector
+   * index on the indexed `vectorField`, plus a composite index whenever
+   * additional `where` filters narrow the candidate set.
+   */
+  findNearest(params) {
+    return runFirestoreFindNearest(this.db.collection(this.collectionPath), params);
+  }
+  // --- Native full-text search (capability: search.fullText) ---
+  /**
+   * Run a full-text search via Firestore Pipelines `search(...)` stage.
+   * Translates `documentMatches(query)` against the indexed search
+   * fields, sorts by relevance score (`score().descending()`), and
+   * applies identifying filters as a follow-up `where(...)` stage
+   * because `search` must be the first stage of a pipeline.
+   *
+   * Enterprise-only: full-text search is an Enterprise product feature.
+   * Standard does not declare `search.fullText` regardless of SDK
+   * surface, and the SQLite-shaped backends have no native FTS index.
+   *
+   * Index requirements: an FTS index on the indexed search fields
+   * (configured in Firestore's index config). Without the index the
+   * underlying `search` stage returns no rows; the firegraph layer
+   * cannot detect that case ahead of time.
+   */
+  fullTextSearch(params) {
+    return runFirestoreFullTextSearch(this.db, this.collectionPath, params);
+  }
+  // --- Native geospatial distance search (capability: search.geo) ---
+  /**
+   * Run a geospatial distance query via Firestore Pipelines
+   * `search(...)` stage. The same `geoDistance(geoField, point)`
+   * expression feeds the radius cap (`<= radiusMeters`) and the
+   * nearest-first sort (when `orderByDistance` is true / unset).
+   * Identifying filters apply as a follow-up `where(...)` stage.
+   *
+   * Enterprise-only: same Enterprise-product-feature gating as FTS.
+   *
+   * Index requirements: a geospatial index on the indexed `geoField`.
+   * Same caveat as FTS — unindexed geo searches return no rows
+   * server-side and the firegraph layer cannot pre-detect that.
+   */
+  geoSearch(params) {
+    return runFirestoreGeoSearch(this.db, this.collectionPath, params);
+  }
+  // --- Server-side multi-source fan-out (capability: query.join) ---
+  /**
+   * Fan out from `params.sources` over a single edge type in one server-
+   * side round trip when running in pipeline mode, or via a chunked
+   * classic-API fan-out when running in classic mode.
+   *
+   * Pipeline mode (default outside the emulator): one call to
+   * `db.pipeline().collection(path).where(equalAny(sourceField, sources))
+   * .execute()`. `equalAny` has no documented cap, so a 1k-source fan-
+   * out is one round trip.
+   *
+   * Classic mode (emulator, or `defaultQueryMode: 'classic'`): chunks
+   * `params.sources` into 30-element groups (the classic `'in'`
+   * operator's documented cap), dispatches one query per chunk in
+   * parallel, concats the results, and applies a cross-chunk re-sort +
+   * total-limit slice. Same observable contract, `ceil(N/30)` round
+   * trips. The chunked path is still a win over the per-source
+   * `findEdges` loop in `traverse.ts` — 100 sources go from 100 round
+   * trips to 4.
+   */
+  expand(params) {
+    if (this.queryMode === "pipeline") {
+      return runFirestorePipelineExpand(this.db, this.collectionPath, params);
+    }
+    return runFirestoreClassicExpand(this.adapter, params);
+  }
+  // --- Server-side DML (capability: query.dml, gated by previewDml) ---
+  /**
+   * Single-statement bulk DELETE via Pipeline `delete()` stage. Wired only
+   * when the backend was created with `previewDml: true`; otherwise the
+   * cap isn't declared and `client.bulkDelete()` throws
+   * `UNSUPPORTED_OPERATION` (or `bulk.ts` cascade falls back to
+   * `bulkRemoveEdges`).
+   *
+   * Empty filter lists are rejected at the helper boundary —
+   * see `runFirestorePipelineDelete`'s `assertNonEmptyFilters`.
+   *
+   * Subgraph isolation comes from `this.collectionPath`: the pipeline's
+   * `collection(path)` source IS the subgraph, so there's no separate
+   * `scope` predicate to enforce (unlike SQLite's leading-`scope`-`?`
+   * filter).
+   */
+  bulkDelete(filters, options) {
+    return runFirestorePipelineDelete(this.db, this.collectionPath, filters, options);
+  }
+  /**
+   * Single-statement bulk UPDATE via Pipeline
+   * `update(transformedFields)` stage. Same gating and scoping as
+   * `bulkDelete` above. The patch is flattened into one
+   * `AliasedExpression` per terminal leaf via the shared `flattenPatch`
+   * pipeline; `deleteField()` sentinels are rejected at the helper
+   * boundary (the typed `update(AliasedExpression[])` surface in 8.5.0
+   * has no field-deletion transform — see `runFirestorePipelineUpdate`).
+   */
+  bulkUpdate(filters, patch, options) {
+    return runFirestorePipelineUpdate(this.db, this.collectionPath, filters, patch, options);
+  }
+  // --- Engine-level multi-hop traversal (capability: traversal.serverSide) ---
+  /**
+   * Compile a multi-hop traversal spec into one nested Pipeline and
+   * dispatch a single round trip via `define` + `addFields(child
+   * .toArrayExpression().as(...))`. The compiler in
+   * `firestore-traverse-compiler.ts` validates spec eligibility (depth
+   * ≤ `MAX_PIPELINE_DEPTH`, every hop has `limitPerSource`, response-
+   * size product ≤ `maxReads`) and the executor in
+   * `firestore-traverse.ts` builds + decodes the tree.
+   *
+   * Unlike `bulkDelete` / `bulkUpdate`, this method is GA-typed in 8.5.0
+   * (no `@beta` annotation on `define`, `addFields`, `toArrayExpression`,
+   * or `variable`), so it does NOT need a `previewDml`-style opt-in.
+   *
+   * `defaultQueryMode` is irrelevant here — engine traversal always
+   * dispatches through Pipelines because the join-key binding (`define`
+   * + `variable`) has no classic Query API equivalent. Specs that
+   * arrive on a classic-mode backend still execute via Pipelines; the
+   * `queryMode` toggle only affects the read query path
+   * (`query()` / `expand()`).
+   */
+  runEngineTraversal(params) {
+    return runFirestoreEngineTraversal(this.db, this.collectionPath, params);
+  }
+};
+function createFirestoreEnterpriseBackend(db, collectionPath, options = {}) {
+  const requestedMode = options.defaultQueryMode ?? "pipeline";
+  const isEmulator = !!process.env.FIRESTORE_EMULATOR_HOST;
+  const effectiveMode = isEmulator && requestedMode === "pipeline" ? "classic" : requestedMode;
+  if (isEmulator && requestedMode === "pipeline" && effectiveMode === "classic" && !_emulatorFallbackWarned) {
+    _emulatorFallbackWarned = true;
+    console.warn(
+      "[firegraph] Firestore Enterprise pipeline mode is unavailable in the emulator; falling back to classic Query API for this run. Set `defaultQueryMode: 'classic'` to silence this warning."
+    );
+  }
+  if (!isEmulator && requestedMode === "classic" && !_classicInProductionWarned) {
+    _classicInProductionWarned = true;
+    console.warn(
+      "[firegraph] Firestore Enterprise backend created with `defaultQueryMode: 'classic'`. Classic-mode `query()` against Enterprise causes full collection scans for `data.*` filters (high billing). For production reads on Standard Firestore, import from `'firegraph/firestore-standard'` instead."
+    );
+  }
+  const previewDml = options.previewDml ?? false;
+  if (previewDml && !_previewDmlWarned) {
+    _previewDmlWarned = true;
+    console.warn(
+      "[firegraph] Firestore Enterprise backend created with `previewDml: true`. bulkDelete()/bulkUpdate() will dispatch through Pipeline.delete() / Pipeline.update(transformedFields), both `@beta` in @google-cloud/firestore@8.5.0. The typed surface may shift before GA \u2014 pin your firestore SDK or be ready to set `previewDml: false` and route through the read-then-write fallback if needed."
+    );
+  }
+  const scopePath = options.scopePath ?? "";
+  return new FirestoreEnterpriseBackendImpl(
+    db,
+    collectionPath,
+    effectiveMode,
+    scopePath,
+    previewDml
+  );
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  META_EDGE_TYPE,
+  META_NODE_TYPE,
+  createFirestoreEnterpriseBackend,
+  createGraphClient,
+  createMergedRegistry,
+  createRegistry,
+  generateId
+});
+//# sourceMappingURL=index.cjs.map