@abloatai/ablo 0.8.0 → 0.9.1

package/dist/react/AbloProvider.js

@@ -1,11 +1,10 @@
 'use client';
 import { jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
 import { useContext, useEffect, useMemo, useRef, useState, } from 'react';
-import { Ablo } from '../client/Ablo.js';
 import { createParticipantClaimId, parseParticipantTtlSeconds, resolveParticipantSyncGroups, } from '../sync/participants.js';
 import { SyncContext } from './context.js';
 import { AbloInternalContext } from './internalContext.js';
-import { AbloValidationError, AbloAuthenticationError } from '../errors.js';
+import { AbloValidationError } from '../errors.js';
 import { useSyncStatus } from './useSyncStatus.js';
 import { DefaultFallback } from './DefaultFallback.js';
 // ── Implementation ───────────────────────────────────────────────────
@@ -32,95 +31,52 @@ function createErrorEmitter() {
     };
 }
 export function AbloProvider(props) {
-    const { schema, url = 'wss://mesh.ablo.finance', userId, teamIds, apiKey, authToken, getToken, authEndpoint, preventUnsavedChanges, onSessionExpired, onError, observability, logger, mutationExecutor, mutationDispatcher, sessionErrorDetector, onlineStatus, configOverrides, syncGroups, scope, bootstrapBaseUrl, maxPoolSize, persistence, bootstrapMode, fallback = _jsx(DefaultFallback, {}), children, } = props;
-    // Account scope is no longer accepted from props. The engine learns
-    // it from auth (capability token) at bootstrap and we read it back
-    // out of `_store.orgId` once `engine.ready()` resolves.
+    const { client, userId, preventUnsavedChanges, onSessionExpired, onError, fallback = _jsx(DefaultFallback, {}), children, } = props;
+    // The client IS the engine — synchronous, never null. This provider is a
+    // REACTIVE binding over it (context + bootstrap gate + error/session
+    // forwarding); it does NOT construct, configure, or own the connection. The
+    // client owns auth, the credential lifecycle (first mint, refresh, and
+    // wake/online/focus re-mint — see `Ablo({ getToken })`), transport, and
+    // `dispose()`. The CONSUMER built the client, so the consumer owns teardown;
+    // the provider never disposes it.
+    const engine = client;
+    const schema = engine.schema;
+    // Account scope isn't a prop — read it from `_store.orgId` once `ready()`
+    // resolves the identity from the client's auth.
     const [resolvedAccountScope, setResolvedAccountScope] = useState(null);
     // ── Error emitter (provider-instance scoped) ─────────────────────
-    //
-    // Built once, reused for the lifetime of this provider. Survives
-    // engine rotations so error listeners don't need to resubscribe.
     const errorEmitterRef = useRef(null);
     if (!errorEmitterRef.current) {
         errorEmitterRef.current = createErrorEmitter();
     }
     const errorEmitter = errorEmitterRef.current;
-    // Stash `onError` in a ref so forwarding it doesn't trigger
-    // engine rotation. The provider wraps it and calls via ref at fire
-    // time, matching the `useEventCallback` idiom.
+    // Stash callbacks in refs so a new identity each render doesn't re-run the
+    // start effect (the `useEventCallback` idiom).
     const onErrorRef = useRef(onError);
     onErrorRef.current = onError;
     useEffect(() => {
         return errorEmitter.subscribe((err) => onErrorRef.current?.(err));
     }, [errorEmitter]);
-    // Stash the token resolver in a ref so a new function identity each render
-    // does not re-key (tear down) the engine. Read at fire time in the connect +
-    // refresh paths below — same `useEventCallback` idiom as `onError`. `getToken`
-    // wins; otherwise `authEndpoint` is fetched for `{ token }`.
-    const tokenFromEndpoint = authEndpoint
-        ? async () => {
-            const res = await fetch(authEndpoint, {
-                method: 'POST',
-                credentials: 'include',
-                headers: { 'Content-Type': 'application/json' },
-            });
-            if (!res.ok)
-                return null;
-            const body = (await res.json());
-            return body.token ?? null;
-        }
-        : undefined;
-    const getTokenRef = useRef(getToken ?? tokenFromEndpoint);
-    getTokenRef.current = getToken ?? tokenFromEndpoint;
-    // ── Engine lifecycle keyed on (userId, url) ─────────────────────
+    const onSessionExpiredRef = useRef(onSessionExpired);
+    onSessionExpiredRef.current = onSessionExpired;
+    // Re-key the bootstrap gate when the client INSTANCE changes — a genuinely new
+    // engine is a fresh "first bootstrap". Stable for the common single-client app.
+    const clientGenRef = useRef({ client, gen: 0 });
+    if (clientGenRef.current.client !== client) {
+        clientGenRef.current = { client, gen: clientGenRef.current.gen + 1 };
+    }
+    const engineKey = String(clientGenRef.current.gen);
+    // ── Start + session-error wiring ─────────────────────────────────
     //
-    // The engine rotates when either of these change. For everything
-    // else (mutators, DI, callbacks) we stash in refs so mutations to
-    // those props don't tear down the engine.
-    const engineKey = JSON.stringify({
-        userId: userId ?? null,
-        url,
-        bootstrapMode: bootstrapMode ?? null,
-    });
-    const [engineState, setEngineState] = useState({ key: engineKey, engine: null });
-    // Keep a ref to the current engine key so the rotation effect can
-    // detect late-arriving prop changes without causing React churn.
-    const currentKeyRef = useRef(engineState.key);
-    currentKeyRef.current = engineState.key;
+    // Two reactive jobs only:
+    //   1. Forward a SERVER session-rejection → purge (wipe IndexedDB so the next
+    //      login starts clean) → onSessionExpired (the app redirects). The
+    //      offline/transient-vs-terminal credential logic lives in the CLIENT now.
+    //   2. Drive `ready()` (idempotent) so bootstrap starts on mount, then read the
+    //      resolved org scope for SyncContext.
+    // It does NOT dispose the client (consumer-owned) and does NOT touch auth.
     useEffect(() => {
-        const abort = new AbortController();
-        let isStale = false;
-        setResolvedAccountScope(null);
-        // Construct engine + multiplayer streams for this key.
-        const engineOptions = {
-            baseURL: url,
-            schema,
-            ...(userId ? { user: { id: userId, teamIds } } : {}),
-            apiKey,
-            ...(authToken ? { authToken } : {}),
-            logger,
-            observability,
-            sessionErrorDetector,
-            onlineStatus,
-            mutationExecutor,
-            mutationDispatcher,
-            configOverrides,
-            // Union raw strings with model-form `scope` resolved through the schema,
-            // so `scope={{ decks: id }}` becomes `deck:<id>` via the model's `scope`.
-            syncGroups: scope
-                ? [...(syncGroups ?? []), ...resolveParticipantSyncGroups(scope, schema)]
-                : syncGroups,
-            bootstrapBaseUrl,
-            maxPoolSize,
-            persistence,
-            ...(bootstrapMode ? { bootstrapMode } : {}),
-            autoStart: false,
-        };
-        const engine = Ablo(engineOptions);
-        setEngineState({ key: engineKey, engine });
-        // Forward session-error events to the consumer. Purge first so
-        // the IndexedDB is wiped before the app redirects to /signin.
+        let stale = false;
         const unsubscribeSession = engine.onSessionError(async (err) => {
             errorEmitter.emit(err);
             try {
@@ -128,130 +84,37 @@ export function AbloProvider(props) {
             }
             catch { }
             try {
-                await onSessionExpired?.();
+                await onSessionExpiredRef.current?.();
             }
             catch (hookErr) {
                 errorEmitter.emit(hookErr);
             }
         });
-        // Drive initial bootstrap. Consumer code that wants to run logic
-        // after the engine is ready calls `useAblo()` and wires its own
-        // `useEffect` — the SDK no longer holds a registry of "post-
-        // bootstrap hooks" because the indirection costs more than it
-        // saves once `useAblo` exists.
-        (async () => {
-            try {
-                // Resolve a fresh bearer token BEFORE `ready()` (which connects —
-                // the engine is built with `autoStart: false`), so the first WS
-                // upgrade + bootstrap carry it. No race: nothing has connected yet.
-                const fetchToken = getTokenRef.current;
-                if (fetchToken) {
-                    const token = await fetchToken();
-                    if (isStale || abort.signal.aborted)
-                        return;
-                    if (token) {
-                        engine.setAuthToken(token);
-                    }
-                    else {
-                        // A configured `getToken` that resolves to falsy means "no active
-                        // session" — the session-token resolver (e.g. `getSyncCapabilityToken`)
-                        // returns null when logged out, the session hasn't hydrated, or the
-                        // mint endpoint rejects. Its contract is "the provider then surfaces
-                        // the usual unauthenticated path rather than connecting with a bad token."
-                        //
-                        // We MUST short-circuit here rather than fall through to
-                        // `engine.ready()`. On apps/web's identity path (org + user.id are
-                        // both supplied) `resolveParticipantIdentity` takes the
-                        // trust-the-caller Branch 3, which does NOT validate the (absent)
-                        // token — so init would proceed into `store.initialize()` and open
-                        // IndexedDB *before* any auth-bearing bootstrap/WS call. If storage
-                        // is at all wedged the no-session condition then surfaces only as an
-                        // opaque `IndexedDB "ablo_databases" open did not resolve within
-                        // 10000ms` stall, never the real auth error. Surface `session_expired`
-                        // explicitly and let the app redirect to sign-in.
-                        //
-                        // Unlike the server-detected `onSessionError` handler above, we do
-                        // NOT purge: nothing connected or wrote this mount, so any cached
-                        // IndexedDB belongs to a prior session and is reconciled by the next
-                        // valid bootstrap — purging here would drop a still-valid offline
-                        // queue on a merely transient null token.
-                        const authErr = new AbloAuthenticationError('No session token available — getToken() resolved to null. The ' +
-                            'session is missing or expired; sign in again.', { code: 'session_expired' });
-                        errorEmitter.emit(authErr);
-                        try {
-                            await onSessionExpired?.();
-                        }
-                        catch (hookErr) {
-                            errorEmitter.emit(hookErr);
-                        }
-                        return;
-                    }
-                }
-                await engine.ready();
-                if (isStale || abort.signal.aborted)
-                    return;
-                setResolvedAccountScope(engine._store.orgId ?? null);
-            }
-            catch (err) {
-                if (isStale || abort.signal.aborted)
-                    return;
-                errorEmitter.emit(err);
-            }
-        })();
+        engine
+            .ready()
+            .then(() => {
+            if (stale)
+                return;
+            setResolvedAccountScope(engine._store.orgId ?? null);
+        })
+            .catch((err) => {
+            if (stale)
+                return;
+            errorEmitter.emit(err);
+        });
         return () => {
-            isStale = true;
-            abort.abort();
+            stale = true;
             unsubscribeSession();
-            void engine.dispose();
-            // AbloClient is stateless-ish — participants manage their own
-            // WebSocket connections via `participant.disconnect()`. No client
-            // close is needed.
         };
-        // We intentionally only re-run on engineKey. All other DI is
-        // captured at first render; rotating the engine on every
-        // `mutationExecutor` identity change would destroy the WebSocket.
-        // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [engineKey]);
-    // ── Bearer-token refresh ─────────────────────────────────────────
-    //
-    // Short-lived tokens (the sync-server JWT defaults to 15m) must be rolled
-    // before they expire or the next reconnect/HTTP call fails auth. Re-resolve
-    // ahead of expiry and push via `engine.setAuthToken`, which swaps the token
-    // on the live WebSocket + bootstrap header without tearing down the engine.
-    // Only runs when a `getToken` resolver is wired (cookie deployments skip it).
-    useEffect(() => {
-        const engine = engineState.engine;
-        if (!engine || !getTokenRef.current)
-            return;
-        // Comfortably inside the 15m JWT lifetime; a missed tick is recovered by
-        // the next one well before expiry.
-        const REFRESH_INTERVAL_MS = 10 * 60 * 1000;
-        const id = setInterval(() => {
-            void (async () => {
-                try {
-                    const token = await getTokenRef.current?.();
-                    if (token)
-                        engine.setAuthToken(token);
-                }
-                catch {
-                    // Transient (offline / session check). The next tick retries; the
-                    // engine keeps using the still-valid current token until then.
-                }
-            })();
-        }, REFRESH_INTERVAL_MS);
-        return () => clearInterval(id);
-    }, [engineState.engine]);
+    }, [engine, errorEmitter]);
     // ── beforeunload + preventUnsavedChanges ─────────────────────────
     useEffect(() => {
         if (typeof window === 'undefined')
             return;
         const handler = (event) => {
-            const engine = engineState.engine;
-            if (!engine)
-                return;
-            // Best-effort: dispose on unload. The async work may not
-            // complete before the tab closes — that's fine for IDB, which
-            // flushes pending writes transactionally.
+            // Best-effort IDB flush on TAB CLOSE — the client is going away with the
+            // page regardless. This is NOT an unmount teardown: the consumer owns the
+            // client's lifecycle and the provider never disposes it on unmount.
             void engine.dispose();
             if (preventUnsavedChanges && engine._store.hasUnsyncedChanges) {
                 event.preventDefault();
@@ -260,30 +123,30 @@ export function AbloProvider(props) {
         };
         window.addEventListener('beforeunload', handler);
         return () => window.removeEventListener('beforeunload', handler);
-    }, [engineState.engine, preventUnsavedChanges]);
+    }, [engine, preventUnsavedChanges]);
     // ── SyncContext value (for useQuery/useOne/useMutate hooks) ──────
+    //
+    // The engine is always present (it's the `client` prop), but its org scope is
+    // unknown until `ready()` resolves identity — so `syncValue` is null until
+    // then, which drives the initial fallback below.
     const syncValue = useMemo(() => {
-        if (!engineState.engine)
-            return null;
         const currentAccountScope = resolvedAccountScope ??
-            engineState.engine._store.orgId;
+            engine._store.orgId;
         if (!currentAccountScope)
             return null;
         return {
-            store: engineState.engine._store,
+            store: engine._store,
             organizationId: currentAccountScope,
             schema,
         };
-    }, [engineState.engine, resolvedAccountScope, schema]);
+    }, [engine, resolvedAccountScope, schema]);
     // ── Internal context (currentUserId + error subscription) ────────
     const internalValue = useMemo(() => ({
         currentUserId: userId ?? null,
         subscribeError: errorEmitter.subscribe,
         emitError: errorEmitter.emit,
-        // `engine` is null until bootstrap finishes; `useSync()` throws
-        // on null so callers are forced to gate with <ClientSideSuspense>.
-        engine: engineState.engine,
-    }), [userId, errorEmitter, engineState.engine]);
+        engine: engine,
+    }), [userId, errorEmitter, engine]);
     // ── Render ───────────────────────────────────────────────────────
     //
     // Two-phase gate (see `BootstrapGate` below for the latch logic):
@@ -307,7 +170,7 @@ export function AbloProvider(props) {
     if (!syncValue) {
         return (_jsx(AbloInternalContext.Provider, { value: internalValue, children: initialFallback }));
     }
-    return (_jsx(AbloInternalContext.Provider, { value: internalValue, children: _jsx(SyncContext.Provider, { value: syncValue, children: passthrough ? (children) : (_jsx(BootstrapGate, { fallback: fallback, children: children }, engineState.key)) }) }));
+    return (_jsx(AbloInternalContext.Provider, { value: internalValue, children: _jsx(SyncContext.Provider, { value: syncValue, children: passthrough ? (children) : (_jsx(BootstrapGate, { fallback: fallback, children: children }, engineKey)) }) }));
 }
 /**
  * Internal gate that renders `fallback` only during the very first

package/dist/react/context.d.ts

@@ -5,11 +5,42 @@ import type { QueryView, QueryViewOptions } from '../core/QueryView.js';
 import type { ViewRegistry } from '../core/ViewRegistry.js';
 import type { Schema } from '../schema/schema.js';
 import type { SyncStatus } from '../BaseSyncedStore.js';
+/**
+ * A single LOCAL mutation as observed off the commit stream — the substrate
+ * the undo system records from. One is emitted per local create/update/
+ * delete/archive (remote/collaborator deltas never appear here: they apply
+ * through a separate pool path that doesn't queue mutations). `previousData`
+ * holds the pre-edit field values (captured from the model's
+ * `modifiedProperties` first-old-wins baseline), so an inverse op is fully
+ * derivable from the event alone — no separate snapshot pass.
+ *
+ * This mirrors how Yjs's `UndoManager` derives reverse-ops by observing the
+ * doc and Liveblocks' `room.history` records room ops: undo listens to the
+ * one place all local writes converge, rather than wrapping the write call.
+ */
+export interface LocalMutation {
+    type: 'create' | 'update' | 'delete' | 'archive' | 'unarchive';
+    /** Registered model name (e.g. `'SlideLayer'`); resolved to a schema key by the recorder. */
+    modelName: string;
+    modelId: string;
+    /** New field values (create/update). */
+    data?: Record<string, unknown> | null;
+    /** Pre-edit field values (update → inverse patch; delete → full re-create row). */
+    previousData?: Record<string, unknown> | null;
+}
 /**
  * Minimal store interface that the SDK hooks need.
  * Consumers provide their concrete store (e.g., SyncedStore) that implements this.
  */
 export interface SyncStoreContract {
+    /**
+     * Subscribe to the LOCAL mutation stream (optimistic, pre-ack) for undo
+     * recording. Optional so minimal test doubles can omit it — when absent,
+     * undo scopes simply record nothing. The concrete store
+     * (`BaseSyncedStore`) wires this to the TransactionQueue's
+     * `transaction:created` event. Returns an unsubscribe function.
+     */
+    subscribeLocalMutations?(handler: (mutation: LocalMutation) => void): () => void;
     retrieve(modelClass: abstract new (...args: never[]) => Model, id: string): Model | undefined;
     queryByClass(modelClass: abstract new (...args: never[]) => Model, options?: {
         predicate?: (model: Model) => boolean;

package/dist/react/useAblo.d.ts

@@ -45,11 +45,11 @@ export type UseAbloHydratedModelResult<T> = Omit<UseAbloModelResult<T>, 'data'>
  * // With Register augmentation (recommended):
  * const ablo = useAblo();
  * if (!ablo) return <Loading />;
- * const doc = await ablo.documents.retrieve(id); // async server read
+ * const doc = await ablo.documents.retrieve({ id }); // async server read
  *
  * // Reactive selector (sync local-graph snapshot):
  * const doc = useAblo((ablo) => ablo.documents.get(id)) ?? serverDoc;
- * const active = useAblo((ablo) => ablo.documents.claim.state(id));
+ * const active = useAblo((ablo) => ablo.documents.claim.state({ id }));
  *
  * // Without augmentation, pass the schema generic:
  * const ablo = useAblo<(typeof schema)['models']>();

package/dist/react/useCurrentUserId.d.ts

@@ -13,7 +13,7 @@
  *   const userId = useCurrentUserId();
  *   const ablo = useAblo();
  *   if (!userId) return null;
- *   return <button onClick={() => ablo?.tasks.update(id, { assigneeId: userId })}>
+ *   return <button onClick={() => ablo?.tasks.update({ id, data: { assigneeId: userId } })}>
  *     Assign to me
  *   </button>;
  * }

package/dist/react/useCurrentUserId.js

@@ -17,7 +17,7 @@ import { AbloValidationError } from '../errors.js';
  *   const userId = useCurrentUserId();
  *   const ablo = useAblo();
  *   if (!userId) return null;
- *   return <button onClick={() => ablo?.tasks.update(id, { assigneeId: userId })}>
+ *   return <button onClick={() => ablo?.tasks.update({ id, data: { assigneeId: userId } })}>
  *     Assign to me
  *   </button>;
  * }

package/dist/react/useMutators.js

@@ -34,19 +34,26 @@ export function useMutators(schemaOrMutators, mutatorsOrOptions, maybeOptions) {
                 invokers[mutatorName] = async (args) => {
                     // Recording path: wrap the transaction so each write snapshots its
                     // inverse. On success, push the captured entry to the scope.
+                    //
+                    // The whole snapshot → write → record sequence runs on the scope's
+                    // serialization chain so concurrent invocations (the slides UI fires
+                    // writes un-awaited) record in *invocation* order and never
+                    // interleave their shared-model snapshots. See UndoScope.runRecorded.
                     if (undoScope) {
-                        const recording = createRecordingTransaction(schema, store, organizationId);
-                        try {
-                            const result = await fn({ tx: recording.tx, args });
-                            const entry = recording.getEntry(label);
-                            if (entry)
-                                undoScope.record(entry);
-                            return result;
-                        }
-                        catch (err) {
-                            getContext().logger.error(`[useMutators] mutator "${label}" threw`, { error: err });
-                            throw err;
-                        }
+                        return undoScope.runRecorded(async () => {
+                            const recording = createRecordingTransaction(schema, store, organizationId);
+                            try {
+                                const result = await fn({ tx: recording.tx, args });
+                                const entry = recording.getEntry(label);
+                                if (entry)
+                                    undoScope.record(entry);
+                                return result;
+                            }
+                            catch (err) {
+                                getContext().logger.error(`[useMutators] mutator "${label}" threw`, { error: err });
+                                throw err;
+                            }
+                        });
                     }
                     // Non-recording path — plain transaction, identical to pre-undo V1.
                     const tx = createTransaction(schema, store, organizationId);

package/dist/schema/ddl.d.ts

@@ -22,18 +22,46 @@ import type { MigrationStep, BackfillValue } from './diff.js';
 export interface ProvisionPlan {
     /** The Postgres schema the tables live in (`app_<id>` or `public`). */
     readonly appSchema: string;
-    /** Ordered, idempotent DDL statements. Safe to run repeatedly. */
+    /** Ordered, idempotent DDL statements. Safe to run repeatedly. Executors run
+     *  these together in ONE transaction. */
     readonly statements: readonly string[];
+    /** Post-commit, NON-transactional DDL (`VALIDATE CONSTRAINT`, `CREATE INDEX
+     *  CONCURRENTLY`) — run AFTER {@link statements} commit, each outside any
+     *  transaction, best-effort. Keeps the lock-heavy / scan-heavy work off the
+     *  main transaction so adding a foreign key never freezes a large, live BYO
+     *  table. Optional + back-compat: absent = nothing to run. */
+    readonly concurrent?: readonly string[];
+}
+export interface ProvisionOptions {
+    /**
+     * Emit `DEFERRABLE INITIALLY DEFERRED` FOREIGN KEY constraints for every
+     * `parent: true` belongsTo relation (true ownership edges only — see
+     * {@link foreignKeyStatements}). Off by default: the soft-reference model keeps
+     * out-of-order sync robust on Ablo-managed tables. Turn on for a customer's own
+     * (BYO / dedicated) database, where a clean, navigable relational schema is
+     * wanted and the DB starts empty (nothing for the constraint to fail against).
+     */
+    readonly foreignKeys?: boolean;
 }
 export interface MigrationPlan {
     /** The app Postgres schema the DDL targets (`app_<id>` or `public`). */
     readonly appSchema: string;
-    /** Ordered DDL statements (expand → contract). */
+    /** Ordered DDL statements (expand → contract). Run in ONE transaction. */
     readonly statements: readonly string[];
+    /** Post-commit, non-transactional DDL — see {@link ProvisionPlan.concurrent}. */
+    readonly concurrent?: readonly string[];
 }
 /** Per-app schema name for an app (organization) id. */
 export declare function appSchemaName(organizationId: string): string;
 export declare function camelToSnake(identifier: string): string;
+/**
+ * Pure snake_case → camelCase — the inverse of {@link camelToSnake}, matching
+ * `postgres.toCamel` semantics. Read-side translation: a column read back from a
+ * BYO database (e.g. via `drizzleDataSource`) maps to the same JS field the SDK
+ * wrote, so `camelToSnake('operatorId') === 'operator_id'` and
+ * `snakeToCamel('operator_id') === 'operatorId'` round-trip.
+ */
+export declare function snakeToCamel(identifier: string): string;
 /** Quote an identifier (defense-in-depth; inputs are already slug/snake). */
 export declare function q(identifier: string): string;
 export declare function sqlType(fieldType: ModelJSON['fields'][string]['type']): string;
@@ -46,7 +74,7 @@ export declare function sqlType(fieldType: ModelJSON['fields'][string]['type']):
  * itself is the isolation boundary). For `public` the `CREATE SCHEMA` is
  * skipped (it always exists).
  */
-export declare function generateProvisionPlan(schema: SchemaJSON, targetSchema: string): ProvisionPlan;
+export declare function generateProvisionPlan(schema: SchemaJSON, targetSchema: string, opts?: ProvisionOptions): ProvisionPlan;
 /**
  * Lower an ordered migration step list to DDL. `next` is the schema being pushed
  * (the target column shapes are read from it), `prev` the active one (used to
@@ -59,4 +87,7 @@ export declare function generateMigrationPlan(steps: readonly MigrationStep[], o
     /** Constant seed values that let a required-field add / made-required step
      *  set NOT NULL on a non-empty table. Keyed by (model, field). */
     readonly backfills?: readonly BackfillValue[];
+    /** Emit DEFERRABLE FK constraints for `parent: true` edges of newly-created
+     *  models. Off by default — see {@link ProvisionOptions.foreignKeys}. */
+    readonly foreignKeys?: boolean;
 }): MigrationPlan;