@typicalday/firegraph 0.7.1 → 0.9.0

package/dist/index.d.ts

@@ -1,136 +1,66 @@
+import { S as StorageBackend, F as FiregraphError } from './scope-path-BtajqNK5.js';
+export { C as CrossBackendTransactionError, D as DynamicRegistryError, E as EdgeNotFoundError, I as InvalidQueryError, M as MigrationError, N as NodeNotFoundError, Q as QuerySafetyError, R as RegistryScopeError, c as RegistryViolationError, a as StorageScopeSegment, d as TraversalError, V as ValidationError, b as appendStorageScope, i as isAncestorScopeUid, p as parseStorageScope, r as resolveAncestorScope } from './scope-path-BtajqNK5.js';
+import { G as GraphClientOptions, b as GraphClient, a as DynamicGraphClient, c as DiscoveryResult, R as RegistryEntry, d as GraphRegistry, e as GraphReader, M as MigrationExecutor, D as DynamicRegistryConfig, S as StoredGraphRecord, f as MigrationWriteBack, g as MigrationStep, F as FindEdgesParams, Q as QueryPlan, h as FindNodesParams, i as QueryFilter, j as GraphRecord, k as MigrationFn, l as StoredMigrationStep, T as TraversalBuilder } from './types-DfWVTsMn.js';
+export { B as BulkBatchError, m as BulkOptions, n as BulkProgress, o as BulkResult, C as CascadeResult, p as DefineTypeOptions, q as DiscoveredEntity, E as EdgeTopology, r as EdgeTypeData, s as FiregraphConfig, t as GraphBatch, u as GraphTransaction, v as GraphWriter, H as HopDefinition, w as HopResult, N as NodeTypeData, x as QueryMode, y as QueryOptions, 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-DfWVTsMn.js';
+export { CodegenOptions, generateTypes } from './codegen/index.js';
 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.js';
-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.js';
-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.js';
 export { Q as QueryClient, a as QueryClientError, b as QueryClientErrorCode, c as QueryClientOptions } from './client-Bk2Cm6xv.js';
+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.js';
 
-declare function createGraphClient(db: Firestore, collectionPath: string, options: GraphClientOptions & {
-    registryMode: DynamicRegistryConfig;
-}): DynamicGraphClient;
-declare function createGraphClient(db: Firestore, collectionPath: string, options?: GraphClientOptions): GraphClient;
-
-/**
- * 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`.
+ * Create a `GraphClient` backed by an arbitrary `StorageBackend`.
  *
- * 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.
+ * 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 createMergedRegistry(base: GraphRegistry, extension: GraphRegistry): GraphRegistry;
+declare function createGraphClientFromBackend(backend: StorageBackend, options?: GraphClientOptions, metaBackend?: StorageBackend): GraphClient | DynamicGraphClient;
 
-/** 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[];
-/**
- * Build the bootstrap registry that validates meta-type writes.
- * This is always available, even before any dynamic types are loaded.
- */
-declare function createBootstrapRegistry(): GraphRegistry;
 /**
- * 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.
+ * Cross-graph edge resolution utilities.
  *
- * Format: 21-char base64url substring of SHA-256(`metaType:name`).
+ * 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 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 generateDeterministicUid(metaType: string, name: string): string;
 /**
- * Read meta-type nodes from the graph and compile them into a GraphRegistry.
+ * 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.
  *
- * The returned registry includes both the dynamic entries AND the bootstrap
- * meta-type entries, so meta-type writes remain validateable after a reload.
+ * @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 GraphReader pointed at the collection containing meta-nodes.
- * @param executor - Optional custom executor for compiling stored migration source strings.
+ * @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 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;
-
+declare function resolveAncestorCollection(collectionPath: string, uid: string): string | null;
 /**
- * Create a traversal builder for multi-hop graph traversal.
- *
- * 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.
+ * Check whether a UID belongs to an ancestor node by scanning the collection 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
+ * @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 createTraversal(reader: GraphClient | GraphReader, startUid: string, registry?: GraphRegistry): TraversalBuilder;
-
-declare class FiregraphError extends Error {
-    readonly code: string;
-    constructor(message: string, code: string);
-}
-declare class NodeNotFoundError extends FiregraphError {
-    constructor(uid: string);
-}
-declare class EdgeNotFoundError extends FiregraphError {
-    constructor(aUid: string, axbType: string, bUid: string);
-}
-declare class ValidationError extends FiregraphError {
-    readonly details?: unknown | undefined;
-    constructor(message: string, details?: unknown | undefined);
-}
-declare class RegistryViolationError extends FiregraphError {
-    constructor(aType: string, axbType: string, bType: string);
-}
-declare class InvalidQueryError extends FiregraphError {
-    constructor(message: string);
-}
-declare class TraversalError extends FiregraphError {
-    constructor(message: string);
-}
-declare class DynamicRegistryError extends FiregraphError {
-    constructor(message: string);
-}
-declare class QuerySafetyError extends FiregraphError {
-    constructor(message: string);
-}
-declare class RegistryScopeError extends FiregraphError {
-    constructor(aType: string, axbType: string, bType: string, scopePath: string, allowedIn: string[]);
-}
-declare class MigrationError extends FiregraphError {
-    constructor(message: string);
-}
+declare function isAncestorUid(collectionPath: string, uid: string): boolean;
 
 /**
  * Entity Discovery — convention-based auto-discovery of entities from
@@ -182,82 +112,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 paths have a rigid alternating structure:
- *   collection / docId / collection / docId / collection
+ * Firestore-specific client factory.
  *
- * 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 +237,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 +411,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 +479,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, DEFAULT_QUERY_LIMIT, type DiscoverResult, DiscoveryError, DiscoveryResult, type DiscoveryWarning, DynamicGraphClient, DynamicRegistryConfig, EDGE_TYPE_SCHEMA, type FieldMeta, FindEdgesParams, FindNodesParams, FiregraphError, type FirestoreIndex, type FirestoreIndexConfig, type FirestoreIndexField, GraphClient, GraphClientOptions, GraphReader, GraphRecord, GraphRegistry, META_EDGE_TYPE, META_NODE_TYPE, MigrationExecutor, MigrationFn, type MigrationResult, MigrationStep, MigrationWriteBack, NODE_TYPE_SCHEMA, QueryFilter, QueryPlan, type QuerySafetyResult, RegistryEntry, SERIALIZATION_TAG, StoredGraphRecord, StoredMigrationStep, TraversalBuilder, 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 };