@typicalday/firegraph 0.7.1 → 0.8.0

package/dist/chunk-YUXOALMR.js

@@ -0,0 +1,1653 @@
+// 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
+import { createHash } from "crypto";
+function computeNodeDocId(uid) {
+  return uid;
+}
+function computeEdgeDocId(aUid, axbType, bUid) {
+  const composite = `${aUid}${SHARD_SEPARATOR}${axbType}${SHARD_SEPARATOR}${bUid}`;
+  const hash = createHash("sha256").update(composite).digest("hex");
+  const shard = hash[0];
+  return `${shard}${SHARD_SEPARATOR}${aUid}${SHARD_SEPARATOR}${axbType}${SHARD_SEPARATOR}${bUid}`;
+}
+
+// src/errors.ts
+var FiregraphError = class extends Error {
+  constructor(message, code) {
+    super(message);
+    this.code = code;
+    this.name = "FiregraphError";
+  }
+};
+var NodeNotFoundError = class extends FiregraphError {
+  constructor(uid) {
+    super(`Node not found: ${uid}`, "NODE_NOT_FOUND");
+    this.name = "NodeNotFoundError";
+  }
+};
+var EdgeNotFoundError = class extends FiregraphError {
+  constructor(aUid, axbType, bUid) {
+    super(`Edge not found: ${aUid} -[${axbType}]-> ${bUid}`, "EDGE_NOT_FOUND");
+    this.name = "EdgeNotFoundError";
+  }
+};
+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 TraversalError = class extends FiregraphError {
+  constructor(message) {
+    super(message, "TRAVERSAL_ERROR");
+    this.name = "TraversalError";
+  }
+};
+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
+import Ajv from "ajv";
+import addFormats from "ajv-formats";
+var ajv = new Ajv({ allErrors: true, strict: false });
+addFormats(ajv);
+function compileSchema(schema, label) {
+  const validate = ajv.compile(schema);
+  return (data) => {
+    if (!validate(data)) {
+      const errors = validate.errors ?? [];
+      const messages = errors.map((err) => `${err.instancePath || "/"}${err.message ? ": " + err.message : ""}`).join("; ");
+      throw new ValidationError(
+        `Data validation failed${label ? " for " + label : ""}: ${messages}`,
+        errors
+      );
+    }
+  };
+}
+function jsonSchemaToFieldMeta(schema) {
+  if (!schema || schema.type !== "object" || !schema.properties) return [];
+  const requiredSet = new Set(
+    Array.isArray(schema.required) ? schema.required : []
+  );
+  return Object.entries(schema.properties).map(
+    ([name, prop]) => propertyToFieldMeta(name, prop, requiredSet.has(name))
+  );
+}
+function propertyToFieldMeta(name, prop, required) {
+  if (!prop) return { name, type: "unknown", required };
+  if (Array.isArray(prop.enum)) {
+    return {
+      name,
+      type: "enum",
+      required,
+      enumValues: prop.enum,
+      description: prop.description
+    };
+  }
+  if (Array.isArray(prop.oneOf) || Array.isArray(prop.anyOf)) {
+    const variants = prop.oneOf ?? prop.anyOf;
+    const nonNull = variants.filter((v) => v.type !== "null");
+    if (nonNull.length === 1) {
+      return propertyToFieldMeta(name, nonNull[0], false);
+    }
+    return { name, type: "unknown", required, description: prop.description };
+  }
+  const type = prop.type;
+  if (type === "string") {
+    return {
+      name,
+      type: "string",
+      required,
+      minLength: prop.minLength,
+      maxLength: prop.maxLength,
+      pattern: prop.pattern,
+      description: prop.description
+    };
+  }
+  if (type === "number" || type === "integer") {
+    return {
+      name,
+      type: "number",
+      required,
+      min: prop.minimum,
+      max: prop.maximum,
+      isInt: type === "integer" ? true : void 0,
+      description: prop.description
+    };
+  }
+  if (type === "boolean") {
+    return { name, type: "boolean", required, description: prop.description };
+  }
+  if (type === "array") {
+    const itemMeta = prop.items ? propertyToFieldMeta("item", prop.items, true) : void 0;
+    return {
+      name,
+      type: "array",
+      required,
+      itemMeta,
+      description: prop.description
+    };
+  }
+  if (type === "object") {
+    return {
+      name,
+      type: "object",
+      required,
+      fields: jsonSchemaToFieldMeta(prop),
+      description: prop.description
+    };
+  }
+  return { name, type: "unknown", required, description: prop.description };
+}
+
+// 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));
+  }
+  return {
+    lookup(aType, axbType, bType) {
+      return map.get(tripleKey(aType, axbType, bType))?.entry;
+    },
+    lookupByAxbType(axbType) {
+      return axbIndex.get(axbType) ?? [];
+    },
+    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);
+    },
+    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
+    });
+  }
+  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
+        });
+      }
+    }
+  }
+  return entries;
+}
+
+// src/sandbox.ts
+import { createHash as createHash2 } from "crypto";
+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 createHash2("sha256").update(source).digest("hex");
+}
+var _serializationModule = null;
+async function loadSerialization() {
+  if (_serializationModule) return _serializationModule;
+  _serializationModule = await import("./serialization-C6JNNOCS.js");
+  return _serializationModule;
+}
+function defaultExecutor(source) {
+  return (async (data) => {
+    const { serializeFirestoreTypes, deserializeFirestoreTypes } = await loadSerialization();
+    const jsonData = JSON.stringify(serializeFirestoreTypes(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 deserializeFirestoreTypes(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)
+  }));
+}
+async function destroySandboxWorker() {
+  if (!_worker) return;
+  const w = _worker;
+  _worker = null;
+  for (const [, p] of _pending) {
+    p.reject(new MigrationError("Sandbox worker terminated"));
+  }
+  _pending.clear();
+  await w.terminate();
+}
+
+// src/dynamic-registry.ts
+import { createHash as createHash3 } from "crypto";
+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"
+  }
+];
+function createBootstrapRegistry() {
+  return createRegistry([...BOOTSTRAP_ENTRIES]);
+}
+function generateDeterministicUid(metaType, name) {
+  const hash = createHash3("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/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) {
+    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);
+  }
+  async putEdge(aType, aUid, axbType, bType, bUid, data) {
+    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);
+  }
+  async updateNode(uid, data) {
+    const docId = computeNodeDocId(uid);
+    this.backend.updateDoc(docId, { dataFields: 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/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) {
+    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);
+  }
+  async putEdge(aType, aUid, axbType, bType, bUid, data) {
+    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);
+  }
+  async updateNode(uid, data) {
+    const docId = computeNodeDocId(uid);
+    await this.backend.updateDoc(docId, { dataFields: 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;
+  // 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;
+  }
+  // ---------------------------------------------------------------------------
+  // 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) {
+    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);
+  }
+  async putEdge(aType, aUid, axbType, bType, bUid, data) {
+    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);
+  }
+  async updateNode(uid, data) {
+    const docId = computeNodeDocId(uid);
+    await this.backend.updateDoc(docId, { dataFields: 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);
+  }
+  // ---------------------------------------------------------------------------
+  // Bulk operations
+  // ---------------------------------------------------------------------------
+  async removeNodeCascade(uid, options) {
+    return this.backend.removeNodeCascade(uid, this, options);
+  }
+  async bulkRemoveEdges(params, options) {
+    return this.backend.bulkRemoveEdges(params, this, options);
+  }
+  // ---------------------------------------------------------------------------
+  // 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 createGraphClientFromBackend(backend, options, metaBackend) {
+  return new GraphClientImpl(backend, options, metaBackend);
+}
+
+export {
+  NODE_RELATION,
+  DEFAULT_QUERY_LIMIT,
+  computeNodeDocId,
+  computeEdgeDocId,
+  FiregraphError,
+  NodeNotFoundError,
+  EdgeNotFoundError,
+  ValidationError,
+  RegistryViolationError,
+  InvalidQueryError,
+  TraversalError,
+  DynamicRegistryError,
+  QuerySafetyError,
+  RegistryScopeError,
+  MigrationError,
+  compileSchema,
+  jsonSchemaToFieldMeta,
+  applyMigrationChain,
+  validateMigrationChain,
+  migrateRecord,
+  migrateRecords,
+  matchScope,
+  matchScopeAny,
+  createRegistry,
+  createMergedRegistry,
+  defaultExecutor,
+  precompileSource,
+  compileMigrationFn,
+  compileMigrations,
+  destroySandboxWorker,
+  META_NODE_TYPE,
+  META_EDGE_TYPE,
+  NODE_TYPE_SCHEMA,
+  EDGE_TYPE_SCHEMA,
+  BOOTSTRAP_ENTRIES,
+  createBootstrapRegistry,
+  generateDeterministicUid,
+  createRegistryFromGraph,
+  buildEdgeQueryPlan,
+  buildNodeQueryPlan,
+  analyzeQuerySafety,
+  GraphClientImpl,
+  createGraphClientFromBackend
+};
+//# sourceMappingURL=chunk-YUXOALMR.js.map