@voltro/database 0.71.1 → 0.73.0

package/dist/sql.d.ts

@@ -22,6 +22,19 @@ declare interface AggregateColumn<TResult = number | Date | null> {
     readonly _result?: TResult;
 }
 
+declare interface AggregateColumn_2<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';
+    readonly column?: string;
+    readonly alias: string;
+    readonly window?: WindowSpec_2;
+    /** Used by lag/lead — offset rows (default 1). */
+    readonly offset?: number;
+    /** Phantom — carries the projected/aggregated result type so
+     *  `aggregate<Spec>()` can infer a precise result row. Never set at
+     *  runtime; exists purely for `AggregateColumn<infer T>` inference. */
+    readonly _result?: TResult;
+}
+
 /** One condition under which a failed DDL statement means "already done". */
 export declare interface AlreadySatisfied {
     /** Why this is safe to ignore. Read by a human, not by code. */
@@ -36,6 +49,10 @@ declare interface AndPredicate {
     readonly and: ReadonlyArray<Predicate>;
 }
 
+declare interface AndPredicate_2 {
+    readonly and: ReadonlyArray<Predicate_2>;
+}
+
 /**
  * Approximate-nearest-neighbour search clause carried on a
  * {@link QueryDescriptor}. See {@link QueryDescriptor.annClause}.
@@ -62,6 +79,32 @@ declare interface AnnClause {
     readonly alpha?: number;
 }
 
+/**
+ * Approximate-nearest-neighbour search clause carried on a
+ * {@link QueryDescriptor}. See {@link QueryDescriptor.annClause}.
+ */
+declare interface AnnClause_2 {
+    /** Vector column to search. */
+    readonly column: string;
+    /** Literal query vector (array overload). Mutually exclusive with `queryText`. */
+    readonly queryVector?: ReadonlyArray<number>;
+    /** Raw query string (string overload) — embedded by the runtime before
+     *  compile. Mutually exclusive with `queryVector`. */
+    readonly queryText?: string;
+    /** Distance metric — MUST match the index opclass to accelerate. Default 'cosine'. */
+    readonly distance: VectorDistance_2;
+    /** Per-query HNSW search effort (pgvector `hnsw.ef_search`). Set by `.efSearch(n)`. */
+    readonly ef?: number;
+    /**
+     * Hybrid-search fusion weight in `[0, 1]`. Set by `hybridSearch(...)`
+     * when both an ANN ranking and an FTS filter are present: `0` = pure
+     * FTS, `1` = pure vector, `0.5` = balanced. The runtime fuses the two
+     * rank signals (Reciprocal-Rank-Fusion) weighted by this. Absent for a
+     * plain `nearestNeighbours(...)` query.
+     */
+    readonly alpha?: number;
+}
+
 declare type AnyMixin = MixinDefinition<Record<string, ColumnDefinition<unknown>>>;
 
 declare type AnyTable = Table<string, Record<string, ColumnDefinition<unknown>>, boolean, string>;
@@ -76,6 +119,24 @@ declare type AnyView = View<string, Record<string, ColumnDefinition<unknown>>>;
  */
 export declare const appliedAtValue: (sql: SqlClient.SqlClient, iso: string) => Effect.Effect<string>;
 
+/**
+ * The ids recorded as applied file migrations on THIS database — exported for
+ * the deploy compensation, which compares the set before a run with the set
+ * after it to know which `down`s to run. An absent ledger table reads as an
+ * empty set: a virgin database has applied nothing.
+ */
+export declare const appliedFileMigrationIds: (sql: SqlClient.SqlClient) => Effect.Effect<ReadonlyArray<string>, never>;
+
+/**
+ * The operations the resume ledger says RAN — `started`, `added` or `applied` —
+ * decoded. The deploy compensation reads them for the one thing a schema diff
+ * cannot see: a rename. A column renamed a→b and then reverted by a diff alone
+ * is DROP b + ADD a, which loses the column's values; knowing the rename was
+ * applied lets the undo declare `a` as renamed from `b` and the planner emit
+ * the rename back. An absent ledger table means nothing ran.
+ */
+export declare const appliedLedgerOperations: (sql: SqlClient.SqlClient) => Effect.Effect<ReadonlyArray<PlannedOperation>, never>;
+
 /**
  * One row of `_voltro_migrations` — what the applier writes after a
  * successful plan execution. Same shape exposed via inspect RPC for
@@ -241,6 +302,9 @@ export declare const assessRollingDeployGate: (input: {
 /** Per-row backfill body executed by the migration runner. */
 declare type BackfillFunction<TsType = unknown> = (row: Readonly<Record<string, unknown>>) => TsType | Promise<TsType>;
 
+/** Per-row backfill body executed by the migration runner. */
+declare type BackfillFunction_2<TsType = unknown> = (row: Readonly<Record<string, unknown>>) => TsType | Promise<TsType>;
+
 declare interface BackfillSpec<TsType = unknown> {
     /**
      * `sql`: server-side expression evaluated by `UPDATE ... SET col = <expr>`.
@@ -259,6 +323,24 @@ declare interface BackfillSpec<TsType = unknown> {
     readonly sleepMs?: number;
 }
 
+declare interface BackfillSpec_2<TsType = unknown> {
+    /**
+     * `sql`: server-side expression evaluated by `UPDATE ... SET col = <expr>`.
+     *   Cheapest path — single DB round-trip, transactional, scales to
+     *   millions of rows.
+     * `js`:  per-row JS function. Pulled in batches, transformed locally,
+     *   pushed back. Use when the value can't be expressed in SQL (calls
+     *   to an embedding model, third-party API, library-only helpers).
+     *   10-100× slower than SQL for the same data — the planner warns
+     *   above ~10k rows.
+     */
+    readonly kind: 'sql' | 'js';
+    readonly sql?: Statement.Fragment;
+    readonly fn?: BackfillFunction_2<TsType>;
+    readonly batchSize?: number;
+    readonly sleepMs?: number;
+}
+
 export declare type BootEnvironment = 'dev' | 'staging' | 'prod';
 
 export declare type BootMigrationOutcome = {
@@ -352,6 +434,125 @@ export declare interface BranchRehearsalReport {
     readonly error?: string;
 }
 
+/** What a `refreshChangeCaptureExclusions()` pass changed. */
+declare interface ChangeCaptureExclusionRefresh {
+    /** Excluded before and after — the condition is real and still there. */
+    readonly stillExcluded: ReadonlyArray<string>;
+    /** Excluded before, decodable now — the schema work removed the cause. */
+    readonly readmitted: ReadonlyArray<string>;
+    /** Decodable before, excluded now — the schema work INTRODUCED the cause. */
+    readonly newlyExcluded: ReadonlyArray<string>;
+}
+
+/**
+ * A row-change event emitted by the data store (in-memory) or the CDC
+ * consumer (Postgres logical replication). Drives the reactive engine.
+ */
+declare type ChangeEvent = {
+    readonly table: string;
+    readonly op: 'insert' | 'update' | 'delete';
+    readonly old: Row_2 | null;
+    readonly new: Row_2 | null;
+    /**
+     * Set when the TRANSPORT could not carry this change's row images and they
+     * had to be RECONSTRUCTED. Absent on every ordinary event, which is the only
+     * case where `old`/`new` are the images as they were at commit.
+     *
+     * Postgres caps a `pg_notify` payload at 8000 bytes, and under
+     * `changeStrategy: 'cdc'` the NOTIFY trigger is the SOLE emitter — so a row
+     * that does not fit used to arrive with both images null and every tap
+     * (search index, analytics mirror, cdc-out, row history) dropped it as a
+     * non-event, permanently, with nothing logged. The CDC consumer re-reads the
+     * row by primary key before the event reaches anyone; this field says what
+     * that recovered:
+     *
+     *   - `'rehydrated'` — insert/update. `new` is the row RE-READ from the
+     *     database, so it is the row as it is NOW, not necessarily the image the
+     *     write that fired this event produced (a later write to the same row can
+     *     already have landed). `old` is null — postgres keeps no pre-image once
+     *     the transaction is gone.
+     *   - `'tombstone'` — delete. `old` carries the PRIMARY KEY AND NOTHING ELSE:
+     *     the row is gone, so the pre-image is unrecoverable and the key is the
+     *     whole truth. Enough to REMOVE the row downstream; not a snapshot of what
+     *     was deleted, and anything recording history must not treat it as one.
+     *   - `'unrecovered'` — both images are null. The change is known to have
+     *     happened and its content is not available (no key in the payload, the
+     *     re-read failed, or the row was already gone). Re-read or resync.
+     */
+    readonly oversized?: 'rehydrated' | 'tombstone' | 'unrecovered';
+    /**
+     * How the event reached this process. Absent/'inline' = emitted by this
+     * process's own write path; 'injected' = delivered over a cross-instance
+     * transport (`injectExternalChange` — the broadcast bus or a CDC
+     * consumer). A deployment that must act exactly once per change
+     * FLEET-WIDE combines this with `DataStore.changeScope`: on a
+     * `'local'`-scope store, acting on non-injected events covers each
+     * change exactly once (on its writer); on a `'fleet'`-scope store every
+     * replica sees the full stream (own writes included, all 'injected'),
+     * so the consumer must elect a single worker instead.
+     */
+    readonly origin?: 'inline' | 'injected';
+    /**
+     * The trace this write happened under — the SAME id `auditPlugin` records as
+     * `AuditEvent.traceId` and `voltro logs --trace` resolves.
+     *
+     * This is the correlation bridge. Without it `plugin-row-history` knows WHAT
+     * changed and the audit sink knows WHO called and whether it was refused, and
+     * nothing joins the two. With it, "what did this call touch" is one query.
+     *
+     * Absent means the write had no request behind it: a seed, a `*.startup.tsx`,
+     * a schedule, a workflow step — or an event injected from another replica.
+     * For `origin: 'injected'` the honest answer is the ORIGINATING replica's
+     * trace or nothing at all; stamping the receiving replica's ambient trace
+     * would attribute a remote write to a local request, which is worse than
+     * silence.
+     */
+    readonly traceId?: string;
+    /**
+     * The acting identity behind the write — the same one `audit()` stamps into
+     * `createdBy`/`updatedBy`, so a row's stamp and its change event never
+     * disagree. For an API-key subject that is the person, not the credential;
+     * which key was used is recoverable from the audit row sharing `traceId`.
+     *
+     * `null` = a resolved subject with no acting user (anonymous / system).
+     * `undefined` = no request context at all. The two are different facts.
+     */
+    readonly subjectId?: string | null;
+    /**
+     * The rpc tag of the call that caused this write (`teams.removeSubTeamMember`).
+     *
+     * `traceId` says WHICH call; this says WHAT CALL IT WAS. The difference
+     * matters to anything rendering history for a human: a row diff carries no
+     * intent, and the same delete on a join table is a member removal, a cascade,
+     * or an expiry depending only on who asked. Absent for a write with no
+     * procedure behind it (seed, startup, migration, schedule) — same meaning as
+     * an absent `traceId`.
+     */
+    readonly procedure?: string;
+    /**
+     * The write was made BY AN AGENT acting as `subjectId`, not by that subject
+     * directly. Mirrors `WriteAttribution.via` — see it for why the identity is
+     * NOT changed instead. Absent = a direct call, which is a fact, not a gap.
+     */
+    readonly via?: 'agent';
+};
+
+/**
+ * A proven interruption in a store's change stream.
+ *
+ * Deliberately NOT a list of what was missed. A pub/sub transport keeps no log,
+ * so the missed changes are gone — the only honest recovery is to re-derive
+ * everything downstream, and a consumer that were handed a partial list would be
+ * tempted to patch instead. `reason` is for the log line; the instruction is the
+ * event itself.
+ */
+declare interface ChangeStreamGap {
+    /** Human-readable cause — goes into the refresh's log line. */
+    readonly reason: string;
+    /** Wall-clock ms the stream was known to be down, when it is known. */
+    readonly downForMs?: number;
+}
+
 /** 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. */
@@ -379,6 +580,17 @@ export declare const chunkTables: <T>(xs: ReadonlyArray<T>, n: number) => T[][];
  */
 export declare const classifyRollingDeploySafety: (op: MigrationOperation) => RollingDeploySafety;
 
+/**
+ * Every resume-ledger row, gone — for a caller that has just UNDONE the run
+ * the rows describe. A ledger that outlives the work it recorded would make
+ * the next apply resume a sequence whose effects were reverted. An absent
+ * ledger table is nothing to clear.
+ */
+export declare const clearResumeLedger: (sql: SqlClient.SqlClient) => Effect.Effect<void, never>;
+
+/** A finished deploy — applied, or undone completely — leaves no row. */
+export declare const closeDeploy: (sql: SqlClient.SqlClient, id: string) => Effect.Effect<void, unknown>;
+
 declare interface ColumnDefinition<TsType, Type extends ColumnType = ColumnType, HasDefault extends boolean = boolean> {
     readonly type: Type;
     readonly nullable: boolean;
@@ -801,351 +1013,1423 @@ declare interface ColumnDefinition<TsType, Type extends ColumnType = ColumnType,
     readonly __tsType?: TsType;
 }
 
-/**
- * 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`.
- */
-export declare interface ColumnSnapshot {
-    readonly name: string;
-    readonly type: ColumnType;
+declare interface ColumnDefinition_2<TsType, Type extends ColumnType_2 = ColumnType_2, HasDefault extends boolean = boolean> {
+    readonly type: Type;
     readonly nullable: boolean;
     readonly unique: boolean;
     readonly hasDefault: boolean;
+    /* Excluded from this release type: __hasDefault */
     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;
-    };
+     * Application-side default factory. When set, the MutationStore
+     * wrapper evaluates this at insert-time IF the caller omits the
+     * column from the row. Distinct from `defaultValue` (which is a
+     * literal landed in the DDL DEFAULT clause). Functions can do
+     * things DDL can't — `() => crypto.randomUUID()`,
+     * `() => process.env.REGION`. NOT emitted in DDL.
+     */
+    readonly defaultFactory?: () => unknown;
     /**
-     * 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.
+     * Application-side computed value. Re-evaluated on INSERT and on
+     * UPDATE from the rest of the row (after merging defaults on insert;
+     * after merging the patch over the existing row on update). The
+     * return value overwrites whatever the caller passed for this column.
+     * NOT emitted in DDL.
      *
-     * 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).
+     * Example: `slug: text().computed(row => slugify(row.title))`.
      *
-     * 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`.
+     * If the computed function reads a column the row doesn't carry,
+     * it gets `undefined` — handle that in the function.
      */
-    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';
-    };
-    /** 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;
-    }>;
+    readonly computed?: (row: Readonly<Record<string, unknown>>) => unknown;
+    readonly onUpdate?: 'now' | (() => unknown);
+    readonly references?: () => TableLike_2;
     /**
-     * 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`.
+     * Physical/TypeScript representation of a foreign key. The default is
+     * `text`, matching Voltro's default TypeID primary key. `numeric` is for a
+     * target declared with `id({ scheme: 'numeric' })`; it renders as the
+     * dialect's 64-bit integer type and decodes as a JavaScript number.
      */
-    readonly precision?: number;
-    readonly scale?: number;
+    readonly referenceStorage?: 'text' | 'numeric';
+    /** Target key; defaults to the framework convention `id`. */
+    readonly referenceColumn?: string;
     /**
-     * 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).
+     * Cascade-on-delete behavior for a `reference()` column. Default
+     * `'restrict'` — Postgres / MySQL / MariaDB / MSSQL / SQLite all block
+     * the parent delete when child rows still point at it. Pre-release
+     * choice: `'restrict'` is safer than `'cascade'` (deleting a user
+     * shouldn't silently nuke 100k posts) and the explicit `'cascade'`
+     * opt-in is one keystroke when the parent-child relationship genuinely
+     * is owned-lifecycle.
      */
-    readonly idScheme?: {
-        readonly kind: string;
-    };
+    readonly onDelete?: 'cascade' | 'restrict' | 'setNull' | 'noAction';
     /**
-     * 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.
+     * Cascade-on-update — default `'noAction'`. Rarely used in practice.
+     * Named `refOnUpdate` (not `onUpdate`) to avoid colliding with the
+     * existing column-level `onUpdate('now' | …)` trigger field which
+     * has nothing to do with FK semantics.
      */
-    readonly rawDdl?: string;
+    readonly refOnUpdate?: 'cascade' | 'restrict' | 'setNull' | 'noAction';
     /**
-     * `.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.
+     * What the RUNTIME does to this column's rows when the referenced row is
+     * SOFT-deleted (`deletedAt` set) — set by `reference(…, { onSoftDelete })`.
+     * A foreign key never sees a soft delete (it is an UPDATE), so `onDelete`
+     * cannot express it; the store's post-commit change channel enforces this
+     * one instead, the way `pluginRef` orphan rules are enforced.
      */
-    readonly generatedAs?: {
-        readonly expr: string;
-        readonly stored: boolean;
-    };
+    readonly refOnSoftDelete?: 'cascade' | 'setNull';
     /**
-     * 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`.
+     * Auto-create a B-tree index on this FK column. Default `true` — FK
+     * columns are nearly always read-by, and the lookup cost of a missing
+     * index dwarfs the write cost of an unnecessary one. Opt-out
+     * (`{ index: false }`) for the rare table where the parent-child set
+     * is small enough that a full-scan beats the index-maintenance
+     * overhead.
      */
-    readonly sensitive?: {
-        readonly class: string;
-    };
+    readonly fkAutoIndex?: boolean;
     /**
-     * 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.
+     * This id-shaped scalar names something outside the local relational graph.
+     * Set by `.externalId()` so schema audits do not guess a local FK from the
+     * column name. Metadata only; it emits no constraint or DDL.
      */
-    readonly safe?: boolean;
+    readonly externalId?: boolean;
+    readonly jsonType?: unknown;
     /**
-     * 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).
+     * Closed value set, set by `text().oneOf([...])`. When present:
      *
-     * 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 row type narrows from `string` to the union of literals.
+     *   - The Postgres migration emitter adds a `CHECK (col IN (...))`
+     *     constraint so a bad value is rejected by the DB regardless
+     *     of which client wrote it.
+     *   - The in-memory data store can validate at insert time
+     *     (helps catch test-data drift early).
      *
-     * 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.
+     * For Postgres-native ENUM types: not used here. We treat the
+     * underlying column as `text` and lean on CHECK — that keeps adding /
+     * removing values a one-statement migration instead of the
+     * three-statement dance Postgres ENUMs need (`ALTER TYPE … ADD VALUE`
+     * + rewrite, or `ALTER TYPE … RENAME VALUE`).
      */
-    readonly vectorDim?: number;
-    readonly vectorPrecision?: 'float32' | 'half';
-    readonly arrayElement?: ColumnType;
-    readonly enumName?: string;
-    readonly enumValues?: ReadonlyArray<string>;
+    readonly oneOf?: 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.
+     * Bounded text length, set by `text().maxLength(n)`. When present the
+     * migrator emits `VARCHAR(n)` (postgres / mysql / mariadb) / `NVARCHAR(n)`
+     * (mssql) instead of the unbounded `TEXT` / `LONGTEXT` default. The point
+     * is index-ability: a bounded column can back a plain BTREE UNIQUE or
+     * composite index, where an unbounded text column can only take a HASH
+     * long-unique constraint or a prefix index. `n` is a character count.
      */
-    readonly spatial?: {
-        readonly kind: 'geography' | 'geometry';
-        readonly geomKind: string;
-        readonly srid: number;
-    };
-}
-
-declare type ColumnType = 'id' | 'text' | 'integer' | 'real' | 'decimal' | 'bigint' | 'boolean' | 'timestamp' | 'date' | 'json' | 'bytes' | 'reference' | 'vector' | 'enum' | 'array' | 'interval' | 'raw';
-
-/**
- * Build a `SchemaSnapshot` from an array of `TableLike` declarations.
- * Caller is responsible for passing the FULL set of tables (user-
- * declared + framework). The fingerprint over this snapshot is what the
- * boot-time prod check compares against `_voltro_migration_plans`.
- */
-export declare const declaredSnapshot: (tables: ReadonlyArray<TableLike>, dialect?: DialectId) => SchemaSnapshot;
-
-/** The NOTIFY channel a schema emits on when none is configured. */
-export declare const DEFAULT_CDC_CHANNEL = "framework_changes";
-
-/**
- * `DEFAULT <expr>` for an array-valued default.
- *
- * Postgres is the only dialect with native arrays, so a `array()` column there
- * takes an array literal (`'{a,b}'::text[]`); every other dialect stores the
- * value as JSON/TEXT and takes the json form. A default on a `json()` column
- * always takes the json form — the array is the VALUE, not the storage.
- */
-export declare const defaultArrayClause: (value: ReadonlyArray<unknown>, column: ColumnDefinition<unknown>, dialect: DialectId) => string;
-
-export declare const defaultClause: (column: ColumnDefinition<unknown>, dialect: DialectId) => string | null;
-
-/**
- * `DEFAULT <expr>` for a plain-object json default, per dialect's json-column
- * type. Single source for the auto-migrate (`defaultClause`) AND declarative-
- * applier paths so the two can't drift (the introspected form must round-trip
- * against `normalizeDefault`, so the emit shape matters on both sides).
- */
-export declare const defaultJsonClause: (value: object, dialect: DialectId) => string;
-
-export declare const describeOutcome: (outcome: BootMigrationOutcome, dialectId: string) => string;
-
-/**
- * Parse `VOLTRO_DESTRUCTIVE_OK`.
- *
- * `1` / `true` acknowledges every lossy op in the run. A comma-separated list
- * acknowledges only those TABLES — which is the form somebody wants far more
- * often, and its absence was a real complaint: a plan carrying one intended drop
- * plus three other lossy ops had no way to say yes to the one. `1` said yes to
- * all four, and the alternative was a hand-written DROP migration, which the
- * framework's own upgrade note warns against.
- *
- * `undefined` = not set at all.
- */
-export declare const destructiveScope: (raw: string | undefined) => {
-    readonly kind: "all";
-} | {
-    readonly kind: "tables";
-    readonly tables: ReadonlySet<string>;
-} | undefined;
-
-/**
- * Compare declared reactivity against the triggers actually installed.
- *
- * Postgres only — it is the one dialect where reactivity is carried by DDL. The
- * binlog and Change Tracking readers are configured at runtime from the same
- * in-memory table list the schema produced, so they cannot drift from it.
- */
-export declare const detectReactiveTriggerDrift: (sql: SqlClient.SqlClient, tables: ReadonlyArray<{
-    readonly tableName: string;
-    readonly isReactive?: boolean;
-}>, 
-/** 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>;
-
-/** Dialect IDs the framework supports. */
-declare type DialectId = 'postgres' | 'mysql' | 'mariadb' | 'mssql' | 'sqlite' | 'turso';
-
-/**
- * Output of `voltro db drift`: compares the live DB's introspected
- * schema against the last applied fingerprint in `_voltro_migrations`.
- *
- * `isDrifted: false` is the happy path. A drift report names the
- * concrete divergences so the operator can either reconcile in code or
- * via a corrective migration.
- */
-export declare interface DriftReport {
-    readonly isDrifted: boolean;
-    readonly lastAppliedFingerprint?: string;
-    readonly liveFingerprint: string;
-    readonly divergences: ReadonlyArray<{
-        readonly kind: 'unexpected' | 'missing';
-        readonly description: string;
-    }>;
-}
-
-/**
- * Per-branch refinement passed to `.with({ relation: { ... } })`.
- *
- * `true` is the zero-config shorthand — equivalent to `{}`. Otherwise
- * each branch can carry its own `where` / `orderBy` / `limit` /
- * `offset` / nested `with`, so `users.with({ posts: { limit: 10,
- * orderBy: 'createdAt' } })` works without dropping into a sub-query
- * builder.
- *
- * Untyped at runtime: the QueryDescriptor is the boundary between the
- * typed builder API and the dialect-agnostic JoinCompiler. End-user
- * types live one layer up in the typed `.with()` method on `Query`.
- */
-declare interface EagerLoadSpec {
-    readonly where?: Predicate;
-    readonly orderBy?: ReadonlyArray<OrderClause>;
+    readonly maxLength?: number;
     /**
-     * Per-parent cap on the relation. `{ limit: 10 }` returns up to 10
-     * rows FOR EACH parent — same semantics as Drizzle / Prisma /
-     * Hibernate. This matches what users actually mean when they write
-     * "the 10 latest posts" inside `users.with({ posts: { limit: 10 } })`.
-     *
-     * The SQL stores express this natively as a `LIMIT` clause in a
-     * correlated subquery (postgres / sqlite / mysql / mariadb) or
-     * via `TOP N` inside `FOR JSON PATH` (mssql) when the JSON-agg path
-     * is active. The walker fallback post-buckets the batch fetch and
-     * slices each bucket.
+     * Raw SQL `CHECK` expressions, set by `column.check(expr)` (accumulates
+     * — call it more than once for multiple checks). Each emits an inline
+     * `CHECK (<expr>)` on the column. DB-enforced regardless of client,
+     * unlike app-level `table().validate(Schema)`. The developer owns the
+     * expr's cross-dialect portability. Distinct from `oneOf` (which emits
+     * its own `CHECK (col IN (...))`).
      */
-    readonly limit?: number;
-    /** Per-parent offset. Only meaningful with `limit`. */
-    readonly offset?: number;
-    readonly with?: WithSpec;
+    readonly checks?: ReadonlyArray<string>;
     /**
-     * Project the JUNCTION row's own columns into a `manyToMany` eager result.
-     *
-     * `true` takes every junction column; an array takes only those named. The
-     * values land under `_junction` on each target row:
+     * DB-level generated column. Set by `.generatedAs(expr, { stored })`.
      *
-     *     projects.with({ teams: { junction: ['role', 'addedAt'] } })
-     *     // → team._junction.addedAt
+     * Distinct from `.computed(row => ...)` (application-time, eval'd
+     * at insert) — generated columns are computed by the DB engine
+     * itself. Visible to raw SQL, kept consistent on UPDATE without
+     * re-stamping, can be indexed (combine with `.expressionIndex`).
      *
-     * Nested rather than merged onto the target row, deliberately: a junction and
-     * its target routinely share column names (`createdAt` is the obvious one),
-     * and merging would silently overwrite real target data with membership data.
-     * A name collision that corrupts a row is worse than one extra level.
+     * `stored: true`  → `GENERATED ALWAYS AS (expr) STORED` (Postgres/
+     *                    MySQL/MariaDB/SQLite; PERSISTED on MSSQL).
+     *                    Disk-resident, indexable.
+     * `stored: false` → VIRTUAL on MySQL/MariaDB/SQLite. Recomputed on
+     *                    read, no disk cost, NOT indexable. Postgres
+     *                    has no VIRTUAL — falls back to STORED with a
+     *                    boot warning.
      *
-     * Why this exists: junction tables carrying meaningful columns — a role, a
-     * joined-at stamp, a permission tier — are the rule rather than the
-     * exception, and without this an eager load could FILTER on them
-     * (`onJunction`) but never return them, so any relation with real membership
-     * data had to stay a hand-written join. The junction rows were already being
-     * fetched in full to resolve the target ids; this stops throwing them away.
+     * The expression is emitted verbatim (caller-quoted). MUST
+     * reference only OTHER columns of the same row — there's no way
+     * to reference the subject/tenant context from a generated column.
+     * Use `.computed(row => ...)` for context-aware values.
      */
-    readonly junction?: true | ReadonlyArray<string>;
+    readonly generatedAs?: {
+        readonly expr: string;
+        readonly stored: boolean;
+    };
     /**
-     * Filter a `manyToMany` eager branch on the THROUGH-table's columns.
-     * The predicate is evaluated against the junction row, not the target
-     * row — e.g. for `users.with({ organizations: { onJunction: eq('role',
-     * 'admin') } })` it keeps only the memberships where `role = 'admin'`,
-     * so the loaded `organizations` are exactly the orgs the user is an
-     * admin of.
+     * Postgres-native ENUM type binding, populated when the column is
+     * built from `dbEnum(...).column()`. Distinct from `oneOf`:
      *
-     * Compiles into the correlated subquery's WHERE alongside the
-     * source-key correlation, qualified to the junction-table alias.
-     * Ignored on `one` / `many` branches (no junction table exists).
-     */
-    readonly onJunction?: Predicate;
-}
+     *   - On Postgres, this column's SQL type is the user-defined ENUM
+     *     (`status order_status` not `status text CHECK (...)`).
+     *   - On MySQL / MariaDB, emits a native `ENUM('a','b','c')` column.
+     *   - On MSSQL / SQLite, falls back to TEXT + CHECK (same shape as
+     *     `oneOf` — distinct constraint name so the diff can tell them
+     *     apart).
+     *
+     * Migration ops `add-enum-value` / `rename-enum-value` apply natively
+     * on Postgres (cheap `ALTER TYPE … ADD VALUE`); MySQL needs a column
+     * rewrite (`MODIFY col ENUM(...)`); MSSQL / SQLite recreate the CHECK.
+     */
+    readonly enumName?: string;
+    readonly enumValues?: ReadonlyArray<string>;
+    /**
+     * Element type for `array(...)` columns. Populated only when
+     * `type === 'array'`. The framework emits the DB-native array
+     * type on postgres (`text[]`, `integer[]`, etc.) and falls back
+     * to a JSON column on other dialects.
+     */
+    readonly arrayElement?: ColumnType_2;
+    /**
+     * Field-level encryption flag, set by `.encrypted()`. When `true`
+     * the runtime's store middleware encrypts the value on write and
+     * decrypts on read via the registered field cipher (AES-256-GCM, keyed
+     * from `VOLTRO_FIELD_ENCRYPTION_KEY` through the Secrets-Resolver — the
+     * framework registers it on both boot paths; `voltro dev` mints the key).
+     * The stored column is an opaque `enc:v2:…` string — bound by GCM's
+     * additional authenticated data to its table, column and row
+     * (`FieldBinding`), so a ciphertext copied into another row or column
+     * does not decrypt there — and the DB type stays `text`. A row written
+     * while encryption is active can't be
+     * read back without the key — losing the key loses the data, by
+     * design. Boot refuses if an `.encrypted()` column is declared but
+     * no cipher is registered.
+     */
+    readonly encrypted?: boolean;
+    /**
+     * Wire-exposure flag, set by `.serverOnly()`. When `true` the column is
+     * SERVER-INTERNAL: server code reads it normally (an auth middleware verifying
+     * a `keyHash`, say), but it must NEVER be serialized to a client. This is the
+     * EXPOSURE axis, orthogonal to `.encrypted()` (which is storage-at-rest): a
+     * column can be either, both, or neither — a hash you never ship is serverOnly
+     * but not encrypted; a private note the owner may read is encrypted but not
+     * serverOnly. The default is exposed to BOTH server and client; `.serverOnly()`
+     * opts a column OUT of the client. The table-aware read paths (`crud.*`) strip
+     * it automatically, and an audit flags a wire-reachable query whose `source`
+     * table carries a serverOnly column that its output declares. What that audit
+     * COSTS is per command — see `serverOnly()` below for the matrix.
+     */
+    readonly serverOnly?: boolean;
+    /**
+     * Field-level read scopes, set by `.readableBy(...scopes)`. A NON-EMPTY list
+     * of scope strings; the column is stripped from wire OUTPUT for any subject
+     * that holds NONE of them, and present for a subject holding at least ONE.
+     * This is the graded middle of the exposure axis: `.serverOnly()` hides a
+     * column from EVERYONE on the wire, a plain column is visible to everyone,
+     * and `.readableBy('billing:read')` is visible only to callers scoped for it.
+     *
+     * The scope strings are the SAME vocabulary as `guards:` / `ctx.access` — they
+     * are checked against the subject's EFFECTIVE scope set (raw subject scopes ∪
+     * any rbac role-derived scopes), and the `admin:full` bypass sees every
+     * `.readableBy()` column, exactly as it satisfies every guard. Empty here is a
+     * declaration error (`.readableBy()` with no scope would mean "nobody" — use
+     * `.serverOnly()` for that), so the field is never present as `[]`.
+     *
+     * Orthogonal to `.encrypted()` (storage-at-rest) and to `.sensitive()` /
+     * `.safe()` (export-time masking): this is purely the WIRE-exposure axis.
+     */
+    readonly readableBy?: ReadonlyArray<string>;
+    /**
+     * CRDT-managed marker, set by the `crdtText()` column constructor. When `true`
+     * the column holds an ENCODED CRDT state (opaque bytes — a Yjs update blob
+     * behind `@voltro/local-first`'s swappable backend) rather than a plain value.
+     *
+     * It changes NOTHING about the column's DDL or how the declarative differ
+     * treats it: the storage type is `bytes` (BYTEA / BLOB / LONGBLOB /
+     * VARBINARY), a normal storable type, and the planner compares it structurally
+     * like any other `bytes` column — introspection never reports this flag, and
+     * `sameColumnShape` never reads it, so a `crdtText()` column round-trips
+     * through a plan with zero churn (no phantom re-plan).
+     *
+     * What it DOES drive lives above the DDL, in the runtime write path: the
+     * MutationStore reads it (via the SchemaRegistry) to run the AUTHORITATIVE
+     * server-side merge on write — an incoming encoded update is folded into the
+     * stored state with `mergeCrdtStates` before the row is written, so two
+     * concurrent clients converge. Orthogonal to every other flag here; a CRDT
+     * column is just `bytes` with server-merge semantics.
+     */
+    readonly crdtManaged?: boolean;
+    /**
+     * Optimistic-concurrency marker, set by `.version()`.
+     *
+     * The column the store INCREMENTS on every update, and the one an update may
+     * carry an expectation of. Two clients that read the same row and both write
+     * it are the normal case, not an exotic one — and without this the second
+     * write silently wins, which is the shape of every "my change disappeared"
+     * report ever filed.
+     *
+     * A TIMESTAMP cannot do this job. Two writes in the same millisecond are
+     * indistinguishable, and across replicas the clocks disagree; this repo has
+     * already lost rows to exactly that (an analytics sink dropped 7 of 40 events
+     * written in the same millisecond as the query bounding them). A monotonic
+     * integer has neither problem, and it also answers the other half of the
+     * question — which of two copies is NEWER — without consulting a clock.
+     */
+    readonly versionColumn?: boolean;
+    /**
+     * Data-sensitivity classification, set by `.sensitive(class)`. Declares that
+     * this column holds personal / sensitive data of a given CLASS (`'email'`,
+     * `'fullName'`, `'phone'`, `'secret'`, …). It changes nothing at runtime or
+     * in the DDL — it is metadata read by the export layer (`voltro data export
+     * --profile …`) to decide how to pseudonymise / anonymise the column when
+     * copying prod data to a lower environment. The class picks the
+     * format-preserving fake transform. Orthogonal to `.encrypted()` (which
+     * protects at rest): an encrypted column is decrypted on read, so it is
+     * PLAINTEXT at export time and is treated as sensitive automatically. See
+     * `.safe()` for the other half of the fail-closed classification.
+     */
+    readonly sensitive?: {
+        readonly class: string;
+    };
+    /**
+     * Reviewed-safe marker, set by `.safe()`. Declares that this column holds NO
+     * personal / sensitive data and may be copied verbatim to a lower
+     * environment. It exists so masking can be FAIL-CLOSED: under a masking
+     * profile, a column that is neither `.sensitive()` nor `.safe()` blocks the
+     * export until it is consciously classified — so a newly-added column can
+     * never silently leak. Metadata only; no runtime/DDL effect.
+     */
+    readonly safe?: boolean;
+    /**
+     * Fixed-point precision (total significant digits), set by
+     * `decimal(precision, scale)` / `numeric(precision, scale)`. Populated
+     * only when `type === 'decimal'`. Drives the DDL size —
+     * `NUMERIC(p,s)` (postgres) / `DECIMAL(p,s)` (mysql/mariadb/mssql) —
+     * so a money column round-trips at full precision. On sqlite/turso
+     * (no fixed-point type) the column is `NUMERIC` affinity and the value
+     * carries as a TEXT string, so `p`/`s` are informational only there.
+     */
+    readonly precision?: number;
+    /**
+     * Fixed-point scale (digits after the decimal point), set by
+     * `decimal(precision, scale)`. Populated only when `type === 'decimal'`.
+     * MUST be `<= precision`. See {@link ColumnDefinition.precision}.
+     */
+    readonly scale?: number;
+    /**
+     * Vector dimensionality. Populated only when `type === 'vector'`.
+     * The migration emitter uses it to size the column DDL —
+     * `VECTOR(n)` on postgres (pgvector) + MariaDB 11.7+ / MySQL 9,
+     * and a sized fallback (`VARBINARY(MAX)` / `BLOB`) elsewhere. The
+     * HNSW index emitter + the `vectorEmbedding()` mixin also read it.
+     */
+    readonly vectorDim?: number;
+    /**
+     * Vector storage precision. Populated only when `type === 'vector'`.
+     * `'float32'` (default) emits `VECTOR(n)`; `'half'` emits pgvector's
+     * `HALFVEC(n)` (half the bytes, marginally lower recall). MariaDB /
+     * MySQL have no half type — the emitter upcasts to `VECTOR(n)` there.
+     */
+    readonly vectorPrecision?: 'float32' | 'half';
+    /**
+     * Verbatim DDL fragment for a `raw(ddl)` escape-hatch column.
+     * Populated only when `type === 'raw'`. The migration emitter returns
+     * this string unchanged as the column's SQL type on EVERY dialect —
+     * the fragment is the single source of truth for the column's type,
+     * nullability, and default. Because of that, `.nullable()`,
+     * `.default()`, and `.unique()` are rejected at declaration time on a
+     * `raw` column (two sources of truth would drift).
+     */
+    readonly rawDdl?: string;
+    /**
+     * Spatial column metadata (`@voltro/plugin-postgis`'s `geography()` /
+     * `geometry()`). The row TYPE stays `text` (handlers read/write WKT/EWKT
+     * strings); this drives the migration emitter to produce real
+     * `geography(Point,4326)` / `geometry(Polygon,4326)` DDL on postgres +
+     * `CREATE EXTENSION IF NOT EXISTS postgis`. PostGIS is postgres-only, so
+     * the emitter THROWS on any other dialect (the documented fail-loud guard)
+     * rather than silently emitting a broken TEXT column. Generic on purpose —
+     * the postgis plugin is the only producer, but core owns the DDL hook (the
+     * same pattern as `vectorDim` / `enumName`) so the column type is real, not
+     * a fabricated marker nothing consumes.
+     */
+    readonly spatial?: {
+        /** PostGIS base type. */
+        readonly kind: 'geography' | 'geometry';
+        /** Geometry subtype: `Point` / `LineString` / `Polygon` / … */
+        readonly geomKind: string;
+        /** Spatial reference id (e.g. 4326 = WGS-84 lat/lon). */
+        readonly srid: number;
+    };
+    /**
+     * Captured `id()` options. Populated only on the primary-key column
+     * (`type: 'id'`). At column-construction time the `prefix` for typeid
+     * may still be missing — `table()` resolves it against the table name
+     * and the resolved scheme lands on `idScheme` below.
+     */
+    readonly idSchemeInput?: IdSchemeInput_2;
+    /**
+     * Fully-resolved id scheme for the primary-key column. Set by
+     * `table()` after walking the field map; downstream code (DDL emit,
+     * SchemaRegistry, MutationStore auto-inject) reads this exclusively.
+     */
+    readonly idScheme?: IdScheme_2;
+    /**
+     * Migration backfill expression. Populated by `.backfill(sqlOrFn, opts?)`.
+     *
+     * The migration planner reads this when ADD COLUMN + NOT NULL on a
+     * populated table would otherwise be classified `needs-backfill` →
+     * with a backfill declared, the planner emits a three-step plan
+     * (ADD COLUMN nullable → UPDATE via expression → SET NOT NULL) inside
+     * one transaction (or one forward-roll group on mysql/mariadb).
+     *
+     * Has zero effect at insert/query time — pure planner metadata.
+     */
+    readonly backfill?: BackfillSpec_2<TsType>;
+    /**
+     * Rename marker. Populated by `.renamedFrom('oldName')`.
+     *
+     * The migration planner sees `oldName` missing + this column present
+     * + the `renamedFrom` annotation → classifies as RENAME instead of
+     * DROP+ADD (which would lose data). The annotation stays in the code
+     * until `_voltro_migrations` records that the rename was applied in
+     * the env(s) the developer cares about; removing it earlier yields
+     * a clear refuse-to-plan message rather than a silent drop.
+     */
+    readonly renamedFrom?: string;
+    /**
+     * Dropped marker. Set by the standalone `dropped()` helper at the
+     * column's field-map slot. The planner treats the column as
+     * intentionally going away — emits a `lossy` op that's auto-allowed
+     * (no `VOLTRO_DESTRUCTIVE_OK=1` required) because the developer
+     * declared intent explicitly in the schema diff.
+     *
+     * The drop-marker stays for one applied migration cycle, then the
+     * developer removes the field map entry entirely.
+     */
+    readonly dropped?: boolean;
+    /**
+     * Type-narrowing marker. Populated by `.narrowedFrom(from, { using })`.
+     *
+     * The planner uses `from` to know what the live-DB column type was
+     * before this migration, and `using` as the dialect-cast expression
+     * when the conversion isn't implicit (e.g. `text → integer` on
+     * postgres requires `USING col::integer`).
+     */
+    readonly narrowedFrom?: NarrowedFromSpec_2;
+    /**
+     * Extended unique-constraint metadata. Populated by
+     * `.unique({ dedup })`. The legacy boolean `unique` flag above
+     * stays as the canonical "is this column unique?" signal — `uniqueSpec`
+     * carries the planner-only metadata (dedup strategy) so existing
+     * runtime consumers don't need to learn the new shape.
+     */
+    readonly uniqueSpec?: UniqueSpec_2;
+    /**
+     * Orphan-handling policy used when adding a foreign key to a
+     * populated column. Mirrors the `ReferenceOptions.orphanPolicy` API:
+     *
+     * - `'fail'`   (default) → bare ADD CONSTRAINT (`needs-backfill`, applies);
+     *                the DB rejects it if an existing row is an orphan — exactly
+     *                like tightening a column to NOT NULL. NOT blocked: the
+     *                planner is pure (no row counts), so it can't tell a clean /
+     *                empty table from one with orphans.
+     * - `'null'`  → planner emits `UPDATE … SET col = NULL` before adding FK
+     * - `'delete'` → planner emits `DELETE FROM child WHERE …` before adding FK
+     *
+     * Has no runtime semantics — purely planner metadata.
+     */
+    readonly orphanPolicy?: 'fail' | 'null' | 'delete';
+    /**
+     * Phantom field so TypeScript can infer the row type at the column level.
+     * Never read at runtime.
+     */
+    readonly __tsType?: TsType;
+}
+
+/** 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 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`.
+ */
+export 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;
+    };
+}
+
+declare type ColumnType = 'id' | 'text' | 'integer' | 'real' | 'decimal' | 'bigint' | 'boolean' | 'timestamp' | 'date' | 'json' | 'bytes' | 'reference' | 'vector' | 'enum' | 'array' | 'interval' | 'raw';
+
+declare type ColumnType_2 = 'id' | 'text' | 'integer' | 'real' | 'decimal' | 'bigint' | 'boolean' | 'timestamp' | 'date' | 'json' | 'bytes' | 'reference' | 'vector' | 'enum' | 'array' | 'interval' | 'raw';
+
+declare interface DataStore {
+    /**
+     * Execute a typed query descriptor and return matching rows.
+     *
+     * Deliberately NOT generic: `DataStore` is the driver SPI, implemented by
+     * every dialect store and its transactional / namespace views. Threading a
+     * phantom row type through all of them would be pure churn — they genuinely
+     * do return untyped rows off the wire. The row type is re-applied one layer
+     * up, on `FluentStore.query`, which is what handlers actually call.
+     */
+    query(descriptor: QueryDescriptor_2): Promise<ReadonlyArray<Row_2>>;
+    /** Insert a row. Emits an insert ChangeEvent (deferred if inside `transactional()`). */
+    insert(table: string, row: Row_2): Promise<Row_2>;
+    /**
+     * Insert many rows in ONE statement and return the inserted rows.
+     *
+     * A single multi-row `INSERT … VALUES (…),(…)` per dialect — one
+     * round-trip regardless of row count, instead of N `insert()` calls.
+     *
+     * Emits ONE `insert` ChangeEvent PER row (deferred if inside
+     * `transactional()`), so reactive subscribers see each new row's
+     * delta exactly as they would from N single inserts.
+     *
+     * Cross-dialect:
+     *   - postgres / sqlite / mariadb 10.5+: `INSERT … VALUES (…),(…) RETURNING *`
+     *   - mssql:                              `INSERT … OUTPUT INSERTED.* VALUES (…),(…)`
+     *   - mysql:                              multi-row `INSERT`, then re-select by id
+     *   - memory store:                       loop + per-row emit
+     *
+     * An empty `rows` array is a no-op that returns `[]` (no statement, no events).
+     */
+    insertMany(table: string, rows: ReadonlyArray<Row_2>): Promise<ReadonlyArray<Row_2>>;
+    /**
+     * In-place JSON merge: set `value` at `path` inside the JSON column
+     * (`path` is the column name, optionally with a nested dot-path, e.g.
+     * `'metadata'` or `'metadata.theme'`). Reads-modifies-writes the
+     * single row identified by `pk` and returns the post-image (or `null`
+     * when the row doesn't exist). Emits an `update` ChangeEvent (deferred
+     * if inside `transactional()`).
+     *
+     * Cross-dialect (server-side merge, no round-trip read):
+     *   - postgres:        `jsonb_set(col, '{path}', value)` (top-level: `col || value`)
+     *   - mysql / mariadb: `JSON_SET(col, '$.path', value)`
+     *   - mssql:           `JSON_MODIFY(col, '$.path', value)`
+     *   - sqlite:          `json_set(col, '$.path', value)`
+     *   - memory store:    read-modify-write the JS object in place
+     *
+     * `additionalPatch` assigns other columns in the SAME row update (e.g. an
+     * automatic timestamp). Undefined values are omitted; null is explicit.
+     * Cannot rewrite the primary key or replace the JSON column being patched.
+     */
+    patchJson(table: string, primaryKey: RowKey, path: string, value: unknown, additionalPatch?: Readonly<Record<string, unknown>>): Promise<Row_2 | null>;
+    /** Patch a row by primary key. Emits an update ChangeEvent (deferred if inside `transactional()`).
+     *  Returns the post-image. */
+    update(table: string, primaryKey: RowKey, patch: Readonly<Record<string, unknown>>): Promise<Row_2 | null>;
+    /**
+     * Bulk update — apply `patch` to every row in `table` matching the
+     * `where` predicate (Q9). The predicate is a `Predicate` AST (the
+     * same shape `.where()` uses on queries) and CAN carry sub-queries
+     * via inSubquery / exists.
+     *
+     * Returns the number of rows updated. Emits one `update`
+     * ChangeEvent per affected row (deferred if inside `transactional()`),
+     * so reactive subscribers see each row's delta — at the cost of N
+     * events instead of one.
+     *
+     * Cross-dialect:
+     *   - SQL stores: `UPDATE <table> SET <patch> WHERE <pred>` in one
+     *     statement; the per-row events come from a fan-out the store
+     *     handles (postgres uses RETURNING; the others read-then-update).
+     *   - memory store: linear filter + per-row update + emit
+     */
+    updateMany(table: string, patch: Readonly<Record<string, unknown>>, options: {
+        where: Predicate;
+    }): Promise<number>;
+    /** Delete a row by primary key. Emits a delete ChangeEvent (deferred if inside `transactional()`). */
+    delete(table: string, primaryKey: RowKey): Promise<boolean>;
+    /**
+     * Bulk delete — remove every row in `table` matching the `where`
+     * predicate. The predicate is a `Predicate` AST (the same shape
+     * `.where()` uses on queries) and CAN carry sub-queries via
+     * inSubquery / exists. The set-based counterpart to `updateMany`.
+     *
+     * This is a HARD delete: it removes the row regardless of whether the
+     * table carries `softDelete()`. (Soft-delete is a write-time concern
+     * the `ctx.store` middleware layers on the keyed `delete()` / the
+     * fluent `delete(...).soft()` builder — `deleteMany` is the low-level
+     * physical remove, mirroring `updateMany`'s lack of mixin handling.)
+     *
+     * Returns the number of rows deleted. Emits one `delete` ChangeEvent
+     * per removed row (deferred if inside `transactional()`), each
+     * carrying the removed row's old-image as `old` — so reactive
+     * subscribers see each row leave, at the cost of N events instead of
+     * one.
+     *
+     * Cross-dialect:
+     *   - postgres / sqlite / mariadb 10.0+: `DELETE FROM <table> WHERE
+     *     <pred> RETURNING *` in one statement; the per-row old-image
+     *     events come from the RETURNING rows.
+     *   - mssql: `DELETE FROM <table> OUTPUT DELETED.* WHERE <pred>` —
+     *     OUTPUT DELETED.* gives the old-images in one statement.
+     *   - mysql (8.x): no `RETURNING` on DELETE — SELECT the matching
+     *     rows FIRST (for the old-image fan-out), then one DELETE.
+     *   - memory store: linear filter + per-row delete + emit.
+     */
+    deleteMany(table: string, options: {
+        where: Predicate;
+    }): Promise<number>;
+    /**
+     * Upsert: INSERT a row, and on conflict over `conflictColumns`,
+     * UPDATE the conflicting row instead.
+     *
+     * `conflictColumns` declares which column set defines a conflict.
+     * Most often a single column with a UNIQUE constraint (`['email']`)
+     * or a composite UNIQUE (`['orgId', 'slug']`).
+     *
+     * `update` controls what happens on conflict:
+     *   - omitted / `undefined`     → update every column from the input row
+     *     (matches Drizzle's `onConflictDoUpdate({ target, set: input })` shorthand)
+     *   - `ReadonlyArray<string>`   → update only these columns from the input row
+     *   - `(existing) => Patch`     → compute a patch from the conflicting row;
+     *     useful for "increment counter" semantics
+     *
+     * `updateValues` adds conflict-only assignments without changing the insert
+     * row. See `UpsertOptions` for precedence and omission rules.
+     *
+     * Returns the FINAL row (post-insert OR post-update) so callers can
+     * read the assigned PK without a separate query.
+     *
+     * Emits an `insert` ChangeEvent on the insert path and an `update`
+     * ChangeEvent on the conflict path, so reactive subscribers see a
+     * single delta regardless of which branch ran.
+     *
+     * Cross-dialect implementation:
+     *   - postgres / sqlite:  `INSERT … ON CONFLICT (cols) DO UPDATE SET …`
+     *   - mariadb 10.5+:      `INSERT … ON DUPLICATE KEY UPDATE … RETURNING *`
+     *   - mysql:              SELECT-then-INSERT-or-UPDATE fallback (no RETURNING)
+     *   - mssql:              SELECT-then-INSERT-or-UPDATE fallback
+     *   - memory store:       linear scan + match-by-conflict-columns
+     */
+    upsert(table: string, row: Row_2, options: UpsertOptions): Promise<Row_2>;
+    /**
+     * `upsert`, plus the one thing it cannot report: whether the row was INSERTED
+     * or UPDATED.
+     *
+     * An app that needs to know does the read itself today — look for the row,
+     * then upsert — which costs a round trip AND opens a window in which the
+     * answer stops being true. It does not have to: the framework's store wrapper
+     * mints the id before the statement, and on the conflict path every dialect
+     * hands back the EXISTING row's id. Two ids that differ ARE the answer, for
+     * free.
+     *
+     * Optional, and provided by the framework's wrapper rather than by a dialect
+     * store — the outcome is decided from what the wrapper already knows, so no
+     * dialect implements anything. It is present on `ctx.store` in a handler; a
+     * hand-written `DataStore` need not have it. The typed helper is
+     * `upsertRowOutcome`.
+     *
+     * `'inserted'` is exact, never a default for "could not tell": where the free
+     * comparison cannot answer (the caller supplied the id, or the table's id is
+     * database-assigned) the destination is read first.
+     */
+    upsertWithOutcome?(table: string, row: Row_2, options: UpsertOptions): Promise<UpsertResult>;
+    /**
+     * Insert-or-ignore: INSERT a row, but if it conflicts on
+     * `conflictColumns`, leave the existing row UNCHANGED and skip the
+     * write. Returns the existing row (when ignored) or the inserted
+     * row.
+     *
+     * Equivalent to `upsert(..., { update: 'nothing' })` but typed as
+     * a separate method for clarity at the call site. The signal is "I
+     * want this row to exist; if it already does, don't touch it" —
+     * common for dedup tables, idempotent event sinks, audit-log
+     * write-once patterns.
+     *
+     * Cross-dialect:
+     *   - postgres / sqlite:  `INSERT … ON CONFLICT (cols) DO NOTHING RETURNING *`
+     *   - mariadb 10.5+:      `INSERT IGNORE … RETURNING *`, lookup on the ignore path
+     *   - mysql:              SELECT-then-skip-or-INSERT fallback
+     *   - mssql:              SELECT-then-skip-or-INSERT fallback
+     *   - memory store:       lookup-then-skip
+     *
+     * Emits an `insert` ChangeEvent ONLY when the insert actually
+     * happened; the ignore path emits nothing (no row changed).
+     */
+    insertIgnore(table: string, row: Row_2, options: {
+        conflictColumns: ReadonlyArray<string>;
+    }): Promise<Row_2>;
+    /**
+     * `insertIgnore`, plus the one thing it cannot report: whether the row was
+     * INSERTED or already there.
+     *
+     * The store's actual insert decision supplies the outcome, including for
+     * caller-supplied and database-generated IDs. A pre-read or comparison of
+     * IDs cannot establish which concurrent caller inserted. Every raw store,
+     * namespace view and transaction view implements this method; wrappers
+     * preserve its outcome while encoding/decoding the row. Inside a transaction
+     * the result is provisional until commit. The typed helper is
+     * `insertIgnoreRowOutcome`.
+     */
+    insertIgnoreWithOutcome(table: string, row: Row_2, options: {
+        conflictColumns: ReadonlyArray<string>;
+    }): Promise<InsertIgnoreResult>;
+    /**
+     * Run `work` inside a transaction. ALL `insert/update/delete` calls
+     * made via `work`'s store reference (passed as argument) are:
+     *
+     *   - atomic — the dialect's native BEGIN/COMMIT/ROLLBACK wraps the
+     *     writes; memory validates snapshot read/write-table revisions before
+     *     committing and retries conflicting attempts with a fresh snapshot.
+     *   - delta-deferred — ChangeEvents queue inside the transaction and
+     *     are emitted ONLY after a successful commit. A throw triggers
+     *     rollback AND drops every queued event so no subscriber ever
+     *     sees a partial-update flicker.
+     *
+     * Reads (`query()`) inside the transaction see the in-flight write
+     * set (read-your-own-writes within the transaction).
+     * Transient contention can replay the whole callback (at most four attempts,
+     * exponential delay starting at 10 ms). Do not perform external side effects
+     * in the callback. Memory validation is table-granular and process-local;
+     * `forUpdate` does not acquire a blocking row lock there.
+     *
+     * `transactional()` MUST NOT be nested — nested invocations throw to
+     * surface design mistakes (transactions are atomic units, not
+     * composable scopes). Use a single top-level `transactional()` per
+     * mutation.
+     */
+    transactional<T>(work: (tx: DataStore) => Promise<T>): Promise<T>;
+    /** Subscribe to row-change events. Returns an unsubscribe function.
+     *
+     *  See `CHANGE_LISTENER_CEILING` for why an EventEmitter-backed
+     *  implementation must raise its listener limit before binding. */
+    onChange(listener: (event: ChangeEvent) => void): () => void;
+    /**
+     * Inject a ChangeEvent that originated OUTSIDE this process — the
+     * cross-instance reactivity seam. Emits the event to local `onChange`
+     * subscribers (the dispatcher, the cache invalidation bus, …) exactly
+     * as a local write would, WITHOUT re-persisting it (the row already
+     * landed in the shared database on the writer).
+     *
+     * Two consumers route through here:
+     *   - Postgres' LISTEN/NOTIFY CDC consumer, translating each NOTIFY
+     *     payload back into a ChangeEvent.
+     *   - `@voltro/plugin-broadcast`'s bus, injecting remote-replica
+     *     ChangeEvents fanned out over Redis / NATS for the non-postgres
+     *     dialects that have no native fan-out.
+     *
+     * It is NOT a write method — there is no transaction, no SQL, no return
+     * value. Subscribe-side only.
+     */
+    injectExternalChange(event: ChangeEvent): void;
+    /**
+     * How this store's ChangeEvents reach the process. `'local'` (the
+     * default when absent): `onChange` carries this process's OWN writes
+     * inline, plus optionally `'injected'`-origin events from a broadcast
+     * transport — a listener that skips `origin === 'injected'` therefore
+     * sees each fleet-wide change exactly once (on its writer). `'fleet'`:
+     * every replica receives the full fleet-wide stream via a CDC consumer
+     * (own writes included, all `'injected'`) — an exactly-once consumer
+     * must elect a single worker instead of filtering by origin.
+     */
+    readonly changeScope?: 'local' | 'fleet';
+    /**
+     * Subscribe to CHANGE-STREAM GAPS — moments where this process proved it
+     * stopped receiving changes for a while and has now started again.
+     *
+     * A gap is not an error to show a user; it is an instruction to the reactive
+     * layer: everything derived from this store may be stale, so re-run it. A
+     * live query is idempotent, which is what makes "re-run all of them" both
+     * safe and the complete recovery. `voltro dev` and `voltro serve` wire this
+     * to the dispatcher's `refreshAll`, the same recovery the broadcast bus's
+     * peer-serial gap uses.
+     *
+     * Optional because only a store whose changes arrive over a TRANSPORT can
+     * have one. An inline store emits its own writes in-process — there is no
+     * connection to lose — and correctly does not implement this. Absent
+     * therefore means "gaps are impossible here", never "gaps are not reported".
+     */
+    readonly onChangeStreamGap?: (listener: (gap: ChangeStreamGap) => void) => () => void;
+    /**
+     * Bind a per-request tenant NAMESPACE, returning a store view whose
+     * every read + write is physically isolated to that namespace
+     * (schema / database / attached file per dialect — see
+     * `@voltro/database`'s `namespace.ts`). The returned view shares the
+     * underlying connection pool + change emitter with `this`; only the
+     * namespace qualification differs.
+     *
+     * `namespace` is the already-resolved, already-sanitised identifier
+     * (e.g. `tenant_acme`) from `resolveTenantNamespace(subject.tenantId)`.
+     * Passing `null` returns a view with NO qualification — the
+     * shared-schema default. The runtime resolves the namespace from the
+     * request subject and binds it here; it NEVER passes a raw, unsanitised
+     * tenant id.
+     *
+     * OPTIONAL on the interface: every shipped store implements it, but
+     * callers that never enable namespace isolation can ignore it.
+     * Equivalent to `this` when the store has no physical-isolation
+     * capability (none ship without it, but the optionality keeps
+     * third-party stores from being forced to implement it).
+     */
+    withNamespace?(namespace: string | null): DataStore;
+    /**
+     * Raw-SQL escape hatch. Execute a {@link RawSqlFragment} captured by
+     * the `sql` template tag (`@voltro/database/sql`) against the store's
+     * live connection and return the decoded rows.
+     *
+     * Values interpolated into the `sql` template are bound as parameters
+     * by the store's dialect-specific `sql` constructor — never
+     * interpolated into the SQL text — so a value containing `'; DROP
+     * TABLE …` round-trips as data. The *static* SQL text is verbatim:
+     * the caller owns its dialect-portability (an escape hatch trades
+     * portability for power).
+     *
+     * `opts.dependsOn` (or `fragment.dependsOn`) declares the tables this
+     * read touches so the reactive layer can recompute it on writes. Raw
+     * reads are otherwise untracked — the planner can't infer table
+     * dependencies from arbitrary SQL. Best-effort: the tables are
+     * recorded, not validated against the fragment.
+     *
+     * OPTIONAL on the interface: SQL stores implement it; the in-memory
+     * store omits it (there is no SQL engine to run raw text against).
+     * Callers must guard with `if (store.raw)` before invoking.
+     */
+    raw?<T extends object = Row_2>(fragment: RawSqlFragment, opts?: {
+        dependsOn?: ReadonlyArray<string>;
+    }): Promise<ReadonlyArray<T>>;
+    /**
+     * Gracefully dispose the store's connection pool + background consumers
+     * (the CDC/NOTIFY fiber). Waits up to `gracePeriodMs` for in-flight
+     * transactions to settle before tearing the pool down, so a `voltro serve`
+     * SIGTERM doesn't sever a connection mid-COMMIT.
+     *
+     * OPTIONAL on the interface: every SQL-backed store implements it; the
+     * in-memory store has no pool to close. `voltro serve`'s shutdown guards
+     * with `if (store.close)`.
+     */
+    close?(gracePeriodMs?: number): Promise<void>;
+    /**
+     * Liveness probe for the store's backing connection — runs a trivial
+     * `SELECT 1`. Resolves when the DB answers; REJECTS when it can't (dead
+     * pool, network partition). The serve path's `/internal/readiness` handler
+     * uses it so a pod whose DB connection died reports 503 and stops taking
+     * traffic instead of erroring every request.
+     *
+     * OPTIONAL on the interface: SQL stores implement it; the in-memory store
+     * omits it (always reachable). Callers guard with `if (store.ping)`.
+     */
+    ping?(): Promise<void>;
+    /**
+     * Empty every one of `tables` as ONE unit, with referential integrity
+     * suspended for the duration.
+     *
+     * Written for `voltro data import --mode replace`, whose whole job is to put
+     * a target into the state a bundle describes. Two properties, and both are
+     * the point:
+     *
+     *   - **All or nothing.** A run that cannot empty every table must leave the
+     *     target exactly as it found it. The loop this replaces deleted table by
+     *     table and stopped at the first refusal, so an operator's *second*
+     *     attempt destroyed more than the first — the deletes that had already
+     *     succeeded stayed gone and nothing was reloaded.
+     *   - **Order-free.** A parent cannot be emptied while a child still points
+     *     at it, and no ordering fixes the two shapes that occur in every real
+     *     schema: a table that references ITSELF (the framework's own actor
+     *     pattern — `createdBy` on `actors` points at `actors`), and a genuine
+     *     cycle. On engines that check each row as it is deleted, ordering the
+     *     TABLES cannot help, because the conflict is between two ROWS of one of
+     *     them.
+     *
+     * What it deliberately does NOT do is reach outside `tables`. A row in some
+     * OTHER table pointing into this set is not ours to delete, and suspending
+     * integrity would strand it. The caller checks for that first and refuses;
+     * see `runImport`'s replace pre-flight.
+     *
+     * Emits no change events, and the consequence is worth stating rather than
+     * implying. One event per deleted row is not affordable at bundle scale — a
+     * replace of a grown target fanned tens of thousands of them out to every live
+     * subscriber — but silence has an edge. In practice the LOAD that follows
+     * covers it: the reactive layer re-reads a query when any row of its table
+     * changes, so the first inserted row refreshes subscribers and the emptied
+     * rows leave their view with it. The exception is a table the bundle carries
+     * EMPTY: nothing is loaded, nothing is emitted, and a subscriber keeps rows
+     * that are gone until it re-subscribes.
+     *
+     * OPTIONAL on the interface: SQL stores implement it per dialect (the
+     * suspension mechanism is engine-specific and session-scoped, so it has to
+     * live next to the connection). Callers guard with `if (store.emptyTables)`
+     * and fall back to deleting inside one transaction — which keeps the
+     * all-or-nothing half on any store, and is all the in-memory store needs.
+     */
+    emptyTables?(tables: ReadonlyArray<string>): Promise<void>;
+    /**
+     * Foreign keys pointing INTO `tables` from tables that are NOT in the set,
+     * read from the LIVE catalog.
+     *
+     * The question `--mode replace` has to answer before it deletes anything:
+     * emptying a parent whose children live outside the bundle would strand rows
+     * the bundle cannot restore. It was answered from the caller's SNAPSHOT, which
+     * is right for the CLI (it introspects the target) and wrong for the admin
+     * endpoint, which passes the app's DECLARED schema — that cannot show a table
+     * the app has stopped declaring but the database still has, and those are
+     * exactly the rows nobody is watching.
+     *
+     * The catalog is the only authority here, so the store asks it.
+     *
+     * OPTIONAL: SQL stores implement it; the in-memory store has no catalog and no
+     * foreign keys, so it omits it and callers fall back to the snapshot.
+     */
+    incomingForeignKeys?(tables: ReadonlyArray<string>): Promise<ReadonlyArray<{
+        readonly from: string;
+        readonly column: string;
+        readonly to: string;
+    }>>;
+    /**
+     * Run `fn` inside a nested savepoint, so a failure inside it costs only its
+     * own work instead of the whole transaction.
+     *
+     * Exists for one reason: on postgres (and SQL Server for some errors) a failed
+     * statement ABORTS the enclosing transaction — every statement after it
+     * answers `current transaction is aborted` and nothing can be salvaged. The
+     * importer's deferred-foreign-key repair depends on the opposite: a row whose
+     * parent has not loaded yet is EXPECTED to fail, is held, and is retried once
+     * the rest has streamed. That repair is how a bundle whose row order puts a
+     * child before its parent lands at all — and ids sort that way as often as
+     * not. Without a savepoint the two are incompatible, so `--atomic` simply
+     * could not import such a bundle on those engines.
+     *
+     * Only the TRANSACTIONAL views implement it, and only for the engines that
+     * need it: the mysql family and sqlite leave a transaction usable after a
+     * failed statement, so wrapping every row there would buy nothing and cost a
+     * round trip per row. Callers guard with `if (store.savepoint)` and run `fn`
+     * directly otherwise — which is also correct outside a transaction, where
+     * there is nothing to protect.
+     *
+     * Failures propagate: the savepoint is rolled back and the error rethrown, so
+     * the caller's own error handling is unchanged.
+     */
+    savepoint?<A>(fn: () => Promise<A>): Promise<A>;
+    /**
+     * Re-decide which tables this store's change-capture reader can decode, and
+     * apply the answer to the LIVE reader.
+     *
+     * Exists because that decision is a reading of the SCHEMA, and a boot that
+     * migrates in the same process moves the schema after the reader attached.
+     * The reader is built before the migration runs (it has consumers — kv,
+     * broadcast, the analytics mirror — that need a store first), so a table
+     * excluded on the pre-migration shape stayed excluded for the life of the
+     * process even when the migration was the very thing that fixed it.
+     *
+     * Call it once every boot, AFTER all schema work. Cheap (one catalog query)
+     * and a no-op on a store whose verdict did not move — including every store
+     * with nothing to exclude.
+     *
+     * OPTIONAL on the interface: only the mysql-family binlog reader has a
+     * physical-layout exclusion at all. Postgres NOTIFY, mssql Change Tracking
+     * and the in-memory store decode whatever they are given, so they omit it and
+     * callers guard with `if (store.refreshChangeCaptureExclusions)`.
+     */
+    refreshChangeCaptureExclusions?(): Promise<ChangeCaptureExclusionRefresh>;
+    /**
+     * Run an Effect that needs this store's own `SqlClient` — the raw-SQL seam.
+     *
+     * The capability the STAGED SWAP is built on. `--mode replace` loads into
+     * `_voltro_staging_<t>` tables and then swaps the CONTENT in one short
+     * transaction (`DELETE FROM t; INSERT INTO t (…) SELECT … FROM
+     * _voltro_staging_t`), which moves the long, network-bound load OUT of the
+     * destructive transaction. None of that is expressible through the typed row
+     * API: it is DDL plus a server-side `INSERT … SELECT`, and the whole point is
+     * that no row crosses the wire.
+     *
+     * OPTIONAL on the interface, and declared here rather than duck-typed at the
+     * call site for the reason the house rule gives: the four dialect stores are
+     * four hand-written copies of one interface, and a capability nothing declares
+     * is a capability nothing can be red about. A store that loses it now fails to
+     * satisfy this member instead of silently falling out of `canStage()` and
+     * taking the weaker path forever, on one dialect, in silence.
+     *
+     * The DECISION does not live per store — that would be the four-copies trap
+     * wearing a different hat. `@voltro/data-transfer`'s `stagedSwap.ts` writes
+     * the per-dialect SQL ONCE and sends it down this seam; the store contributes
+     * a connection, not a policy.
+     *
+     * Callers guard with `if (store.run)` (or `canStage(store)`), and a store
+     * without it keeps the path it already has: the in-memory store has no SQL
+     * and no catalog, and neither does a bare `DataStore` view.
+     *
+     * `R` is deliberately `SqlClient.SqlClient`: the effect asks for the client
+     * and the store provides its own, which is what makes this a SEAM rather than
+     * a way to hand a store somebody else's connection.
+     */
+    run?<A, E>(effect: Effect.Effect<A, E, SqlClient.SqlClient>): Promise<A>;
+}
+
+/**
+ * Build a `SchemaSnapshot` from an array of `TableLike` declarations.
+ * Caller is responsible for passing the FULL set of tables (user-
+ * declared + framework). The fingerprint over this snapshot is what the
+ * boot-time prod check compares against `_voltro_migration_plans`.
+ */
+export declare const declaredSnapshot: (tables: ReadonlyArray<TableLike>, dialect?: DialectId) => SchemaSnapshot;
+
+/** The NOTIFY channel a schema emits on when none is configured. */
+export declare const DEFAULT_CDC_CHANNEL = "framework_changes";
+
+/**
+ * `DEFAULT <expr>` for an array-valued default.
+ *
+ * Postgres is the only dialect with native arrays, so a `array()` column there
+ * takes an array literal (`'{a,b}'::text[]`); every other dialect stores the
+ * value as JSON/TEXT and takes the json form. A default on a `json()` column
+ * always takes the json form — the array is the VALUE, not the storage.
+ */
+export declare const defaultArrayClause: (value: ReadonlyArray<unknown>, column: ColumnDefinition<unknown>, dialect: DialectId) => string;
+
+export declare const defaultClause: (column: ColumnDefinition<unknown>, dialect: DialectId) => string | null;
+
+/**
+ * `DEFAULT <expr>` for a plain-object json default, per dialect's json-column
+ * type. Single source for the auto-migrate (`defaultClause`) AND declarative-
+ * applier paths so the two can't drift (the introspected form must round-trip
+ * against `normalizeDefault`, so the emit shape matters on both sides).
+ */
+export declare const defaultJsonClause: (value: object, dialect: DialectId) => string;
+
+/**
+ * The DATA half of a three-step `add-column`, handed back by `executeOp`
+ * instead of run in place when the caller collects it. `data` is the backfill
+ * — UPDATEs only; `after` is the DDL that follows it (the NOT NULL
+ * enforcement, or the sqlite rebuild that stands in for it). The two are
+ * separate so the caller can run every collected `data` inside ONE
+ * transaction and every `after` outside it, which is the only order MySQL
+ * and MariaDB can honour: a DDL statement inside the transaction would commit
+ * the backfills before it.
+ */
+export declare interface DeferredData {
+    readonly table: string;
+    readonly op: MigrationOperation;
+    readonly data: Effect.Effect<void, SqlError_2>;
+    readonly after: Effect.Effect<void, SqlError_2>;
+}
+
+export declare const DEPLOY_LEDGER_TABLE = "_voltro_deploys";
+
+export declare interface DeployLedgerRow {
+    readonly id: string;
+    readonly status: 'running' | 'failed';
+    readonly dialect: string;
+    readonly appliedBy: string;
+    readonly startedAt: string;
+    readonly baseline: string;
+    readonly report: string | null;
+}
+
+export declare const describeOutcome: (outcome: BootMigrationOutcome, dialectId: string) => string;
+
+/**
+ * Parse `VOLTRO_DESTRUCTIVE_OK`.
+ *
+ * `1` / `true` acknowledges every lossy op in the run. A comma-separated list
+ * acknowledges only those TABLES — which is the form somebody wants far more
+ * often, and its absence was a real complaint: a plan carrying one intended drop
+ * plus three other lossy ops had no way to say yes to the one. `1` said yes to
+ * all four, and the alternative was a hand-written DROP migration, which the
+ * framework's own upgrade note warns against.
+ *
+ * `undefined` = not set at all.
+ */
+export declare const destructiveScope: (raw: string | undefined) => {
+    readonly kind: "all";
+} | {
+    readonly kind: "tables";
+    readonly tables: ReadonlySet<string>;
+} | undefined;
+
+/**
+ * Compare declared reactivity against the triggers actually installed.
+ *
+ * Postgres only — it is the one dialect where reactivity is carried by DDL. The
+ * binlog and Change Tracking readers are configured at runtime from the same
+ * in-memory table list the schema produced, so they cannot drift from it.
+ */
+export declare const detectReactiveTriggerDrift: (sql: SqlClient.SqlClient, tables: ReadonlyArray<{
+    readonly tableName: string;
+    readonly isReactive?: boolean;
+}>, 
+/** 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>;
+
+/** Dialect IDs the framework supports. */
+declare type DialectId = 'postgres' | 'mysql' | 'mariadb' | 'mssql' | 'sqlite' | 'turso';
+
+/**
+ * Output of `voltro db drift`: compares the live DB's introspected
+ * schema against the last applied fingerprint in `_voltro_migrations`.
+ *
+ * `isDrifted: false` is the happy path. A drift report names the
+ * concrete divergences so the operator can either reconcile in code or
+ * via a corrective migration.
+ */
+export declare interface DriftReport {
+    readonly isDrifted: boolean;
+    readonly lastAppliedFingerprint?: string;
+    readonly liveFingerprint: string;
+    readonly divergences: ReadonlyArray<{
+        readonly kind: 'unexpected' | 'missing';
+        readonly description: string;
+    }>;
+}
+
+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;
+}
+
+/**
+ * Per-branch refinement passed to `.with({ relation: { ... } })`.
+ *
+ * `true` is the zero-config shorthand — equivalent to `{}`. Otherwise
+ * each branch can carry its own `where` / `orderBy` / `limit` /
+ * `offset` / nested `with`, so `users.with({ posts: { limit: 10,
+ * orderBy: 'createdAt' } })` works without dropping into a sub-query
+ * builder.
+ *
+ * Untyped at runtime: the QueryDescriptor is the boundary between the
+ * typed builder API and the dialect-agnostic JoinCompiler. End-user
+ * types live one layer up in the typed `.with()` method on `Query`.
+ */
+declare interface EagerLoadSpec {
+    readonly where?: Predicate;
+    readonly orderBy?: ReadonlyArray<OrderClause>;
+    /**
+     * Per-parent cap on the relation. `{ limit: 10 }` returns up to 10
+     * rows FOR EACH parent — same semantics as Drizzle / Prisma /
+     * Hibernate. This matches what users actually mean when they write
+     * "the 10 latest posts" inside `users.with({ posts: { limit: 10 } })`.
+     *
+     * The SQL stores express this natively as a `LIMIT` clause in a
+     * correlated subquery (postgres / sqlite / mysql / mariadb) or
+     * via `TOP N` inside `FOR JSON PATH` (mssql) when the JSON-agg path
+     * is active. The walker fallback post-buckets the batch fetch and
+     * slices each bucket.
+     */
+    readonly limit?: number;
+    /** Per-parent offset. Only meaningful with `limit`. */
+    readonly offset?: number;
+    readonly with?: WithSpec;
+    /**
+     * Project the JUNCTION row's own columns into a `manyToMany` eager result.
+     *
+     * `true` takes every junction column; an array takes only those named. The
+     * values land under `_junction` on each target row:
+     *
+     *     projects.with({ teams: { junction: ['role', 'addedAt'] } })
+     *     // → team._junction.addedAt
+     *
+     * Nested rather than merged onto the target row, deliberately: a junction and
+     * its target routinely share column names (`createdAt` is the obvious one),
+     * and merging would silently overwrite real target data with membership data.
+     * A name collision that corrupts a row is worse than one extra level.
+     *
+     * Why this exists: junction tables carrying meaningful columns — a role, a
+     * joined-at stamp, a permission tier — are the rule rather than the
+     * exception, and without this an eager load could FILTER on them
+     * (`onJunction`) but never return them, so any relation with real membership
+     * data had to stay a hand-written join. The junction rows were already being
+     * fetched in full to resolve the target ids; this stops throwing them away.
+     */
+    readonly junction?: true | ReadonlyArray<string>;
+    /**
+     * Filter a `manyToMany` eager branch on the THROUGH-table's columns.
+     * The predicate is evaluated against the junction row, not the target
+     * row — e.g. for `users.with({ organizations: { onJunction: eq('role',
+     * 'admin') } })` it keeps only the memberships where `role = 'admin'`,
+     * so the loaded `organizations` are exactly the orgs the user is an
+     * admin of.
+     *
+     * Compiles into the correlated subquery's WHERE alongside the
+     * source-key correlation, qualified to the junction-table alias.
+     * Ignored on `one` / `many` branches (no junction table exists).
+     */
+    readonly onJunction?: Predicate;
+}
+
+/**
+ * Per-branch refinement passed to `.with({ relation: { ... } })`.
+ *
+ * `true` is the zero-config shorthand — equivalent to `{}`. Otherwise
+ * each branch can carry its own `where` / `orderBy` / `limit` /
+ * `offset` / nested `with`, so `users.with({ posts: { limit: 10,
+ * orderBy: 'createdAt' } })` works without dropping into a sub-query
+ * builder.
+ *
+ * Untyped at runtime: the QueryDescriptor is the boundary between the
+ * typed builder API and the dialect-agnostic JoinCompiler. End-user
+ * types live one layer up in the typed `.with()` method on `Query`.
+ */
+declare interface EagerLoadSpec_2 {
+    readonly where?: Predicate_2;
+    readonly orderBy?: ReadonlyArray<OrderClause_2>;
+    /**
+     * Per-parent cap on the relation. `{ limit: 10 }` returns up to 10
+     * rows FOR EACH parent — same semantics as Drizzle / Prisma /
+     * Hibernate. This matches what users actually mean when they write
+     * "the 10 latest posts" inside `users.with({ posts: { limit: 10 } })`.
+     *
+     * The SQL stores express this natively as a `LIMIT` clause in a
+     * correlated subquery (postgres / sqlite / mysql / mariadb) or
+     * via `TOP N` inside `FOR JSON PATH` (mssql) when the JSON-agg path
+     * is active. The walker fallback post-buckets the batch fetch and
+     * slices each bucket.
+     */
+    readonly limit?: number;
+    /** Per-parent offset. Only meaningful with `limit`. */
+    readonly offset?: number;
+    readonly with?: WithSpec_2;
+    /**
+     * Project the JUNCTION row's own columns into a `manyToMany` eager result.
+     *
+     * `true` takes every junction column; an array takes only those named. The
+     * values land under `_junction` on each target row:
+     *
+     *     projects.with({ teams: { junction: ['role', 'addedAt'] } })
+     *     // → team._junction.addedAt
+     *
+     * Nested rather than merged onto the target row, deliberately: a junction and
+     * its target routinely share column names (`createdAt` is the obvious one),
+     * and merging would silently overwrite real target data with membership data.
+     * A name collision that corrupts a row is worse than one extra level.
+     *
+     * Why this exists: junction tables carrying meaningful columns — a role, a
+     * joined-at stamp, a permission tier — are the rule rather than the
+     * exception, and without this an eager load could FILTER on them
+     * (`onJunction`) but never return them, so any relation with real membership
+     * data had to stay a hand-written join. The junction rows were already being
+     * fetched in full to resolve the target ids; this stops throwing them away.
+     */
+    readonly junction?: true | ReadonlyArray<string>;
+    /**
+     * Filter a `manyToMany` eager branch on the THROUGH-table's columns.
+     * The predicate is evaluated against the junction row, not the target
+     * row — e.g. for `users.with({ organizations: { onJunction: eq('role',
+     * 'admin') } })` it keeps only the memberships where `role = 'admin'`,
+     * so the loaded `organizations` are exactly the orgs the user is an
+     * admin of.
+     *
+     * Compiles into the correlated subquery's WHERE alongside the
+     * source-key correlation, qualified to the junction-table alias.
+     * Ignored on `one` / `many` branches (no junction table exists).
+     */
+    readonly onJunction?: Predicate_2;
+}
 
 export declare const emitAddIndexMysql: (op: Extract<MigrationOperation, {
     kind: "add-index";
@@ -1262,6 +2546,35 @@ 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) => Effect.Effect<void, SqlError_2>;
+
+/**
+ * Create `_voltro_migration_ops` if it isn't there yet.
+ *
+ * Rendered from the SAME per-dialect create-table emitters the planner uses for
+ * user tables, off the declared descriptor — so the ledger cannot acquire a
+ * hand-written second DDL path that disagrees with the first. All four emitters
+ * are already idempotent (`IF NOT EXISTS` / an `IF OBJECT_ID … IS NULL` guard on
+ * mssql), so this is safe to call on every apply.
+ *
+ * The ledger is bootstrapped here rather than registered with the CLI's
+ * 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) => Effect.Effect<void, SqlError_2>;
+
+/** Exported for the same reason as {@link enumTypeBlocks}, and it MUST run
+ *  before it — see that function's note on ordering. */
+export declare const enumRenameBlocks: (tables: ReadonlyArray<AnyTable>, dialect: DialectId) => string;
+
+/** Exported for the APPLIER: `voltro db apply` builds its DDL from operations,
+ *  not from this emitter, and an operation only names a column's type by tag.
+ *  A create-table referencing a `dbEnum` therefore ran before anything had
+ *  created the type — `type "x" does not exist`, on a fresh database, for every
+ *  app declaring one. One emitter, two callers. */
+export declare const enumTypeBlocks: (tables: ReadonlyArray<AnyTable>, dialect: DialectId) => string;
+
 /**
  * `EXISTS (SELECT 1 FROM ... WHERE ...)` / `NOT EXISTS (...)`.
  * Mirrors `SubqueryInPredicate` but doesn't bind to a specific
@@ -1274,6 +2587,38 @@ declare interface ExistsPredicate {
     readonly subquery: QueryDescriptor;
 }
 
+/**
+ * `EXISTS (SELECT 1 FROM ... WHERE ...)` / `NOT EXISTS (...)`.
+ * Mirrors `SubqueryInPredicate` but doesn't bind to a specific
+ * outer column — the predicate is "the sub-query produces at least
+ * one row" (or doesn't). Non-correlated in v1; the sub-query's
+ * WHERE clause references only its own table.
+ */
+declare interface ExistsPredicate_2 {
+    readonly op: 'exists' | 'not-exists';
+    readonly subquery: QueryDescriptor_2;
+}
+
+/**
+ * The postgres extensions the declared tables need, as one DDL block — or
+ * `undefined`. `IF NOT EXISTS`, so every apply can run it. Shared by the
+ * bring-up emitter and the plan applier; a block only one of them emits is a
+ * boot failure waiting for the right database (see the reactive-trigger scar).
+ */
+export declare const extensionBlocks: (tables: ReadonlyArray<AnyTable>, dialect: DialectId) => string | undefined;
+
+/** An undo that could not complete: the row stays, with the report, until an operator forgets it. */
+export declare const failDeploy: (sql: SqlClient.SqlClient, id: string, report: string) => Effect.Effect<void, unknown>;
+
+/**
+ * Evaluate the post-conditions a body registered. The descriptions of the
+ * ones that did not hold, in registration order.
+ */
+export declare const failedExpectations: (expectations: ReadonlyArray<{
+    readonly description: string;
+    readonly check: () => Promise<boolean> | Effect.Effect<boolean, unknown, never>;
+}>) => Effect.Effect<ReadonlyArray<string>, unknown>;
+
 /**
  * Filename pattern the discovery walker matches: timestamp-prefixed
  * `.ts` files in any depth under the project's `migrations/` dir.
@@ -1301,26 +2646,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
@@ -1333,6 +2724,71 @@ 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>;
+}
+
+export declare interface FileMigrationContextInput {
+    readonly sql: SqlClient.SqlClient;
+    readonly store: DataStore;
+    readonly dialect: DialectId;
+    readonly migrationId: string;
+    readonly appliedAt: string;
 }
 
 /**
@@ -1410,6 +2866,25 @@ declare type IdScheme = {
     readonly generate: (tableName: string) => string;
 };
 
+/**
+ * Fully-resolved scheme stored on the `id` column definition AFTER
+ * `table()` walks the fields. For `typeid`, the prefix is always
+ * populated here — either user-supplied or derived from the table name.
+ */
+declare type IdScheme_2 = {
+    readonly kind: 'typeid';
+    readonly prefix: string;
+} | {
+    readonly kind: 'ulid';
+} | {
+    readonly kind: 'numeric';
+} | {
+    readonly kind: 'snowflake';
+} | {
+    readonly kind: 'custom';
+    readonly generate: (tableName: string) => string;
+};
+
 /**
  * User-facing input to `id()`. Some shapes leave the prefix to be
  * derived from the table name at register-time.
@@ -1436,6 +2911,32 @@ declare type IdSchemeInput = undefined | {
     readonly generate: (tableName: string) => string;
 };
 
+/**
+ * User-facing input to `id()`. Some shapes leave the prefix to be
+ * derived from the table name at register-time.
+ *
+ * Defaults:
+ *   - `undefined`                            → `{ scheme: 'typeid' }` with derived prefix
+ *   - `{ prefix }`                           → typeid with that prefix
+ *   - `{ scheme: 'typeid' }`                 → derived prefix
+ *   - `{ scheme: 'typeid', prefix }`         → explicit prefix
+ */
+declare type IdSchemeInput_2 = undefined | {
+    readonly prefix: string;
+} | {
+    readonly scheme: 'typeid';
+    readonly prefix?: string;
+} | {
+    readonly scheme: 'ulid';
+} | {
+    readonly scheme: 'numeric';
+} | {
+    readonly scheme: 'snowflake';
+} | {
+    readonly scheme: 'custom';
+    readonly generate: (tableName: string) => string;
+};
+
 /**
  * Live tables the planner must NOT drop, parsed from `VOLTRO_DB_IGNORE_TABLES`
  * (comma-separated). The framework already self-excludes its own `_voltro_*`
@@ -1559,8 +3060,35 @@ export declare interface IndexSnapshot {
     readonly expression?: boolean;
 }
 
+/** What an `insertIgnoreWithOutcome` did, beside the row it hands back. */
+declare interface InsertIgnoreResult {
+    readonly row: Row_2;
+    /** `'ignored'` means a row already existed for the conflict key; it is the
+     *  row returned, untouched. */
+    readonly outcome: 'inserted' | 'ignored';
+}
+
 export declare const introspectSchema: (sql: SqlClient.SqlClient) => Effect.Effect<SchemaSnapshot, SqlError_2>;
 
+/**
+ * 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;
+
 export declare const isAlreadySatisfied: (err: unknown, rules: ReadonlyArray<AlreadySatisfied>) => boolean;
 
 /** Type-guard for the discovery walker. */
@@ -1601,8 +3129,31 @@ declare interface JsonIndexPath {
 
 declare type LeafOperator = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'notIn' | 'contains' | 'startsWith' | 'arrayContains' | 'arrayOverlaps' | 'arrayHas' | 'isNull' | 'isNotNull' | 'spatial';
 
+declare type LeafOperator_2 = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'notIn' | 'contains' | 'startsWith' | 'arrayContains' | 'arrayOverlaps' | 'arrayHas' | 'isNull' | 'isNotNull' | 'spatial';
+
+/**
+ * Build the context for one migration body. Returns the context and the
+ * post-conditions it collects, so the runner can evaluate them after `up`.
+ */
+export declare const makeFileMigrationContext: (input: FileMigrationContextInput) => {
+    ctx: FileMigrationContext;
+    expectations: {
+        readonly description: string;
+        readonly check: () => Promise<boolean> | Effect.Effect<boolean, unknown, never>;
+    }[];
+};
+
 export declare const mapPgType: (dataType: string, udtName?: string) => ColumnType;
 
+/**
+ * A whole live snapshot as DECLARATIONS, each table's references resolved
+ * against the others — what the planner needs on its declared side to bring a
+ * database back to the shape this snapshot describes. Used by the deploy
+ * compensation: the pre-deploy snapshot is the target, the current live schema
+ * the source, and the plan between them is the undo.
+ */
+export declare const materialiseSnapshot: (snap: SchemaSnapshot) => ReadonlyArray<TableLike>;
+
 declare type MergeMixinFields<Mixins extends ReadonlyArray<AnyMixin>> = Mixins extends readonly [] ? EmptyMerge : Mixins extends readonly [infer Head, ...infer Rest] ? (Head extends MixinDefinition<infer F> ? F : EmptyMerge) & (Rest extends ReadonlyArray<AnyMixin> ? MergeMixinFields<Rest> : EmptyMerge) : EmptyMerge;
 
 /**
@@ -1616,20 +3167,51 @@ declare type MergeMixinFields<Mixins extends ReadonlyArray<AnyMixin>> = Mixins e
  *     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;
 
+export declare const MIGRATION_ATOMICITY: Readonly<Record<DialectId, MigrationAtomicity>>;
+
+/**
+ * The lock HOLDS a connection for the whole apply, so the work needs a second
+ * one — a pool of one waits out its acquire timeout and reports a connection
+ * problem that is really a sizing one. Said here, at the failure, in the words
+ * an operator behind a pooler can act on.
+ */
+export declare const MIGRATION_NEEDS_TWO_CONNECTIONS: string;
+
+/**
+ * How much of a plan a dialect can apply atomically.
+ *
+ *  - `plan-transactional` — the applier wraps the plan in one transaction; a
+ *    mid-apply failure rolls the WHOLE plan back and there is nothing to resume.
+ *  - `per-operation` — each statement is its own unit; a mid-apply failure
+ *    leaves earlier operations applied, so the resume ledger carries the run.
+ *
+ * Keyed by `DialectId`, not by the four driver tokens, so `mariadb` and `turso`
+ * are stated rather than inferred from a sibling. `resumeLedger.test.ts`
+ * ("covers every dialect in the union") asserts every member has an entry.
+ */
+export declare type MigrationAtomicity = 'plan-transactional' | 'per-operation';
+
+export declare const migrationAtomicityFor: (dialect: DialectId) => MigrationAtomicity;
+
+/** 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>);
+}
+
 /**
  * The postgres advisory-lock key for a schema. Default schema (undefined /
  * `'public'`) → the EXACT legacy constant (rolling-deploy pin, see above).
@@ -1739,6 +3321,19 @@ export declare type MigrationOperation = {
     readonly kind: 'drop-unique';
     readonly table: string;
     readonly column: string;
+} | {
+    readonly kind: 'add-enum-value';
+    readonly table: string;
+    readonly column: string;
+    /** The postgres type the value is added to — several columns may share it. */
+    /**
+     * The postgres TYPE name. ABSENT on every other dialect, and that is a
+     * fact about the database rather than a missing field: the mysql family's
+     * `ENUM(...)` is anonymous and mssql/sqlite render a CHECK, so there is no
+     * named object to alter. The applier redeclares the column there instead.
+     */
+    readonly enumName?: string;
+    readonly value: string;
 } | {
     readonly kind: 'add-unique-composite';
     readonly table: string;
@@ -1755,413 +3350,884 @@ export declare type MigrationOperation = {
     readonly kind: 'add-foreign-key';
     readonly table: string;
     readonly column: string;
-    readonly targetTable: string;
-    readonly targetColumn: string;
-    readonly onDelete?: 'cascade' | 'restrict' | 'setNull' | 'noAction';
-    readonly onUpdate?: 'cascade' | 'restrict' | 'setNull' | 'noAction';
-    readonly orphanPolicy?: 'null' | 'delete';
-} | {
-    readonly kind: 'drop-foreign-key';
-    readonly table: string;
+    readonly targetTable: string;
+    readonly targetColumn: string;
+    readonly onDelete?: 'cascade' | 'restrict' | 'setNull' | 'noAction';
+    readonly onUpdate?: 'cascade' | 'restrict' | 'setNull' | 'noAction';
+    readonly orphanPolicy?: 'null' | 'delete';
+}
+/** `name` is the live constraint's catalog name when the reader reported
+*  one; absent, the applier falls back to the `<table>_<column>_fkey`
+*  convention it uses when creating. */
+| {
+    readonly kind: 'drop-foreign-key';
+    readonly table: string;
+    readonly column: string;
+    readonly name?: string;
+} | {
+    readonly kind: 'add-check';
+    readonly table: string;
+    readonly column: string;
+    readonly values: ReadonlyArray<string>;
+} | {
+    readonly kind: 'drop-check';
+    readonly table: string;
+    readonly column: string;
+} | {
+    readonly kind: 'reconcile-json-check';
+    readonly table: string;
+    readonly column: string;
+    readonly validation: 'value' | 'container';
+    readonly previousValidation: 'value' | 'container' | 'unverified' | 'absent';
+    readonly dropConstraints: ReadonlyArray<string>;
+};
+
+export declare interface MigrationPlan {
+    readonly operations: ReadonlyArray<PlannedOperation>;
+    /** Pre-state fingerprint (live DB at plan time). */
+    readonly fromFingerprint: string;
+    /** Post-state fingerprint (what the DB will look like after apply). */
+    readonly toFingerprint: string;
+    /**
+     * Where the two fingerprints part when the plan is EMPTY. `fromFingerprint`
+     * hashes the whole live introspection; `toFingerprint` hashes the declaration;
+     * a plan of zero operations says the schemas agree — and the hashes can still
+     * differ. Then this names the tables on which they do:
+     *
+     *   `outsideDiff` — live tables the diff never compares: framework-owned
+     *   (`cluster_*`, an undeclared `_voltro_*`), soft-drop snapshots, a name in
+     *   `VOLTRO_DB_IGNORE_TABLES`, the old name of a rename. In the live hash, in
+     *   no declaration.
+     *   `diffEquivalent` — tables on both sides the diff planned nothing for whose
+     *   live and declared snapshots hash apart anyway: a detail introspection
+     *   reports differently from how it was declared.
+     *
+     * Both empty means the hashes agree table for table. A reader who meets two
+     * different hashes over `0 operations` is otherwise left to guess what moved.
+     */
+    readonly fingerprintDivergence: {
+        readonly outsideDiff: ReadonlyArray<string>;
+        readonly diffEquivalent: ReadonlyArray<string>;
+    };
+    /** Count summaries by class — what `voltro db plan` prints. */
+    readonly summary: {
+        readonly safe: number;
+        readonly needsDefault: number;
+        readonly needsBackfill: number;
+        readonly needsRenameAnnotation: number;
+        readonly lossy: number;
+        readonly onlineRequired: number;
+        readonly multiStep: number;
+        readonly blocked: number;
+    };
+}
+
+/** The schema operations a file migration's context can ask for by name. */
+export declare type MigrationSchemaOp = {
+    readonly kind: 'drop-foreign-key';
+    readonly table: string;
+    readonly column: string;
+    readonly name?: string;
+} | {
+    readonly kind: 'drop-index';
+    readonly table: string;
+    readonly index: string;
+} | {
+    readonly kind: 'drop-column';
+    readonly table: string;
+    readonly column: string;
+} | {
+    readonly kind: 'rename-column';
+    readonly table: string;
+    readonly from: string;
+    readonly to: 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);
+}
+
+declare interface MixinDefinition<F extends Record<string, ColumnDefinition<unknown>>> {
+    /**
+     * Stable dedup key. Two mixins with the same `id` reaching a table via
+     * different paths (direct + transitive) are materialised once. Convention:
+     * `<pluginNamespace>/<mixinName>` — e.g. `voltro/audit`, `voltro/tenant`,
+     * `acmeBilling/invoiceable`.
+     */
+    readonly id?: string;
+    readonly fields: F;
+    /**
+     * Other mixins this one needs in place. Resolved depth-first before the
+     * mixin itself is applied, so its `beforeInsert` / `defaultWhere` can rely
+     * on the columns added by its dependencies.
+     */
+    readonly requires?: ReadonlyArray<AnyMixin>;
+    /**
+     * Indexes the mixin contributes when applied to a table. Used by the
+     * built-in `tenant()` mixin to auto-index `tenantId` without
+     * resurrecting a column-level `.index()` modifier (which we
+     * deliberately collapsed into the single table-level surface). The
+     * table-builder merges these into its `appliedIndexes` and
+     * auto-names anonymous entries per-table.
+     */
+    readonly indexes?: ReadonlyArray<MixinIndex>;
+    readonly behaviors?: {
+        readonly beforeInsert?: (...args: unknown[]) => unknown;
+        readonly beforeUpdate?: (...args: unknown[]) => unknown;
+        readonly onDelete?: (...args: unknown[]) => unknown;
+        readonly defaultWhere?: (...args: unknown[]) => unknown;
+    };
+    readonly policies?: ReadonlyArray<{
+        readonly name: string;
+        readonly predicate: (...args: unknown[]) => boolean;
+    }>;
+}
+
+/**
+ * Index contribution from a mixin. The fields are column names that
+ * MUST exist either on the host table or on the mixin's own `fields`
+ * map. The optional `name` lets the mixin pin the literal index
+ * identifier; omitted, the table-builder auto-generates
+ * `<tableName>_<col1>_<col2>_idx` so the same mixin applied to
+ * different tables produces distinct DDL names.
+ */
+declare interface MixinIndex {
+    readonly fields: ReadonlyArray<string>;
+    readonly name?: string;
+    /**
+     * Index access method. Default `'btree'`. The `vectorEmbedding()` mixin
+     * sets `kind: 'hnsw'` so the vector column it contributes also gets its
+     * ANN index — without resurrecting a column-level `.index()` modifier.
+     * The table-builder forwards `kind` + `kindOptions` into the
+     * `TableIndex` it materialises from this contribution.
+     */
+    readonly kind?: IndexKind;
+    /** Per-kind tuning (e.g. `kindOptions.hnsw.{m, efConstruction, distance}`). */
+    readonly kindOptions?: IndexKindOptions;
+}
+
+/** Which engine a `mysql`-dialect connection is actually talking to. */
+export declare type MysqlEngine = 'mysql' | 'mariadb';
+
+/**
+ * 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
+ * current type. Without `using`, narrowing fails for rows whose value
+ * can't fit the new type. The `using` fragment is the dialect-specific
+ * cast expression (Postgres `... USING col::int`, MSSQL CONVERT/CAST,
+ * MySQL CAST).
+ */
+declare interface NarrowedFromSpec {
+    readonly from: ColumnType;
+    /**
+     * Raw SQL cast expression spliced into the planner's
+     * `ALTER COLUMN … TYPE … USING <using>` (postgres) / shadow-copy
+     * (`shadow := <using>(old)`). Authored by the developer in the
+     * migration — e.g. `'role::role_enum'`, `'flag::int::text'`. Omit when
+     * the conversion is implicit on the dialect (e.g. `varchar → text`).
+     */
+    readonly using?: string;
+}
+
+/**
+ * Type-narrowing migration marker. Tells the planner that this column
+ * previously had type `from` and is now being narrowed/converted to its
+ * current type. Without `using`, narrowing fails for rows whose value
+ * can't fit the new type. The `using` fragment is the dialect-specific
+ * cast expression (Postgres `... USING col::int`, MSSQL CONVERT/CAST,
+ * MySQL CAST).
+ */
+declare interface NarrowedFromSpec_2 {
+    readonly from: ColumnType_2;
+    /**
+     * Raw SQL cast expression spliced into the planner's
+     * `ALTER COLUMN … TYPE … USING <using>` (postgres) / shadow-copy
+     * (`shadow := <using>(old)`). Authored by the developer in the
+     * migration — e.g. `'role::role_enum'`, `'flag::int::text'`. Omit when
+     * the conversion is implicit on the dialect (e.g. `varchar → text`).
+     */
+    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`). */
+declare interface NotPredicate {
+    readonly not: Predicate;
+}
+
+/** 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`). */
+declare interface NotPredicate_2 {
+    readonly not: Predicate_2;
+}
+
+/**
+ * DDL fragment for a numeric primary key column. Each dialect has its
+ * own auto-increment idiom — there's no portable shorthand, so we
+ * dispatch per dialect explicitly. The fragment includes type + PK +
+ * auto-increment in one statement; the caller skips the generic
+ * `NOT NULL` / `PRIMARY KEY` additions for numeric ids.
+ */
+export declare const numericIdSql: (name: string, dialect: DialectId) => string;
+
+export declare const openDeploy: (sql: SqlClient.SqlClient, row: {
+    readonly id: string;
+    readonly dialect: string;
+    readonly appliedBy: string;
+    readonly baseline: string;
+}) => Effect.Effect<void, unknown>;
+
+/**
+ * The seven classes of schema operations the planner recognises. The
+ * default policy for each is encoded by the planner; the applier
+ * obeys it. Keep this enum in lockstep with the AGENTS.md template's
+ * "Schema migrations" section — agents grep for these strings.
+ */
+export declare type OperationClass = 
+/** Reversible, side-effect-free for existing data. Auto-applied. */
+'safe'
+/** ADD COLUMN + NOT NULL with `.default(value)` declared.
+*  Applied as `ADD COLUMN ... NOT NULL DEFAULT <value>`. */
+| 'needs-default'
+/** ADD COLUMN + NOT NULL on a populated table, ADD UNIQUE / FK / CHECK
+*  with existing offenders. Requires a deliberate declaration
+*  (`.backfill()`, `.unique({dedup})`, `reference({orphanPolicy})`).
+*  Applied as a three-step plan (ADD nullable → run backfill → SET
+*  NOT NULL). */
+| 'needs-backfill'
+/** Column appears removed + a new one appeared. Looks like DROP+ADD
+*  but is probably a rename. Refuse-to-plan without an explicit
+*  `.renamedFrom('oldName')` marker — silent renames lose data. */
+| 'needs-rename-annotation'
+/** DROP COLUMN, DROP TABLE, narrow type with existing offenders.
+*  Refuse-to-plan unless `dropped()` / `.narrowedFrom()` declared
+*  OR `VOLTRO_DESTRUCTIVE_OK=1` set. */
+| 'lossy'
+/** Large-table operation that should run online (CREATE INDEX
+*  CONCURRENTLY, batched backfill, shadow-column swap). The applier
+*  auto-rewrites these once the row count crosses the threshold
+*  (`online-after`, default 50k). */
+| 'online-required'
+/** Operations the planner can't infer from a diff (table split /
+*  merge, custom data move, type-change with USING). Requires a
+*  file-based migration in `migrations/<id>.ts`. */
+| 'multi-step';
+
+/**
+ * The vocabulary of concrete DDL-level operations the planner emits.
+ * Each `MigrationOperation` carries one of these kinds plus the data
+ * the applier needs to execute it.
+ *
+ * `kind` strings are short + lowercase-kebab so they round-trip
+ * cleanly through JSON (the `operations` column of `_voltro_migrations`)
+ * and can be grepped in `voltro logs` output.
+ */
+export declare type OperationKind = 'create-table' | 'drop-table' | 'add-column' | 'drop-column' | 'rename-column' | 'alter-column-nullability' | 'alter-column-type' | 'alter-column-default' | 'add-index' | 'drop-index' | 'add-unique' | 'drop-unique' | 'add-enum-value' | 'add-unique-composite' | 'drop-unique-composite' | 'add-foreign-key' | 'drop-foreign-key' | 'add-check' | 'drop-check' | 'reconcile-json-check';
+
+declare interface OrderClause {
+    readonly column: string;
+    readonly direction: 'asc' | 'desc';
+}
+
+declare interface OrderClause_2 {
     readonly column: string;
-} | {
-    readonly kind: 'add-check';
-    readonly table: string;
+    readonly direction: 'asc' | 'desc';
+}
+
+declare interface OrPredicate {
+    readonly or: ReadonlyArray<Predicate>;
+}
+
+declare interface OrPredicate_2 {
+    readonly or: ReadonlyArray<Predicate_2>;
+}
+
+export declare const parseEnumCheck: (clause: string) => {
     readonly column: string;
     readonly values: ReadonlyArray<string>;
-} | {
-    readonly kind: 'drop-check';
-    readonly table: string;
-    readonly column: string;
-} | {
-    readonly kind: 'reconcile-json-check';
-    readonly table: string;
-    readonly column: string;
-    readonly validation: 'value' | 'container';
-    readonly previousValidation: 'value' | 'container' | 'unverified' | 'absent';
-    readonly dropConstraints: ReadonlyArray<string>;
-};
+} | null;
 
-export declare interface MigrationPlan {
-    readonly operations: ReadonlyArray<PlannedOperation>;
-    /** Pre-state fingerprint (live DB at plan time). */
-    readonly fromFingerprint: string;
-    /** Post-state fingerprint (what the DB will look like after apply). */
-    readonly toFingerprint: string;
-    /**
-     * Where the two fingerprints part when the plan is EMPTY. `fromFingerprint`
-     * hashes the whole live introspection; `toFingerprint` hashes the declaration;
-     * a plan of zero operations says the schemas agree — and the hashes can still
-     * differ. Then this names the tables on which they do:
-     *
-     *   `outsideDiff` — live tables the diff never compares: framework-owned
-     *   (`cluster_*`, an undeclared `_voltro_*`), soft-drop snapshots, a name in
-     *   `VOLTRO_DB_IGNORE_TABLES`, the old name of a rename. In the live hash, in
-     *   no declaration.
-     *   `diffEquivalent` — tables on both sides the diff planned nothing for whose
-     *   live and declared snapshots hash apart anyway: a detail introspection
-     *   reports differently from how it was declared.
-     *
-     * Both empty means the hashes agree table for table. A reader who meets two
-     * different hashes over `0 operations` is otherwise left to guess what moved.
-     */
-    readonly fingerprintDivergence: {
-        readonly outsideDiff: ReadonlyArray<string>;
-        readonly diffEquivalent: ReadonlyArray<string>;
-    };
-    /** Count summaries by class — what `voltro db plan` prints. */
-    readonly summary: {
-        readonly safe: number;
-        readonly needsDefault: number;
-        readonly needsBackfill: number;
-        readonly needsRenameAnnotation: number;
-        readonly lossy: number;
-        readonly onlineRequired: number;
-        readonly multiStep: number;
-        readonly blocked: number;
-    };
-}
+/**
+ * The ids of migration files present on disk but NOT yet recorded against THIS
+ * database — i.e. exactly what `runFileBasedMigrations` would execute next.
+ *
+ * Exists so a caller can decide WHETHER to apply before applying. `voltro dev`
+ * uses it to refuse unattended file migrations against a remote database: that
+ * decision needs the list (to name it in the refusal) and must not have run
+ * anything to get it.
+ */
+export declare const pendingFileMigrationIds: (sql: SqlClient.SqlClient, projectRoot: string) => Effect.Effect<ReadonlyArray<string>, unknown>;
 
-declare interface MixinDefinition<F extends Record<string, ColumnDefinition<unknown>>> {
+/**
+ * What `runFileBasedMigrations` would execute next, with the one fact a deploy
+ * has to know BEFORE it starts: whether the migration's `down` is declared
+ * `irreversible()`. A deploy that undoes its own work on failure can undo
+ * every pending migration except those, so they are named in the question
+ * the operator answers, not discovered in the report afterwards.
+ */
+export declare const pendingFileMigrationSummary: (sql: SqlClient.SqlClient, projectRoot: string) => Effect.Effect<ReadonlyArray<{
+    readonly id: string;
+    readonly irreversible: string | undefined;
+}>, unknown>;
+
+export declare interface PlanInput {
+    readonly declared: ReadonlyArray<TableLike>;
+    readonly live: SchemaSnapshot;
     /**
-     * Stable dedup key. Two mixins with the same `id` reaching a table via
-     * different paths (direct + transitive) are materialised once. Convention:
-     * `<pluginNamespace>/<mixinName>` — e.g. `voltro/audit`, `voltro/tenant`,
-     * `acmeBilling/invoiceable`.
+     * Threshold above which safe DDL ops on a populated table get
+     * promoted to `online-required` (CONCURRENTLY / batched / shadow-
+     * column). Pass undefined to use the framework default (50_000).
      */
-    readonly id?: string;
-    readonly fields: F;
+    readonly onlineAfter?: number;
     /**
-     * Other mixins this one needs in place. Resolved depth-first before the
-     * mixin itself is applied, so its `beforeInsert` / `defaultWhere` can rely
-     * on the columns added by its dependencies.
+     * The target dialect. Drives storage-collapse type equivalence (sqlite
+     * stores timestamp/json as TEXT, mssql stores json as NVARCHAR) so the plan
+     * doesn't churn phantom alter-column-type ops. Omit → no collapse (postgres
+     * / mysql / mariadb distinguish these natively anyway).
      */
-    readonly requires?: ReadonlyArray<AnyMixin>;
+    readonly dialect?: DialectId;
     /**
-     * Indexes the mixin contributes when applied to a table. Used by the
-     * built-in `tenant()` mixin to auto-index `tenantId` without
-     * resurrecting a column-level `.index()` modifier (which we
-     * deliberately collapsed into the single table-level surface). The
-     * table-builder merges these into its `appliedIndexes` and
-     * auto-names anonymous entries per-table.
+     * Live tables to LEAVE ALONE — never planned as a drop even though no
+     * declared entity matches them. The framework already self-excludes its own
+     * runtime tables (`_voltro_*` / `_cloud_*` / `cluster_*`, see
+     * `isFrameworkOwnedLiveTable`); this is the USER escape hatch for their own
+     * unmanaged infra tables (e.g. a Strapi→Voltro `_strapi_id_map`), so the diff
+     * doesn't try to drop a table the migration tooling itself depends on. The
+     * CLI populates it from `VOLTRO_DB_IGNORE_TABLES` (comma-separated names).
      */
-    readonly indexes?: ReadonlyArray<MixinIndex>;
-    readonly behaviors?: {
-        readonly beforeInsert?: (...args: unknown[]) => unknown;
-        readonly beforeUpdate?: (...args: unknown[]) => unknown;
-        readonly onDelete?: (...args: unknown[]) => unknown;
-        readonly defaultWhere?: (...args: unknown[]) => unknown;
+    readonly ignoreTables?: ReadonlyArray<string>;
+}
+
+/**
+ * Compute the migration plan between a declared schema (with
+ * annotations) and a live snapshot.
+ *
+ * The output is deterministic: same inputs → same `MigrationPlan`
+ * (modulo op insertion order, which follows table-then-kind sort
+ * order). Lets the applier replay the plan from `_voltro_migration_plans`
+ * without surprises.
+ *
+ * The planner does NOT execute pre-check queries — that's the
+ * applier's job (it needs live SQL access). The classifications here
+ * are based purely on the snapshot shapes + the annotations on
+ * `ColumnDefinition`. The applier may downgrade `safe` → `online-required`
+ * once it knows the row count exceeds the threshold.
+ */
+export declare const planMigrations: (input: PlanInput) => MigrationPlan;
+
+/**
+ * One row in a `MigrationPlan` — a concrete operation paired with the
+ * planner's classification + any blocking reason.
+ *
+ * `blocked` is set when the classification refuses-to-plan (lossy
+ * without `dropped()`, rename without `.renamedFrom()`, etc.). The
+ * applier checks `blocked` before executing; the CLI's `voltro db plan`
+ * output highlights it red.
+ *
+ * `backfill` / `dedup` / `orphanPolicy` mirror the user's annotations
+ * straight from `ColumnDefinition` so the applier doesn't need to
+ * re-introspect them.
+ */
+export declare interface PlannedOperation {
+    readonly op: MigrationOperation;
+    readonly classification: OperationClass;
+    /** Why the op was classified this way (also surfaces in the CLI). */
+    readonly reason?: string;
+    /** Set on lossy / needs-rename / multi-step ops with no resolution. */
+    readonly blocked?: {
+        readonly fix: string;
+    };
+    /** Pre-check estimate the planner ran (row counts, offender count). */
+    readonly estimate?: {
+        readonly affectedRows?: number;
+        readonly offenderCount?: number;
+    };
+    /** Whether the op is atomic for each supported dialect. Postgres,
+     *  mssql, sqlite are atomic for all DDL; mysql/mariadb implicit-commit
+     *  every statement. */
+    readonly atomicByDialect: {
+        readonly postgres: boolean;
+        readonly mysql: boolean;
+        readonly mariadb: boolean;
+        readonly mssql: boolean;
+        readonly sqlite: boolean;
     };
-    readonly policies?: ReadonlyArray<{
-        readonly name: string;
-        readonly predicate: (...args: unknown[]) => boolean;
-    }>;
 }
 
-/**
- * Index contribution from a mixin. The fields are column names that
- * MUST exist either on the host table or on the mixin's own `fields`
- * map. The optional `name` lets the mixin pin the literal index
- * identifier; omitted, the table-builder auto-generates
- * `<tableName>_<col1>_<col2>_idx` so the same mixin applied to
- * different tables produces distinct DDL names.
- */
-declare interface MixinIndex {
-    readonly fields: ReadonlyArray<string>;
-    readonly name?: string;
+/** What happens to the referencing row when the target row goes away. */
+declare type PluginRefOrphanPolicy = 
+/** Delete the referencing row. For a row that only exists to point at it —
+*  a favourite, a pin, a share. */
+'delete'
+/** Null the column, keeping the row. Requires `.nullable()`; declaring it on
+*  a non-nullable column is refused at declaration rather than failing at the
+*  first delete, months later. */
+| 'null'
+/** Do nothing. The explicit "I know, and I handle it myself" — different from
+*  omitting the option, which is the same behaviour arrived at by accident. */
+| 'keep';
+
+declare type Predicate = PredicateLeaf | AndPredicate | OrPredicate | NotPredicate | SubqueryInPredicate | ExistsPredicate;
+
+declare type Predicate_2 = PredicateLeaf_2 | AndPredicate_2 | OrPredicate_2 | NotPredicate_2 | SubqueryInPredicate_2 | ExistsPredicate_2;
+
+declare interface PredicateLeaf {
+    readonly column: string;
+    readonly op: LeafOperator;
+    readonly value?: unknown;
     /**
-     * Index access method. Default `'btree'`. The `vectorEmbedding()` mixin
-     * sets `kind: 'hnsw'` so the vector column it contributes also gets its
-     * ANN index — without resurrecting a column-level `.index()` modifier.
-     * The table-builder forwards `kind` + `kindOptions` into the
-     * `TableIndex` it materialises from this contribution.
+     * JSON-path segments INTO a `json()` column (object keys / array indices).
+     * When set, the leaf filters on the extracted value, not the whole column —
+     * built via {@link jsonField}. The sql compiler lowers it to the dialect's
+     * json-extract expression; the reactive matcher treats it as non-indexable
+     * (rides the unindexed bucket → re-checked on any change to the table, like
+     * `contains`). Absent for a normal column leaf.
      */
-    readonly kind?: IndexKind;
-    /** Per-kind tuning (e.g. `kindOptions.hnsw.{m, efConstruction, distance}`). */
-    readonly kindOptions?: IndexKindOptions;
+    readonly path?: ReadonlyArray<string | number>;
 }
 
-/** Which engine a `mysql`-dialect connection is actually talking to. */
-export declare type MysqlEngine = 'mysql' | 'mariadb';
+declare interface PredicateLeaf_2 {
+    readonly column: string;
+    readonly op: LeafOperator_2;
+    readonly value?: unknown;
+    /**
+     * JSON-path segments INTO a `json()` column (object keys / array indices).
+     * When set, the leaf filters on the extracted value, not the whole column —
+     * built via {@link jsonField}. The sql compiler lowers it to the dialect's
+     * json-extract expression; the reactive matcher treats it as non-indexable
+     * (rides the unindexed bucket → re-checked on any change to the table, like
+     * `contains`). Absent for a normal column leaf.
+     */
+    readonly path?: ReadonlyArray<string | number>;
+}
 
 /**
- * How long a prefix a MySQL/MariaDB index key may take on this column.
+ * 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).
  *
- * `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.
+ * **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.
  *
- * 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.
+ * 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).
  *
- * `undefined` = no prefix clause at all (the column is not text-like, or is
- * unbounded and takes the full 191).
+ * 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 mysqlIndexPrefixFor: (col: ColumnSnapshot | undefined) => number | undefined;
+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>;
 
 /**
- * Type-narrowing migration marker. Tells the planner that this column
- * previously had type `from` and is now being narrowed/converted to its
- * current type. Without `using`, narrowing fails for rows whose value
- * can't fit the new type. The `using` fragment is the dialect-specific
- * cast expression (Postgres `... USING col::int`, MSSQL CONVERT/CAST,
- * MySQL CAST).
+ * The runtime-facing materialized query — a plain bag of strings the store and
+ * the matcher consume.
+ *
+ * `R` is a PHANTOM row type. It exists so the row shape the typed builder
+ * already knows survives the trip through `.descriptor` into `store.query()`,
+ * which is where it used to be thrown away: `store.query(database.notes...)`
+ * returned `Row` (`Record<string, unknown>`), so every field read needed a
+ * hand-written cast. One downstream app wrote 2,032 of them. The type was
+ * always available — it was just dropped at this boundary.
+ *
+ * It is an OPTIONAL field, never set at runtime. That matters for two reasons:
+ * a plain object literal still satisfies `QueryDescriptor` (dispatcher, matcher
+ * and store code build and forward these structurally), and `R` stays
+ * covariant, so a `QueryDescriptor<Note>` is still assignable to the bare
+ * `QueryDescriptor` that generic infrastructure passes around. Defaulting to
+ * `Row` keeps every existing annotation meaning exactly what it meant before.
  */
-declare interface NarrowedFromSpec {
-    readonly from: ColumnType;
+declare interface QueryDescriptor<R = Row> {
+    readonly table: string;
+    readonly predicate: Predicate | undefined;
+    /** Phantom — carries the row type through to `store.query()`. Never set at
+     *  runtime; erased entirely by the compiler. */
+    readonly __row?: R;
+    /**
+     * Opt OUT of the runtime's automatic `deletedAt IS NULL` scope on
+     * `softDelete()` tables. Set by `.withDeleted()`. The query builder is
+     * browser-safe and mixin-unaware, so this is just a flag the RUNTIME
+     * (storeMiddleware read path + reactive-query finalize) honors.
+     */
+    readonly includeDeleted?: boolean;
+    /** Opt OUT of the `expires()` read filter — a deliberate read of expired
+     *  rows (an admin view, a grace-period check). Same shape and same posture as
+     *  `includeDeleted`. */
+    readonly includeExpired?: boolean;
+    /**
+     * Lock the matched rows for the rest of the enclosing transaction — set by
+     * `.forUpdate()`. `SELECT … FOR UPDATE` on postgres / mysql / mariadb,
+     * `WITH (UPDLOCK, ROWLOCK)` on mssql; sqlite serialises writers already and
+     * emits nothing. Outside a transaction the lock is released as the statement
+     * ends, which is harmless and useless — the point is a read-modify-write
+     * whose read and write share one transaction.
+     */
+    readonly lock?: 'update';
+    /**
+     * Opt OUT of the runtime's automatic tenant scope on `tenant()` tables.
+     * Set by `.unscoped()`. Honored by the runtime, same as `includeDeleted`.
+     */
+    readonly crossTenant?: boolean;
+    readonly order: ReadonlyArray<OrderClause>;
+    readonly take: number | undefined;
+    readonly skip: number | undefined;
+    readonly projection: ReadonlyArray<string> | undefined;
+    /**
+     * Aggregate projection. When set, `SELECT` emits the aggregates
+     * instead of row columns; the result is always exactly ONE row
+     * (per group when combined with `groupBy`, ONE row total when not).
+     *
+     * Cannot coexist with `projection` (the two are mutually exclusive
+     * select clauses). The builder enforces this at chain time.
+     */
+    readonly aggregations?: ReadonlyArray<AggregateColumn<unknown>>;
+    /**
+     * `GROUP BY` columns. When set, the query returns ONE row per
+     * distinct combination of these columns + the aggregations.
+     * Requires `aggregations` to be set; ungrouped aggregates always
+     * produce exactly one row.
+     */
+    readonly groupBy?: ReadonlyArray<string>;
+    /**
+     * `HAVING` clause — predicate evaluated AFTER GROUP BY. Distinct
+     * from `predicate` (which becomes `WHERE` and runs BEFORE grouping).
+     * Use HAVING to filter groups based on their aggregate values
+     * (e.g. "users with more than 10 posts").
+     *
+     * Stored as a `Predicate` so the same predicate compiler that
+     * handles WHERE handles HAVING — but the column names on the LHS
+     * of HAVING refer to aggregate aliases, not raw rows.
+     */
+    readonly having?: Predicate;
+    /**
+     * Full-text-search predicate (S7). Set by `.matching('indexName',
+     * 'query')`. `.matching()` resolves the index back to its declared
+     * columns + config + weights from the table registry at call time and
+     * stores them here, so the SQL compiler can emit the right per-dialect
+     * predicate (and an optional relevance-ranking expression) without
+     * re-consulting the registry.
+     *
+     * Per-dialect emission:
+     *   - postgres        → `<tsvCol> @@ plainto_tsquery('<cfg>', ?)`
+     *   - mysql / mariadb → `MATCH(col1, col2) AGAINST (? IN NATURAL LANGUAGE MODE)`
+     *   - sqlite          → `<table>_<idx>_fts MATCH ?` against the FTS5 table
+     *   - mssql           → ranked LOWER(...) LIKE fallback (no server FTS catalog)
+     *
+     * `rank` carries an optional relevance-ranking request. When set, the
+     * compiler also surfaces a synthetic relevance column aliased `rank.alias`
+     * and (when `rank.order` is set) orders by it DESC. The score expression
+     * is per-dialect: postgres `ts_rank`, mysql/mariadb `MATCH ... AGAINST`
+     * score, sqlite FTS5 `bm25`, mssql a LIKE-hit count.
+     */
+    /**
+     * Full-text indexes declared on the FROM table — captured by
+     * `queryFor()` so `.matching()` can resolve an index's columns/config
+     * without a global table-registry lookup. Pure builder metadata; the
+     * SQL compiler never reads it (it reads the resolved `fullTextSearch`).
+     */
+    readonly fullTextIndexes?: ReadonlyArray<{
+        readonly name: string;
+        readonly columns: ReadonlyArray<string>;
+        readonly config?: string;
+        readonly weights?: Readonly<Record<string, 'A' | 'B' | 'C' | 'D'>>;
+    }>;
+    /**
+     * The SOURCE table object this query was built from (`queryFor(t)` / a
+     * `databaseHandle` entry sets it). The eager-load resolver (`.with(...)`)
+     * needs the source table's shape + relations; it used to re-resolve it
+     * BY NAME via `requireTable(descriptor.table)`, which forces every queried
+     * table to be pre-registered (`databaseHandle(...)` / discovery). A direct
+     * query needs no such registration — it carries the object — so an eager
+     * query that threw "table 'X' is not registered" for a table you can query
+     * directly was an asymmetry. Carrying the object here (same precedent as
+     * `fullTextIndexes`) lets the store use it directly, with `requireTable` as
+     * the fallback for reconstructed descriptors (e.g. `paginateById`). NOT
+     * serialized/fingerprinted — the reactive engine keys on table+predicate.
+     */
+    readonly sourceTable?: TableLike;
+    readonly fullTextSearch?: {
+        readonly indexName: string;
+        readonly query: string;
+        /** Columns the index covers — resolved from the table registry. */
+        readonly columns: ReadonlyArray<string>;
+        /** Postgres tsvector config (default 'english'). */
+        readonly config?: string;
+        /** Per-column weight letters (postgres ts_rank). */
+        readonly weights?: Readonly<Record<string, 'A' | 'B' | 'C' | 'D'>>;
+        /** Relevance-ranking request — set by `.rankBy(alias?)`. */
+        readonly rank?: {
+            readonly alias: string;
+            readonly order: boolean;
+        };
+    };
+    /**
+     * Common-Table-Expression definitions (Q4) — `WITH <name> AS (...)`.
+     * Each entry binds a `name` to a sub-query descriptor; the outer
+     * SELECT can reference the CTE by name in `from`, `inSubquery`,
+     * `exists`, etc.
+     *
+     * `.withCte()` adds a non-recursive CTE. For tree-walks use
+     * `.recursiveCte()`, which sets `recursive: true` and emits
+     * `WITH RECURSIVE` (the inner descriptor self-references the CTE
+     * name). Both are reactive — see `runtime/dependencyGraph.ts`.
+     */
+    readonly ctes?: ReadonlyArray<{
+        readonly name: string;
+        readonly descriptor: QueryDescriptor;
+        /**
+         * Recursive CTE marker (Q4 v2). When true, the compiler emits
+         * `WITH RECURSIVE name AS (...)`. The inner descriptor must be a
+         * UNION (via the `union` / `unionAll` helpers) whose first arm is
+         * the anchor and subsequent arms reference the CTE by name (the
+         * recursion). Cycle-detection per-dialect: postgres uses
+         * `UNION` semantics (implicit dedup); other dialects mirror.
+         */
+        readonly recursive?: boolean;
+    }>;
     /**
-     * Raw SQL cast expression spliced into the planner's
-     * `ALTER COLUMN … TYPE … USING <using>` (postgres) / shadow-copy
-     * (`shadow := <using>(old)`). Authored by the developer in the
-     * migration — e.g. `'role::role_enum'`, `'flag::int::text'`. Omit when
-     * the conversion is implicit on the dialect (e.g. `varchar → text`).
+     * SELECT DISTINCT (Q7). When true, dedup rows by the full result
+     * shape. Cross-dialect.
      */
-    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`). */
-declare interface NotPredicate {
-    readonly not: Predicate;
-}
-
-/**
- * DDL fragment for a numeric primary key column. Each dialect has its
- * own auto-increment idiom — there's no portable shorthand, so we
- * dispatch per dialect explicitly. The fragment includes type + PK +
- * auto-increment in one statement; the caller skips the generic
- * `NOT NULL` / `PRIMARY KEY` additions for numeric ids.
- */
-export declare const numericIdSql: (name: string, dialect: DialectId) => string;
-
-/**
- * The seven classes of schema operations the planner recognises. The
- * default policy for each is encoded by the planner; the applier
- * obeys it. Keep this enum in lockstep with the AGENTS.md template's
- * "Schema migrations" section — agents grep for these strings.
- */
-export declare type OperationClass = 
-/** Reversible, side-effect-free for existing data. Auto-applied. */
-'safe'
-/** ADD COLUMN + NOT NULL with `.default(value)` declared.
-*  Applied as `ADD COLUMN ... NOT NULL DEFAULT <value>`. */
-| 'needs-default'
-/** ADD COLUMN + NOT NULL on a populated table, ADD UNIQUE / FK / CHECK
-*  with existing offenders. Requires a deliberate declaration
-*  (`.backfill()`, `.unique({dedup})`, `reference({orphanPolicy})`).
-*  Applied as a three-step plan (ADD nullable → run backfill → SET
-*  NOT NULL). */
-| 'needs-backfill'
-/** Column appears removed + a new one appeared. Looks like DROP+ADD
-*  but is probably a rename. Refuse-to-plan without an explicit
-*  `.renamedFrom('oldName')` marker — silent renames lose data. */
-| 'needs-rename-annotation'
-/** DROP COLUMN, DROP TABLE, narrow type with existing offenders.
-*  Refuse-to-plan unless `dropped()` / `.narrowedFrom()` declared
-*  OR `VOLTRO_DESTRUCTIVE_OK=1` set. */
-| 'lossy'
-/** Large-table operation that should run online (CREATE INDEX
-*  CONCURRENTLY, batched backfill, shadow-column swap). The applier
-*  auto-rewrites these once the row count crosses the threshold
-*  (`online-after`, default 50k). */
-| 'online-required'
-/** Operations the planner can't infer from a diff (table split /
-*  merge, custom data move, type-change with USING). Requires a
-*  file-based migration in `migrations/<id>.ts`. */
-| 'multi-step';
-
-/**
- * The vocabulary of concrete DDL-level operations the planner emits.
- * Each `MigrationOperation` carries one of these kinds plus the data
- * the applier needs to execute it.
- *
- * `kind` strings are short + lowercase-kebab so they round-trip
- * cleanly through JSON (the `operations` column of `_voltro_migrations`)
- * and can be grepped in `voltro logs` output.
- */
-export declare type OperationKind = 'create-table' | 'drop-table' | 'add-column' | 'drop-column' | 'rename-column' | 'alter-column-nullability' | 'alter-column-type' | 'alter-column-default' | 'add-index' | 'drop-index' | 'add-unique' | 'drop-unique' | 'add-unique-composite' | 'drop-unique-composite' | 'add-foreign-key' | 'drop-foreign-key' | 'add-check' | 'drop-check' | 'reconcile-json-check';
-
-declare interface OrderClause {
-    readonly column: string;
-    readonly direction: 'asc' | 'desc';
-}
-
-declare interface OrPredicate {
-    readonly or: ReadonlyArray<Predicate>;
-}
-
-export declare const parseEnumCheck: (clause: string) => {
-    readonly column: string;
-    readonly values: ReadonlyArray<string>;
-} | null;
-
-/**
- * The ids of migration files present on disk but NOT yet recorded against THIS
- * database — i.e. exactly what `runFileBasedMigrations` would execute next.
- *
- * Exists so a caller can decide WHETHER to apply before applying. `voltro dev`
- * uses it to refuse unattended file migrations against a remote database: that
- * decision needs the list (to name it in the refusal) and must not have run
- * anything to get it.
- */
-export declare const pendingFileMigrationIds: (sql: SqlClient.SqlClient, projectRoot: string) => Effect.Effect<ReadonlyArray<string>, unknown>;
-
-export declare interface PlanInput {
-    readonly declared: ReadonlyArray<TableLike>;
-    readonly live: SchemaSnapshot;
+    readonly distinct?: boolean;
     /**
-     * Threshold above which safe DDL ops on a populated table get
-     * promoted to `online-required` (CONCURRENTLY / batched / shadow-
-     * column). Pass undefined to use the framework default (50_000).
+     * SELECT DISTINCT ON (cols) — postgres-only (Q7). Picks ONE row
+     * per distinct combination of `distinctOn` columns; the row picked
+     * is the FIRST per the descriptor's `order`. The compiler emits a
+     * windowed-rownumber fallback on other dialects.
+     *
+     * Common use: "latest message per channel".
      */
-    readonly onlineAfter?: number;
+    readonly distinctOn?: ReadonlyArray<string>;
     /**
-     * The target dialect. Drives storage-collapse type equivalence (sqlite
-     * stores timestamp/json as TEXT, mssql stores json as NVARCHAR) so the plan
-     * doesn't churn phantom alter-column-type ops. Omit → no collapse (postgres
-     * / mysql / mariadb distinguish these natively anyway).
+     * Alias for the FROM table — `FROM <table> AS <alias>` (Q8).
+     * Needed for self-joins where the same table appears multiple
+     * times with different aliases. When unset, the FROM clause is
+     * the bare table name.
      */
-    readonly dialect?: DialectId;
+    readonly alias?: string;
     /**
-     * Live tables to LEAVE ALONE — never planned as a drop even though no
-     * declared entity matches them. The framework already self-excludes its own
-     * runtime tables (`_voltro_*` / `_cloud_*` / `cluster_*`, see
-     * `isFrameworkOwnedLiveTable`); this is the USER escape hatch for their own
-     * unmanaged infra tables (e.g. a Strapi→Voltro `_strapi_id_map`), so the diff
-     * doesn't try to drop a table the migration tooling itself depends on. The
-     * CLI populates it from `VOLTRO_DB_IGNORE_TABLES` (comma-separated names).
+     * Joined tables (Q8). Each entry adds an INNER JOIN or LEFT JOIN
+     * with an explicit ON predicate. Self-joins re-use the same
+     * source table with a different alias.
+     *
+     * `on` is a regular `Predicate` — the leaf columns may carry
+     * `alias.column` style qualifiers since the compiler emits the
+     * column string verbatim.
      */
-    readonly ignoreTables?: ReadonlyArray<string>;
-}
-
-/**
- * Compute the migration plan between a declared schema (with
- * annotations) and a live snapshot.
- *
- * The output is deterministic: same inputs → same `MigrationPlan`
- * (modulo op insertion order, which follows table-then-kind sort
- * order). Lets the applier replay the plan from `_voltro_migration_plans`
- * without surprises.
- *
- * The planner does NOT execute pre-check queries — that's the
- * applier's job (it needs live SQL access). The classifications here
- * are based purely on the snapshot shapes + the annotations on
- * `ColumnDefinition`. The applier may downgrade `safe` → `online-required`
- * once it knows the row count exceeds the threshold.
- */
-export declare const planMigrations: (input: PlanInput) => MigrationPlan;
-
-/**
- * One row in a `MigrationPlan` — a concrete operation paired with the
- * planner's classification + any blocking reason.
- *
- * `blocked` is set when the classification refuses-to-plan (lossy
- * without `dropped()`, rename without `.renamedFrom()`, etc.). The
- * applier checks `blocked` before executing; the CLI's `voltro db plan`
- * output highlights it red.
- *
- * `backfill` / `dedup` / `orphanPolicy` mirror the user's annotations
- * straight from `ColumnDefinition` so the applier doesn't need to
- * re-introspect them.
- */
-export declare interface PlannedOperation {
-    readonly op: MigrationOperation;
-    readonly classification: OperationClass;
-    /** Why the op was classified this way (also surfaces in the CLI). */
-    readonly reason?: string;
-    /** Set on lossy / needs-rename / multi-step ops with no resolution. */
-    readonly blocked?: {
-        readonly fix: string;
-    };
-    /** Pre-check estimate the planner ran (row counts, offender count). */
-    readonly estimate?: {
-        readonly affectedRows?: number;
-        readonly offenderCount?: number;
-    };
-    /** Whether the op is atomic for each supported dialect. Postgres,
-     *  mssql, sqlite are atomic for all DDL; mysql/mariadb implicit-commit
-     *  every statement. */
-    readonly atomicByDialect: {
-        readonly postgres: boolean;
-        readonly mysql: boolean;
-        readonly mariadb: boolean;
-        readonly mssql: boolean;
-        readonly sqlite: boolean;
-    };
-}
-
-/** What happens to the referencing row when the target row goes away. */
-declare type PluginRefOrphanPolicy = 
-/** Delete the referencing row. For a row that only exists to point at it —
-*  a favourite, a pin, a share. */
-'delete'
-/** Null the column, keeping the row. Requires `.nullable()`; declaring it on
-*  a non-nullable column is refused at declaration rather than failing at the
-*  first delete, months later. */
-| 'null'
-/** Do nothing. The explicit "I know, and I handle it myself" — different from
-*  omitting the option, which is the same behaviour arrived at by accident. */
-| 'keep';
-
-declare type Predicate = PredicateLeaf | AndPredicate | OrPredicate | NotPredicate | SubqueryInPredicate | ExistsPredicate;
-
-declare interface PredicateLeaf {
-    readonly column: string;
-    readonly op: LeafOperator;
-    readonly value?: unknown;
+    readonly joins?: ReadonlyArray<{
+        readonly kind: 'inner' | 'left';
+        readonly table: string;
+        readonly alias: string;
+        readonly on: Predicate;
+    }>;
+    /**
+     * Aliased projection for joined queries (Q8 v2). When set, the
+     * SELECT emits `alias.col AS outputKey` for each entry, producing
+     * a flat row with the user's chosen keys.
+     *
+     * Mutually exclusive with `projection` (regular select-cols).
+     * Bypassed by `aggregations`.
+     */
+    readonly joinedProjection?: ReadonlyArray<{
+        readonly outputKey: string;
+        readonly source: string;
+    }>;
     /**
-     * JSON-path segments INTO a `json()` column (object keys / array indices).
-     * When set, the leaf filters on the extracted value, not the whole column —
-     * built via {@link jsonField}. The sql compiler lowers it to the dialect's
-     * json-extract expression; the reactive matcher treats it as non-indexable
-     * (rides the unindexed bucket → re-checked on any change to the table, like
-     * `contains`). Absent for a normal column leaf.
+     * Set-operation composition (Q6). When set, the SELECT shape is
+     * replaced by `(SELECT ...) <OP> (SELECT ...) ...`.
+     *
+     * - `'union'`           → dedup-merge (`UNION`)
+     * - `'union-all'`       → no dedup (`UNION ALL`)
+     * - `'intersect'`       → rows in BOTH (`INTERSECT`)
+     * - `'except'`          → rows in LHS not in RHS (`EXCEPT`)
+     *
+     * All four are standard SQL + supported on every dialect we ship.
      */
-    readonly path?: ReadonlyArray<string | number>;
+    readonly setOp?: {
+        readonly kind: 'union' | 'union-all' | 'intersect' | 'except';
+        readonly queries: ReadonlyArray<QueryDescriptor>;
+    };
+    /**
+     * Optional index hint. Set by `.using('indexName')` on the query
+     * builder. The framework stores it on the descriptor for two reasons:
+     *
+     *   1. Suppresses the dev-mode "non-indexed query" warning for this
+     *      descriptor (the user explicitly signalled they thought about
+     *      the access pattern).
+     *   2. The matcher's tuple-routing path keys subscriptions on the
+     *      declared index's column set — see `IndexedMatcher` in
+     *      `@voltro/runtime/matcher.ts`. Subscriptions that declare a
+     *      covering index get O(1) candidate lookup per event instead
+     *      of column-union routing.
+     */
+    readonly usingIndex?: string;
+    /**
+     * Eager-load tree declared via `.with({ ... })`. Consumed by the
+     * JoinCompiler (`./joinCompiler.ts`) when present — the SQL stores
+     * dispatch nested-JSON-aggregation queries; the in-memory store
+     * walks it via post-hoc lookups.
+     */
+    readonly eager?: WithSpec;
+    /**
+     * Approximate-nearest-neighbour clause (plan 01). Set by
+     * `.nearestNeighbours(...)`. Drives a synthetic `distance` projection
+     * + `ORDER BY <col> <op> <query>` in the SQL compiler:
+     *
+     *   - postgres (pgvector): `<col> <=> $q` (cosine) / `<->` (l2) /
+     *     `<#>` (inner).
+     *   - mariadb / mysql: `VEC_DISTANCE_COSINE/EUCLIDEAN(<col>, $q)`.
+     *   - mssql / sqlite: no portable ANN operator → the compiler warns +
+     *     skips the distance ordering (sequential scan; rows still return).
+     *
+     * `queryVector` is the literal float array; `queryText` is the
+     * raw string the runtime embeds to a vector *before* compiling
+     * (only valid when the table carries `vectorEmbedding()`). Exactly
+     * one of the two is set.
+     */
+    readonly annClause?: AnnClause;
+    /**
+     * PostGIS spatial distance clause (`@voltro/plugin-postgis`). Set by the
+     * `withDistance(...)` / `nearestBy(...)` transforms applied via `.use(...)`.
+     * Postgres-only — the SQL compiler lowers it to a `ST_Distance(...)`
+     * projected column and/or a `<->` KNN `ORDER BY`; on any non-postgres
+     * dialect the compiler THROWS (mirrors the spatial predicate + column
+     * guards). Never evaluated in-memory (no PostGIS in JS). Composes with
+     * `.where(...)`, `.limit(k)`, spatial predicates, etc.
+     */
+    readonly spatialClause?: SpatialClause;
 }
 
-/**
- * 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, options?: SchemaApplyOptions) => Promise<void>;
-
 /**
  * The runtime-facing materialized query — a plain bag of strings the store and
  * the matcher consume.
@@ -2180,9 +4246,9 @@ export declare const provisionTenantNamespace: (tables: ReadonlyArray<AnyTable>,
  * `QueryDescriptor` that generic infrastructure passes around. Defaulting to
  * `Row` keeps every existing annotation meaning exactly what it meant before.
  */
-declare interface QueryDescriptor<R = Row> {
+declare interface QueryDescriptor_2<R = Row_2> {
     readonly table: string;
-    readonly predicate: Predicate | undefined;
+    readonly predicate: Predicate_2 | undefined;
     /** Phantom — carries the row type through to `store.query()`. Never set at
      *  runtime; erased entirely by the compiler. */
     readonly __row?: R;
@@ -2211,7 +4277,7 @@ declare interface QueryDescriptor<R = Row> {
      * Set by `.unscoped()`. Honored by the runtime, same as `includeDeleted`.
      */
     readonly crossTenant?: boolean;
-    readonly order: ReadonlyArray<OrderClause>;
+    readonly order: ReadonlyArray<OrderClause_2>;
     readonly take: number | undefined;
     readonly skip: number | undefined;
     readonly projection: ReadonlyArray<string> | undefined;
@@ -2223,7 +4289,7 @@ declare interface QueryDescriptor<R = Row> {
      * Cannot coexist with `projection` (the two are mutually exclusive
      * select clauses). The builder enforces this at chain time.
      */
-    readonly aggregations?: ReadonlyArray<AggregateColumn<unknown>>;
+    readonly aggregations?: ReadonlyArray<AggregateColumn_2<unknown>>;
     /**
      * `GROUP BY` columns. When set, the query returns ONE row per
      * distinct combination of these columns + the aggregations.
@@ -2241,7 +4307,7 @@ declare interface QueryDescriptor<R = Row> {
      * handles WHERE handles HAVING — but the column names on the LHS
      * of HAVING refer to aggregate aliases, not raw rows.
      */
-    readonly having?: Predicate;
+    readonly having?: Predicate_2;
     /**
      * Full-text-search predicate (S7). Set by `.matching('indexName',
      * 'query')`. `.matching()` resolves the index back to its declared
@@ -2287,7 +4353,7 @@ declare interface QueryDescriptor<R = Row> {
      * the fallback for reconstructed descriptors (e.g. `paginateById`). NOT
      * serialized/fingerprinted — the reactive engine keys on table+predicate.
      */
-    readonly sourceTable?: TableLike;
+    readonly sourceTable?: TableLike_2;
     readonly fullTextSearch?: {
         readonly indexName: string;
         readonly query: string;
@@ -2316,7 +4382,7 @@ declare interface QueryDescriptor<R = Row> {
      */
     readonly ctes?: ReadonlyArray<{
         readonly name: string;
-        readonly descriptor: QueryDescriptor;
+        readonly descriptor: QueryDescriptor_2;
         /**
          * Recursive CTE marker (Q4 v2). When true, the compiler emits
          * `WITH RECURSIVE name AS (...)`. The inner descriptor must be a
@@ -2361,7 +4427,7 @@ declare interface QueryDescriptor<R = Row> {
         readonly kind: 'inner' | 'left';
         readonly table: string;
         readonly alias: string;
-        readonly on: Predicate;
+        readonly on: Predicate_2;
     }>;
     /**
      * Aliased projection for joined queries (Q8 v2). When set, the
@@ -2388,7 +4454,7 @@ declare interface QueryDescriptor<R = Row> {
      */
     readonly setOp?: {
         readonly kind: 'union' | 'union-all' | 'intersect' | 'except';
-        readonly queries: ReadonlyArray<QueryDescriptor>;
+        readonly queries: ReadonlyArray<QueryDescriptor_2>;
     };
     /**
      * Optional index hint. Set by `.using('indexName')` on the query
@@ -2410,7 +4476,7 @@ declare interface QueryDescriptor<R = Row> {
      * dispatch nested-JSON-aggregation queries; the in-memory store
      * walks it via post-hoc lookups.
      */
-    readonly eager?: WithSpec;
+    readonly eager?: WithSpec_2;
     /**
      * Approximate-nearest-neighbour clause (plan 01). Set by
      * `.nearestNeighbours(...)`. Drives a synthetic `distance` projection
@@ -2427,7 +4493,7 @@ declare interface QueryDescriptor<R = Row> {
      * (only valid when the table carries `vectorEmbedding()`). Exactly
      * one of the two is set.
      */
-    readonly annClause?: AnnClause;
+    readonly annClause?: AnnClause_2;
     /**
      * PostGIS spatial distance clause (`@voltro/plugin-postgis`). Set by the
      * `withDistance(...)` / `nearestBy(...)` transforms applied via `.use(...)`.
@@ -2437,7 +4503,7 @@ declare interface QueryDescriptor<R = Row> {
      * guards). Never evaluated in-memory (no PostGIS in JS). Composes with
      * `.where(...)`, `.limit(k)`, spatial predicates, etc.
      */
-    readonly spatialClause?: SpatialClause;
+    readonly spatialClause?: SpatialClause_2;
 }
 
 declare const quote: (name: string) => string;
@@ -2497,6 +4563,19 @@ export declare interface ReactiveTriggerDrift {
      * business, not this one's.
      */
     readonly functionOutdated: boolean;
+    /**
+     * What the verdict was measured against — so a report that contradicts a
+     * `db apply` that just installed the triggers can be read: the schema the
+     * detector looked in, the channel it derived the names from, and how many
+     * `framework_changes_*` triggers it found there at all. A consumer measured
+     * "71 have NO trigger" eleven seconds after their migrate job installed 71,
+     * and nothing in the line said which schema or channel was compared.
+     */
+    readonly compared?: {
+        readonly schema: string;
+        readonly channel: string;
+        readonly present: number;
+    };
 }
 
 /**
@@ -2649,6 +4728,39 @@ export declare const resolveMysqlEngine: (sql: SqlClient.SqlClient) => Effect.Ef
 
 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);
+}
+
 /**
  * Roll back a single file-based migration by id. Looks up the
  * migration's `down` body via file discovery (the file must still be
@@ -2663,6 +4775,7 @@ export declare const rollbackFileBasedMigration: (sql: SqlClient.SqlClient, ctx:
     projectRoot: string;
     id: string;
     lockSchema?: string;
+    store: DataStore;
 }) => Effect.Effect<{
     id: string;
     durationMs: number;
@@ -2700,6 +4813,11 @@ export declare const rollingDeployUnsafeOps: (operations: ReadonlyArray<PlannedO
 
 declare type Row = Readonly<Record<string, unknown>>;
 
+declare type Row_2 = Readonly<Record<string, unknown>>;
+
+/** Addresses one row: its `id`, or the columns of an explicit primary key. */
+declare type RowKey = string | Readonly<Record<string, unknown>>;
+
 /** The context a rule predicate is evaluated with. */
 declare interface RuleContext {
     /** Transactional store — read other tables in the mutation's snapshot. */
@@ -2750,6 +4868,19 @@ export declare interface RunFileBasedMigrationsCtx {
     readonly projectRoot: string;
     readonly env: 'dev' | 'staging' | 'prod';
     readonly appliedBy: string;
+    /** The application's data store over the same database `sql` is connected
+     *  to — what a migration body receives as `ctx.store`. Required, not
+     *  optional: a runner that can leave it out is a runner that hands one body
+     *  a store and the next one an error, depending on which command ran it. */
+    readonly store: DataStore;
+    /**
+     * The caller holds a transaction the whole run is part of — `voltro db apply`
+     * on a dialect with transactional DDL runs the file migrations and the
+     * schema plan as ONE unit. Each migration then runs on the given store and
+     * connection without a transaction of its own (nesting would be a mistake)
+     * and without the commit probe (the caller's unit is the guarantee).
+     */
+    readonly enclosed?: boolean;
     /** Schema scope for the migration advisory lock (see `migrations/lock.ts`).
      *  Absent → resolved from configuration (`DB_SCHEMA`). */
     readonly lockSchema?: string;
@@ -2775,6 +4906,17 @@ export declare const runFrameworkBootstrap: (tables: ReadonlyArray<AnyTable>, sq
  */
 export declare const runMigrate: (tables: ReadonlyArray<AnyTable>, sqlLayer: Layer.Layer<SqlClient.SqlClient, ConfigError.ConfigError | SqlError.SqlError, never>, dialect?: DialectId, options?: SchemaApplyOptions) => Promise<void>;
 
+/**
+ * Execute ONE planned operation with the applier's own per-dialect
+ * statements, outside a plan — for a file migration's schema helpers
+ * (`ctx.schema.addColumn`, `addIndex`, `createTable`, …), which construct the
+ * operation from the live table and hand it here. `declared` is what the
+ * mysql MODIFY, the mssql prefix rules and the sqlite rebuild read the target
+ * 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>;
+
 /**
  * Top-level entry point — called once per boot. Returns a
  * `BootMigrationOutcome`; the caller logs + acts on it (refuse-to-boot
@@ -2795,6 +4937,19 @@ export declare interface RunPlannedMigrationsCtx {
     readonly softDropRetentionDays?: number;
 }
 
+/**
+ * Execute ONE schema operation against the database as it is, with the same
+ * per-dialect statements the planner's applier uses — so a migration body
+ * that needs to drop a foreign key, an index or a column, or rename a column,
+ * gets the dialect right without spelling it. `live` is the snapshot the
+ * caller just read; on sqlite it is what the rebuild is computed from.
+ *
+ * Existence is the CALLER's question (`fileContext.ts` reads the snapshot and
+ * 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>;
+
 /**
  * Effect that applies the emitted DDL to the provided SqlClient. Splits
  * on `;` only outside dollar-quoted blocks (the postgres NOTIFY trigger
@@ -2825,6 +4980,9 @@ export declare interface SchemaApplyOptions {
     readonly lockSchema?: string;
 }
 
+/** 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
@@ -2847,7 +5005,9 @@ export declare const shortFingerprint: (fp: string) => string;
  * trip to/from `information_schema`. `idScheme.kind` IS carried — the
  * applier needs it to emit auto-increment DDL for numeric ids.
  */
-export declare const snapshotColumn: (name: string, def: ColumnDefinition<unknown>) => ColumnSnapshot;
+export declare const snapshotColumn: (name: string, def: ColumnDefinition<unknown>, 
+/** Needed only for `storageType` — a caller that renders DDL does not want it. */
+dialect?: DialectId) => ColumnSnapshot;
 
 /**
  * PostGIS spatial-distance clause carried on a {@link QueryDescriptor}.
@@ -2884,6 +5044,41 @@ declare interface SpatialClause {
     readonly order?: 'asc' | 'desc';
 }
 
+/**
+ * PostGIS spatial-distance clause carried on a {@link QueryDescriptor}.
+ * Drives a `ST_Distance` projected column (distance-as-a-value) and/or a
+ * `<->` nearest-neighbour `ORDER BY` (KNN). Built by `@voltro/plugin-postgis`;
+ * postgres-only (the compiler throws on other dialects).
+ */
+declare interface SpatialClause_2 {
+    /** The spatial column to measure from. */
+    readonly column: string;
+    /** The comparison geometry as WKT/EWKT (e.g. `SRID=4326;POINT(8 50)`). Bound as a parameter. */
+    readonly geom: string;
+    /**
+     * Measure metric metres via a `::geography` cast on both operands
+     * (great-circle distance). When false, distance is in the SRID's own
+     * planar units (`::geometry`). Default true — the "distance in metres"
+     * users expect for lat/lon data.
+     */
+    readonly useGeography: boolean;
+    /**
+     * When set, surface the distance as a projected column aliased this name
+     * (`ST_Distance(col, geom) AS "<projectAs>"`). The row type gains a
+     * `number` field. Absent → no distance projection (KNN-order-only).
+     */
+    readonly projectAs?: string;
+    /**
+     * When set, add a KNN `ORDER BY col <-> geom <dir>` clause (indexed
+     * nearest-neighbour when a GiST index covers the column). Leads any
+     * explicit `.orderBy(...)`. Absent → no spatial ordering. `<->` is always
+     * a planar operator (postgres has no geography `<->`), so KNN ordering
+     * ranks by planar distance even when `useGeography` is true for the
+     * projected metric distance.
+     */
+    readonly order?: 'asc' | 'desc';
+}
+
 /**
  * The `sql` template tag — captures a tagged-template literal into a
  * {@link RawSqlFragment} descriptor without binding it to any client.
@@ -2972,6 +5167,25 @@ declare interface SubqueryInPredicate {
     readonly subquery: QueryDescriptor;
 }
 
+/**
+ * `col IN (SELECT col FROM ...)` / `col NOT IN (SELECT ...)` — the
+ * RHS is a sub-query descriptor. The sub-query MUST project a
+ * single column (via `.select('col')`); the SQL compiler emits the
+ * full inner SELECT inline, and the in-memory store evaluates the
+ * sub-query first + then runs the IN check against the materialized
+ * set.
+ *
+ * The sub-query is non-correlated in v1 — it can't reference outer
+ * row columns. Correlated sub-queries (`WHERE EXISTS (... WHERE
+ * inner.userId = outer.id)`) would require a table-alias mechanism;
+ * tracked separately.
+ */
+declare interface SubqueryInPredicate_2 {
+    readonly column: string;
+    readonly op: 'subquery-in' | 'subquery-not-in';
+    readonly subquery: QueryDescriptor_2;
+}
+
 declare interface Table<Name extends string, Fields extends Record<string, ColumnDefinition<unknown>>, Reactive extends boolean = true, IxNames extends string = never> extends TableLike {
     readonly tableName: Name;
     readonly fields: Fields;
@@ -3507,6 +5721,11 @@ declare interface TableLike {
     readonly fields: Record<string, ColumnDefinition<unknown>>;
 }
 
+declare interface TableLike_2 {
+    readonly tableName: string;
+    readonly fields: Record<string, ColumnDefinition_2<unknown>>;
+}
+
 /**
  * A named cross-table business rule, attached by `.rule(name, predicate)`.
  *
@@ -3560,8 +5779,26 @@ declare interface TableUnique {
     };
 }
 
+/**
+ * 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);
+}
+
 export declare const unblockLossy: (plan: MigrationPlan, scope?: ReturnType<typeof destructiveScope>) => MigrationPlan;
 
+/** Every deploy that did not finish — `running` (the process died) or `failed` (its undo did not complete). An absent table is an empty ledger. */
+export declare const unfinishedDeploys: (sql: SqlClient.SqlClient) => Effect.Effect<ReadonlyArray<DeployLedgerRow>, never>;
+
 /**
  * Unique-constraint metadata. Set by `.unique()` (or `.unique({ dedup })`).
  *
@@ -3579,6 +5816,43 @@ declare interface UniqueSpec {
     readonly dedup?: 'fail' | 'suffix-counter' | Statement.Fragment;
 }
 
+/**
+ * Unique-constraint metadata. Set by `.unique()` (or `.unique({ dedup })`).
+ *
+ * The planner reads `dedup` when ADD UNIQUE is applied to a populated
+ * column — without it, the constraint fails for any existing duplicates.
+ *
+ * - `'fail'`     — refuse to migrate; surface offending rows in the plan
+ *                  output (the safe default).
+ * - `'suffix-counter'` — auto-rename duplicates `value`, `value-2`,
+ *                  `value-3`, … (only sensible for text columns).
+ * - `sql\`...\`` — custom UPDATE expression keyed off `id` /
+ *                  ROW_NUMBER() to disambiguate.
+ */
+declare interface UniqueSpec_2 {
+    readonly dedup?: 'fail' | 'suffix-counter' | Statement.Fragment;
+}
+
+declare interface UpsertOptions {
+    conflictColumns: ReadonlyArray<string>;
+    update?: ReadonlyArray<string> | ((existing: Row_2) => Readonly<Record<string, unknown>>);
+    /**
+     * Additional assignments on CONFLICT only; never part of the INSERT row.
+     * Defined values override the `update` projection (including callback results).
+     * `undefined` is omitted; explicit `null`, false, zero and empty strings are
+     * preserved. Cannot rewrite `id` or a conflict column. Column-list/default
+     * upserts keep their dialect's native statement instead of becoming callbacks.
+     */
+    readonly updateValues?: Readonly<Record<string, unknown>>;
+}
+
+/** What an `upsertWithOutcome` did, beside the row it wrote. */
+declare interface UpsertResult {
+    readonly row: Row_2;
+    /** `'updated'` means the statement landed on a row that already existed. */
+    readonly outcome: 'inserted' | 'updated';
+}
+
 /**
  * Vector distance metric. Drives the HNSW opclass at index-build time and
  * the distance operator at query time — the two MUST agree or the index
@@ -3589,6 +5863,16 @@ declare interface UniqueSpec {
  */
 declare type VectorDistance = 'cosine' | 'l2' | 'inner';
 
+/**
+ * Vector distance metric. Drives the HNSW opclass at index-build time and
+ * the distance operator at query time — the two MUST agree or the index
+ * can't accelerate the search.
+ *   - `'cosine'` — 1 − cosine similarity (pgvector `<=>`)
+ *   - `'l2'`     — Euclidean distance (pgvector `<->`)
+ *   - `'inner'`  — negative inner product (pgvector `<#>`)
+ */
+declare type VectorDistance_2 = 'cosine' | 'l2' | 'inner';
+
 /**
  * A read-only SQL view descriptor. Structurally a `TableLike` (carries
  * `tableName` + `fields`) so the query builder + row decoder + by-name
@@ -3621,6 +5905,9 @@ declare interface View<Name extends string, Fields extends Record<string, Column
  */
 export declare const VOLTRO_MIGRATION_LOCK_KEY = 6322741009312437n;
 
+/** Index-free for the same reason `_voltro_migration_ops` is: at most a row or two, ever. */
+export declare const _voltroDeploysTable: TableLike;
+
 /**
  * One aggregate column in a `SELECT` projection — `COUNT(*)`,
  * `SUM(amount) AS total`, etc. Built via the `count() / sum() /
@@ -3647,9 +5934,38 @@ declare interface WindowSpec {
     }>;
 }
 
+/**
+ * One aggregate column in a `SELECT` projection — `COUNT(*)`,
+ * `SUM(amount) AS total`, etc. Built via the `count() / sum() /
+ * avg() / min() / max() / countDistinct()` helpers exported from
+ * `@voltro/database`.
+ *
+ * `column` is undefined for `count()` (which compiles to `COUNT(*)`)
+ * and required for every other op. `alias` is the column name on the
+ * result row.
+ */
+/**
+ * Window-function spec (Q3). When set on an AggregateColumn, the
+ * compiler emits `<OP>(...) OVER (PARTITION BY ... ORDER BY ...)`
+ * instead of a plain aggregate. The query is reactive coarsely — the
+ * matcher can't bucket on a window-function result, so the engine
+ * widens the dependency to the whole source table and re-queries on
+ * any write to it (see `runtime/relevantFields.ts`).
+ */
+declare interface WindowSpec_2 {
+    readonly partitionBy?: ReadonlyArray<string>;
+    readonly orderBy?: ReadonlyArray<{
+        column: string;
+        direction: 'asc' | 'desc';
+    }>;
+}
+
 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>>;
 
+/** Tree of relations to eager-load. */
+declare type WithSpec_2 = Readonly<Record<string, true | EagerLoadSpec_2>>;
+
 export { }