@voltro/database 0.81.0 → 0.82.0

package/dist/sql.d.ts

@@ -3,11 +3,15 @@ import { Effect } from 'effect';
 import { Layer } from 'effect';
 import { Schema } from 'effect';
 import { SqlClient } from '@effect/sql';
-import { SqlError } from '@effect/sql';
-import { SqlError as SqlError_2 } from '@effect/sql/SqlError';
+import { SqlError } from '@effect/sql/SqlError';
+import { SqlError as SqlError_2 } from '@effect/sql';
 import { Statement } from '@effect/sql';
 
-export declare const acquireMigrationLock: (sql: SqlClient.SqlClient, scope?: MigrationLockScope) => Effect.Effect<HeldMigrationLock, SqlError_2>;
+/** Every hash this source may have been recorded under: its own, and the body
+ *  before each framework edit in {@link FRAMEWORK_MIGRATION_EDITS}. */
+export declare const acceptedBodyHashes: (source: string) => ReadonlySet<string>;
+
+export declare const acquireMigrationLock: (sql: SqlClient.SqlClient, scope?: MigrationLockScope) => Effect.Effect<HeldMigrationLock, SqlError>;
 
 export declare const addColumnDdl: (op: Extract<MigrationOperation, {
     kind: "add-column";
@@ -161,7 +165,36 @@ declare type AnyView = View<string, Record<string, ColumnDefinition<unknown>>>;
  */
 export declare const appliedAtValue: (sql: SqlClient.SqlClient, iso: string) => Effect.Effect<string>;
 
-export declare const appliedFileMigrationIds: (sql: SqlClient.SqlClient) => Effect.Effect<ReadonlyArray<string>, SqlError_2>;
+/**
+ * Does the plan ledger exist on THIS database? Asked of the CATALOG, which
+ * ANSWERS on a virgin database rather than failing.
+ *
+ * The read below used to be a plain `SELECT` with `Effect.catchAll(() => [])`
+ * beside it, and that is correct only OUTSIDE a transaction — the rule
+ * `objectReadable` states in `applier.ts`, in those words, about its own query.
+ * `voltro db apply` opens ONE transaction on the plan-transactional dialects,
+ * so against a database without the ledger the failed SELECT aborted that
+ * transaction and every later statement of the deploy died — starting with the
+ * first migration's own `SAVEPOINT`:
+ *
+ *     ERROR: relation "_voltro_migration_plans" does not exist
+ *     ERROR: current transaction is aborted, commands ignored until end of
+ *            transaction block
+ *
+ * The catch turned an error postgres does not forget into one only Effect had
+ * forgotten. So a project with even ONE file under `migrations/` could not
+ * `db apply` against an empty database at all — every new environment, every
+ * reset local database, every hermetic e2e stack — and the schema was never
+ * created.
+ *
+ * The fix is NOT to create the ledger first. Both apply paths used to open with
+ * `applySchema(voltroFrameworkTables)`, and it was removed for a reason the
+ * header of `runApplyFromPlanFile` records: on a virgin database it created
+ * tables and thereby moved the very fingerprint the saved plan was measured
+ * against. The ledger is planned like any other declared table; what had to
+ * change is that ASKING for it stops being a statement that can fail.
+ */
+export declare const appliedFileMigrationIds: (sql: SqlClient.SqlClient) => Effect.Effect<ReadonlyArray<string>, SqlError>;
 
 /**
  * The applied file migrations WITH the body hash recorded at the time.
@@ -175,7 +208,7 @@ export declare const appliedFileMigrationIds: (sql: SqlClient.SqlClient) => Effe
 export declare const appliedFileMigrations: (sql: SqlClient.SqlClient) => Effect.Effect<ReadonlyArray<{
     readonly id: string;
     readonly hash: string;
-}>, SqlError_2>;
+}>, SqlError>;
 
 /**
  * The operations the resume ledger says RAN — `started`, `added` or `applied` —
@@ -245,9 +278,14 @@ export declare const applyNamespacedSchema: (tables: ReadonlyArray<AnyTable>, na
  * interruption, which is exactly the set a JS `finally` inside `Effect.gen`
  * does not cover.
  */
-export declare const applyPlan: (sql: SqlClient.SqlClient, plan: MigrationPlan, ctx: ApplyPlanCtx) => Effect.Effect<AppliedMigration, SqlError_2, SqlClient.SqlClient>;
+export declare const applyPlan: (sql: SqlClient.SqlClient, plan: MigrationPlan, ctx: ApplyPlanCtx) => Effect.Effect<AppliedMigration, SqlError, SqlClient.SqlClient>;
 
 export declare interface ApplyPlanCtx {
+    /** Prepare schema-owned resources under the migration lock after replan,
+     * refusal checks and interrupted-run reconciliation, before planned work.
+     * Not called when no operations remain. Ledger/extension bootstrap may
+     * already have run; this is not a dry-run boundary or its own transaction. */
+    readonly beforeExecute?: Effect.Effect<void, SqlError, SqlClient.SqlClient>;
     /** Tables declared by user code — needed to look up
      *  `.backfill()` specs for add-column ops, since the snapshot
      *  doesn't carry them. */
@@ -319,7 +357,7 @@ export declare interface ApplyPlanCtx {
      * migration was a framework bug. `voltro db apply` did exactly that for two
      * releases while `voltro dev`'s boot diff, which uses this parameter, did not.
      */
-    readonly replan: (sql: SqlClient.SqlClient) => Effect.Effect<MigrationPlan, SqlError_2, SqlClient.SqlClient>;
+    readonly replan: (sql: SqlClient.SqlClient) => Effect.Effect<MigrationPlan, SqlError, SqlClient.SqlClient>;
     /**
      * The declared store charset — the one `replan` plans with. Here only for
      * the resume ledger this creates before the first statement: nothing declares
@@ -342,7 +380,7 @@ cdcChannel?: string, options?: SchemaApplyOptions) => Effect.Effect<void, never,
  * `.unprepared`, the text protocol, like every DDL statement a prepared
  * protocol may refuse on one of the two engines.
  */
-export declare const applyUndeclaredCharsetWork: (sql: SqlClient.SqlClient, work: UndeclaredCharsetWork) => Effect.Effect<void, SqlError_2>;
+export declare const applyUndeclaredCharsetWork: (sql: SqlClient.SqlClient, work: UndeclaredCharsetWork) => Effect.Effect<void, SqlError>;
 
 /**
  * The OPT-IN refuse gate over the advisory. By default (`VOLTRO_ROLLING_DEPLOY`
@@ -544,6 +582,9 @@ declare type ChangeEvent = {
      *     re-read failed, or the row was already gone). Re-read or resync.
      */
     readonly oversized?: 'rehydrated' | 'tombstone' | 'unrecovered';
+    /** A net-change feed may coalesce intermediate writes and supply current
+     * images or delete keys only. It cannot support exact historical replay. */
+    readonly netChange?: true;
     /**
      * How the event reached this process. Absent/'inline' = emitted by this
      * process's own write path; 'injected' = delivered over a cross-instance
@@ -634,9 +675,13 @@ export declare const charsetColumnsOf: (table: TableSnapshot) => ReadonlyArray<{
  * Without `mayWrite` nothing is created or written: a missing table or row is
  * `unclaimed`, and only an existing FOREIGN claim is reported.
  */
-export declare const checkSchemaOwner: (sql: SqlClient.SqlClient, claim: SchemaOwnerClaim, options: {
+export declare const checkSchemaOwner: (sql: SqlClient.SqlClient, claim: SchemaOwnerClaim, 
+/** `charset`: the declared store charset (MySQL family) the owner table is
+ *  created in — the same one every other framework table gets. */
+options: {
     readonly mayWrite: boolean;
-}) => Effect.Effect<SchemaOwnership, SqlError_2>;
+    readonly charset: MysqlCharset | undefined;
+}) => Effect.Effect<SchemaOwnership, SqlError>;
 
 /** Partition into ≤`n`-sized chunks (disjoint, complete). Exported for the
  *  batching regression test — the introspection's correctness reduces to this
@@ -1553,7 +1598,7 @@ export declare type ColumnInput = {
  * `drop-check` still removes a CHECK the declaration no longer has: it runs
  * after the column changes and reads the catalog again.
  */
-export declare const columnLevelChecksMysql: (sql: SqlClient.SqlClient, table: string) => Effect.Effect<ReadonlyMap<string, string>, SqlError_2>;
+export declare const columnLevelChecksMysql: (sql: SqlClient.SqlClient, table: string) => Effect.Effect<ReadonlyMap<string, string>, SqlError>;
 
 /**
  * A column as seen by the planner: either declared in code (extracted
@@ -1824,7 +1869,7 @@ export declare const convergeUndeclaredCharset: (sql: SqlClient.SqlClient, optio
     readonly declaredNames: ReadonlySet<string>;
     readonly charset: MysqlCharset | undefined;
     readonly lockSchema?: string | undefined;
-}) => Effect.Effect<UndeclaredCharsetWork, SqlError_2>;
+}) => Effect.Effect<UndeclaredCharsetWork, SqlError>;
 
 /** A live foreign key a charset conversion has to carry across the rewrite. */
 export declare interface ConvertCharsetForeignKey {
@@ -2431,8 +2476,8 @@ export declare const defaultJsonClause: (value: object, dialect: DialectId) => s
 export declare interface DeferredData {
     readonly table: string;
     readonly op: MigrationOperation;
-    readonly data: Effect.Effect<void, SqlError_2>;
-    readonly after: Effect.Effect<void, SqlError_2>;
+    readonly data: Effect.Effect<void, SqlError>;
+    readonly after: Effect.Effect<void, SqlError>;
 }
 
 export declare const DEPLOY_LEDGER_TABLE = "_voltro_deploys";
@@ -2491,11 +2536,33 @@ export declare const detectReactiveTriggerDrift: (sql: SqlClient.SqlClient, tabl
 /** The app's `cdcChannel`. Part of the trigger NAME on any non-default
  *  channel, so omitting it here reported every table as missing on a database
  *  where every trigger was present. */
-channel?: string) => Effect.Effect<ReactiveTriggerDrift, SqlError_2>;
+channel?: string) => Effect.Effect<ReactiveTriggerDrift, SqlError>;
 
 /** Dialect IDs the framework supports. */
 declare type DialectId = 'postgres' | 'mysql' | 'mariadb' | 'mssql' | 'sqlite' | 'turso';
 
+/**
+ * Resolve the live dialect from the `SqlClient`.
+ *
+ * `sql.onDialectOrElse` collapses the six voltro dialects onto four driver
+ * tokens: mysql+mariadb share `mysql` (one `@effect/sql-mysql2` client) and
+ * sqlite+turso share `sqlite`. That collapse is fine for every consumer here —
+ * the paired dialects behave identically for everything this module decides.
+ *
+ * Single copy on purpose: a second, subtly different dialect switch is how a
+ * per-dialect divergence gets shipped in this codebase.
+ */
+export declare const dialectOf: (sql: {
+    readonly onDialectOrElse: <A, B, C, D, E, F>(options: {
+        readonly orElse: () => A;
+        readonly sqlite?: () => B;
+        readonly pg?: () => C;
+        readonly mysql?: () => D;
+        readonly mssql?: () => E;
+        readonly clickhouse?: () => F;
+    }) => A | B | C | D | E | F;
+}) => DialectId;
+
 /**
  * Output of `voltro db drift`: compares the live DB's introspected
  * schema against the last applied fingerprint in `_voltro_migrations`.
@@ -2811,7 +2878,19 @@ declare type EmptyMerge = unknown;
 export declare const engineFromVersion: (version: string) => MysqlEngine;
 
 /** The deploy ledger (`_voltro_deploys`) — same bootstrap, same reason: it has to exist before the first plan. */
-export declare const ensureDeployLedgerTable: (sql: SqlClient.SqlClient, dialect: DialectId, charset?: MysqlCharset) => Effect.Effect<void, SqlError_2>;
+export declare const ensureDeployLedgerTable: (sql: SqlClient.SqlClient, dialect: DialectId, charset: MysqlCharset | undefined) => Effect.Effect<void, SqlError>;
+
+/**
+ * Make every declared full-text index exist, on a database the PLANNER
+ * migrates. The planner diffs what it introspects — columns, indexes — and
+ * deliberately skips the FTS artifacts (a generated tsvector column and its GIN
+ * index, a FULLTEXT index, an FTS5 shadow table): they are framework plumbing
+ * for a declaration, carry no data of their own, and their DDL is idempotent.
+ * So they CONVERGE after the plan instead of being planned — without this, a
+ * table the planner created never got its index, and `.matching()` failed on
+ * the missing column. Returns how many statements ran.
+ */
+export declare const ensureFullTextIndexes: (tables: ReadonlyArray<AnyTable>, dialect: DialectId) => Effect.Effect<number, SqlError_2.SqlError, SqlClient.SqlClient>;
 
 /**
  * Create `_voltro_migration_ops` if it isn't there yet.
@@ -2826,7 +2905,7 @@ export declare const ensureDeployLedgerTable: (sql: SqlClient.SqlClient, dialect
  * framework-table set because it has to exist before the FIRST plan — and the
  * first plan is the one that creates the framework tables.
  */
-export declare const ensureLedgerTable: (sql: SqlClient.SqlClient, dialect: DialectId, charset?: MysqlCharset) => Effect.Effect<void, SqlError_2>;
+export declare const ensureLedgerTable: (sql: SqlClient.SqlClient, dialect: DialectId, charset: MysqlCharset | undefined) => Effect.Effect<void, SqlError>;
 
 /**
  * The PLAN ledger (`_voltro_migration_plans`) — same bootstrap, one caller.
@@ -2841,7 +2920,11 @@ export declare const ensureLedgerTable: (sql: SqlClient.SqlClient, dialect: Dial
  * Index-free like the others, so the planner still owns the table's shape and a
  * re-plan converges by adding the indexes it declares.
  */
-export declare const ensurePlanLedgerTable: (sql: SqlClient.SqlClient, dialect: DialectId) => Effect.Effect<void, SqlError_2>;
+export declare const ensurePlanLedgerTable: (sql: SqlClient.SqlClient, dialect: DialectId, charset: MysqlCharset | undefined) => Effect.Effect<void, SqlError>;
+
+/** The plugin-migration ledger (`_voltro_plugin_migrations`) — same bootstrap:
+ *  a plugin's steps run after the schema apply, outside any plan. */
+export declare const ensurePluginMigrationsLedgerTable: (sql: SqlClient.SqlClient, dialect: DialectId, charset: MysqlCharset | undefined) => Effect.Effect<void, SqlError>;
 
 /**
  * The in-progress marker (`_voltro_replace_in_progress`) — same bootstrap,
@@ -2857,11 +2940,11 @@ export declare const ensurePlanLedgerTable: (sql: SqlClient.SqlClient, dialect:
  * exits 1 over a database that is otherwise fine. The planner emits no trigger
  * for this table either, so the shape converges on the next apply.
  */
-export declare const ensureReplaceMarkerTable: (sql: SqlClient.SqlClient, dialect: DialectId) => Effect.Effect<void, SqlError_2>;
+export declare const ensureReplaceMarkerTable: (sql: SqlClient.SqlClient, dialect: DialectId, charset: MysqlCharset | undefined) => Effect.Effect<void, SqlError>;
 
 /** The schema-owner row's table (`_voltro_schema_owner`) — bootstrapped so the
  *  ownership check can run BEFORE the first plan, which is the plan it guards. */
-export declare const ensureSchemaOwnerTable: (sql: SqlClient.SqlClient, dialect: DialectId) => Effect.Effect<void, SqlError_2>;
+export declare const ensureSchemaOwnerTable: (sql: SqlClient.SqlClient, dialect: DialectId, charset: MysqlCharset | undefined) => Effect.Effect<void, SqlError>;
 
 /** Exported for the same reason as {@link enumTypeBlocks}, and it MUST run
  *  before it — see that function's note on ordering. */
@@ -2918,6 +3001,21 @@ export declare const failedExpectations: (expectations: ReadonlyArray<{
     readonly check: () => Promise<boolean> | Effect.Effect<boolean, unknown, never>;
 }>) => Effect.Effect<ReadonlyArray<string>, unknown>;
 
+/**
+ * Look up the most recently applied plan's fingerprint. Returns
+ * `undefined` if the table doesn't exist yet or no rows are present —
+ * both meaning "the framework hasn't applied a planner-style migration
+ * in this DB yet" (typical for fresh installs).
+ *
+ * A failed read is NOT one of those two unless the table is really absent.
+ * This read used to end in `catchAll(() => undefined)`, and on SQL Server its
+ * `LIMIT 1` was a syntax error: every production boot there reported
+ * `live=<no _voltro_migration_plans row>` over a table holding the row, and
+ * refused. So a failure is followed by a probe that is valid on every dialect;
+ * if the table answers it, the original failure is the answer, loudly.
+ */
+export declare const fetchLastFingerprint: (sql: SqlClient.SqlClient) => Effect.Effect<string | undefined, never>;
+
 /**
  * Filename pattern the discovery walker matches: timestamp-prefixed
  * `.ts` files in any depth under the project's `migrations/` dir.
@@ -3223,6 +3321,49 @@ export declare const formatBranchRehearsal: (report: BranchRehearsalReport) => s
 /** Human report, or `undefined` when the database and the schema agree. */
 export declare const formatReactiveTriggerDrift: (drift: ReactiveTriggerDrift) => string | undefined;
 
+/**
+ * Edits the FRAMEWORK made to migration files — through a codemod, after they
+ * may already have run — each with the inverse that recovers the body as it was
+ * when it ran.
+ *
+ * `0.78.0/01_file-migration-phase` inserted `phase: 'before-schema',` into every
+ * migration without one, and 0.78.0 made the field required. Every migration
+ * applied before that then warned on every boot that its body had changed,
+ * forever: the file cannot be put back, and the recorded hash is the operator's
+ * to keep, not to hand-edit. A warning that is always there is the one nobody
+ * reads when a real edit lands, so an edit we made is not drift.
+ *
+ * A codemod that rewrites files under `migrations/` adds its inverse here in the
+ * same change — `fileMigrationCodemodInverses.test.ts` fails otherwise, and runs
+ * the real codemod over every file shape it has measured. An inverse returns
+ * the CANDIDATE originals, because the rewrite is not always one line: ts-morph
+ * replaces the whitespace around the property it inserts with its own (LF, two
+ * spaces), so a one-line spec, a CRLF file and a tab-indented one each lose
+ * bytes that only the file's own style can put back. It undoes exactly what the
+ * codemod wrote: a hand-written `after-schema` on an applied migration is still
+ * an edit, and still said.
+ */
+export declare const FRAMEWORK_MIGRATION_EDITS: ReadonlyArray<{
+    readonly codemod: string;
+    readonly inverse: (source: string) => ReadonlyArray<string>;
+}>;
+
+/**
+ * The DDL that makes a table's `.fullTextIndex(...)` declarations exist —
+ * THE one builder, used by the full-schema emit and by
+ * `ensureFullTextIndexes` (the planner path's convergence). Idempotent per
+ * dialect:
+ *   postgres:       STORED tsvector column + GIN index (`IF NOT EXISTS`)
+ *   mysql/mariadb:  native FULLTEXT INDEX (a re-run's duplicate is swallowed)
+ *   sqlite:         native FTS5 virtual table + sync triggers (`IF NOT EXISTS`)
+ *   mssql:          nothing — a ranked LIKE fallback at query time
+ * Turso has no FTS5 and throws.
+ */
+export declare const fullTextIndexSql: (table: AnyTable, dialect: DialectId) => ReadonlyArray<string>;
+
+/** A converged schema can still have an unfinished history write. Boot must not skip it. */
+export declare const hasInterruptedMigration: (sql: SqlClient.SqlClient) => Effect.Effect<boolean, SqlError>;
+
 /**
  * A lock that is being HELD, and the only way to let it go.
  *
@@ -3236,7 +3377,7 @@ export declare const formatReactiveTriggerDrift: (drift: ReactiveTriggerDrift) =
 export declare interface HeldMigrationLock {
     /** Release the lock and return its connection to the pool. Idempotent only
      *  in the sense that the dialect statements are; call it once. */
-    readonly release: Effect.Effect<void, SqlError_2>;
+    readonly release: Effect.Effect<void, SqlError>;
 }
 
 /**
@@ -3460,7 +3601,7 @@ declare interface InsertIgnoreResult {
     readonly outcome: 'inserted' | 'ignored';
 }
 
-export declare const introspectSchema: (sql: SqlClient.SqlClient) => Effect.Effect<SchemaSnapshot, SqlError_2>;
+export declare const introspectSchema: (sql: SqlClient.SqlClient) => Effect.Effect<SchemaSnapshot, SqlError>;
 
 /**
  * A `down` that says there is no inverse — with the reason, which is what a
@@ -3535,6 +3676,22 @@ declare type LeafOperator = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' |
 
 declare type LeafOperator_2 = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'notIn' | 'contains' | 'startsWith' | 'arrayContains' | 'arrayOverlaps' | 'arrayHas' | 'isNull' | 'isNotNull' | 'spatial';
 
+/**
+ * `LIMIT n`, spelled for the dialect — after an `ORDER BY`, which every caller
+ * has. SQL Server has no LIMIT; `OFFSET 0 ROWS FETCH NEXT n ROWS ONLY` is its
+ * spelling, valid in a derived table too.
+ *
+ * One helper because the same mistake was written six times: a batched
+ * backfill failed on its first page, and `voltro serve`'s schema check read the
+ * newest applied plan with `LIMIT 1`, got a syntax error back, and reported it
+ * as "no plan row" — so a production serve on SQL Server refused every boot,
+ * including the one right after `voltro db apply`.
+ *
+ * Splicing a number into SQL text needs a reason: this one is framework-chosen
+ * and floored to a positive integer here, so it cannot carry anything but digits.
+ */
+export declare const limitClause: (sql: SqlClient.SqlClient, n: number) => Statement.Fragment;
+
 /**
  * Build the context for one migration body. Returns the context and the
  * post-conditions it collects, so the runner can evaluate them after `up`.
@@ -4039,6 +4196,20 @@ export declare class MigrationSkipped {
     constructor(reason: string);
 }
 
+export declare interface MigrationSnapshotCandidate {
+    readonly planId: string;
+    readonly objects: ReadonlyArray<SnapshotRestorationObject>;
+}
+
+export declare interface MigrationSquashPreview {
+    readonly before: string;
+    readonly fingerprint: string;
+    readonly planIds: ReadonlyArray<string>;
+    readonly count: number;
+    /** Opaque selection identity, not an authorization credential. */
+    readonly token: string;
+}
+
 declare interface MixinDefinition<F extends Record<string, ColumnDefinition<unknown>>> {
     /**
      * Stable dedup key. Two mixins with the same `id` reaching a table via
@@ -4423,6 +4594,9 @@ export declare const plannedCreations: (plan: MigrationPlan) => ReadonlyArray<Sc
  */
 export declare interface PlannedOperation {
     readonly op: MigrationOperation;
+    /** Exact retained object name assigned by the applier before soft-drop DDL.
+     * Persisted in operation/resume history; absent when the history has no recorded identity or for hard drops. */
+    readonly softDropSnapshot?: string;
     readonly classification: OperationClass;
     /** Why the op was classified this way (also surfaces in the CLI). */
     readonly reason?: string;
@@ -4494,6 +4668,10 @@ declare interface PredicateLeaf_2 {
     readonly path?: ReadonlyArray<string | number>;
 }
 
+/** Read the complete eligible history, independent of the dashboard's recent
+ * history limit. The token must be rechecked by squashMigrationPlans on write. */
+export declare const previewMigrationSquash: (options: Pick<SquashOptions, "before" | "fingerprint">) => Effect.Effect<MigrationSquashPreview, Error, SqlClient.SqlClient>;
+
 /**
  * Imperative `applyNamespacedSchema` against a fresh SqlClient — the
  * entry point the CLI / runtime use to provision a tenant's namespace
@@ -4517,7 +4695,7 @@ declare interface PredicateLeaf_2 {
  * 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, options?: SchemaApplyOptions) => Promise<void>;
+export declare const provisionTenantNamespace: (tables: ReadonlyArray<AnyTable>, namespace: string, sqlLayer: Layer.Layer<SqlClient.SqlClient, ConfigError.ConfigError | SqlError_2.SqlError, never>, dialect?: DialectId, options?: SchemaApplyOptions) => Promise<void>;
 
 /**
  * The runtime-facing materialized query — a plain bag of strings the store and
@@ -4659,6 +4837,16 @@ declare interface QueryDescriptor<R = Row> {
             readonly alias: string;
             readonly order: boolean;
         };
+        /** Each query word matches as a word BEGINNING (`tomato` finds
+         *  `tomatoes`), every word required — `.matching(…, { prefix: true })`. */
+        readonly prefix?: boolean;
+        /**
+         * Set by a store whose engine keeps no full-text index (Turso's MVCC mode
+         * has no FTS5): the match compiles to a case-insensitive LIKE over the
+         * covered columns, ranked by how many of them hit — the same fallback as
+         * mssql. Never set by the query builder.
+         */
+        readonly fallback?: 'like';
     };
     /**
      * Common-Table-Expression definitions (Q4) — `WITH <name> AS (...)`.
@@ -4937,6 +5125,16 @@ declare interface QueryDescriptor_2<R = Row_2> {
             readonly alias: string;
             readonly order: boolean;
         };
+        /** Each query word matches as a word BEGINNING (`tomato` finds
+         *  `tomatoes`), every word required — `.matching(…, { prefix: true })`. */
+        readonly prefix?: boolean;
+        /**
+         * Set by a store whose engine keeps no full-text index (Turso's MVCC mode
+         * has no FTS5): the match compiles to a case-insensitive LIKE over the
+         * covered columns, ranked by how many of them hit — the same fallback as
+         * mssql. Never set by the query builder.
+         */
+        readonly fallback?: 'like';
     };
     /**
      * Common-Table-Expression definitions (Q4) — `WITH <name> AS (...)`.
@@ -5196,8 +5394,10 @@ export declare const reactiveTriggerRepairSql: (input: {
     readonly channel?: string;
 }) => ReadonlyArray<string>;
 
+export declare const readMigrationSnapshotCandidates: (sql: SqlClient.SqlClient, live: SchemaSnapshot) => Effect.Effect<ReadonlyArray<MigrationSnapshotCandidate>, SqlError>;
+
 /** Every string column of a base table in the connected database. */
-export declare const readUndeclaredCharsetColumns: (sql: SqlClient.SqlClient) => Effect.Effect<ReadonlyArray<UndeclaredCharsetColumn>, SqlError_2>;
+export declare const readUndeclaredCharsetColumns: (sql: SqlClient.SqlClient) => Effect.Effect<ReadonlyArray<UndeclaredCharsetColumn>, SqlError>;
 
 /**
  * Record that a schema was applied even though there was nothing to DO.
@@ -5298,7 +5498,12 @@ export declare const renderColumnPg: (col: ColumnSnapshot, hasCompositePk?: bool
  */
 export declare const resolveMigrationLockSchema: (scope?: MigrationLockScope) => string | undefined;
 
-export declare const resolveMysqlEngine: (sql: SqlClient.SqlClient) => Effect.Effect<MysqlEngine, SqlError_2>;
+export declare const resolveMysqlEngine: (sql: SqlClient.SqlClient) => Effect.Effect<MysqlEngine, SqlError>;
+
+/** Restore only recorded objects, under the same lock as schema migrations. */
+export declare const restoreMigrationSnapshots: (sql: SqlClient.SqlClient, planId: string, options?: {
+    readonly beforeExecute?: (sql: SqlClient.SqlClient) => Effect.Effect<void, SqlError, SqlClient.SqlClient>;
+}) => Effect.Effect<SnapshotRestorationResult, SqlError | Error, SqlClient.SqlClient>;
 
 declare type RetryDecision = 'retry' | 'noRetry';
 
@@ -5352,6 +5557,9 @@ export declare const rollbackFileBasedMigration: (sql: SqlClient.SqlClient, ctx:
     id: string;
     lockSchema?: string;
     store: DataStore;
+    /** Runs under the migration lock after all refusal checks, immediately
+     * before down. Failure leaves the body and ledger untouched. */
+    beforeExecute?: Effect.Effect<void, unknown>;
 }) => Effect.Effect<{
     id: string;
     durationMs: number;
@@ -5450,6 +5658,10 @@ declare interface RuleViolationDetail {
 export declare const runFileBasedMigrations: (sql: SqlClient.SqlClient, ctx: RunFileBasedMigrationsCtx) => Effect.Effect<FileMigrationRunResult, unknown>;
 
 export declare interface RunFileBasedMigrationsCtx {
+    /** Runs once under the migration lock, after pending work is rechecked and
+     * before its bodies start. Not called for an empty/already-applied pass.
+     * Failure aborts the pass. Preparation is outside each body's transaction. */
+    readonly beforeExecute?: Effect.Effect<void, unknown>;
     readonly projectRoot: string;
     readonly env: 'dev' | 'staging' | 'prod';
     readonly appliedBy: string;
@@ -5476,6 +5688,12 @@ export declare interface RunFileBasedMigrationsCtx {
      * called — which is the defect the phase exists to remove, moved up a layer.
      */
     readonly phase: MigrationPhase;
+    /**
+     * The declared store charset (MySQL family), for the ledgers this run
+     * creates before any plan has. Required, `undefined` spelled out — see
+     * `ensureBootstrapTable`.
+     */
+    readonly charset: MysqlCharset | undefined;
 }
 
 /**
@@ -5486,7 +5704,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, options?: SchemaApplyOptions) => Promise<void>;
+export declare const runFrameworkBootstrap: (tables: ReadonlyArray<AnyTable>, sqlLayer: Layer.Layer<SqlClient.SqlClient, ConfigError.ConfigError | SqlError_2.SqlError, never>, dialect?: DialectId, options?: SchemaApplyOptions) => Promise<void>;
 
 /**
  * Run `applySchema` against a fresh SqlClient from the provided sqlLayer.
@@ -5496,7 +5714,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, options?: SchemaApplyOptions) => Promise<void>;
+export declare const runMigrate: (tables: ReadonlyArray<AnyTable>, sqlLayer: Layer.Layer<SqlClient.SqlClient, ConfigError.ConfigError | SqlError_2.SqlError, never>, dialect?: DialectId, options?: SchemaApplyOptions) => Promise<void>;
 
 /**
  * Execute ONE planned operation with the applier's own per-dialect
@@ -5507,7 +5725,7 @@ export declare const runMigrate: (tables: ReadonlyArray<AnyTable>, sqlLayer: Lay
  * shape from: the live table with the change applied, materialised as a
  * declaration by the caller.
  */
-export declare const runMigrationOp: (sql: SqlClient.SqlClient, planned: PlannedOperation, declared: ReadonlyArray<TableLike>) => Effect.Effect<AppliedOp, SqlError_2>;
+export declare const runMigrationOp: (sql: SqlClient.SqlClient, planned: PlannedOperation, declared: ReadonlyArray<TableLike>) => Effect.Effect<AppliedOp, SqlError>;
 
 /**
  * Top-level entry point — called once per boot. Returns a
@@ -5516,9 +5734,11 @@ export declare const runMigrationOp: (sql: SqlClient.SqlClient, planned: Planned
  *
  * Wires the dev/prod dispatch + the VOLTRO_AUTO_MIGRATE escape hatch.
  */
-export declare const runPlannedMigrations: (sql: SqlClient.SqlClient, declared: ReadonlyArray<TableLike>, ctx: RunPlannedMigrationsCtx) => Effect.Effect<BootMigrationOutcome, SqlError_2, SqlClient.SqlClient>;
+export declare const runPlannedMigrations: (sql: SqlClient.SqlClient, declared: ReadonlyArray<TableLike>, ctx: RunPlannedMigrationsCtx) => Effect.Effect<BootMigrationOutcome, SqlError, SqlClient.SqlClient>;
 
 export declare interface RunPlannedMigrationsCtx {
+    /** Forwarded to the applier only when an approved schema plan executes. */
+    readonly beforeExecute?: Effect.Effect<void, SqlError, SqlClient.SqlClient>;
     /** What `voltro logs` should attribute this run to. */
     readonly appliedBy: string;
     readonly environment: BootEnvironment;
@@ -5543,10 +5763,10 @@ export declare interface RunPlannedMigrationsCtx {
  * answers `already-absent` before reaching here). This function assumes the
  * object is there.
  */
-export declare const runSchemaOp: (sql: SqlClient.SqlClient, op: MigrationSchemaOp, live: SchemaSnapshot) => Effect.Effect<void, SqlError_2>;
+export declare const runSchemaOp: (sql: SqlClient.SqlClient, op: MigrationSchemaOp, live: SchemaSnapshot) => Effect.Effect<void, SqlError>;
 
 /** Runs one Effect over the connection — the shape `ManagedRuntime.runPromise` and a store's `run` share. */
-export declare type RunSql = <A>(effect: Effect.Effect<A, SqlError_2, SqlClient.SqlClient>) => Promise<A>;
+export declare type RunSql = <A>(effect: Effect.Effect<A, SqlError, SqlClient.SqlClient>) => Promise<A>;
 
 export declare const SCHEMA_OWNER_TABLE = "_voltro_schema_owner";
 
@@ -5673,6 +5893,19 @@ export declare const snapshotColumn: (name: string, def: ColumnDefinition<unknow
 /** Needed only for `storageType` — a caller that renders DDL does not want it. */
 dialect?: DialectId) => ColumnSnapshot;
 
+export declare interface SnapshotRestorationObject {
+    readonly kind: 'column' | 'table';
+    readonly table: string;
+    readonly originalName: string;
+    readonly snapshotName: string;
+}
+
+export declare interface SnapshotRestorationResult {
+    readonly restoredColumns: number;
+    readonly restoredTables: number;
+    readonly objects: ReadonlyArray<SnapshotRestorationObject>;
+}
+
 /**
  * PostGIS spatial-distance clause carried on a {@link QueryDescriptor}.
  * Drives a `ST_Distance` projected column (distance-as-a-value) and/or a
@@ -5784,7 +6017,7 @@ export declare const sqlType: (column: ColumnDefinition<unknown>, dialect: Diale
  * Effect that performs the squash + returns a summary. Fails if:
  *   - no eligible rows match (`before` cut everything off)
  *   - the latest pre-squash fingerprint differs from `fingerprint`
- *     (signals uncommitted drift — refuse to lock in)
+ *     (the cut-off may select an older schema, or declarations may be unapplied)
  */
 export declare const squashMigrationPlans: (options: SquashOptions) => Effect.Effect<SquashResult, Error, SqlClient.SqlClient>;
 
@@ -5803,6 +6036,9 @@ export declare interface SquashOptions {
     readonly appliedBy: string;
     /** Environment tag for the snapshot row. */
     readonly environment: string;
+    /** Confirmation token from previewMigrationSquash. Rechecked under the lock
+     * before writing; changed eligibility refuses without changing history. */
+    readonly expectedPreview?: string;
 }
 
 export declare interface SquashResult {
@@ -6539,9 +6775,9 @@ export declare class TransactionBrokenByBodyError extends Error {
  * Hand the schema to a different app name — `voltro db claim`. The one
  * deliberate way to change the owner: an app was RENAMED, not replaced.
  */
-export declare const transferSchemaOwner: (sql: SqlClient.SqlClient, claim: SchemaOwnerClaim) => Effect.Effect<{
+export declare const transferSchemaOwner: (sql: SqlClient.SqlClient, claim: SchemaOwnerClaim, charset: MysqlCharset | undefined) => Effect.Effect<{
     readonly previous: string | undefined;
-}, SqlError_2>;
+}, SqlError>;
 
 export declare const unblockLossy: (plan: MigrationPlan, scope?: ReturnType<typeof destructiveScope>) => MigrationPlan;
 
@@ -6756,7 +6992,7 @@ declare interface WindowSpec_2 {
     }>;
 }
 
-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>;
+export declare const withMigrationLock: <A, E, R = never>(sql: SqlClient.SqlClient, work: Effect.Effect<A, E, R>, scope?: MigrationLockScope) => Effect.Effect<A, E | SqlError, R>;
 
 /**
  * Wrap a migration context so its four existence questions are recorded when —