@typicalday/firegraph 0.11.2 → 0.13.0

package/dist/backend-DuvHGgK1.d.cts

@@ -0,0 +1,1897 @@
+import { WhereFilterOp, Timestamp, FieldValue } from '@google-cloud/firestore';
+
+/**
+ * Firegraph Configuration — project-level config file support.
+ *
+ * Projects create a `firegraph.config.ts` (or `.js`/`.mjs`) in their root:
+ *
+ * @example
+ * ```ts
+ * import { defineConfig } from 'firegraph';
+ *
+ * export default defineConfig({
+ *   entities: './entities',
+ *   project: 'my-project',
+ *   collection: 'graph',
+ * });
+ * ```
+ */
+
+/** Display contexts where views can appear. */
+type ViewContext = 'listing' | 'detail' | 'inline';
+/** View resolution configuration for a single entity type. */
+interface ViewResolverConfig {
+    /** Default view name (e.g. 'card'). Falls back to 'json' if unset. */
+    default?: string;
+    /** View to use in NodeBrowser listing rows. */
+    listing?: string;
+    /** View to use on the NodeDetail page. */
+    detail?: string;
+    /** View to use for inline/embedded previews (edge rows, traversal). */
+    inline?: string;
+}
+/** Declarative view defaults, keyed by entity type. */
+interface ViewDefaultsConfig {
+    /** Node view defaults keyed by aType (e.g. 'user', 'task'). */
+    nodes?: Record<string, ViewResolverConfig>;
+    /** Edge view defaults keyed by axbType (e.g. 'hasDeparture'). */
+    edges?: Record<string, ViewResolverConfig>;
+}
+/** Project-level firegraph configuration. */
+interface FiregraphConfig {
+    /** Path to entities directory (per-entity folder convention). */
+    entities?: string;
+    /** GCP project ID. */
+    project?: string;
+    /** Firestore collection path (default: 'graph'). */
+    collection?: string;
+    /** Firestore emulator address (e.g. '127.0.0.1:8080'). */
+    emulator?: string;
+    /**
+     * Query execution backend.
+     *
+     * - `'pipeline'` (default) — Uses Firestore Pipeline API. Requires Enterprise
+     *   Firestore. Enables indexless queries on `data.*` fields.
+     * - `'standard'` — Uses standard Firestore `.where().get()` queries. Not
+     *   recommended for production. See README for risk details.
+     *
+     * When the emulator is active, always falls back to `'standard'`.
+     */
+    queryMode?: QueryMode;
+    /**
+     * AI chat configuration. Auto-detects `claude` CLI on PATH by default.
+     * Set to `false` to disable chat even if claude is available.
+     */
+    chat?: false | {
+        /** Claude model to use (default: 'sonnet'). */
+        model?: string;
+        /** Maximum concurrent claude processes (default: 2). */
+        maxConcurrency?: number;
+    };
+    /** Editor-specific settings. */
+    editor?: {
+        /** Server port (default: 3883). */
+        port?: number;
+        /** Force read-only mode. */
+        readonly?: boolean;
+    };
+    /** Declarative view defaults per entity type (overrides per-entity meta.json). */
+    viewDefaults?: ViewDefaultsConfig;
+    /**
+     * Dynamic registry mode. When set, the editor loads type definitions
+     * from Firestore meta-nodes in addition to filesystem entities.
+     * Filesystem types take precedence on name conflicts.
+     */
+    registryMode?: DynamicRegistryConfig;
+}
+/**
+ * Identity function providing type-checking and autocomplete for config files.
+ *
+ * @example
+ * ```ts
+ * import { defineConfig } from 'firegraph';
+ * export default defineConfig({ entities: './entities' });
+ * ```
+ */
+declare function defineConfig(config: FiregraphConfig): FiregraphConfig;
+/**
+ * Resolve which view to show for a given entity.
+ *
+ * 1. If `context` is provided and a context-specific default exists, use it.
+ * 2. Falls back to `resolverConfig.default`.
+ * 3. Ultimate fallback: `'json'`.
+ *
+ * Only returns view names that exist in `availableViewNames`.
+ */
+declare function resolveView(resolverConfig: ViewResolverConfig | undefined, availableViewNames: string[], context?: ViewContext): string;
+
+/**
+ * Backend-agnostic timestamp.
+ *
+ * Structurally compatible with `@google-cloud/firestore`'s `Timestamp` so
+ * that records returned by either the Firestore or SQLite backend can be
+ * consumed through the same `StoredGraphRecord` shape.
+ *
+ * Firestore's native `Timestamp` already satisfies this interface, so
+ * existing Firestore consumers see no behavior change. The SQLite backend
+ * returns instances of `GraphTimestampImpl` which also satisfies it.
+ */
+interface GraphTimestamp {
+    readonly seconds: number;
+    readonly nanoseconds: number;
+    toDate(): Date;
+    toMillis(): number;
+}
+
+interface GraphRecord {
+    aType: string;
+    aUid: string;
+    axbType: string;
+    bType: string;
+    bUid: string;
+    data: Record<string, unknown>;
+    createdAt: Timestamp | FieldValue;
+    updatedAt: Timestamp | FieldValue;
+    /** Schema version — set automatically when the registry entry has migrations. */
+    v?: number;
+}
+interface StoredGraphRecord {
+    aType: string;
+    aUid: string;
+    axbType: string;
+    bType: string;
+    bUid: string;
+    data: Record<string, unknown>;
+    /**
+     * Backend-agnostic timestamp. Firestore returns its native `Timestamp`
+     * (which structurally satisfies `GraphTimestamp`); the SQLite backends
+     * return a `GraphTimestampImpl` instance.
+     */
+    createdAt: GraphTimestamp;
+    updatedAt: GraphTimestamp;
+    /** Schema version — set automatically when the registry entry has migrations. */
+    v?: number;
+}
+interface WhereClause {
+    field: string;
+    op: '==' | '!=' | '<' | '<=' | '>' | '>=';
+    value: unknown;
+}
+interface FindEdgesParams {
+    aType?: string;
+    aUid?: string;
+    axbType?: string;
+    bType?: string;
+    bUid?: string;
+    limit?: number;
+    orderBy?: {
+        field: string;
+        direction?: 'asc' | 'desc';
+    };
+    where?: WhereClause[];
+    /** Set to true to allow queries that may cause full collection scans. */
+    allowCollectionScan?: boolean;
+}
+interface FindNodesParams {
+    aType: string;
+    limit?: number;
+    orderBy?: {
+        field: string;
+        direction?: 'asc' | 'desc';
+    };
+    where?: WhereClause[];
+    /** Set to true to allow queries that may cause full collection scans. */
+    allowCollectionScan?: boolean;
+}
+interface QueryOptions {
+    limit?: number;
+    orderBy?: {
+        field: string;
+        direction?: 'asc' | 'desc';
+    };
+}
+type QueryPlan = {
+    strategy: 'get';
+    docId: string;
+} | {
+    strategy: 'query';
+    filters: QueryFilter[];
+    options?: QueryOptions;
+};
+interface QueryFilter {
+    field: string;
+    op: WhereFilterOp;
+    value: unknown;
+}
+/**
+ * Closed string-literal union of every logical capability a storage backend
+ * may declare. Capabilities express user-facing query features, not SDK
+ * details — the same logical capability may map to different SDK calls per
+ * backend (e.g. `query.aggregate` is `runAggregationQuery` on Firestore
+ * Standard, `pipeline().aggregate()` on Firestore Enterprise, `GROUP BY` on
+ * SQL).
+ *
+ * See `.claude/backend-capabilities.md` for the design rationale and the
+ * capability matrix per backend.
+ */
+type Capability = 'core.read' | 'core.write' | 'core.transactions' | 'core.batch' | 'core.subgraph' | 'query.aggregate' | 'query.select' | 'query.join' | 'query.dml' | 'traversal.serverSide' | 'search.fullText' | 'search.geo' | 'search.vector' | 'realtime.listen' | 'raw.firestore' | 'raw.sql';
+/**
+ * An executable migration function that transforms data from one schema
+ * version to the next. Can be synchronous or asynchronous.
+ */
+type MigrationFn = (data: Record<string, unknown>) => Record<string, unknown> | Promise<Record<string, unknown>>;
+/**
+ * A single migration step in a registry entry.
+ * Transforms data from `fromVersion` to `toVersion`.
+ */
+interface MigrationStep {
+    fromVersion: number;
+    toVersion: number;
+    up: MigrationFn;
+}
+/**
+ * A stored migration step for dynamic registry types.
+ * The `up` field is a source code string that will be compiled at runtime.
+ *
+ * @example
+ * ```ts
+ * { fromVersion: 0, toVersion: 1, up: "(data) => ({ ...data, status: 'draft' })" }
+ * ```
+ */
+interface StoredMigrationStep {
+    fromVersion: number;
+    toVersion: number;
+    up: string;
+}
+/**
+ * Pluggable executor interface for compiling migration function source
+ * strings into executable functions. Used for dynamic registry migrations.
+ *
+ * The default executor uses SES (Secure ECMAScript) Compartments with
+ * JSON marshaling for isolation. Users can supply an alternative via
+ * `GraphClientOptions.migrationSandbox`.
+ */
+type MigrationExecutor = (source: string) => MigrationFn;
+/** Write-back mode for auto-migrated records. */
+type MigrationWriteBack = 'off' | 'eager' | 'background';
+/**
+ * One field in a composite index. The string shorthand form defaults to
+ * ascending order; use the object form when a field needs to be indexed
+ * descending (e.g., pagination by `{ path: 'updatedAt', desc: true }`).
+ */
+interface IndexFieldSpec {
+    /**
+     * Field path. Top-level firegraph fields (`aType`, `aUid`, `axbType`,
+     * `bType`, `bUid`, `createdAt`, `updatedAt`, `v`) resolve to their
+     * underlying columns. Dotted paths like `'data.status'` or
+     * `'data.author.name'` index into the JSON data payload.
+     *
+     * Each dotted component must match `/^[A-Za-z_][A-Za-z0-9_-]*$/` — keys
+     * with dots, quotes, brackets, spaces, or other syntax characters are
+     * rejected at DDL build time. Indexes on exotic keys are not supported
+     * because SQLite expression indexes must match the query compiler's
+     * output verbatim, and inlining quoted path components into DDL would
+     * desynchronize the two compilers. If you need to filter by an exotic
+     * key, use `replaceNode` / `replaceEdge` writes rather than an indexed
+     * field.
+     */
+    path: string;
+    /** Descending order; defaults to ascending. */
+    desc?: boolean;
+}
+/**
+ * Declarative secondary index. Translators emit a `CREATE INDEX` statement
+ * (SQLite) or a `FirestoreIndex` composite (Firestore) per spec.
+ *
+ * Composite indexes support the prefix of their `fields` list — a spec
+ * `{ fields: ['aType', 'axbType'] }` also covers queries filtering on
+ * `aType` alone.
+ *
+ * @example
+ * ```ts
+ * // Plain composite on top-level fields
+ * { fields: ['aType', 'axbType'] }
+ *
+ * // Mixed string + object form; `updatedAt` descending
+ * { fields: ['aType', 'aUid', 'axbType', { path: 'updatedAt', desc: true }] }
+ *
+ * // JSON data-field index (SQLite: expression index on json_extract)
+ * { fields: ['aType', 'axbType', 'data.status'] }
+ *
+ * // Partial index (SQLite only — Firestore ignores the `where` clause)
+ * { fields: ['aType'], where: "json_extract(data, '$.archived') = 0" }
+ * ```
+ */
+interface IndexSpec {
+    /**
+     * Ordered field list. String shorthand = ascending. Use `IndexFieldSpec`
+     * form to mark individual fields descending.
+     */
+    fields: Array<string | IndexFieldSpec>;
+    /**
+     * Partial-index predicate. Applied verbatim after `WHERE` in the emitted
+     * SQLite DDL. Ignored (with a one-time warning) by the Firestore
+     * generator — Firestore composite indexes do not support predicates.
+     */
+    where?: string;
+}
+interface RegistryEntry {
+    aType: string;
+    axbType: string;
+    bType: string;
+    /** JSON Schema object for the data payload. */
+    jsonSchema?: object;
+    description?: string;
+    inverseLabel?: string;
+    /** Data field to use as the display title (e.g. 'name', 'date'). */
+    titleField?: string;
+    /** Data field to use as the display subtitle (e.g. 'status', 'difficulty'). */
+    subtitleField?: string;
+    /**
+     * Scope patterns constraining where this type can exist.
+     * Omit or leave empty to allow everywhere (backwards compatible).
+     *
+     * Patterns:
+     *   - `'root'`            — top-level collection only
+     *   - `'agents'`          — exact subgraph name match
+     *   - `'workflow/agents'`  — exact path match
+     *   - `'*​/agents'`        — `*` matches one segment
+     *   - `'**​/agents'`       — `**` matches zero or more segments
+     */
+    allowedIn?: string[];
+    /**
+     * Subgraph name where cross-graph edges of this type live.
+     *
+     * When set, forward traversal queries the named subgraph under each
+     * source node (e.g., `{collection}/{sourceUid}/{targetGraph}`) instead
+     * of the current collection. The subgraph contains both the edge
+     * documents and the target nodes they reference.
+     *
+     * Reverse traversal is unaffected — if you're already in the subgraph,
+     * the edges are local.
+     *
+     * Only applies to edge entries (not node self-loop entries).
+     * Must be a single segment (no `/`).
+     *
+     * @example
+     * ```ts
+     * { aType: 'task', axbType: 'assignedTo', bType: 'agent', targetGraph: 'workflow' }
+     * // Forward traversal from task1: queries {collection}/task1/workflow
+     * ```
+     */
+    targetGraph?: string;
+    /**
+     * Schema version for this type's data payload.
+     * **Computed automatically** from `migrations` as `max(toVersion)`.
+     * Do not set directly — provide migrations instead.
+     */
+    schemaVersion?: number;
+    /**
+     * Ordered list of migrations to transform data from older versions
+     * to the current version. The schema version is derived as the highest
+     * `toVersion` in this array.
+     */
+    migrations?: MigrationStep[];
+    /**
+     * Per-entry write-back override for auto-migrated records.
+     * Takes precedence over `GraphClientOptions.migrationWriteBack`.
+     * Omit to inherit the global setting.
+     */
+    migrationWriteBack?: MigrationWriteBack;
+    /**
+     * Secondary indexes tied to this triple. Each spec becomes a single
+     * backend-native composite index scoped to rows matching
+     * `(aType, axbType, bType)` — though the DDL does not currently restrict
+     * by triple, so authors should think of these as globally-applied indexes
+     * declared on the triple's behalf.
+     *
+     * Use this to accelerate `findNodes` / `findEdges` queries that filter
+     * on `data.*` fields or compose with firegraph's top-level fields in ways
+     * the default preset doesn't cover.
+     */
+    indexes?: IndexSpec[];
+}
+/** Topology declaration for an edge (from edge.json). */
+interface EdgeTopology {
+    from: string | string[];
+    to: string | string[];
+    inverseLabel?: string;
+    /**
+     * Subgraph name where cross-graph edges of this type live.
+     * See `RegistryEntry.targetGraph` for full documentation.
+     */
+    targetGraph?: string;
+}
+/** A discovered entity from the per-entity folder convention. */
+interface DiscoveredEntity {
+    kind: 'node' | 'edge';
+    name: string;
+    /** Parsed JSON Schema for the data payload. */
+    schema: object;
+    /** Edge topology (only for edges). */
+    topology?: EdgeTopology;
+    description?: string;
+    /** Data field to use as the display title (e.g. 'name', 'date'). */
+    titleField?: string;
+    /** Data field to use as the display subtitle (e.g. 'status', 'difficulty'). */
+    subtitleField?: string;
+    /** View defaults from meta.json. */
+    viewDefaults?: ViewResolverConfig;
+    /** Absolute path to views.ts if present. */
+    viewsPath?: string;
+    /** Sample data from sample.json. */
+    sampleData?: Record<string, unknown>;
+    /** Scope patterns constraining where this type can exist in subgraphs. */
+    allowedIn?: string[];
+    /** Subgraph name where cross-graph edges of this type live. */
+    targetGraph?: string;
+    /** Migration steps loaded from migrations.ts. */
+    migrations?: MigrationStep[];
+    /** Per-entity write-back override from meta.json. */
+    migrationWriteBack?: MigrationWriteBack;
+    /** Secondary indexes loaded from meta.json (`indexes` field). */
+    indexes?: IndexSpec[];
+}
+/** Result of scanning an entities directory. */
+interface DiscoveryResult {
+    nodes: Map<string, DiscoveredEntity>;
+    edges: Map<string, DiscoveredEntity>;
+}
+/** Controls which Firestore query backend is used. */
+type QueryMode = 'pipeline' | 'standard';
+/**
+ * Configuration for dynamic registry mode where type definitions
+ * are stored as graph data (meta-nodes) rather than in code.
+ */
+interface DynamicRegistryConfig {
+    mode: 'dynamic';
+    /**
+     * Collection path for meta-type nodes (`nodeType`, `edgeType`).
+     * Defaults to the main `collectionPath` if omitted.
+     */
+    collection?: string;
+}
+/** Options for defineNodeType / defineEdgeType beyond the core fields. */
+interface DefineTypeOptions {
+    /** Data field to use as the display title (e.g. 'name', 'date'). */
+    titleField?: string;
+    /** Data field to use as the display subtitle (e.g. 'status', 'difficulty'). */
+    subtitleField?: string;
+    /** Mustache HTML template for rendering this type in the editor. */
+    viewTemplate?: string;
+    /** Scoped CSS for the view template (injected via Shadow DOM). */
+    viewCss?: string;
+    /** Scope patterns constraining where this type can exist in subgraphs. */
+    allowedIn?: string[];
+    /**
+     * Migration steps. Accepts function objects (auto-serialized via .toString())
+     * or strings (stored as-is). The schema version is derived as the highest
+     * `toVersion` in this array.
+     */
+    migrations?: Array<{
+        fromVersion: number;
+        toVersion: number;
+        up: MigrationFn | string;
+    }>;
+    /** Per-type write-back override for auto-migrated records. */
+    migrationWriteBack?: MigrationWriteBack;
+}
+/** Data shape stored in a `nodeType` meta-node. */
+interface NodeTypeData {
+    name: string;
+    jsonSchema: object;
+    description?: string;
+    titleField?: string;
+    subtitleField?: string;
+    viewTemplate?: string;
+    viewCss?: string;
+    allowedIn?: string[];
+    migrations?: StoredMigrationStep[];
+    migrationWriteBack?: MigrationWriteBack;
+}
+/** Data shape stored in an `edgeType` meta-node. */
+interface EdgeTypeData {
+    name: string;
+    from: string | string[];
+    to: string | string[];
+    jsonSchema?: object;
+    inverseLabel?: string;
+    description?: string;
+    titleField?: string;
+    subtitleField?: string;
+    viewTemplate?: string;
+    viewCss?: string;
+    allowedIn?: string[];
+    targetGraph?: string;
+    migrations?: StoredMigrationStep[];
+    migrationWriteBack?: MigrationWriteBack;
+}
+type ScanProtection = 'error' | 'warn' | 'off';
+interface GraphClientOptions {
+    /**
+     * Static registry built from code/discovery.
+     *
+     * When provided alone, all writes are validated against this registry.
+     *
+     * When provided together with `registryMode`, operates in **merged mode**:
+     * static entries take priority and cannot be overridden by dynamic
+     * definitions. Dynamic definitions can only add new types. The merged
+     * client is returned as a `DynamicGraphClient`.
+     */
+    registry?: GraphRegistry;
+    /** Dynamic registry mode — type definitions stored as graph data. */
+    registryMode?: DynamicRegistryConfig;
+    /**
+     * Query execution backend.
+     *
+     * - `'pipeline'` (default) — Uses Firestore Pipeline API. Requires Enterprise
+     *   Firestore. Enables indexless queries on `data.*` fields.
+     * - `'standard'` — Uses standard Firestore `.where().get()` queries. Requires
+     *   composite indexes for `data.*` filters or risks full collection scans
+     *   (Enterprise) / query failures (Standard Firestore).
+     *
+     * When `FIRESTORE_EMULATOR_HOST` is set, the client auto-falls back to
+     * `'standard'` regardless of this setting (emulator doesn't support pipelines).
+     */
+    queryMode?: QueryMode;
+    /**
+     * Controls query safety behavior for full collection scan prevention.
+     *
+     * - `'error'` (default) — Throws `QuerySafetyError` for queries that would
+     *   likely cause a full collection scan. Override per-query with
+     *   `allowCollectionScan: true`.
+     * - `'warn'` — Logs a warning but executes the query.
+     * - `'off'` — No scan protection.
+     */
+    scanProtection?: ScanProtection;
+    /**
+     * Global default for write-back of auto-migrated records on read.
+     *
+     * - `'off'` (default) — Migrated data is returned but NOT written back.
+     * - `'eager'` — Migrated data is written back immediately after migration.
+     * - `'background'` — Write-back happens asynchronously; errors are logged.
+     *
+     * Per-entry `migrationWriteBack` on `RegistryEntry` overrides this setting.
+     */
+    migrationWriteBack?: MigrationWriteBack;
+    /**
+     * Custom executor for compiling dynamic registry migration source strings.
+     * Defaults to SES Compartments with JSON marshaling. Supply an
+     * alternative for custom sandboxing.
+     *
+     * Only used for dynamic registry migrations — static registry migrations
+     * are already in-memory functions and never go through this executor.
+     */
+    migrationSandbox?: MigrationExecutor;
+}
+interface GraphRegistry {
+    validate(aType: string, axbType: string, bType: string, data: unknown, scopePath?: string): void;
+    lookup(aType: string, axbType: string, bType: string): RegistryEntry | undefined;
+    /** Return all entries matching the given axbType (edge relation name). */
+    lookupByAxbType(axbType: string): ReadonlyArray<RegistryEntry>;
+    /**
+     * Return every edge entry originating from `aType` that has `targetGraph`
+     * set — i.e. the direct subgraph children of nodes of this type.
+     *
+     * Used by backends that need to enumerate a node's subgraph DOs without
+     * walking the graph. Each returned entry carries both `axbType` (the edge
+     * label that introduces the subgraph) and `targetGraph` (the subgraph
+     * segment name).
+     *
+     * Entries are deduplicated by `targetGraph` alone — the physical subgraph
+     * store is addressed by `(parentUid, targetGraph)`, so multiple edge
+     * relations (distinct `axbType` or `bType`) pointing into the same segment
+     * collapse to a single representative entry. The first-declared entry
+     * wins the collision. Callers only care about the subgraph name, not the
+     * originating relation or target node type.
+     */
+    getSubgraphTopology(aType: string): ReadonlyArray<RegistryEntry>;
+    entries(): ReadonlyArray<RegistryEntry>;
+}
+interface GraphReader {
+    getNode(uid: string): Promise<StoredGraphRecord | null>;
+    getEdge(aUid: string, axbType: string, bUid: string): Promise<StoredGraphRecord | null>;
+    edgeExists(aUid: string, axbType: string, bUid: string): Promise<boolean>;
+    findEdges(params: FindEdgesParams): Promise<StoredGraphRecord[]>;
+    findNodes(params: FindNodesParams): Promise<StoredGraphRecord[]>;
+}
+interface GraphWriter {
+    /**
+     * Write a node, deep-merging into any existing record.
+     *
+     * Nested objects are merged recursively — sibling keys at any depth
+     * survive. Arrays are terminal (replaced as a unit, not element-merged).
+     * `undefined` values are omitted; `null` is preserved. To delete a field,
+     * pass the `deleteField()` sentinel as its value.
+     *
+     * Use {@link replaceNode} when you want full-document replacement.
+     */
+    putNode(aType: string, uid: string, data: Record<string, unknown>): Promise<void>;
+    /**
+     * Write an edge, deep-merging into any existing record. See
+     * {@link putNode} for the merge contract.
+     */
+    putEdge(aType: string, aUid: string, axbType: string, bType: string, bUid: string, data: Record<string, unknown>): Promise<void>;
+    /**
+     * Replace a node's `data` payload entirely. Any field absent from
+     * `data` is dropped. Use sparingly — prefer {@link putNode} unless you
+     * specifically need to drop unknown fields.
+     */
+    replaceNode(aType: string, uid: string, data: Record<string, unknown>): Promise<void>;
+    /**
+     * Replace an edge's `data` payload entirely. See {@link replaceNode}.
+     */
+    replaceEdge(aType: string, aUid: string, axbType: string, bType: string, bUid: string, data: Record<string, unknown>): Promise<void>;
+    /**
+     * Patch a node's `data` payload. Like {@link putNode} this is a deep
+     * merge — nested objects are walked, only leaves are written. Use the
+     * `deleteField()` sentinel to remove a field.
+     */
+    updateNode(uid: string, data: Record<string, unknown>): Promise<void>;
+    /**
+     * Patch an edge's `data` payload. See {@link updateNode}.
+     */
+    updateEdge(aUid: string, axbType: string, bUid: string, data: Record<string, unknown>): Promise<void>;
+    removeNode(uid: string): Promise<void>;
+    removeEdge(aUid: string, axbType: string, bUid: string): Promise<void>;
+}
+/**
+ * Portable graph client surface.
+ *
+ * Every backend supports these methods unconditionally — they are the
+ * "graph as a graph" operations: read/write nodes and edges, run
+ * transactions, scope into subgraphs, etc. Edition-specific extensions
+ * (aggregate, full-text search, vector search, raw escape hatches, etc.)
+ * are added by intersection in `GraphClient<C>` only when the backend
+ * declares the matching capability — see the `*Extension` interfaces and
+ * `GraphClient<C>` below.
+ */
+interface CoreGraphClient extends GraphReader, GraphWriter {
+    /**
+     * Capability set of the underlying storage backend. Mirrors
+     * `StorageBackend.capabilities` so callers can do portability checks
+     * without reaching for the backend handle:
+     *
+     * ```ts
+     * if (client.capabilities.has('query.join')) {
+     *   await client.expand({ sources, axbType: 'wrote' });
+     * } else {
+     *   // fall back to the per-source loop in createTraversal()
+     * }
+     * ```
+     *
+     * The set is static for the lifetime of the client (invariant 3 from
+     * `.claude/backend-capabilities.md`). Subgraph clients return the cap
+     * set of their wrapped backend — typically identical to the parent's,
+     * but the routing wrapper may return a narrowed set when crossing into
+     * a routed child of a different backend type.
+     */
+    readonly capabilities: BackendCapabilities;
+    runTransaction<T>(fn: (tx: GraphTransaction) => Promise<T>): Promise<T>;
+    batch(): GraphBatch;
+    /** Delete a node and all its outgoing/incoming edges in chunked batches. */
+    removeNodeCascade(uid: string, options?: BulkOptions): Promise<CascadeResult>;
+    /** Find all edges matching `params` and delete them in chunked batches. */
+    bulkRemoveEdges(params: FindEdgesParams, options?: BulkOptions): Promise<BulkResult>;
+    /**
+     * Create a scoped client for a Firestore subcollection under the given
+     * parent node's document.
+     *
+     * The returned client shares a snapshot of the parent's registry at
+     * the time of this call. If the parent is a `DynamicGraphClient` and
+     * `reloadRegistry()` is called later, existing subgraph clients will
+     * NOT see the updated types — create a new subgraph client after
+     * reloading to pick up changes.
+     *
+     * @param parentNodeUid - UID of the parent node whose document owns the subcollection
+     * @param name - Subcollection name (defaults to `'graph'`). Must not contain `/`.
+     * @returns A `GraphClient` scoped to `{collectionPath}/{parentNodeUid}/{name}`
+     */
+    subgraph(parentNodeUid: string, name?: string): GraphClient;
+    /**
+     * Find edges across all subgraphs using a Firestore collection group query.
+     *
+     * Queries all collections with the given name (defaults to `'graph'`) across
+     * the entire database. This is useful for cross-cutting reads that span
+     * multiple subgraphs.
+     *
+     * **Requires** a Firestore collection group index for the query pattern.
+     *
+     * @param params - Edge filter parameters (same as `findEdges`)
+     * @param collectionName - Collection name to query across (defaults to last segment of this client's collection path)
+     */
+    findEdgesGlobal(params: FindEdgesParams, collectionName?: string): Promise<StoredGraphRecord[]>;
+}
+/** Supported aggregation operations.
+ *
+ * Firestore Standard supports `count`, `sum`, `avg` only. SQLite/DO additionally
+ * support `min` and `max` via SQL. Backends that cannot satisfy a requested op
+ * throw `FiregraphError` with code `UNSUPPORTED_AGGREGATE`.
+ */
+type AggregateOp = 'count' | 'sum' | 'avg' | 'min' | 'max';
+/** A single aggregation request.
+ *
+ * `field` is required for `sum`/`avg`/`min`/`max` and follows the same dotted
+ * path convention as `QueryFilter.field` (e.g. `'data.price'`). For `count`
+ * the field is forbidden — every backend rejects `count` with a stray field
+ * via `INVALID_QUERY`. We reject (rather than silently ignore) so a typo like
+ * `{ n: { op: 'count', field: 'data.price' } }` — easy to introduce when
+ * cribbing a sum spec and changing only the op — surfaces as a clear error
+ * instead of producing misleading row counts. */
+interface AggregateField {
+    op: AggregateOp;
+    field?: string;
+}
+/** Map of result alias -> aggregation request. */
+type AggregateSpec = Record<string, AggregateField>;
+/** Result shape derived from an `AggregateSpec` — one number per alias. */
+type AggregateResult<A extends AggregateSpec> = {
+    [K in keyof A]: number;
+};
+/** Aggregate query surface — count/sum/avg/min/max over a filter set. */
+interface AggregateExtension {
+    aggregate<A extends AggregateSpec>(params: FindEdgesParams & {
+        aggregates: A;
+    }): Promise<AggregateResult<A>>;
+}
+/**
+ * One row in the result of a `findEdgesProjected()` call.
+ *
+ * The shape is `{ [F]: unknown }` over the caller-supplied field list `F`.
+ * Each value is whatever the backend extracted from the underlying record:
+ *
+ *   - Top-level firegraph fields (`aType`, `aUid`, `axbType`, `bType`,
+ *     `bUid`, `createdAt`, `updatedAt`, `v`) come back as the same JS shape
+ *     `findEdges` produces — strings for the identifying fields, `number |
+ *     null` for `v` (`null` when the record predates schema versioning),
+ *     and the backend's native timestamp instance (Firestore's `Timestamp`
+ *     or `GraphTimestampImpl`) for `createdAt` / `updatedAt`.
+ *   - A bare name (e.g. `'title'`) is interpreted as `data.<name>`. SQL
+ *     backends extract via `json_extract` and the value comes back as the
+ *     JSON-decoded primitive / object. Firestore returns the field's stored
+ *     type unchanged.
+ *   - A dotted `data.x.y` path is the explicit form for nested fields.
+ *   - Absent paths surface as `null` (not `undefined`) across all backends
+ *     so that `JSON.stringify(row)` round-trips the requested shape.
+ *
+ * Why `unknown` rather than a stricter type: per-entity codegen integration
+ * (Phase 7 plan note) is the right place to surface concrete value types.
+ * Until that lands, the projection layer doesn't know whether `data.title`
+ * is a string, a number, or an object — a stricter type would lie. Use
+ * a registry-aware wrapper (or a per-call cast) to narrow.
+ */
+type ProjectedRow<F extends ReadonlyArray<string>> = {
+    [K in F[number]]: unknown;
+};
+/**
+ * Parameters for `findEdgesProjected` — `FindEdgesParams` plus a `select`
+ * field list. Field names follow the same rules as `WhereClause.field`:
+ *
+ *   - Built-in record fields (`aType`, `aUid`, etc.) resolve to their typed
+ *     column / Firestore field directly.
+ *   - A bare name resolves to `data.<name>` (the most common shape — most
+ *     callers project a few keys out of the JSON payload).
+ *   - A dotted `data.x.y` path is explicit.
+ *
+ * Empty `select: []` is rejected at the client level. The backend never
+ * sees an empty projection list because `SELECT FROM …` (no projection
+ * clause) is a syntactically different query and `SELECT * FROM …` is what
+ * `findEdges` already does.
+ *
+ * Duplicate entries in `select` are collapsed at compile time — the
+ * resulting row carries one slot per unique field. This keeps the
+ * SQL projection list minimal and matches Firestore's `Query.select(...)`
+ * de-duplication behaviour.
+ */
+interface FindEdgesProjectedParams<F extends ReadonlyArray<string>> extends FindEdgesParams {
+    /** Non-empty list of field paths to return. See type-level docs for the
+     * dotted-path convention. */
+    select: F;
+}
+/**
+ * Server-side field projection — return only the requested fields.
+ *
+ * Backends declaring `query.select` translate the call into a projecting
+ * server-side query (`SELECT json_extract(data, '$.f1'), …` on SQLite,
+ * `Query.select(...)` on Firestore Standard, pipeline `select()` on
+ * Firestore Enterprise). Backends without the cap throw
+ * `UNSUPPORTED_OPERATION` from the client wrapper — there is no
+ * client-side fallback that materialises full rows and then drops fields,
+ * because the wire-payload reduction is the entire point of the API.
+ */
+interface SelectExtension {
+    /** Fetch only the requested field paths from each matching edge.
+     *
+     * Returns one `ProjectedRow<F>` per matching edge, in the same order
+     * `findEdges` would have produced. Migrations are not applied — the
+     * projection bypasses the read-path migration pipeline because the
+     * caller asked for a specific shape, not a full record. If you need the
+     * migrated shape, use `findEdges` and project in JS.
+     */
+    findEdgesProjected<F extends ReadonlyArray<string>>(params: FindEdgesProjectedParams<F>): Promise<Array<ProjectedRow<F>>>;
+}
+/**
+ * Parameters for one expansion hop — fan out from a set of source UIDs over
+ * a single edge type in one server-side round trip.
+ *
+ * The shape mirrors `HopDefinition` (see `traverse.ts`) but is flat instead
+ * of chained: a multi-hop traversal calls `expand()` once per depth, and
+ * the traversal layer drives the hop-to-hop loop. We keep `expand()` per-
+ * depth (not per-traversal) for two reasons:
+ *
+ *   1. **Backend symmetry.** SQL `JOIN`s and Firestore Pipeline subqueries
+ *      both express N→1-source fan-out cleanly, but neither expresses
+ *      arbitrary-depth chained joins as a single statement (CTEs are
+ *      possible, but the `IN (?, …)` cap on Firestore makes a multi-depth
+ *      pipeline brittle). Per-depth fan-out is the largest constant-factor
+ *      win that's portable across all backends declaring `query.join`.
+ *
+ *   2. **Result shaping.** Per-hop edges feed cross-graph hops and
+ *      `targetGraph` re-routing, which traversal already owns. Pushing the
+ *      whole chain into one backend call would re-implement that logic at
+ *      the storage layer.
+ */
+interface ExpandParams {
+    /** Source UIDs from which to expand. The hop matches every row whose
+     * `aUid` (forward) or `bUid` (reverse) is in this list. May be empty —
+     * empty input yields empty output without touching the backend. */
+    sources: string[];
+    /** Edge relation name. Required. */
+    axbType: string;
+    /** Hop direction. `'forward'` (default) follows `aUid → bUid`; `'reverse'`
+     * follows `bUid → aUid`. */
+    direction?: 'forward' | 'reverse';
+    /** Optional `aType` predicate on the matched edge. */
+    aType?: string;
+    /** Optional `bType` predicate on the matched edge. */
+    bType?: string;
+    /** Per-source soft fan-out cap. The backend translates this to an upper
+     * bound on the total result count (`sources.length * limitPerSource`); it
+     * does **not** enforce strict per-source limits — a SQL `LIMIT N` over an
+     * `IN (…)` query may return all N rows from a single source if that's
+     * where the matches concentrate. Callers needing strict per-source caps
+     * should fall back to the per-hop loop. */
+    limitPerSource?: number;
+    /** Order edges by field; applied before limit. */
+    orderBy?: {
+        field: string;
+        direction?: 'asc' | 'desc';
+    };
+    /** Hydrate target nodes alongside edges. When `true`, the returned
+     * `ExpandResult.targets` array is index-aligned with `edges` and contains
+     * the corresponding target-side node record (the b-side for forward, the
+     * a-side for reverse) or `null` when the node row is missing. */
+    hydrate?: boolean;
+}
+/** Result shape for one `expand()` call.
+ *
+ * `edges` is the list of edge rows that matched the hop, in the order the
+ * backend returned them (subject to `orderBy`). `targets`, when present,
+ * is the same length as `edges` — one slot per edge — and holds the
+ * corresponding target-side node record (or `null` when the target node
+ * does not exist). */
+interface ExpandResult {
+    edges: StoredGraphRecord[];
+    /** Present iff the request set `hydrate: true`. Index-aligned with
+     * `edges`; entries are `null` for edges whose target node row is
+     * missing. */
+    targets?: Array<StoredGraphRecord | null>;
+}
+/** Multi-hop fan-out with target-node hydration in one round trip per hop.
+ *
+ * Backends declaring `query.join` translate one `expand()` call into one
+ * server-side query (SQL `IN (…)`, Firestore Pipeline batched fan-out).
+ * That collapses the per-source `findEdges` loop in `traverse.ts` into a
+ * single round trip per hop, regardless of source-set size.
+ *
+ * Backends without `query.join` are not required to expose `expand()` at
+ * all — `traverse.ts` keeps the per-source loop for them. The capability
+ * gate is the single source of truth on whether the optimization runs. */
+interface JoinExtension {
+    /** Fan out from `params.sources` over `params.axbType` in one round
+     * trip. See `ExpandParams` for shape and `ExpandResult` for return value.
+     *
+     * Cross-graph hops (those with `targetGraph`) are not eligible for
+     * `expand()` because each source UID would resolve to a distinct
+     * subgraph location — there's no single collection to fan out over.
+     * Callers (notably `traverse.ts`) detect cross-graph hops and stay on
+     * the per-source loop. */
+    expand(params: ExpandParams): Promise<ExpandResult>;
+}
+/**
+ * Patch shape for `bulkUpdate`.
+ *
+ *   - `data`: a deep partial of the row's `data` field. Applied via
+ *     deep-merge semantics (the same `flattenPatch` pipeline that
+ *     `updateNode` / `updateEdge` use). Use `deleteField()` sentinels to
+ *     remove individual leaves; arrays are replaced as a unit, never
+ *     concatenated.
+ *
+ * Backends with `query.dml` translate this to a single server-side UPDATE
+ * statement. The patch is applied to every row that matches the filter
+ * list; there is no per-row callback or read-modify-write loop. Identifying
+ * fields (`aType`, `axbType`, `bType`, `aUid`, `bUid`, `v`) are owned by
+ * firegraph and cannot be mutated through `bulkUpdate` — pass them in the
+ * filter list to scope the update, not in the patch body.
+ */
+interface BulkUpdatePatch {
+    /** Deep-partial patch applied to each matching row's `data` field. */
+    data: Record<string, unknown>;
+}
+/** Server-side conditional bulk DML — bulkDelete / bulkUpdate.
+ *
+ * Backends declaring `query.dml` translate each call to one server-side
+ * statement (Firestore Pipeline `remove`/`update` stage, SQL `DELETE`/
+ * `UPDATE`). Standard Firestore omits this capability and the
+ * Phase 5 code falls back to the existing fetch-then-write loop in
+ * `src/bulk.ts`.
+ *
+ * Both methods scope to the **current backend** only — they do not fan
+ * out to routed children or subcollections. Use `removeNodeCascade` for
+ * the cascade-aware cousin of `bulkDelete`. */
+interface DmlExtension {
+    /**
+     * Delete every row matching `params` in one server-side statement.
+     * Subject to the same scan-protection rules as `findEdges`: pass
+     * `allowCollectionScan: true` to bypass.
+     */
+    bulkDelete(params: FindEdgesParams, options?: BulkOptions): Promise<BulkResult>;
+    /**
+     * Update every row matching `params` with `patch` in one server-side
+     * statement. The patch is deep-merged into each row's `data` field.
+     * Identifying columns (`aType`, `axbType`, etc.) are immutable through
+     * this path — to relabel rows, delete and re-insert.
+     */
+    bulkUpdate(params: FindEdgesParams, patch: BulkUpdatePatch, options?: BulkOptions): Promise<BulkResult>;
+}
+/**
+ * One hop in an engine-level traversal spec.
+ *
+ * Strict subset of `HopDefinition` — engine traversal cannot honour
+ * arbitrary client-side filter callbacks (the predicate runs in JS, not
+ * server-side) and cannot compose across `targetGraph` boundaries (each
+ * subgraph lives at a distinct collection path; nested pipelines need
+ * one root collection). The compiler rejects specs that include either,
+ * falling back to the per-hop loop in `traverse.ts`.
+ *
+ * `limitPerSource` is REQUIRED on every engine hop — without it the
+ * compiler can't bound the response-size product against `maxReads`.
+ * Missing it is a compile-time error.
+ */
+interface EngineHopSpec {
+    axbType: string;
+    direction?: 'forward' | 'reverse';
+    aType?: string;
+    bType?: string;
+    /** Required for engine traversal — bounds the worst-case response size. */
+    limitPerSource: number;
+    orderBy?: {
+        field: string;
+        direction?: 'asc' | 'desc';
+    };
+}
+/**
+ * Parameters for one engine-level traversal call. The traversal layer
+ * compiles a multi-hop spec into a single nested Pipeline and dispatches
+ * one round trip; the executor decodes the tree result into per-hop
+ * `StoredGraphRecord[][]` arrays index-aligned with the source set.
+ *
+ * Cross-graph hops, depth > `MAX_PIPELINE_DEPTH`, or response-size
+ * estimates over `maxReads` are caught at compile time by the compiler
+ * and signal the traversal layer to fall back to the per-hop loop.
+ */
+interface EngineTraversalParams {
+    /** Initial source UIDs (the "frontier" at depth 0). */
+    sources: string[];
+    /** Hop chain. Length must be ≥ 1 and ≤ `MAX_PIPELINE_DEPTH`. */
+    hops: EngineHopSpec[];
+    /** Optional cap on the worst-case response-size product. The compiler
+     * estimates `Π(limitPerSource_i × N_i)` and refuses to emit (forcing
+     * fallback) if the estimate exceeds this. */
+    maxReads?: number;
+}
+/**
+ * Result of one engine-traversal call. `hops[i]` is the edge set
+ * returned at depth `i`, after per-hop dedupe on `bUid` (forward) /
+ * `aUid` (reverse). The arrays are flat — the tree shape is collapsed
+ * by the executor so the traversal layer can splice the result into
+ * the same `HopResult[]` shape `traverse.ts` already produces from the
+ * per-hop loop.
+ */
+interface EngineTraversalResult {
+    hops: Array<{
+        /** Edges returned at this depth, deduped on the target-side UID. */
+        edges: StoredGraphRecord[];
+        /** Number of distinct source UIDs at this depth. */
+        sourceCount: number;
+    }>;
+    /** Total documents read on the server side (for budget bookkeeping). */
+    totalReads: number;
+}
+/**
+ * Engine-level multi-hop traversal — a compiled, single-round-trip
+ * traversal for backends that can express it server-side.
+ *
+ * Backends declaring `traversal.serverSide` translate one
+ * `runEngineTraversal()` call into one server-side query (a nested
+ * Pipeline using `define` / `addFields` / `toArrayExpression` on
+ * Firestore Enterprise). That collapses the per-hop `expand()` loop
+ * in `traverse.ts` into a single round trip, regardless of depth.
+ *
+ * The traversal layer (`src/traverse.ts`) compiles a `TraversalBuilder`
+ * spec to `EngineTraversalParams` when:
+ *
+ *   - the backend declares `traversal.serverSide`;
+ *   - no hop is cross-graph (`targetGraph` unset);
+ *   - no hop carries a JS `filter` callback;
+ *   - depth ≤ `MAX_PIPELINE_DEPTH`;
+ *   - `Π(limitPerSource_i × N_i)` ≤ `maxReads` budget;
+ *   - every hop sets `limitPerSource`.
+ *
+ * Specs that fail any condition fall back to the per-hop loop with
+ * an optional `console.warn` (only when explicitly forced via the
+ * `engineTraversal: 'force'` opt-in in `TraversalOptions`).
+ */
+interface EngineTraversalExtension {
+    /** Execute one nested-Pipeline traversal in a single round trip. */
+    runEngineTraversal(params: EngineTraversalParams): Promise<EngineTraversalResult>;
+}
+/**
+ * Parameters for a server-side full-text search query.
+ *
+ * Translates on Firestore Enterprise into a Pipeline `search({ query: documentMatches(...) })`
+ * stage. Field-path conventions match `FindNearestParams.vectorField` and
+ * `WhereClause.field` — bare names resolve to `data.<name>`, envelope
+ * fields are rejected.
+ */
+interface FullTextSearchParams {
+    /**
+     * Optional filter on `aType`. Applied as a `where(aType == …)` stage
+     * after the `search()` stage (Firestore requires `search` to be the
+     * first stage of a pipeline, so identifying filters cannot be applied
+     * before the index walk).
+     */
+    aType?: string;
+    /** Optional filter on `axbType`. Same post-search-stage application as `aType`. */
+    axbType?: string;
+    /** Optional filter on `bType`. Same post-search-stage application as `aType`. */
+    bType?: string;
+    /**
+     * Free-form query string. The Firestore search index tokenises and
+     * ranks; the string accepts the same DSL as `documentMatches(...)` —
+     * boolean operators (`AND`, `OR`, `NOT`), phrase quoting, etc.
+     */
+    query: string;
+    /**
+     * Indexed text fields the caller wants the search restricted to.
+     *
+     * **Not yet supported.** Passing a non-empty `fields` array throws
+     * `INVALID_QUERY` (`'fields is not yet supported'`). The option is
+     * reserved for when `@google-cloud/firestore` exposes a typed per-field
+     * text predicate (`matches(field, query)`). Until then, omit `fields` —
+     * every search executes document-wide `documentMatches(query)`. For
+     * per-`aType` scoping, rely on Firestore's per-collection FTS indexes.
+     */
+    fields?: string[];
+    /** Upper bound on rows returned, sorted by relevance. */
+    limit: number;
+    /**
+     * Bypass scan-protection for unfiltered FTS. A search with no
+     * `aType` / `axbType` / `bType` filter walks every row the index
+     * scored — opt in explicitly when that's intended (analytics dumps,
+     * full-collection rerank).
+     */
+    allowCollectionScan?: boolean;
+}
+/**
+ * Native full-text search.
+ *
+ *   - **Firestore Enterprise** ✓ — implemented via Pipeline
+ *     `search({ query: documentMatches(...) })` (typed stage exposed in
+ *     `@google-cloud/firestore@8.5.0`). Identifying filters (`aType` /
+ *     `axbType` / `bType`) are applied as a follow-up `where(...)`
+ *     stage because the `search` stage must be the first stage of a
+ *     pipeline. Requires Enterprise Firestore (the FTS index is an
+ *     Enterprise product feature, not a free-tier feature).
+ *   - **Firestore Standard** — not supported. FTS is an Enterprise-only
+ *     product feature; this row will never become "✓".
+ *   - **SQLite / Cloudflare DO** — not supported. No native FTS index;
+ *     emulating it over `json_extract` is not viable for any realistic
+ *     dataset.
+ *
+ * Migrations are NOT applied to the result. The search index walked
+ * the raw stored shape; rehydrating each row through the migration
+ * pipeline would change the candidate set the index already scored.
+ * If you need migrated shape, follow up with `getNode` / `findEdges`
+ * on the returned UIDs.
+ */
+interface FullTextSearchExtension {
+    /**
+     * Run a full-text search. Returns the top-N records by relevance,
+     * ordered by the search index's score.
+     *
+     * Throws:
+     *
+     *   - `INVALID_QUERY` if `query` is empty, any field path resolves to
+     *     a built-in envelope field, or `limit` is non-positive.
+     *   - `QUERY_SAFETY` if no identifying filters are supplied and
+     *     `allowCollectionScan` is not set.
+     *   - `UNSUPPORTED_OPERATION` if the backend does not declare
+     *     `search.fullText`.
+     */
+    fullTextSearch(params: FullTextSearchParams): Promise<StoredGraphRecord[]>;
+}
+/**
+ * Geographic point — lat/lng in degrees. Mirrors the runtime shape of
+ * Firestore's `GeoPoint` so callers can pass either a literal or a
+ * `GeoPoint` instance once wiring lands.
+ */
+interface GeoPointLiteral {
+    lat: number;
+    lng: number;
+}
+/**
+ * Parameters for a server-side geospatial distance query.
+ *
+ * Translates on Firestore Enterprise into a Pipeline
+ * `search({ query: geoDistance(field, point).lessThanOrEqual(radius), sort: geoDistance(...).ascending() })`
+ * stage. The two `geoDistance(...)` expressions are computed identically
+ * server-side; the radius cap goes into the search query and the
+ * nearest-first ordering goes into `sort`.
+ */
+interface GeoSearchParams {
+    /**
+     * Optional filter on `aType`. Applied as a `where(aType == …)` stage
+     * after the `search()` stage (search must be the first stage).
+     */
+    aType?: string;
+    /** Optional filter on `axbType`. Same post-search-stage application as `aType`. */
+    axbType?: string;
+    /** Optional filter on `bType`. Same post-search-stage application as `aType`. */
+    bType?: string;
+    /**
+     * Field path of the indexed `GeoPoint`. Bare name → `data.<name>` per
+     * the same convention as `select` / `where`. Built-in envelope fields
+     * are rejected.
+     */
+    geoField: string;
+    /** Centre of the search radius. */
+    point: GeoPointLiteral;
+    /** Search radius in metres. */
+    radiusMeters: number;
+    /** Upper bound on rows returned. */
+    limit: number;
+    /**
+     * If true (default), results are sorted nearest-first via a
+     * `geoDistance(...).ascending()` ordering inside the `search` stage;
+     * if false, ordering is unspecified — the backend returns rows in
+     * whatever order the geo index emits.
+     */
+    orderByDistance?: boolean;
+    /**
+     * Bypass scan-protection for unfiltered geo searches. A geo query
+     * with no `aType` / `axbType` / `bType` filter walks every indexed
+     * row inside the radius — opt in explicitly when that's intended.
+     */
+    allowCollectionScan?: boolean;
+}
+/**
+ * Native geospatial distance search.
+ *
+ *   - **Firestore Enterprise** ✓ — implemented via Pipeline
+ *     `search({ query: geoDistance(field, point).lessThanOrEqual(radius), sort: geoDistance(...).ascending() })`
+ *     (typed `geoDistance(...)` function exposed in
+ *     `@google-cloud/firestore@8.5.0`). Identifying filters
+ *     (`aType` / `axbType` / `bType`) are applied as a follow-up
+ *     `where(...)` stage because the `search` stage must be the
+ *     first stage of a pipeline. Requires Enterprise Firestore (the
+ *     geo index is an Enterprise product feature).
+ *   - **Firestore Standard** — not supported. Geospatial queries are
+ *     an Enterprise-only product feature; this row will never become
+ *     "✓".
+ *   - **SQLite / Cloudflare DO** — not supported. No native geo
+ *     index; emulating it over `json_extract` and the haversine
+ *     formula is viable only for trivial dataset sizes and would give
+ *     callers the wrong mental model about cost.
+ *
+ * Migrations are NOT applied to the result — same rationale as
+ * `findNearest` and `fullTextSearch`. The geo index walked the raw
+ * stored shape.
+ */
+interface GeoExtension {
+    /**
+     * Run a geospatial distance search. Returns rows whose
+     * `geoField` lies within `radiusMeters` of `point`, ordered
+     * nearest-first by default.
+     *
+     * Throws:
+     *
+     *   - `INVALID_QUERY` if `geoField` resolves to a built-in envelope
+     *     field, `radiusMeters` is non-positive, `limit` is
+     *     non-positive, or `point.lat` / `point.lng` are out of range.
+     *   - `QUERY_SAFETY` if no identifying filters are supplied and
+     *     `allowCollectionScan` is not set.
+     *   - `UNSUPPORTED_OPERATION` if the backend does not declare
+     *     `search.geo`.
+     */
+    geoSearch(params: GeoSearchParams): Promise<StoredGraphRecord[]>;
+}
+/**
+ * Distance metric for vector / nearest-neighbour search. Mirrors
+ * Firestore's `VectorQueryOptions.distanceMeasure` enum so the value
+ * passes through to the SDK without translation:
+ *
+ *   - `EUCLIDEAN` — straight-line distance in n-dimensional space; lower
+ *     is more similar.
+ *   - `COSINE` — angle between vectors; lower is more similar (1 −
+ *     cosine_similarity).
+ *   - `DOT_PRODUCT` — inner product; *higher* is more similar. The
+ *     `distanceThreshold` semantics flip accordingly (see
+ *     `FindNearestParams`).
+ */
+type DistanceMeasure = 'EUCLIDEAN' | 'COSINE' | 'DOT_PRODUCT';
+/**
+ * Parameters for a server-side vector / nearest-neighbour query.
+ *
+ * Identifying filters (`aType`, `axbType`, `bType`) and `where` clauses
+ * narrow the candidate set *before* the ANN query runs — Firestore folds
+ * them into the same `Query` the vector index walks. Combining multiple
+ * filters with vector search requires composite indexes on Firestore
+ * Standard; the Enterprise edition lifts the index requirement for some
+ * shapes (see Firestore docs).
+ *
+ * `vectorField` follows the same dotted-path / bare-name convention as
+ * `select` in `FindEdgesProjectedParams` and `field` in `WhereClause`:
+ *
+ *   - A bare name (e.g. `'embedding'`) resolves to `data.embedding`.
+ *   - A literal `'data'` or `'data.<x>'` is taken as-is.
+ *   - Built-in envelope fields are not vector-indexable — passing one
+ *     throws `INVALID_QUERY` at the client surface.
+ *
+ * `queryVector` accepts either a plain `number[]` or a Firestore
+ * `VectorValue`. The dimension must match the indexed `vectorField`'s
+ * dimension; Firestore filters out rows whose vector dimension differs
+ * (rather than throwing) so the result set may be smaller than `limit`.
+ *
+ * `distanceThreshold` semantics depend on `distanceMeasure`:
+ *
+ *   - `EUCLIDEAN` / `COSINE` → return rows with `distance <=` threshold.
+ *   - `DOT_PRODUCT` → return rows with `distance >=` threshold (higher
+ *     dot product = more similar).
+ *
+ * If `distanceResultField` is set, every returned record carries the
+ * computed distance at that field path inside `data`. Pass a built-in
+ * envelope field name (e.g. `'aType'`) and the request fails server-side
+ * — the SDK reserves the envelope.
+ */
+interface FindNearestParams {
+    /** Optional filter on `aType`. Resolves to `where('aType', '==', …)`. */
+    aType?: string;
+    /** Optional filter on `axbType`. */
+    axbType?: string;
+    /** Optional filter on `bType`. */
+    bType?: string;
+    /**
+     * Field path of the indexed vector. Bare name → `data.<name>`. Built-in
+     * envelope fields are rejected — they are not vector-indexable.
+     */
+    vectorField: string;
+    /** Query vector. `number[]` or `VectorValue`; must match the indexed dimension. */
+    queryVector: number[] | {
+        toArray(): number[];
+    };
+    /** Upper bound on rows returned. Firestore caps at 1000. */
+    limit: number;
+    /** Distance metric — see `DistanceMeasure` for the semantics flip on `DOT_PRODUCT`. */
+    distanceMeasure: DistanceMeasure;
+    /**
+     * Optional similarity cutoff. Interpretation depends on `distanceMeasure`
+     * — see the type-level docs.
+     */
+    distanceThreshold?: number;
+    /**
+     * Optional dotted path that, if set, will be populated on each returned
+     * record with the computed distance. Bare name → `data.<name>`. Use this
+     * when downstream code needs to rank or threshold the results in JS.
+     */
+    distanceResultField?: string;
+    /**
+     * Additional filters applied before the ANN walk. Same shape as
+     * `findEdges({ where })`. Field-path rules match `WhereClause.field`.
+     */
+    where?: WhereClause[];
+    /**
+     * Bypass scan-protection for unfiltered vector searches. A vector query
+     * with no `aType` / `axbType` / `bType` / `where` filters scans every
+     * row in the collection before the ANN narrowing — opt in explicitly.
+     */
+    allowCollectionScan?: boolean;
+}
+/**
+ * Native vector / nearest-neighbour search.
+ *
+ * Backends declaring `search.vector` translate the call into a single
+ * server-side `findNearest` query. The SQLite-shaped backends (shared
+ * SQLite, Cloudflare DO) do not declare this capability — they have no
+ * native vector index, and emulating ANN on top of `json_extract` is a
+ * non-starter for any realistic dataset. Firestore Standard and
+ * Enterprise both implement it via the classic `Query.findNearest(...)`
+ * API; the pipeline `findNearest` stage is a future optimisation.
+ *
+ * Migrations are NOT applied to the result. The vector query selects
+ * documents by similarity, not by query plan — applying migrations
+ * inline would change the candidate set the index already walked. If
+ * you need migrated shape, follow up with `getNode` / `findEdges` on the
+ * returned UIDs.
+ */
+interface VectorExtension {
+    /**
+     * Run a vector / nearest-neighbour search. Returns the top-K records
+     * by similarity, sorted nearest-first (or furthest-first for
+     * `DOT_PRODUCT` where higher = more similar).
+     *
+     * Throws:
+     *
+     *   - `INVALID_QUERY` if `vectorField` resolves to a built-in envelope
+     *     field, `limit` is non-positive or > 1000, `queryVector` is
+     *     empty, or `distanceResultField` collides with a built-in.
+     *   - `QUERY_SAFETY` if no identifying filters / `where` clauses are
+     *     supplied and `allowCollectionScan` is not set.
+     *   - `UNSUPPORTED_OPERATION` if the backend does not declare
+     *     `search.vector`.
+     */
+    findNearest(params: FindNearestParams): Promise<StoredGraphRecord[]>;
+}
+/** Escape hatch — expose the underlying Firestore handle. */
+interface RawFirestoreExtension {
+}
+/** Escape hatch — expose the underlying SQL executor. */
+interface RawSqlExtension {
+}
+/** Realtime listener API — `onSnapshot`-style live subscriptions. */
+interface RealtimeListenExtension {
+}
+/**
+ * Capability-gated graph client.
+ *
+ * `C` is the closed union of capabilities the underlying backend
+ * declared. Each extension is conditionally intersected: it appears in the
+ * resulting type only when the matching capability is in `C`. The default
+ * `C = Capability` evaluates every conditional truthy, yielding the full
+ * surface — that is the "permissive" shape returned when no capability
+ * narrowing is in effect (e.g. legacy callers using
+ * `let x: GraphClient = …` without a parameter).
+ *
+ * Why distributive conditionals work: `'query.aggregate' extends C ? A : B`
+ * distributes over the union members of `C`. If any union member is
+ * `'query.aggregate'`, the conditional evaluates to `A`; otherwise `B`.
+ * Intersection with `object` (the false branch) is a no-op, so omitted
+ * extensions contribute nothing to the resulting type.
+ */
+type GraphClient<C extends Capability = Capability> = CoreGraphClient & ('query.aggregate' extends C ? AggregateExtension : object) & ('query.select' extends C ? SelectExtension : object) & ('query.join' extends C ? JoinExtension : object) & ('query.dml' extends C ? DmlExtension : object) & ('traversal.serverSide' extends C ? EngineTraversalExtension : object) & ('search.fullText' extends C ? FullTextSearchExtension : object) & ('search.geo' extends C ? GeoExtension : object) & ('search.vector' extends C ? VectorExtension : object) & ('realtime.listen' extends C ? RealtimeListenExtension : object) & ('raw.firestore' extends C ? RawFirestoreExtension : object) & ('raw.sql' extends C ? RawSqlExtension : object);
+/**
+ * Methods present only on dynamic-registry clients. Composed with
+ * `GraphClient<C>` to form `DynamicGraphClient<C>` — the type returned
+ * by `createGraphClient(...)` when `registryMode` is set on the options.
+ */
+interface DynamicGraphMethods {
+    /** Define or update a node type in the dynamic registry. */
+    defineNodeType(name: string, jsonSchema: object, description?: string, options?: DefineTypeOptions): Promise<void>;
+    /** Define or update an edge type in the dynamic registry. */
+    defineEdgeType(name: string, topology: EdgeTopology, jsonSchema?: object, description?: string, options?: DefineTypeOptions): Promise<void>;
+    /** Reload the registry from meta-type nodes in the graph. */
+    reloadRegistry(): Promise<void>;
+}
+/**
+ * Dynamic-registry graph client. Same conditional capability surface as
+ * `GraphClient<C>`, plus the meta-type definition methods.
+ */
+type DynamicGraphClient<C extends Capability = Capability> = GraphClient<C> & DynamicGraphMethods;
+interface GraphTransaction extends GraphReader, GraphWriter {
+}
+interface GraphBatch extends GraphWriter {
+    commit(): Promise<void>;
+}
+interface HopDefinition {
+    axbType: string;
+    direction?: 'forward' | 'reverse';
+    aType?: string;
+    bType?: string;
+    limit?: number;
+    orderBy?: {
+        field: string;
+        direction?: 'asc' | 'desc';
+    };
+    filter?: (edge: StoredGraphRecord) => boolean;
+    /**
+     * Subgraph name to cross into for this hop (forward traversal only).
+     *
+     * When set, the traversal queries the named subgraph under each source node
+     * instead of the current collection (`{collection}/{sourceUid}/{targetGraph}`).
+     *
+     * If omitted but the registry has a `targetGraph` for this `axbType`,
+     * the registry value is used automatically.
+     *
+     * **Context tracking:** Once a hop crosses into a subgraph, subsequent
+     * hops without `targetGraph` stay in that subgraph automatically. To
+     * cross into a different subgraph, set `targetGraph` explicitly on the
+     * next hop — explicit `targetGraph` always resolves relative to the
+     * root client, not the current subgraph. To return to the root graph,
+     * create a separate traversal from the root client.
+     */
+    targetGraph?: string;
+}
+interface TraversalOptions {
+    maxReads?: number;
+    concurrency?: number;
+    returnIntermediates?: boolean;
+    /**
+     * Engine-level traversal mode. Controls whether the traversal layer
+     * tries to compile the hop chain into one server-side nested Pipeline
+     * (Firestore Enterprise only, gated by `traversal.serverSide`).
+     *
+     *   - `'auto'` (default) — use engine traversal when the backend
+     *     declares the capability AND the spec passes the compiler's
+     *     eligibility checks (no cross-graph hops, no JS filters, depth
+     *     ≤ `MAX_PIPELINE_DEPTH`, response-size product ≤ `maxReads`,
+     *     `limitPerSource` set on every hop). Otherwise fall back to
+     *     the per-hop loop. No warning fires on fallback.
+     *
+     *   - `'force'` — engine traversal MUST run. If the backend lacks
+     *     the capability or the spec is ineligible, the traversal throws
+     *     `FiregraphError('UNSUPPORTED_OPERATION')`. Useful for
+     *     benchmarking and tests.
+     *
+     *   - `'off'` — never use engine traversal, even when available.
+     *     The traversal layer always uses the per-hop loop.
+     *
+     * Default: `'auto'`.
+     */
+    engineTraversal?: 'auto' | 'force' | 'off';
+}
+interface HopResult {
+    axbType: string;
+    depth: number;
+    edges: StoredGraphRecord[];
+    sourceCount: number;
+    truncated: boolean;
+}
+interface TraversalResult {
+    nodes: StoredGraphRecord[];
+    hops: HopResult[];
+    totalReads: number;
+    truncated: boolean;
+}
+interface TraversalBuilder {
+    follow(axbType: string, options?: Omit<HopDefinition, 'axbType'>): TraversalBuilder;
+    run(options?: TraversalOptions): Promise<TraversalResult>;
+}
+interface BulkOptions {
+    /** Max operations per Firestore batch (default 500, Firestore hard limit). */
+    batchSize?: number;
+    /** Number of retry attempts per failed batch (default 3). */
+    maxRetries?: number;
+    /** Called after each batch commits. */
+    onProgress?: (progress: BulkProgress) => void;
+    /**
+     * Recursively delete subcollections (subgraphs) under the node's document.
+     * Defaults to `true` for `removeNodeCascade`.
+     */
+    deleteSubcollections?: boolean;
+}
+interface BulkProgress {
+    /** Batches committed so far. */
+    completedBatches: number;
+    /** Total batches planned. */
+    totalBatches: number;
+    /** Total documents deleted so far. */
+    deletedSoFar: number;
+}
+interface BulkResult {
+    /**
+     * Total documents affected.
+     *
+     * For `bulkDelete()` this is the count of deleted documents; for
+     * `bulkUpdate()` this is the count of updated documents (the field name
+     * is a legacy from cascade-delete).
+     */
+    deleted: number;
+    /** Number of batches committed. */
+    batches: number;
+    /** Errors from batches that failed after all retries. */
+    errors: BulkBatchError[];
+}
+interface BulkBatchError {
+    /** Zero-based index of the failed batch. */
+    batchIndex: number;
+    /** The underlying error. */
+    error: Error;
+    /** Number of operations in this batch that were not applied. */
+    operationCount: number;
+}
+interface CascadeResult extends BulkResult {
+    /** Number of edges deleted. */
+    edgesDeleted: number;
+    /** Whether the node itself was deleted. */
+    nodeDeleted: boolean;
+}
+
+/**
+ * Write-plan helper — flattens partial-update payloads into a list of
+ * deep-path operations every backend can execute identically.
+ *
+ * Background: firegraph used to ship two write semantics that quietly
+ * disagreed about depth.
+ *   - `putNode`/`putEdge` did a full document replace.
+ *   - `updateNode`/`updateEdge` did a one-level shallow merge: top-level
+ *     keys were preserved, but nested objects were replaced wholesale.
+ *
+ * Both behaviours dropped sibling keys silently. The 0.12 contract is that
+ * `put*` and `update*` deep-merge by default (sibling keys at any depth
+ * survive); `replace*` is the explicit escape hatch.
+ *
+ * `flattenPatch` walks a partial-update payload and emits one
+ * {@link DataPathOp} per terminal value. Plain objects recurse; arrays,
+ * primitives, Firestore special types, and tagged firegraph-serialization
+ * objects are terminal (replaced as a unit). `undefined` values are
+ * skipped; `null` is preserved as a real `null` write; the
+ * {@link DELETE_FIELD} sentinel marks a field for removal.
+ *
+ * The output is deliberately backend-agnostic. Each backend translates ops
+ * into its native dialect:
+ *   - Firestore: dotted field path → `data.a.b.c` for `update()`.
+ *   - SQLite / DO SQLite: `json_set(data, '$.a.b.c', ?)` /
+ *     `json_remove(data, '$.a.b.c')`.
+ */
+/**
+ * Sentinel returned by {@link deleteField}. Treated by all backends as
+ * "remove this field from the stored document".
+ *
+ * Equivalent to Firestore's `FieldValue.delete()`, but works for SQLite
+ * backends too. Use inside `updateNode`/`updateEdge` payloads.
+ */
+declare const DELETE_FIELD: unique symbol;
+type DeleteSentinel = typeof DELETE_FIELD;
+/**
+ * Returns the firegraph delete sentinel. Place this anywhere in an
+ * `updateNode`/`updateEdge` payload to remove the corresponding field.
+ *
+ * ```ts
+ * await client.updateNode('tour', uid, {
+ *   attrs: { obsoleteFlag: deleteField() },
+ * });
+ * ```
+ */
+declare function deleteField(): DeleteSentinel;
+/** Type guard for the delete sentinel. */
+declare function isDeleteSentinel(value: unknown): value is DeleteSentinel;
+/**
+ * Single terminal write operation produced by {@link flattenPatch}.
+ *
+ * `path` is a non-empty array of plain object keys. `value` is the value to
+ * write; ignored when `delete` is `true`. Arrays / primitives / Firestore
+ * special types appear here as whole terminal values.
+ */
+interface DataPathOp {
+    path: readonly string[];
+    value: unknown;
+    delete: boolean;
+}
+/**
+ * Flatten a partial-update payload into a list of terminal {@link DataPathOp}s.
+ *
+ * Rules:
+ *   - Plain objects (no prototype or `Object.prototype`) recurse — each
+ *     key becomes another path segment.
+ *   - Arrays are terminal: writing `{tags: ['a']}` overwrites the whole
+ *     `tags` array. Element-wise array merging is intentionally NOT
+ *     supported — it's almost never what callers actually want, and
+ *     Firestore `arrayUnion`/`arrayRemove` give precise semantics when
+ *     they are.
+ *   - `undefined` values are skipped (no op generated). Use
+ *     {@link deleteField} if you actually want to remove a field.
+ *   - `null` is preserved verbatim — emits a terminal op with `value: null`.
+ *   - {@link DELETE_FIELD} produces an op with `delete: true`.
+ *   - Firestore special types and tagged serialization payloads are terminal.
+ *   - Class instances are terminal.
+ *
+ * Throws if any object key on the recursion path is unsafe (see
+ * {@link assertSafePath}).
+ */
+declare function flattenPatch(data: Record<string, unknown>): DataPathOp[];
+
+/**
+ * Backend abstraction for firegraph.
+ *
+ * `StorageBackend` is the single interface every storage driver implements.
+ * The Firestore backend wraps `@google-cloud/firestore`; the SQLite backend
+ * (shared by D1 and Durable Object SQLite) uses a parameterized SQL executor.
+ *
+ * `GraphClientImpl` and friends depend only on this interface — they have
+ * no direct knowledge of Firestore or SQLite.
+ */
+
+/**
+ * Runtime descriptor of which `Capability`s a `StorageBackend` actually
+ * implements. Static for the lifetime of a backend instance; declared at
+ * construction. The phantom `_phantom` field is a type-level marker
+ * (never read at runtime) that lets the type parameter `C` flow through
+ * the descriptor for use by `GraphClient<C>` conditional gating.
+ *
+ * Use `createCapabilities` to construct one. Use `.has(c)` to check
+ * membership at runtime; the type system gates extension methods on the
+ * client level (see `.claude/backend-capabilities.md`).
+ */
+interface BackendCapabilities<C extends Capability = Capability> {
+    /** Runtime membership check. */
+    has(capability: Capability): boolean;
+    /** Iterate declared capabilities (diagnostics, error messages). */
+    values(): IterableIterator<Capability>;
+    /** Type-level marker. Never read at runtime. */
+    readonly _phantom?: C;
+}
+/**
+ * Construct a `BackendCapabilities<C>` from an explicit set. The set is
+ * captured by reference; callers should treat it as readonly after passing
+ * it in. The runtime cost of `has()` is one Set lookup.
+ */
+declare function createCapabilities<C extends Capability>(caps: ReadonlySet<C>): BackendCapabilities<C>;
+/**
+ * Intersect multiple capability sets. Used by `RoutingStorageBackend` to
+ * derive the capability set of a composite backend: a routed graph can
+ * only honour a capability if every wrapped backend honours it.
+ */
+declare function intersectCapabilities(parts: ReadonlyArray<BackendCapabilities>): BackendCapabilities;
+/**
+ * Per-record write payload — backend-agnostic. Timestamps are not present;
+ * the backend supplies them via `serverTimestamp()` placeholders that it
+ * itself resolves at commit time.
+ */
+interface WritableRecord {
+    aType: string;
+    aUid: string;
+    axbType: string;
+    bType: string;
+    bUid: string;
+    data: Record<string, unknown>;
+    /** Schema version (set by the writer when registry has migrations). */
+    v?: number;
+}
+/**
+ * Write semantics for `setDoc`.
+ *
+ *   - `'merge'` — the new contract (0.12+). Existing fields not mentioned
+ *     in the new data survive; nested objects are recursively merged;
+ *     arrays are replaced as a unit. This is the default for
+ *     `putNode` / `putEdge`.
+ *   - `'replace'` — the document is replaced wholesale, dropping any
+ *     fields not present in the payload. This is the explicit escape
+ *     hatch surfaced as `replaceNode` / `replaceEdge` and used by
+ *     migration write-back.
+ */
+type WriteMode = 'merge' | 'replace';
+/**
+ * Patch shape for `updateDoc`.
+ *
+ *   - `dataOps`: list of deep-path terminal ops produced by
+ *     `flattenPatch()` (one op per leaf — arrays / primitives / Firestore
+ *     special types are terminal). Used by `updateNode` / `updateEdge`.
+ *     Sibling keys at every depth are preserved.
+ *   - `replaceData`: full `data` replacement. Used only by the migration
+ *     write-back path, which has already produced a complete migrated
+ *     document.
+ *   - `v`: optional schema-version stamp.
+ *
+ * `updatedAt` is always set by the backend.
+ */
+interface UpdatePayload {
+    dataOps?: DataPathOp[];
+    replaceData?: Record<string, unknown>;
+    v?: number;
+}
+/**
+ * Read/write transaction adapter. Mirrors Firestore's transaction semantics:
+ * reads are snapshot-consistent; writes are issued inside the transaction
+ * and a rejection from any write aborts the surrounding `runTransaction`.
+ *
+ * Writes return `Promise<void>` so SQL drivers can surface row-level errors
+ * (constraint violations, malformed JSON paths) rather than swallowing them.
+ * Firestore implementations can resolve synchronously since the underlying
+ * `Transaction.set/update/delete` calls are themselves synchronous buffers.
+ */
+interface TransactionBackend {
+    getDoc(docId: string): Promise<StoredGraphRecord | null>;
+    query(filters: QueryFilter[], options?: QueryOptions): Promise<StoredGraphRecord[]>;
+    setDoc(docId: string, record: WritableRecord, mode: WriteMode): Promise<void>;
+    updateDoc(docId: string, update: UpdatePayload): Promise<void>;
+    deleteDoc(docId: string): Promise<void>;
+}
+/**
+ * Atomic multi-write batch.
+ */
+interface BatchBackend {
+    setDoc(docId: string, record: WritableRecord, mode: WriteMode): void;
+    updateDoc(docId: string, update: UpdatePayload): void;
+    deleteDoc(docId: string): void;
+    commit(): Promise<void>;
+}
+/**
+ * The single storage abstraction.
+ *
+ * Each backend instance is scoped to a "graph location" — for Firestore
+ * that's a collection path; for SQLite it's a (table, scopePath) pair.
+ * `subgraph()` returns a child backend bound to a nested location.
+ */
+interface StorageBackend<C extends Capability = Capability> {
+    /** Capabilities this backend instance declares. Static for the lifetime of the backend. */
+    readonly capabilities: BackendCapabilities<C>;
+    /** Backend-internal location identifier (collection path or table name). */
+    readonly collectionPath: string;
+    /** Subgraph scope (empty string for root). */
+    readonly scopePath: string;
+    getDoc(docId: string): Promise<StoredGraphRecord | null>;
+    query(filters: QueryFilter[], options?: QueryOptions): Promise<StoredGraphRecord[]>;
+    setDoc(docId: string, record: WritableRecord, mode: WriteMode): Promise<void>;
+    updateDoc(docId: string, update: UpdatePayload): Promise<void>;
+    deleteDoc(docId: string): Promise<void>;
+    runTransaction<T>(fn: (tx: TransactionBackend) => Promise<T>): Promise<T>;
+    createBatch(): BatchBackend;
+    subgraph(parentNodeUid: string, name: string): StorageBackend;
+    removeNodeCascade(uid: string, reader: GraphReader, options?: BulkOptions): Promise<CascadeResult>;
+    bulkRemoveEdges(params: FindEdgesParams, reader: GraphReader, options?: BulkOptions): Promise<BulkResult>;
+    /**
+     * Find edges across all subgraphs sharing a given collection name.
+     * Optional — backends that can't support this should throw a clear error.
+     */
+    findEdgesGlobal?(params: FindEdgesParams, collectionName?: string): Promise<StoredGraphRecord[]>;
+    /**
+     * Run an aggregate query (count/sum/avg/min/max). Present only on backends
+     * that declare `query.aggregate`. The map's keys are caller-defined aliases
+     * matching `AggregateSpec`; values are the resolved numeric results.
+     *
+     * Backends that can't satisfy a particular op throw `FiregraphError` with
+     * code `UNSUPPORTED_AGGREGATE` (e.g. Firestore Standard rejects min/max).
+     */
+    aggregate?(spec: AggregateSpec, filters: QueryFilter[]): Promise<Record<string, number>>;
+    /**
+     * Delete every row matching `filters` in one server-side statement.
+     * Present only on backends that declare `query.dml`. The default cascade
+     * implementation in `bulk.ts` uses this when available; backends without
+     * the cap (e.g. Firestore Standard) fall back to a fetch-then-delete
+     * loop driven by `findEdges` + per-row `deleteDoc`.
+     *
+     * The contract matches `findEdges`: scope predicates are honoured
+     * automatically by the backend's own internal scope tracking. Callers
+     * supply only the filter list — the same shape produced by
+     * `buildEdgeQueryPlan`.
+     */
+    bulkDelete?(filters: QueryFilter[], options?: BulkOptions): Promise<BulkResult>;
+    /**
+     * Update every row matching `filters` with `patch` in one server-side
+     * statement. The patch is deep-merged into each row's `data` field, the
+     * same flatten-then-merge pipeline `updateDoc` uses. Identifying columns
+     * (`aType`, `axbType`, `aUid`, `bType`, `bUid`, `v`) are not writable
+     * through this path.
+     */
+    bulkUpdate?(filters: QueryFilter[], patch: BulkUpdatePatch, options?: BulkOptions): Promise<BulkResult>;
+    /**
+     * Fan out from `params.sources` over a single edge type in one server-side
+     * round trip. Present only on backends that declare `query.join`. The
+     * traversal layer (`traverse.ts`) calls `expand` once per hop when the
+     * backend declares the cap; otherwise it falls back to the per-source
+     * `findEdges` loop.
+     *
+     * Cross-graph hops are never dispatched through `expand` — each source
+     * UID resolves to a distinct subgraph location, which can't be fanned
+     * out as a single statement. The traversal layer enforces that
+     * boundary; `expand` itself does not need to inspect `targetGraph`.
+     */
+    expand?(params: ExpandParams): Promise<ExpandResult>;
+    /**
+     * Compile a multi-hop traversal spec into one server-side query and
+     * dispatch a single round trip. Present only on backends that declare
+     * `traversal.serverSide` (Firestore Enterprise today, via nested
+     * Pipelines that combine `define`, `addFields`, and
+     * `toArrayExpression`).
+     *
+     * The traversal layer (`traverse.ts`) compiles a `TraversalBuilder`
+     * spec into `EngineTraversalParams` only when the spec is eligible
+     * (no cross-graph hops, no JS filters, depth ≤ `MAX_PIPELINE_DEPTH`,
+     * `Π(limitPerSource_i × N_i) ≤ maxReads`, `limitPerSource` set on
+     * every hop). Ineligible specs fall back to the per-hop `expand()`
+     * loop without invoking this method.
+     *
+     * The result collapses the nested-pipeline tree into per-hop edge
+     * arrays so the traversal layer can fold the result into the same
+     * `HopResult[]` shape it produces from the per-hop loop.
+     */
+    runEngineTraversal?(params: EngineTraversalParams): Promise<EngineTraversalResult>;
+    /**
+     * Run a projecting query — return only the listed fields per row. Present
+     * only on backends that declare `query.select`. The cap-less fallback is
+     * `findEdges` followed by a JS-side projection in user code; firegraph
+     * does not auto-fall-back because the wire-payload reduction is the only
+     * reason to call this method.
+     *
+     * `select` is the explicit field list; `filters` and `options` mirror the
+     * `query()` shape. The returned rows have one slot per unique entry in
+     * `select`. Field-name interpretation is the backend's responsibility:
+     * built-in fields resolve to columns / Firestore field names, bare names
+     * resolve to `data.<name>`, and dotted paths resolve verbatim. See
+     * `FindEdgesProjectedParams` for the user-facing contract.
+     *
+     * Migrations are not applied to the result — the caller asked for a
+     * specific projection shape, and rehydrating a partial record into the
+     * migration pipeline would require synthesising every absent field.
+     */
+    findEdgesProjected?(select: ReadonlyArray<string>, filters: QueryFilter[], options?: QueryOptions): Promise<Array<Record<string, unknown>>>;
+    /**
+     * Run a vector / nearest-neighbour query. Present only on backends that
+     * declare `search.vector`. There is no client-side fallback — the
+     * SQLite-shaped backends (shared SQLite, Cloudflare DO) genuinely have
+     * no native ANN index, and a JS-side k-NN sweep over `findEdges()` would
+     * scale catastrophically. Backends without the cap throw
+     * `UNSUPPORTED_OPERATION` from the client wrapper.
+     *
+     * `params` carries the user-facing shape (vector field path, query
+     * vector, distance metric, optional threshold and result-field). The
+     * client wrapper has already run scan-protection on the identifying
+     * / `where` filter list before dispatching.
+     *
+     * Path normalisation is the backend's responsibility: rewriting bare
+     * `vectorField` / `distanceResultField` names to `data.<name>` and
+     * rejecting envelope fields (`aType`, `axbType`, `bType`, `aUid`,
+     * `bUid`, `v`, etc.) with `INVALID_QUERY` happens inside the
+     * backend, not the client wrapper. The two in-tree Firestore-edition
+     * backends share `runFirestoreFindNearest` (see
+     * `src/internal/firestore-vector.ts`) for this; third-party backends
+     * declaring `search.vector` must apply equivalent normalisation
+     * before calling their underlying SDK.
+     *
+     * The backend is also responsible for translating to the underlying
+     * SDK call (`Query.findNearest` on Firestore today) and decoding the
+     * result snapshot into `StoredGraphRecord[]`.
+     *
+     * Migrations are not applied to the result. The vector index walks the
+     * raw stored shape; rehydrating into the migration pipeline before
+     * returning would change the candidate set the index already chose.
+     */
+    findNearest?(params: FindNearestParams): Promise<StoredGraphRecord[]>;
+    /**
+     * Run a full-text search query. Present only on backends that declare
+     * `search.fullText`. There is no client-side fallback — the only
+     * in-tree backend that supports it is Firestore Enterprise (via
+     * Pipeline `search({ query: documentMatches(...) })`); Standard and
+     * the SQLite-shaped backends throw `UNSUPPORTED_OPERATION` from the
+     * client wrapper.
+     *
+     * The backend is responsible for path normalisation (rewriting
+     * bare `fields` entries to `data.<name>`, rejecting envelope fields
+     * with `INVALID_QUERY`), translating to the underlying SDK call,
+     * and decoding the result into `StoredGraphRecord[]`.
+     *
+     * Migrations are not applied to the result. The search index walked
+     * the raw stored shape; rehydrating into the migration pipeline
+     * would change the candidate set the index already scored.
+     */
+    fullTextSearch?(params: FullTextSearchParams): Promise<StoredGraphRecord[]>;
+    /**
+     * Run a geospatial distance search. Present only on backends that
+     * declare `search.geo`. There is no client-side fallback — only
+     * Firestore Enterprise has a native geo index (translated via
+     * Pipeline `search({ query: geoDistance(...).lessThanOrEqual(...) })`).
+     * Backends without the cap throw `UNSUPPORTED_OPERATION` from the
+     * client wrapper.
+     *
+     * The backend is responsible for `geoField` path normalisation,
+     * translating `point` to a Firestore `GeoPoint`, applying the
+     * radius cap inside the search query, and (when
+     * `orderByDistance` is true / unset) emitting the
+     * `geoDistance(...).ascending()` ordering inside the search stage.
+     *
+     * Migrations are not applied to the result.
+     */
+    geoSearch?(params: GeoSearchParams): Promise<StoredGraphRecord[]>;
+}
+
+export { type DynamicRegistryConfig as $, type AggregateExtension as A, type BackendCapabilities as B, type BulkBatchError as C, DELETE_FIELD as D, type ExpandParams as E, type FindEdgesParams as F, type GraphRegistry as G, type BulkOptions as H, type IndexSpec as I, type JoinExtension as J, type BulkProgress as K, type BulkResult as L, type MigrationWriteBack as M, type Capability as N, type CascadeResult as O, type CoreGraphClient as P, type QueryPlan as Q, type RegistryEntry as R, type StorageBackend as S, type TransactionBackend as T, type UpdatePayload as U, type DefineTypeOptions as V, type WritableRecord as W, type DiscoveredEntity as X, type DistanceMeasure as Y, type DynamicGraphClient as Z, type DynamicGraphMethods as _, type BatchBackend as a, type EdgeTopology as a0, type EdgeTypeData as a1, type FindEdgesProjectedParams as a2, type FindNearestParams as a3, type FiregraphConfig as a4, type FullTextSearchExtension as a5, type GeoExtension as a6, type GraphBatch as a7, type GraphClientOptions as a8, type GraphRecord as a9, type GraphTransaction as aa, type GraphWriter as ab, type HopDefinition as ac, type HopResult as ad, type IndexFieldSpec as ae, type NodeTypeData as af, type ProjectedRow as ag, type QueryMode as ah, type QueryOptions as ai, type RawFirestoreExtension as aj, type RawSqlExtension as ak, type RealtimeListenExtension as al, type ScanProtection as am, type SelectExtension as an, type TraversalOptions as ao, type TraversalResult as ap, type VectorExtension as aq, type ViewContext as ar, type ViewDefaultsConfig as as, type ViewResolverConfig as at, type WhereClause as au, defineConfig as av, resolveView as aw, type BulkUpdatePatch as b, type DataPathOp as c, type DmlExtension as d, type ExpandResult as e, type WriteMode as f, createCapabilities as g, deleteField as h, flattenPatch as i, intersectCapabilities as j, isDeleteSentinel as k, type DiscoveryResult as l, type StoredGraphRecord as m, type MigrationStep as n, type FindNodesParams as o, type QueryFilter as p, type MigrationExecutor as q, type MigrationFn as r, type StoredMigrationStep as s, type GraphClient as t, type GraphReader as u, type TraversalBuilder as v, type AggregateField as w, type AggregateOp as x, type AggregateResult as y, type AggregateSpec as z };