@typicalday/firegraph 0.11.2 → 0.13.0

package/dist/cloudflare/index.js

@@ -1,137 +1,39 @@
 import {
-  DEFAULT_CORE_INDEXES,
+  GraphTimestampImpl,
+  assertJsonSafePayload,
+  buildIndexDDL,
+  compileDataOpsExpr,
+  dedupeIndexSpecs,
+  isFirestoreSpecialType,
+  validateJsonPathKey
+} from "../chunk-4MMQ5W74.js";
+import {
+  DEFAULT_CORE_INDEXES
+} from "../chunk-2DHMNTV6.js";
+import {
+  createCapabilities,
+  intersectCapabilities
+} from "../chunk-N5HFDWQX.js";
+import {
+  META_EDGE_TYPE,
+  META_NODE_TYPE,
   NODE_RELATION,
   buildEdgeQueryPlan,
   computeEdgeDocId,
   computeNodeDocId,
-  createGraphClientFromBackend
-} from "../chunk-NJSOD64C.js";
+  createGraphClientFromBackend,
+  createMergedRegistry,
+  createRegistry,
+  generateId
+} from "../chunk-WRTFC5NG.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;
-}
+  CapabilityNotSupportedError,
+  FiregraphError,
+  assertUpdatePayloadExclusive,
+  deleteField,
+  flattenPatch
+} from "../chunk-TK64DNVK.js";
+import "../chunk-EQJUUVFG.js";
 
 // src/cloudflare/schema.ts
 var DO_FIELD_TO_COLUMN = {
@@ -144,9 +46,9 @@ var DO_FIELD_TO_COLUMN = {
   createdAt: "created_at",
   updatedAt: "updated_at"
 };
-var IDENT_RE2 = /^[A-Za-z_][A-Za-z0-9_]*$/;
+var IDENT_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
 function validateDOTableName(name) {
-  if (!IDENT_RE2.test(name)) {
+  if (!IDENT_RE.test(name)) {
     throw new Error(`Invalid SQL identifier: ${name}. Must match /^[A-Za-z_][A-Za-z0-9_]*$/.`);
   }
 }
@@ -154,6 +56,9 @@ function quoteDOIdent(name) {
   validateDOTableName(name);
   return `"${name}"`;
 }
+function quoteDOColumnAlias(label) {
+  return `"${label.replace(/"/g, '""')}"`;
+}
 function buildDOSchemaStatements(table, options = {}) {
   const t = quoteDOIdent(table);
   const statements = [
@@ -180,6 +85,8 @@ function buildDOSchemaStatements(table, options = {}) {
 }
 
 // src/cloudflare/sql.ts
+var DO_BACKEND_LABEL = "DO SQLite";
+var DO_BACKEND_ERR_LABEL = "DO SQLite backend";
 function compileFieldRef(field) {
   const column = DO_FIELD_TO_COLUMN[field];
   if (column) {
@@ -188,7 +95,7 @@ function compileFieldRef(field) {
   if (field.startsWith("data.")) {
     const suffix = field.slice(5);
     for (const part of suffix.split(".")) {
-      validateJsonPathKey(part);
+      validateJsonPathKey(part, DO_BACKEND_ERR_LABEL);
     }
     return { expr: `json_extract("data", '$.${suffix}')` };
   }
@@ -200,18 +107,6 @@ function compileFieldRef(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") {
@@ -230,21 +125,6 @@ function bindValue(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) {
@@ -325,17 +205,244 @@ function compileDOSelect(table, filters, options) {
   sql += compileLimit(options, params);
   return { sql, params };
 }
+function compileDOExpand(table, params) {
+  if (params.sources.length === 0) {
+    throw new FiregraphError(
+      "compileDOExpand requires a non-empty sources list \u2014 empty IN () is invalid SQL.",
+      "INVALID_QUERY"
+    );
+  }
+  const direction = params.direction ?? "forward";
+  const aUidCol = compileFieldRef("aUid").expr;
+  const bUidCol = compileFieldRef("bUid").expr;
+  const aTypeCol = compileFieldRef("aType").expr;
+  const bTypeCol = compileFieldRef("bType").expr;
+  const axbTypeCol = compileFieldRef("axbType").expr;
+  const sourceColumn = direction === "forward" ? aUidCol : bUidCol;
+  const sqlParams = [params.axbType];
+  const conditions = [`${axbTypeCol} = ?`];
+  const placeholders = params.sources.map(() => "?").join(", ");
+  conditions.push(`${sourceColumn} IN (${placeholders})`);
+  for (const uid of params.sources) sqlParams.push(uid);
+  if (params.aType !== void 0) {
+    conditions.push(`${aTypeCol} = ?`);
+    sqlParams.push(params.aType);
+  }
+  if (params.bType !== void 0) {
+    conditions.push(`${bTypeCol} = ?`);
+    sqlParams.push(params.bType);
+  }
+  if (params.axbType === NODE_RELATION) {
+    conditions.push(`${aUidCol} != ${bUidCol}`);
+  }
+  let sql = `SELECT * FROM ${quoteDOIdent(table)} WHERE ${conditions.join(" AND ")}`;
+  if (params.orderBy) {
+    sql += compileOrderBy({ orderBy: params.orderBy }, sqlParams);
+  }
+  if (params.limitPerSource !== void 0) {
+    const totalLimit = params.sources.length * params.limitPerSource;
+    sql += ` LIMIT ?`;
+    sqlParams.push(totalLimit);
+  }
+  return { sql, params: sqlParams };
+}
+function compileDOExpandHydrate(table, targetUids) {
+  if (targetUids.length === 0) {
+    throw new FiregraphError(
+      "compileDOExpandHydrate requires a non-empty target list \u2014 empty IN () is invalid SQL.",
+      "INVALID_QUERY"
+    );
+  }
+  const placeholders = targetUids.map(() => "?").join(", ");
+  const sqlParams = [NODE_RELATION];
+  for (const uid of targetUids) sqlParams.push(uid);
+  const aUidCol = compileFieldRef("aUid").expr;
+  const bUidCol = compileFieldRef("bUid").expr;
+  const axbTypeCol = compileFieldRef("axbType").expr;
+  return {
+    sql: `SELECT * FROM ${quoteDOIdent(table)} WHERE ${axbTypeCol} = ? AND ${aUidCol} = ${bUidCol} AND ${bUidCol} IN (${placeholders})`,
+    params: sqlParams
+  };
+}
 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 = [
+function normalizeDOProjectionField(field) {
+  if (field in DO_FIELD_TO_COLUMN) return field;
+  if (field === "data" || field.startsWith("data.")) return field;
+  return `data.${field}`;
+}
+function compileDOFindEdgesProjected(table, select, filters, options) {
+  if (select.length === 0) {
+    throw new FiregraphError(
+      "compileDOFindEdgesProjected requires a non-empty select list \u2014 an empty projection has no SQL representation distinct from `findEdges`.",
+      "INVALID_QUERY"
+    );
+  }
+  const seen = /* @__PURE__ */ new Set();
+  const uniqueFields = [];
+  for (const f of select) {
+    if (!seen.has(f)) {
+      seen.add(f);
+      uniqueFields.push(f);
+    }
+  }
+  const projections = [];
+  const columns = [];
+  for (let idx = 0; idx < uniqueFields.length; idx++) {
+    const field = uniqueFields[idx];
+    const canonical = normalizeDOProjectionField(field);
+    const { expr } = compileFieldRef(canonical);
+    const alias = quoteDOColumnAlias(field);
+    projections.push(`${expr} AS ${alias}`);
+    let kind;
+    let typeAliasName;
+    if (canonical === "data") {
+      kind = "data";
+    } else if (canonical.startsWith("data.")) {
+      kind = "json";
+      typeAliasName = `__fg_t_${idx}`;
+      const typeAlias = quoteDOColumnAlias(typeAliasName);
+      projections.push(`json_type("data", '$.${canonical.slice(5)}') AS ${typeAlias}`);
+    } else {
+      if (canonical === "v") kind = "builtin-int";
+      else if (canonical === "createdAt" || canonical === "updatedAt") kind = "builtin-timestamp";
+      else kind = "builtin-text";
+    }
+    columns.push({ field, kind, typeAlias: typeAliasName });
+  }
+  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 ${projections.join(", ")} FROM ${quoteDOIdent(table)}${where}`;
+  sql += compileOrderBy(options, params);
+  sql += compileLimit(options, params);
+  return { stmt: { sql, params }, columns };
+}
+function decodeDOProjectedRow(row, columns) {
+  const out = {};
+  for (const c of columns) {
+    const raw = row[c.field];
+    switch (c.kind) {
+      case "builtin-text":
+        out[c.field] = raw === null || raw === void 0 ? null : String(raw);
+        break;
+      case "builtin-int":
+        if (raw === null || raw === void 0) {
+          out[c.field] = null;
+        } else if (typeof raw === "bigint") {
+          out[c.field] = Number(raw);
+        } else if (typeof raw === "number") {
+          out[c.field] = raw;
+        } else {
+          out[c.field] = Number(raw);
+        }
+        break;
+      case "builtin-timestamp": {
+        const ms = toMillis(raw);
+        out[c.field] = GraphTimestampImpl.fromMillis(ms);
+        break;
+      }
+      case "data":
+        if (raw === null || raw === void 0 || raw === "") {
+          out[c.field] = {};
+        } else {
+          out[c.field] = JSON.parse(raw);
+        }
+        break;
+      case "json": {
+        const t = row[c.typeAlias];
+        if (raw === null || raw === void 0) {
+          out[c.field] = null;
+        } else if (t === "object" || t === "array") {
+          out[c.field] = typeof raw === "string" ? JSON.parse(raw) : raw;
+        } else if (t === "integer" && typeof raw === "bigint") {
+          out[c.field] = Number(raw);
+        } else {
+          out[c.field] = raw;
+        }
+        break;
+      }
+    }
+  }
+  return out;
+}
+function compileDOAggregate(table, spec, filters) {
+  const aliases = Object.keys(spec);
+  if (aliases.length === 0) {
+    throw new FiregraphError(
+      "aggregate() requires at least one aggregation in the `aggregates` map.",
+      "INVALID_QUERY"
+    );
+  }
+  const projections = [];
+  for (const alias of aliases) {
+    const { op, field } = spec[alias];
+    validateJsonPathKey(alias, DO_BACKEND_ERR_LABEL);
+    if (op === "count") {
+      if (field !== void 0) {
+        throw new FiregraphError(
+          `Aggregate '${alias}' op 'count' must not specify a field \u2014 count operates on rows, not a column expression.`,
+          "INVALID_QUERY"
+        );
+      }
+      projections.push(`COUNT(*) AS ${quoteDOIdent(alias)}`);
+      continue;
+    }
+    if (!field) {
+      throw new FiregraphError(
+        `Aggregate '${alias}' op '${op}' requires a field.`,
+        "INVALID_QUERY"
+      );
+    }
+    const { expr } = compileFieldRef(field);
+    const numeric = `CAST(${expr} AS REAL)`;
+    if (op === "sum") projections.push(`SUM(${numeric}) AS ${quoteDOIdent(alias)}`);
+    else if (op === "avg") projections.push(`AVG(${numeric}) AS ${quoteDOIdent(alias)}`);
+    else if (op === "min") projections.push(`MIN(${numeric}) AS ${quoteDOIdent(alias)}`);
+    else if (op === "max") projections.push(`MAX(${numeric}) AS ${quoteDOIdent(alias)}`);
+    else
+      throw new FiregraphError(
+        `DO SQLite backend does not support aggregate op: ${String(op)}`,
+        "INVALID_QUERY"
+      );
+  }
+  const params = [];
+  const conditions = [];
+  for (const f of filters) {
+    conditions.push(compileFilter(f, params));
+  }
+  const where = conditions.length > 0 ? ` WHERE ${conditions.join(" AND ")}` : "";
+  const sql = `SELECT ${projections.join(", ")} FROM ${quoteDOIdent(table)}${where}`;
+  return { stmt: { sql, params }, aliases };
+}
+function compileDOSet(table, docId, record, nowMillis, mode) {
+  assertJsonSafePayload(record.data, DO_BACKEND_LABEL);
+  if (mode === "replace") {
+    const sql2 = `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: sql2, params };
+  }
+  const insertParams = [
     docId,
     record.aType,
     record.aUid,
@@ -347,22 +454,44 @@ function compileDOSet(table, docId, record, nowMillis) {
     nowMillis,
     nowMillis
   ];
-  return { sql, params };
+  const ops = flattenPatch(record.data ?? {});
+  const updateParams = [];
+  const dataExpr = compileDataOpsExpr(ops, `COALESCE("data", '{}')`, updateParams, DO_BACKEND_ERR_LABEL) ?? `COALESCE("data", '{}')`;
+  const sql = `INSERT INTO ${quoteDOIdent(table)} (
+      doc_id, a_type, a_uid, axb_type, b_type, b_uid, data, v, created_at, updated_at
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(doc_id) DO UPDATE SET
+      "a_type" = excluded."a_type",
+      "a_uid" = excluded."a_uid",
+      "axb_type" = excluded."axb_type",
+      "b_type" = excluded."b_type",
+      "b_uid" = excluded."b_uid",
+      "data" = ${dataExpr},
+      "v" = COALESCE(excluded."v", "v"),
+      "created_at" = excluded."created_at",
+      "updated_at" = excluded."updated_at"`;
+  return { sql, params: [...insertParams, ...updateParams] };
 }
 function compileDOUpdate(table, docId, update, nowMillis) {
+  assertUpdatePayloadExclusive(update);
   const setClauses = [];
   const params = [];
   if (update.replaceData) {
+    assertJsonSafePayload(update.replaceData, DO_BACKEND_LABEL);
     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));
+  } else if (update.dataOps && update.dataOps.length > 0) {
+    for (const op of update.dataOps) {
+      if (!op.delete) assertJsonSafePayload(op.value, DO_BACKEND_LABEL);
+    }
+    const expr = compileDataOpsExpr(
+      update.dataOps,
+      `COALESCE("data", '{}')`,
+      params,
+      DO_BACKEND_ERR_LABEL
+    );
+    if (expr !== null) {
+      setClauses.push(`"data" = ${expr}`);
     }
   }
   if (update.v !== void 0) {
@@ -383,6 +512,55 @@ function compileDODelete(table, docId) {
     params: [docId]
   };
 }
+function compileDOBulkDelete(table, filters) {
+  const params = [];
+  const conditions = [];
+  for (const f of filters) {
+    conditions.push(compileFilter(f, params));
+  }
+  const where = conditions.length > 0 ? ` WHERE ${conditions.join(" AND ")}` : "";
+  return {
+    sql: `DELETE FROM ${quoteDOIdent(table)}${where}`,
+    params
+  };
+}
+function compileDOBulkUpdate(table, filters, patchData, nowMillis) {
+  const dataOps = flattenPatch(patchData);
+  if (dataOps.length === 0) {
+    throw new FiregraphError(
+      "bulkUpdate() patch.data must contain at least one leaf \u2014 an empty patch would only rewrite `updated_at`, which is almost certainly a bug. Use `setDoc` with merge mode if you want to stamp without editing data.",
+      "INVALID_QUERY"
+    );
+  }
+  for (const op of dataOps) {
+    if (!op.delete) assertJsonSafePayload(op.value, DO_BACKEND_LABEL);
+  }
+  const setParams = [];
+  const expr = compileDataOpsExpr(
+    dataOps,
+    `COALESCE("data", '{}')`,
+    setParams,
+    DO_BACKEND_ERR_LABEL
+  );
+  if (expr === null) {
+    throw new FiregraphError(
+      "bulkUpdate() patch produced no SQL operations \u2014 internal invariant violated.",
+      "INVALID_ARGUMENT"
+    );
+  }
+  const setClauses = [`"data" = ${expr}`, `"updated_at" = ?`];
+  setParams.push(nowMillis);
+  const whereParams = [];
+  const conditions = [];
+  for (const f of filters) {
+    conditions.push(compileFilter(f, whereParams));
+  }
+  const where = conditions.length > 0 ? ` WHERE ${conditions.join(" AND ")}` : "";
+  return {
+    sql: `UPDATE ${quoteDOIdent(table)} SET ${setClauses.join(", ")}${where}`,
+    params: [...setParams, ...whereParams]
+  };
+}
 function compileDODeleteAll(table) {
   return {
     sql: `DELETE FROM ${quoteDOIdent(table)}`,
@@ -458,8 +636,8 @@ var DORPCBatchBackend = class {
     this.getStub = getStub;
   }
   ops = [];
-  setDoc(docId, record) {
-    this.ops.push({ kind: "set", docId, record });
+  setDoc(docId, record, mode) {
+    this.ops.push({ kind: "set", docId, record, mode });
   }
   updateDoc(docId, update) {
     this.ops.push({ kind: "update", docId, update });
@@ -474,7 +652,18 @@ var DORPCBatchBackend = class {
     await this.getStub()._fgBatch(ops);
   }
 };
+var DO_CAPS = /* @__PURE__ */ new Set([
+  "core.read",
+  "core.write",
+  "core.batch",
+  "core.subgraph",
+  "query.aggregate",
+  "query.dml",
+  "query.join",
+  "query.select"
+]);
 var DORPCBackend = class _DORPCBackend {
+  capabilities = createCapabilities(DO_CAPS);
   collectionPath = "firegraph";
   scopePath;
   /** @internal */
@@ -508,9 +697,37 @@ var DORPCBackend = class _DORPCBackend {
     const wires = await this.stub._fgQuery(filters, options);
     return wires.map(hydrateDORecord);
   }
+  // --- Aggregate ---
+  /**
+   * Run an aggregate query inside the backing DO. The DO returns a row of
+   * `{ alias: number | null }` (null = SQLite NULL for SUM/MIN/MAX over an
+   * empty set, or the count being literally 0); this method resolves NULL
+   * to 0 for SUM/MIN/MAX and to NaN for AVG, matching the SQLite backend
+   * and the Firestore Standard helper.
+   */
+  async aggregate(spec, filters) {
+    const stub = this.stub;
+    if (!stub._fgAggregate) {
+      throw new FiregraphError(
+        "aggregate() not supported by this Durable Object stub. The wrapped stub does not implement `_fgAggregate`. If you control the stub wrapper, forward `_fgAggregate` to the underlying DO.",
+        "UNSUPPORTED_OPERATION"
+      );
+    }
+    const wire = await stub._fgAggregate(spec, filters);
+    const out = {};
+    for (const [alias, { op }] of Object.entries(spec)) {
+      const v = wire[alias];
+      if (v === null || v === void 0) {
+        out[alias] = op === "avg" ? Number.NaN : 0;
+      } else {
+        out[alias] = v;
+      }
+    }
+    return out;
+  }
   // --- Writes ---
-  async setDoc(docId, record) {
-    return this.stub._fgSetDoc(docId, record);
+  async setDoc(docId, record, mode) {
+    return this.stub._fgSetDoc(docId, record, mode);
   }
   async updateDoc(docId, update) {
     return this.stub._fgUpdateDoc(docId, update);
@@ -564,6 +781,105 @@ var DORPCBackend = class _DORPCBackend {
     void _reader;
     return this.stub._fgBulkRemoveEdges(params, options);
   }
+  // --- Server-side DML (capability: query.dml) ---
+  /**
+   * Single-statement bulk DELETE inside the backing DO. The DO compiles
+   * the filter list to one `DELETE … WHERE …` statement and returns a
+   * `BulkResult` whose `deleted` is the affected-row count.
+   *
+   * Defensive `_fgBulkDelete` presence check mirrors `aggregate()`: the
+   * RPC method is optional on `FiregraphStub` so external worker code with
+   * a hand-rolled stub wrapper still type-checks. Surface a clear
+   * `UNSUPPORTED_OPERATION` rather than `TypeError: stub._fgBulkDelete is
+   * not a function` when the wrapper hasn't forwarded the method.
+   */
+  async bulkDelete(filters, options) {
+    const stub = this.stub;
+    if (!stub._fgBulkDelete) {
+      throw new FiregraphError(
+        "bulkDelete() not supported by this Durable Object stub. The wrapped stub does not implement `_fgBulkDelete`. If you control the stub wrapper, forward `_fgBulkDelete` to the underlying DO.",
+        "UNSUPPORTED_OPERATION"
+      );
+    }
+    return stub._fgBulkDelete(filters, options);
+  }
+  /**
+   * Single-statement bulk UPDATE inside the backing DO. Same contract as
+   * `bulkDelete` for the missing-method case; the DO compiles the patch to
+   * one `UPDATE … SET data = json_patch(...) WHERE …` statement.
+   */
+  async bulkUpdate(filters, patch, options) {
+    const stub = this.stub;
+    if (!stub._fgBulkUpdate) {
+      throw new FiregraphError(
+        "bulkUpdate() not supported by this Durable Object stub. The wrapped stub does not implement `_fgBulkUpdate`. If you control the stub wrapper, forward `_fgBulkUpdate` to the underlying DO.",
+        "UNSUPPORTED_OPERATION"
+      );
+    }
+    return stub._fgBulkUpdate(filters, patch, options);
+  }
+  /**
+   * Multi-source fan-out — `query.join` capability. Routes the call through
+   * the DO's `_fgExpand` RPC, which compiles to one `SELECT … WHERE
+   * "aUid" IN (?, …)` statement (plus, when `params.hydrate === true`, a
+   * second IN-clause statement against the node rows).
+   *
+   * Defensive `_fgExpand` presence check matches the bulk-DML pattern: the
+   * RPC method is optional on `FiregraphStub` so external worker code with
+   * a hand-rolled stub wrapper still type-checks. We surface a clear
+   * `UNSUPPORTED_OPERATION` rather than `TypeError: stub._fgExpand is not a
+   * function` if the wrapper hasn't forwarded the method.
+   */
+  async expand(params) {
+    const stub = this.stub;
+    if (!stub._fgExpand) {
+      throw new FiregraphError(
+        "expand() not supported by this Durable Object stub. The wrapped stub does not implement `_fgExpand`. If you control the stub wrapper, forward `_fgExpand` to the underlying DO.",
+        "UNSUPPORTED_OPERATION"
+      );
+    }
+    if (params.sources.length === 0) {
+      return params.hydrate ? { edges: [], targets: [] } : { edges: [] };
+    }
+    const wire = await stub._fgExpand(params);
+    const edges = wire.edges.map(hydrateDORecord);
+    if (!params.hydrate) {
+      return { edges };
+    }
+    const targets = (wire.targets ?? []).map((row) => row ? hydrateDORecord(row) : null);
+    return { edges, targets };
+  }
+  // --- Server-side projection (capability: query.select) ---
+  /**
+   * Server-side projection — `query.select` capability. Forwards the call to
+   * the DO's `_fgFindEdgesProjected` RPC, which compiles to a single
+   * `SELECT json_extract(...) AS …, json_type(...) AS …__t FROM <table>
+   * WHERE …` statement. The DO returns raw rows + per-column metadata; this
+   * method decodes each row locally via `decodeDOProjectedRow`.
+   *
+   * Decoding lives on this side (not inside the DO) because
+   * `GraphTimestampImpl` is a class — its prototype does not survive
+   * workerd's structured-clone boundary — so timestamp rehydration must
+   * happen wherever the rows are consumed by the GraphClient.
+   *
+   * Defensive `_fgFindEdgesProjected` presence check matches the `expand` /
+   * bulk-DML / aggregate pattern: the RPC method is optional on
+   * `FiregraphStub` so external worker code with a hand-rolled stub wrapper
+   * still type-checks. Surface a clear `UNSUPPORTED_OPERATION` rather than
+   * `TypeError: stub._fgFindEdgesProjected is not a function` if the
+   * wrapper hasn't forwarded the method.
+   */
+  async findEdgesProjected(select, filters, options) {
+    const stub = this.stub;
+    if (!stub._fgFindEdgesProjected) {
+      throw new FiregraphError(
+        "findEdgesProjected() not supported by this Durable Object stub. The wrapped stub does not implement `_fgFindEdgesProjected`. If you control the stub wrapper, forward `_fgFindEdgesProjected` to the underlying DO.",
+        "UNSUPPORTED_OPERATION"
+      );
+    }
+    const { rows, columns } = await stub._fgFindEdgesProjected(select, filters, options);
+    return rows.map((row) => decodeDOProjectedRow(row, columns));
+  }
   // --- Cross-scope queries ---
   //
   // `findEdgesGlobal` is deliberately NOT defined on this class. The
@@ -757,11 +1073,32 @@ var FiregraphDO = class extends DurableObject {
     const rows = this.execAll(stmt);
     return rows.map(rowToDORecord);
   }
+  /**
+   * Aggregate query (capability `query.aggregate`). Compiles a single
+   * `SELECT` projecting one column per alias; SQLite handles count, sum,
+   * avg, min, max natively. Empty-set fix-ups (NULL → 0 for sum/min/max,
+   * NaN for avg) happen on the client side in `DORPCBackend.aggregate` so
+   * the wire payload stays a plain row of (alias → number | null).
+   */
+  async _fgAggregate(spec, filters) {
+    const { stmt, aliases } = compileDOAggregate(this.table, spec, filters);
+    const rows = this.execAll(stmt);
+    const row = rows[0] ?? {};
+    const out = {};
+    for (const alias of aliases) {
+      const v = row[alias];
+      if (v === null || v === void 0) out[alias] = null;
+      else if (typeof v === "bigint") out[alias] = Number(v);
+      else if (typeof v === "number") out[alias] = v;
+      else out[alias] = Number(v);
+    }
+    return out;
+  }
   // ---------------------------------------------------------------------------
   // RPC: writes
   // ---------------------------------------------------------------------------
-  async _fgSetDoc(docId, record) {
-    const stmt = compileDOSet(this.table, docId, record, Date.now());
+  async _fgSetDoc(docId, record, mode) {
+    const stmt = compileDOSet(this.table, docId, record, Date.now(), mode);
     this.execRun(stmt);
   }
   async _fgUpdateDoc(docId, update) {
@@ -791,7 +1128,7 @@ var FiregraphDO = class extends DurableObject {
     const statements = ops.map((op) => {
       switch (op.kind) {
         case "set":
-          return compileDOSet(this.table, op.docId, op.record, now);
+          return compileDOSet(this.table, op.docId, op.record, now, op.mode);
         case "update":
           return compileDOUpdate(this.table, op.docId, op.update, now);
         case "delete":
@@ -907,6 +1244,119 @@ var FiregraphDO = class extends DurableObject {
     }
   }
   // ---------------------------------------------------------------------------
+  // RPC: server-side DML (capability `query.dml`)
+  //
+  // Single-statement DELETE/UPDATE WHERE that the SQLite engine handles in
+  // one shot — the cap-less alternative is `_fgBulkRemoveEdges` which fetches
+  // doc IDs first, then deletes them one-by-one inside a transaction. The
+  // DML path skips the round-trip and lets SQLite optimize the WHERE.
+  //
+  // RETURNING "doc_id" gives us an authoritative affected-row count; SQLite
+  // ≥3.35 supports it for both DELETE and UPDATE and DO SQLite is always
+  // recent enough.
+  //
+  // Retry policy: unlike `SqliteBackendImpl.bulkDelete` / `bulkUpdate`, which
+  // wrap a chunked retry/backoff loop around each batch (D1's 1000-statement
+  // cap forces chunking, so a single transient failure shouldn't kill the
+  // whole job), the DO path runs a single un-chunked statement against
+  // `state.storage.sql` synchronously. There's nothing to retry inside the
+  // DO — the engine commits or it doesn't. If a caller wants retry semantics
+  // on the wire, they wrap the `bulkDelete` / `bulkUpdate` call themselves.
+  // ---------------------------------------------------------------------------
+  async _fgBulkDelete(filters, _options) {
+    void _options;
+    if (filters.length === 0) {
+      throw new FiregraphError(
+        "bulkDelete() requires at least one filter when targeting a Durable Object backend. An empty filter list would wipe every row in the DO. To wipe a routed subgraph DO, use `removeNodeCascade` on the parent node or `_fgDestroy` directly on the stub.",
+        "INVALID_ARGUMENT"
+      );
+    }
+    const stmt = compileDOBulkDelete(this.table, filters);
+    return this.execDmlWithReturning(stmt);
+  }
+  async _fgBulkUpdate(filters, patch, _options) {
+    void _options;
+    const stmt = compileDOBulkUpdate(this.table, filters, patch.data, Date.now());
+    return this.execDmlWithReturning(stmt);
+  }
+  // ---------------------------------------------------------------------------
+  // RPC: multi-source fan-out (`query.join`)
+  //
+  // One `SELECT … WHERE "aUid" IN (?, ?, …)` (or `"bUid"` for reverse)
+  // collapses N per-source `findEdges` round trips into one. When the
+  // caller asks for hydration, a second IN-clause statement fetches the
+  // target node rows; the DO does the alignment in JS so the wire payload
+  // is two `DORecordWire[]` arrays instead of a JOIN-shaped row that
+  // would force a custom client-side decoder.
+  // ---------------------------------------------------------------------------
+  async _fgExpand(params) {
+    if (params.sources.length === 0) {
+      return params.hydrate ? { edges: [], targets: [] } : { edges: [] };
+    }
+    const stmt = compileDOExpand(this.table, params);
+    const rows = this.state.storage.sql.exec(stmt.sql, ...stmt.params).toArray();
+    const edges = rows.map((row) => rowToDORecord(row));
+    if (!params.hydrate) {
+      return { edges };
+    }
+    const direction = params.direction ?? "forward";
+    const targetUids = edges.map((e) => direction === "forward" ? e.bUid : e.aUid);
+    const uniqueTargets = [...new Set(targetUids)];
+    if (uniqueTargets.length === 0) {
+      return { edges, targets: [] };
+    }
+    const hydrateStmt = compileDOExpandHydrate(this.table, uniqueTargets);
+    const hydrateRows = this.state.storage.sql.exec(hydrateStmt.sql, ...hydrateStmt.params).toArray();
+    const byUid = /* @__PURE__ */ new Map();
+    for (const row of hydrateRows) {
+      const node = rowToDORecord(row);
+      byUid.set(node.bUid, node);
+    }
+    const targets = targetUids.map((uid) => byUid.get(uid) ?? null);
+    return { edges, targets };
+  }
+  // ---------------------------------------------------------------------------
+  // RPC: server-side projection (`query.select`)
+  //
+  // One `SELECT json_extract(data, '$.f1'), …` returns the projected fields.
+  // The DO leaves decoding to the client because timestamp values need to
+  // rewrap as `GraphTimestampImpl` (a class instance, lost by structured
+  // clone) — instead of inventing per-field timestamp sentinels, we send the
+  // raw rows and the column spec, and let `DORPCBackend.findEdgesProjected`
+  // call `decodeDOProjectedRow` once. The spec is small (≤ ~100 bytes for
+  // a typical projection); structured clone copes happily.
+  // ---------------------------------------------------------------------------
+  async _fgFindEdgesProjected(select, filters, options) {
+    const { stmt, columns } = compileDOFindEdgesProjected(this.table, select, filters, options);
+    const rows = this.state.storage.sql.exec(stmt.sql, ...stmt.params).toArray();
+    return { rows, columns };
+  }
+  /**
+   * Run a DML statement with `RETURNING "doc_id"` so the affected-row count
+   * comes back authoritatively. Errors are caught and surfaced via the
+   * `BulkResult.errors` array (single batch, batchIndex 0) so the wire
+   * payload stays a regular `BulkResult` and the client doesn't have to
+   * differentiate "RPC threw" from "single-statement failure."
+   */
+  execDmlWithReturning(stmt) {
+    const sqlWithReturning = `${stmt.sql} RETURNING "doc_id"`;
+    try {
+      const rows = this.state.storage.sql.exec(sqlWithReturning, ...stmt.params).toArray();
+      return { deleted: rows.length, batches: 1, errors: [] };
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error(String(err));
+      return {
+        deleted: 0,
+        batches: 0,
+        // Like `_fgBulkRemoveEdges`'s catch arm: a single failed statement
+        // is one batch, and the operationCount is "unknown" for a server-
+        // side DML — we report 0 as the lower bound. Callers that care
+        // about partial state should re-query and reconcile.
+        errors: [{ batchIndex: 0, error, operationCount: 0 }]
+      };
+    }
+  }
+  // ---------------------------------------------------------------------------
   // RPC: admin
   // ---------------------------------------------------------------------------
   /**
@@ -938,10 +1388,19 @@ var FiregraphDO = class extends DurableObject {
   }
 };
 export {
+  CapabilityNotSupportedError,
   DORPCBackend,
   FiregraphDO,
+  META_EDGE_TYPE,
+  META_NODE_TYPE,
   buildDOSchemaStatements,
+  createCapabilities,
   createDOClient,
-  createSiblingClient
+  createMergedRegistry,
+  createRegistry,
+  createSiblingClient,
+  deleteField,
+  generateId,
+  intersectCapabilities
 };
 //# sourceMappingURL=index.js.map