@typicalday/firegraph 0.11.2 → 0.12.0

package/README.md

@@ -101,16 +101,19 @@ const g = createGraphClient(db, 'graph', { registry });
 ```typescript
 const tourId = generateId();
 
-// Create or overwrite a node
+// Create or deep-merge a node (sibling keys at any depth survive)
 await g.putNode('tour', tourId, { name: 'Dolomites Classic' });
 
 // Read a node
 const node = await g.getNode(tourId);
 // → StoredGraphRecord | null
 
-// Update fields (partial merge into data)
+// Partial update (deep merge into data)
 await g.updateNode(tourId, { difficulty: 'extreme' });
 
+// Full replace — discards every prior key not in the new payload
+await g.replaceNode('tour', tourId, { name: 'Dolomites — 2026 Edition' });
+
 // Delete a node
 await g.removeNode(tourId);
 
@@ -118,12 +121,19 @@ await g.removeNode(tourId);
 const tours = await g.findNodes({ aType: 'tour' });
 ```
 
+**Write semantics (0.12+):** `putNode`/`putEdge` and `updateNode`/`updateEdge`
+**deep-merge** by default — sibling keys at every nesting depth survive. Use
+`replaceNode`/`replaceEdge` when you want the old "wipe and rewrite" behaviour.
+Arrays are terminal (replaced wholesale, not element-merged); `undefined`
+values are skipped; `null` is preserved verbatim; and the
+[`deleteField()`](#field-deletion) sentinel removes a field at any depth.
+
 ### Edges
 
 ```typescript
 const depId = generateId();
 
-// Create or overwrite an edge
+// Create or deep-merge an edge
 await g.putEdge('tour', tourId, 'hasDeparture', 'departure', depId, { order: 0 });
 
 // Read a specific edge
@@ -133,10 +143,33 @@ const edge = await g.getEdge(tourId, 'hasDeparture', depId);
 // Check existence
 const exists = await g.edgeExists(tourId, 'hasDeparture', depId);
 
+// Partial update (deep merge)
+await g.updateEdge(tourId, 'hasDeparture', depId, { order: 5 });
+
+// Full replace — discards every prior key not in the new payload
+await g.replaceEdge('tour', tourId, 'hasDeparture', 'departure', depId, { order: 5 });
+
 // Delete an edge
 await g.removeEdge(tourId, 'hasDeparture', depId);
 ```
 
+### Field Deletion
+
+The `deleteField()` sentinel removes a field from a stored document. It works
+across every backend (Firestore, SQLite, Cloudflare Durable Objects), so
+calling code stays portable:
+
+```typescript
+import { deleteField } from 'firegraph';
+
+await g.updateNode(tourId, {
+  meta: { deprecatedTag: deleteField() }, // removes meta.deprecatedTag
+});
+```
+
+Equivalent to Firestore's `FieldValue.delete()`, but Workers-safe and
+SQLite-aware.
+
 ### Querying Edges
 
 `findEdges` accepts any combination of filters. When all three identifiers (`aUid`, `axbType`, `bUid`) are provided, it uses a direct document lookup instead of a query scan.
@@ -377,8 +410,8 @@ const tour = await g.getNode(tourId);
 
 - **Version storage**: The `v` field lives on the record envelope (top-level, alongside `aType`, `data`, etc.), not inside `data`. Records without `v` are treated as version 0 (legacy data).
 - **Read path**: When a record is read and its `v` is behind the derived version (`max(toVersion)` from migrations), migrations run sequentially to bring data up to the current version.
-- **Write path**: When writing via `putNode`/`putEdge`, the record is stamped with `v` equal to the derived version automatically.
-- **`updateNode`**: Does not stamp `v` — it is a raw partial update without schema context. The next read re-triggers migration (which is idempotent).
+- **Write path**: When writing via `putNode`/`putEdge` (deep-merge) or `replaceNode`/`replaceEdge` (full overwrite), the record is stamped with `v` equal to the derived version automatically.
+- **`updateNode` / `updateEdge`**: Do not stamp `v` — they are raw partial patches without schema context. The next read re-triggers migration (which is idempotent).
 
 #### Write-Back
 

package/dist/backend-BsR0lnFL.d.ts

@@ -0,0 +1,200 @@
+import { S as StoredGraphRecord, g as QueryFilter, z as QueryOptions, l as GraphReader, m as BulkOptions, C as CascadeResult, F as FindEdgesParams, o as BulkResult } from './types-DxYLy8Ol.js';
+
+/**
+ * Write-plan helper — flattens partial-update payloads into a list of
+ * deep-path operations every backend can execute identically.
+ *
+ * Background: firegraph used to ship two write semantics that quietly
+ * disagreed about depth.
+ *   - `putNode`/`putEdge` did a full document replace.
+ *   - `updateNode`/`updateEdge` did a one-level shallow merge: top-level
+ *     keys were preserved, but nested objects were replaced wholesale.
+ *
+ * Both behaviours dropped sibling keys silently. The 0.12 contract is that
+ * `put*` and `update*` deep-merge by default (sibling keys at any depth
+ * survive); `replace*` is the explicit escape hatch.
+ *
+ * `flattenPatch` walks a partial-update payload and emits one
+ * {@link DataPathOp} per terminal value. Plain objects recurse; arrays,
+ * primitives, Firestore special types, and tagged firegraph-serialization
+ * objects are terminal (replaced as a unit). `undefined` values are
+ * skipped; `null` is preserved as a real `null` write; the
+ * {@link DELETE_FIELD} sentinel marks a field for removal.
+ *
+ * The output is deliberately backend-agnostic. Each backend translates ops
+ * into its native dialect:
+ *   - Firestore: dotted field path → `data.a.b.c` for `update()`.
+ *   - SQLite / DO SQLite: `json_set(data, '$.a.b.c', ?)` /
+ *     `json_remove(data, '$.a.b.c')`.
+ */
+/**
+ * Sentinel returned by {@link deleteField}. Treated by all backends as
+ * "remove this field from the stored document".
+ *
+ * Equivalent to Firestore's `FieldValue.delete()`, but works for SQLite
+ * backends too. Use inside `updateNode`/`updateEdge` payloads.
+ */
+declare const DELETE_FIELD: unique symbol;
+type DeleteSentinel = typeof DELETE_FIELD;
+/**
+ * Returns the firegraph delete sentinel. Place this anywhere in an
+ * `updateNode`/`updateEdge` payload to remove the corresponding field.
+ *
+ * ```ts
+ * await client.updateNode('tour', uid, {
+ *   attrs: { obsoleteFlag: deleteField() },
+ * });
+ * ```
+ */
+declare function deleteField(): DeleteSentinel;
+/** Type guard for the delete sentinel. */
+declare function isDeleteSentinel(value: unknown): value is DeleteSentinel;
+/**
+ * Single terminal write operation produced by {@link flattenPatch}.
+ *
+ * `path` is a non-empty array of plain object keys. `value` is the value to
+ * write; ignored when `delete` is `true`. Arrays / primitives / Firestore
+ * special types appear here as whole terminal values.
+ */
+interface DataPathOp {
+    path: readonly string[];
+    value: unknown;
+    delete: boolean;
+}
+/**
+ * Flatten a partial-update payload into a list of terminal {@link DataPathOp}s.
+ *
+ * Rules:
+ *   - Plain objects (no prototype or `Object.prototype`) recurse — each
+ *     key becomes another path segment.
+ *   - Arrays are terminal: writing `{tags: ['a']}` overwrites the whole
+ *     `tags` array. Element-wise array merging is intentionally NOT
+ *     supported — it's almost never what callers actually want, and
+ *     Firestore `arrayUnion`/`arrayRemove` give precise semantics when
+ *     they are.
+ *   - `undefined` values are skipped (no op generated). Use
+ *     {@link deleteField} if you actually want to remove a field.
+ *   - `null` is preserved verbatim — emits a terminal op with `value: null`.
+ *   - {@link DELETE_FIELD} produces an op with `delete: true`.
+ *   - Firestore special types and tagged serialization payloads are terminal.
+ *   - Class instances are terminal.
+ *
+ * Throws if any object key on the recursion path is unsafe (see
+ * {@link assertSafePath}).
+ */
+declare function flattenPatch(data: Record<string, unknown>): DataPathOp[];
+
+/**
+ * Backend abstraction for firegraph.
+ *
+ * `StorageBackend` is the single interface every storage driver implements.
+ * The Firestore backend wraps `@google-cloud/firestore`; the SQLite backend
+ * (shared by D1 and Durable Object SQLite) uses a parameterized SQL executor.
+ *
+ * `GraphClientImpl` and friends depend only on this interface — they have
+ * no direct knowledge of Firestore or SQLite.
+ */
+
+/**
+ * Per-record write payload — backend-agnostic. Timestamps are not present;
+ * the backend supplies them via `serverTimestamp()` placeholders that it
+ * itself resolves at commit time.
+ */
+interface WritableRecord {
+    aType: string;
+    aUid: string;
+    axbType: string;
+    bType: string;
+    bUid: string;
+    data: Record<string, unknown>;
+    /** Schema version (set by the writer when registry has migrations). */
+    v?: number;
+}
+/**
+ * Write semantics for `setDoc`.
+ *
+ *   - `'merge'` — the new contract (0.12+). Existing fields not mentioned
+ *     in the new data survive; nested objects are recursively merged;
+ *     arrays are replaced as a unit. This is the default for
+ *     `putNode` / `putEdge`.
+ *   - `'replace'` — the document is replaced wholesale, dropping any
+ *     fields not present in the payload. This is the explicit escape
+ *     hatch surfaced as `replaceNode` / `replaceEdge` and used by
+ *     migration write-back.
+ */
+type WriteMode = 'merge' | 'replace';
+/**
+ * Patch shape for `updateDoc`.
+ *
+ *   - `dataOps`: list of deep-path terminal ops produced by
+ *     `flattenPatch()` (one op per leaf — arrays / primitives / Firestore
+ *     special types are terminal). Used by `updateNode` / `updateEdge`.
+ *     Sibling keys at every depth are preserved.
+ *   - `replaceData`: full `data` replacement. Used only by the migration
+ *     write-back path, which has already produced a complete migrated
+ *     document.
+ *   - `v`: optional schema-version stamp.
+ *
+ * `updatedAt` is always set by the backend.
+ */
+interface UpdatePayload {
+    dataOps?: DataPathOp[];
+    replaceData?: Record<string, unknown>;
+    v?: number;
+}
+/**
+ * Read/write transaction adapter. Mirrors Firestore's transaction semantics:
+ * reads are snapshot-consistent; writes are issued inside the transaction
+ * and a rejection from any write aborts the surrounding `runTransaction`.
+ *
+ * Writes return `Promise<void>` so SQL drivers can surface row-level errors
+ * (constraint violations, malformed JSON paths) rather than swallowing them.
+ * Firestore implementations can resolve synchronously since the underlying
+ * `Transaction.set/update/delete` calls are themselves synchronous buffers.
+ */
+interface TransactionBackend {
+    getDoc(docId: string): Promise<StoredGraphRecord | null>;
+    query(filters: QueryFilter[], options?: QueryOptions): Promise<StoredGraphRecord[]>;
+    setDoc(docId: string, record: WritableRecord, mode: WriteMode): Promise<void>;
+    updateDoc(docId: string, update: UpdatePayload): Promise<void>;
+    deleteDoc(docId: string): Promise<void>;
+}
+/**
+ * Atomic multi-write batch.
+ */
+interface BatchBackend {
+    setDoc(docId: string, record: WritableRecord, mode: WriteMode): void;
+    updateDoc(docId: string, update: UpdatePayload): void;
+    deleteDoc(docId: string): void;
+    commit(): Promise<void>;
+}
+/**
+ * The single storage abstraction.
+ *
+ * Each backend instance is scoped to a "graph location" — for Firestore
+ * that's a collection path; for SQLite it's a (table, scopePath) pair.
+ * `subgraph()` returns a child backend bound to a nested location.
+ */
+interface StorageBackend {
+    /** Backend-internal location identifier (collection path or table name). */
+    readonly collectionPath: string;
+    /** Subgraph scope (empty string for root). */
+    readonly scopePath: string;
+    getDoc(docId: string): Promise<StoredGraphRecord | null>;
+    query(filters: QueryFilter[], options?: QueryOptions): Promise<StoredGraphRecord[]>;
+    setDoc(docId: string, record: WritableRecord, mode: WriteMode): Promise<void>;
+    updateDoc(docId: string, update: UpdatePayload): Promise<void>;
+    deleteDoc(docId: string): Promise<void>;
+    runTransaction<T>(fn: (tx: TransactionBackend) => Promise<T>): Promise<T>;
+    createBatch(): BatchBackend;
+    subgraph(parentNodeUid: string, name: string): StorageBackend;
+    removeNodeCascade(uid: string, reader: GraphReader, options?: BulkOptions): Promise<CascadeResult>;
+    bulkRemoveEdges(params: FindEdgesParams, reader: GraphReader, options?: BulkOptions): Promise<BulkResult>;
+    /**
+     * Find edges across all subgraphs sharing a given collection name.
+     * Optional — backends that can't support this should throw a clear error.
+     */
+    findEdgesGlobal?(params: FindEdgesParams, collectionName?: string): Promise<StoredGraphRecord[]>;
+}
+
+export { type BatchBackend as B, DELETE_FIELD as D, type StorageBackend as S, type TransactionBackend as T, type UpdatePayload as U, type WritableRecord as W, type DataPathOp as a, type WriteMode as b, deleteField as d, flattenPatch as f, isDeleteSentinel as i };

package/dist/backend-Ct-fLlkG.d.cts

@@ -0,0 +1,200 @@
+import { S as StoredGraphRecord, g as QueryFilter, z as QueryOptions, l as GraphReader, m as BulkOptions, C as CascadeResult, F as FindEdgesParams, o as BulkResult } from './types-DxYLy8Ol.cjs';
+
+/**
+ * Write-plan helper — flattens partial-update payloads into a list of
+ * deep-path operations every backend can execute identically.
+ *
+ * Background: firegraph used to ship two write semantics that quietly
+ * disagreed about depth.
+ *   - `putNode`/`putEdge` did a full document replace.
+ *   - `updateNode`/`updateEdge` did a one-level shallow merge: top-level
+ *     keys were preserved, but nested objects were replaced wholesale.
+ *
+ * Both behaviours dropped sibling keys silently. The 0.12 contract is that
+ * `put*` and `update*` deep-merge by default (sibling keys at any depth
+ * survive); `replace*` is the explicit escape hatch.
+ *
+ * `flattenPatch` walks a partial-update payload and emits one
+ * {@link DataPathOp} per terminal value. Plain objects recurse; arrays,
+ * primitives, Firestore special types, and tagged firegraph-serialization
+ * objects are terminal (replaced as a unit). `undefined` values are
+ * skipped; `null` is preserved as a real `null` write; the
+ * {@link DELETE_FIELD} sentinel marks a field for removal.
+ *
+ * The output is deliberately backend-agnostic. Each backend translates ops
+ * into its native dialect:
+ *   - Firestore: dotted field path → `data.a.b.c` for `update()`.
+ *   - SQLite / DO SQLite: `json_set(data, '$.a.b.c', ?)` /
+ *     `json_remove(data, '$.a.b.c')`.
+ */
+/**
+ * Sentinel returned by {@link deleteField}. Treated by all backends as
+ * "remove this field from the stored document".
+ *
+ * Equivalent to Firestore's `FieldValue.delete()`, but works for SQLite
+ * backends too. Use inside `updateNode`/`updateEdge` payloads.
+ */
+declare const DELETE_FIELD: unique symbol;
+type DeleteSentinel = typeof DELETE_FIELD;
+/**
+ * Returns the firegraph delete sentinel. Place this anywhere in an
+ * `updateNode`/`updateEdge` payload to remove the corresponding field.
+ *
+ * ```ts
+ * await client.updateNode('tour', uid, {
+ *   attrs: { obsoleteFlag: deleteField() },
+ * });
+ * ```
+ */
+declare function deleteField(): DeleteSentinel;
+/** Type guard for the delete sentinel. */
+declare function isDeleteSentinel(value: unknown): value is DeleteSentinel;
+/**
+ * Single terminal write operation produced by {@link flattenPatch}.
+ *
+ * `path` is a non-empty array of plain object keys. `value` is the value to
+ * write; ignored when `delete` is `true`. Arrays / primitives / Firestore
+ * special types appear here as whole terminal values.
+ */
+interface DataPathOp {
+    path: readonly string[];
+    value: unknown;
+    delete: boolean;
+}
+/**
+ * Flatten a partial-update payload into a list of terminal {@link DataPathOp}s.
+ *
+ * Rules:
+ *   - Plain objects (no prototype or `Object.prototype`) recurse — each
+ *     key becomes another path segment.
+ *   - Arrays are terminal: writing `{tags: ['a']}` overwrites the whole
+ *     `tags` array. Element-wise array merging is intentionally NOT
+ *     supported — it's almost never what callers actually want, and
+ *     Firestore `arrayUnion`/`arrayRemove` give precise semantics when
+ *     they are.
+ *   - `undefined` values are skipped (no op generated). Use
+ *     {@link deleteField} if you actually want to remove a field.
+ *   - `null` is preserved verbatim — emits a terminal op with `value: null`.
+ *   - {@link DELETE_FIELD} produces an op with `delete: true`.
+ *   - Firestore special types and tagged serialization payloads are terminal.
+ *   - Class instances are terminal.
+ *
+ * Throws if any object key on the recursion path is unsafe (see
+ * {@link assertSafePath}).
+ */
+declare function flattenPatch(data: Record<string, unknown>): DataPathOp[];
+
+/**
+ * Backend abstraction for firegraph.
+ *
+ * `StorageBackend` is the single interface every storage driver implements.
+ * The Firestore backend wraps `@google-cloud/firestore`; the SQLite backend
+ * (shared by D1 and Durable Object SQLite) uses a parameterized SQL executor.
+ *
+ * `GraphClientImpl` and friends depend only on this interface — they have
+ * no direct knowledge of Firestore or SQLite.
+ */
+
+/**
+ * Per-record write payload — backend-agnostic. Timestamps are not present;
+ * the backend supplies them via `serverTimestamp()` placeholders that it
+ * itself resolves at commit time.
+ */
+interface WritableRecord {
+    aType: string;
+    aUid: string;
+    axbType: string;
+    bType: string;
+    bUid: string;
+    data: Record<string, unknown>;
+    /** Schema version (set by the writer when registry has migrations). */
+    v?: number;
+}
+/**
+ * Write semantics for `setDoc`.
+ *
+ *   - `'merge'` — the new contract (0.12+). Existing fields not mentioned
+ *     in the new data survive; nested objects are recursively merged;
+ *     arrays are replaced as a unit. This is the default for
+ *     `putNode` / `putEdge`.
+ *   - `'replace'` — the document is replaced wholesale, dropping any
+ *     fields not present in the payload. This is the explicit escape
+ *     hatch surfaced as `replaceNode` / `replaceEdge` and used by
+ *     migration write-back.
+ */
+type WriteMode = 'merge' | 'replace';
+/**
+ * Patch shape for `updateDoc`.
+ *
+ *   - `dataOps`: list of deep-path terminal ops produced by
+ *     `flattenPatch()` (one op per leaf — arrays / primitives / Firestore
+ *     special types are terminal). Used by `updateNode` / `updateEdge`.
+ *     Sibling keys at every depth are preserved.
+ *   - `replaceData`: full `data` replacement. Used only by the migration
+ *     write-back path, which has already produced a complete migrated
+ *     document.
+ *   - `v`: optional schema-version stamp.
+ *
+ * `updatedAt` is always set by the backend.
+ */
+interface UpdatePayload {
+    dataOps?: DataPathOp[];
+    replaceData?: Record<string, unknown>;
+    v?: number;
+}
+/**
+ * Read/write transaction adapter. Mirrors Firestore's transaction semantics:
+ * reads are snapshot-consistent; writes are issued inside the transaction
+ * and a rejection from any write aborts the surrounding `runTransaction`.
+ *
+ * Writes return `Promise<void>` so SQL drivers can surface row-level errors
+ * (constraint violations, malformed JSON paths) rather than swallowing them.
+ * Firestore implementations can resolve synchronously since the underlying
+ * `Transaction.set/update/delete` calls are themselves synchronous buffers.
+ */
+interface TransactionBackend {
+    getDoc(docId: string): Promise<StoredGraphRecord | null>;
+    query(filters: QueryFilter[], options?: QueryOptions): Promise<StoredGraphRecord[]>;
+    setDoc(docId: string, record: WritableRecord, mode: WriteMode): Promise<void>;
+    updateDoc(docId: string, update: UpdatePayload): Promise<void>;
+    deleteDoc(docId: string): Promise<void>;
+}
+/**
+ * Atomic multi-write batch.
+ */
+interface BatchBackend {
+    setDoc(docId: string, record: WritableRecord, mode: WriteMode): void;
+    updateDoc(docId: string, update: UpdatePayload): void;
+    deleteDoc(docId: string): void;
+    commit(): Promise<void>;
+}
+/**
+ * The single storage abstraction.
+ *
+ * Each backend instance is scoped to a "graph location" — for Firestore
+ * that's a collection path; for SQLite it's a (table, scopePath) pair.
+ * `subgraph()` returns a child backend bound to a nested location.
+ */
+interface StorageBackend {
+    /** Backend-internal location identifier (collection path or table name). */
+    readonly collectionPath: string;
+    /** Subgraph scope (empty string for root). */
+    readonly scopePath: string;
+    getDoc(docId: string): Promise<StoredGraphRecord | null>;
+    query(filters: QueryFilter[], options?: QueryOptions): Promise<StoredGraphRecord[]>;
+    setDoc(docId: string, record: WritableRecord, mode: WriteMode): Promise<void>;
+    updateDoc(docId: string, update: UpdatePayload): Promise<void>;
+    deleteDoc(docId: string): Promise<void>;
+    runTransaction<T>(fn: (tx: TransactionBackend) => Promise<T>): Promise<T>;
+    createBatch(): BatchBackend;
+    subgraph(parentNodeUid: string, name: string): StorageBackend;
+    removeNodeCascade(uid: string, reader: GraphReader, options?: BulkOptions): Promise<CascadeResult>;
+    bulkRemoveEdges(params: FindEdgesParams, reader: GraphReader, options?: BulkOptions): Promise<BulkResult>;
+    /**
+     * Find edges across all subgraphs sharing a given collection name.
+     * Optional — backends that can't support this should throw a clear error.
+     */
+    findEdgesGlobal?(params: FindEdgesParams, collectionName?: string): Promise<StoredGraphRecord[]>;
+}
+
+export { type BatchBackend as B, DELETE_FIELD as D, type StorageBackend as S, type TransactionBackend as T, type UpdatePayload as U, type WritableRecord as W, type DataPathOp as a, type WriteMode as b, deleteField as d, flattenPatch as f, isDeleteSentinel as i };

package/dist/backend.cjs

@@ -21,9 +21,13 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var backend_exports = {};
 __export(backend_exports, {
   CrossBackendTransactionError: () => CrossBackendTransactionError,
+  DELETE_FIELD: () => DELETE_FIELD,
   appendStorageScope: () => appendStorageScope,
   createRoutingBackend: () => createRoutingBackend,
+  deleteField: () => deleteField,
+  flattenPatch: () => flattenPatch,
   isAncestorScopeUid: () => isAncestorScopeUid,
+  isDeleteSentinel: () => isDeleteSentinel,
   parseStorageScope: () => parseStorageScope,
   resolveAncestorScope: () => resolveAncestorScope
 });
@@ -104,8 +108,8 @@ var RoutingStorageBackend = class _RoutingStorageBackend {
     return this.base.query(filters, options);
   }
   // --- Pass-through writes ---
-  setDoc(docId, record) {
-    return this.base.setDoc(docId, record);
+  setDoc(docId, record, mode) {
+    return this.base.setDoc(docId, record, mode);
   }
   updateDoc(docId, update) {
     return this.base.updateDoc(docId, update);
@@ -161,6 +165,139 @@ function createRoutingBackend(base, options) {
   return new RoutingStorageBackend(base, options, "", base.scopePath);
 }
 
+// src/internal/serialization-tag.ts
+var SERIALIZATION_TAG = "__firegraph_ser__";
+var KNOWN_TYPES = /* @__PURE__ */ new Set(["Timestamp", "GeoPoint", "VectorValue", "DocumentReference"]);
+function isTaggedValue(value) {
+  if (value === null || typeof value !== "object") return false;
+  const tag = value[SERIALIZATION_TAG];
+  return typeof tag === "string" && KNOWN_TYPES.has(tag);
+}
+
+// src/internal/write-plan.ts
+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 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/scope-path.ts
 function parseStorageScope(scope) {
   if (scope === "") return [];
@@ -213,9 +350,13 @@ function appendStorageScope(parentScope, uid, name) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CrossBackendTransactionError,
+  DELETE_FIELD,
   appendStorageScope,
   createRoutingBackend,
+  deleteField,
+  flattenPatch,
   isAncestorScopeUid,
+  isDeleteSentinel,
   parseStorageScope,
   resolveAncestorScope
 });