@voltro/database 0.33.0 → 0.35.0

package/dist/sql.d.ts

@@ -7,7 +7,7 @@ import { SqlError } from '@effect/sql';
 import { SqlError as SqlError_2 } from '@effect/sql/SqlError';
 import { Statement } from '@effect/sql';
 
-export declare const acquireMigrationLock: (sql: SqlClient.SqlClient) => Effect.Effect<void, SqlError_2>;
+export declare const acquireMigrationLock: (sql: SqlClient.SqlClient, scope?: MigrationLockScope) => Effect.Effect<void, SqlError_2>;
 
 declare interface AggregateColumn<TResult = number | Date | null> {
     readonly op: 'count' | 'sum' | 'avg' | 'min' | 'max' | 'count-distinct' | 'window-row-number' | 'window-rank' | 'window-dense-rank' | 'window-lag' | 'window-lead' | 'window-sum-over' | 'window-avg-over' | 'column';
@@ -58,6 +58,14 @@ declare type AnyTable = Table<string, Record<string, ColumnDefinition<unknown>>,
 
 declare type AnyView = View<string, Record<string, ColumnDefinition<unknown>>>;
 
+/**
+ * The dialect-correct value for an `appliedAt` column, given an ISO instant.
+ *
+ * MySQL-family: UTC wall clock, `YYYY-MM-DD HH:MM:SS.fff`.
+ * Everything else: the ISO string, offset included.
+ */
+export declare const appliedAtValue: (sql: SqlClient.SqlClient, iso: string) => Effect.Effect<string>;
+
 /**
  * One row of `_voltro_migrations` — what the applier writes after a
  * successful plan execution. Same shape exposed via inspect RPC for
@@ -106,7 +114,7 @@ export declare interface AppliedOp {
  * no-op (except sqlite's ATTACH, which the splitter runs standalone and
  * whose "already attached" error the caller can ignore).
  */
-export declare const applyNamespacedSchema: (tables: ReadonlyArray<AnyTable>, namespace: string, dialect?: DialectId) => Effect.Effect<void, never, SqlClient.SqlClient>;
+export declare const applyNamespacedSchema: (tables: ReadonlyArray<AnyTable>, namespace: string, dialect?: DialectId, options?: SchemaApplyOptions) => Effect.Effect<void, never, SqlClient.SqlClient>;
 
 /**
  * Execute a `MigrationPlan` against the connected database.
@@ -116,11 +124,15 @@ export declare const applyNamespacedSchema: (tables: ReadonlyArray<AnyTable>, na
  *   1. If the plan has ANY blocked operation, throw before touching
  *      the DB. Callers should run `voltro db plan` first + resolve.
  *   2. Acquire the advisory lock (per-dialect; postgres v1).
- *   3. For each op in plan order: emit the DDL, run any backfill,
- *      mark applied.
- *   4. Write a row to `_voltro_migration_plans` with the post-state
- *      fingerprint + operations JSON + duration + environment.
- *   5. Release the advisory lock.
+ *   3. Bootstrap the resume ledger and finish any run a crash left behind
+ *      (see `resolveInterruptedRun`).
+ *   4. Record every operation that will run OUTSIDE a transaction, then for
+ *      each op in plan order: mark it started, emit the DDL, run any backfill,
+ *      mark it applied.
+ *   5. Write a row to `_voltro_migration_plans` with the post-state
+ *      fingerprint + operations JSON + duration + environment, and clear the
+ *      ledger.
+ *   6. Release the advisory lock.
  *
  * The return value is the `AppliedMigration` row — the same shape
  * used by the inspect RPC + the cloud dashboard timeline.
@@ -141,6 +153,15 @@ export declare interface ApplyPlanCtx {
     readonly source: 'auto-diff' | 'file';
     /** Optional human note via `voltro db apply --note "..."`. */
     readonly notes?: string;
+    /**
+     * Schema scope for the migration advisory lock (see `migrations/lock.ts`).
+     * Absent → resolved from configuration (`DB_SCHEMA`), which is what every
+     * CLI path wants; explicit for programmatic callers whose schema does not
+     * come from the environment. Every taker of this lock must resolve the
+     * scope the same way, or two writers in one schema stop excluding each
+     * other — worse than the cluster-wide key this replaced.
+     */
+    readonly lockSchema?: string;
     /**
      * Re-plan against the LIVE schema — the convergence proof.
      *
@@ -168,23 +189,13 @@ export declare interface ApplyPlanCtx {
     readonly replan: (sql: SqlClient.SqlClient) => Effect.Effect<MigrationPlan, SqlError_2, SqlClient.SqlClient>;
 }
 
-/**
- * Effect that applies the emitted DDL to the provided SqlClient. Splits
- * on `;` only outside dollar-quoted blocks (the postgres NOTIFY trigger
- * function body uses `$$`), so the plpgsql block stays intact as a
- * single statement. SQLite has no `$$` quoting so the splitter is a
- * superset.
- *
- * Caller passes the dialect explicitly. Defaults to `'postgres'` for
- * call-sites that haven't migrated yet.
- */
 export declare const applySchema: (tables: ReadonlyArray<AnyTable>, dialect?: DialectId, 
 /** NOTIFY channel for the reactive triggers. Pass the SAME value the store
  *  was built with. They are two halves of one contract and used to be able to
  *  disagree silently: the store listened on its `cdcChannel` while the DDL
  *  always emitted on the default, so a custom channel received nothing and
  *  raised nothing. */
-cdcChannel?: string) => Effect.Effect<void, never, SqlClient.SqlClient>;
+cdcChannel?: string, options?: SchemaApplyOptions) => Effect.Effect<void, never, SqlClient.SqlClient>;
 
 /**
  * The OPT-IN refuse gate over the advisory. By default (`VOLTRO_ROLLING_DEPLOY`
@@ -247,6 +258,78 @@ export declare type BootMigrationOutcome = {
     readonly plan: MigrationPlan;
 };
 
+/** Which engine-level mechanism stands a branch up. `namespace` = the portable
+ *  schema/database snapshot (every dialect); `neon-cow` = Neon's instant
+ *  copy-on-write branch API (zero-copy, Neon only). */
+declare type BranchMechanism = 'namespace' | 'neon-cow';
+
+/**
+ * The CI exit code.
+ *
+ *   0 — rehearsed clean and converged.
+ *   2 — a REVIEW signal: the plan destroys data, or the planner refuses part of
+ *       it. The migration may well be correct; a human has to say so.
+ *   1 — the rehearsal could not answer: it failed, the branch was not faithful,
+ *       or the migration did not converge.
+ *
+ * `lossy` is deliberately NOT an error. A `drop-column` in a PR is a normal,
+ * intentional thing; making it exit 1 trains people to pass `--force`, and the
+ * next real failure goes with it.
+ */
+export declare const branchRehearsalExitCode: (report: BranchRehearsalReport) => number;
+
+export declare interface BranchRehearsalOps {
+    readonly branchId: string;
+    readonly mechanism: BranchMechanism;
+    readonly branchedTables: number;
+    readonly replayedForeignKeys: number;
+    /** Stand the branch up. Throwing here yields `outcome: 'failed'`. */
+    readonly provision: () => Promise<void>;
+    /**
+     * The FIDELITY check: plan the PARENT's live schema against the BRANCH. Empty
+     * ⇒ the branch is a faithful copy. Supplied as a function rather than a
+     * boolean so the caller does the introspection it already knows how to do.
+     */
+    readonly fidelityPlan: () => Promise<MigrationPlan>;
+    /** Plan the DECLARED schema against the branch — the migration under review. */
+    readonly plan: () => Promise<MigrationPlan>;
+    /** Execute a (lossy-unblocked) plan on the branch. */
+    readonly apply: (plan: MigrationPlan) => Promise<void>;
+    /** Re-plan after the apply. Empty ⇒ converged. */
+    readonly replan: () => Promise<MigrationPlan>;
+    /** Drop the branch. Skipped when `keep`. */
+    readonly teardown: () => Promise<void>;
+    readonly keep?: boolean;
+    readonly log?: (message: string) => void;
+}
+
+export declare interface BranchRehearsalReport {
+    readonly branchId: string;
+    readonly mechanism: BranchMechanism;
+    readonly outcome: RehearsalOutcome;
+    /** Tables the branch was stood up with. */
+    readonly branchedTables: number;
+    /** Foreign keys replayed into the branch (`LIKE` does not copy them). */
+    readonly replayedForeignKeys: number;
+    /** Every operation the plan proposed, classified. */
+    readonly operations: ReadonlyArray<RehearsedOperation>;
+    /** The subset that destroys data — what a PR comment leads with. */
+    readonly lossy: ReadonlyArray<RehearsedOperation>;
+    /** Operations still refused after the branch's lossy unblock. */
+    readonly blocked: ReadonlyArray<RehearsedOperation>;
+    /** Was the plan actually executed on the branch? */
+    readonly applied: boolean;
+    /** Did the re-plan come back empty? `false` whenever `applied` is false. */
+    readonly converged: boolean;
+    /** What the re-plan still proposes — empty iff `converged`. */
+    readonly residual: ReadonlyArray<RehearsedOperation>;
+    /** Non-empty ⇒ the branch diverged from the parent BEFORE the plan ran. */
+    readonly infidelity: ReadonlyArray<RehearsedOperation>;
+    /** Was the branch torn down (false ⇒ `--keep`, or teardown failed). */
+    readonly tornDown: boolean;
+    readonly error?: string;
+}
+
 /** Partition into ≤`n`-sized chunks (disjoint, complete). Exported for the
  *  batching regression test — the introspection's correctness reduces to this
  *  producing a complete, non-overlapping partition of the table list. */
@@ -1002,6 +1085,14 @@ declare interface EagerLoadSpec {
     readonly onJunction?: Predicate;
 }
 
+export declare const emitAddIndexMysql: (op: Extract<MigrationOperation, {
+    kind: "add-index";
+}>, declared: ReadonlyArray<TableLike>) => string;
+
+export declare const emitCreateTableMysql: (op: Extract<MigrationOperation, {
+    kind: "create-table";
+}>) => ReadonlyArray<string>;
+
 export declare const emitDropColumnDdl: (op: Extract<MigrationOperation, {
     kind: "drop-column";
 }>, q: typeof quote) => string;
@@ -1191,6 +1282,12 @@ export declare interface FileMigrationRunResult {
  */
 export declare const fingerprintSchema: (snapshot: SchemaSnapshot) => string;
 
+export declare const fnv1a64: (input: string) => bigint;
+
+/** Human/PR-comment rendering. Markdown-free on purpose — the CI job that posts
+ *  it to a PR wraps it, and a terminal reader gets the same text. */
+export declare const formatBranchRehearsal: (report: BranchRehearsalReport) => string;
+
 /** Human report, or `undefined` when the database and the schema agree. */
 export declare const formatReactiveTriggerDrift: (drift: ReactiveTriggerDrift) => string | undefined;
 
@@ -1362,6 +1459,20 @@ export declare const isFileMigration: (value: unknown) => value is FileMigration
 /** Type guard — narrows an unknown value to a {@link RawSqlFragment}. */
 export declare const isRawSqlFragment: (value: unknown) => value is RawSqlFragment;
 
+/**
+ * True when re-RUNNING this exact statement is a no-op if the previous attempt
+ * (or a sibling process) already applied it. This is what makes an IN-PLACE
+ * statement retry sound on the per-operation dialects: the auto-migrate
+ * emitter's DDL is `IF NOT EXISTS`-shaped almost everywhere, and mysql's one
+ * exception (plain `CREATE INDEX` — the dialect cannot spell the conditional)
+ * is tolerated by `isReRunnableDuplicateIndex` above, which is precisely the
+ * re-run contract this predicate leans on. Anything else (sqlite `ATTACH`,
+ * a bare `ADD CONSTRAINT`) is NOT a retry candidate: a half-applied non-
+ * idempotent statement retried blindly turns a transient error into a
+ * confusing permanent one.
+ */
+export declare const isReRunSafeDdl: (statement: string, dialect: DialectId) => boolean;
+
 /**
  * A json-path index entry, produced by {@link jsonIndex}. Unlike a plain
  * `{ expr }` (verbatim, dialect-specific) this carries the column + path
@@ -1409,6 +1520,40 @@ declare type MergeMixinFields<Mixins extends ReadonlyArray<AnyMixin>> = Mixins e
  */
 export declare const migration: (spec: FileMigration) => FileMigration;
 
+/**
+ * The postgres advisory-lock key for a schema. Default schema (undefined /
+ * `'public'`) → the EXACT legacy constant (rolling-deploy pin, see above).
+ * Otherwise FNV-1a 64 of `voltro_migration_lock:<schema>`, with the sign
+ * bit cleared so the value is a positive signed 64-bit int (`pg_advisory_
+ * lock(bigint)`). Collisions across schemas are possible and ACCEPTABLE —
+ * a collision reintroduces serialization between two schemas, not a race.
+ */
+export declare const migrationLockKeyForSchema: (schema: string | undefined) => bigint;
+
+/**
+ * The mysql/mssql lock NAME for a schema. Default → the EXACT pre-1.5 name
+ * (`voltro_migration_<key36>`). Otherwise the schema is suffixed; MySQL
+ * caps `GET_LOCK` names at 64 chars, so a name that would overflow falls
+ * back to a hashed suffix (`_h<fnv-1a-64 hex>`, 46 chars total) instead of
+ * a server error. Note mysql's `GET_LOCK` scope is the SERVER: on
+ * mysql/mariadb `DB_SCHEMA` is not a connection pin (the database comes
+ * from the URL), but setting it to the database name is how two apps on
+ * one server un-share this lock.
+ */
+export declare const migrationLockNameForSchema: (schema: string | undefined) => string;
+
+/**
+ * Which schema's migration lock to take. `schema` undefined → resolve from
+ * configuration (`DB_SCHEMA`, the same variable `connectionConfig.ts` pins
+ * the postgres `search_path` from); the empty string and `'public'`
+ * normalize to the default scope. The scope must come from CONFIGURATION —
+ * never from a per-call `current_schema()` probe, whose answer can drift
+ * per session while the configured value cannot.
+ */
+export declare interface MigrationLockScope {
+    readonly schema?: string | undefined;
+}
+
 /**
  * Discriminated union for the concrete DDL operations the planner
  * emits. Every variant carries the `table` (most ops act on one
@@ -1598,6 +1743,25 @@ declare interface MixinIndex {
     readonly kindOptions?: IndexKindOptions;
 }
 
+/**
+ * How long a prefix a MySQL/MariaDB index key may take on this column.
+ *
+ * `undefined` when the column cannot be found — an introspected-only column
+ * with no live declaration. The caller then emits an unprefixed key, which is
+ * right for every non-text type and only risks "key too long" for an undeclared
+ * text one.
+ *
+ * A second guard, deliberately, and not because the first one is doubted: the
+ * defect above was a renderer losing the column's parameters on the way to a
+ * type decision, and that is a mistake a future path can make again. This one
+ * cannot emit a prefix longer than the column, whatever concluded it needed
+ * one — `min(191, declaredLength)`, which is what the reporter proposed.
+ *
+ * `undefined` = no prefix clause at all (the column is not text-like, or is
+ * unbounded and takes the full 191).
+ */
+export declare const mysqlIndexPrefixFor: (col: ColumnSnapshot | undefined) => number | undefined;
+
 /**
  * Type-narrowing migration marker. Tells the planner that this column
  * previously had type `from` and is now being narrowed/converted to its
@@ -1618,6 +1782,18 @@ declare interface NarrowedFromSpec {
     readonly using?: string;
 }
 
+/**
+ * Postgres identifier for the trigger function backing a given channel.
+ *
+ * Derived from the channel, NOT a single global name, and that is the whole
+ * point: `CREATE OR REPLACE FUNCTION framework_notify_change()` is one row in
+ * `pg_proc` for the entire database, so two schemas applied with different
+ * channels overwrote each other and the last one won. Everything applied
+ * earlier then emitted on somebody else's channel — silently, because a NOTIFY
+ * nobody listens to is not an error.
+ */
+export declare const notifyFunctionName: (channel: string) => string;
+
 /** Negation of an arbitrary sub-predicate → `NOT (...)`. Wraps any
  *  leaf/and/or/subquery subtree (distinct from the per-column `neq` and
  *  the narrow `notInSubquery`/`notExists`). */
@@ -1824,8 +2000,26 @@ declare interface PredicateLeaf {
  * Imperative `applyNamespacedSchema` against a fresh SqlClient — the
  * entry point the CLI / runtime use to provision a tenant's namespace
  * (eager at migrate time, or lazily on first use).
+ *
+ * **This is where `lifecycle: 'onTenantCreate'` seeds fire**, after the DDL
+ * lands and before this resolves — so a caller that awaits provisioning gets
+ * a tenant whose tables AND reference data exist, or an error. It was the
+ * missing half: the lifecycle validated, registered, and never ran, so every
+ * tenant came up empty and nothing said so.
+ *
+ * The seeds run through `setTenantCreateSeedHook` — the hook itself IS
+ * installed at boot (`seedRunner.ts`); with no seeds declared this costs one
+ * null check. A seed failure REJECTS — see `fireTenantCreateSeeds` for why,
+ * and note that re-calling this function is safe (the DDL is `IF NOT EXISTS`
+ * and seed steps are idempotent by contract).
+ *
+ * Wired by BOTH boot paths through `makeTenantProvisioner` (@voltro/cli):
+ * under `tenantIsolation: 'namespace'` on a SQL dialect, every namespace store
+ * view provisions lazily on first use — memoised per namespace per process.
+ * Eager provisioning is the APP's move (call this from a seed/startup over its
+ * own tenant table); the framework has no tenant registry to enumerate.
  */
-export declare const provisionTenantNamespace: (tables: ReadonlyArray<AnyTable>, namespace: string, sqlLayer: Layer.Layer<SqlClient.SqlClient, ConfigError.ConfigError | SqlError.SqlError, never>, dialect?: DialectId) => Promise<void>;
+export declare const provisionTenantNamespace: (tables: ReadonlyArray<AnyTable>, namespace: string, sqlLayer: Layer.Layer<SqlClient.SqlClient, ConfigError.ConfigError | SqlError.SqlError, never>, dialect?: DialectId, options?: SchemaApplyOptions) => Promise<void>;
 
 /**
  * The runtime-facing materialized query — a plain bag of strings the store and
@@ -2110,11 +2304,22 @@ export declare interface RawSqlFragment {
     readonly strings: ReadonlyArray<string>;
     readonly values: ReadonlyArray<unknown>;
     /**
-     * Tables this raw read depends on, for reactive invalidation. Raw
-     * reads are otherwise untracked — the query planner can't infer which
-     * tables an arbitrary SQL string touches. Declare them here (or via
-     * `store.raw(fragment, { dependsOn })`) to opt the read into the
-     * reactive layer's change-driven recomputation.
+     * Tables this raw read depends on, for reactive invalidation. Raw reads are
+     * otherwise untracked — the query planner cannot infer which tables an
+     * arbitrary SQL string touches. Declare them here (or via
+     * `store.raw(fragment, { dependsOn })`).
+     *
+     * WHAT IT DRIVES, stated narrowly because the previous wording promised more
+     * than any code delivered. For a live query whose handler returns a COMPUTED
+     * VALUE — the shape whose handler is genuinely re-run on a change — these
+     * tables JOIN the query's declared `source:`, so a write to one recomputes the
+     * subscription. That is the only shape where re-running can refresh a raw
+     * result. A handler that returns a query DESCRIPTOR re-runs the DESCRIPTOR on
+     * a change, not the handler, so declaring tables cannot refresh the raw read
+     * there; the runtime warns about that case at subscribe time instead.
+     *
+     * Best-effort in both directions: the tables are recorded as declared and
+     * never validated against the SQL.
      */
     readonly dependsOn?: ReadonlyArray<string>;
 }
@@ -2128,8 +2333,31 @@ export declare interface ReactiveTriggerDrift {
     /** Tables that carry a trigger but are declared `.nonReactive()` — their
      *  writes still hit the NOTIFY channel and cost WAL for nothing. */
     readonly stale: ReadonlyArray<string>;
+    /**
+     * The notify FUNCTION exists but its body predates this build
+     * (`NOTIFY_BODY_MARKER` absent from `pg_proc.prosrc`).
+     *
+     * Every trigger can be present, every table correct, and the PAYLOADS still
+     * be wrong — which is a state no per-table check can see. It matters because
+     * of what the body changed: an oversized payload (a row over pg_notify's
+     * 8000-byte cap) that does not carry the primary key cannot be re-read, so
+     * the change reaches every tap as a non-event and is lost with nothing
+     * logged. False when the function is ABSENT — nothing calls a function that
+     * does not exist, and "no reactivity here" is the missing/stale report's
+     * business, not this one's.
+     */
+    readonly functionOutdated: boolean;
 }
 
+/**
+ * Trigger name for one table on one channel.
+ *
+ * The channel is part of the name so a table reachable from two channels keeps
+ * one trigger per channel, instead of the second install's `DROP TRIGGER IF
+ * EXISTS` silently removing the first.
+ */
+export declare const reactiveTriggerName: (tableName: string, channel: string) => string;
+
 /**
  * The statements that bring the DATABASE's change triggers back in line with
  * what the schema declares.
@@ -2160,15 +2388,117 @@ export declare const reactiveTriggerRepairSql: (input: {
     readonly missing: ReadonlyArray<string>;
     /** Table names the detector found triggered-but-declared-nonReactive. */
     readonly stale: ReadonlyArray<string>;
+    /**
+     * The installed notify FUNCTION is older than the one this build emits
+     * (`detectReactiveTriggerDrift().functionOutdated`) — every trigger can be
+     * present and the payloads still be wrong. Replaces the body; touches no
+     * table.
+     */
+    readonly functionOutdated?: boolean;
     readonly channel?: string;
 }) => ReadonlyArray<string>;
 
-export declare const releaseMigrationLock: (sql: SqlClient.SqlClient) => Effect.Effect<void, SqlError_2>;
+/**
+ * Record that a schema was applied even though there was nothing to DO.
+ *
+ * ── The deadlock this exists to remove ──────────────────────────────────────
+ *
+ * `applyPlan` is the only writer of `_voltro_migration_plans`, and every caller
+ * short-circuits before it when `operations.length === 0`. So a plan with an
+ * empty diff records nothing — and `checkProdSchema` compares the DECLARED
+ * fingerprint against the last recorded row.
+ *
+ * Those two rules are individually reasonable and together they deadlock. A
+ * consumer walked into it on an upgrade-only deploy and reproduced it in
+ * isolation on a restored database:
+ *
+ *   1. `voltro serve`            → refuses: declared=8aaa5c9b live=72c2305a
+ *   2. `db files` / `db plan` / `db apply --plan`  → "schema is up to date",
+ *                                  0 operations, exit 0, nothing recorded
+ *   3. `voltro serve`            → the identical refusal
+ *   4. introduce ANY real delta  → apply has work, records, and
+ *   5. `voltro serve`            → boots
+ *
+ * There is no path from 1 to 5 through the documented commands. The migrate job
+ * is the gate that is supposed to stop a bad release: it passes, and then every
+ * pod CrashLoopBackOffs, pointing at the command that just succeeded. The
+ * remaining exit is the error message's own suggestion — turn the check off —
+ * and a safety gate disabled to work around bookkeeping stays off.
+ *
+ * `db drift --accept` is not the escape hatch and the consumer checked: drift
+ * compares the LIVE side against the recorded `liveFingerprint`, and the live
+ * side had not moved. What moved is the DECLARED side, which drift never reads.
+ *
+ * ── Why this is a recording rule and not a fingerprint question ─────────────
+ *
+ * A framework upgrade is allowed to change what the declared fingerprint hashes.
+ * Their own note says so, and they are right. What is not allowed is for that
+ * change to be uncatchable: an apply that ran and found nothing to do IS a
+ * successful apply of that schema, and recording it is what makes that sentence
+ * true tomorrow.
+ *
+ * ── Idempotent on purpose ──────────────────────────────────────────────────
+ *
+ * It writes only when the fingerprint is not already the latest recorded one.
+ * `voltro dev` re-boots on every file save; a row per boot would put this table
+ * on the list of things that grow without bound, which is a list this release
+ * has spent enough time on.
+ */
+export declare const recordUpToDate: (sql: SqlClient.SqlClient, plan: MigrationPlan, ctx: {
+    readonly appliedBy: string;
+    readonly environment: "dev" | "staging" | "prod";
+    readonly source: string;
+}) => Effect.Effect<"recorded" | "already-current", never>;
+
+export declare type RehearsalOutcome = 
+/** The plan applied on the branch and the re-plan was empty. Nothing lossy. */
+'clean'
+/** Applied + converged, but the plan destroys data. A review signal, not a failure. */
+| 'lossy'
+/** The plan carries operations the planner refuses to auto-apply even on a
+*  throwaway branch (`needs-rename-annotation`, `multi-step`). */
+| 'blocked'
+/** Applied, and the re-plan STILL proposes work — the migration does not converge. */
+| 'diverged'
+/** The branch is not a faithful copy of the parent, so nothing below it can be trusted. */
+| 'infidelity'
+/** Provisioning or the apply threw. */
+| 'failed';
+
+/** One operation the rehearsal wants a human to look at, flattened for a PR comment. */
+export declare interface RehearsedOperation {
+    readonly kind: string;
+    readonly table: string | undefined;
+    readonly classification: PlannedOperation['classification'];
+    readonly reason: string | undefined;
+    /** The `fix` the planner would have printed had this run against production. */
+    readonly blockedFix: string | undefined;
+}
+
+export declare const rehearsedOperation: (planned: PlannedOperation) => RehearsedOperation;
+
+/**
+ * Run the rehearsal. Never throws for a database-side failure — a rehearsal that
+ * blows up is itself a result the caller has to report, and swallowing the
+ * teardown behind an exception is how branches leak.
+ */
+export declare const rehearseMigrationOnBranch: (ops: BranchRehearsalOps) => Promise<BranchRehearsalReport>;
+
+export declare const releaseMigrationLock: (sql: SqlClient.SqlClient, scope?: MigrationLockScope) => Effect.Effect<void, SqlError_2>;
 
 export declare const renderColumnMysql: (col: ColumnSnapshot) => string;
 
 export declare const renderColumnPg: (col: ColumnSnapshot) => string;
 
+/**
+ * The effective lock schema: an explicit scope wins; otherwise `DB_SCHEMA`
+ * (the one env var the CLI's connection resolver reads for the schema pin).
+ * `undefined` = the default schema → the legacy constant key/name.
+ */
+export declare const resolveMigrationLockSchema: (scope?: MigrationLockScope) => string | undefined;
+
+declare type RetryDecision = 'retry' | 'noRetry';
+
 /**
  * Roll back a single file-based migration by id. Looks up the
  * migration's `down` body via file discovery (the file must still be
@@ -2182,6 +2512,7 @@ export declare const renderColumnPg: (col: ColumnSnapshot) => string;
 export declare const rollbackFileBasedMigration: (sql: SqlClient.SqlClient, ctx: {
     projectRoot: string;
     id: string;
+    lockSchema?: string;
 }) => Effect.Effect<{
     id: string;
     durationMs: number;
@@ -2269,6 +2600,9 @@ export declare interface RunFileBasedMigrationsCtx {
     readonly projectRoot: string;
     readonly env: 'dev' | 'staging' | 'prod';
     readonly appliedBy: string;
+    /** Schema scope for the migration advisory lock (see `migrations/lock.ts`).
+     *  Absent → resolved from configuration (`DB_SCHEMA`). */
+    readonly lockSchema?: string;
 }
 
 /**
@@ -2279,7 +2613,7 @@ export declare interface RunFileBasedMigrationsCtx {
  * `voltro_isr_cache` so framework releases that grow new columns
  * don't crash old DBs at boot.
  */
-export declare const runFrameworkBootstrap: (tables: ReadonlyArray<AnyTable>, sqlLayer: Layer.Layer<SqlClient.SqlClient, ConfigError.ConfigError | SqlError.SqlError, never>, dialect?: DialectId) => Promise<void>;
+export declare const runFrameworkBootstrap: (tables: ReadonlyArray<AnyTable>, sqlLayer: Layer.Layer<SqlClient.SqlClient, ConfigError.ConfigError | SqlError.SqlError, never>, dialect?: DialectId, options?: SchemaApplyOptions) => Promise<void>;
 
 /**
  * Run `applySchema` against a fresh SqlClient from the provided sqlLayer.
@@ -2289,7 +2623,7 @@ export declare const runFrameworkBootstrap: (tables: ReadonlyArray<AnyTable>, sq
  * `dialect` is passed through to the DDL emitter so SQL types + reactive
  * trigger emission match the underlying engine.
  */
-export declare const runMigrate: (tables: ReadonlyArray<AnyTable>, sqlLayer: Layer.Layer<SqlClient.SqlClient, ConfigError.ConfigError | SqlError.SqlError, never>, dialect?: DialectId) => Promise<void>;
+export declare const runMigrate: (tables: ReadonlyArray<AnyTable>, sqlLayer: Layer.Layer<SqlClient.SqlClient, ConfigError.ConfigError | SqlError.SqlError, never>, dialect?: DialectId, options?: SchemaApplyOptions) => Promise<void>;
 
 /**
  * Top-level entry point — called once per boot. Returns a
@@ -2308,6 +2642,36 @@ export declare interface RunPlannedMigrationsCtx {
     readonly dialectId: string;
 }
 
+/**
+ * Effect that applies the emitted DDL to the provided SqlClient. Splits
+ * on `;` only outside dollar-quoted blocks (the postgres NOTIFY trigger
+ * function body uses `$$`), so the plpgsql block stays intact as a
+ * single statement. SQLite has no `$$` quoting so the splitter is a
+ * superset.
+ *
+ * Caller passes the dialect explicitly. Defaults to `'postgres'` for
+ * call-sites that haven't migrated yet.
+ */
+/**
+ * Cross-cutting options for the auto-migrate apply entry points.
+ *
+ * `retryFilter` is the DIALECT's own transient-failure predicate
+ * (`SqlDialect.retryFilter`), threaded in by the caller because this package
+ * deliberately has NO dialect registry — the CLI loads the dialect module and
+ * hands its predicate through (optimizations 1.6). Absent → no retry, the
+ * pre-1.6 behavior. Present → a transient DDL failure (SQLITE_BUSY meeting
+ * the schema lock, a deadlock victim) is retried BOUNDED instead of dying on
+ * the first attempt while every equivalent DML statement would be retried.
+ *
+ * `lockSchema` scopes the migration advisory lock (see `migrations/lock.ts`);
+ * absent → `DB_SCHEMA` from the environment, the same configuration the
+ * connection's `search_path` pin reads.
+ */
+export declare interface SchemaApplyOptions {
+    readonly retryFilter?: (error: unknown) => RetryDecision;
+    readonly lockSchema?: string;
+}
+
 /**
  * The full schema as the planner sees it on one side of the diff.
  * Both the declared side and the introspected side conform to this
@@ -3094,6 +3458,11 @@ declare interface View<Name extends string, Fields extends Record<string, Column
  * `pg_advisory_lock(bigint)` wants a number; we hard-code a constant
  * inside the safe-integer range so every consumer races for the same
  * lock without doing string hashing at runtime.
+ *
+ * This is the key for the DEFAULT schema, and it must stay EXACTLY this
+ * value: a rolling deploy of a default-schema app has old and new
+ * replicas migrating side by side, and they can only serialize if both
+ * generations compute the SAME key.
  */
 export declare const VOLTRO_MIGRATION_LOCK_KEY = 6322741009312437n;
 
@@ -3129,7 +3498,7 @@ declare interface WindowSpec {
  * leaves the postgres lock held until that connection closes (which
  * the pooled SqlClient does on Effect scope cleanup).
  */
-export declare const withMigrationLock: <A, E, R = never>(sql: SqlClient.SqlClient, work: Effect.Effect<A, E, R>) => Effect.Effect<A, E | SqlError_2, R>;
+export declare const withMigrationLock: <A, E, R = never>(sql: SqlClient.SqlClient, work: Effect.Effect<A, E, R>, scope?: MigrationLockScope) => Effect.Effect<A, E | SqlError_2, R>;
 
 /** Tree of relations to eager-load. */
 declare type WithSpec = Readonly<Record<string, true | EagerLoadSpec>>;