@typicalday/firegraph 0.11.2 → 0.12.0

package/dist/backend.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/backend.ts","../src/errors.ts","../src/internal/routing-backend.ts","../src/scope-path.ts"],"sourcesContent":["/**\n * Public backend surface — the stable set of types and primitives for code\n * that wants to wrap, substitute, or compose `StorageBackend`s.\n *\n * Most firegraph users only touch `GraphClient`; this module is for the\n * narrower set of users who write their own storage drivers (e.g. an RPC\n * executor that tunnels a `StorageBackend` into a Durable Object) or who\n * need to route `subgraph()` calls across multiple physical backends\n * (see `createRoutingBackend`).\n *\n * Entry point: `firegraph/backend`.\n */\n\nexport { CrossBackendTransactionError } from './errors.js';\nexport type {\n  BatchBackend,\n  StorageBackend,\n  TransactionBackend,\n  UpdatePayload,\n  WritableRecord,\n} from './internal/backend.js';\nexport type { RoutingBackendOptions, RoutingContext } from './internal/routing-backend.js';\nexport { createRoutingBackend } from './internal/routing-backend.js';\nexport type { StorageScopeSegment } from './scope-path.js';\nexport {\n  appendStorageScope,\n  isAncestorScopeUid,\n  parseStorageScope,\n  resolveAncestorScope,\n} from './scope-path.js';\n","export class FiregraphError extends Error {\n  constructor(\n    message: string,\n    public readonly code: string,\n  ) {\n    super(message);\n    this.name = 'FiregraphError';\n  }\n}\n\nexport class NodeNotFoundError extends FiregraphError {\n  constructor(uid: string) {\n    super(`Node not found: ${uid}`, 'NODE_NOT_FOUND');\n    this.name = 'NodeNotFoundError';\n  }\n}\n\nexport class EdgeNotFoundError extends FiregraphError {\n  constructor(aUid: string, axbType: string, bUid: string) {\n    super(`Edge not found: ${aUid} -[${axbType}]-> ${bUid}`, 'EDGE_NOT_FOUND');\n    this.name = 'EdgeNotFoundError';\n  }\n}\n\nexport class ValidationError extends FiregraphError {\n  constructor(\n    message: string,\n    public readonly details?: unknown,\n  ) {\n    super(message, 'VALIDATION_ERROR');\n    this.name = 'ValidationError';\n  }\n}\n\nexport class RegistryViolationError extends FiregraphError {\n  constructor(aType: string, axbType: string, bType: string) {\n    super(`Unregistered triple: (${aType}) -[${axbType}]-> (${bType})`, 'REGISTRY_VIOLATION');\n    this.name = 'RegistryViolationError';\n  }\n}\n\nexport class InvalidQueryError extends FiregraphError {\n  constructor(message: string) {\n    super(message, 'INVALID_QUERY');\n    this.name = 'InvalidQueryError';\n  }\n}\n\nexport class TraversalError extends FiregraphError {\n  constructor(message: string) {\n    super(message, 'TRAVERSAL_ERROR');\n    this.name = 'TraversalError';\n  }\n}\n\nexport class DynamicRegistryError extends FiregraphError {\n  constructor(message: string) {\n    super(message, 'DYNAMIC_REGISTRY_ERROR');\n    this.name = 'DynamicRegistryError';\n  }\n}\n\nexport class QuerySafetyError extends FiregraphError {\n  constructor(message: string) {\n    super(message, 'QUERY_SAFETY');\n    this.name = 'QuerySafetyError';\n  }\n}\n\nexport class RegistryScopeError extends FiregraphError {\n  constructor(\n    aType: string,\n    axbType: string,\n    bType: string,\n    scopePath: string,\n    allowedIn: string[],\n  ) {\n    super(\n      `Type (${aType}) -[${axbType}]-> (${bType}) is not allowed at scope \"${scopePath || 'root'}\". ` +\n        `Allowed in: [${allowedIn.join(', ')}]`,\n      'REGISTRY_SCOPE',\n    );\n    this.name = 'RegistryScopeError';\n  }\n}\n\nexport class MigrationError extends FiregraphError {\n  constructor(message: string) {\n    super(message, 'MIGRATION_ERROR');\n    this.name = 'MigrationError';\n  }\n}\n\n/**\n * Thrown when a caller tries to perform an operation that would require\n * atomicity across two physical storage backends — e.g. opening a routed\n * subgraph client from inside a transaction callback. Cross-backend\n * atomicity cannot be honoured by real-world storage engines (Firestore,\n * SQLite drivers over D1/DO/better-sqlite3, etc.), so firegraph surfaces\n * this as a typed error instead of silently confining the write to the\n * base backend.\n *\n * Normally `TransactionBackend` and `BatchBackend` don't expose `subgraph()`\n * at the type level, so this error is unreachable through well-typed code.\n * It exists as a public catchable type for app code that needs to tolerate\n * this case deliberately (e.g. dynamic code paths that bypass the type\n * system) and as future-proofing if the interface ever grows a way to\n * request a sub-scope inside a transaction.\n */\nexport class CrossBackendTransactionError extends FiregraphError {\n  constructor(message: string) {\n    super(message, 'CROSS_BACKEND_TRANSACTION');\n    this.name = 'CrossBackendTransactionError';\n  }\n}\n","/**\n * Routing `StorageBackend` wrapper.\n *\n * `createRoutingBackend(base, { route })` returns a `StorageBackend` that\n * behaves identically to `base` except for `subgraph(parentUid, name)`:\n * each such call consults the caller-supplied `route` function, and if it\n * returns a non-null `StorageBackend`, that backend is used for the child\n * scope.\n *\n * This is the single seam firegraph ships for splitting a logical graph\n * across multiple physical storage backends — e.g. fanning particular\n * subgraph names out to their own Durable Objects to stay under the 10 GB\n * per-DO limit. The routing policy itself, the RPC protocol, and any\n * live-scope index are left to the caller; firegraph only owns the\n * composition primitive and the invariants that come with it.\n *\n * ## Contract — nested routing\n *\n * Whether `route()` returns a routed backend OR `null` (pass-through), the\n * child returned by `subgraph()` is **always** itself wrapped by the same\n * router. Without that self-wrap, a call chain like\n *\n * ```ts\n * router.subgraph(A, 'memories').subgraph(B, 'context')\n * ```\n *\n * would route the first hop correctly but bypass the router on the second\n * hop (since the routed backend's own `.subgraph()` doesn't know about the\n * caller's policy). Keeping routing active through grandchildren is the\n * load-bearing behaviour; `'continues routing on grandchildren …'` in the\n * unit tests locks it in.\n *\n * ## Contract — `route` is synchronous\n *\n * `.subgraph()` is synchronous in firegraph's public API. Making the\n * routing callback async would require rippling Promises through every\n * client-factory call site. Consequence: `route` can only consult data it\n * already has in hand (DO bindings, naming rules, in-memory caches). If\n * you need \"does this DO exist?\" checks, do them lazily — the first read\n * against the returned backend will surface the failure naturally.\n *\n * ## Contract — cross-backend atomicity is not silently degraded\n *\n * The wrapper's `runTransaction` and `createBatch` delegate to `base` —\n * they run entirely on the base backend. `TransactionBackend` and\n * `BatchBackend` deliberately have no `subgraph()` method, so user code\n * physically cannot open a routed child from inside a transaction\n * callback. Any attempt to bypass that (via `as any` / unchecked casts)\n * should surface as `CrossBackendTransactionError` so app code can catch\n * it cleanly — the error type is part of the public surface.\n *\n * ## Contract — `findEdgesGlobal` is base-scope only\n *\n * When delegated, `findEdgesGlobal` runs against the base backend only.\n * It does **not** fan out to routed children — firegraph has no\n * enumeration index for which routed backends exist. Callers who need\n * cross-shard collection-group queries must maintain their own scope\n * directory and query it directly. This keeps the common case (local\n * analytics inside one DO) fast.\n */\n\nimport { FiregraphError } from '../errors.js';\nimport type {\n  BulkOptions,\n  BulkResult,\n  CascadeResult,\n  FindEdgesParams,\n  GraphReader,\n  QueryFilter,\n  QueryOptions,\n  StoredGraphRecord,\n} from '../types.js';\nimport type {\n  BatchBackend,\n  StorageBackend,\n  TransactionBackend,\n  UpdatePayload,\n  WritableRecord,\n} from './backend.js';\n\n/**\n * Context passed to a routing callback when `subgraph(parentUid, name)` is\n * called on a routed backend. All four strings describe the *child* scope\n * the caller is requesting, so the router can key its decision off whichever\n * representation is most convenient:\n *\n *   - `parentUid` / `subgraphName` — the arguments just passed to `subgraph()`.\n *   - `scopePath` — logical, names-only chain (`'memories'`, `'memories/context'`).\n *     This is what `allowedIn` patterns match against.\n *   - `storageScope` — the materialized-path form (`'A/memories'`,\n *     `'A/memories/B/context'`), suitable for use as a DO name or shard key\n *     because it's globally unique within a root graph.\n */\nexport interface RoutingContext {\n  parentUid: string;\n  subgraphName: string;\n  scopePath: string;\n  storageScope: string;\n}\n\nexport interface RoutingBackendOptions {\n  /**\n   * Decide whether a `subgraph(parentUid, name)` call should route to a\n   * different backend. Return the target backend to route; return `null`\n   * (or `undefined`) to fall through to the wrapped base backend.\n   *\n   * The returned backend is itself wrapped by the same router so that\n   * nested `.subgraph()` calls on the returned child continue to be\n   * consulted.\n   */\n  route: (ctx: RoutingContext) => StorageBackend | null | undefined;\n}\n\nfunction assertValidSubgraphArgs(parentNodeUid: string, name: string): void {\n  if (!parentNodeUid || parentNodeUid.includes('/')) {\n    throw new FiregraphError(\n      `Invalid parentNodeUid for subgraph: \"${parentNodeUid}\". ` +\n        'Must be a non-empty string without \"/\".',\n      'INVALID_SUBGRAPH',\n    );\n  }\n  if (!name || name.includes('/')) {\n    throw new FiregraphError(\n      `Subgraph name must not contain \"/\" and must be non-empty: got \"${name}\". ` +\n        'Use chained .subgraph() calls for nested subgraphs.',\n      'INVALID_SUBGRAPH',\n    );\n  }\n}\n\nclass RoutingStorageBackend implements StorageBackend {\n  readonly collectionPath: string;\n  /**\n   * Logical (names-only) scope path for *this* wrapper. Tracked\n   * independently of `base.scopePath` because a routed backend returned by\n   * `options.route()` typically represents its own physical root and has\n   * no knowledge of the caller's logical chain. The wrapper is the\n   * authoritative source of the logical scope for routing decisions and\n   * for satisfying the `StorageBackend.scopePath` contract surfaced to\n   * client code.\n   */\n  readonly scopePath: string;\n  /**\n   * Materialized-path form of `scopePath` — interleaved `<uid>/<name>`\n   * pairs. Not a property on the underlying `StorageBackend` interface\n   * (Firestore doesn't produce one), so we track it ourselves from\n   * `.subgraph()` arguments. Root routers start with `''`.\n   */\n  private readonly storageScope: string;\n  /**\n   * Conditionally installed in the constructor — only present when the\n   * wrapped base backend supports it. Declared as an optional instance\n   * property (rather than a prototype method) so `typeof router.findEdgesGlobal\n   * === 'function'` reflects the base's capability, matching the optional\n   * shape in the `StorageBackend` interface.\n   */\n  findEdgesGlobal?: StorageBackend['findEdgesGlobal'];\n\n  constructor(\n    private readonly base: StorageBackend,\n    private readonly options: RoutingBackendOptions,\n    storageScope: string,\n    logicalScopePath: string,\n  ) {\n    this.collectionPath = base.collectionPath;\n    this.scopePath = logicalScopePath;\n    this.storageScope = storageScope;\n    if (base.findEdgesGlobal) {\n      // We deliberately do *not* fan out across routed children: we have no\n      // enumeration index for which backends exist. Callers needing\n      // cross-shard collection-group queries must maintain their own index.\n      this.findEdgesGlobal = (params, collectionName) =>\n        base.findEdgesGlobal!(params, collectionName);\n    }\n  }\n\n  // --- Pass-through reads ---\n\n  getDoc(docId: string): Promise<StoredGraphRecord | null> {\n    return this.base.getDoc(docId);\n  }\n\n  query(filters: QueryFilter[], options?: QueryOptions): Promise<StoredGraphRecord[]> {\n    return this.base.query(filters, options);\n  }\n\n  // --- Pass-through writes ---\n\n  setDoc(docId: string, record: WritableRecord): Promise<void> {\n    return this.base.setDoc(docId, record);\n  }\n\n  updateDoc(docId: string, update: UpdatePayload): Promise<void> {\n    return this.base.updateDoc(docId, update);\n  }\n\n  deleteDoc(docId: string): Promise<void> {\n    return this.base.deleteDoc(docId);\n  }\n\n  // --- Transactions / batches run against the base backend only ---\n\n  runTransaction<T>(fn: (tx: TransactionBackend) => Promise<T>): Promise<T> {\n    // Transactions cannot span base + routed backends (different DBs /\n    // DOs / Firestore projects). `TransactionBackend` has no `subgraph()`\n    // method, so the user physically cannot open a routed child from\n    // inside the callback — the compiler rejects it. At runtime, all\n    // reads/writes are confined to the base backend.\n    return this.base.runTransaction(fn);\n  }\n\n  createBatch(): BatchBackend {\n    // Same constraint as transactions: `BatchBackend` has no `subgraph()`\n    // so all buffered ops target the base backend. The router itself\n    // doesn't need to guard anything here.\n    return this.base.createBatch();\n  }\n\n  // --- Subgraphs: the only method that actually routes ---\n\n  subgraph(parentNodeUid: string, name: string): StorageBackend {\n    assertValidSubgraphArgs(parentNodeUid, name);\n\n    const childScopePath = this.scopePath ? `${this.scopePath}/${name}` : name;\n    const childStorageScope = this.storageScope\n      ? `${this.storageScope}/${parentNodeUid}/${name}`\n      : `${parentNodeUid}/${name}`;\n\n    const routed = this.options.route({\n      parentUid: parentNodeUid,\n      subgraphName: name,\n      scopePath: childScopePath,\n      storageScope: childStorageScope,\n    });\n\n    if (routed) {\n      // The user returned a different backend. We still wrap it so that\n      // further `.subgraph()` calls on the returned child continue to\n      // consult the router. The routed backend's own `scopePath` / storage\n      // layout is its business — for routing purposes we carry *our*\n      // logical view forward (`childScopePath`) so grandchildren see a\n      // correct context regardless of what `routed.scopePath` happens to\n      // be (typically `''` for a freshly-minted per-DO backend).\n      return new RoutingStorageBackend(routed, this.options, childStorageScope, childScopePath);\n    }\n\n    // No route — delegate to the base backend and keep routing in effect\n    // for grandchildren.\n    const childBase = this.base.subgraph(parentNodeUid, name);\n    return new RoutingStorageBackend(childBase, this.options, childStorageScope, childScopePath);\n  }\n\n  // --- Bulk operations: delegate, but cascade is base-scope only ---\n\n  removeNodeCascade(\n    uid: string,\n    reader: GraphReader,\n    options?: BulkOptions,\n  ): Promise<CascadeResult> {\n    // `removeNodeCascade` on the base backend cannot see rows that live\n    // in routed child backends — each routed backend is a different\n    // physical store. Callers with routed subgraphs under `uid` are\n    // responsible for cascading those themselves (see routing.md).\n    return this.base.removeNodeCascade(uid, reader, options);\n  }\n\n  bulkRemoveEdges(\n    params: FindEdgesParams,\n    reader: GraphReader,\n    options?: BulkOptions,\n  ): Promise<BulkResult> {\n    return this.base.bulkRemoveEdges(params, reader, options);\n  }\n\n  // --- Collection-group queries are base-scope only ---\n  //\n  // `findEdgesGlobal` is installed in the constructor *only* when the base\n  // backend supports it, so `typeof router.findEdgesGlobal === 'function'`\n  // reflects the base's capability — matching the optional shape declared\n  // on `StorageBackend`.\n}\n\n/**\n * Wrap a `StorageBackend` so that `subgraph(parentUid, name)` calls can be\n * routed to a different backend based on a user-supplied callback.\n *\n * See the module docstring for the atomicity rules. In short: transactions\n * and batches opened on a routing backend run entirely on the *base*\n * backend — they cannot span routed children, by design.\n *\n * @example\n * ```ts\n * // `base` is any StorageBackend — e.g. a Firestore-backed one, an\n * // in-process SQLite backend, or the DO backend from firegraph/cloudflare.\n * const routed = createRoutingBackend(base, {\n *   route: ({ subgraphName, storageScope }) => {\n *     if (subgraphName !== 'memories') return null;\n *     return createMyMemoriesBackend(storageScope); // caller-owned\n *   },\n * });\n * const client = createGraphClientFromBackend(routed, { registry });\n * ```\n */\nexport function createRoutingBackend(\n  base: StorageBackend,\n  options: RoutingBackendOptions,\n): StorageBackend {\n  if (typeof options?.route !== 'function') {\n    throw new FiregraphError(\n      'createRoutingBackend: `options.route` must be a function.',\n      'INVALID_ARGUMENT',\n    );\n  }\n  return new RoutingStorageBackend(base, options, '', base.scopePath);\n}\n","/**\n * Storage-scope path utilities — materialized-path parsing helpers for the\n * SQLite backend's `storageScope` string and for any custom backend that\n * adopts the same encoding (e.g. a cross-DO routing layer that uses\n * `storageScope` as a Durable Object name).\n *\n * **Storage-scope** (as produced by `SqliteBackendImpl`) interleaves parent\n * UIDs with subgraph names:\n *\n * ```\n * ''                                  // root\n * 'A/memories'                        // g.subgraph(A, 'memories')\n * 'A/memories/B/context'              // .subgraph(B, 'context') on the above\n * ```\n *\n * The structure is the same as a Firestore collection path with the\n * collection/doc segments reordered: each pair is `<uid>/<name>`, where\n * `<uid>` is a node UID in the parent scope and `<name>` is the subgraph\n * name. Use these helpers to decode that structure when building cross-\n * backend routers (see `createRoutingBackend`).\n *\n * For Firestore paths (which begin with a collection segment), use\n * `resolveAncestorCollection` / `isAncestorUid` from `./cross-graph.js`.\n */\n\n/**\n * One segment of a materialized-path storage-scope — a `(uid, name)` pair\n * produced by one `subgraph(uid, name)` call.\n */\nexport interface StorageScopeSegment {\n  /** Parent node UID at the enclosing scope. */\n  uid: string;\n  /** Subgraph name chosen by the caller (e.g. `'memories'`). */\n  name: string;\n}\n\n/**\n * Parse a materialized-path storage-scope into its `(uid, name)` pairs.\n *\n * Returns `[]` for the root (`''`). Throws `Error('INVALID_SCOPE_PATH')`\n * when the string has an odd number of segments (a corrupt path — every\n * level contributes exactly two segments) or when any segment is empty.\n *\n * @example\n * ```ts\n * parseStorageScope('');                         // []\n * parseStorageScope('A/memories');               // [{ uid: 'A', name: 'memories' }]\n * parseStorageScope('A/memories/B/context');     // [{ uid: 'A', name: 'memories' }, { uid: 'B', name: 'context' }]\n * ```\n */\nexport function parseStorageScope(scope: string): StorageScopeSegment[] {\n  if (scope === '') return [];\n  const parts = scope.split('/');\n  if (parts.length % 2 !== 0) {\n    throw new Error(\n      `INVALID_SCOPE_PATH: storage-scope \"${scope}\" has an odd number of segments; ` +\n        'expected interleaved <uid>/<name> pairs.',\n    );\n  }\n  const out: StorageScopeSegment[] = [];\n  for (let i = 0; i < parts.length; i += 2) {\n    const uid = parts[i];\n    const name = parts[i + 1];\n    if (!uid || !name) {\n      throw new Error(\n        `INVALID_SCOPE_PATH: storage-scope \"${scope}\" contains an empty segment at position ${i}.`,\n      );\n    }\n    out.push({ uid, name });\n  }\n  return out;\n}\n\n/**\n * Resolve the ancestor **storage-scope** at which a given UID's node lives,\n * by scanning a materialized-path storage-scope for that UID.\n *\n * Mirrors `resolveAncestorCollection()` from `./cross-graph.js` for\n * Firestore paths, but operates on `storageScope` (no leading collection\n * segment — segments are `<uid>/<name>` pairs).\n *\n * @returns The storage-scope at which the UID's node was added via\n *   `subgraph(uid, _)`, or `null` if the UID does not appear at a UID\n *   position in the path.\n *\n * @example\n * ```ts\n * // Scope: 'A/memories/B/context'\n * resolveAncestorScope('A/memories/B/context', 'A');  // ''    (A was added at root)\n * resolveAncestorScope('A/memories/B/context', 'B');  // 'A/memories'\n * resolveAncestorScope('A/memories/B/context', 'X');  // null\n * ```\n */\nexport function resolveAncestorScope(storageScope: string, uid: string): string | null {\n  if (!uid) return null;\n  if (storageScope === '') return null;\n  const parts = storageScope.split('/');\n  // UID positions are even indices (0, 2, 4, …); names are at odd indices.\n  for (let i = 0; i < parts.length; i += 2) {\n    if (parts[i] === uid) {\n      return i === 0 ? '' : parts.slice(0, i).join('/');\n    }\n  }\n  return null;\n}\n\n/**\n * Boolean shorthand for `resolveAncestorScope(scope, uid) !== null`.\n */\nexport function isAncestorScopeUid(storageScope: string, uid: string): boolean {\n  return resolveAncestorScope(storageScope, uid) !== null;\n}\n\n/**\n * Join a parent storage-scope with a new `(uid, name)` pair, producing the\n * storage-scope that `backend.subgraph(uid, name)` would use internally.\n *\n * This is the inverse of `parseStorageScope`'s per-segment semantics and is\n * useful when computing DO names / shard keys from the router callback.\n */\nexport function appendStorageScope(parentScope: string, uid: string, name: string): string {\n  if (!uid || uid.includes('/')) {\n    throw new Error(\n      `INVALID_SCOPE_PATH: uid must be non-empty and must not contain \"/\": got \"${uid}\".`,\n    );\n  }\n  if (!name || name.includes('/')) {\n    throw new Error(\n      `INVALID_SCOPE_PATH: name must be non-empty and must not contain \"/\": got \"${name}\".`,\n    );\n  }\n  return parentScope ? `${parentScope}/${uid}/${name}` : `${uid}/${name}`;\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/backend.ts","../src/errors.ts","../src/internal/routing-backend.ts","../src/internal/serialization-tag.ts","../src/internal/write-plan.ts","../src/scope-path.ts"],"sourcesContent":["/**\n * Public backend surface — the stable set of types and primitives for code\n * that wants to wrap, substitute, or compose `StorageBackend`s.\n *\n * Most firegraph users only touch `GraphClient`; this module is for the\n * narrower set of users who write their own storage drivers (e.g. an RPC\n * executor that tunnels a `StorageBackend` into a Durable Object) or who\n * need to route `subgraph()` calls across multiple physical backends\n * (see `createRoutingBackend`).\n *\n * Entry point: `firegraph/backend`.\n */\n\nexport { CrossBackendTransactionError } from './errors.js';\nexport type {\n  BatchBackend,\n  StorageBackend,\n  TransactionBackend,\n  UpdatePayload,\n  WritableRecord,\n  WriteMode,\n} from './internal/backend.js';\nexport type { RoutingBackendOptions, RoutingContext } from './internal/routing-backend.js';\nexport { createRoutingBackend } from './internal/routing-backend.js';\nexport type { DataPathOp } from './internal/write-plan.js';\nexport {\n  DELETE_FIELD,\n  deleteField,\n  flattenPatch,\n  isDeleteSentinel,\n} from './internal/write-plan.js';\nexport type { StorageScopeSegment } from './scope-path.js';\nexport {\n  appendStorageScope,\n  isAncestorScopeUid,\n  parseStorageScope,\n  resolveAncestorScope,\n} from './scope-path.js';\n","export class FiregraphError extends Error {\n  constructor(\n    message: string,\n    public readonly code: string,\n  ) {\n    super(message);\n    this.name = 'FiregraphError';\n  }\n}\n\nexport class NodeNotFoundError extends FiregraphError {\n  constructor(uid: string) {\n    super(`Node not found: ${uid}`, 'NODE_NOT_FOUND');\n    this.name = 'NodeNotFoundError';\n  }\n}\n\nexport class EdgeNotFoundError extends FiregraphError {\n  constructor(aUid: string, axbType: string, bUid: string) {\n    super(`Edge not found: ${aUid} -[${axbType}]-> ${bUid}`, 'EDGE_NOT_FOUND');\n    this.name = 'EdgeNotFoundError';\n  }\n}\n\nexport class ValidationError extends FiregraphError {\n  constructor(\n    message: string,\n    public readonly details?: unknown,\n  ) {\n    super(message, 'VALIDATION_ERROR');\n    this.name = 'ValidationError';\n  }\n}\n\nexport class RegistryViolationError extends FiregraphError {\n  constructor(aType: string, axbType: string, bType: string) {\n    super(`Unregistered triple: (${aType}) -[${axbType}]-> (${bType})`, 'REGISTRY_VIOLATION');\n    this.name = 'RegistryViolationError';\n  }\n}\n\nexport class InvalidQueryError extends FiregraphError {\n  constructor(message: string) {\n    super(message, 'INVALID_QUERY');\n    this.name = 'InvalidQueryError';\n  }\n}\n\nexport class TraversalError extends FiregraphError {\n  constructor(message: string) {\n    super(message, 'TRAVERSAL_ERROR');\n    this.name = 'TraversalError';\n  }\n}\n\nexport class DynamicRegistryError extends FiregraphError {\n  constructor(message: string) {\n    super(message, 'DYNAMIC_REGISTRY_ERROR');\n    this.name = 'DynamicRegistryError';\n  }\n}\n\nexport class QuerySafetyError extends FiregraphError {\n  constructor(message: string) {\n    super(message, 'QUERY_SAFETY');\n    this.name = 'QuerySafetyError';\n  }\n}\n\nexport class RegistryScopeError extends FiregraphError {\n  constructor(\n    aType: string,\n    axbType: string,\n    bType: string,\n    scopePath: string,\n    allowedIn: string[],\n  ) {\n    super(\n      `Type (${aType}) -[${axbType}]-> (${bType}) is not allowed at scope \"${scopePath || 'root'}\". ` +\n        `Allowed in: [${allowedIn.join(', ')}]`,\n      'REGISTRY_SCOPE',\n    );\n    this.name = 'RegistryScopeError';\n  }\n}\n\nexport class MigrationError extends FiregraphError {\n  constructor(message: string) {\n    super(message, 'MIGRATION_ERROR');\n    this.name = 'MigrationError';\n  }\n}\n\n/**\n * Thrown when a caller tries to perform an operation that would require\n * atomicity across two physical storage backends — e.g. opening a routed\n * subgraph client from inside a transaction callback. Cross-backend\n * atomicity cannot be honoured by real-world storage engines (Firestore,\n * SQLite drivers over D1/DO/better-sqlite3, etc.), so firegraph surfaces\n * this as a typed error instead of silently confining the write to the\n * base backend.\n *\n * Normally `TransactionBackend` and `BatchBackend` don't expose `subgraph()`\n * at the type level, so this error is unreachable through well-typed code.\n * It exists as a public catchable type for app code that needs to tolerate\n * this case deliberately (e.g. dynamic code paths that bypass the type\n * system) and as future-proofing if the interface ever grows a way to\n * request a sub-scope inside a transaction.\n */\nexport class CrossBackendTransactionError extends FiregraphError {\n  constructor(message: string) {\n    super(message, 'CROSS_BACKEND_TRANSACTION');\n    this.name = 'CrossBackendTransactionError';\n  }\n}\n","/**\n * Routing `StorageBackend` wrapper.\n *\n * `createRoutingBackend(base, { route })` returns a `StorageBackend` that\n * behaves identically to `base` except for `subgraph(parentUid, name)`:\n * each such call consults the caller-supplied `route` function, and if it\n * returns a non-null `StorageBackend`, that backend is used for the child\n * scope.\n *\n * This is the single seam firegraph ships for splitting a logical graph\n * across multiple physical storage backends — e.g. fanning particular\n * subgraph names out to their own Durable Objects to stay under the 10 GB\n * per-DO limit. The routing policy itself, the RPC protocol, and any\n * live-scope index are left to the caller; firegraph only owns the\n * composition primitive and the invariants that come with it.\n *\n * ## Contract — nested routing\n *\n * Whether `route()` returns a routed backend OR `null` (pass-through), the\n * child returned by `subgraph()` is **always** itself wrapped by the same\n * router. Without that self-wrap, a call chain like\n *\n * ```ts\n * router.subgraph(A, 'memories').subgraph(B, 'context')\n * ```\n *\n * would route the first hop correctly but bypass the router on the second\n * hop (since the routed backend's own `.subgraph()` doesn't know about the\n * caller's policy). Keeping routing active through grandchildren is the\n * load-bearing behaviour; `'continues routing on grandchildren …'` in the\n * unit tests locks it in.\n *\n * ## Contract — `route` is synchronous\n *\n * `.subgraph()` is synchronous in firegraph's public API. Making the\n * routing callback async would require rippling Promises through every\n * client-factory call site. Consequence: `route` can only consult data it\n * already has in hand (DO bindings, naming rules, in-memory caches). If\n * you need \"does this DO exist?\" checks, do them lazily — the first read\n * against the returned backend will surface the failure naturally.\n *\n * ## Contract — cross-backend atomicity is not silently degraded\n *\n * The wrapper's `runTransaction` and `createBatch` delegate to `base` —\n * they run entirely on the base backend. `TransactionBackend` and\n * `BatchBackend` deliberately have no `subgraph()` method, so user code\n * physically cannot open a routed child from inside a transaction\n * callback. Any attempt to bypass that (via `as any` / unchecked casts)\n * should surface as `CrossBackendTransactionError` so app code can catch\n * it cleanly — the error type is part of the public surface.\n *\n * ## Contract — `findEdgesGlobal` is base-scope only\n *\n * When delegated, `findEdgesGlobal` runs against the base backend only.\n * It does **not** fan out to routed children — firegraph has no\n * enumeration index for which routed backends exist. Callers who need\n * cross-shard collection-group queries must maintain their own scope\n * directory and query it directly. This keeps the common case (local\n * analytics inside one DO) fast.\n */\n\nimport { FiregraphError } from '../errors.js';\nimport type {\n  BulkOptions,\n  BulkResult,\n  CascadeResult,\n  FindEdgesParams,\n  GraphReader,\n  QueryFilter,\n  QueryOptions,\n  StoredGraphRecord,\n} from '../types.js';\nimport type {\n  BatchBackend,\n  StorageBackend,\n  TransactionBackend,\n  UpdatePayload,\n  WritableRecord,\n  WriteMode,\n} from './backend.js';\n\n/**\n * Context passed to a routing callback when `subgraph(parentUid, name)` is\n * called on a routed backend. All four strings describe the *child* scope\n * the caller is requesting, so the router can key its decision off whichever\n * representation is most convenient:\n *\n *   - `parentUid` / `subgraphName` — the arguments just passed to `subgraph()`.\n *   - `scopePath` — logical, names-only chain (`'memories'`, `'memories/context'`).\n *     This is what `allowedIn` patterns match against.\n *   - `storageScope` — the materialized-path form (`'A/memories'`,\n *     `'A/memories/B/context'`), suitable for use as a DO name or shard key\n *     because it's globally unique within a root graph.\n */\nexport interface RoutingContext {\n  parentUid: string;\n  subgraphName: string;\n  scopePath: string;\n  storageScope: string;\n}\n\nexport interface RoutingBackendOptions {\n  /**\n   * Decide whether a `subgraph(parentUid, name)` call should route to a\n   * different backend. Return the target backend to route; return `null`\n   * (or `undefined`) to fall through to the wrapped base backend.\n   *\n   * The returned backend is itself wrapped by the same router so that\n   * nested `.subgraph()` calls on the returned child continue to be\n   * consulted.\n   */\n  route: (ctx: RoutingContext) => StorageBackend | null | undefined;\n}\n\nfunction assertValidSubgraphArgs(parentNodeUid: string, name: string): void {\n  if (!parentNodeUid || parentNodeUid.includes('/')) {\n    throw new FiregraphError(\n      `Invalid parentNodeUid for subgraph: \"${parentNodeUid}\". ` +\n        'Must be a non-empty string without \"/\".',\n      'INVALID_SUBGRAPH',\n    );\n  }\n  if (!name || name.includes('/')) {\n    throw new FiregraphError(\n      `Subgraph name must not contain \"/\" and must be non-empty: got \"${name}\". ` +\n        'Use chained .subgraph() calls for nested subgraphs.',\n      'INVALID_SUBGRAPH',\n    );\n  }\n}\n\nclass RoutingStorageBackend implements StorageBackend {\n  readonly collectionPath: string;\n  /**\n   * Logical (names-only) scope path for *this* wrapper. Tracked\n   * independently of `base.scopePath` because a routed backend returned by\n   * `options.route()` typically represents its own physical root and has\n   * no knowledge of the caller's logical chain. The wrapper is the\n   * authoritative source of the logical scope for routing decisions and\n   * for satisfying the `StorageBackend.scopePath` contract surfaced to\n   * client code.\n   */\n  readonly scopePath: string;\n  /**\n   * Materialized-path form of `scopePath` — interleaved `<uid>/<name>`\n   * pairs. Not a property on the underlying `StorageBackend` interface\n   * (Firestore doesn't produce one), so we track it ourselves from\n   * `.subgraph()` arguments. Root routers start with `''`.\n   */\n  private readonly storageScope: string;\n  /**\n   * Conditionally installed in the constructor — only present when the\n   * wrapped base backend supports it. Declared as an optional instance\n   * property (rather than a prototype method) so `typeof router.findEdgesGlobal\n   * === 'function'` reflects the base's capability, matching the optional\n   * shape in the `StorageBackend` interface.\n   */\n  findEdgesGlobal?: StorageBackend['findEdgesGlobal'];\n\n  constructor(\n    private readonly base: StorageBackend,\n    private readonly options: RoutingBackendOptions,\n    storageScope: string,\n    logicalScopePath: string,\n  ) {\n    this.collectionPath = base.collectionPath;\n    this.scopePath = logicalScopePath;\n    this.storageScope = storageScope;\n    if (base.findEdgesGlobal) {\n      // We deliberately do *not* fan out across routed children: we have no\n      // enumeration index for which backends exist. Callers needing\n      // cross-shard collection-group queries must maintain their own index.\n      this.findEdgesGlobal = (params, collectionName) =>\n        base.findEdgesGlobal!(params, collectionName);\n    }\n  }\n\n  // --- Pass-through reads ---\n\n  getDoc(docId: string): Promise<StoredGraphRecord | null> {\n    return this.base.getDoc(docId);\n  }\n\n  query(filters: QueryFilter[], options?: QueryOptions): Promise<StoredGraphRecord[]> {\n    return this.base.query(filters, options);\n  }\n\n  // --- Pass-through writes ---\n\n  setDoc(docId: string, record: WritableRecord, mode: WriteMode): Promise<void> {\n    return this.base.setDoc(docId, record, mode);\n  }\n\n  updateDoc(docId: string, update: UpdatePayload): Promise<void> {\n    return this.base.updateDoc(docId, update);\n  }\n\n  deleteDoc(docId: string): Promise<void> {\n    return this.base.deleteDoc(docId);\n  }\n\n  // --- Transactions / batches run against the base backend only ---\n\n  runTransaction<T>(fn: (tx: TransactionBackend) => Promise<T>): Promise<T> {\n    // Transactions cannot span base + routed backends (different DBs /\n    // DOs / Firestore projects). `TransactionBackend` has no `subgraph()`\n    // method, so the user physically cannot open a routed child from\n    // inside the callback — the compiler rejects it. At runtime, all\n    // reads/writes are confined to the base backend.\n    return this.base.runTransaction(fn);\n  }\n\n  createBatch(): BatchBackend {\n    // Same constraint as transactions: `BatchBackend` has no `subgraph()`\n    // so all buffered ops target the base backend. The router itself\n    // doesn't need to guard anything here.\n    return this.base.createBatch();\n  }\n\n  // --- Subgraphs: the only method that actually routes ---\n\n  subgraph(parentNodeUid: string, name: string): StorageBackend {\n    assertValidSubgraphArgs(parentNodeUid, name);\n\n    const childScopePath = this.scopePath ? `${this.scopePath}/${name}` : name;\n    const childStorageScope = this.storageScope\n      ? `${this.storageScope}/${parentNodeUid}/${name}`\n      : `${parentNodeUid}/${name}`;\n\n    const routed = this.options.route({\n      parentUid: parentNodeUid,\n      subgraphName: name,\n      scopePath: childScopePath,\n      storageScope: childStorageScope,\n    });\n\n    if (routed) {\n      // The user returned a different backend. We still wrap it so that\n      // further `.subgraph()` calls on the returned child continue to\n      // consult the router. The routed backend's own `scopePath` / storage\n      // layout is its business — for routing purposes we carry *our*\n      // logical view forward (`childScopePath`) so grandchildren see a\n      // correct context regardless of what `routed.scopePath` happens to\n      // be (typically `''` for a freshly-minted per-DO backend).\n      return new RoutingStorageBackend(routed, this.options, childStorageScope, childScopePath);\n    }\n\n    // No route — delegate to the base backend and keep routing in effect\n    // for grandchildren.\n    const childBase = this.base.subgraph(parentNodeUid, name);\n    return new RoutingStorageBackend(childBase, this.options, childStorageScope, childScopePath);\n  }\n\n  // --- Bulk operations: delegate, but cascade is base-scope only ---\n\n  removeNodeCascade(\n    uid: string,\n    reader: GraphReader,\n    options?: BulkOptions,\n  ): Promise<CascadeResult> {\n    // `removeNodeCascade` on the base backend cannot see rows that live\n    // in routed child backends — each routed backend is a different\n    // physical store. Callers with routed subgraphs under `uid` are\n    // responsible for cascading those themselves (see routing.md).\n    return this.base.removeNodeCascade(uid, reader, options);\n  }\n\n  bulkRemoveEdges(\n    params: FindEdgesParams,\n    reader: GraphReader,\n    options?: BulkOptions,\n  ): Promise<BulkResult> {\n    return this.base.bulkRemoveEdges(params, reader, options);\n  }\n\n  // --- Collection-group queries are base-scope only ---\n  //\n  // `findEdgesGlobal` is installed in the constructor *only* when the base\n  // backend supports it, so `typeof router.findEdgesGlobal === 'function'`\n  // reflects the base's capability — matching the optional shape declared\n  // on `StorageBackend`.\n}\n\n/**\n * Wrap a `StorageBackend` so that `subgraph(parentUid, name)` calls can be\n * routed to a different backend based on a user-supplied callback.\n *\n * See the module docstring for the atomicity rules. In short: transactions\n * and batches opened on a routing backend run entirely on the *base*\n * backend — they cannot span routed children, by design.\n *\n * @example\n * ```ts\n * // `base` is any StorageBackend — e.g. a Firestore-backed one, an\n * // in-process SQLite backend, or the DO backend from firegraph/cloudflare.\n * const routed = createRoutingBackend(base, {\n *   route: ({ subgraphName, storageScope }) => {\n *     if (subgraphName !== 'memories') return null;\n *     return createMyMemoriesBackend(storageScope); // caller-owned\n *   },\n * });\n * const client = createGraphClientFromBackend(routed, { registry });\n * ```\n */\nexport function createRoutingBackend(\n  base: StorageBackend,\n  options: RoutingBackendOptions,\n): StorageBackend {\n  if (typeof options?.route !== 'function') {\n    throw new FiregraphError(\n      'createRoutingBackend: `options.route` must be a function.',\n      'INVALID_ARGUMENT',\n    );\n  }\n  return new RoutingStorageBackend(base, options, '', base.scopePath);\n}\n","/**\n * Firegraph serialization tag — split from `src/serialization.ts` so it can\n * be imported from Workers-facing code without dragging in\n * `@google-cloud/firestore`.\n *\n * The full serialization module (with Timestamp/GeoPoint round-tripping)\n * lives one folder up because the sandbox migration pipeline needs it; the\n * write-plan helper only needs to recognise tagged objects to keep them\n * terminal during patch flattening, so it imports just the tag from here.\n */\n\n/** Sentinel key used to tag serialized Firestore types. */\nexport const SERIALIZATION_TAG = '__firegraph_ser__' as const;\n\nconst KNOWN_TYPES = new Set(['Timestamp', 'GeoPoint', 'VectorValue', 'DocumentReference']);\n\n/** Check if a value is a tagged serialized Firestore type. */\nexport function isTaggedValue(value: unknown): boolean {\n  if (value === null || typeof value !== 'object') return false;\n  const tag = (value as Record<string, unknown>)[SERIALIZATION_TAG];\n  return typeof tag === 'string' && KNOWN_TYPES.has(tag);\n}\n","/**\n * Write-plan helper — flattens partial-update payloads into a list of\n * deep-path operations every backend can execute identically.\n *\n * Background: firegraph used to ship two write semantics that quietly\n * disagreed about depth.\n *   - `putNode`/`putEdge` did a full document replace.\n *   - `updateNode`/`updateEdge` did a one-level shallow merge: top-level\n *     keys were preserved, but nested objects were replaced wholesale.\n *\n * Both behaviours dropped sibling keys silently. The 0.12 contract is that\n * `put*` and `update*` deep-merge by default (sibling keys at any depth\n * survive); `replace*` is the explicit escape hatch.\n *\n * `flattenPatch` walks a partial-update payload and emits one\n * {@link DataPathOp} per terminal value. Plain objects recurse; arrays,\n * primitives, Firestore special types, and tagged firegraph-serialization\n * objects are terminal (replaced as a unit). `undefined` values are\n * skipped; `null` is preserved as a real `null` write; the\n * {@link DELETE_FIELD} sentinel marks a field for removal.\n *\n * The output is deliberately backend-agnostic. Each backend translates ops\n * into its native dialect:\n *   - Firestore: dotted field path → `data.a.b.c` for `update()`.\n *   - SQLite / DO SQLite: `json_set(data, '$.a.b.c', ?)` /\n *     `json_remove(data, '$.a.b.c')`.\n */\n\nimport { isTaggedValue, SERIALIZATION_TAG } from './serialization-tag.js';\n\n// ---------------------------------------------------------------------------\n// Public sentinel\n// ---------------------------------------------------------------------------\n\n/**\n * Sentinel returned by {@link deleteField}. Treated by all backends as\n * \"remove this field from the stored document\".\n *\n * Equivalent to Firestore's `FieldValue.delete()`, but works for SQLite\n * backends too. Use inside `updateNode`/`updateEdge` payloads.\n */\nexport const DELETE_FIELD: unique symbol = Symbol.for('firegraph.deleteField');\nexport type DeleteSentinel = typeof DELETE_FIELD;\n\n/**\n * Returns the firegraph delete sentinel. Place this anywhere in an\n * `updateNode`/`updateEdge` payload to remove the corresponding field.\n *\n * ```ts\n * await client.updateNode('tour', uid, {\n *   attrs: { obsoleteFlag: deleteField() },\n * });\n * ```\n */\nexport function deleteField(): DeleteSentinel {\n  return DELETE_FIELD;\n}\n\n/** Type guard for the delete sentinel. */\nexport function isDeleteSentinel(value: unknown): value is DeleteSentinel {\n  return value === DELETE_FIELD;\n}\n\n// ---------------------------------------------------------------------------\n// Terminal-detection helpers\n// ---------------------------------------------------------------------------\n\nconst FIRESTORE_TERMINAL_CTOR = new Set([\n  'Timestamp',\n  'GeoPoint',\n  'VectorValue',\n  'DocumentReference',\n  'FieldValue',\n  'NumericIncrementTransform',\n  'ArrayUnionTransform',\n  'ArrayRemoveTransform',\n  'ServerTimestampTransform',\n  'DeleteTransform',\n]);\n\n/**\n * Should this value be written as a single terminal op (no recursion)?\n *\n * Plain JS objects (constructor === Object, or no prototype) are recursed.\n * Everything else — arrays, primitives, class instances, Firestore special\n * types, tagged serialization payloads — is terminal.\n */\nexport function isTerminalValue(value: unknown): boolean {\n  if (value === null) return true;\n  const t = typeof value;\n  if (t !== 'object') return true;\n  if (Array.isArray(value)) return true;\n  // Tagged serialization payloads carry the SERIALIZATION_TAG sentinel and\n  // should be persisted whole — never split into per-field ops.\n  if (isTaggedValue(value)) return true;\n  const proto = Object.getPrototypeOf(value);\n  if (proto === null || proto === Object.prototype) return false;\n  // Class instances — Firestore types or anything else exotic.\n  const ctor = (value as { constructor?: { name?: string } }).constructor;\n  if (ctor && typeof ctor.name === 'string' && FIRESTORE_TERMINAL_CTOR.has(ctor.name)) return true;\n  // Unknown class instance: treat as terminal. Recursing into a class\n  // instance is almost always wrong (Map, Set, Date, Buffer...).\n  return true;\n}\n\n// ---------------------------------------------------------------------------\n// Core type\n// ---------------------------------------------------------------------------\n\n/**\n * Single terminal write operation produced by {@link flattenPatch}.\n *\n * `path` is a non-empty array of plain object keys. `value` is the value to\n * write; ignored when `delete` is `true`. Arrays / primitives / Firestore\n * special types appear here as whole terminal values.\n */\nexport interface DataPathOp {\n  path: readonly string[];\n  value: unknown;\n  delete: boolean;\n}\n\n// ---------------------------------------------------------------------------\n// Path-segment validation\n// ---------------------------------------------------------------------------\n\n/**\n * Object keys that are safe to embed in SQLite `json_set`/`json_remove`\n * paths. The SQLite backend uses an allowlist regex too — keep these in\n * sync (see `JSON_PATH_KEY_RE` in `internal/sqlite-sql.ts` and\n * `cloudflare/sql.ts`).\n *\n * Allows: ASCII letters, digits, `_`, `-`. Must start with a letter or\n * underscore. This rejects keys containing dots, brackets, quotes, or\n * non-ASCII characters that could break path parsing or be used to\n * inject into the path expression.\n */\nconst SAFE_KEY_RE = /^[A-Za-z_][A-Za-z0-9_-]*$/;\n\n/**\n * Mutual-exclusion guard for {@link UpdatePayload}. The two branches of the\n * shape — `dataOps` (deep-merge) and `replaceData` (full replace) — are\n * structurally incompatible: combining them would tell the backend to\n * simultaneously merge AND wipe, and the three backends disagree on which\n * wins. This helper centralises the runtime check so all three backends\n * trip the same error.\n *\n * Imported as a runtime check from `firestore-backend`, `sqlite-sql`, and\n * `cloudflare/sql`. Backend authors implementing the public `StorageBackend`\n * contract should call it too.\n */\nexport function assertUpdatePayloadExclusive(update: {\n  dataOps?: unknown;\n  replaceData?: unknown;\n}): void {\n  if (update.replaceData !== undefined && update.dataOps !== undefined) {\n    throw new Error(\n      'firegraph: UpdatePayload cannot specify both `replaceData` and `dataOps`. ' +\n        'Use one or the other — `replaceData` is the migration-write-back form, ' +\n        '`dataOps` is the standard partial-update form.',\n    );\n  }\n}\n\n/**\n * Reject `DELETE_FIELD` sentinels in payloads where field deletion isn't a\n * meaningful operation: full-document replace (`replaceNode`/`replaceEdge`)\n * and the merge-default put surface (`putNode`/`putEdge`).\n *\n * Why both:\n *   - In **replace**, the entire `data` field is overwritten. A delete\n *     sentinel in that payload either silently disappears (Firestore drops\n *     the Symbol during `.set()` serialization) or produces an empty SQLite\n *     `json_remove` no-op, depending on backend. Either way the caller's\n *     intent — \"remove field X\" — is lost. Use `updateNode` instead.\n *   - In **put** (merge mode), behaviour diverges across backends today:\n *     SQLite's flattenPatch emits a real delete op, but Firestore's\n *     `.set(..., {merge: true})` silently drops the Symbol. Until that's\n *     fixed end-to-end, the safest contract is to reject sentinels at the\n *     entry point and steer callers to `updateNode`.\n *\n * The walk mirrors `flattenPatch`: plain objects recurse, everything else\n * is terminal. Tagged serialization payloads short-circuit so we don't\n * recurse into the `__firegraph_ser__` envelope.\n */\nexport function assertNoDeleteSentinels(data: unknown, callerLabel: string): void {\n  walkForDeleteSentinels(data, [], { kind: 'root' }, ({ path }) => {\n    const where = path.length === 0 ? '<root>' : path.map((p) => JSON.stringify(p)).join(' > ');\n    throw new Error(\n      `firegraph: ${callerLabel} payload contains a deleteField() sentinel at ${where}. ` +\n        `deleteField() is only valid inside updateNode/updateEdge — full-data ` +\n        `writes (put*, replace*) cannot delete individual fields. Use updateNode ` +\n        `with a deleteField() value, or omit the field from the replace payload.`,\n    );\n  });\n}\n\ntype SentinelParent = { kind: 'root' } | { kind: 'object' } | { kind: 'array'; index: number };\n\nfunction walkForDeleteSentinels(\n  node: unknown,\n  path: readonly string[],\n  parent: SentinelParent,\n  visit: (ctx: { path: readonly string[]; parent: SentinelParent }) => void,\n): void {\n  if (node === null || node === undefined) return;\n  if (isDeleteSentinel(node)) {\n    visit({ path, parent });\n    return;\n  }\n  if (typeof node !== 'object') return;\n  if (isTaggedValue(node)) return;\n  if (Array.isArray(node)) {\n    for (let i = 0; i < node.length; i++) {\n      walkForDeleteSentinels(node[i], [...path, String(i)], { kind: 'array', index: i }, visit);\n    }\n    return;\n  }\n  const proto = Object.getPrototypeOf(node);\n  if (proto !== null && proto !== Object.prototype) return;\n  const obj = node as Record<string, unknown>;\n  for (const key of Object.keys(obj)) {\n    walkForDeleteSentinels(obj[key], [...path, key], { kind: 'object' }, visit);\n  }\n}\n\n/** Throws if any path segment in the patch is unsafe for SQLite paths. */\nexport function assertSafePath(path: readonly string[]): void {\n  for (const seg of path) {\n    if (!SAFE_KEY_RE.test(seg)) {\n      throw new Error(\n        `firegraph: unsafe object key ${JSON.stringify(seg)} at path ${path\n          .map((p) => JSON.stringify(p))\n          .join(' > ')}. Keys used inside update payloads must match ` +\n          `/^[A-Za-z_][A-Za-z0-9_-]*$/ so they can be embedded safely in ` +\n          `SQLite JSON paths.`,\n      );\n    }\n  }\n}\n\n// ---------------------------------------------------------------------------\n// flattenPatch\n// ---------------------------------------------------------------------------\n\n/**\n * Flatten a partial-update payload into a list of terminal {@link DataPathOp}s.\n *\n * Rules:\n *   - Plain objects (no prototype or `Object.prototype`) recurse — each\n *     key becomes another path segment.\n *   - Arrays are terminal: writing `{tags: ['a']}` overwrites the whole\n *     `tags` array. Element-wise array merging is intentionally NOT\n *     supported — it's almost never what callers actually want, and\n *     Firestore `arrayUnion`/`arrayRemove` give precise semantics when\n *     they are.\n *   - `undefined` values are skipped (no op generated). Use\n *     {@link deleteField} if you actually want to remove a field.\n *   - `null` is preserved verbatim — emits a terminal op with `value: null`.\n *   - {@link DELETE_FIELD} produces an op with `delete: true`.\n *   - Firestore special types and tagged serialization payloads are terminal.\n *   - Class instances are terminal.\n *\n * Throws if any object key on the recursion path is unsafe (see\n * {@link assertSafePath}).\n */\nexport function flattenPatch(data: Record<string, unknown>): DataPathOp[] {\n  const ops: DataPathOp[] = [];\n  walk(data, [], ops);\n  return ops;\n}\n\nfunction assertNoDeleteSentinelsInArrayValue(\n  arr: readonly unknown[],\n  arrayPath: readonly string[],\n): void {\n  walkForDeleteSentinels(arr, arrayPath, { kind: 'root' }, ({ parent }) => {\n    const arrayPathStr =\n      arrayPath.length === 0 ? '<root>' : arrayPath.map((p) => JSON.stringify(p)).join(' > ');\n    if (parent.kind === 'array') {\n      throw new Error(\n        `firegraph: deleteField() sentinel at index ${parent.index} inside an array at ` +\n          `path ${arrayPathStr}. Arrays are ` +\n          `terminal in update payloads (replaced as a unit), so the sentinel ` +\n          `would be silently dropped by JSON serialization. To remove the ` +\n          `field entirely, pass deleteField() in place of the whole array.`,\n      );\n    }\n    throw new Error(\n      `firegraph: deleteField() sentinel inside an array element at ` +\n        `path ${arrayPathStr}. ` +\n        `Arrays are terminal in update payloads — the sentinel would ` +\n        `be silently dropped by JSON serialization.`,\n    );\n  });\n}\n\nfunction walk(node: unknown, path: string[], out: DataPathOp[]): void {\n  // Caller guarantees the root is a plain object; this branch only\n  // matters for recursion.\n  if (node === undefined) return;\n  if (isDeleteSentinel(node)) {\n    if (path.length === 0) {\n      throw new Error('firegraph: deleteField() cannot be the entire update payload.');\n    }\n    assertSafePath(path);\n    out.push({ path: [...path], value: undefined, delete: true });\n    return;\n  }\n  if (isTerminalValue(node)) {\n    if (path.length === 0) {\n      // `null` / array / primitive at the root is illegal — patches must\n      // describe per-key changes.\n      throw new Error(\n        'firegraph: update payload must be a plain object. Got ' +\n          (node === null ? 'null' : Array.isArray(node) ? 'array' : typeof node) +\n          '.',\n      );\n    }\n    // A DELETE_FIELD sentinel embedded inside an array (which is terminal\n    // and replaced as a unit) would silently disappear: JSON.stringify drops\n    // Symbols, and Firestore's serializer does likewise. Reject loudly so\n    // the divergence between \"user wrote a delete\" and \"field stayed put\"\n    // can't happen.\n    if (Array.isArray(node)) {\n      assertNoDeleteSentinelsInArrayValue(node, path);\n    }\n    assertSafePath(path);\n    out.push({ path: [...path], value: node, delete: false });\n    return;\n  }\n  // Plain object: recurse into its own enumerable keys.\n  const obj = node as Record<string, unknown>;\n  const keys = Object.keys(obj);\n  if (keys.length === 0) {\n    // Empty object at non-root: emit terminal op so an empty object can\n    // be written explicitly when the caller really wants one. Skip at\n    // the root — no-op patches should produce no ops.\n    if (path.length > 0) {\n      assertSafePath(path);\n      out.push({ path: [...path], value: {}, delete: false });\n    }\n    return;\n  }\n  for (const key of keys) {\n    if (key === SERIALIZATION_TAG) {\n      const where = path.length === 0 ? '<root>' : path.map((p) => JSON.stringify(p)).join(' > ');\n      throw new Error(\n        `firegraph: update payload contains a literal \\`${SERIALIZATION_TAG}\\` key at ` +\n          `${where}. That key is reserved for firegraph's serialization envelope and ` +\n          `cannot appear on a plain object in user data. Use a different field name, ` +\n          `or pass a recognized tagged value through replaceNode/replaceEdge instead.`,\n      );\n    }\n    walk(obj[key], [...path, key], out);\n  }\n}\n","/**\n * Storage-scope path utilities — materialized-path parsing helpers for the\n * SQLite backend's `storageScope` string and for any custom backend that\n * adopts the same encoding (e.g. a cross-DO routing layer that uses\n * `storageScope` as a Durable Object name).\n *\n * **Storage-scope** (as produced by `SqliteBackendImpl`) interleaves parent\n * UIDs with subgraph names:\n *\n * ```\n * ''                                  // root\n * 'A/memories'                        // g.subgraph(A, 'memories')\n * 'A/memories/B/context'              // .subgraph(B, 'context') on the above\n * ```\n *\n * The structure is the same as a Firestore collection path with the\n * collection/doc segments reordered: each pair is `<uid>/<name>`, where\n * `<uid>` is a node UID in the parent scope and `<name>` is the subgraph\n * name. Use these helpers to decode that structure when building cross-\n * backend routers (see `createRoutingBackend`).\n *\n * For Firestore paths (which begin with a collection segment), use\n * `resolveAncestorCollection` / `isAncestorUid` from `./cross-graph.js`.\n */\n\n/**\n * One segment of a materialized-path storage-scope — a `(uid, name)` pair\n * produced by one `subgraph(uid, name)` call.\n */\nexport interface StorageScopeSegment {\n  /** Parent node UID at the enclosing scope. */\n  uid: string;\n  /** Subgraph name chosen by the caller (e.g. `'memories'`). */\n  name: string;\n}\n\n/**\n * Parse a materialized-path storage-scope into its `(uid, name)` pairs.\n *\n * Returns `[]` for the root (`''`). Throws `Error('INVALID_SCOPE_PATH')`\n * when the string has an odd number of segments (a corrupt path — every\n * level contributes exactly two segments) or when any segment is empty.\n *\n * @example\n * ```ts\n * parseStorageScope('');                         // []\n * parseStorageScope('A/memories');               // [{ uid: 'A', name: 'memories' }]\n * parseStorageScope('A/memories/B/context');     // [{ uid: 'A', name: 'memories' }, { uid: 'B', name: 'context' }]\n * ```\n */\nexport function parseStorageScope(scope: string): StorageScopeSegment[] {\n  if (scope === '') return [];\n  const parts = scope.split('/');\n  if (parts.length % 2 !== 0) {\n    throw new Error(\n      `INVALID_SCOPE_PATH: storage-scope \"${scope}\" has an odd number of segments; ` +\n        'expected interleaved <uid>/<name> pairs.',\n    );\n  }\n  const out: StorageScopeSegment[] = [];\n  for (let i = 0; i < parts.length; i += 2) {\n    const uid = parts[i];\n    const name = parts[i + 1];\n    if (!uid || !name) {\n      throw new Error(\n        `INVALID_SCOPE_PATH: storage-scope \"${scope}\" contains an empty segment at position ${i}.`,\n      );\n    }\n    out.push({ uid, name });\n  }\n  return out;\n}\n\n/**\n * Resolve the ancestor **storage-scope** at which a given UID's node lives,\n * by scanning a materialized-path storage-scope for that UID.\n *\n * Mirrors `resolveAncestorCollection()` from `./cross-graph.js` for\n * Firestore paths, but operates on `storageScope` (no leading collection\n * segment — segments are `<uid>/<name>` pairs).\n *\n * @returns The storage-scope at which the UID's node was added via\n *   `subgraph(uid, _)`, or `null` if the UID does not appear at a UID\n *   position in the path.\n *\n * @example\n * ```ts\n * // Scope: 'A/memories/B/context'\n * resolveAncestorScope('A/memories/B/context', 'A');  // ''    (A was added at root)\n * resolveAncestorScope('A/memories/B/context', 'B');  // 'A/memories'\n * resolveAncestorScope('A/memories/B/context', 'X');  // null\n * ```\n */\nexport function resolveAncestorScope(storageScope: string, uid: string): string | null {\n  if (!uid) return null;\n  if (storageScope === '') return null;\n  const parts = storageScope.split('/');\n  // UID positions are even indices (0, 2, 4, …); names are at odd indices.\n  for (let i = 0; i < parts.length; i += 2) {\n    if (parts[i] === uid) {\n      return i === 0 ? '' : parts.slice(0, i).join('/');\n    }\n  }\n  return null;\n}\n\n/**\n * Boolean shorthand for `resolveAncestorScope(scope, uid) !== null`.\n */\nexport function isAncestorScopeUid(storageScope: string, uid: string): boolean {\n  return resolveAncestorScope(storageScope, uid) !== null;\n}\n\n/**\n * Join a parent storage-scope with a new `(uid, name)` pair, producing the\n * storage-scope that `backend.subgraph(uid, name)` would use internally.\n *\n * This is the inverse of `parseStorageScope`'s per-segment semantics and is\n * useful when computing DO names / shard keys from the router callback.\n */\nexport function appendStorageScope(parentScope: string, uid: string, name: string): string {\n  if (!uid || uid.includes('/')) {\n    throw new Error(\n      `INVALID_SCOPE_PATH: uid must be non-empty and must not contain \"/\": got \"${uid}\".`,\n    );\n  }\n  if (!name || name.includes('/')) {\n    throw new Error(\n      `INVALID_SCOPE_PATH: name must be non-empty and must not contain \"/\": got \"${name}\".`,\n    );\n  }\n  return parentScope ? `${parentScope}/${uid}/${name}` : `${uid}/${name}`;\n}\n"],"mappings":"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","names":[]}

package/dist/backend.d.cts

@@ -1,7 +1,7 @@
 export { C as CrossBackendTransactionError, S as StorageScopeSegment, a as appendStorageScope, i as isAncestorScopeUid, p as parseStorageScope, r as resolveAncestorScope } from './scope-path-B1G3YiA7.cjs';
-import { S as StorageBackend } from './backend-np4gEVhB.cjs';
-export { B as BatchBackend, T as TransactionBackend, U as UpdatePayload, W as WritableRecord } from './backend-np4gEVhB.cjs';
-import './types-BGWxcpI_.cjs';
+import { S as StorageBackend } from './backend-Ct-fLlkG.cjs';
+export { B as BatchBackend, D as DELETE_FIELD, a as DataPathOp, T as TransactionBackend, U as UpdatePayload, W as WritableRecord, b as WriteMode, d as deleteField, f as flattenPatch, i as isDeleteSentinel } from './backend-Ct-fLlkG.cjs';
+import './types-DxYLy8Ol.cjs';
 import '@google-cloud/firestore';
 
 /**

package/dist/backend.d.ts

@@ -1,7 +1,7 @@
 export { C as CrossBackendTransactionError, S as StorageScopeSegment, a as appendStorageScope, i as isAncestorScopeUid, p as parseStorageScope, r as resolveAncestorScope } from './scope-path-B1G3YiA7.js';
-import { S as StorageBackend } from './backend-U-MLShlg.js';
-export { B as BatchBackend, T as TransactionBackend, U as UpdatePayload, W as WritableRecord } from './backend-U-MLShlg.js';
-import './types-BGWxcpI_.js';
+import { S as StorageBackend } from './backend-BsR0lnFL.js';
+export { B as BatchBackend, D as DELETE_FIELD, a as DataPathOp, T as TransactionBackend, U as UpdatePayload, W as WritableRecord, b as WriteMode, d as deleteField, f as flattenPatch, i as isDeleteSentinel } from './backend-BsR0lnFL.js';
+import './types-DxYLy8Ol.js';
 import '@google-cloud/firestore';
 
 /**

package/dist/backend.js

@@ -6,8 +6,13 @@ import {
 } from "./chunk-TYYPRVIE.js";
 import {
   CrossBackendTransactionError,
-  FiregraphError
-} from "./chunk-R7CRGYY4.js";
+  DELETE_FIELD,
+  FiregraphError,
+  deleteField,
+  flattenPatch,
+  isDeleteSentinel
+} from "./chunk-AWW4MUJ5.js";
+import "./chunk-EQJUUVFG.js";
 
 // src/internal/routing-backend.ts
 function assertValidSubgraphArgs(parentNodeUid, name) {
@@ -69,8 +74,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);
@@ -127,9 +132,13 @@ function createRoutingBackend(base, options) {
 }
 export {
   CrossBackendTransactionError,
+  DELETE_FIELD,
   appendStorageScope,
   createRoutingBackend,
+  deleteField,
+  flattenPatch,
   isAncestorScopeUid,
+  isDeleteSentinel,
   parseStorageScope,
   resolveAncestorScope
 };

package/dist/backend.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/internal/routing-backend.ts"],"sourcesContent":["/**\n * Routing `StorageBackend` wrapper.\n *\n * `createRoutingBackend(base, { route })` returns a `StorageBackend` that\n * behaves identically to `base` except for `subgraph(parentUid, name)`:\n * each such call consults the caller-supplied `route` function, and if it\n * returns a non-null `StorageBackend`, that backend is used for the child\n * scope.\n *\n * This is the single seam firegraph ships for splitting a logical graph\n * across multiple physical storage backends — e.g. fanning particular\n * subgraph names out to their own Durable Objects to stay under the 10 GB\n * per-DO limit. The routing policy itself, the RPC protocol, and any\n * live-scope index are left to the caller; firegraph only owns the\n * composition primitive and the invariants that come with it.\n *\n * ## Contract — nested routing\n *\n * Whether `route()` returns a routed backend OR `null` (pass-through), the\n * child returned by `subgraph()` is **always** itself wrapped by the same\n * router. Without that self-wrap, a call chain like\n *\n * ```ts\n * router.subgraph(A, 'memories').subgraph(B, 'context')\n * ```\n *\n * would route the first hop correctly but bypass the router on the second\n * hop (since the routed backend's own `.subgraph()` doesn't know about the\n * caller's policy). Keeping routing active through grandchildren is the\n * load-bearing behaviour; `'continues routing on grandchildren …'` in the\n * unit tests locks it in.\n *\n * ## Contract — `route` is synchronous\n *\n * `.subgraph()` is synchronous in firegraph's public API. Making the\n * routing callback async would require rippling Promises through every\n * client-factory call site. Consequence: `route` can only consult data it\n * already has in hand (DO bindings, naming rules, in-memory caches). If\n * you need \"does this DO exist?\" checks, do them lazily — the first read\n * against the returned backend will surface the failure naturally.\n *\n * ## Contract — cross-backend atomicity is not silently degraded\n *\n * The wrapper's `runTransaction` and `createBatch` delegate to `base` —\n * they run entirely on the base backend. `TransactionBackend` and\n * `BatchBackend` deliberately have no `subgraph()` method, so user code\n * physically cannot open a routed child from inside a transaction\n * callback. Any attempt to bypass that (via `as any` / unchecked casts)\n * should surface as `CrossBackendTransactionError` so app code can catch\n * it cleanly — the error type is part of the public surface.\n *\n * ## Contract — `findEdgesGlobal` is base-scope only\n *\n * When delegated, `findEdgesGlobal` runs against the base backend only.\n * It does **not** fan out to routed children — firegraph has no\n * enumeration index for which routed backends exist. Callers who need\n * cross-shard collection-group queries must maintain their own scope\n * directory and query it directly. This keeps the common case (local\n * analytics inside one DO) fast.\n */\n\nimport { FiregraphError } from '../errors.js';\nimport type {\n  BulkOptions,\n  BulkResult,\n  CascadeResult,\n  FindEdgesParams,\n  GraphReader,\n  QueryFilter,\n  QueryOptions,\n  StoredGraphRecord,\n} from '../types.js';\nimport type {\n  BatchBackend,\n  StorageBackend,\n  TransactionBackend,\n  UpdatePayload,\n  WritableRecord,\n} from './backend.js';\n\n/**\n * Context passed to a routing callback when `subgraph(parentUid, name)` is\n * called on a routed backend. All four strings describe the *child* scope\n * the caller is requesting, so the router can key its decision off whichever\n * representation is most convenient:\n *\n *   - `parentUid` / `subgraphName` — the arguments just passed to `subgraph()`.\n *   - `scopePath` — logical, names-only chain (`'memories'`, `'memories/context'`).\n *     This is what `allowedIn` patterns match against.\n *   - `storageScope` — the materialized-path form (`'A/memories'`,\n *     `'A/memories/B/context'`), suitable for use as a DO name or shard key\n *     because it's globally unique within a root graph.\n */\nexport interface RoutingContext {\n  parentUid: string;\n  subgraphName: string;\n  scopePath: string;\n  storageScope: string;\n}\n\nexport interface RoutingBackendOptions {\n  /**\n   * Decide whether a `subgraph(parentUid, name)` call should route to a\n   * different backend. Return the target backend to route; return `null`\n   * (or `undefined`) to fall through to the wrapped base backend.\n   *\n   * The returned backend is itself wrapped by the same router so that\n   * nested `.subgraph()` calls on the returned child continue to be\n   * consulted.\n   */\n  route: (ctx: RoutingContext) => StorageBackend | null | undefined;\n}\n\nfunction assertValidSubgraphArgs(parentNodeUid: string, name: string): void {\n  if (!parentNodeUid || parentNodeUid.includes('/')) {\n    throw new FiregraphError(\n      `Invalid parentNodeUid for subgraph: \"${parentNodeUid}\". ` +\n        'Must be a non-empty string without \"/\".',\n      'INVALID_SUBGRAPH',\n    );\n  }\n  if (!name || name.includes('/')) {\n    throw new FiregraphError(\n      `Subgraph name must not contain \"/\" and must be non-empty: got \"${name}\". ` +\n        'Use chained .subgraph() calls for nested subgraphs.',\n      'INVALID_SUBGRAPH',\n    );\n  }\n}\n\nclass RoutingStorageBackend implements StorageBackend {\n  readonly collectionPath: string;\n  /**\n   * Logical (names-only) scope path for *this* wrapper. Tracked\n   * independently of `base.scopePath` because a routed backend returned by\n   * `options.route()` typically represents its own physical root and has\n   * no knowledge of the caller's logical chain. The wrapper is the\n   * authoritative source of the logical scope for routing decisions and\n   * for satisfying the `StorageBackend.scopePath` contract surfaced to\n   * client code.\n   */\n  readonly scopePath: string;\n  /**\n   * Materialized-path form of `scopePath` — interleaved `<uid>/<name>`\n   * pairs. Not a property on the underlying `StorageBackend` interface\n   * (Firestore doesn't produce one), so we track it ourselves from\n   * `.subgraph()` arguments. Root routers start with `''`.\n   */\n  private readonly storageScope: string;\n  /**\n   * Conditionally installed in the constructor — only present when the\n   * wrapped base backend supports it. Declared as an optional instance\n   * property (rather than a prototype method) so `typeof router.findEdgesGlobal\n   * === 'function'` reflects the base's capability, matching the optional\n   * shape in the `StorageBackend` interface.\n   */\n  findEdgesGlobal?: StorageBackend['findEdgesGlobal'];\n\n  constructor(\n    private readonly base: StorageBackend,\n    private readonly options: RoutingBackendOptions,\n    storageScope: string,\n    logicalScopePath: string,\n  ) {\n    this.collectionPath = base.collectionPath;\n    this.scopePath = logicalScopePath;\n    this.storageScope = storageScope;\n    if (base.findEdgesGlobal) {\n      // We deliberately do *not* fan out across routed children: we have no\n      // enumeration index for which backends exist. Callers needing\n      // cross-shard collection-group queries must maintain their own index.\n      this.findEdgesGlobal = (params, collectionName) =>\n        base.findEdgesGlobal!(params, collectionName);\n    }\n  }\n\n  // --- Pass-through reads ---\n\n  getDoc(docId: string): Promise<StoredGraphRecord | null> {\n    return this.base.getDoc(docId);\n  }\n\n  query(filters: QueryFilter[], options?: QueryOptions): Promise<StoredGraphRecord[]> {\n    return this.base.query(filters, options);\n  }\n\n  // --- Pass-through writes ---\n\n  setDoc(docId: string, record: WritableRecord): Promise<void> {\n    return this.base.setDoc(docId, record);\n  }\n\n  updateDoc(docId: string, update: UpdatePayload): Promise<void> {\n    return this.base.updateDoc(docId, update);\n  }\n\n  deleteDoc(docId: string): Promise<void> {\n    return this.base.deleteDoc(docId);\n  }\n\n  // --- Transactions / batches run against the base backend only ---\n\n  runTransaction<T>(fn: (tx: TransactionBackend) => Promise<T>): Promise<T> {\n    // Transactions cannot span base + routed backends (different DBs /\n    // DOs / Firestore projects). `TransactionBackend` has no `subgraph()`\n    // method, so the user physically cannot open a routed child from\n    // inside the callback — the compiler rejects it. At runtime, all\n    // reads/writes are confined to the base backend.\n    return this.base.runTransaction(fn);\n  }\n\n  createBatch(): BatchBackend {\n    // Same constraint as transactions: `BatchBackend` has no `subgraph()`\n    // so all buffered ops target the base backend. The router itself\n    // doesn't need to guard anything here.\n    return this.base.createBatch();\n  }\n\n  // --- Subgraphs: the only method that actually routes ---\n\n  subgraph(parentNodeUid: string, name: string): StorageBackend {\n    assertValidSubgraphArgs(parentNodeUid, name);\n\n    const childScopePath = this.scopePath ? `${this.scopePath}/${name}` : name;\n    const childStorageScope = this.storageScope\n      ? `${this.storageScope}/${parentNodeUid}/${name}`\n      : `${parentNodeUid}/${name}`;\n\n    const routed = this.options.route({\n      parentUid: parentNodeUid,\n      subgraphName: name,\n      scopePath: childScopePath,\n      storageScope: childStorageScope,\n    });\n\n    if (routed) {\n      // The user returned a different backend. We still wrap it so that\n      // further `.subgraph()` calls on the returned child continue to\n      // consult the router. The routed backend's own `scopePath` / storage\n      // layout is its business — for routing purposes we carry *our*\n      // logical view forward (`childScopePath`) so grandchildren see a\n      // correct context regardless of what `routed.scopePath` happens to\n      // be (typically `''` for a freshly-minted per-DO backend).\n      return new RoutingStorageBackend(routed, this.options, childStorageScope, childScopePath);\n    }\n\n    // No route — delegate to the base backend and keep routing in effect\n    // for grandchildren.\n    const childBase = this.base.subgraph(parentNodeUid, name);\n    return new RoutingStorageBackend(childBase, this.options, childStorageScope, childScopePath);\n  }\n\n  // --- Bulk operations: delegate, but cascade is base-scope only ---\n\n  removeNodeCascade(\n    uid: string,\n    reader: GraphReader,\n    options?: BulkOptions,\n  ): Promise<CascadeResult> {\n    // `removeNodeCascade` on the base backend cannot see rows that live\n    // in routed child backends — each routed backend is a different\n    // physical store. Callers with routed subgraphs under `uid` are\n    // responsible for cascading those themselves (see routing.md).\n    return this.base.removeNodeCascade(uid, reader, options);\n  }\n\n  bulkRemoveEdges(\n    params: FindEdgesParams,\n    reader: GraphReader,\n    options?: BulkOptions,\n  ): Promise<BulkResult> {\n    return this.base.bulkRemoveEdges(params, reader, options);\n  }\n\n  // --- Collection-group queries are base-scope only ---\n  //\n  // `findEdgesGlobal` is installed in the constructor *only* when the base\n  // backend supports it, so `typeof router.findEdgesGlobal === 'function'`\n  // reflects the base's capability — matching the optional shape declared\n  // on `StorageBackend`.\n}\n\n/**\n * Wrap a `StorageBackend` so that `subgraph(parentUid, name)` calls can be\n * routed to a different backend based on a user-supplied callback.\n *\n * See the module docstring for the atomicity rules. In short: transactions\n * and batches opened on a routing backend run entirely on the *base*\n * backend — they cannot span routed children, by design.\n *\n * @example\n * ```ts\n * // `base` is any StorageBackend — e.g. a Firestore-backed one, an\n * // in-process SQLite backend, or the DO backend from firegraph/cloudflare.\n * const routed = createRoutingBackend(base, {\n *   route: ({ subgraphName, storageScope }) => {\n *     if (subgraphName !== 'memories') return null;\n *     return createMyMemoriesBackend(storageScope); // caller-owned\n *   },\n * });\n * const client = createGraphClientFromBackend(routed, { registry });\n * ```\n */\nexport function createRoutingBackend(\n  base: StorageBackend,\n  options: RoutingBackendOptions,\n): StorageBackend {\n  if (typeof options?.route !== 'function') {\n    throw new FiregraphError(\n      'createRoutingBackend: `options.route` must be a function.',\n      'INVALID_ARGUMENT',\n    );\n  }\n  return new RoutingStorageBackend(base, options, '', base.scopePath);\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/internal/routing-backend.ts"],"sourcesContent":["/**\n * Routing `StorageBackend` wrapper.\n *\n * `createRoutingBackend(base, { route })` returns a `StorageBackend` that\n * behaves identically to `base` except for `subgraph(parentUid, name)`:\n * each such call consults the caller-supplied `route` function, and if it\n * returns a non-null `StorageBackend`, that backend is used for the child\n * scope.\n *\n * This is the single seam firegraph ships for splitting a logical graph\n * across multiple physical storage backends — e.g. fanning particular\n * subgraph names out to their own Durable Objects to stay under the 10 GB\n * per-DO limit. The routing policy itself, the RPC protocol, and any\n * live-scope index are left to the caller; firegraph only owns the\n * composition primitive and the invariants that come with it.\n *\n * ## Contract — nested routing\n *\n * Whether `route()` returns a routed backend OR `null` (pass-through), the\n * child returned by `subgraph()` is **always** itself wrapped by the same\n * router. Without that self-wrap, a call chain like\n *\n * ```ts\n * router.subgraph(A, 'memories').subgraph(B, 'context')\n * ```\n *\n * would route the first hop correctly but bypass the router on the second\n * hop (since the routed backend's own `.subgraph()` doesn't know about the\n * caller's policy). Keeping routing active through grandchildren is the\n * load-bearing behaviour; `'continues routing on grandchildren …'` in the\n * unit tests locks it in.\n *\n * ## Contract — `route` is synchronous\n *\n * `.subgraph()` is synchronous in firegraph's public API. Making the\n * routing callback async would require rippling Promises through every\n * client-factory call site. Consequence: `route` can only consult data it\n * already has in hand (DO bindings, naming rules, in-memory caches). If\n * you need \"does this DO exist?\" checks, do them lazily — the first read\n * against the returned backend will surface the failure naturally.\n *\n * ## Contract — cross-backend atomicity is not silently degraded\n *\n * The wrapper's `runTransaction` and `createBatch` delegate to `base` —\n * they run entirely on the base backend. `TransactionBackend` and\n * `BatchBackend` deliberately have no `subgraph()` method, so user code\n * physically cannot open a routed child from inside a transaction\n * callback. Any attempt to bypass that (via `as any` / unchecked casts)\n * should surface as `CrossBackendTransactionError` so app code can catch\n * it cleanly — the error type is part of the public surface.\n *\n * ## Contract — `findEdgesGlobal` is base-scope only\n *\n * When delegated, `findEdgesGlobal` runs against the base backend only.\n * It does **not** fan out to routed children — firegraph has no\n * enumeration index for which routed backends exist. Callers who need\n * cross-shard collection-group queries must maintain their own scope\n * directory and query it directly. This keeps the common case (local\n * analytics inside one DO) fast.\n */\n\nimport { FiregraphError } from '../errors.js';\nimport type {\n  BulkOptions,\n  BulkResult,\n  CascadeResult,\n  FindEdgesParams,\n  GraphReader,\n  QueryFilter,\n  QueryOptions,\n  StoredGraphRecord,\n} from '../types.js';\nimport type {\n  BatchBackend,\n  StorageBackend,\n  TransactionBackend,\n  UpdatePayload,\n  WritableRecord,\n  WriteMode,\n} from './backend.js';\n\n/**\n * Context passed to a routing callback when `subgraph(parentUid, name)` is\n * called on a routed backend. All four strings describe the *child* scope\n * the caller is requesting, so the router can key its decision off whichever\n * representation is most convenient:\n *\n *   - `parentUid` / `subgraphName` — the arguments just passed to `subgraph()`.\n *   - `scopePath` — logical, names-only chain (`'memories'`, `'memories/context'`).\n *     This is what `allowedIn` patterns match against.\n *   - `storageScope` — the materialized-path form (`'A/memories'`,\n *     `'A/memories/B/context'`), suitable for use as a DO name or shard key\n *     because it's globally unique within a root graph.\n */\nexport interface RoutingContext {\n  parentUid: string;\n  subgraphName: string;\n  scopePath: string;\n  storageScope: string;\n}\n\nexport interface RoutingBackendOptions {\n  /**\n   * Decide whether a `subgraph(parentUid, name)` call should route to a\n   * different backend. Return the target backend to route; return `null`\n   * (or `undefined`) to fall through to the wrapped base backend.\n   *\n   * The returned backend is itself wrapped by the same router so that\n   * nested `.subgraph()` calls on the returned child continue to be\n   * consulted.\n   */\n  route: (ctx: RoutingContext) => StorageBackend | null | undefined;\n}\n\nfunction assertValidSubgraphArgs(parentNodeUid: string, name: string): void {\n  if (!parentNodeUid || parentNodeUid.includes('/')) {\n    throw new FiregraphError(\n      `Invalid parentNodeUid for subgraph: \"${parentNodeUid}\". ` +\n        'Must be a non-empty string without \"/\".',\n      'INVALID_SUBGRAPH',\n    );\n  }\n  if (!name || name.includes('/')) {\n    throw new FiregraphError(\n      `Subgraph name must not contain \"/\" and must be non-empty: got \"${name}\". ` +\n        'Use chained .subgraph() calls for nested subgraphs.',\n      'INVALID_SUBGRAPH',\n    );\n  }\n}\n\nclass RoutingStorageBackend implements StorageBackend {\n  readonly collectionPath: string;\n  /**\n   * Logical (names-only) scope path for *this* wrapper. Tracked\n   * independently of `base.scopePath` because a routed backend returned by\n   * `options.route()` typically represents its own physical root and has\n   * no knowledge of the caller's logical chain. The wrapper is the\n   * authoritative source of the logical scope for routing decisions and\n   * for satisfying the `StorageBackend.scopePath` contract surfaced to\n   * client code.\n   */\n  readonly scopePath: string;\n  /**\n   * Materialized-path form of `scopePath` — interleaved `<uid>/<name>`\n   * pairs. Not a property on the underlying `StorageBackend` interface\n   * (Firestore doesn't produce one), so we track it ourselves from\n   * `.subgraph()` arguments. Root routers start with `''`.\n   */\n  private readonly storageScope: string;\n  /**\n   * Conditionally installed in the constructor — only present when the\n   * wrapped base backend supports it. Declared as an optional instance\n   * property (rather than a prototype method) so `typeof router.findEdgesGlobal\n   * === 'function'` reflects the base's capability, matching the optional\n   * shape in the `StorageBackend` interface.\n   */\n  findEdgesGlobal?: StorageBackend['findEdgesGlobal'];\n\n  constructor(\n    private readonly base: StorageBackend,\n    private readonly options: RoutingBackendOptions,\n    storageScope: string,\n    logicalScopePath: string,\n  ) {\n    this.collectionPath = base.collectionPath;\n    this.scopePath = logicalScopePath;\n    this.storageScope = storageScope;\n    if (base.findEdgesGlobal) {\n      // We deliberately do *not* fan out across routed children: we have no\n      // enumeration index for which backends exist. Callers needing\n      // cross-shard collection-group queries must maintain their own index.\n      this.findEdgesGlobal = (params, collectionName) =>\n        base.findEdgesGlobal!(params, collectionName);\n    }\n  }\n\n  // --- Pass-through reads ---\n\n  getDoc(docId: string): Promise<StoredGraphRecord | null> {\n    return this.base.getDoc(docId);\n  }\n\n  query(filters: QueryFilter[], options?: QueryOptions): Promise<StoredGraphRecord[]> {\n    return this.base.query(filters, options);\n  }\n\n  // --- Pass-through writes ---\n\n  setDoc(docId: string, record: WritableRecord, mode: WriteMode): Promise<void> {\n    return this.base.setDoc(docId, record, mode);\n  }\n\n  updateDoc(docId: string, update: UpdatePayload): Promise<void> {\n    return this.base.updateDoc(docId, update);\n  }\n\n  deleteDoc(docId: string): Promise<void> {\n    return this.base.deleteDoc(docId);\n  }\n\n  // --- Transactions / batches run against the base backend only ---\n\n  runTransaction<T>(fn: (tx: TransactionBackend) => Promise<T>): Promise<T> {\n    // Transactions cannot span base + routed backends (different DBs /\n    // DOs / Firestore projects). `TransactionBackend` has no `subgraph()`\n    // method, so the user physically cannot open a routed child from\n    // inside the callback — the compiler rejects it. At runtime, all\n    // reads/writes are confined to the base backend.\n    return this.base.runTransaction(fn);\n  }\n\n  createBatch(): BatchBackend {\n    // Same constraint as transactions: `BatchBackend` has no `subgraph()`\n    // so all buffered ops target the base backend. The router itself\n    // doesn't need to guard anything here.\n    return this.base.createBatch();\n  }\n\n  // --- Subgraphs: the only method that actually routes ---\n\n  subgraph(parentNodeUid: string, name: string): StorageBackend {\n    assertValidSubgraphArgs(parentNodeUid, name);\n\n    const childScopePath = this.scopePath ? `${this.scopePath}/${name}` : name;\n    const childStorageScope = this.storageScope\n      ? `${this.storageScope}/${parentNodeUid}/${name}`\n      : `${parentNodeUid}/${name}`;\n\n    const routed = this.options.route({\n      parentUid: parentNodeUid,\n      subgraphName: name,\n      scopePath: childScopePath,\n      storageScope: childStorageScope,\n    });\n\n    if (routed) {\n      // The user returned a different backend. We still wrap it so that\n      // further `.subgraph()` calls on the returned child continue to\n      // consult the router. The routed backend's own `scopePath` / storage\n      // layout is its business — for routing purposes we carry *our*\n      // logical view forward (`childScopePath`) so grandchildren see a\n      // correct context regardless of what `routed.scopePath` happens to\n      // be (typically `''` for a freshly-minted per-DO backend).\n      return new RoutingStorageBackend(routed, this.options, childStorageScope, childScopePath);\n    }\n\n    // No route — delegate to the base backend and keep routing in effect\n    // for grandchildren.\n    const childBase = this.base.subgraph(parentNodeUid, name);\n    return new RoutingStorageBackend(childBase, this.options, childStorageScope, childScopePath);\n  }\n\n  // --- Bulk operations: delegate, but cascade is base-scope only ---\n\n  removeNodeCascade(\n    uid: string,\n    reader: GraphReader,\n    options?: BulkOptions,\n  ): Promise<CascadeResult> {\n    // `removeNodeCascade` on the base backend cannot see rows that live\n    // in routed child backends — each routed backend is a different\n    // physical store. Callers with routed subgraphs under `uid` are\n    // responsible for cascading those themselves (see routing.md).\n    return this.base.removeNodeCascade(uid, reader, options);\n  }\n\n  bulkRemoveEdges(\n    params: FindEdgesParams,\n    reader: GraphReader,\n    options?: BulkOptions,\n  ): Promise<BulkResult> {\n    return this.base.bulkRemoveEdges(params, reader, options);\n  }\n\n  // --- Collection-group queries are base-scope only ---\n  //\n  // `findEdgesGlobal` is installed in the constructor *only* when the base\n  // backend supports it, so `typeof router.findEdgesGlobal === 'function'`\n  // reflects the base's capability — matching the optional shape declared\n  // on `StorageBackend`.\n}\n\n/**\n * Wrap a `StorageBackend` so that `subgraph(parentUid, name)` calls can be\n * routed to a different backend based on a user-supplied callback.\n *\n * See the module docstring for the atomicity rules. In short: transactions\n * and batches opened on a routing backend run entirely on the *base*\n * backend — they cannot span routed children, by design.\n *\n * @example\n * ```ts\n * // `base` is any StorageBackend — e.g. a Firestore-backed one, an\n * // in-process SQLite backend, or the DO backend from firegraph/cloudflare.\n * const routed = createRoutingBackend(base, {\n *   route: ({ subgraphName, storageScope }) => {\n *     if (subgraphName !== 'memories') return null;\n *     return createMyMemoriesBackend(storageScope); // caller-owned\n *   },\n * });\n * const client = createGraphClientFromBackend(routed, { registry });\n * ```\n */\nexport function createRoutingBackend(\n  base: StorageBackend,\n  options: RoutingBackendOptions,\n): StorageBackend {\n  if (typeof options?.route !== 'function') {\n    throw new FiregraphError(\n      'createRoutingBackend: `options.route` must be a function.',\n      'INVALID_ARGUMENT',\n    );\n  }\n  return new RoutingStorageBackend(base, options, '', base.scopePath);\n}\n"],"mappings":"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","names":[]}

package/dist/chunk-AWW4MUJ5.js

@@ -0,0 +1,245 @@
+import {
+  SERIALIZATION_TAG,
+  isTaggedValue
+} from "./chunk-EQJUUVFG.js";
+
+// src/errors.ts
+var FiregraphError = class extends Error {
+  constructor(message, code) {
+    super(message);
+    this.code = code;
+    this.name = "FiregraphError";
+  }
+};
+var NodeNotFoundError = class extends FiregraphError {
+  constructor(uid) {
+    super(`Node not found: ${uid}`, "NODE_NOT_FOUND");
+    this.name = "NodeNotFoundError";
+  }
+};
+var EdgeNotFoundError = class extends FiregraphError {
+  constructor(aUid, axbType, bUid) {
+    super(`Edge not found: ${aUid} -[${axbType}]-> ${bUid}`, "EDGE_NOT_FOUND");
+    this.name = "EdgeNotFoundError";
+  }
+};
+var ValidationError = class extends FiregraphError {
+  constructor(message, details) {
+    super(message, "VALIDATION_ERROR");
+    this.details = details;
+    this.name = "ValidationError";
+  }
+};
+var RegistryViolationError = class extends FiregraphError {
+  constructor(aType, axbType, bType) {
+    super(`Unregistered triple: (${aType}) -[${axbType}]-> (${bType})`, "REGISTRY_VIOLATION");
+    this.name = "RegistryViolationError";
+  }
+};
+var InvalidQueryError = class extends FiregraphError {
+  constructor(message) {
+    super(message, "INVALID_QUERY");
+    this.name = "InvalidQueryError";
+  }
+};
+var TraversalError = class extends FiregraphError {
+  constructor(message) {
+    super(message, "TRAVERSAL_ERROR");
+    this.name = "TraversalError";
+  }
+};
+var DynamicRegistryError = class extends FiregraphError {
+  constructor(message) {
+    super(message, "DYNAMIC_REGISTRY_ERROR");
+    this.name = "DynamicRegistryError";
+  }
+};
+var QuerySafetyError = class extends FiregraphError {
+  constructor(message) {
+    super(message, "QUERY_SAFETY");
+    this.name = "QuerySafetyError";
+  }
+};
+var RegistryScopeError = class extends FiregraphError {
+  constructor(aType, axbType, bType, scopePath, allowedIn) {
+    super(
+      `Type (${aType}) -[${axbType}]-> (${bType}) is not allowed at scope "${scopePath || "root"}". Allowed in: [${allowedIn.join(", ")}]`,
+      "REGISTRY_SCOPE"
+    );
+    this.name = "RegistryScopeError";
+  }
+};
+var MigrationError = class extends FiregraphError {
+  constructor(message) {
+    super(message, "MIGRATION_ERROR");
+    this.name = "MigrationError";
+  }
+};
+var CrossBackendTransactionError = class extends FiregraphError {
+  constructor(message) {
+    super(message, "CROSS_BACKEND_TRANSACTION");
+    this.name = "CrossBackendTransactionError";
+  }
+};
+
+// 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 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);
+  }
+}
+
+export {
+  FiregraphError,
+  NodeNotFoundError,
+  EdgeNotFoundError,
+  ValidationError,
+  RegistryViolationError,
+  InvalidQueryError,
+  TraversalError,
+  DynamicRegistryError,
+  QuerySafetyError,
+  RegistryScopeError,
+  MigrationError,
+  CrossBackendTransactionError,
+  DELETE_FIELD,
+  deleteField,
+  isDeleteSentinel,
+  assertUpdatePayloadExclusive,
+  assertNoDeleteSentinels,
+  assertSafePath,
+  flattenPatch
+};
+//# sourceMappingURL=chunk-AWW4MUJ5.js.map

package/dist/chunk-AWW4MUJ5.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts","../src/internal/write-plan.ts"],"sourcesContent":["export class FiregraphError extends Error {\n  constructor(\n    message: string,\n    public readonly code: string,\n  ) {\n    super(message);\n    this.name = 'FiregraphError';\n  }\n}\n\nexport class NodeNotFoundError extends FiregraphError {\n  constructor(uid: string) {\n    super(`Node not found: ${uid}`, 'NODE_NOT_FOUND');\n    this.name = 'NodeNotFoundError';\n  }\n}\n\nexport class EdgeNotFoundError extends FiregraphError {\n  constructor(aUid: string, axbType: string, bUid: string) {\n    super(`Edge not found: ${aUid} -[${axbType}]-> ${bUid}`, 'EDGE_NOT_FOUND');\n    this.name = 'EdgeNotFoundError';\n  }\n}\n\nexport class ValidationError extends FiregraphError {\n  constructor(\n    message: string,\n    public readonly details?: unknown,\n  ) {\n    super(message, 'VALIDATION_ERROR');\n    this.name = 'ValidationError';\n  }\n}\n\nexport class RegistryViolationError extends FiregraphError {\n  constructor(aType: string, axbType: string, bType: string) {\n    super(`Unregistered triple: (${aType}) -[${axbType}]-> (${bType})`, 'REGISTRY_VIOLATION');\n    this.name = 'RegistryViolationError';\n  }\n}\n\nexport class InvalidQueryError extends FiregraphError {\n  constructor(message: string) {\n    super(message, 'INVALID_QUERY');\n    this.name = 'InvalidQueryError';\n  }\n}\n\nexport class TraversalError extends FiregraphError {\n  constructor(message: string) {\n    super(message, 'TRAVERSAL_ERROR');\n    this.name = 'TraversalError';\n  }\n}\n\nexport class DynamicRegistryError extends FiregraphError {\n  constructor(message: string) {\n    super(message, 'DYNAMIC_REGISTRY_ERROR');\n    this.name = 'DynamicRegistryError';\n  }\n}\n\nexport class QuerySafetyError extends FiregraphError {\n  constructor(message: string) {\n    super(message, 'QUERY_SAFETY');\n    this.name = 'QuerySafetyError';\n  }\n}\n\nexport class RegistryScopeError extends FiregraphError {\n  constructor(\n    aType: string,\n    axbType: string,\n    bType: string,\n    scopePath: string,\n    allowedIn: string[],\n  ) {\n    super(\n      `Type (${aType}) -[${axbType}]-> (${bType}) is not allowed at scope \"${scopePath || 'root'}\". ` +\n        `Allowed in: [${allowedIn.join(', ')}]`,\n      'REGISTRY_SCOPE',\n    );\n    this.name = 'RegistryScopeError';\n  }\n}\n\nexport class MigrationError extends FiregraphError {\n  constructor(message: string) {\n    super(message, 'MIGRATION_ERROR');\n    this.name = 'MigrationError';\n  }\n}\n\n/**\n * Thrown when a caller tries to perform an operation that would require\n * atomicity across two physical storage backends — e.g. opening a routed\n * subgraph client from inside a transaction callback. Cross-backend\n * atomicity cannot be honoured by real-world storage engines (Firestore,\n * SQLite drivers over D1/DO/better-sqlite3, etc.), so firegraph surfaces\n * this as a typed error instead of silently confining the write to the\n * base backend.\n *\n * Normally `TransactionBackend` and `BatchBackend` don't expose `subgraph()`\n * at the type level, so this error is unreachable through well-typed code.\n * It exists as a public catchable type for app code that needs to tolerate\n * this case deliberately (e.g. dynamic code paths that bypass the type\n * system) and as future-proofing if the interface ever grows a way to\n * request a sub-scope inside a transaction.\n */\nexport class CrossBackendTransactionError extends FiregraphError {\n  constructor(message: string) {\n    super(message, 'CROSS_BACKEND_TRANSACTION');\n    this.name = 'CrossBackendTransactionError';\n  }\n}\n","/**\n * Write-plan helper — flattens partial-update payloads into a list of\n * deep-path operations every backend can execute identically.\n *\n * Background: firegraph used to ship two write semantics that quietly\n * disagreed about depth.\n *   - `putNode`/`putEdge` did a full document replace.\n *   - `updateNode`/`updateEdge` did a one-level shallow merge: top-level\n *     keys were preserved, but nested objects were replaced wholesale.\n *\n * Both behaviours dropped sibling keys silently. The 0.12 contract is that\n * `put*` and `update*` deep-merge by default (sibling keys at any depth\n * survive); `replace*` is the explicit escape hatch.\n *\n * `flattenPatch` walks a partial-update payload and emits one\n * {@link DataPathOp} per terminal value. Plain objects recurse; arrays,\n * primitives, Firestore special types, and tagged firegraph-serialization\n * objects are terminal (replaced as a unit). `undefined` values are\n * skipped; `null` is preserved as a real `null` write; the\n * {@link DELETE_FIELD} sentinel marks a field for removal.\n *\n * The output is deliberately backend-agnostic. Each backend translates ops\n * into its native dialect:\n *   - Firestore: dotted field path → `data.a.b.c` for `update()`.\n *   - SQLite / DO SQLite: `json_set(data, '$.a.b.c', ?)` /\n *     `json_remove(data, '$.a.b.c')`.\n */\n\nimport { isTaggedValue, SERIALIZATION_TAG } from './serialization-tag.js';\n\n// ---------------------------------------------------------------------------\n// Public sentinel\n// ---------------------------------------------------------------------------\n\n/**\n * Sentinel returned by {@link deleteField}. Treated by all backends as\n * \"remove this field from the stored document\".\n *\n * Equivalent to Firestore's `FieldValue.delete()`, but works for SQLite\n * backends too. Use inside `updateNode`/`updateEdge` payloads.\n */\nexport const DELETE_FIELD: unique symbol = Symbol.for('firegraph.deleteField');\nexport type DeleteSentinel = typeof DELETE_FIELD;\n\n/**\n * Returns the firegraph delete sentinel. Place this anywhere in an\n * `updateNode`/`updateEdge` payload to remove the corresponding field.\n *\n * ```ts\n * await client.updateNode('tour', uid, {\n *   attrs: { obsoleteFlag: deleteField() },\n * });\n * ```\n */\nexport function deleteField(): DeleteSentinel {\n  return DELETE_FIELD;\n}\n\n/** Type guard for the delete sentinel. */\nexport function isDeleteSentinel(value: unknown): value is DeleteSentinel {\n  return value === DELETE_FIELD;\n}\n\n// ---------------------------------------------------------------------------\n// Terminal-detection helpers\n// ---------------------------------------------------------------------------\n\nconst FIRESTORE_TERMINAL_CTOR = new Set([\n  'Timestamp',\n  'GeoPoint',\n  'VectorValue',\n  'DocumentReference',\n  'FieldValue',\n  'NumericIncrementTransform',\n  'ArrayUnionTransform',\n  'ArrayRemoveTransform',\n  'ServerTimestampTransform',\n  'DeleteTransform',\n]);\n\n/**\n * Should this value be written as a single terminal op (no recursion)?\n *\n * Plain JS objects (constructor === Object, or no prototype) are recursed.\n * Everything else — arrays, primitives, class instances, Firestore special\n * types, tagged serialization payloads — is terminal.\n */\nexport function isTerminalValue(value: unknown): boolean {\n  if (value === null) return true;\n  const t = typeof value;\n  if (t !== 'object') return true;\n  if (Array.isArray(value)) return true;\n  // Tagged serialization payloads carry the SERIALIZATION_TAG sentinel and\n  // should be persisted whole — never split into per-field ops.\n  if (isTaggedValue(value)) return true;\n  const proto = Object.getPrototypeOf(value);\n  if (proto === null || proto === Object.prototype) return false;\n  // Class instances — Firestore types or anything else exotic.\n  const ctor = (value as { constructor?: { name?: string } }).constructor;\n  if (ctor && typeof ctor.name === 'string' && FIRESTORE_TERMINAL_CTOR.has(ctor.name)) return true;\n  // Unknown class instance: treat as terminal. Recursing into a class\n  // instance is almost always wrong (Map, Set, Date, Buffer...).\n  return true;\n}\n\n// ---------------------------------------------------------------------------\n// Core type\n// ---------------------------------------------------------------------------\n\n/**\n * Single terminal write operation produced by {@link flattenPatch}.\n *\n * `path` is a non-empty array of plain object keys. `value` is the value to\n * write; ignored when `delete` is `true`. Arrays / primitives / Firestore\n * special types appear here as whole terminal values.\n */\nexport interface DataPathOp {\n  path: readonly string[];\n  value: unknown;\n  delete: boolean;\n}\n\n// ---------------------------------------------------------------------------\n// Path-segment validation\n// ---------------------------------------------------------------------------\n\n/**\n * Object keys that are safe to embed in SQLite `json_set`/`json_remove`\n * paths. The SQLite backend uses an allowlist regex too — keep these in\n * sync (see `JSON_PATH_KEY_RE` in `internal/sqlite-sql.ts` and\n * `cloudflare/sql.ts`).\n *\n * Allows: ASCII letters, digits, `_`, `-`. Must start with a letter or\n * underscore. This rejects keys containing dots, brackets, quotes, or\n * non-ASCII characters that could break path parsing or be used to\n * inject into the path expression.\n */\nconst SAFE_KEY_RE = /^[A-Za-z_][A-Za-z0-9_-]*$/;\n\n/**\n * Mutual-exclusion guard for {@link UpdatePayload}. The two branches of the\n * shape — `dataOps` (deep-merge) and `replaceData` (full replace) — are\n * structurally incompatible: combining them would tell the backend to\n * simultaneously merge AND wipe, and the three backends disagree on which\n * wins. This helper centralises the runtime check so all three backends\n * trip the same error.\n *\n * Imported as a runtime check from `firestore-backend`, `sqlite-sql`, and\n * `cloudflare/sql`. Backend authors implementing the public `StorageBackend`\n * contract should call it too.\n */\nexport function assertUpdatePayloadExclusive(update: {\n  dataOps?: unknown;\n  replaceData?: unknown;\n}): void {\n  if (update.replaceData !== undefined && update.dataOps !== undefined) {\n    throw new Error(\n      'firegraph: UpdatePayload cannot specify both `replaceData` and `dataOps`. ' +\n        'Use one or the other — `replaceData` is the migration-write-back form, ' +\n        '`dataOps` is the standard partial-update form.',\n    );\n  }\n}\n\n/**\n * Reject `DELETE_FIELD` sentinels in payloads where field deletion isn't a\n * meaningful operation: full-document replace (`replaceNode`/`replaceEdge`)\n * and the merge-default put surface (`putNode`/`putEdge`).\n *\n * Why both:\n *   - In **replace**, the entire `data` field is overwritten. A delete\n *     sentinel in that payload either silently disappears (Firestore drops\n *     the Symbol during `.set()` serialization) or produces an empty SQLite\n *     `json_remove` no-op, depending on backend. Either way the caller's\n *     intent — \"remove field X\" — is lost. Use `updateNode` instead.\n *   - In **put** (merge mode), behaviour diverges across backends today:\n *     SQLite's flattenPatch emits a real delete op, but Firestore's\n *     `.set(..., {merge: true})` silently drops the Symbol. Until that's\n *     fixed end-to-end, the safest contract is to reject sentinels at the\n *     entry point and steer callers to `updateNode`.\n *\n * The walk mirrors `flattenPatch`: plain objects recurse, everything else\n * is terminal. Tagged serialization payloads short-circuit so we don't\n * recurse into the `__firegraph_ser__` envelope.\n */\nexport function assertNoDeleteSentinels(data: unknown, callerLabel: string): void {\n  walkForDeleteSentinels(data, [], { kind: 'root' }, ({ path }) => {\n    const where = path.length === 0 ? '<root>' : path.map((p) => JSON.stringify(p)).join(' > ');\n    throw new Error(\n      `firegraph: ${callerLabel} payload contains a deleteField() sentinel at ${where}. ` +\n        `deleteField() is only valid inside updateNode/updateEdge — full-data ` +\n        `writes (put*, replace*) cannot delete individual fields. Use updateNode ` +\n        `with a deleteField() value, or omit the field from the replace payload.`,\n    );\n  });\n}\n\ntype SentinelParent = { kind: 'root' } | { kind: 'object' } | { kind: 'array'; index: number };\n\nfunction walkForDeleteSentinels(\n  node: unknown,\n  path: readonly string[],\n  parent: SentinelParent,\n  visit: (ctx: { path: readonly string[]; parent: SentinelParent }) => void,\n): void {\n  if (node === null || node === undefined) return;\n  if (isDeleteSentinel(node)) {\n    visit({ path, parent });\n    return;\n  }\n  if (typeof node !== 'object') return;\n  if (isTaggedValue(node)) return;\n  if (Array.isArray(node)) {\n    for (let i = 0; i < node.length; i++) {\n      walkForDeleteSentinels(node[i], [...path, String(i)], { kind: 'array', index: i }, visit);\n    }\n    return;\n  }\n  const proto = Object.getPrototypeOf(node);\n  if (proto !== null && proto !== Object.prototype) return;\n  const obj = node as Record<string, unknown>;\n  for (const key of Object.keys(obj)) {\n    walkForDeleteSentinels(obj[key], [...path, key], { kind: 'object' }, visit);\n  }\n}\n\n/** Throws if any path segment in the patch is unsafe for SQLite paths. */\nexport function assertSafePath(path: readonly string[]): void {\n  for (const seg of path) {\n    if (!SAFE_KEY_RE.test(seg)) {\n      throw new Error(\n        `firegraph: unsafe object key ${JSON.stringify(seg)} at path ${path\n          .map((p) => JSON.stringify(p))\n          .join(' > ')}. Keys used inside update payloads must match ` +\n          `/^[A-Za-z_][A-Za-z0-9_-]*$/ so they can be embedded safely in ` +\n          `SQLite JSON paths.`,\n      );\n    }\n  }\n}\n\n// ---------------------------------------------------------------------------\n// flattenPatch\n// ---------------------------------------------------------------------------\n\n/**\n * Flatten a partial-update payload into a list of terminal {@link DataPathOp}s.\n *\n * Rules:\n *   - Plain objects (no prototype or `Object.prototype`) recurse — each\n *     key becomes another path segment.\n *   - Arrays are terminal: writing `{tags: ['a']}` overwrites the whole\n *     `tags` array. Element-wise array merging is intentionally NOT\n *     supported — it's almost never what callers actually want, and\n *     Firestore `arrayUnion`/`arrayRemove` give precise semantics when\n *     they are.\n *   - `undefined` values are skipped (no op generated). Use\n *     {@link deleteField} if you actually want to remove a field.\n *   - `null` is preserved verbatim — emits a terminal op with `value: null`.\n *   - {@link DELETE_FIELD} produces an op with `delete: true`.\n *   - Firestore special types and tagged serialization payloads are terminal.\n *   - Class instances are terminal.\n *\n * Throws if any object key on the recursion path is unsafe (see\n * {@link assertSafePath}).\n */\nexport function flattenPatch(data: Record<string, unknown>): DataPathOp[] {\n  const ops: DataPathOp[] = [];\n  walk(data, [], ops);\n  return ops;\n}\n\nfunction assertNoDeleteSentinelsInArrayValue(\n  arr: readonly unknown[],\n  arrayPath: readonly string[],\n): void {\n  walkForDeleteSentinels(arr, arrayPath, { kind: 'root' }, ({ parent }) => {\n    const arrayPathStr =\n      arrayPath.length === 0 ? '<root>' : arrayPath.map((p) => JSON.stringify(p)).join(' > ');\n    if (parent.kind === 'array') {\n      throw new Error(\n        `firegraph: deleteField() sentinel at index ${parent.index} inside an array at ` +\n          `path ${arrayPathStr}. Arrays are ` +\n          `terminal in update payloads (replaced as a unit), so the sentinel ` +\n          `would be silently dropped by JSON serialization. To remove the ` +\n          `field entirely, pass deleteField() in place of the whole array.`,\n      );\n    }\n    throw new Error(\n      `firegraph: deleteField() sentinel inside an array element at ` +\n        `path ${arrayPathStr}. ` +\n        `Arrays are terminal in update payloads — the sentinel would ` +\n        `be silently dropped by JSON serialization.`,\n    );\n  });\n}\n\nfunction walk(node: unknown, path: string[], out: DataPathOp[]): void {\n  // Caller guarantees the root is a plain object; this branch only\n  // matters for recursion.\n  if (node === undefined) return;\n  if (isDeleteSentinel(node)) {\n    if (path.length === 0) {\n      throw new Error('firegraph: deleteField() cannot be the entire update payload.');\n    }\n    assertSafePath(path);\n    out.push({ path: [...path], value: undefined, delete: true });\n    return;\n  }\n  if (isTerminalValue(node)) {\n    if (path.length === 0) {\n      // `null` / array / primitive at the root is illegal — patches must\n      // describe per-key changes.\n      throw new Error(\n        'firegraph: update payload must be a plain object. Got ' +\n          (node === null ? 'null' : Array.isArray(node) ? 'array' : typeof node) +\n          '.',\n      );\n    }\n    // A DELETE_FIELD sentinel embedded inside an array (which is terminal\n    // and replaced as a unit) would silently disappear: JSON.stringify drops\n    // Symbols, and Firestore's serializer does likewise. Reject loudly so\n    // the divergence between \"user wrote a delete\" and \"field stayed put\"\n    // can't happen.\n    if (Array.isArray(node)) {\n      assertNoDeleteSentinelsInArrayValue(node, path);\n    }\n    assertSafePath(path);\n    out.push({ path: [...path], value: node, delete: false });\n    return;\n  }\n  // Plain object: recurse into its own enumerable keys.\n  const obj = node as Record<string, unknown>;\n  const keys = Object.keys(obj);\n  if (keys.length === 0) {\n    // Empty object at non-root: emit terminal op so an empty object can\n    // be written explicitly when the caller really wants one. Skip at\n    // the root — no-op patches should produce no ops.\n    if (path.length > 0) {\n      assertSafePath(path);\n      out.push({ path: [...path], value: {}, delete: false });\n    }\n    return;\n  }\n  for (const key of keys) {\n    if (key === SERIALIZATION_TAG) {\n      const where = path.length === 0 ? '<root>' : path.map((p) => JSON.stringify(p)).join(' > ');\n      throw new Error(\n        `firegraph: update payload contains a literal \\`${SERIALIZATION_TAG}\\` key at ` +\n          `${where}. That key is reserved for firegraph's serialization envelope and ` +\n          `cannot appear on a plain object in user data. Use a different field name, ` +\n          `or pass a recognized tagged value through replaceNode/replaceEdge instead.`,\n      );\n    }\n    walk(obj[key], [...path, key], out);\n  }\n}\n"],"mappings":"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","names":[]}