@typicalday/firegraph 0.7.0 → 0.8.0

package/dist/index.d.cts

@@ -1,100 +1,158 @@
+import { S as StoredGraphRecord, Q as QueryFilter, c as QueryOptions, d as GraphReader, B as BulkOptions, C as CascadeResult, F as FindEdgesParams, e as BulkResult, G as GraphClientOptions, b as GraphClient, a as DynamicGraphClient, f as DiscoveryResult, R as RegistryEntry, g as GraphRegistry, M as MigrationExecutor, D as DynamicRegistryConfig, h as MigrationWriteBack, i as MigrationStep, j as QueryPlan, k as FindNodesParams, l as GraphRecord, m as MigrationFn, n as StoredMigrationStep, T as TraversalBuilder } from './types-BVtx9zLv.cjs';
+export { o as BulkBatchError, p as BulkProgress, q as DefineTypeOptions, r as DiscoveredEntity, E as EdgeTopology, s as EdgeTypeData, t as FiregraphConfig, u as GraphBatch, v as GraphTransaction, w as GraphWriter, H as HopDefinition, x as HopResult, N as NodeTypeData, y as QueryMode, z as ScanProtection, A as TraversalOptions, I as TraversalResult, V as ViewContext, J as ViewDefaultsConfig, K as ViewResolverConfig, W as WhereClause, L as defineConfig, O as resolveView } from './types-BVtx9zLv.cjs';
+export { CodegenOptions, generateTypes } from './codegen/index.cjs';
 import { Firestore } from '@google-cloud/firestore';
-import { G as GraphClientOptions, D as DynamicRegistryConfig, a as DynamicGraphClient, b as GraphClient, c as GraphRegistry, R as RegistryEntry, d as DiscoveryResult, e as GraphReader, M as MigrationExecutor, f as GraphRecord, F as FindEdgesParams, Q as QueryPlan, g as FindNodesParams, T as TraversalBuilder, h as MigrationFn, S as StoredMigrationStep, i as MigrationStep, j as StoredGraphRecord, k as MigrationWriteBack, l as QueryFilter } from './index-B9aodfYD.cjs';
-export { B as BulkBatchError, m as BulkOptions, n as BulkProgress, o as BulkResult, C as CascadeResult, p as CodegenOptions, q as DefineTypeOptions, r as DiscoveredEntity, E as EdgeTopology, s as EdgeTypeData, t as FiregraphConfig, u as GraphBatch, v as GraphTransaction, w as GraphWriter, H as HopDefinition, x as HopResult, N as NodeTypeData, y as QueryMode, z as QueryOptions, A as ScanProtection, I as TraversalOptions, J as TraversalResult, V as ViewContext, K as ViewDefaultsConfig, L as ViewResolverConfig, W as WhereClause, O as defineConfig, P as generateTypes, U as resolveView } from './index-B9aodfYD.cjs';
-export { E as EntityViewConfig, a as EntityViewMeta, V as ViewComponentClass, b as ViewMeta, c as ViewRegistry, d as ViewRegistryInput, e as defineViews } from './views-DL60k0cf.cjs';
 export { Q as QueryClient, a as QueryClientError, b as QueryClientErrorCode, c as QueryClientOptions } from './client-Bk2Cm6xv.cjs';
-
-declare function createGraphClient(db: Firestore, collectionPath: string, options: GraphClientOptions & {
-    registryMode: DynamicRegistryConfig;
-}): DynamicGraphClient;
-declare function createGraphClient(db: Firestore, collectionPath: string, options?: GraphClientOptions): GraphClient;
+export { E as EntityViewConfig, a as EntityViewMeta, V as ViewComponentClass, b as ViewMeta, c as ViewRegistry, d as ViewRegistryInput, e as defineViews } from './views-DL60k0cf.cjs';
 
 /**
- * Build a registry from either explicit entries or a DiscoveryResult.
+ * Backend abstraction for firegraph.
  *
- * @example
- * ```ts
- * // From explicit entries (programmatic)
- * const registry = createRegistry([
- *   { aType: 'user', axbType: 'is', bType: 'user', jsonSchema: userSchema },
- *   { aType: 'user', axbType: 'follows', bType: 'user', jsonSchema: followsSchema },
- * ]);
+ * `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.
  *
- * // From discovery result (folder convention)
- * const discovered = await discoverEntities('./entities');
- * const registry = createRegistry(discovered);
- * ```
+ * `GraphClientImpl` and friends depend only on this interface — they have
+ * no direct knowledge of Firestore or SQLite.
  */
-declare function createRegistry(input: RegistryEntry[] | DiscoveryResult): GraphRegistry;
+
 /**
- * Create a merged registry where `base` entries take priority and `extension`
- * entries fill in gaps. Lookups and validation check `base` first; only if the
- * triple is not found there does the merged registry fall through to
- * `extension`.
+ * 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;
+}
+/**
+ * Patch shape for `updateDoc`. Captures the two patterns that exist today:
+ *   - `dataFields`: shallow merge under `data` (used by `updateNode`)
+ *   - `replaceData`: full data replacement (used by migration write-back)
+ *   - `v`: optional schema-version stamp
  *
- * The `entries()` method returns a deduplicated list (base wins on collision).
- * The `lookupByAxbType()` method merges results from both registries,
- * deduplicating by triple key with base entries winning.
+ * `updatedAt` is always set by the backend.
  */
-declare function createMergedRegistry(base: GraphRegistry, extension: GraphRegistry): GraphRegistry;
-
-/** The aType used for node type definition meta-nodes. */
-declare const META_NODE_TYPE = "nodeType";
-/** The aType used for edge type definition meta-nodes. */
-declare const META_EDGE_TYPE = "edgeType";
-/** JSON Schema for the `data` payload of a `nodeType` meta-node. */
-declare const NODE_TYPE_SCHEMA: object;
-/** JSON Schema for the `data` payload of an `edgeType` meta-node. */
-declare const EDGE_TYPE_SCHEMA: object;
-/** Registry entries for the two meta-types (always present). */
-declare const BOOTSTRAP_ENTRIES: readonly RegistryEntry[];
+interface UpdatePayload {
+    dataFields?: Record<string, unknown>;
+    replaceData?: Record<string, unknown>;
+    v?: number;
+}
 /**
- * Build the bootstrap registry that validates meta-type writes.
- * This is always available, even before any dynamic types are loaded.
+ * 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): Promise<void>;
+    updateDoc(docId: string, update: UpdatePayload): Promise<void>;
+    deleteDoc(docId: string): Promise<void>;
+}
+/**
+ * Atomic multi-write batch.
  */
-declare function createBootstrapRegistry(): GraphRegistry;
+interface BatchBackend {
+    setDoc(docId: string, record: WritableRecord): void;
+    updateDoc(docId: string, update: UpdatePayload): void;
+    deleteDoc(docId: string): void;
+    commit(): Promise<void>;
+}
 /**
- * Generate a deterministic UID for a meta-type definition.
- * This ensures that defining the same type name always targets the same
- * Firestore document, enabling upsert semantics.
+ * The single storage abstraction.
+ *
+ * Each backend instance is scoped to a "graph location" — for Firestore
+ * that's a collection path; for SQLite it's a (table, scopePath) pair.
+ * `subgraph()` returns a child backend bound to a nested location.
+ */
+interface StorageBackend {
+    /** Backend-internal location identifier (collection path or table name). */
+    readonly collectionPath: string;
+    /** Subgraph scope (empty string for root). */
+    readonly scopePath: string;
+    getDoc(docId: string): Promise<StoredGraphRecord | null>;
+    query(filters: QueryFilter[], options?: QueryOptions): Promise<StoredGraphRecord[]>;
+    setDoc(docId: string, record: WritableRecord): 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[]>;
+}
+
+/**
+ * Create a `GraphClient` backed by an arbitrary `StorageBackend`.
  *
- * Format: 21-char base64url substring of SHA-256(`metaType:name`).
+ * Used by backend-specific factories (D1, DO-SQLite, etc.) — most callers
+ * should use the higher-level `createGraphClient(firestore, ...)` overload
+ * below or import the equivalent from `firegraph/d1` / `firegraph/do-sqlite`.
  */
-declare function generateDeterministicUid(metaType: string, name: string): string;
+declare function createGraphClientFromBackend(backend: StorageBackend, options?: GraphClientOptions, metaBackend?: StorageBackend): GraphClient | DynamicGraphClient;
+
 /**
- * Read meta-type nodes from the graph and compile them into a GraphRegistry.
+ * Cross-graph edge resolution utilities.
  *
- * The returned registry includes both the dynamic entries AND the bootstrap
- * meta-type entries, so meta-type writes remain validateable after a reload.
+ * Provides path-scanning resolution for determining whether an edge's source
+ * (aUid) is an ancestor node by checking if the UID appears in the Firestore
+ * collection path.
  *
- * @param reader - A GraphReader pointed at the collection containing meta-nodes.
- * @param executor - Optional custom executor for compiling stored migration source strings.
+ * Firestore paths have a rigid alternating structure:
+ *   collection / docId / collection / docId / collection
+ *
+ * Given a path like `graph/A/workspace/B/context`, segments at even indices
+ * are collection names and odd indices are document IDs. When we find a UID
+ * at an odd index, the collection containing that document is the path up to
+ * (and including) the preceding even-index segment.
  */
-declare function createRegistryFromGraph(reader: GraphReader, executor?: MigrationExecutor): Promise<GraphRegistry>;
-
-declare function generateId(): string;
-
-declare function computeNodeDocId(uid: string): string;
-declare function computeEdgeDocId(aUid: string, axbType: string, bUid: string): string;
-
-declare function buildNodeRecord(aType: string, uid: string, data: Record<string, unknown>): GraphRecord;
-declare function buildEdgeRecord(aType: string, aUid: string, axbType: string, bType: string, bUid: string, data: Record<string, unknown>): GraphRecord;
-
-declare function buildEdgeQueryPlan(params: FindEdgesParams): QueryPlan;
-declare function buildNodeQueryPlan(params: FindNodesParams): QueryPlan;
-
 /**
- * Create a traversal builder for multi-hop graph traversal.
+ * Parse a Firestore collection path and determine the collection path
+ * where a given UID's document lives, if that UID is an ancestor in the path.
  *
- * Accepts either a `GraphReader` (backwards compatible) or a `GraphClient`.
- * When a `GraphClient` is provided, cross-graph traversal via `targetGraph`
- * is supported — the traversal can follow edges into subgraphs.
+ * @param collectionPath - The full Firestore collection path of the current client
+ * @param uid - The UID to search for in the path
+ * @returns The collection path containing the UID, or `null` if not found in the path
  *
- * @param reader - A `GraphClient` or `GraphReader` to execute queries against
- * @param startUid - UID of the starting node
- * @param registry - Optional registry for automatic `targetGraph` resolution
+ * @example
+ * ```ts
+ * // Path: graph/A/workspace/B/context
+ * resolveAncestorCollection('graph/A/workspace/B/context', 'A')
+ * // → 'graph'
+ *
+ * resolveAncestorCollection('graph/A/workspace/B/context', 'B')
+ * // → 'graph/A/workspace'
+ *
+ * resolveAncestorCollection('graph/A/workspace/B/context', 'unknown')
+ * // → null
+ * ```
  */
-declare function createTraversal(reader: GraphClient | GraphReader, startUid: string, registry?: GraphRegistry): TraversalBuilder;
+declare function resolveAncestorCollection(collectionPath: string, uid: string): string | null;
+/**
+ * Check whether a UID belongs to an ancestor node by scanning the collection path.
+ *
+ * @param collectionPath - The full Firestore collection path of the current client
+ * @param uid - The UID to check
+ * @returns `true` if the UID appears as a document segment in the path
+ */
+declare function isAncestorUid(collectionPath: string, uid: string): boolean;
 
 declare class FiregraphError extends Error {
     readonly code: string;
@@ -182,82 +240,97 @@ interface DiscoverResult {
  */
 declare function discoverEntities(entitiesDir: string): DiscoverResult;
 
+declare function computeNodeDocId(uid: string): string;
+declare function computeEdgeDocId(aUid: string, axbType: string, bUid: string): string;
+
+/** The aType used for node type definition meta-nodes. */
+declare const META_NODE_TYPE = "nodeType";
+/** The aType used for edge type definition meta-nodes. */
+declare const META_EDGE_TYPE = "edgeType";
+/** JSON Schema for the `data` payload of a `nodeType` meta-node. */
+declare const NODE_TYPE_SCHEMA: object;
+/** JSON Schema for the `data` payload of an `edgeType` meta-node. */
+declare const EDGE_TYPE_SCHEMA: object;
+/** Registry entries for the two meta-types (always present). */
+declare const BOOTSTRAP_ENTRIES: readonly RegistryEntry[];
 /**
- * Scope path matching for subgraph-level registry constraints.
- *
- * Scope paths are slash-separated names derived from the chain of
- * `subgraph()` calls (e.g., `'agents'`, `'agents/memories'`).
- * The root graph has an empty scope path (`''`).
- *
- * Patterns:
- *   - `'root'`              — matches only the root graph (empty scope path)
- *   - `'agents'`            — matches exactly `'agents'`
- *   - `'agents/memories'`   — matches exactly `'agents/memories'`
- *   - `'*​/agents'`          — `*` matches one segment: `'foo/agents'` but not `'a/b/agents'`
- *   - `'**​/memories'`       — `**` matches zero or more segments
- *   - `'**'`                — matches everything including root
+ * Build the bootstrap registry that validates meta-type writes.
+ * This is always available, even before any dynamic types are loaded.
  */
+declare function createBootstrapRegistry(): GraphRegistry;
 /**
- * Test whether a scope path matches a single pattern.
+ * Generate a deterministic UID for a meta-type definition.
+ * This ensures that defining the same type name always targets the same
+ * Firestore document, enabling upsert semantics.
  *
- * @param scopePath - The current scope path (empty string for root)
- * @param pattern - The pattern to match against
+ * Format: 21-char base64url substring of SHA-256(`metaType:name`).
  */
-declare function matchScope(scopePath: string, pattern: string): boolean;
+declare function generateDeterministicUid(metaType: string, name: string): string;
 /**
- * Test whether a scope path matches any pattern in a list.
- * Returns `true` if the list is empty or undefined (allowed everywhere).
+ * Read meta-type nodes from the graph and compile them into a GraphRegistry.
  *
- * @param scopePath - The current scope path (empty string for root)
- * @param patterns - Array of patterns to match against
+ * The returned registry includes both the dynamic entries AND the bootstrap
+ * meta-type entries, so meta-type writes remain validateable after a reload.
+ *
+ * @param reader - A GraphReader pointed at the collection containing meta-nodes.
+ * @param executor - Optional custom executor for compiling stored migration source strings.
  */
-declare function matchScopeAny(scopePath: string, patterns: string[]): boolean;
+declare function createRegistryFromGraph(reader: GraphReader, executor?: MigrationExecutor): Promise<GraphRegistry>;
 
 /**
- * Cross-graph edge resolution utilities.
- *
- * Provides path-scanning resolution for determining whether an edge's source
- * (aUid) is an ancestor node by checking if the UID appears in the Firestore
- * collection path.
+ * Firestore-specific client factory.
  *
- * Firestore paths have a rigid alternating structure:
- *   collection / docId / collection / docId / collection
- *
- * Given a path like `graph/A/workspace/B/context`, segments at even indices
- * are collection names and odd indices are document IDs. When we find a UID
- * at an odd index, the collection containing that document is the path up to
- * (and including) the preceding even-index segment.
+ * Kept in its own module so that bundlers don't pull
+ * `@google-cloud/firestore` into SQLite-only entry points
+ * (`firegraph/d1`, `firegraph/do-sqlite`).
  */
+
+declare function createGraphClient(db: Firestore, collectionPath: string, options: GraphClientOptions & {
+    registryMode: DynamicRegistryConfig;
+}): DynamicGraphClient;
+declare function createGraphClient(db: Firestore, collectionPath: string, options?: GraphClientOptions): GraphClient;
+
+declare function generateId(): string;
+
+interface FirestoreIndexField {
+    fieldPath: string;
+    order: 'ASCENDING' | 'DESCENDING';
+}
+interface FirestoreIndex {
+    collectionGroup: string;
+    queryScope: 'COLLECTION' | 'COLLECTION_GROUP';
+    fields: FirestoreIndexField[];
+}
+interface FirestoreIndexConfig {
+    indexes: FirestoreIndex[];
+    fieldOverrides: unknown[];
+}
 /**
- * Parse a Firestore collection path and determine the collection path
- * where a given UID's document lives, if that UID is an ancestor in the path.
- *
- * @param collectionPath - The full Firestore collection path of the current client
- * @param uid - The UID to search for in the path
- * @returns The collection path containing the UID, or `null` if not found in the path
+ * Generates a Firestore index configuration for a firegraph collection.
  *
- * @example
- * ```ts
- * // Path: graph/A/workspace/B/context
- * resolveAncestorCollection('graph/A/workspace/B/context', 'A')
- * // → 'graph'
+ * Always includes the 4 base composite indexes. If an entity discovery result
+ * is provided, generates additional data-field indexes for common query
+ * patterns on node data fields:
+ *   (aType, axbType, data.{field})
  *
- * resolveAncestorCollection('graph/A/workspace/B/context', 'B')
- * // → 'graph/A/workspace'
+ * When registry entries with `targetGraph` are provided, also generates
+ * collection group indexes for `findEdgesGlobal()` queries. The collection
+ * group name defaults to `'graph'` (the standard subgraph name) but can be
+ * overridden per `targetGraph` value.
  *
- * resolveAncestorCollection('graph/A/workspace/B/context', 'unknown')
- * // → null
- * ```
+ * @param collection - Firestore collection name (e.g. 'graph')
+ * @param entities - Optional discovery result for per-entity data field indexes
+ * @param registryEntries - Optional registry entries; when any have `targetGraph`,
+ *   collection group indexes are generated for the distinct subgraph names
  */
-declare function resolveAncestorCollection(collectionPath: string, uid: string): string | null;
+declare function generateIndexConfig(collection: string, entities?: DiscoveryResult, registryEntries?: ReadonlyArray<RegistryEntry>): FirestoreIndexConfig;
+
 /**
- * Check whether a UID belongs to an ancestor node by scanning the collection path.
- *
- * @param collectionPath - The full Firestore collection path of the current client
- * @param uid - The UID to check
- * @returns `true` if the UID appears as a document segment in the path
+ * Default result limit applied to findEdges/findNodes queries
+ * when no explicit limit is provided. Prevents unbounded result sets
+ * that could be expensive on Enterprise Firestore.
  */
-declare function isAncestorUid(collectionPath: string, uid: string): boolean;
+declare const DEFAULT_QUERY_LIMIT = 500;
 
 /**
  * JSON Schema validation and introspection utilities.
@@ -292,6 +365,107 @@ declare function compileSchema(schema: object, label?: string): (data: unknown)
  */
 declare function jsonSchemaToFieldMeta(schema: any): FieldMeta[];
 
+/**
+ * Migration pipeline for auto-migrating records on read.
+ *
+ * When a record's `v` is behind the version derived from the registry
+ * entry's migrations, the pipeline applies migration steps sequentially
+ * to bring the data up to the current version.
+ */
+
+/** Result of attempting to migrate a single record. */
+interface MigrationResult {
+    record: StoredGraphRecord;
+    migrated: boolean;
+    /** Resolved write-back mode for this record (entry-level > global > 'off'). */
+    writeBack: MigrationWriteBack;
+}
+/**
+ * Apply a chain of migration steps to transform data from `currentVersion`
+ * to `targetVersion`. Throws `MigrationError` if the chain is incomplete
+ * or a migration function fails.
+ *
+ * Returns the migrated data payload only — the caller is responsible for
+ * stamping `v` on the record envelope.
+ */
+declare function applyMigrationChain(data: Record<string, unknown>, currentVersion: number, targetVersion: number, migrations: MigrationStep[]): Promise<Record<string, unknown>>;
+/**
+ * Validate that a migration chain forms a contiguous path from version 0
+ * to the highest `toVersion`. Throws `MigrationError` if the chain has
+ * gaps or duplicate `fromVersion` values.
+ *
+ * Called at registry construction time to catch incomplete chains early,
+ * rather than at read time when a record is migrated.
+ */
+declare function validateMigrationChain(migrations: MigrationStep[], label: string): void;
+/**
+ * Attempt to migrate a single record based on its registry entry.
+ *
+ * Returns the original record unchanged if no migration is needed
+ * (no schema version, already at current version, or no migrations defined).
+ */
+declare function migrateRecord(record: StoredGraphRecord, registry: GraphRegistry, globalWriteBack?: MigrationWriteBack): Promise<MigrationResult>;
+/**
+ * Migrate an array of records, returning all results.
+ * If any single migration fails, the entire call rejects — a broken
+ * migration function is a bug that should surface immediately.
+ */
+declare function migrateRecords(records: StoredGraphRecord[], registry: GraphRegistry, globalWriteBack?: MigrationWriteBack): Promise<MigrationResult[]>;
+
+declare function buildEdgeQueryPlan(params: FindEdgesParams): QueryPlan;
+declare function buildNodeQueryPlan(params: FindNodesParams): QueryPlan;
+
+/**
+ * Result of analyzing a query for collection scan risk.
+ */
+interface QuerySafetyResult {
+    /** Whether the query matches a known indexed pattern. */
+    safe: boolean;
+    /** Human-readable explanation when the query is unsafe. */
+    reason?: string;
+}
+/**
+ * Analyzes a set of query filters to determine whether the query would
+ * likely cause a full collection scan on Firestore Enterprise.
+ *
+ * A query is considered "safe" if the builtin fields present in the filters
+ * match at least one known composite index pattern. Queries that only use
+ * `data.*` fields without a safe base pattern are flagged as unsafe.
+ */
+declare function analyzeQuerySafety(filters: QueryFilter[]): QuerySafetyResult;
+
+declare function buildNodeRecord(aType: string, uid: string, data: Record<string, unknown>): GraphRecord;
+declare function buildEdgeRecord(aType: string, aUid: string, axbType: string, bType: string, bUid: string, data: Record<string, unknown>): GraphRecord;
+
+/**
+ * Build a registry from either explicit entries or a DiscoveryResult.
+ *
+ * @example
+ * ```ts
+ * // From explicit entries (programmatic)
+ * const registry = createRegistry([
+ *   { aType: 'user', axbType: 'is', bType: 'user', jsonSchema: userSchema },
+ *   { aType: 'user', axbType: 'follows', bType: 'user', jsonSchema: followsSchema },
+ * ]);
+ *
+ * // From discovery result (folder convention)
+ * const discovered = await discoverEntities('./entities');
+ * const registry = createRegistry(discovered);
+ * ```
+ */
+declare function createRegistry(input: RegistryEntry[] | DiscoveryResult): GraphRegistry;
+/**
+ * Create a merged registry where `base` entries take priority and `extension`
+ * entries fill in gaps. Lookups and validation check `base` first; only if the
+ * triple is not found there does the merged registry fall through to
+ * `extension`.
+ *
+ * The `entries()` method returns a deduplicated list (base wins on collision).
+ * The `lookupByAxbType()` method merges results from both registries,
+ * deduplicating by triple key with base entries winning.
+ */
+declare function createMergedRegistry(base: GraphRegistry, extension: GraphRegistry): GraphRegistry;
+
 /**
  * Sandbox module for compiling dynamic registry migration source strings
  * into executable functions.
@@ -365,6 +539,37 @@ declare function compileMigrations(stored: StoredMigrationStep[], executor?: Mig
  */
 declare function destroySandboxWorker(): Promise<void>;
 
+/**
+ * Scope path matching for subgraph-level registry constraints.
+ *
+ * Scope paths are slash-separated names derived from the chain of
+ * `subgraph()` calls (e.g., `'agents'`, `'agents/memories'`).
+ * The root graph has an empty scope path (`''`).
+ *
+ * Patterns:
+ *   - `'root'`              — matches only the root graph (empty scope path)
+ *   - `'agents'`            — matches exactly `'agents'`
+ *   - `'agents/memories'`   — matches exactly `'agents/memories'`
+ *   - `'*​/agents'`          — `*` matches one segment: `'foo/agents'` but not `'a/b/agents'`
+ *   - `'**​/memories'`       — `**` matches zero or more segments
+ *   - `'**'`                — matches everything including root
+ */
+/**
+ * Test whether a scope path matches a single pattern.
+ *
+ * @param scopePath - The current scope path (empty string for root)
+ * @param pattern - The pattern to match against
+ */
+declare function matchScope(scopePath: string, pattern: string): boolean;
+/**
+ * Test whether a scope path matches any pattern in a list.
+ * Returns `true` if the list is empty or undefined (allowed everywhere).
+ *
+ * @param scopePath - The current scope path (empty string for root)
+ * @param patterns - Array of patterns to match against
+ */
+declare function matchScopeAny(scopePath: string, patterns: string[]): boolean;
+
 /**
  * Firestore-aware serialization for the sandbox migration pipeline.
  *
@@ -402,109 +607,16 @@ declare function serializeFirestoreTypes(data: Record<string, unknown>): Record<
 declare function deserializeFirestoreTypes(data: Record<string, unknown>, db?: Firestore): Record<string, unknown>;
 
 /**
- * Migration pipeline for auto-migrating records on read.
- *
- * When a record's `v` is behind the version derived from the registry
- * entry's migrations, the pipeline applies migration steps sequentially
- * to bring the data up to the current version.
- */
-
-/** Result of attempting to migrate a single record. */
-interface MigrationResult {
-    record: StoredGraphRecord;
-    migrated: boolean;
-    /** Resolved write-back mode for this record (entry-level > global > 'off'). */
-    writeBack: MigrationWriteBack;
-}
-/**
- * Apply a chain of migration steps to transform data from `currentVersion`
- * to `targetVersion`. Throws `MigrationError` if the chain is incomplete
- * or a migration function fails.
- *
- * Returns the migrated data payload only — the caller is responsible for
- * stamping `v` on the record envelope.
- */
-declare function applyMigrationChain(data: Record<string, unknown>, currentVersion: number, targetVersion: number, migrations: MigrationStep[]): Promise<Record<string, unknown>>;
-/**
- * Validate that a migration chain forms a contiguous path from version 0
- * to the highest `toVersion`. Throws `MigrationError` if the chain has
- * gaps or duplicate `fromVersion` values.
- *
- * Called at registry construction time to catch incomplete chains early,
- * rather than at read time when a record is migrated.
- */
-declare function validateMigrationChain(migrations: MigrationStep[], label: string): void;
-/**
- * Attempt to migrate a single record based on its registry entry.
- *
- * Returns the original record unchanged if no migration is needed
- * (no schema version, already at current version, or no migrations defined).
- */
-declare function migrateRecord(record: StoredGraphRecord, registry: GraphRegistry, globalWriteBack?: MigrationWriteBack): Promise<MigrationResult>;
-/**
- * Migrate an array of records, returning all results.
- * If any single migration fails, the entire call rejects — a broken
- * migration function is a bug that should surface immediately.
- */
-declare function migrateRecords(records: StoredGraphRecord[], registry: GraphRegistry, globalWriteBack?: MigrationWriteBack): Promise<MigrationResult[]>;
-
-interface FirestoreIndexField {
-    fieldPath: string;
-    order: 'ASCENDING' | 'DESCENDING';
-}
-interface FirestoreIndex {
-    collectionGroup: string;
-    queryScope: 'COLLECTION' | 'COLLECTION_GROUP';
-    fields: FirestoreIndexField[];
-}
-interface FirestoreIndexConfig {
-    indexes: FirestoreIndex[];
-    fieldOverrides: unknown[];
-}
-/**
- * Generates a Firestore index configuration for a firegraph collection.
- *
- * Always includes the 4 base composite indexes. If an entity discovery result
- * is provided, generates additional data-field indexes for common query
- * patterns on node data fields:
- *   (aType, axbType, data.{field})
- *
- * When registry entries with `targetGraph` are provided, also generates
- * collection group indexes for `findEdgesGlobal()` queries. The collection
- * group name defaults to `'graph'` (the standard subgraph name) but can be
- * overridden per `targetGraph` value.
+ * Create a traversal builder for multi-hop graph traversal.
  *
- * @param collection - Firestore collection name (e.g. 'graph')
- * @param entities - Optional discovery result for per-entity data field indexes
- * @param registryEntries - Optional registry entries; when any have `targetGraph`,
- *   collection group indexes are generated for the distinct subgraph names
- */
-declare function generateIndexConfig(collection: string, entities?: DiscoveryResult, registryEntries?: ReadonlyArray<RegistryEntry>): FirestoreIndexConfig;
-
-/**
- * Result of analyzing a query for collection scan risk.
- */
-interface QuerySafetyResult {
-    /** Whether the query matches a known indexed pattern. */
-    safe: boolean;
-    /** Human-readable explanation when the query is unsafe. */
-    reason?: string;
-}
-/**
- * Analyzes a set of query filters to determine whether the query would
- * likely cause a full collection scan on Firestore Enterprise.
+ * Accepts either a `GraphReader` (backwards compatible) or a `GraphClient`.
+ * When a `GraphClient` is provided, cross-graph traversal via `targetGraph`
+ * is supported — the traversal can follow edges into subgraphs.
  *
- * A query is considered "safe" if the builtin fields present in the filters
- * match at least one known composite index pattern. Queries that only use
- * `data.*` fields without a safe base pattern are flagged as unsafe.
- */
-declare function analyzeQuerySafety(filters: QueryFilter[]): QuerySafetyResult;
-
-/**
- * Default result limit applied to findEdges/findNodes queries
- * when no explicit limit is provided. Prevents unbounded result sets
- * that could be expensive on Enterprise Firestore.
+ * @param reader - A `GraphClient` or `GraphReader` to execute queries against
+ * @param startUid - UID of the starting node
+ * @param registry - Optional registry for automatic `targetGraph` resolution
  */
-declare const DEFAULT_QUERY_LIMIT = 500;
+declare function createTraversal(reader: GraphClient | GraphReader, startUid: string, registry?: GraphRegistry): TraversalBuilder;
 
-export { BOOTSTRAP_ENTRIES, DEFAULT_QUERY_LIMIT, type DiscoverResult, DiscoveryError, DiscoveryResult, type DiscoveryWarning, DynamicGraphClient, DynamicRegistryConfig, DynamicRegistryError, EDGE_TYPE_SCHEMA, EdgeNotFoundError, type FieldMeta, FindEdgesParams, FindNodesParams, FiregraphError, type FirestoreIndex, type FirestoreIndexConfig, type FirestoreIndexField, GraphClient, GraphClientOptions, GraphReader, GraphRecord, GraphRegistry, InvalidQueryError, META_EDGE_TYPE, META_NODE_TYPE, MigrationError, MigrationExecutor, MigrationFn, type MigrationResult, MigrationStep, MigrationWriteBack, NODE_TYPE_SCHEMA, NodeNotFoundError, QueryFilter, QueryPlan, QuerySafetyError, type QuerySafetyResult, RegistryEntry, RegistryScopeError, RegistryViolationError, SERIALIZATION_TAG, StoredGraphRecord, StoredMigrationStep, TraversalBuilder, TraversalError, ValidationError, analyzeQuerySafety, applyMigrationChain, buildEdgeQueryPlan, buildEdgeRecord, buildNodeQueryPlan, buildNodeRecord, compileMigrationFn, compileMigrations, compileSchema, computeEdgeDocId, computeNodeDocId, createBootstrapRegistry, createGraphClient, createMergedRegistry, createRegistry, createRegistryFromGraph, createTraversal, defaultExecutor, deserializeFirestoreTypes, destroySandboxWorker, discoverEntities, generateDeterministicUid, generateId, generateIndexConfig, isAncestorUid, isTaggedValue, jsonSchemaToFieldMeta, matchScope, matchScopeAny, migrateRecord, migrateRecords, precompileSource, resolveAncestorCollection, serializeFirestoreTypes, validateMigrationChain };
+export { BOOTSTRAP_ENTRIES, BulkOptions, BulkResult, CascadeResult, DEFAULT_QUERY_LIMIT, type DiscoverResult, DiscoveryError, DiscoveryResult, type DiscoveryWarning, DynamicGraphClient, DynamicRegistryConfig, DynamicRegistryError, EDGE_TYPE_SCHEMA, EdgeNotFoundError, type FieldMeta, FindEdgesParams, FindNodesParams, FiregraphError, type FirestoreIndex, type FirestoreIndexConfig, type FirestoreIndexField, GraphClient, GraphClientOptions, GraphReader, GraphRecord, GraphRegistry, InvalidQueryError, META_EDGE_TYPE, META_NODE_TYPE, MigrationError, MigrationExecutor, MigrationFn, type MigrationResult, MigrationStep, MigrationWriteBack, NODE_TYPE_SCHEMA, NodeNotFoundError, QueryFilter, QueryOptions, QueryPlan, QuerySafetyError, type QuerySafetyResult, RegistryEntry, RegistryScopeError, RegistryViolationError, SERIALIZATION_TAG, StoredGraphRecord, StoredMigrationStep, TraversalBuilder, TraversalError, ValidationError, analyzeQuerySafety, applyMigrationChain, buildEdgeQueryPlan, buildEdgeRecord, buildNodeQueryPlan, buildNodeRecord, compileMigrationFn, compileMigrations, compileSchema, computeEdgeDocId, computeNodeDocId, createBootstrapRegistry, createGraphClient, createGraphClientFromBackend, createMergedRegistry, createRegistry, createRegistryFromGraph, createTraversal, defaultExecutor, deserializeFirestoreTypes, destroySandboxWorker, discoverEntities, generateDeterministicUid, generateId, generateIndexConfig, isAncestorUid, isTaggedValue, jsonSchemaToFieldMeta, matchScope, matchScopeAny, migrateRecord, migrateRecords, precompileSource, resolveAncestorCollection, serializeFirestoreTypes, validateMigrationChain };