@voltro/database 0.71.0 → 0.72.0

package/dist/index.d.ts

@@ -1791,6 +1791,11 @@ export declare interface ColumnDefinition<TsType, Type extends ColumnType = Colu
  *  `boolean` does not distribute. */
 declare type ColumnHasDefault<D> = D extends ColumnDefinition<unknown, ColumnType, infer HD> ? ([HD] extends [true] ? true : false) : false;
 
+/** A column as the DSL builds it — `text().nullable()`, `integer().default(0)` — or its definition. */
+export declare type ColumnInput = {
+    __definition(): ColumnDefinition<unknown>;
+} | ColumnDefinition<unknown>;
+
 /** A column may be omitted from an insert when it is auto-filled, has a default,
  *  or is nullable. */
 declare type ColumnOptionalForInsert<K extends PropertyKey, D> = K extends AutoFilledColumn ? true : ColumnHasDefault<D> extends true ? true : null extends InferColumn<D> ? true : false;
@@ -1811,6 +1816,232 @@ declare type ColumnOptionalForInsert<K extends PropertyKey, D> = K extends AutoF
  */
 export declare const columnSchema: <TsType, C extends ColumnType>(def: ColumnDefinition<TsType, C>) => Schema.Schema.Any;
 
+/**
+ * A column as seen by the planner: either declared in code (extracted
+ * from `ColumnDefinition`) or live in the DB (extracted via introspection).
+ *
+ * The shape is intentionally minimal — only the bits that affect diff
+ * classification land here. Things like `idScheme`, `computed`,
+ * `defaultFactory` etc. live in the runtime layer and don't survive
+ * the round-trip to `information_schema`.
+ */
+declare interface ColumnSnapshot {
+    readonly name: string;
+    readonly type: ColumnType;
+    readonly nullable: boolean;
+    readonly unique: boolean;
+    readonly hasDefault: boolean;
+    readonly defaultValue?: unknown;
+    /**
+     * Type-narrowing acknowledgement from `.narrowedFrom(from, { using })`.
+     * Only ever set on the DECLARED side; introspection leaves it
+     * undefined (the live DB has no notion of a prior type). When
+     * `from` equals the live column type the planner downgrades the
+     * otherwise-blocked type change to `needs-backfill` and threads
+     * `using` into the `ALTER COLUMN … TYPE … USING <using>` cast. */
+    readonly narrowedFrom?: {
+        readonly from: ColumnType;
+        readonly using?: string;
+    };
+    /**
+     * Bounded text length from `text().maxLength(n)` — carried on BOTH sides.
+     *
+     * DECLARED: from the column definition. LIVE: from introspection, and ONLY when
+     * the dialect materialises a length. An unbounded text family member
+     * (`text`/`longtext`/`mediumtext`/`clob`) leaves this `undefined` rather than
+     * reporting the type's theoretical maximum — mysql answers 4294967295 for
+     * `longtext`, and comparing that against a declared `undefined` would re-emit an
+     * ALTER on every boot forever.
+     *
+     * WHY IT IS HERE AT ALL. It was absent from the snapshot entirely: the value
+     * lived on the column definition, was read only when rendering CREATE DDL, and
+     * never reached the comparison. So the differ was not comparing lengths wrongly
+     * — it could not see them. Adding `.maxLength(n)` to an EXISTING column planned
+     * zero operations and reported "schema is up to date" while the live column
+     * stayed `longtext`. A deployment hit that trying to apply the documented remedy
+     * for MariaDB's hash long-unique, and their contrast is what pinned it: a column
+     * bounded AT CREATION was `varchar(64)` (DDL path, fine), one bounded afterwards
+     * stayed `longtext` (diff path, blind).
+     *
+     * NOT compared on sqlite: it has no length-enforced type, so the declared value
+     * is real and the live side can never report one. Comparing them there would
+     * re-emit forever. See `sameColumnShape`.
+     */
+    readonly maxLength?: number;
+    readonly references?: {
+        readonly table: string;
+        readonly column: string;
+        readonly onDelete?: 'cascade' | 'restrict' | 'setNull' | 'noAction';
+        readonly onUpdate?: 'cascade' | 'restrict' | 'setNull' | 'noAction';
+        /**
+         * Orphan-handling policy for adding this FK to a POPULATED column
+         * (`reference(() => t, { orphanPolicy })`). Only ever set on the
+         * DECLARED side; introspection leaves it undefined (the live DB has
+         * no notion of it). `normRef` strips it before comparison so it never
+         * causes FK churn — the planner reads it directly to classify +
+         * drive the applier's orphan pre-step. See the references-diff in
+         * `classifyColumnChange`.
+         */
+        readonly orphanPolicy?: 'fail' | 'null' | 'delete';
+        /**
+         * The constraint's catalog name, on the LIVE side only. A reader reports
+         * it (postgres, the mysql family, mssql; sqlite names nothing) so a drop
+         * can name the constraint that is actually there rather than assume the
+         * `<table>_<column>_fkey` convention the framework uses when IT creates
+         * one. `normRef` strips it before comparison and before hashing: a name
+         * is a catalog identity, not schema.
+         */
+        readonly constraintName?: string;
+    };
+    /** Physical representation for `reference()`; defaults to `text`. */
+    readonly referenceStorage?: 'text' | 'numeric';
+    /** `oneOf(['a','b'])` → CHECK constraint values. */
+    readonly oneOf?: ReadonlyArray<string>;
+    /** Required/observed JSON validity on SQL Server. Unverified means no
+     * recognized enabled and trusted check proves the existing data valid. */
+    readonly jsonValidation?: 'value' | 'container' | 'unverified';
+    /** Live SQL Server JSON checks recognized by complete predicate shape.
+     * Names are catalog identities for DDL, not portable schema fingerprints. */
+    readonly jsonChecks?: ReadonlyArray<{
+        readonly name: string;
+        readonly validation: 'value' | 'container';
+        readonly enabled: boolean;
+        readonly trusted: boolean;
+    }>;
+    /**
+     * Fixed-point precision + scale for a `decimal(p,s)` / `numeric(p,s)`
+     * column (`type === 'decimal'`). Drives the emitted `NUMERIC(p,s)` /
+     * `DECIMAL(p,s)` DDL. Set on the DECLARED side; introspection leaves them
+     * undefined (the planner compares the `decimal` type structurally, not the
+     * exact precision — an ALTER of precision alone is not auto-classified, same
+     * posture as `generatedAs`). See `snapshotPgType` / `snapshotMysqlType`.
+     */
+    readonly precision?: number;
+    readonly scale?: number;
+    /**
+     * Id-generation scheme for `type: 'id'` columns. Mirrors
+     * `ColumnDefinition.idScheme.kind` so the applier can tell a numeric
+     * auto-increment PK (`kind: 'numeric'`) from a typeid/string PK and
+     * emit the dialect-correct auto-increment DDL (BIGSERIAL / BIGINT
+     * AUTO_INCREMENT / IDENTITY / INTEGER AUTOINCREMENT). Only ever set on
+     * the DECLARED side; introspection leaves it undefined (the live DB
+     * doesn't report a scheme — a numeric PK is detectable there from the
+     * integer type + auto_increment, which the diff doesn't need).
+     */
+    readonly idScheme?: {
+        readonly kind: string;
+    };
+    /**
+     * What the `id` KIND is made of, on the LIVE side.
+     *
+     * Introspection cannot see a DSL spelling, only a column, and it reports the
+     * `id` kind for ANY sole primary key named `id` — a NAME-based inference. So
+     * the kind alone erases the one distinction that matters when the two sides
+     * disagree: a text key and a sequence are both reported as `id`, and a
+     * declaration that changed from one to the other compared EQUAL. That
+     * approximation predates the `text()` spelling and got wider with it.
+     *
+     * This carries the storage the kind was inferred over, derived from the same
+     * raw type the introspector already read. Set by all four dialect readers
+     * wherever they apply the inference, and derived for the DECLARED side from
+     * `idScheme` — so the comparison pairs like with like instead of pairing on
+     * the name.
+     */
+    readonly idStorage?: 'text' | 'numeric';
+    /**
+     * What this column's declared KIND is stored AS, when the two differ and no
+     * reader can report the kind back.
+     *
+     * An `array()` is `<element>[]` on postgres and JSON / NVARCHAR(MAX) / TEXT
+     * elsewhere, and every reader answers with the STORAGE — so the declared
+     * kind and the live one never matched and the table hashed apart from its own
+     * database forever. The planner already collapses this per dialect; the
+     * fingerprint has no dialect, so the DECLARED side states the answer here at
+     * snapshot time (`declaredSnapshot` takes the dialect) and the hash reads it.
+     * Set on the declared side only; a live snapshot needs none, because its type
+     * IS the storage.
+     */
+    readonly storageType?: ColumnType;
+    /**
+     * Verbatim DDL fragment for a `raw(ddl)` column (`type === 'raw'`).
+     * Emitted unchanged as the column's SQL type on every dialect — the
+     * applier and the CREATE-TABLE emitter both defer to it. Only ever set
+     * on the declared side; the live DB reports a concrete type, not the
+     * original fragment, so introspection leaves it undefined.
+     */
+    readonly rawDdl?: string;
+    /**
+     * `.generatedAs(expr, { stored })` — a DB-computed column. When set the
+     * applier emits `GENERATED ALWAYS AS (<expr>) STORED|VIRTUAL` (mssql:
+     * `AS (<expr>) PERSISTED`) and SUPPRESSES NOT NULL / DEFAULT / inline
+     * UNIQUE / REFERENCES (the value is computed; the DB rejects those
+     * alongside a generation clause). Only ever set on the DECLARED side —
+     * introspection does NOT read generation expressions, so the live snapshot
+     * leaves it undefined. The planner's `sameColumnShape` deliberately does
+     * NOT compare this field, so a declared-generated column never diffs
+     * against its introspected-as-plain live form (no churn). Consequence:
+     * the declarative engine creates generated columns correctly but does NOT
+     * detect a CHANGE to the expression after the fact — recreate the table
+     * (drop + re-migrate) to alter a generation expression.
+     */
+    readonly generatedAs?: {
+        readonly expr: string;
+        readonly stored: boolean;
+    };
+    /**
+     * Data-sensitivity classification from `.sensitive(class)` (or implied by
+     * `.encrypted()`). DECLARED-side only — introspection never reports it. Read
+     * by the export masker to pseudonymise/anonymise the column when copying to a
+     * lower environment; the planner ignores it (no DDL, no churn). See `safe`.
+     */
+    readonly sensitive?: {
+        readonly class: string;
+    };
+    /**
+     * Reviewed-safe marker from `.safe()`. DECLARED-side only. Lets the export
+     * masker be fail-closed: a column that is neither `sensitive` nor `safe`
+     * blocks a masking export until classified.
+     */
+    readonly safe?: boolean;
+    /**
+     * Type PARAMETERS for the three `ColumnType`s whose DDL is not determined by
+     * the type tag alone — `vector(n)`, `array(of)`, `enum(name, values)`.
+     * DECLARED-side only (introspection reports a concrete SQL type, not the
+     * declaration that produced it).
+     *
+     * These exist because the applier renders its DDL from a ColumnSnapshot, not
+     * from the `ColumnDefinition` that `migrate.ts`'s canonical `sqlType` reads.
+     * Without them the snapshot renderers had nothing to render and collapsed all
+     * three to `text` — which is not a smaller mistake than it looks. A declared
+     * `vector(1536)` against a live `text` column planned an `alter-column-type`
+     * that emitted `ALTER COLUMN … TYPE text`: valid SQL, applied successfully,
+     * changed nothing. The plan re-emitted it on every boot, the applier reported
+     * success every time, and the schema never converged. (Reported from a live
+     * pod: "applied 31 op(s)" with none of the 31 present in the database.)
+     *
+     * The rule for anything added later: if the applier has to RENDER it, the
+     * snapshot has to CARRY it — a snapshot renderer must never invent a type it
+     * wasn't given.
+     */
+    readonly vectorDim?: number;
+    readonly vectorPrecision?: 'float32' | 'half';
+    readonly arrayElement?: ColumnType;
+    readonly enumName?: string;
+    readonly enumValues?: ReadonlyArray<string>;
+    /**
+     * PostGIS `geography(kind, srid)` / `geometry(kind, srid)` parameters. Same
+     * reason as the three above: a spatial column declares `type: 'text'`, so
+     * WITHOUT this the applier's `add-column` created a plain `text` column and
+     * introspection (`USER-DEFINED` → `text`) agreed with it — no churn, no
+     * error, and no spatial column. DECLARED-side only.
+     */
+    readonly spatial?: {
+        readonly kind: 'geography' | 'geometry';
+        readonly geomKind: string;
+        readonly srid: number;
+    };
+}
+
 /**
  * How many bind parameters one row costs.
  *
@@ -2871,6 +3102,15 @@ export declare const decodeFieldValue: (cipher: FieldCipher, ciphertext: string,
 
 export declare type DecoderDialectId = 'postgres' | 'mysql' | 'mariadb' | 'sqlite' | 'mssql' | 'turso';
 
+/**
+ * The same decode, for a caller that HOLDS the table definition rather than
+ * a name to look up — the migration applier reads rows of a table it was
+ * handed as a declaration, on a process where nothing registered it.
+ */
+export declare const decodeRowsForTable: <T extends Record<string, unknown>>(rows: ReadonlyArray<T>, table: {
+    readonly fields: Record<string, unknown>;
+}, dialect: DecoderDialectId) => ReadonlyArray<T>;
+
 /**
  * Decode every row of a query result against the table's registered
  * column types + the dialect's read quirks. Returns a fresh array of
@@ -2960,6 +3200,9 @@ export declare const defineMixin: <const Input extends FieldsInput>(options: Mix
 
 export declare const defineSeed: (input: SeedDefinitionInput) => SeedDefinition;
 
+/** Forget the selection. A no-op when there is none. */
+export declare const deleteTenantSelection: (store: DataStore, identity: TenantSelectionRowIdentity) => Promise<void>;
+
 export declare const denseRank: (alias?: string) => WindowBuilder;
 
 /**
@@ -3209,6 +3452,18 @@ export declare const drainIdentifierWarnings: () => ReadonlyArray<string>;
  */
 export declare const dropped: () => ColumnBuilder<unknown, "text">;
 
+export declare interface EachOptions {
+    /** Rows per page. Default 1000. Pages are keyed by the `id` column. */
+    readonly batchSize?: number;
+    /** Milliseconds to sleep between pages, to share the database with live traffic. Default 0. */
+    readonly sleepMs?: number;
+}
+
+export declare interface EachReport {
+    readonly scanned: number;
+    readonly pages: number;
+}
+
 /**
  * Raised when a relation declared `one` matches MORE than one row for the same
  * parent key — the mis-declaration that silently hands the app an arbitrary
@@ -3660,26 +3915,72 @@ export declare interface FileMigration {
     /** Human description that surfaces in `voltro db plans` + the
      *  history timeline. Keep it short — what the migration does. */
     readonly description: string;
-    /** The forward body. Runs inside a transaction on dialects that
-     *  support transactional DDL (postgres / mssql / sqlite); runs as
-     *  separate implicit-commit statements on mysql / mariadb. */
+    /**
+     * Run `up` and the ledger row that records it inside ONE transaction, on
+     * every dialect. **The default.** A body that fails or crashes leaves
+     * nothing behind — not half its rows, and not a ledger row for work that did
+     * not finish. `transactional: false` is one unit per statement with the
+     * ledger row written after the body: a crash in the middle leaves the rows
+     * already written AND no record, so the body runs again on the next boot
+     * over half-converted data, and has to be written to survive that.
+     *
+     * The decision is per MIGRATION, not per dialect, because the engine
+     * property that matters is about DDL: MySQL, MariaDB and Turso cannot hold
+     * DDL inside a transaction — the MySQL family commits everything before it
+     * on every `ALTER`. A transactional migration there is data only. The
+     * runner MEASURES this rather than trusting it: a body that broke its own
+     * transaction is recorded, so it does not run twice, and the run then fails
+     * with the migration's name and the fix (`transactional: false`, or the
+     * schema change through `ctx.schema` in a migration of its own).
+     */
+    readonly transactional?: boolean;
+    /** The forward body. */
     readonly up: (ctx: FileMigrationContext) => Promise<void> | Effect.Effect<void, unknown, never>;
-    /** The reverse body — required. The runner uses this for
-     *  `voltro db rollback <id>`. Non-destructive inverses don't
-     *  bring back data dropped in `up`; design accordingly (see
-     *  Rollback docs). */
+    /**
+     * The reverse body — required, so that the decision is written down. A
+     * migration that repairs a shape has no inverse: say so with
+     * `down: irreversible('…')`, and `voltro db rollback-file` refuses with
+     * that reason instead of running a body that pretends.
+     */
     readonly down: (ctx: FileMigrationContext) => Promise<void> | Effect.Effect<void, unknown, never>;
 }
 
 /**
  * The runtime context a file-based migration's `up` / `down` body
  * receives.
+ *
+ * `store` is the same typed data store the application runs on — the same
+ * column codecs, the same dialect, the same query builder — bound to the
+ * database this migration is running against. A row read through it has its
+ * JSON parsed and its timestamps as `Date`s on every dialect; a row written
+ * through it is encoded the same way. `sql` stays beside it for what the
+ * builder does not express.
  */
 export declare interface FileMigrationContext {
-    /** The live `@effect/sql` SqlClient — issue raw DDL via
-     *  `sql.unsafe(...)`, tagged-template fragments via `sql\`...\``,
-     *  per-dialect dispatch via `sql.onDialectOrElse({...})`. */
-    readonly sql: SqlClient.SqlClient;
+    /**
+     * The escape hatch, and it asks for a reason. `raw('why')` returns the
+     * `@effect/sql` client — `sql.unsafe(...)`, `sql\`...\``,
+     * `sql.onDialectOrElse({...})` — for the one thing neither `store` nor
+     * `schema` expresses. The reason is required (an empty one throws), it is
+     * what `voltro doctor` lists beside every migration that reaches for raw
+     * SQL, and it is the sentence a reviewer reads first. A migration written
+     * against the raw client is bound to the dialect it was written on; the
+     * rest of this context is not.
+     */
+    readonly raw: (reason: string) => SqlClient.SqlClient;
+    /**
+     * The application's data store over this database. Typed reads through a
+     * descriptor (`store.query(database.vacations.descriptor)`) are checked
+     * against the CURRENT declaration at compile time — a column renamed since
+     * this migration was written fails the build, not the deploy. Reads by
+     * table name (`store.query({ table: 'vacations', … })`) go to the database
+     * as it is, decoded through whatever the current declaration says about
+     * the columns it still knows; a column it no longer declares passes
+     * through as the driver returned it.
+     */
+    readonly store: DataStore;
+    /** The dialect this migration is running against. */
+    readonly dialect: DialectId;
     /**
      * Lightweight log surface scoped to the migration. Lands in
      * `voltro logs --filter 'migrations:file:<id>'` for any apply
@@ -3692,6 +3993,63 @@ export declare interface FileMigrationContext {
     /** ISO-8601 timestamp when this migration started (deterministic
      *  across the up/down pair via the applied_at column). */
     readonly appliedAt: string;
+    /** Schema questions and dialect-aware schema operations. */
+    readonly schema: MigrationSchemaOps;
+    /**
+     * Visit every row of `table` in pages keyed by `id`. `fn` may return a
+     * Promise or an Effect. The table needs an `id` column, which every
+     * `table()` with `id()` has.
+     */
+    readonly each: <R extends Row = Row>(table: string, fn: (row: R) => Promise<void> | Effect.Effect<void, unknown, never>, options?: EachOptions) => Effect.Effect<EachReport, unknown>;
+    /**
+     * Read rows in pages, compute a patch per row, write it back under an
+     * optimistic guard, and repeat until a pass changes nothing.
+     *
+     * The guard is the row's own values: the UPDATE carries `WHERE id = ? AND
+     * <each patched column> = <the value just read>` (plus `options.guard`), so
+     * a row another process changed between the read and the write is not
+     * overwritten — it is counted as contended and read again on the next
+     * pass. That is the guard a migration needs while the previous deploy is
+     * still writing, without a hashing function a dialect may not have.
+     *
+     * `fn` returns the patch, or `undefined` for a row that is already in
+     * shape. A pass in which every row returns `undefined` and nothing was
+     * contended is the stable state that ends the rewrite.
+     */
+    readonly rewrite: <R extends Row = Row>(table: string, fn: (row: R) => Partial<R> | undefined | Promise<Partial<R> | undefined>, options?: RewriteOptions) => Effect.Effect<RewriteReport, unknown>;
+    /**
+     * A post-condition. Registered during `up`, evaluated after it — every one
+     * must hold, or the migration FAILS and is not recorded, so the next run
+     * tries again. This is the "read it back and check" every data migration
+     * ends with, as a contract the runner enforces instead of a pattern each
+     * body repeats.
+     */
+    readonly expect: (description: string, check: () => Promise<boolean> | Effect.Effect<boolean, unknown, never>) => void;
+    /**
+     * A precondition. When `condition` is false the body stops HERE, the
+     * migration is recorded as applied with `skipped: <reason>` in its notes,
+     * and it never runs again on this database — the same answer Liquibase's
+     * `MARK_RAN` gives. For a migration that must not be recorded when its
+     * precondition fails, fail it instead.
+     *
+     *     yield* ctx.skipUnless(ctx.schema.tableExists('vacations'), 'no vacations table on this database')
+     */
+    readonly skipUnless: (condition: boolean | Promise<boolean> | Effect.Effect<boolean, unknown, never>, reason: string) => Effect.Effect<void, unknown>;
+    /**
+     * Run `work` inside ONE database transaction: the `store` it receives is
+     * the transaction's view, and an Effect it returns is executed on the
+     * transaction's connection, so `sql` statements yielded inside it are part
+     * of the same unit. A migration that is transactional as a whole declares
+     * `transactional: true` instead and gets the ledger row in the same unit.
+     *
+     * What the engine cannot do, this cannot do either: on MySQL and MariaDB a
+     * DDL statement inside the unit commits everything before it. A
+     * transactional scope is for data.
+     */
+    readonly transactional: <T>(work: (tx: {
+        readonly store: DataStore;
+        readonly raw: (reason: string) => SqlClient.SqlClient;
+    }) => Promise<T> | Effect.Effect<T, unknown, SqlClient.SqlClient>) => Effect.Effect<T, unknown>;
 }
 
 /**
@@ -4041,6 +4399,32 @@ export declare interface IndexKindOptions {
     };
 }
 
+declare interface IndexSnapshot {
+    readonly name: string;
+    readonly table: string;
+    readonly columns: ReadonlyArray<string>;
+    readonly unique: boolean;
+    /** Physical access method; absent means btree. Catalogs may name extension methods. */
+    readonly kind?: string;
+    /** Resolved HNSW build parameters and operator class, not a query-time metric. */
+    readonly kindOptions?: IndexKindOptions;
+    /** SQL predicate for a partial/filtered index; never a full UNIQUE constraint. */
+    readonly where?: string;
+    /** False for an invalid PostgreSQL index left by an interrupted online build. */
+    readonly valid?: boolean;
+    /**
+     * Expression / json-path index (`expressionIndex(...)` / `jsonIndex(...)`),
+     * i.e. at least one key is a SQL expression rather than a bare column. The
+     * DB normalises the expression text on introspection (`(lower("email"))` →
+     * `lower(email)`), so it can NEVER round-trip byte-for-byte. The planner
+     * therefore matches such indexes by NAME + uniqueness only (see
+     * `sameIndexShape`) — without this they re-emit on every `db plan` forever
+     * (postgres pre-fix: they were INVISIBLE to introspect — an `add` with no
+     * `drop` that never converged to "up to date").
+     */
+    readonly expression?: boolean;
+}
+
 export declare type InferColumn<C> = C extends ColumnDefinition<infer T, ColumnType> ? T : never;
 
 /**
@@ -4209,6 +4593,25 @@ export declare const intersect: (...queries: ReadonlyArray<QueryWithDescriptorAn
  */
 export declare const interval: () => ColumnBuilder<string, "interval", boolean>;
 
+/**
+ * A `down` that says there is no inverse — with the reason, which is what a
+ * rollback prints. A data migration that repairs a broken shape HAS no
+ * inverse (its inverse would be the defect), and a `down` that only logs
+ * "nothing to undo" and returns success lets `voltro db rollback-file`
+ * delete the ledger row for a change that is still in the database.
+ */
+export declare const irreversible: (reason: string) => FileMigration["down"];
+
+export declare class IrreversibleMigrationError extends Error {
+    readonly migrationId: string;
+    readonly reason: string;
+    readonly _tag = "IrreversibleMigrationError";
+    constructor(migrationId: string, reason: string);
+}
+
+/** The reason a `down` was declared irreversible with, or `undefined` for an ordinary body. */
+export declare const irreversibleReason: (down: FileMigration["down"]) => string | undefined;
+
 /** Is this value a BOUND ciphertext (`enc:v2:`)? An unbound `enc:v1:` value
  *  reads fine and is what `voltro db encrypt-column` re-binds. */
 export declare const isBoundCiphertext: (value: unknown) => value is string;
@@ -4689,16 +5092,13 @@ export declare type MergeMixinFields<Mixins extends ReadonlyArray<AnyMixin>> = M
  *     export default migration({
  *       id:          '20260415_120000_split_address_out',
  *       description: 'Move users.address* into a separate addresses table.',
- *       up: async ({ sql, log }) => {
- *         await sql.unsafe(`CREATE TABLE addresses ( ... )`)
- *         await sql.unsafe(`INSERT INTO addresses (...) SELECT (...) FROM users`)
- *         await sql.unsafe(`ALTER TABLE users DROP COLUMN addressStreet`)
- *         log.info('migrated address fields to new table')
- *       },
- *       down: async ({ sql }) => {
- *         await sql.unsafe(`ALTER TABLE users ADD COLUMN addressStreet text`)
- *         // ... etc — see file-based docs for the full pattern
- *       },
+ *       up: ({ sql, store, log }) => Effect.gen(function* () {
+ *         yield* sql.unsafe(`CREATE TABLE addresses ( ... )`)
+ *         yield* sql.unsafe(`INSERT INTO addresses (...) SELECT (...) FROM users`)
+ *         yield* sql.unsafe(`ALTER TABLE users DROP COLUMN addressStreet`)
+ *         yield* log.info('migrated address fields to new table')
+ *       }),
+ *       down: irreversible('the address rows have no column to go back to'),
  *     })
  */
 export declare const migration: (spec: FileMigration) => FileMigration;
@@ -4735,6 +5135,109 @@ export declare interface MigrationDefinitionInput {
  */
 export declare type MigrationEffect = Effect.Effect<unknown, unknown, SqlClient.SqlClient>;
 
+/** One or more `ctx.expect` post-conditions did not hold after `up`. */
+export declare class MigrationExpectationFailed extends Error {
+    readonly migrationId: string;
+    readonly failed: ReadonlyArray<string>;
+    readonly _tag = "MigrationExpectationFailed";
+    constructor(migrationId: string, failed: ReadonlyArray<string>);
+}
+
+/**
+ * Schema questions and schema operations a migration body can ask of the
+ * database it is running against, spelled once for every dialect.
+ *
+ * Every operation is idempotent by INSPECTION, not by error tolerance: it
+ * reads the live schema first and answers `already-absent` /
+ * `already-present` when there is nothing to do. That is the portable
+ * `IF EXISTS` — MySQL has no such clause for a foreign key, and its two
+ * "already gone" error codes are not the kind of thing a migration should
+ * be matching on.
+ *
+ * On SQLite the dropping operations are table rebuilds (the dialect has no
+ * `DROP CONSTRAINT`), built from the live table minus the change — the same
+ * rebuild the planner's applier performs, with foreign-key enforcement off
+ * for its duration and checked before the connection is handed back.
+ */
+export declare interface MigrationSchemaOps {
+    /** The live schema, read fresh on every call — an operation above may have changed it. */
+    readonly snapshot: () => Effect.Effect<SchemaSnapshot, unknown>;
+    readonly tableExists: (table: string) => Effect.Effect<boolean, unknown>;
+    readonly columnExists: (table: string, column: string) => Effect.Effect<boolean, unknown>;
+    readonly indexExists: (table: string, index: string) => Effect.Effect<boolean, unknown>;
+    /** Whether `table.column` currently carries a FOREIGN KEY. */
+    readonly foreignKeyExists: (table: string, column: string) => Effect.Effect<boolean, unknown>;
+    /** Drop the FOREIGN KEY on `table.column`, under the name the catalog reports for it. */
+    readonly dropForeignKey: (table: string, column: string) => Effect.Effect<SchemaOpOutcome, unknown>;
+    readonly dropIndex: (table: string, index: string) => Effect.Effect<SchemaOpOutcome, unknown>;
+    /** Drop a column — and first the FOREIGN KEY it carries, if any, on the
+     *  dialects that refuse to drop a column a constraint still holds. */
+    readonly dropColumn: (table: string, column: string) => Effect.Effect<SchemaOpOutcome, unknown>;
+    /** Rename a column. `already-present` when `to` exists and `from` does not:
+     *  a re-run after a crash that landed the rename. */
+    readonly renameColumn: (table: string, from: string, to: string) => Effect.Effect<SchemaOpOutcome, unknown>;
+    /** Create a table from a declaration. `already-present` when a table of that name exists. */
+    readonly createTable: (table: TableLike) => Effect.Effect<SchemaOpOutcome, unknown>;
+    /** Drop a table and everything in it. Data loss is the caller's explicit intent here. */
+    readonly dropTable: (table: string) => Effect.Effect<SchemaOpOutcome, unknown>;
+    /** Rename a table. `already-present` when `to` exists and `from` does not. */
+    readonly renameTable: (from: string, to: string) => Effect.Effect<SchemaOpOutcome, unknown>;
+    /**
+     * Add a column. A NOT NULL column without a default cannot be added to a
+     * table that has rows on any dialect: add it nullable or with a default,
+     * fill it (`rewrite`), then `alterColumn(table, name, { nullable: false })`.
+     */
+    readonly addColumn: (table: string, name: string, column: ColumnInput) => Effect.Effect<SchemaOpOutcome, unknown>;
+    /**
+     * Change a column's nullability and/or default. `default: null` removes the
+     * default; a type change goes through `evolve`, where the planner decides
+     * whether it is lossy.
+     */
+    readonly alterColumn: (table: string, name: string, change: {
+        readonly nullable?: boolean;
+        readonly default?: unknown;
+    }) => Effect.Effect<SchemaOpOutcome, unknown>;
+    /** Add an index over `columns`; the name defaults to `<table>_<cols>_idx`. */
+    readonly addIndex: (table: string, columns: ReadonlyArray<string>, options?: {
+        readonly unique?: boolean;
+        readonly name?: string;
+    }) => Effect.Effect<SchemaOpOutcome, unknown>;
+    /** Add a FOREIGN KEY from `table.column` to `target.table`'s `target.column` (default `id`). */
+    readonly addForeignKey: (table: string, column: string, target: {
+        readonly table: string;
+        readonly column?: string;
+    }, options?: {
+        readonly onDelete?: 'cascade' | 'restrict' | 'setNull' | 'noAction';
+        readonly onUpdate?: 'cascade' | 'restrict' | 'setNull' | 'noAction';
+    }) => Effect.Effect<SchemaOpOutcome, unknown>;
+    /** Remove every row. `DELETE FROM` where the dialect has no TRUNCATE inside a unit. */
+    readonly truncate: (table: string) => Effect.Effect<void, unknown>;
+    /**
+     * The Voltro way to change a table's shape in a migration: DECLARE the
+     * table as it should be from here on, and the same planner that drives
+     * `voltro db apply` diffs it against the live table and applies the
+     * difference — add, drop, rename, retype, index, constraint — with the same
+     * per-dialect statements, the same three-step backfills, and the same
+     * convergence proof (an `evolve` whose re-plan is not empty fails). A drop
+     * is allowed without a `dropped()` marker: calling `evolve` from a
+     * migration IS the explicit intent the marker stands for elsewhere.
+     */
+    readonly evolve: (table: TableLike) => Effect.Effect<{
+        readonly applied: number;
+    }, unknown>;
+}
+
+/**
+ * The signal `ctx.skipUnless` raises. The runner treats it as an OUTCOME,
+ * not a failure: the migration is recorded with the reason and never runs
+ * again on this database.
+ */
+export declare class MigrationSkipped {
+    readonly reason: string;
+    readonly _tag = "MigrationSkipped";
+    constructor(reason: string);
+}
+
 export declare interface MigrationStep {
     readonly name: string;
     readonly apply: MigrationEffect;
@@ -6157,6 +6660,9 @@ export declare interface ReadableByColumn {
  */
 export declare const readableByColumns: (table: TableLike) => ReadonlyArray<ReadableByColumn>;
 
+/** The stored tenant, or null when the subject has no selection. */
+export declare const readTenantSelection: (store: DataStore, identity: TenantSelectionRowIdentity) => Promise<string | null>;
+
 /** Floating-point number. Postgres `DOUBLE PRECISION`, mysql/mariadb `DOUBLE`,
  *  mssql `FLOAT`, sqlite `REAL`. Drivers return JS numbers — no codec. Use for
  *  fractional values (ratings, percentages, measurements) where `integer()`
@@ -6609,6 +7115,39 @@ export declare const retentionTtlMsFromEnv: (envValue: string | undefined, defau
 
 export declare type RetryDecision = 'retry' | 'noRetry';
 
+export declare interface RewriteOptions extends EachOptions {
+    /**
+     * Columns whose CURRENT value must still hold when the patch is written, in
+     * addition to the columns the patch itself changes. A JSON column cannot be
+     * compared by value on every dialect, so a rewrite of one guards on what
+     * you name here — an `updatedAt`, a `version` — rather than on the document.
+     */
+    readonly guard?: ReadonlyArray<string>;
+    /**
+     * How many passes over the table before contention is a failure. A pass
+     * that rewrites nothing and contends on nothing is STABLE and ends the
+     * rewrite; a row that changed under the migration between its read and its
+     * write is contended and is read again on the next pass. Default 10.
+     */
+    readonly maxPasses?: number;
+}
+
+export declare interface RewriteReport {
+    readonly passes: number;
+    readonly scanned: number;
+    readonly rewritten: number;
+    /** Writes lost to a concurrent change and retried on a later pass. */
+    readonly contended: number;
+}
+
+/** A `ctx.rewrite` that was still contended after `maxPasses`. */
+export declare class RewriteUnstableError extends Error {
+    readonly table: string;
+    readonly report: RewriteReport;
+    readonly _tag = "RewriteUnstableError";
+    constructor(table: string, report: RewriteReport);
+}
+
 export declare type Row = Readonly<Record<string, unknown>>;
 
 declare type Row_2 = Readonly<Record<string, unknown>>;
@@ -6805,6 +7344,18 @@ export declare interface SchemaChangeSeedEvent {
 
 export declare type SchemaChangeSeedHook = (event: SchemaChangeSeedEvent) => Promise<void>;
 
+/** What a schema operation on the migration context found to do. */
+export declare type SchemaOpOutcome = 'applied' | 'already-absent' | 'already-present';
+
+/**
+ * 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
+ * shape so the diff algorithm is symmetric.
+ */
+declare interface SchemaSnapshot {
+    readonly tables: ReadonlyArray<TableSnapshot>;
+}
+
 /**
  * The PUBLIC structural view of a built table — name, columns, and applied
  * indexes — with NONE of the fluent builder methods.
@@ -8049,6 +8600,36 @@ export declare interface TableRule {
     readonly severity: RuleSeverity;
 }
 
+declare interface TableSnapshot {
+    readonly name: string;
+    readonly columns: ReadonlyArray<ColumnSnapshot>;
+    readonly indexes: ReadonlyArray<IndexSnapshot>;
+    /**
+     * Composite PRIMARY KEY column set (`.primaryKey(['a','b'])`). Set on the
+     * DECLARED side only — it drives the `PRIMARY KEY (a, b)` line in the
+     * applier's create-table emission. Absent (the default) means the single
+     * `id()` column carries the PK inline. Introspection leaves it undefined;
+     * the live PK is compared via the synthesised `<table>_pkey` index.
+     */
+    readonly primaryKey?: ReadonlyArray<string>;
+    /**
+     * Approximate row count from the live DB's planner stats — used by
+     * the migration planner to promote `safe` ops to `online-required`
+     * when the table exceeds the configured threshold (default 50_000).
+     * Pulled from `pg_class.reltuples` on postgres; equivalent stats
+     * on other dialects. Absent on the declared side of the diff (no
+     * data exists yet), present from introspection.
+     */
+    readonly rowCount?: number;
+    /**
+     * The name this table previously had (`table(name, fields, { renamedFrom })`).
+     * DECLARED side only — introspection has no way to know. The planner pairs it
+     * against a live table of that name and folds what would otherwise be
+     * DROP + CREATE into a `rename-table`.
+     */
+    readonly renamedFrom?: string;
+}
+
 /** A page read failed while streaming a table. Carries the underlying store
  *  error as `cause` so callers can inspect the transient-ness for retry. */
 export declare class TableStreamError extends TableStreamError_base<{
@@ -8076,6 +8657,8 @@ export declare interface TableUnique {
  */
 export declare const teardownBranch: (branchId: string, mechanism: BranchMechanism, executor: BranchExecutor) => Promise<ReadonlyArray<BranchStep>>;
 
+export declare const TENANT_SELECTIONS_TABLE: string;
+
 /** What a tenant-create firing knows: which namespace was just provisioned. */
 export declare interface TenantCreateSeedEvent {
     /** The namespace (postgres schema / mysql database / attached sqlite file)
@@ -8137,6 +8720,19 @@ export declare class TenantResidencyUnresolved extends Error {
     constructor(message: string);
 }
 
+/** The row id a subject's selection lives under: a hash of the identity, so
+ *  the key is bounded on every dialect and a second selection for one subject
+ *  is the same row, never a second one. */
+export declare const tenantSelectionId: (identity: TenantSelectionRowIdentity) => string;
+
+/** The two fields that name a subject across credentials. Structurally the
+ *  protocol's `TenantSelectionIdentity`; typed loosely here because this
+ *  package does not depend on the protocol. */
+export declare interface TenantSelectionRowIdentity {
+    readonly type: string;
+    readonly id: string;
+}
+
 export declare const text: () => ColumnBuilder<string, "text", boolean>;
 
 export declare const timestamp: () => ColumnBuilder<Date, "timestamp", boolean>;
@@ -8191,6 +8787,21 @@ export declare interface TransactionalViewHandle {
     commitEvents(): void;
 }
 
+/**
+ * A `transactional` migration whose body committed the transaction from
+ * inside — DDL on the MySQL family, or an explicit COMMIT. The body's work
+ * IS in the database and the migration IS recorded (running it again would
+ * repeat the committed half); what failed is the guarantee the migration
+ * asked for, and the run stops so nobody deploys on top of an assumption
+ * that did not hold.
+ */
+export declare class TransactionBrokenByBodyError extends Error {
+    readonly migrationId: string;
+    readonly dialect: DialectId;
+    readonly _tag = "TransactionBrokenByBodyError";
+    constructor(migrationId: string, dialect: DialectId);
+}
+
 /**
  * The `[Connection, depth]` tuple `@effect/sql` provides inside
  * `withTransaction`. Every statement that must run on the transaction's OWN
@@ -8679,6 +9290,18 @@ export declare const _voltroCdcOffsetsTable: TableLike;
  */
 export declare const _voltroDataTransfersTable: TableLike;
 
+/**
+ * `_voltro_devices` — device identity beside `_voltro_api_keys`: a machine
+ * caller with a tenant whose credential is short-lived and rotated. Only
+ * hashes: the one-time pairing code, the current access token, the current
+ * refresh token and the refresh token rotated OUT last (a replay of it revokes
+ * the device). `generation` counts rotations. Hash columns are indexed, not
+ * unique: they are nullable, and a UNIQUE over NULLs is the partial-unique
+ * trap on MariaDB. Created for every sql app (empty unless `devices` is
+ * enabled in app.config). See `@voltro/runtime`'s `DeviceService`.
+ */
+export declare const _voltroDevicesTable: SchemaTable;
+
 /**
  * `_voltro_idempotency` — one row per (scope, key) for HTTP idempotency
  * (the `Idempotency-Key` header on REST routes). `scope` namespaces the key
@@ -8701,15 +9324,6 @@ export declare const _voltroDataTransfersTable: TableLike;
  */
 export declare const _voltroIdempotencyTable: SchemaTable;
 
-/**
- * `_voltro_kv` — the durable key-value store behind `ctx.kv` / the `Kv`
- * service when `KV_BACKEND=database` (the default for sql apps). One row per
- * key; `key` is UNIQUE and already carries any namespace the facade layered on
- * (e.g. a per-tenant prefix). `value` is opaque JSON; `expiresAt` drives the
- * optional TTL (NULL = never). Distinct from the cache: entries are NEVER
- * evicted for capacity — they live until deleted or their TTL lapses. Created
- * for every sql app (empty unless `ctx.kv` is used).
- */
 export declare const _voltroKvTable: SchemaTable;
 
 /**
@@ -8795,6 +9409,19 @@ export declare const _voltroReplicaObservationsTable: SchemaTable;
  */
 export declare const _voltroSeedsTable: SchemaTable;
 
+/**
+ * `_voltro_tenant_selections` — the ACTIVE tenant a subject chose among the
+ * tenants it belongs to, stored beside the subject rather than inside a
+ * credential so it survives the credential: the next JWT from an external
+ * IdP, the next API-key call, finds it. One row per subject identity —
+ * `id` is `sha256(type, id)` (`tenantSelectionId` in `@voltro/runtime`), so
+ * a `text` primary key stays bounded on every dialect. Verified against the
+ * app's memberships on every request it applies to and cleared when the
+ * membership is gone. Created for every sql app (empty unless `auth.memberships`
+ * is configured and someone switches).
+ */
+export declare const _voltroTenantSelectionsTable: SchemaTable;
+
 export declare const walkLeaves: (predicate: Predicate, conjunctive?: boolean) => Generator<PredicateLeafWithContext>;
 
 /** Three chars from the floor — at this point a typical next-column
@@ -8940,4 +9567,8 @@ export declare type WriteRecorder = (port: TxnRecorderPort, write: RecordedWrite
 /** Are recorders suspended right here? Exported so a caller can SAY so. */
 export declare const writeRecordersSuspended: () => boolean;
 
+/** Store the selection — an upsert on the derived id, so it is a replace. The
+ *  caller has verified the membership; this writes, and only writes. */
+export declare const writeTenantSelection: (store: DataStore, identity: TenantSelectionRowIdentity, tenantId: string) => Promise<void>;
+
 export { }