@typicalday/firegraph 0.4.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, c as GraphRegistry, R as RegistryEntry, d as DiscoveryResult, e as GraphReader, f as GraphRecord, F as FindEdgesParams, Q as QueryPlan, g as FindNodesParams, T as TraversalBuilder, h as QueryFilter } from './index-DR3jF5_b.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-DR3jF5_b.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';
 
@@ -68,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;
 
@@ -127,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
@@ -288,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';
@@ -347,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, createMergedRegistry, 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, c as GraphRegistry, R as RegistryEntry, d as DiscoveryResult, e as GraphReader, f as GraphRecord, F as FindEdgesParams, Q as QueryPlan, g as FindNodesParams, T as TraversalBuilder, h as QueryFilter } from './index-DR3jF5_b.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-DR3jF5_b.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';
 
@@ -68,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;
 
@@ -127,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
@@ -288,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';
@@ -347,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, createMergedRegistry, 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 };