@typicalday/firegraph 0.3.0 → 0.5.0

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 import { Firestore } from '@google-cloud/firestore';
-import { G as GraphClientOptions, D as DynamicRegistryConfig, a as DynamicGraphClient, b as GraphClient, R as RegistryEntry, c as DiscoveryResult, d as GraphRegistry, e as GraphReader, f as GraphRecord, F as FindEdgesParams, Q as QueryPlan, g as FindNodesParams, T as TraversalBuilder, h as QueryFilter } from './index-CQkofEC_.cjs';
-export { B as BulkBatchError, i as BulkOptions, j as BulkProgress, k as BulkResult, C as CascadeResult, l as CodegenOptions, m as DefineTypeOptions, n as DiscoveredEntity, E as EdgeTopology, o as EdgeTypeData, p as FiregraphConfig, q as GraphBatch, r as GraphTransaction, s as GraphWriter, H as HopDefinition, t as HopResult, N as NodeTypeData, u as QueryMode, v as QueryOptions, S as ScanProtection, w as StoredGraphRecord, x as TraversalOptions, y as TraversalResult, V as ViewContext, z as ViewDefaultsConfig, A as ViewResolverConfig, W as WhereClause, I as defineConfig, J as generateTypes, K as resolveView } from './index-CQkofEC_.cjs';
+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';
 
@@ -26,6 +26,17 @@ declare function createGraphClient(db: Firestore, collectionPath: string, option
  * ```
  */
 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;
 
 /** The aType used for node type definition meta-nodes. */
 declare const META_NODE_TYPE = "nodeType";
@@ -57,8 +68,9 @@ declare function generateDeterministicUid(metaType: string, name: string): strin
  * 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 createRegistryFromGraph(reader: GraphReader): Promise<GraphRegistry>;
+declare function createRegistryFromGraph(reader: GraphReader, executor?: MigrationExecutor): Promise<GraphRegistry>;
 
 declare function generateId(): string;
 
@@ -116,6 +128,9 @@ declare class QuerySafetyError extends FiregraphError {
 declare class RegistryScopeError extends FiregraphError {
     constructor(aType: string, axbType: string, bType: string, scopePath: string, allowedIn: string[]);
 }
+declare class MigrationError extends FiregraphError {
+    constructor(message: string);
+}
 
 /**
  * Entity Discovery — convention-based auto-discovery of entities from
@@ -277,6 +292,162 @@ declare function compileSchema(schema: object, label?: string): (data: unknown)
  */
 declare function jsonSchemaToFieldMeta(schema: any): FieldMeta[];
 
+/**
+ * Sandbox module for compiling dynamic registry migration source strings
+ * into executable functions.
+ *
+ * Uses a dedicated worker thread with SES (Secure ECMAScript) Compartments
+ * for isolation. SES `lockdown()` and `Compartment` evaluation run in the
+ * worker thread so that the host process's intrinsics remain unaffected.
+ *
+ * Each migration function runs in a hardened compartment with no ambient
+ * authority — no access to `process`, `require`, `fetch`, `setTimeout`,
+ * or any other host-provided globals. Data crosses the compartment boundary
+ * as JSON strings to prevent prototype chain escapes.
+ *
+ * Static registry migrations are already in-memory functions and never
+ * go through this module.
+ */
+
+/**
+ * Default executor using a worker-thread SES Compartment with JSON marshaling.
+ *
+ * Migration source is compiled and executed inside an isolated SES
+ * Compartment running in a dedicated worker thread. The worker calls
+ * `lockdown()` in its own V8 isolate, leaving the host process's
+ * intrinsics completely unaffected.
+ *
+ * Data crosses the compartment boundary as JSON strings, preventing
+ * prototype chain escapes. The compartment receives only `JSON` as an
+ * endowment for parsing/stringifying data.
+ *
+ * The returned `MigrationFn` always returns a `Promise` (communication
+ * with the worker is inherently async via `postMessage`).
+ */
+declare function defaultExecutor(source: string): MigrationFn;
+/**
+ * Eagerly validate a migration source string by compiling it in the
+ * sandbox worker (or via a custom executor) without executing it.
+ *
+ * Use this to catch syntax errors at define-time or reload-time rather
+ * than at first migration execution.
+ *
+ * @throws {MigrationError} If the source is syntactically invalid or
+ *   does not produce a function.
+ */
+declare function precompileSource(source: string, executor?: MigrationExecutor): Promise<void>;
+/**
+ * Compile a stored migration source string into an executable function.
+ * Results are cached by SHA-256 hash of the source string so repeated
+ * reads never re-parse the same migration.
+ *
+ * **Important:** When using the default executor, this function does NOT
+ * validate the source synchronously — validation is deferred to the
+ * worker thread at execution time. Callers that need eager validation
+ * (e.g., `defineNodeType`, `reloadRegistry`) should call
+ * `precompileSource()` before or alongside `compileMigrationFn()`.
+ */
+declare function compileMigrationFn(source: string, executor?: MigrationExecutor): MigrationFn;
+/**
+ * Batch compile stored migration steps into executable MigrationStep[].
+ *
+ * With the default executor, source validation is deferred to execution
+ * time. Use `precompileSource()` to validate eagerly — see
+ * `createRegistryFromGraph()` for the recommended pattern.
+ */
+declare function compileMigrations(stored: StoredMigrationStep[], executor?: MigrationExecutor): MigrationStep[];
+/**
+ * Terminate the sandbox worker thread. The worker will be respawned
+ * on the next `defaultExecutor` call.
+ *
+ * Primarily useful for test cleanup to avoid vitest hanging on
+ * unfinished worker threads.
+ */
+declare function destroySandboxWorker(): Promise<void>;
+
+/**
+ * Firestore-aware serialization for the sandbox migration pipeline.
+ *
+ * Firestore documents can contain special types (Timestamp, GeoPoint,
+ * VectorValue, DocumentReference) that don't survive plain JSON
+ * round-tripping. This module provides tagged serialization: Firestore
+ * types are wrapped in tagged plain objects before JSON marshaling and
+ * reconstructed after.
+ *
+ * Only used by the `defaultExecutor` sandbox path. Static migrations
+ * (in-memory functions) receive raw Firestore objects directly.
+ */
+
+/** Sentinel key used to tag serialized Firestore types. */
+declare const SERIALIZATION_TAG: "__firegraph_ser__";
+/** Check if a value is a tagged serialized Firestore type. */
+declare function isTaggedValue(value: unknown): boolean;
+/**
+ * Recursively walk a data object and replace Firestore types with tagged
+ * plain objects suitable for JSON serialization.
+ *
+ * Returns a new object tree — the input is never mutated.
+ */
+declare function serializeFirestoreTypes(data: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Recursively walk a data object and reconstruct Firestore types from
+ * tagged plain objects.
+ *
+ * @param data - The data to deserialize (typically from JSON.parse)
+ * @param db - Optional Firestore instance for DocumentReference reconstruction.
+ *   If not provided, tagged DocumentReferences are left as-is with a one-time warning.
+ *
+ * Returns a new object tree — the input is never mutated.
+ */
+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';
@@ -336,4 +507,4 @@ declare function analyzeQuerySafety(filters: QueryFilter[]): QuerySafetyResult;
  */
 declare const DEFAULT_QUERY_LIMIT = 500;
 
-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, NODE_TYPE_SCHEMA, NodeNotFoundError, QueryFilter, QueryPlan, QuerySafetyError, type QuerySafetyResult, RegistryEntry, RegistryScopeError, RegistryViolationError, TraversalBuilder, TraversalError, ValidationError, analyzeQuerySafety, buildEdgeQueryPlan, buildEdgeRecord, buildNodeQueryPlan, buildNodeRecord, compileSchema, computeEdgeDocId, computeNodeDocId, createBootstrapRegistry, createGraphClient, createRegistry, createRegistryFromGraph, createTraversal, discoverEntities, generateDeterministicUid, generateId, generateIndexConfig, isAncestorUid, jsonSchemaToFieldMeta, matchScope, matchScopeAny, resolveAncestorCollection };
+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 };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { Firestore } from '@google-cloud/firestore';
-import { G as GraphClientOptions, D as DynamicRegistryConfig, a as DynamicGraphClient, b as GraphClient, R as RegistryEntry, c as DiscoveryResult, d as GraphRegistry, e as GraphReader, f as GraphRecord, F as FindEdgesParams, Q as QueryPlan, g as FindNodesParams, T as TraversalBuilder, h as QueryFilter } from './index-CQkofEC_.js';
-export { B as BulkBatchError, i as BulkOptions, j as BulkProgress, k as BulkResult, C as CascadeResult, l as CodegenOptions, m as DefineTypeOptions, n as DiscoveredEntity, E as EdgeTopology, o as EdgeTypeData, p as FiregraphConfig, q as GraphBatch, r as GraphTransaction, s as GraphWriter, H as HopDefinition, t as HopResult, N as NodeTypeData, u as QueryMode, v as QueryOptions, S as ScanProtection, w as StoredGraphRecord, x as TraversalOptions, y as TraversalResult, V as ViewContext, z as ViewDefaultsConfig, A as ViewResolverConfig, W as WhereClause, I as defineConfig, J as generateTypes, K as resolveView } from './index-CQkofEC_.js';
+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';
 
@@ -26,6 +26,17 @@ declare function createGraphClient(db: Firestore, collectionPath: string, option
  * ```
  */
 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;
 
 /** The aType used for node type definition meta-nodes. */
 declare const META_NODE_TYPE = "nodeType";
@@ -57,8 +68,9 @@ declare function generateDeterministicUid(metaType: string, name: string): strin
  * 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 createRegistryFromGraph(reader: GraphReader): Promise<GraphRegistry>;
+declare function createRegistryFromGraph(reader: GraphReader, executor?: MigrationExecutor): Promise<GraphRegistry>;
 
 declare function generateId(): string;
 
@@ -116,6 +128,9 @@ declare class QuerySafetyError extends FiregraphError {
 declare class RegistryScopeError extends FiregraphError {
     constructor(aType: string, axbType: string, bType: string, scopePath: string, allowedIn: string[]);
 }
+declare class MigrationError extends FiregraphError {
+    constructor(message: string);
+}
 
 /**
  * Entity Discovery — convention-based auto-discovery of entities from
@@ -277,6 +292,162 @@ declare function compileSchema(schema: object, label?: string): (data: unknown)
  */
 declare function jsonSchemaToFieldMeta(schema: any): FieldMeta[];
 
+/**
+ * Sandbox module for compiling dynamic registry migration source strings
+ * into executable functions.
+ *
+ * Uses a dedicated worker thread with SES (Secure ECMAScript) Compartments
+ * for isolation. SES `lockdown()` and `Compartment` evaluation run in the
+ * worker thread so that the host process's intrinsics remain unaffected.
+ *
+ * Each migration function runs in a hardened compartment with no ambient
+ * authority — no access to `process`, `require`, `fetch`, `setTimeout`,
+ * or any other host-provided globals. Data crosses the compartment boundary
+ * as JSON strings to prevent prototype chain escapes.
+ *
+ * Static registry migrations are already in-memory functions and never
+ * go through this module.
+ */
+
+/**
+ * Default executor using a worker-thread SES Compartment with JSON marshaling.
+ *
+ * Migration source is compiled and executed inside an isolated SES
+ * Compartment running in a dedicated worker thread. The worker calls
+ * `lockdown()` in its own V8 isolate, leaving the host process's
+ * intrinsics completely unaffected.
+ *
+ * Data crosses the compartment boundary as JSON strings, preventing
+ * prototype chain escapes. The compartment receives only `JSON` as an
+ * endowment for parsing/stringifying data.
+ *
+ * The returned `MigrationFn` always returns a `Promise` (communication
+ * with the worker is inherently async via `postMessage`).
+ */
+declare function defaultExecutor(source: string): MigrationFn;
+/**
+ * Eagerly validate a migration source string by compiling it in the
+ * sandbox worker (or via a custom executor) without executing it.
+ *
+ * Use this to catch syntax errors at define-time or reload-time rather
+ * than at first migration execution.
+ *
+ * @throws {MigrationError} If the source is syntactically invalid or
+ *   does not produce a function.
+ */
+declare function precompileSource(source: string, executor?: MigrationExecutor): Promise<void>;
+/**
+ * Compile a stored migration source string into an executable function.
+ * Results are cached by SHA-256 hash of the source string so repeated
+ * reads never re-parse the same migration.
+ *
+ * **Important:** When using the default executor, this function does NOT
+ * validate the source synchronously — validation is deferred to the
+ * worker thread at execution time. Callers that need eager validation
+ * (e.g., `defineNodeType`, `reloadRegistry`) should call
+ * `precompileSource()` before or alongside `compileMigrationFn()`.
+ */
+declare function compileMigrationFn(source: string, executor?: MigrationExecutor): MigrationFn;
+/**
+ * Batch compile stored migration steps into executable MigrationStep[].
+ *
+ * With the default executor, source validation is deferred to execution
+ * time. Use `precompileSource()` to validate eagerly — see
+ * `createRegistryFromGraph()` for the recommended pattern.
+ */
+declare function compileMigrations(stored: StoredMigrationStep[], executor?: MigrationExecutor): MigrationStep[];
+/**
+ * Terminate the sandbox worker thread. The worker will be respawned
+ * on the next `defaultExecutor` call.
+ *
+ * Primarily useful for test cleanup to avoid vitest hanging on
+ * unfinished worker threads.
+ */
+declare function destroySandboxWorker(): Promise<void>;
+
+/**
+ * Firestore-aware serialization for the sandbox migration pipeline.
+ *
+ * Firestore documents can contain special types (Timestamp, GeoPoint,
+ * VectorValue, DocumentReference) that don't survive plain JSON
+ * round-tripping. This module provides tagged serialization: Firestore
+ * types are wrapped in tagged plain objects before JSON marshaling and
+ * reconstructed after.
+ *
+ * Only used by the `defaultExecutor` sandbox path. Static migrations
+ * (in-memory functions) receive raw Firestore objects directly.
+ */
+
+/** Sentinel key used to tag serialized Firestore types. */
+declare const SERIALIZATION_TAG: "__firegraph_ser__";
+/** Check if a value is a tagged serialized Firestore type. */
+declare function isTaggedValue(value: unknown): boolean;
+/**
+ * Recursively walk a data object and replace Firestore types with tagged
+ * plain objects suitable for JSON serialization.
+ *
+ * Returns a new object tree — the input is never mutated.
+ */
+declare function serializeFirestoreTypes(data: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Recursively walk a data object and reconstruct Firestore types from
+ * tagged plain objects.
+ *
+ * @param data - The data to deserialize (typically from JSON.parse)
+ * @param db - Optional Firestore instance for DocumentReference reconstruction.
+ *   If not provided, tagged DocumentReferences are left as-is with a one-time warning.
+ *
+ * Returns a new object tree — the input is never mutated.
+ */
+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';
@@ -336,4 +507,4 @@ declare function analyzeQuerySafety(filters: QueryFilter[]): QuerySafetyResult;
  */
 declare const DEFAULT_QUERY_LIMIT = 500;
 
-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, NODE_TYPE_SCHEMA, NodeNotFoundError, QueryFilter, QueryPlan, QuerySafetyError, type QuerySafetyResult, RegistryEntry, RegistryScopeError, RegistryViolationError, TraversalBuilder, TraversalError, ValidationError, analyzeQuerySafety, buildEdgeQueryPlan, buildEdgeRecord, buildNodeQueryPlan, buildNodeRecord, compileSchema, computeEdgeDocId, computeNodeDocId, createBootstrapRegistry, createGraphClient, createRegistry, createRegistryFromGraph, createTraversal, discoverEntities, generateDeterministicUid, generateId, generateIndexConfig, isAncestorUid, jsonSchemaToFieldMeta, matchScope, matchScopeAny, resolveAncestorCollection };
+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 };