@typicalday/firegraph 0.9.0 → 0.11.0

package/dist/cloudflare/index.js

@@ -0,0 +1,934 @@
+import {
+  DEFAULT_CORE_INDEXES,
+  NODE_RELATION,
+  buildEdgeQueryPlan,
+  computeEdgeDocId,
+  computeNodeDocId,
+  createGraphClientFromBackend
+} from "../chunk-6SB34IPQ.js";
+import {
+  FiregraphError
+} from "../chunk-R7CRGYY4.js";
+
+// src/timestamp.ts
+var GraphTimestampImpl = class _GraphTimestampImpl {
+  constructor(seconds, nanoseconds) {
+    this.seconds = seconds;
+    this.nanoseconds = nanoseconds;
+  }
+  toDate() {
+    return new Date(this.toMillis());
+  }
+  toMillis() {
+    return this.seconds * 1e3 + Math.floor(this.nanoseconds / 1e6);
+  }
+  toJSON() {
+    return { seconds: this.seconds, nanoseconds: this.nanoseconds };
+  }
+  static fromMillis(ms) {
+    const seconds = Math.floor(ms / 1e3);
+    const nanoseconds = (ms - seconds * 1e3) * 1e6;
+    return new _GraphTimestampImpl(seconds, nanoseconds);
+  }
+  static now() {
+    return _GraphTimestampImpl.fromMillis(Date.now());
+  }
+};
+
+// src/internal/sqlite-index-ddl.ts
+var IDENT_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+var JSON_PATH_KEY_RE = /^[A-Za-z_][A-Za-z0-9_-]*$/;
+function quoteIdent(name) {
+  if (!IDENT_RE.test(name)) {
+    throw new FiregraphError(
+      `Invalid SQL identifier in index DDL: ${name}. Must match /^[A-Za-z_][A-Za-z0-9_]*$/.`,
+      "INVALID_INDEX"
+    );
+  }
+  return `"${name}"`;
+}
+function fnv1a32(str) {
+  let h = 2166136261;
+  for (let i = 0; i < str.length; i++) {
+    h ^= str.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return (h >>> 0).toString(16).padStart(8, "0");
+}
+function normalizeFields(fields) {
+  return fields.map((f) => {
+    if (typeof f === "string") return { path: f, desc: false };
+    if (!f.path || typeof f.path !== "string") {
+      throw new FiregraphError(
+        `IndexSpec field must be a string or { path: string, desc?: boolean }; got ${JSON.stringify(f)}`,
+        "INVALID_INDEX"
+      );
+    }
+    return { path: f.path, desc: !!f.desc };
+  });
+}
+function specFingerprint(spec, leadingColumns) {
+  const normalized = {
+    lead: leadingColumns,
+    fields: normalizeFields(spec.fields),
+    where: spec.where ?? ""
+  };
+  return fnv1a32(JSON.stringify(normalized));
+}
+function compileFieldExpr(path, fieldToColumn) {
+  const col = fieldToColumn[path];
+  if (col) return quoteIdent(col);
+  if (path === "data") {
+    return `json_extract("data", '$')`;
+  }
+  if (path.startsWith("data.")) {
+    const suffix = path.slice(5);
+    const parts = suffix.split(".");
+    for (const part of parts) {
+      if (!JSON_PATH_KEY_RE.test(part)) {
+        throw new FiregraphError(
+          `IndexSpec data path "${path}" has invalid component "${part}". Each component must match /^[A-Za-z_][A-Za-z0-9_-]*$/.`,
+          "INVALID_INDEX"
+        );
+      }
+    }
+    return `json_extract("data", '$.${suffix}')`;
+  }
+  throw new FiregraphError(
+    `IndexSpec field "${path}" is not a known firegraph field. Use a top-level field (aType, aUid, axbType, bType, bUid, createdAt, updatedAt, v) or a dotted data path like 'data.status'.`,
+    "INVALID_INDEX"
+  );
+}
+function buildIndexDDL(spec, options) {
+  const { table, fieldToColumn, leadingColumns = [] } = options;
+  if (!spec.fields || spec.fields.length === 0) {
+    throw new FiregraphError("IndexSpec.fields must be a non-empty array", "INVALID_INDEX");
+  }
+  const normalized = normalizeFields(spec.fields);
+  const hash = specFingerprint(spec, leadingColumns);
+  const indexName = `${table}_idx_${hash}`;
+  const cols = [];
+  for (const col of leadingColumns) {
+    cols.push(quoteIdent(col));
+  }
+  for (const f of normalized) {
+    const expr = compileFieldExpr(f.path, fieldToColumn);
+    cols.push(f.desc ? `${expr} DESC` : expr);
+  }
+  let ddl = `CREATE INDEX IF NOT EXISTS ${quoteIdent(indexName)} ON ${quoteIdent(table)}(${cols.join(", ")})`;
+  if (spec.where) {
+    ddl += ` WHERE ${spec.where}`;
+  }
+  return ddl;
+}
+function dedupeIndexSpecs(specs, leadingColumns = []) {
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const spec of specs) {
+    const fp = specFingerprint(spec, leadingColumns);
+    if (seen.has(fp)) continue;
+    seen.add(fp);
+    out.push(spec);
+  }
+  return out;
+}
+
+// src/cloudflare/schema.ts
+var DO_FIELD_TO_COLUMN = {
+  aType: "a_type",
+  aUid: "a_uid",
+  axbType: "axb_type",
+  bType: "b_type",
+  bUid: "b_uid",
+  v: "v",
+  createdAt: "created_at",
+  updatedAt: "updated_at"
+};
+var IDENT_RE2 = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function validateDOTableName(name) {
+  if (!IDENT_RE2.test(name)) {
+    throw new Error(`Invalid SQL identifier: ${name}. Must match /^[A-Za-z_][A-Za-z0-9_]*$/.`);
+  }
+}
+function quoteDOIdent(name) {
+  validateDOTableName(name);
+  return `"${name}"`;
+}
+function buildDOSchemaStatements(table, options = {}) {
+  const t = quoteDOIdent(table);
+  const statements = [
+    `CREATE TABLE IF NOT EXISTS ${t} (
+      doc_id      TEXT NOT NULL PRIMARY KEY,
+      a_type      TEXT NOT NULL,
+      a_uid       TEXT NOT NULL,
+      axb_type    TEXT NOT NULL,
+      b_type      TEXT NOT NULL,
+      b_uid       TEXT NOT NULL,
+      data        TEXT NOT NULL,
+      v           INTEGER,
+      created_at  INTEGER NOT NULL,
+      updated_at  INTEGER NOT NULL
+    )`
+  ];
+  const core = options.coreIndexes ?? [...DEFAULT_CORE_INDEXES];
+  const fromRegistry = options.registry?.entries().flatMap((e) => e.indexes ?? []) ?? [];
+  const deduped = dedupeIndexSpecs([...core, ...fromRegistry]);
+  for (const spec of deduped) {
+    statements.push(buildIndexDDL(spec, { table, fieldToColumn: DO_FIELD_TO_COLUMN }));
+  }
+  return statements;
+}
+
+// src/cloudflare/sql.ts
+function compileFieldRef(field) {
+  const column = DO_FIELD_TO_COLUMN[field];
+  if (column) {
+    return { expr: quoteDOIdent(column) };
+  }
+  if (field.startsWith("data.")) {
+    const suffix = field.slice(5);
+    for (const part of suffix.split(".")) {
+      validateJsonPathKey(part);
+    }
+    return { expr: `json_extract("data", '$.${suffix}')` };
+  }
+  if (field === "data") {
+    return { expr: `json_extract("data", '$')` };
+  }
+  throw new FiregraphError(
+    `DO SQLite backend cannot resolve filter field: ${field}`,
+    "INVALID_QUERY"
+  );
+}
+var FIRESTORE_TYPE_NAMES = /* @__PURE__ */ new Set([
+  "Timestamp",
+  "GeoPoint",
+  "VectorValue",
+  "DocumentReference",
+  "FieldValue"
+]);
+function isFirestoreSpecialType(value) {
+  const ctorName = value.constructor?.name;
+  if (ctorName && FIRESTORE_TYPE_NAMES.has(ctorName)) return ctorName;
+  return null;
+}
+function bindValue(value) {
+  if (value === null || value === void 0) return null;
+  if (typeof value === "string" || typeof value === "number" || typeof value === "bigint" || typeof value === "boolean") {
+    return value;
+  }
+  if (value instanceof Date) return value.getTime();
+  if (typeof value === "object") {
+    const firestoreType = isFirestoreSpecialType(value);
+    if (firestoreType) {
+      throw new FiregraphError(
+        `DO SQLite backend cannot bind a Firestore ${firestoreType} value \u2014 JSON serialization would silently drop fields and the resulting bind would never match a stored row. Convert to a primitive (e.g. \`ts.toMillis()\` for Timestamp) before filtering or updating.`,
+        "INVALID_QUERY"
+      );
+    }
+    return JSON.stringify(value);
+  }
+  return String(value);
+}
+var JSON_PATH_KEY_RE2 = /^[A-Za-z_][A-Za-z0-9_-]*$/;
+function validateJsonPathKey(key) {
+  if (key.length === 0) {
+    throw new FiregraphError(
+      "DO SQLite backend: empty JSON path component is not allowed",
+      "INVALID_QUERY"
+    );
+  }
+  if (!JSON_PATH_KEY_RE2.test(key)) {
+    throw new FiregraphError(
+      `DO SQLite backend: data field path component "${key}" is not a safe JSON-path identifier. Allowed pattern: /^[A-Za-z_][A-Za-z0-9_-]*$/. Use replaceData (full-data overwrite) for keys with reserved characters (whitespace, dots, brackets, quotes, etc.).`,
+      "INVALID_QUERY"
+    );
+  }
+}
+function compileFilter(filter, params) {
+  const { expr } = compileFieldRef(filter.field);
+  switch (filter.op) {
+    case "==":
+      params.push(bindValue(filter.value));
+      return `${expr} = ?`;
+    case "!=":
+      params.push(bindValue(filter.value));
+      return `${expr} != ?`;
+    case "<":
+      params.push(bindValue(filter.value));
+      return `${expr} < ?`;
+    case "<=":
+      params.push(bindValue(filter.value));
+      return `${expr} <= ?`;
+    case ">":
+      params.push(bindValue(filter.value));
+      return `${expr} > ?`;
+    case ">=":
+      params.push(bindValue(filter.value));
+      return `${expr} >= ?`;
+    case "in": {
+      const values = asArray(filter.value, "in");
+      const placeholders = values.map(() => "?").join(", ");
+      for (const v of values) params.push(bindValue(v));
+      return `${expr} IN (${placeholders})`;
+    }
+    case "not-in": {
+      const values = asArray(filter.value, "not-in");
+      const placeholders = values.map(() => "?").join(", ");
+      for (const v of values) params.push(bindValue(v));
+      return `${expr} NOT IN (${placeholders})`;
+    }
+    case "array-contains": {
+      params.push(bindValue(filter.value));
+      return `EXISTS (SELECT 1 FROM json_each(${expr}) WHERE value = ?)`;
+    }
+    case "array-contains-any": {
+      const values = asArray(filter.value, "array-contains-any");
+      const placeholders = values.map(() => "?").join(", ");
+      for (const v of values) params.push(bindValue(v));
+      return `EXISTS (SELECT 1 FROM json_each(${expr}) WHERE value IN (${placeholders}))`;
+    }
+    default:
+      throw new FiregraphError(
+        `DO SQLite backend does not support filter operator: ${String(filter.op)}`,
+        "INVALID_QUERY"
+      );
+  }
+}
+function asArray(value, op) {
+  if (!Array.isArray(value) || value.length === 0) {
+    throw new FiregraphError(`Operator "${op}" requires a non-empty array value`, "INVALID_QUERY");
+  }
+  return value;
+}
+function compileOrderBy(options, _params) {
+  if (!options?.orderBy) return "";
+  const { field, direction } = options.orderBy;
+  const { expr } = compileFieldRef(field);
+  const dir = direction === "desc" ? "DESC" : "ASC";
+  return ` ORDER BY ${expr} ${dir}`;
+}
+function compileLimit(options, params) {
+  if (options?.limit === void 0) return "";
+  params.push(options.limit);
+  return ` LIMIT ?`;
+}
+function compileDOSelect(table, filters, options) {
+  const params = [];
+  const conditions = [];
+  for (const f of filters) {
+    conditions.push(compileFilter(f, params));
+  }
+  const where = conditions.length > 0 ? ` WHERE ${conditions.join(" AND ")}` : "";
+  let sql = `SELECT * FROM ${quoteDOIdent(table)}${where}`;
+  sql += compileOrderBy(options, params);
+  sql += compileLimit(options, params);
+  return { sql, params };
+}
+function compileDOSelectByDocId(table, docId) {
+  return {
+    sql: `SELECT * FROM ${quoteDOIdent(table)} WHERE "doc_id" = ? LIMIT 1`,
+    params: [docId]
+  };
+}
+function compileDOSet(table, docId, record, nowMillis) {
+  const sql = `INSERT OR REPLACE INTO ${quoteDOIdent(table)} (
+    doc_id, a_type, a_uid, axb_type, b_type, b_uid, data, v, created_at, updated_at
+  ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`;
+  const params = [
+    docId,
+    record.aType,
+    record.aUid,
+    record.axbType,
+    record.bType,
+    record.bUid,
+    JSON.stringify(record.data ?? {}),
+    record.v ?? null,
+    nowMillis,
+    nowMillis
+  ];
+  return { sql, params };
+}
+function compileDOUpdate(table, docId, update, nowMillis) {
+  const setClauses = [];
+  const params = [];
+  if (update.replaceData) {
+    setClauses.push(`"data" = ?`);
+    params.push(JSON.stringify(update.replaceData));
+  } else if (update.dataFields && Object.keys(update.dataFields).length > 0) {
+    const entries = Object.entries(update.dataFields);
+    const pathArgs = entries.map(() => `?, ?`).join(", ");
+    setClauses.push(`"data" = json_set(COALESCE("data", '{}'), ${pathArgs})`);
+    for (const [k, v] of entries) {
+      validateJsonPathKey(k);
+      params.push(`$.${k}`);
+      params.push(bindValue(v));
+    }
+  }
+  if (update.v !== void 0) {
+    setClauses.push(`"v" = ?`);
+    params.push(update.v);
+  }
+  setClauses.push(`"updated_at" = ?`);
+  params.push(nowMillis);
+  params.push(docId);
+  return {
+    sql: `UPDATE ${quoteDOIdent(table)} SET ${setClauses.join(", ")} WHERE "doc_id" = ?`,
+    params
+  };
+}
+function compileDODelete(table, docId) {
+  return {
+    sql: `DELETE FROM ${quoteDOIdent(table)} WHERE "doc_id" = ?`,
+    params: [docId]
+  };
+}
+function compileDODeleteAll(table) {
+  return {
+    sql: `DELETE FROM ${quoteDOIdent(table)}`,
+    params: []
+  };
+}
+function rowToDORecord(row) {
+  const dataString = row.data;
+  const data = dataString ? JSON.parse(dataString) : {};
+  const createdAtMs = toMillis(row.created_at);
+  const updatedAtMs = toMillis(row.updated_at);
+  const record = {
+    aType: row.a_type,
+    aUid: row.a_uid,
+    axbType: row.axb_type,
+    bType: row.b_type,
+    bUid: row.b_uid,
+    data,
+    createdAtMs,
+    updatedAtMs
+  };
+  if (row.v !== null && row.v !== void 0) {
+    record.v = Number(row.v);
+  }
+  return record;
+}
+function hydrateDORecord(wire) {
+  const record = {
+    aType: wire.aType,
+    aUid: wire.aUid,
+    axbType: wire.axbType,
+    bType: wire.bType,
+    bUid: wire.bUid,
+    data: wire.data,
+    createdAt: GraphTimestampImpl.fromMillis(wire.createdAtMs),
+    updatedAt: GraphTimestampImpl.fromMillis(wire.updatedAtMs)
+  };
+  if (wire.v !== void 0) {
+    record.v = wire.v;
+  }
+  return record;
+}
+function toMillis(value) {
+  if (typeof value === "number") return value;
+  if (typeof value === "bigint") return Number(value);
+  if (typeof value === "string") {
+    const n = Number(value);
+    if (Number.isFinite(n)) return n;
+  }
+  throw new FiregraphError(
+    `DO SQLite row has non-numeric timestamp column: ${typeof value} (${String(value)})`,
+    "INVALID_QUERY"
+  );
+}
+
+// src/cloudflare/backend.ts
+function validateSegment(value, label) {
+  if (!value || value.includes("/")) {
+    throw new FiregraphError(
+      `Invalid ${label} for subgraph: "${value}". Must be non-empty and not contain "/".`,
+      "INVALID_SUBGRAPH"
+    );
+  }
+}
+function transactionsUnsupported() {
+  return new FiregraphError(
+    "Interactive transactions are not supported by the Cloudflare DO backend. Use `batch()` for atomic multi-write commits, or restructure the read-then-conditional-write as an explicit read \u2192 decide \u2192 batch sequence.",
+    "UNSUPPORTED_OPERATION"
+  );
+}
+var DORPCBatchBackend = class {
+  constructor(getStub) {
+    this.getStub = getStub;
+  }
+  ops = [];
+  setDoc(docId, record) {
+    this.ops.push({ kind: "set", docId, record });
+  }
+  updateDoc(docId, update) {
+    this.ops.push({ kind: "update", docId, update });
+  }
+  deleteDoc(docId) {
+    this.ops.push({ kind: "delete", docId });
+  }
+  async commit() {
+    if (this.ops.length === 0) return;
+    const ops = this.ops.slice();
+    this.ops.length = 0;
+    await this.getStub()._fgBatch(ops);
+  }
+};
+var DORPCBackend = class _DORPCBackend {
+  collectionPath = "firegraph";
+  scopePath;
+  /** @internal */
+  storageKey;
+  /** @internal */
+  namespace;
+  registryAccessor;
+  /** @internal — see `DORPCBackendOptions.makeSiblingClient` for the union-type rationale. */
+  makeSiblingClient;
+  cachedStub = null;
+  constructor(namespace, options) {
+    this.namespace = namespace;
+    this.scopePath = options.scopePath ?? "";
+    this.storageKey = options.storageKey;
+    this.registryAccessor = options.registryAccessor;
+    this.makeSiblingClient = options.makeSiblingClient;
+  }
+  get stub() {
+    if (!this.cachedStub) {
+      const id = this.namespace.idFromName(this.storageKey);
+      this.cachedStub = this.namespace.get(id);
+    }
+    return this.cachedStub;
+  }
+  // --- Reads ---
+  async getDoc(docId) {
+    const wire = await this.stub._fgGetDoc(docId);
+    return wire ? hydrateDORecord(wire) : null;
+  }
+  async query(filters, options) {
+    const wires = await this.stub._fgQuery(filters, options);
+    return wires.map(hydrateDORecord);
+  }
+  // --- Writes ---
+  async setDoc(docId, record) {
+    return this.stub._fgSetDoc(docId, record);
+  }
+  async updateDoc(docId, update) {
+    return this.stub._fgUpdateDoc(docId, update);
+  }
+  async deleteDoc(docId) {
+    return this.stub._fgDeleteDoc(docId);
+  }
+  // --- Transactions / batches ---
+  async runTransaction(_fn) {
+    void _fn;
+    throw transactionsUnsupported();
+  }
+  createBatch() {
+    return new DORPCBatchBackend(() => this.stub);
+  }
+  // --- Subgraphs ---
+  subgraph(parentNodeUid, name) {
+    validateSegment(parentNodeUid, "parentNodeUid");
+    validateSegment(name, "subgraph name");
+    const newStorageKey = `${this.storageKey}/${parentNodeUid}/${name}`;
+    const newScopePath = this.scopePath ? `${this.scopePath}/${name}` : name;
+    return new _DORPCBackend(this.namespace, {
+      scopePath: newScopePath,
+      storageKey: newStorageKey,
+      // Subgraph backends share the same live registry accessor so a cascade
+      // invoked on a subgraph client still fans out correctly. The sibling
+      // factory is also carried forward so `createSiblingClient` works from
+      // any subgraph client in the chain.
+      registryAccessor: this.registryAccessor,
+      makeSiblingClient: this.makeSiblingClient
+    });
+  }
+  // --- Cascade & bulk ---
+  async removeNodeCascade(uid, reader, options) {
+    const shouldDeleteSubgraphs = options?.deleteSubcollections !== false;
+    const registry = this.registryAccessor?.();
+    if (shouldDeleteSubgraphs && registry) {
+      const node = await reader.getNode(uid);
+      if (node) {
+        const topology = registry.getSubgraphTopology(node.aType);
+        for (const entry of topology) {
+          const target = entry.targetGraph;
+          const childBackend = this.subgraph(uid, target);
+          await childBackend.destroyRecursively(registry);
+        }
+      }
+    }
+    return this.stub._fgRemoveNodeCascade(uid);
+  }
+  async bulkRemoveEdges(params, _reader, options) {
+    void _reader;
+    return this.stub._fgBulkRemoveEdges(params, options);
+  }
+  // --- Cross-scope queries ---
+  //
+  // `findEdgesGlobal` is deliberately NOT defined on this class. The
+  // GraphClient checks for its presence before running query planning and
+  // throws `UNSUPPORTED_OPERATION` when absent, giving the caller an
+  // immediate, accurate error. Defining the method with a throwing body
+  // would only surface the same error AFTER `checkQuerySafety` had already
+  // fired — and for scan-unsafe calls that results in a misleading
+  // `QuerySafetyError` ("add filters like aUid+axbType") when no filter
+  // combination would actually make the call work on this backend. See the
+  // "What's not supported" section in `createDOClient` for the design
+  // rationale (no collection-group index across DOs).
+  // --- Destroy helpers ---
+  /**
+   * Wipe this DO's storage. The DO itself can't be deleted — its ID
+   * persists forever — but its rows can be emptied, which is what the
+   * cascade walk does on every descendant subgraph DO.
+   *
+   * Exposed on the concrete class (not `StorageBackend`) so generic
+   * backend code doesn't reach for it.
+   */
+  async destroy() {
+    await this.stub._fgDestroy();
+  }
+  /**
+   * Tear down every descendant subgraph DO, then wipe this DO's own rows.
+   *
+   * Invoked by cross-DO cascade: for each node in this DO we enumerate the
+   * subgraph topology and recurse into child DOs depth-first before
+   * wiping the current DO. The current DO's own rows are destroyed last so
+   * that a partial failure mid-recursion leaves the caller's reader able
+   * to discover what's still present.
+   *
+   * @internal
+   */
+  async destroyRecursively(registry) {
+    const nodes = await this.query([{ field: "axbType", op: "==", value: NODE_RELATION }]);
+    for (const node of nodes) {
+      const topology = registry.getSubgraphTopology(node.aType);
+      for (const entry of topology) {
+        const target = entry.targetGraph;
+        const childBackend = this.subgraph(node.aUid, target);
+        await childBackend.destroyRecursively(registry);
+      }
+    }
+    await this.destroy();
+  }
+};
+
+// src/cloudflare/client.ts
+function createDOClient(namespace, rootKey, options = {}) {
+  if (!rootKey || typeof rootKey !== "string") {
+    throw new FiregraphError(
+      `createDOClient: rootKey must be a non-empty string, got ${JSON.stringify(rootKey)}.`,
+      "INVALID_ARGUMENT"
+    );
+  }
+  if (rootKey.includes("/")) {
+    throw new FiregraphError(
+      `createDOClient: rootKey must not contain "/". Got: "${rootKey}".`,
+      "INVALID_ARGUMENT"
+    );
+  }
+  let client;
+  const registryAccessor = () => {
+    if (!client) {
+      throw new FiregraphError(
+        "createDOClient: registryAccessor fired before the client was assigned. This indicates a programming error in the DO backend \u2014 the accessor must only be invoked lazily from `removeNodeCascade`, never synchronously from the `DORPCBackend` constructor.",
+        "INTERNAL"
+      );
+    }
+    return client.getRegistrySnapshot();
+  };
+  const siblingOptions = { ...options };
+  const makeSiblingClient = (siblingRootKey) => createDOClient(namespace, siblingRootKey, siblingOptions);
+  const backend = new DORPCBackend(namespace, {
+    scopePath: "",
+    storageKey: rootKey,
+    registryAccessor,
+    makeSiblingClient
+  });
+  let metaBackend;
+  if (options.registryMode?.collection) {
+    const metaKey = options.registryMode.collection;
+    if (metaKey.includes("/")) {
+      throw new FiregraphError(
+        `createDOClient: registryMode.collection must not contain "/". Got: "${metaKey}".`,
+        "INVALID_ARGUMENT"
+      );
+    }
+    if (metaKey !== rootKey) {
+      metaBackend = new DORPCBackend(namespace, {
+        scopePath: "",
+        storageKey: metaKey,
+        // Meta backend shares the accessor so its own `removeNodeCascade`
+        // (unlikely, but safe) would also see the live registry. Sibling
+        // factory is carried for consistency; there's no user-facing path
+        // that creates a sibling from the meta backend, but it costs
+        // nothing to keep the two backends in sync.
+        registryAccessor,
+        makeSiblingClient
+      });
+    }
+  }
+  client = createGraphClientFromBackend(backend, options, metaBackend);
+  return client;
+}
+function createSiblingClient(client, siblingRootKey) {
+  if (!siblingRootKey || typeof siblingRootKey !== "string") {
+    throw new FiregraphError(
+      `createSiblingClient: siblingRootKey must be a non-empty string, got ${JSON.stringify(siblingRootKey)}.`,
+      "INVALID_ARGUMENT"
+    );
+  }
+  if (siblingRootKey.includes("/")) {
+    throw new FiregraphError(
+      `createSiblingClient: siblingRootKey must not contain "/". Got: "${siblingRootKey}".`,
+      "INVALID_ARGUMENT"
+    );
+  }
+  const impl = client;
+  const backend = typeof impl.getBackend === "function" ? impl.getBackend() : void 0;
+  const maker = backend && backend.makeSiblingClient;
+  if (typeof maker !== "function") {
+    throw new FiregraphError(
+      "createSiblingClient: the provided client is not backed by a DO client produced by `createDOClient`. Sibling construction is only available for DO-backed clients.",
+      "UNSUPPORTED_OPERATION"
+    );
+  }
+  return maker(siblingRootKey);
+}
+
+// src/cloudflare/do.ts
+var DEFAULT_OPTIONS = {
+  table: "firegraph",
+  autoMigrate: true
+};
+var FiregraphDO = class {
+  /** @internal — exposed for subclass access, not part of the public RPC. */
+  ctx;
+  /** @internal — exposed for subclass access; opaque to this class. */
+  env;
+  /** @internal — table name used by every compiled statement. */
+  table;
+  /** @internal — registry consulted by `runSchema` for per-entry indexes. */
+  registry;
+  /** @internal — overrides `DEFAULT_CORE_INDEXES` when set. */
+  coreIndexes;
+  constructor(ctx, env, options = {}) {
+    this.ctx = ctx;
+    this.env = env;
+    const table = options.table ?? DEFAULT_OPTIONS.table;
+    validateDOTableName(table);
+    this.table = table;
+    this.registry = options.registry;
+    this.coreIndexes = options.coreIndexes;
+    const autoMigrate = options.autoMigrate ?? DEFAULT_OPTIONS.autoMigrate;
+    if (autoMigrate) {
+      void this.ctx.blockConcurrencyWhile(async () => {
+        this.runSchema();
+      });
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // RPC: reads
+  //
+  // Method names are prefixed `_fg` so user subclasses can add their own RPC
+  // methods without name collisions. The client-side backend in
+  // `src/cloudflare/backend.ts` calls these directly on the DO stub.
+  // ---------------------------------------------------------------------------
+  async _fgGetDoc(docId) {
+    const stmt = compileDOSelectByDocId(this.table, docId);
+    const rows = this.execAll(stmt);
+    return rows.length === 0 ? null : rowToDORecord(rows[0]);
+  }
+  async _fgQuery(filters, options) {
+    const stmt = compileDOSelect(this.table, filters, options);
+    const rows = this.execAll(stmt);
+    return rows.map(rowToDORecord);
+  }
+  // ---------------------------------------------------------------------------
+  // RPC: writes
+  // ---------------------------------------------------------------------------
+  async _fgSetDoc(docId, record) {
+    const stmt = compileDOSet(this.table, docId, record, Date.now());
+    this.execRun(stmt);
+  }
+  async _fgUpdateDoc(docId, update) {
+    const stmt = compileDOUpdate(this.table, docId, update, Date.now());
+    const sqlWithReturning = `${stmt.sql} RETURNING "doc_id"`;
+    const rows = this.ctx.storage.sql.exec(sqlWithReturning, ...stmt.params).toArray();
+    if (rows.length === 0) {
+      throw new FiregraphError(`updateDoc: no document found for doc_id=${docId}`, "NOT_FOUND");
+    }
+  }
+  async _fgDeleteDoc(docId) {
+    const stmt = compileDODelete(this.table, docId);
+    this.execRun(stmt);
+  }
+  // ---------------------------------------------------------------------------
+  // RPC: batch
+  // ---------------------------------------------------------------------------
+  /**
+   * Execute a list of write ops atomically. DO SQLite's `transactionSync`
+   * provides real atomicity — either every statement commits or none do.
+   * No statement-count cap applies (contrast with D1's ~100-statement batch
+   * limit), so the caller can submit as many ops as they like in one call.
+   */
+  async _fgBatch(ops) {
+    if (ops.length === 0) return;
+    const now = Date.now();
+    const statements = ops.map((op) => {
+      switch (op.kind) {
+        case "set":
+          return compileDOSet(this.table, op.docId, op.record, now);
+        case "update":
+          return compileDOUpdate(this.table, op.docId, op.update, now);
+        case "delete":
+          return compileDODelete(this.table, op.docId);
+      }
+    });
+    this.ctx.storage.transactionSync(() => {
+      for (const stmt of statements) {
+        this.ctx.storage.sql.exec(stmt.sql, ...stmt.params).toArray();
+      }
+    });
+  }
+  // ---------------------------------------------------------------------------
+  // RPC: cascade + bulk (local DO only)
+  //
+  // These cascade *within this DO*. Subgraph DOs (nested under this node) are
+  // not reachable from here — the client-side `DORPCBackend.removeNodeCascade`
+  // consults the registry topology to discover descendant subgraph DOs and
+  // fans out explicit `_fgDestroy` calls to each before invoking this method.
+  // Without that topology the DO has no way to enumerate its children.
+  // ---------------------------------------------------------------------------
+  async _fgRemoveNodeCascade(uid) {
+    const outgoingStmt = compileDOSelect(this.table, [{ field: "aUid", op: "==", value: uid }]);
+    const incomingStmt = compileDOSelect(this.table, [{ field: "bUid", op: "==", value: uid }]);
+    const outgoingRows = this.execAll(outgoingStmt);
+    const incomingRows = this.execAll(incomingStmt);
+    const seen = /* @__PURE__ */ new Set();
+    const edgeDocIds = [];
+    let nodeExists = false;
+    for (const row of [...outgoingRows, ...incomingRows]) {
+      const axbType = row.axb_type;
+      const aUid = row.a_uid;
+      const bUid = row.b_uid;
+      if (axbType === NODE_RELATION && aUid === bUid) {
+        nodeExists = true;
+        continue;
+      }
+      const docId = computeEdgeDocId(aUid, axbType, bUid);
+      if (!seen.has(docId)) {
+        seen.add(docId);
+        edgeDocIds.push(docId);
+      }
+    }
+    const statements = edgeDocIds.map((id) => compileDODelete(this.table, id));
+    if (nodeExists) {
+      statements.push(compileDODelete(this.table, computeNodeDocId(uid)));
+    }
+    if (statements.length === 0) {
+      return {
+        deleted: 0,
+        batches: 0,
+        errors: [],
+        edgesDeleted: 0,
+        nodeDeleted: false
+      };
+    }
+    try {
+      this.ctx.storage.transactionSync(() => {
+        for (const stmt of statements) {
+          this.ctx.storage.sql.exec(stmt.sql, ...stmt.params).toArray();
+        }
+      });
+      return {
+        deleted: statements.length,
+        batches: 1,
+        errors: [],
+        edgesDeleted: edgeDocIds.length,
+        nodeDeleted: nodeExists
+      };
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      return {
+        deleted: 0,
+        batches: 0,
+        errors: [{ batchIndex: 0, error, operationCount: statements.length }],
+        edgesDeleted: 0,
+        nodeDeleted: false
+      };
+    }
+  }
+  async _fgBulkRemoveEdges(params, _options) {
+    const plan = buildEdgeQueryPlan(params);
+    let docIds;
+    if (plan.strategy === "get") {
+      const existsStmt = compileDOSelectByDocId(this.table, plan.docId);
+      const rows = this.execAll(existsStmt);
+      docIds = rows.length > 0 ? [plan.docId] : [];
+    } else {
+      const selectStmt = compileDOSelect(this.table, plan.filters, plan.options);
+      const rows = this.execAll(selectStmt);
+      docIds = rows.map(
+        (row) => computeEdgeDocId(row.a_uid, row.axb_type, row.b_uid)
+      );
+    }
+    if (docIds.length === 0) {
+      return { deleted: 0, batches: 0, errors: [] };
+    }
+    const deleteStmts = docIds.map((id) => compileDODelete(this.table, id));
+    try {
+      this.ctx.storage.transactionSync(() => {
+        for (const stmt of deleteStmts) {
+          this.ctx.storage.sql.exec(stmt.sql, ...stmt.params).toArray();
+        }
+      });
+      return { deleted: deleteStmts.length, batches: 1, errors: [] };
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      return {
+        deleted: 0,
+        batches: 0,
+        errors: [{ batchIndex: 0, error, operationCount: deleteStmts.length }]
+      };
+    }
+  }
+  // ---------------------------------------------------------------------------
+  // RPC: admin
+  // ---------------------------------------------------------------------------
+  /**
+   * Wipe every row. Called by the client when tearing down a subgraph DO as
+   * part of cascade — the DO itself can't be destroyed (DO IDs persist
+   * forever), but its storage can be emptied.
+   */
+  async _fgDestroy() {
+    const stmt = compileDODeleteAll(this.table);
+    this.execRun(stmt);
+  }
+  // ---------------------------------------------------------------------------
+  // Internals
+  // ---------------------------------------------------------------------------
+  runSchema() {
+    const statements = buildDOSchemaStatements(this.table, {
+      coreIndexes: this.coreIndexes,
+      registry: this.registry
+    });
+    for (const sql of statements) {
+      this.ctx.storage.sql.exec(sql).toArray();
+    }
+  }
+  execAll(stmt) {
+    return this.ctx.storage.sql.exec(stmt.sql, ...stmt.params).toArray();
+  }
+  execRun(stmt) {
+    this.ctx.storage.sql.exec(stmt.sql, ...stmt.params).toArray();
+  }
+};
+export {
+  DORPCBackend,
+  FiregraphDO,
+  buildDOSchemaStatements,
+  createDOClient,
+  createSiblingClient
+};
+//# sourceMappingURL=index.js.map