@typicalday/firegraph 0.11.2 → 0.12.0

package/dist/cloudflare/index.cjs

@@ -30,6 +30,21 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
+// src/internal/serialization-tag.ts
+function isTaggedValue(value) {
+  if (value === null || typeof value !== "object") return false;
+  const tag = value[SERIALIZATION_TAG];
+  return typeof tag === "string" && KNOWN_TYPES.has(tag);
+}
+var SERIALIZATION_TAG, KNOWN_TYPES;
+var init_serialization_tag = __esm({
+  "src/internal/serialization-tag.ts"() {
+    "use strict";
+    SERIALIZATION_TAG = "__firegraph_ser__";
+    KNOWN_TYPES = /* @__PURE__ */ new Set(["Timestamp", "GeoPoint", "VectorValue", "DocumentReference"]);
+  }
+});
+
 // src/serialization.ts
 var serialization_exports = {};
 __export(serialization_exports, {
@@ -38,11 +53,6 @@ __export(serialization_exports, {
   isTaggedValue: () => isTaggedValue,
   serializeFirestoreTypes: () => serializeFirestoreTypes
 });
-function isTaggedValue(value) {
-  if (value === null || typeof value !== "object") return false;
-  const tag = value[SERIALIZATION_TAG];
-  return typeof tag === "string" && KNOWN_TYPES.has(tag);
-}
 function isTimestamp(value) {
   return value instanceof import_firestore.Timestamp;
 }
@@ -143,13 +153,13 @@ function deserializeValue(value, db) {
   }
   return result;
 }
-var import_firestore, SERIALIZATION_TAG, KNOWN_TYPES, _docRefWarned;
+var import_firestore, _docRefWarned;
 var init_serialization = __esm({
   "src/serialization.ts"() {
     "use strict";
     import_firestore = require("@google-cloud/firestore");
-    SERIALIZATION_TAG = "__firegraph_ser__";
-    KNOWN_TYPES = /* @__PURE__ */ new Set(["Timestamp", "GeoPoint", "VectorValue", "DocumentReference"]);
+    init_serialization_tag();
+    init_serialization_tag();
     _docRefWarned = false;
   }
 });
@@ -159,9 +169,15 @@ var cloudflare_exports = {};
 __export(cloudflare_exports, {
   DORPCBackend: () => DORPCBackend,
   FiregraphDO: () => FiregraphDO,
+  META_EDGE_TYPE: () => META_EDGE_TYPE,
+  META_NODE_TYPE: () => META_NODE_TYPE,
   buildDOSchemaStatements: () => buildDOSchemaStatements,
   createDOClient: () => createDOClient,
-  createSiblingClient: () => createSiblingClient
+  createMergedRegistry: () => createMergedRegistry,
+  createRegistry: () => createRegistry,
+  createSiblingClient: () => createSiblingClient,
+  deleteField: () => deleteField,
+  generateId: () => generateId
 });
 module.exports = __toCommonJS(cloudflare_exports);
 
@@ -234,6 +250,296 @@ var BUILTIN_FIELDS = /* @__PURE__ */ new Set([
 ]);
 var SHARD_SEPARATOR = ":";
 
+// src/internal/sqlite-data-ops.ts
+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;
+}
+var JSON_PATH_KEY_RE = /^[A-Za-z_][A-Za-z0-9_-]*$/;
+function validateJsonPathKey(key, backendLabel) {
+  if (key.length === 0) {
+    throw new FiregraphError(
+      `${backendLabel}: empty JSON path component is not allowed`,
+      "INVALID_QUERY"
+    );
+  }
+  if (!JSON_PATH_KEY_RE.test(key)) {
+    throw new FiregraphError(
+      `${backendLabel}: data field path component "${key}" is not a safe JSON-path identifier. Allowed pattern: /^[A-Za-z_][A-Za-z0-9_-]*$/. Use replaceNode/replaceEdge (full-data overwrite) for keys with reserved characters (whitespace, dots, brackets, quotes, etc.).`,
+      "INVALID_QUERY"
+    );
+  }
+}
+function jsonBind(value, backendLabel) {
+  if (value === void 0) return "null";
+  if (value !== null && typeof value === "object") {
+    const firestoreType = isFirestoreSpecialType(value);
+    if (firestoreType) {
+      throw new FiregraphError(
+        `${backendLabel} cannot persist a Firestore ${firestoreType} value. Convert to a primitive before writing (e.g. \`ts.toMillis()\` for Timestamp).`,
+        "INVALID_ARGUMENT"
+      );
+    }
+  }
+  return JSON.stringify(value);
+}
+function compileDataOpsExpr(ops, base, params, backendLabel) {
+  if (ops.length === 0) return null;
+  const deletes = [];
+  const sets = [];
+  for (const op of ops) (op.delete ? deletes : sets).push(op);
+  let expr = base;
+  if (deletes.length > 0) {
+    const placeholders = deletes.map(() => "?").join(", ");
+    expr = `json_remove(${expr}, ${placeholders})`;
+    for (const op of deletes) {
+      for (const seg of op.path) validateJsonPathKey(seg, backendLabel);
+      params.push(`$.${op.path.join(".")}`);
+    }
+  }
+  if (sets.length > 0) {
+    const pieces = sets.map(() => "?, json(?)").join(", ");
+    expr = `json_set(${expr}, ${pieces})`;
+    for (const op of sets) {
+      for (const seg of op.path) validateJsonPathKey(seg, backendLabel);
+      params.push(`$.${op.path.join(".")}`);
+      params.push(jsonBind(op.value, backendLabel));
+    }
+  }
+  return expr;
+}
+
+// src/internal/sqlite-payload-guard.ts
+init_serialization_tag();
+
+// src/internal/write-plan.ts
+init_serialization_tag();
+var DELETE_FIELD = /* @__PURE__ */ Symbol.for("firegraph.deleteField");
+function deleteField() {
+  return DELETE_FIELD;
+}
+function isDeleteSentinel(value) {
+  return value === DELETE_FIELD;
+}
+var FIRESTORE_TERMINAL_CTOR = /* @__PURE__ */ new Set([
+  "Timestamp",
+  "GeoPoint",
+  "VectorValue",
+  "DocumentReference",
+  "FieldValue",
+  "NumericIncrementTransform",
+  "ArrayUnionTransform",
+  "ArrayRemoveTransform",
+  "ServerTimestampTransform",
+  "DeleteTransform"
+]);
+function isTerminalValue(value) {
+  if (value === null) return true;
+  const t = typeof value;
+  if (t !== "object") return true;
+  if (Array.isArray(value)) return true;
+  if (isTaggedValue(value)) return true;
+  const proto = Object.getPrototypeOf(value);
+  if (proto === null || proto === Object.prototype) return false;
+  const ctor = value.constructor;
+  if (ctor && typeof ctor.name === "string" && FIRESTORE_TERMINAL_CTOR.has(ctor.name)) return true;
+  return true;
+}
+var SAFE_KEY_RE = /^[A-Za-z_][A-Za-z0-9_-]*$/;
+function assertUpdatePayloadExclusive(update) {
+  if (update.replaceData !== void 0 && update.dataOps !== void 0) {
+    throw new Error(
+      "firegraph: UpdatePayload cannot specify both `replaceData` and `dataOps`. Use one or the other \u2014 `replaceData` is the migration-write-back form, `dataOps` is the standard partial-update form."
+    );
+  }
+}
+function assertNoDeleteSentinels(data, callerLabel) {
+  walkForDeleteSentinels(data, [], { kind: "root" }, ({ path }) => {
+    const where = path.length === 0 ? "<root>" : path.map((p) => JSON.stringify(p)).join(" > ");
+    throw new Error(
+      `firegraph: ${callerLabel} payload contains a deleteField() sentinel at ${where}. deleteField() is only valid inside updateNode/updateEdge \u2014 full-data writes (put*, replace*) cannot delete individual fields. Use updateNode with a deleteField() value, or omit the field from the replace payload.`
+    );
+  });
+}
+function walkForDeleteSentinels(node, path, parent, visit) {
+  if (node === null || node === void 0) return;
+  if (isDeleteSentinel(node)) {
+    visit({ path, parent });
+    return;
+  }
+  if (typeof node !== "object") return;
+  if (isTaggedValue(node)) return;
+  if (Array.isArray(node)) {
+    for (let i = 0; i < node.length; i++) {
+      walkForDeleteSentinels(node[i], [...path, String(i)], { kind: "array", index: i }, visit);
+    }
+    return;
+  }
+  const proto = Object.getPrototypeOf(node);
+  if (proto !== null && proto !== Object.prototype) return;
+  const obj = node;
+  for (const key of Object.keys(obj)) {
+    walkForDeleteSentinels(obj[key], [...path, key], { kind: "object" }, visit);
+  }
+}
+function assertSafePath(path) {
+  for (const seg of path) {
+    if (!SAFE_KEY_RE.test(seg)) {
+      throw new Error(
+        `firegraph: unsafe object key ${JSON.stringify(seg)} at path ${path.map((p) => JSON.stringify(p)).join(" > ")}. Keys used inside update payloads must match /^[A-Za-z_][A-Za-z0-9_-]*$/ so they can be embedded safely in SQLite JSON paths.`
+      );
+    }
+  }
+}
+function flattenPatch(data) {
+  const ops = [];
+  walk(data, [], ops);
+  return ops;
+}
+function assertNoDeleteSentinelsInArrayValue(arr, arrayPath) {
+  walkForDeleteSentinels(arr, arrayPath, { kind: "root" }, ({ parent }) => {
+    const arrayPathStr = arrayPath.length === 0 ? "<root>" : arrayPath.map((p) => JSON.stringify(p)).join(" > ");
+    if (parent.kind === "array") {
+      throw new Error(
+        `firegraph: deleteField() sentinel at index ${parent.index} inside an array at path ${arrayPathStr}. Arrays are terminal in update payloads (replaced as a unit), so the sentinel would be silently dropped by JSON serialization. To remove the field entirely, pass deleteField() in place of the whole array.`
+      );
+    }
+    throw new Error(
+      `firegraph: deleteField() sentinel inside an array element at path ${arrayPathStr}. Arrays are terminal in update payloads \u2014 the sentinel would be silently dropped by JSON serialization.`
+    );
+  });
+}
+function walk(node, path, out) {
+  if (node === void 0) return;
+  if (isDeleteSentinel(node)) {
+    if (path.length === 0) {
+      throw new Error("firegraph: deleteField() cannot be the entire update payload.");
+    }
+    assertSafePath(path);
+    out.push({ path: [...path], value: void 0, delete: true });
+    return;
+  }
+  if (isTerminalValue(node)) {
+    if (path.length === 0) {
+      throw new Error(
+        "firegraph: update payload must be a plain object. Got " + (node === null ? "null" : Array.isArray(node) ? "array" : typeof node) + "."
+      );
+    }
+    if (Array.isArray(node)) {
+      assertNoDeleteSentinelsInArrayValue(node, path);
+    }
+    assertSafePath(path);
+    out.push({ path: [...path], value: node, delete: false });
+    return;
+  }
+  const obj = node;
+  const keys = Object.keys(obj);
+  if (keys.length === 0) {
+    if (path.length > 0) {
+      assertSafePath(path);
+      out.push({ path: [...path], value: {}, delete: false });
+    }
+    return;
+  }
+  for (const key of keys) {
+    if (key === SERIALIZATION_TAG) {
+      const where = path.length === 0 ? "<root>" : path.map((p) => JSON.stringify(p)).join(" > ");
+      throw new Error(
+        `firegraph: update payload contains a literal \`${SERIALIZATION_TAG}\` key at ${where}. That key is reserved for firegraph's serialization envelope and cannot appear on a plain object in user data. Use a different field name, or pass a recognized tagged value through replaceNode/replaceEdge instead.`
+      );
+    }
+    walk(obj[key], [...path, key], out);
+  }
+}
+
+// src/internal/sqlite-payload-guard.ts
+var FIRESTORE_TYPE_NAMES2 = /* @__PURE__ */ new Set([
+  "Timestamp",
+  "GeoPoint",
+  "VectorValue",
+  "DocumentReference",
+  "FieldValue"
+]);
+function assertJsonSafePayload(data, label) {
+  walk2(data, [], label);
+}
+function walk2(node, path, label) {
+  if (node === null || node === void 0) return;
+  if (isDeleteSentinel(node)) {
+    throw new FiregraphError(
+      `${label} backend cannot persist a deleteField() sentinel inside a full-data payload (replaceNode/replaceEdge or first-insert). The sentinel is only valid inside an updateNode/updateEdge dataOps patch. Path: ${formatPath(path)}.`,
+      "INVALID_ARGUMENT"
+    );
+  }
+  const t = typeof node;
+  if (t === "symbol" || t === "function") {
+    throw new FiregraphError(
+      `${label} backend cannot persist a value of type ${t}. JSON.stringify drops it silently. Path: ${formatPath(path)}.`,
+      "INVALID_ARGUMENT"
+    );
+  }
+  if (t === "bigint") {
+    throw new FiregraphError(
+      `${label} backend cannot persist a value of type bigint. JSON.stringify cannot serialize this type (throws TypeError). Path: ${formatPath(path)}.`,
+      "INVALID_ARGUMENT"
+    );
+  }
+  if (t !== "object") return;
+  if (Array.isArray(node)) {
+    for (let i = 0; i < node.length; i++) {
+      walk2(node[i], [...path, String(i)], label);
+    }
+    return;
+  }
+  const obj = node;
+  if (Object.prototype.hasOwnProperty.call(obj, SERIALIZATION_TAG)) {
+    const tagValue = obj[SERIALIZATION_TAG];
+    throw new FiregraphError(
+      `${label} backend cannot persist an object with a \`${SERIALIZATION_TAG}\` key (value: ${formatTagValue(tagValue)}). Recognised tags are valid only on the Firestore backend (migration-sandbox output); a literal \`${SERIALIZATION_TAG}\` field in user data is reserved and not allowed. Path: ${formatPath(path)}.`,
+      "INVALID_ARGUMENT"
+    );
+  }
+  const proto = Object.getPrototypeOf(node);
+  if (proto !== null && proto !== Object.prototype) {
+    const ctor = node.constructor;
+    const ctorName = ctor && typeof ctor.name === "string" ? ctor.name : "<anonymous>";
+    if (FIRESTORE_TYPE_NAMES2.has(ctorName)) {
+      throw new FiregraphError(
+        `${label} backend cannot persist a Firestore ${ctorName} value. Convert to a primitive before writing (e.g. \`ts.toMillis()\` for Timestamp, \`{lat,lng}\` for GeoPoint). Path: ${formatPath(path)}.`,
+        "INVALID_ARGUMENT"
+      );
+    }
+    if (node instanceof Date) return;
+    throw new FiregraphError(
+      `${label} backend cannot persist a class instance of type ${ctorName}. Only plain objects, arrays, and primitives round-trip safely through JSON storage. Path: ${formatPath(path)}.`,
+      "INVALID_ARGUMENT"
+    );
+  }
+  for (const key of Object.keys(obj)) {
+    walk2(obj[key], [...path, key], label);
+  }
+}
+function formatPath(path) {
+  return path.length === 0 ? "<root>" : path.map((p) => JSON.stringify(p)).join(" > ");
+}
+function formatTagValue(value) {
+  if (value === null) return "null";
+  if (value === void 0) return "undefined";
+  if (typeof value === "string") return JSON.stringify(value);
+  if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") {
+    return String(value);
+  }
+  return typeof value;
+}
+
 // src/timestamp.ts
 var GraphTimestampImpl = class _GraphTimestampImpl {
   constructor(seconds, nanoseconds) {
@@ -273,7 +579,7 @@ var DEFAULT_CORE_INDEXES = Object.freeze([
 
 // 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_-]*$/;
+var JSON_PATH_KEY_RE2 = /^[A-Za-z_][A-Za-z0-9_-]*$/;
 function quoteIdent(name) {
   if (!IDENT_RE.test(name)) {
     throw new FiregraphError(
@@ -321,7 +627,7 @@ function compileFieldExpr(path, fieldToColumn) {
     const suffix = path.slice(5);
     const parts = suffix.split(".");
     for (const part of parts) {
-      if (!JSON_PATH_KEY_RE.test(part)) {
+      if (!JSON_PATH_KEY_RE2.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"
@@ -416,6 +722,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) {
@@ -424,7 +732,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}')` };
   }
@@ -436,18 +744,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") {
@@ -466,21 +762,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) {
@@ -567,11 +848,27 @@ function compileDOSelectByDocId(table, docId) {
     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 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,
@@ -583,22 +880,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) {
@@ -694,8 +1013,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 });
@@ -745,8 +1064,8 @@ var DORPCBackend = class _DORPCBackend {
     return wires.map(hydrateDORecord);
   }
   // --- 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);
@@ -875,6 +1194,19 @@ var GraphBatchImpl = class {
     this.scopePath = scopePath;
   }
   async putNode(aType, uid, data) {
+    this.writeNode(aType, uid, data, "merge");
+  }
+  async putEdge(aType, aUid, axbType, bType, bUid, data) {
+    this.writeEdge(aType, aUid, axbType, bType, bUid, data, "merge");
+  }
+  async replaceNode(aType, uid, data) {
+    this.writeNode(aType, uid, data, "replace");
+  }
+  async replaceEdge(aType, aUid, axbType, bType, bUid, data) {
+    this.writeEdge(aType, aUid, axbType, bType, bUid, data, "replace");
+  }
+  writeNode(aType, uid, data, mode) {
+    assertNoDeleteSentinels(data, mode === "replace" ? "replaceNode" : "putNode");
     if (this.registry) {
       this.registry.validate(aType, NODE_RELATION, aType, data, this.scopePath);
     }
@@ -886,9 +1218,10 @@ var GraphBatchImpl = class {
         record.v = entry.schemaVersion;
       }
     }
-    this.backend.setDoc(docId, record);
+    this.backend.setDoc(docId, record, mode);
   }
-  async putEdge(aType, aUid, axbType, bType, bUid, data) {
+  writeEdge(aType, aUid, axbType, bType, bUid, data, mode) {
+    assertNoDeleteSentinels(data, mode === "replace" ? "replaceEdge" : "putEdge");
     if (this.registry) {
       this.registry.validate(aType, axbType, bType, data, this.scopePath);
     }
@@ -900,11 +1233,15 @@ var GraphBatchImpl = class {
         record.v = entry.schemaVersion;
       }
     }
-    this.backend.setDoc(docId, record);
+    this.backend.setDoc(docId, record, mode);
   }
   async updateNode(uid, data) {
     const docId = computeNodeDocId(uid);
-    this.backend.updateDoc(docId, { dataFields: data });
+    this.backend.updateDoc(docId, { dataOps: flattenPatch(data) });
+  }
+  async updateEdge(aUid, axbType, bUid, data) {
+    const docId = computeEdgeDocId(aUid, axbType, bUid);
+    this.backend.updateDoc(docId, { dataOps: flattenPatch(data) });
   }
   async removeNode(uid) {
     const docId = computeNodeDocId(uid);
@@ -1853,6 +2190,19 @@ var GraphTransactionImpl = class {
     return results.map((r) => r.record);
   }
   async putNode(aType, uid, data) {
+    await this.writeNode(aType, uid, data, "merge");
+  }
+  async putEdge(aType, aUid, axbType, bType, bUid, data) {
+    await this.writeEdge(aType, aUid, axbType, bType, bUid, data, "merge");
+  }
+  async replaceNode(aType, uid, data) {
+    await this.writeNode(aType, uid, data, "replace");
+  }
+  async replaceEdge(aType, aUid, axbType, bType, bUid, data) {
+    await this.writeEdge(aType, aUid, axbType, bType, bUid, data, "replace");
+  }
+  async writeNode(aType, uid, data, mode) {
+    assertNoDeleteSentinels(data, mode === "replace" ? "replaceNode" : "putNode");
     if (this.registry) {
       this.registry.validate(aType, NODE_RELATION, aType, data, this.scopePath);
     }
@@ -1864,9 +2214,10 @@ var GraphTransactionImpl = class {
         record.v = entry.schemaVersion;
       }
     }
-    await this.backend.setDoc(docId, record);
+    await this.backend.setDoc(docId, record, mode);
   }
-  async putEdge(aType, aUid, axbType, bType, bUid, data) {
+  async writeEdge(aType, aUid, axbType, bType, bUid, data, mode) {
+    assertNoDeleteSentinels(data, mode === "replace" ? "replaceEdge" : "putEdge");
     if (this.registry) {
       this.registry.validate(aType, axbType, bType, data, this.scopePath);
     }
@@ -1878,11 +2229,15 @@ var GraphTransactionImpl = class {
         record.v = entry.schemaVersion;
       }
     }
-    await this.backend.setDoc(docId, record);
+    await this.backend.setDoc(docId, record, mode);
   }
   async updateNode(uid, data) {
     const docId = computeNodeDocId(uid);
-    await this.backend.updateDoc(docId, { dataFields: data });
+    await this.backend.updateDoc(docId, { dataOps: flattenPatch(data) });
+  }
+  async updateEdge(aUid, axbType, bUid, data) {
+    const docId = computeEdgeDocId(aUid, axbType, bUid);
+    await this.backend.updateDoc(docId, { dataOps: flattenPatch(data) });
   }
   async removeNode(uid) {
     const docId = computeNodeDocId(uid);
@@ -2081,6 +2436,19 @@ var GraphClientImpl = class _GraphClientImpl {
   // GraphWriter
   // ---------------------------------------------------------------------------
   async putNode(aType, uid, data) {
+    await this.writeNode(aType, uid, data, "merge");
+  }
+  async putEdge(aType, aUid, axbType, bType, bUid, data) {
+    await this.writeEdge(aType, aUid, axbType, bType, bUid, data, "merge");
+  }
+  async replaceNode(aType, uid, data) {
+    await this.writeNode(aType, uid, data, "replace");
+  }
+  async replaceEdge(aType, aUid, axbType, bType, bUid, data) {
+    await this.writeEdge(aType, aUid, axbType, bType, bUid, data, "replace");
+  }
+  async writeNode(aType, uid, data, mode) {
+    assertNoDeleteSentinels(data, mode === "replace" ? "replaceNode" : "putNode");
     const registry = this.getRegistryForType(aType);
     if (registry) {
       registry.validate(aType, NODE_RELATION, aType, data, this.backend.scopePath);
@@ -2094,9 +2462,10 @@ var GraphClientImpl = class _GraphClientImpl {
         record.v = entry.schemaVersion;
       }
     }
-    await backend.setDoc(docId, record);
+    await backend.setDoc(docId, record, mode);
   }
-  async putEdge(aType, aUid, axbType, bType, bUid, data) {
+  async writeEdge(aType, aUid, axbType, bType, bUid, data, mode) {
+    assertNoDeleteSentinels(data, mode === "replace" ? "replaceEdge" : "putEdge");
     const registry = this.getRegistryForType(aType);
     if (registry) {
       registry.validate(aType, axbType, bType, data, this.backend.scopePath);
@@ -2110,11 +2479,15 @@ var GraphClientImpl = class _GraphClientImpl {
         record.v = entry.schemaVersion;
       }
     }
-    await backend.setDoc(docId, record);
+    await backend.setDoc(docId, record, mode);
   }
   async updateNode(uid, data) {
     const docId = computeNodeDocId(uid);
-    await this.backend.updateDoc(docId, { dataFields: data });
+    await this.backend.updateDoc(docId, { dataOps: flattenPatch(data) });
+  }
+  async updateEdge(aUid, axbType, bUid, data) {
+    const docId = computeEdgeDocId(aUid, axbType, bUid);
+    await this.backend.updateDoc(docId, { dataOps: flattenPatch(data) });
   }
   async removeNode(uid) {
     const docId = computeNodeDocId(uid);
@@ -2495,8 +2868,8 @@ var FiregraphDO = class extends import_cloudflare_workers.DurableObject {
   // ---------------------------------------------------------------------------
   // 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) {
@@ -2526,7 +2899,7 @@ var FiregraphDO = class extends import_cloudflare_workers.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":
@@ -2672,12 +3045,24 @@ var FiregraphDO = class extends import_cloudflare_workers.DurableObject {
     this.state.storage.sql.exec(stmt.sql, ...stmt.params).toArray();
   }
 };
+
+// src/id.ts
+var import_nanoid = require("nanoid");
+function generateId() {
+  return (0, import_nanoid.nanoid)();
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   DORPCBackend,
   FiregraphDO,
+  META_EDGE_TYPE,
+  META_NODE_TYPE,
   buildDOSchemaStatements,
   createDOClient,
-  createSiblingClient
+  createMergedRegistry,
+  createRegistry,
+  createSiblingClient,
+  deleteField,
+  generateId
 });
 //# sourceMappingURL=index.cjs.map