@voltro/database 0.1.0

package/dist/sql.d.ts

@@ -0,0 +1,2023 @@
+import { ConfigError } from 'effect';
+import { Effect } from 'effect';
+import { Layer } from 'effect';
+import { Schema } from 'effect';
+import { SqlClient } from '@effect/sql';
+import { SqlError } from '@effect/sql';
+import { SqlError as SqlError_2 } from '@effect/sql/SqlError';
+import { Statement } from '@effect/sql';
+
+export declare const acquireMigrationLock: (sql: SqlClient.SqlClient) => Effect.Effect<void, SqlError_2>;
+
+declare type AnyMixin = MixinDefinition<Record<string, ColumnDefinition<unknown>>>;
+
+declare type AnyTable = Table<string, Record<string, ColumnDefinition<unknown>>, boolean, string>;
+
+declare type AnyView = View<string, Record<string, ColumnDefinition<unknown>>>;
+
+/**
+ * One row of `_voltro_migrations` — what the applier writes after a
+ * successful plan execution. Same shape exposed via inspect RPC for
+ * devtools / cloud dashboards.
+ */
+export declare interface AppliedMigration {
+    readonly id: string;
+    readonly appliedAt: string;
+    readonly fingerprint: string;
+    readonly operations: ReadonlyArray<PlannedOperation>;
+    readonly appliedBy: string;
+    readonly environment: 'dev' | 'staging' | 'prod';
+    readonly rollbackPlan?: ReadonlyArray<MigrationOperation>;
+    readonly durationMs: number;
+    readonly onlineStrategy?: 'inline' | 'concurrent' | 'batched' | 'shadow-column';
+    readonly source: 'auto-diff' | 'file';
+    readonly notes?: string;
+}
+
+/** Result of executing one op (per-step instrumentation). */
+export declare interface AppliedOp {
+    readonly op: MigrationOperation;
+    readonly status: 'applied' | 'skipped';
+    readonly durationMs: number;
+}
+
+/**
+ * Apply the schema DDL for a SINGLE tenant namespace: create the
+ * container (schema / database / attached file), then create the tenant's
+ * tables inside it. This is the migration-time fan-out for namespace
+ * isolation — call it once per active tenant namespace, OR lazily on a
+ * tenant's first request (the runtime can call this to provision a new
+ * tenant's namespace on demand).
+ *
+ * Idempotent: the container DDL uses `IF NOT EXISTS` / guards, and the
+ * table DDL is the same `CREATE TABLE IF NOT EXISTS` path the shared
+ * migrate uses — re-running against an already-provisioned namespace is a
+ * no-op (except sqlite's ATTACH, which the splitter runs standalone and
+ * whose "already attached" error the caller can ignore).
+ */
+export declare const applyNamespacedSchema: (tables: ReadonlyArray<AnyTable>, namespace: string, dialect?: DialectId) => Effect.Effect<void, never, SqlClient.SqlClient>;
+
+/**
+ * Execute a `MigrationPlan` against the connected database.
+ *
+ * Behaviour:
+ *
+ *   1. If the plan has ANY blocked operation, throw before touching
+ *      the DB. Callers should run `voltro db plan` first + resolve.
+ *   2. Acquire the advisory lock (per-dialect; postgres v1).
+ *   3. For each op in plan order: emit the DDL, run any backfill,
+ *      mark applied.
+ *   4. Write a row to `_voltro_migration_plans` with the post-state
+ *      fingerprint + operations JSON + duration + environment.
+ *   5. Release the advisory lock.
+ *
+ * The return value is the `AppliedMigration` row — the same shape
+ * used by the inspect RPC + the cloud dashboard timeline.
+ */
+export declare const applyPlan: (sql: SqlClient.SqlClient, plan: MigrationPlan, ctx: ApplyPlanCtx) => Effect.Effect<AppliedMigration, SqlError_2, SqlClient.SqlClient>;
+
+export declare interface ApplyPlanCtx {
+    /** Tables declared by user code — needed to look up
+     *  `.backfill()` specs for add-column ops, since the snapshot
+     *  doesn't carry them. */
+    readonly declared: ReadonlyArray<TableLike>;
+    /** `dev:boot` | `cli:user` | service-principal. Written to
+     *  `_voltro_migration_plans.appliedBy`. */
+    readonly appliedBy: string;
+    /** Set from `NODE_ENV` upstream. */
+    readonly environment: 'dev' | 'staging' | 'prod';
+    /** `auto-diff` (planner) or `file` (file-based migration). */
+    readonly source: 'auto-diff' | 'file';
+    /** Optional human note via `voltro db apply --note "..."`. */
+    readonly notes?: string;
+}
+
+/**
+ * Effect that applies the emitted DDL to the provided SqlClient. Splits
+ * on `;` only outside dollar-quoted blocks (the postgres NOTIFY trigger
+ * function body uses `$$`), so the plpgsql block stays intact as a
+ * single statement. SQLite has no `$$` quoting so the splitter is a
+ * superset.
+ *
+ * Caller passes the dialect explicitly. Defaults to `'postgres'` for
+ * call-sites that haven't migrated yet.
+ */
+export declare const applySchema: (tables: ReadonlyArray<AnyTable>, dialect?: DialectId) => Effect.Effect<void, never, SqlClient.SqlClient>;
+
+/** Per-row backfill body executed by the migration runner. */
+declare type BackfillFunction<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>`.
+     *   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<TsType>;
+    readonly batchSize?: number;
+    readonly sleepMs?: number;
+}
+
+export declare type BootEnvironment = 'dev' | 'staging' | 'prod';
+
+export declare type BootMigrationOutcome = {
+    readonly kind: 'skipped';
+    readonly reason: 'VOLTRO_AUTO_MIGRATE=0';
+} | {
+    readonly kind: 'up-to-date';
+    readonly fingerprint: string;
+} | {
+    readonly kind: 'applied';
+    readonly applied: AppliedMigration;
+    readonly plan: MigrationPlan;
+} | {
+    readonly kind: 'prod-mismatch';
+    readonly expected: string;
+    readonly actual?: string | undefined;
+} | {
+    readonly kind: 'refused-blocked';
+    readonly plan: MigrationPlan;
+};
+
+/** 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. */
+export declare const chunkTables: <T>(xs: ReadonlyArray<T>, n: number) => T[][];
+
+declare interface ColumnDefinition<TsType, Type extends ColumnType = ColumnType> {
+    readonly type: Type;
+    readonly nullable: boolean;
+    readonly unique: boolean;
+    readonly hasDefault: boolean;
+    readonly defaultValue?: unknown;
+    /**
+     * 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;
+    /**
+     * 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.
+     *
+     * Example: `slug: text().computed(row => slugify(row.title))`.
+     *
+     * If the computed function reads a column the row doesn't carry,
+     * it gets `undefined` — handle that in the function.
+     */
+    readonly computed?: (row: Readonly<Record<string, unknown>>) => unknown;
+    readonly onUpdate?: 'now' | (() => unknown);
+    readonly references?: () => TableLike;
+    /**
+     * 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 onDelete?: 'cascade' | 'restrict' | 'setNull' | 'noAction';
+    /**
+     * 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 refOnUpdate?: 'cascade' | 'restrict' | 'setNull' | 'noAction';
+    /**
+     * 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 fkAutoIndex?: boolean;
+    readonly jsonType?: unknown;
+    /**
+     * Closed value set, set by `text().oneOf([...])`. When present:
+     *
+     *   - 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).
+     *
+     * 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 oneOf?: ReadonlyArray<string>;
+    /**
+     * 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 maxLength?: number;
+    /**
+     * 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 checks?: ReadonlyArray<string>;
+    /**
+     * DB-level generated column. Set by `.generatedAs(expr, { stored })`.
+     *
+     * 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`).
+     *
+     * `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.
+     *
+     * 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 generatedAs?: {
+        readonly expr: string;
+        readonly stored: boolean;
+    };
+    /**
+     * Postgres-native ENUM type binding, populated when the column is
+     * built from `dbEnum(...).column()`. Distinct from `oneOf`:
+     *
+     *   - 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;
+    /**
+     * 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 the Secrets-Resolver — see `@voltro/plugin-governance`).
+     * The stored column is an opaque `enc:v1:…` string, so 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 fails loud if an `.encrypted()` column is present but
+     * no cipher is registered.
+     */
+    readonly encrypted?: 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;
+    /**
+     * 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;
+    /**
+     * 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<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;
+    /**
+     * 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;
+    /**
+     * 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 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;
+    };
+    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';
+    };
+    /** `oneOf(['a','b'])` → CHECK constraint values. */
+    readonly oneOf?: ReadonlyArray<string>;
+    /**
+     * 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;
+    };
+    /**
+     * 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;
+}
+
+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>) => SchemaSnapshot;
+
+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;
+
+/** 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 const emitDropColumnDdl: (op: Extract<MigrationOperation, {
+    kind: "drop-column";
+}>, q: typeof quote) => string;
+
+export declare const emitDropColumnDdlMysql: (op: Extract<MigrationOperation, {
+    kind: "drop-column";
+}>) => string;
+
+/**
+ * Evolution-aware DDL emitter for framework-managed tables (the
+ * `_voltro_*` bookkeeping set + the `voltro_isr_cache` runtime
+ * cache). Adds one extra step between CREATE TABLE and CREATE INDEX:
+ *
+ *   ALTER TABLE <t> ADD COLUMN IF NOT EXISTS <col> <type>
+ *
+ * for every column the framework's declared shape carries. Without
+ * this the CREATE TABLE IF NOT EXISTS path is fine for fresh DBs but
+ * silently no-ops on existing tables — subsequent CREATE INDEX IF
+ * NOT EXISTS then PARSE-fails when an index references a column the
+ * framework added in a later release that the live DB never picked
+ * up (pg error 42703).
+ *
+ * Postgres-only — the other dialects' framework-bookkeeping path
+ * doesn't suffer this because @effect/sql-cluster / migrationRunner
+ * own their own schema. The applier in the per-dialect packages does
+ * the equivalent work for their own bookkeeping.
+ *
+ * For user / plugin / cloud tables this path is wrong — they need the
+ * full planner refuse-to-boot semantics on column drops, renames,
+ * type changes. Framework bookkeeping is a tighter contract:
+ * additive-only column evolution, no destructive changes, no user
+ * data ever lives in a `.dropped()` slot. The framework versions
+ * its own schema additively + can safely ALTER TABLE forward.
+ */
+export declare const emitFrameworkBootstrapSql: (tables: ReadonlyArray<AnyTable>, dialect: DialectId) => string;
+
+/**
+ * Emit the full schema DDL SCOPED to a tenant namespace. The container is
+ * created first (CREATE SCHEMA / DATABASE / ATTACH), then the table DDL
+ * runs INSIDE it:
+ *
+ *   - postgres → `SET search_path TO "<ns>"` precedes the (unchanged)
+ *     table DDL, so unqualified CREATE TABLEs land in the tenant schema.
+ *     The migrate connection is dedicated + disposed after, so the
+ *     session-scoped search_path never leaks to a request connection.
+ *   - mysql / mariadb → `USE \`<ns>\`` precedes the DDL (same idea).
+ *   - mssql / sqlite → these dialects have no per-session schema switch
+ *     usable here, so the table + index names are SCHEMA-QUALIFIED
+ *     (`[ns].[todos]` / `"ns"."todos"`). The migrator passes the
+ *     namespace through to the per-table emitter.
+ *
+ * On mssql/sqlite, namespaced DDL qualification covers CREATE TABLE +
+ * CREATE INDEX. FK targets that reference framework/core tables in the
+ * shared schema are NOT re-pointed — database-per-tenant FKs across
+ * containers are a deliberate non-goal (each tenant namespace is
+ * self-contained for its own tables).
+ */
+export declare const emitNamespacedSchemaSql: (tables: ReadonlyArray<AnyTable>, dialect: DialectId, namespace: string, sqliteFile?: string) => string;
+
+/**
+ * DDL that creates a tenant's namespace CONTAINER, per dialect:
+ *
+ *   - postgres / mssql → a SCHEMA
+ *   - mysql / mariadb  → a DATABASE (SCHEMA ≡ DATABASE — database-per-tenant)
+ *   - sqlite           → an ATTACHed database file
+ *
+ * `namespace` MUST already be a safe identifier (`tenant_<id>` from
+ * `resolveTenantNamespace`) — it's emitted in an identifier position, so
+ * the caller owns the injection guard. Idempotent where the dialect
+ * supports it (`IF NOT EXISTS` / `OBJECT_ID` guard); sqlite's `ATTACH`
+ * errors if the alias is already attached, which the migrator treats as
+ * "already provisioned".
+ */
+export declare const emitNamespaceProvisionDdl: (namespace: string, dialect: DialectId, sqliteFile?: string) => string;
+
+export declare const emitSchemaSql: (entities: ReadonlyArray<AnyTable | AnyView>, dialect: DialectId) => string;
+
+declare type EmptyMerge = unknown;
+
+/**
+ * Filename pattern the discovery walker matches: timestamp-prefixed
+ * `.ts` files in any depth under the project's `migrations/` dir.
+ *
+ *     <UTC-timestamp>_<slug>.ts
+ *     20260415_120000_split_address_out.ts
+ *
+ * Timestamp format is YYYYMMDD_HHMMSS — sortable, globally unique
+ * without coordination, human-readable. The `_<slug>` is for humans
+ * + tools; the runner only orders by the leading timestamp.
+ */
+export declare const FILE_MIGRATION_PATTERN: RegExp;
+
+/**
+ * A file-based migration descriptor. Default-export an instance from
+ * a `migrations/<timestamp>_<slug>.ts` file; the framework's file
+ * runner picks it up via the discovery walker.
+ */
+export declare interface FileMigration {
+    /** Stable id — convention is `<UTC-timestamp>_<slug>`. Must match
+     *  the file's basename minus the `.ts`. Recorded in
+     *  `_voltro_migration_plans.id` so `voltro db rollback <id>`
+     *  can find the right `down` body. */
+    readonly id: string;
+    /** 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. */
+    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). */
+    readonly down: (ctx: FileMigrationContext) => Promise<void> | Effect.Effect<void, unknown, never>;
+}
+
+/**
+ * The runtime context a file-based migration's `up` / `down` body
+ * receives.
+ */
+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;
+    /**
+     * Lightweight log surface scoped to the migration. Lands in
+     * `voltro logs --filter 'migrations:file:<id>'` for any apply
+     * that runs through the dev / start boot path.
+     */
+    readonly log: {
+        readonly info: (message: string, fields?: Record<string, unknown>) => Effect.Effect<void>;
+        readonly warn: (message: string, fields?: Record<string, unknown>) => Effect.Effect<void>;
+    };
+    /** ISO-8601 timestamp when this migration started (deterministic
+     *  across the up/down pair via the applied_at column). */
+    readonly appliedAt: string;
+}
+
+export declare interface FileMigrationRunResult {
+    readonly applied: ReadonlyArray<{
+        id: string;
+        durationMs: number;
+    }>;
+    readonly skipped: ReadonlyArray<string>;
+}
+
+/**
+ * Stable-hash a SchemaSnapshot. Returns the hex-encoded sha256 of the
+ * canonicalised JSON representation. Truncated identifiers are NOT
+ * accepted as equivalent — the hash sees the full name. Length: 64 hex
+ * chars; the CLI displays the first 16 in boot logs and devtools UI.
+ */
+export declare const fingerprintSchema: (snapshot: SchemaSnapshot) => 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 = {
+    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.
+ *
+ * Defaults:
+ *   - `undefined`                            → `{ scheme: 'typeid' }` with derived prefix
+ *   - `{ prefix }`                           → typeid with that prefix
+ *   - `{ scheme: 'typeid' }`                 → derived prefix
+ *   - `{ scheme: 'typeid', prefix }`         → explicit prefix
+ */
+declare type IdSchemeInput = 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_*`
+ * runtime tables; 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.
+ *
+ * Single-sourced here so the BOOT auto-migrate (`runDev`, below) and the
+ * `voltro db plan/apply` CLI paths honour the EXACT same ignore-list — before
+ * this, only the CLI read the env var, so `voltro dev` would still refuse-to-boot
+ * on a `drop-table` for a table the CLI was told to leave alone.
+ */
+export declare const ignoreTablesFromEnv: () => {
+    ignoreTables?: ReadonlyArray<string>;
+};
+
+/**
+ * A (possibly composite) secondary index declared at the table level
+ * via `.index('byName', [...fields])`. The migration emitter turns each
+ * one into a `CREATE INDEX IF NOT EXISTS` statement; the runtime's
+ * SchemaRegistry indexes the fields for the non-indexed-query warning
+ * (see `@voltro/runtime/schemaRegistry.ts`).
+ *
+ * Postgres uses leading-prefix matching: an index on
+ * `[tenantId, email]` helps queries that filter on `tenantId` alone OR
+ * `tenantId AND email`, but NOT queries that filter only on `email`.
+ * The warning logic accounts for that — the FIRST field of a composite
+ * is treated as "covered", the rest aren't.
+ */
+/**
+ * An entry in `TableIndex.fields` is either a column name (the
+ * common case) or an expression object. Expression objects let an
+ * index sit on `lower("email")` / `date_trunc('month', "createdAt")`
+ * etc. The expression string is emitted verbatim into the DDL —
+ * caller is responsible for quoting identifiers correctly.
+ */
+declare type IndexField = string | {
+    readonly expr: string;
+} | {
+    readonly jsonPath: JsonIndexPath;
+};
+
+/**
+ * Index access method. `btree` (default) and `gist` are the original
+ * two; `gin` / `brin` / `hnsw` extend the DSL with real per-dialect
+ * compilation + fallbacks (see the support matrix in `migrate.ts`'s
+ * `usingClauseFor`).
+ *
+ * - `btree` — default; the all-purpose ordered index. Implicit on every
+ *   dialect.
+ * - `gist`  — postgres-only (PostGIS spatial / range types). Warn +
+ *   btree elsewhere.
+ * - `gin`   — postgres inverted index for `jsonb` containment / array
+ *   membership / fulltext. mysql/mariadb have no GIN → warn + skip (a
+ *   btree on a JSON/array column is useless); mssql/sqlite → warn +
+ *   btree.
+ * - `brin`  — postgres block-range index for naturally-ordered large
+ *   tables (append-only timestamps). Other dialects → warn + btree (a
+ *   legitimate, if larger, substitute for the range-scan use case).
+ * - `hnsw`  — postgres + pgvector approximate-nearest-neighbour index
+ *   for `vector` columns. Off-postgres → warn + skip (no analogue; a
+ *   btree on a vector is meaningless). Requires exactly one `vector`
+ *   field — validated at declaration time.
+ */
+declare type IndexKind = 'btree' | 'gist' | 'gin' | 'brin' | 'hnsw';
+
+/**
+ * Per-kind tuning options. Today only `hnsw` carries knobs (the pgvector
+ * build-time params). `m` controls graph connectivity (default 16),
+ * `efConstruction` the build-time candidate-list size (default 64).
+ */
+declare interface IndexKindOptions {
+    readonly hnsw?: {
+        readonly m?: number;
+        readonly efConstruction?: number;
+        /**
+         * Distance metric the index (and matching `nearestNeighbours`
+         * queries) use. Selects the pgvector opclass:
+         *   - `'cosine'` → `vector_cosine_ops` (default; the right choice for
+         *     normalised embeddings from most modern models)
+         *   - `'l2'`     → `vector_l2_ops` (Euclidean)
+         *   - `'inner'`  → `vector_ip_ops` (negative inner product)
+         * The opclass MUST match the metric the query orders by, or the
+         * index can't accelerate the search. Set `opclass` directly only to
+         * override the mapping (e.g. `halfvec_cosine_ops`).
+         */
+        readonly distance?: VectorDistance;
+        /**
+         * pgvector opclass token spliced into `USING hnsw (col <opclass>)`.
+         * When unset, derived from `distance` (default `vector_cosine_ops`).
+         * Set explicitly to override (e.g. `'halfvec_cosine_ops'` for a
+         * `vector(n, { precision: 'half' })` column).
+         */
+        readonly opclass?: string;
+    };
+}
+
+export declare interface IndexSnapshot {
+    readonly name: string;
+    readonly table: string;
+    readonly columns: ReadonlyArray<string>;
+    readonly unique: boolean;
+    /**
+     * Expression / json-path index (`expressionIndex(...)` / `jsonIndex(...)`),
+     * i.e. at least one key is a SQL expression rather than a bare column. The
+     * DB normalises the expression text on introspection (`(lower("email"))` →
+     * `lower(email)`), so it can NEVER round-trip byte-for-byte. The planner
+     * therefore matches such indexes by NAME + uniqueness only (see
+     * `sameIndexShape`) — without this they re-emit on every `db plan` forever
+     * (postgres pre-fix: they were INVISIBLE to introspect — an `add` with no
+     * `drop` that never converged to "up to date").
+     */
+    readonly expression?: boolean;
+}
+
+export declare const _internalCmp: (name: string) => (a: {
+    name: string;
+}, b: {
+    name: string;
+}) => number;
+
+/**
+ * Read the current shape of the connected database. Dispatched per
+ * dialect; supports postgres only.
+ *
+ * The returned `SchemaSnapshot` is the same shape `declaredSnapshot`
+ * produces — they're directly diffable via `planMigrations`.
+ *
+ * Restricted to the `public` schema today; multi-schema apps will
+ * grow a `schema` parameter when we have a real need.
+ */
+export declare const introspectSchema: (sql: SqlClient.SqlClient) => Effect.Effect<SchemaSnapshot, SqlError_2>;
+
+/** Type-guard for the discovery walker. */
+export declare const isFileMigration: (value: unknown) => value is FileMigration;
+
+/** Type guard — narrows an unknown value to a {@link RawSqlFragment}. */
+export declare const isRawSqlFragment: (value: unknown) => value is RawSqlFragment;
+
+/**
+ * A json-path index entry, produced by {@link jsonIndex}. Unlike a plain
+ * `{ expr }` (verbatim, dialect-specific) this carries the column + path
+ * abstractly and is lowered to each dialect's json accessor at DDL time —
+ * through the SAME `jsonPathSql` the predicate compiler uses, so a
+ * `jsonField('p','k')` FILTER and a `jsonIndex('p','k')` INDEX produce
+ * byte-identical SQL and the optimiser actually uses the index.
+ */
+declare interface JsonIndexPath {
+    readonly column: string;
+    readonly path: ReadonlyArray<string | number>;
+    /** Index the value as a number (for `gt/gte/lt/lte` range filters)
+     *  rather than as text. Set via {@link JsonIndexField.numeric}. */
+    readonly numeric: boolean;
+}
+
+export declare const mapPgType: (dataType: string, udtName?: string) => ColumnType;
+
+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;
+
+/**
+ * Factory for declaring a file-based migration. The shape is
+ * intentionally minimal — the framework deals with discovery,
+ * ordering, transaction wrapping + history tracking. Bodies stay
+ * focused on the actual data move.
+ *
+ * @example
+ *
+ *     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
+ *       },
+ *     })
+ */
+export declare const migration: (spec: FileMigration) => FileMigration;
+
+/**
+ * Discriminated union for the concrete DDL operations the planner
+ * emits. Every variant carries the `table` (most ops act on one
+ * table) plus whatever payload the applier needs.
+ *
+ * The planner does NOT emit raw SQL here — that's the applier's job,
+ * dispatched per-dialect via `sql.onDialectOrElse`. Keeping the
+ * payload structural (not stringified) lets the same plan apply
+ * cleanly on every dialect.
+ */
+export declare type MigrationOperation = {
+    readonly kind: 'create-table';
+    readonly table: string;
+    readonly columns: ReadonlyArray<ColumnSnapshot>;
+    readonly indexes: ReadonlyArray<IndexSnapshot>;
+    readonly primaryKey?: ReadonlyArray<string>;
+} | {
+    readonly kind: 'drop-table';
+    readonly table: string;
+} | {
+    readonly kind: 'add-column';
+    readonly table: string;
+    readonly column: ColumnSnapshot;
+} | {
+    readonly kind: 'drop-column';
+    readonly table: string;
+    readonly column: string;
+} | {
+    readonly kind: 'rename-column';
+    readonly table: string;
+    readonly from: string;
+    readonly to: string;
+} | {
+    readonly kind: 'alter-column-nullability';
+    readonly table: string;
+    readonly column: string;
+    readonly toNullable: boolean;
+} | {
+    readonly kind: 'alter-column-type';
+    readonly table: string;
+    readonly column: string;
+    readonly from: ColumnType;
+    readonly to: ColumnType;
+    readonly using?: string;
+} | {
+    readonly kind: 'alter-column-default';
+    readonly table: string;
+    readonly column: string;
+    readonly defaultValue?: unknown;
+    readonly hasDefault: boolean;
+} | {
+    readonly kind: 'add-index';
+    readonly table: string;
+    readonly index: IndexSnapshot;
+} | {
+    readonly kind: 'drop-index';
+    readonly table: string;
+    readonly index: string;
+} | {
+    readonly kind: 'add-unique';
+    readonly table: string;
+    readonly column: string;
+} | {
+    readonly kind: 'drop-unique';
+    readonly table: string;
+    readonly column: string;
+} | {
+    readonly kind: 'add-unique-composite';
+    readonly table: string;
+    readonly name: string;
+    readonly fields: ReadonlyArray<string>;
+    readonly dedup?: 'fail' | 'suffix-counter' | {
+        sql: string;
+    };
+} | {
+    readonly kind: 'drop-unique-composite';
+    readonly table: string;
+    readonly name: string;
+} | {
+    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 column: 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;
+};
+
+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;
+    /** 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;
+    };
+}
+
+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;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * 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';
+
+export declare const parseEnumCheck: (clause: string) => {
+    readonly column: string;
+    readonly values: ReadonlyArray<string>;
+} | null;
+
+export declare interface PlanInput {
+    readonly declared: ReadonlyArray<TableLike>;
+    readonly live: SchemaSnapshot;
+    /**
+     * 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 onlineAfter?: number;
+    /**
+     * 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 dialect?: DialectId;
+    /**
+     * 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 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;
+    };
+}
+
+/**
+ * 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).
+ */
+export declare const provisionTenantNamespace: (tables: ReadonlyArray<AnyTable>, namespace: string, sqlLayer: Layer.Layer<SqlClient.SqlClient, ConfigError.ConfigError | SqlError.SqlError, never>, dialect?: DialectId) => Promise<void>;
+
+declare const quote: (name: string) => string;
+
+/**
+ * A captured raw-SQL fragment: the literal string segments of a tagged
+ * template plus the interpolated values, in template order
+ * (`strings[0]`, `values[0]`, `strings[1]`, …, `strings[n]`). The store
+ * rebinds it onto its live `sql` at execution time — `strings` splice in
+ * verbatim, `values` bind as parameters.
+ */
+export declare interface RawSqlFragment {
+    readonly _tag: 'RawSqlFragment';
+    readonly strings: ReadonlyArray<string>;
+    readonly values: ReadonlyArray<unknown>;
+    /**
+     * Tables this raw read depends on, for reactive invalidation. Raw
+     * reads are otherwise untracked — the query planner can't infer which
+     * tables an arbitrary SQL string touches. Declare them here (or via
+     * `store.raw(fragment, { dependsOn })`) to opt the read into the
+     * reactive layer's change-driven recomputation.
+     */
+    readonly dependsOn?: ReadonlyArray<string>;
+}
+
+export declare const releaseMigrationLock: (sql: SqlClient.SqlClient) => Effect.Effect<void, SqlError_2>;
+
+export declare const renderColumnMysql: (col: ColumnSnapshot) => string;
+
+export declare const renderColumnPg: (col: ColumnSnapshot) => string;
+
+/**
+ * Roll back a single file-based migration by id. Looks up the
+ * migration's `down` body via file discovery (the file must still be
+ * present on disk — file-based rollback is NOT idempotent across
+ * file deletion).
+ *
+ * The runner refuses to roll back any migration that isn't the
+ * latest applied file-based one (chain integrity); use `voltro db
+ * rollback --to <id>` to walk multiple back.
+ */
+export declare const rollbackFileBasedMigration: (sql: SqlClient.SqlClient, ctx: {
+    projectRoot: string;
+    id: string;
+}) => Effect.Effect<{
+    id: string;
+    durationMs: number;
+}, unknown>;
+
+/**
+ * Discover + apply every pending file-based migration under
+ * `projectRoot/migrations/`. Runs under the same advisory lock as
+ * the planner-based applier, so concurrent invocations serialise.
+ *
+ * - Returns `applied` (newly-run ids + durations) + `skipped`
+ *   (ids that were already applied) for the caller's log line.
+ * - Failures abort the run + propagate as the Effect's error
+ *   channel; the caller (dev.ts boot) is expected to refuse-to-boot.
+ */
+export declare const runFileBasedMigrations: (sql: SqlClient.SqlClient, ctx: RunFileBasedMigrationsCtx) => Effect.Effect<FileMigrationRunResult, unknown>;
+
+export declare interface RunFileBasedMigrationsCtx {
+    readonly projectRoot: string;
+    readonly env: 'dev' | 'staging' | 'prod';
+    readonly appliedBy: string;
+}
+
+/**
+ * Evolution-aware bootstrap for framework-managed tables. Same
+ * imperative shape as `runMigrate` but uses `emitFrameworkBootstrapSql`
+ * (which adds `ALTER TABLE ADD COLUMN IF NOT EXISTS` between
+ * CREATE TABLE and CREATE INDEX). Use this for `_voltro_*` and
+ * `voltro_isr_cache` so framework releases that grow new columns
+ * don't crash old DBs at boot.
+ */
+export declare const runFrameworkBootstrap: (tables: ReadonlyArray<AnyTable>, sqlLayer: Layer.Layer<SqlClient.SqlClient, ConfigError.ConfigError | SqlError.SqlError, never>, dialect?: DialectId) => Promise<void>;
+
+/**
+ * Run `applySchema` against a fresh SqlClient from the provided sqlLayer.
+ * Imperative entry point for the voltro dev CLI; callers that already
+ * own a runtime can use `applySchema` directly.
+ *
+ * `dialect` is passed through to the DDL emitter so SQL types + reactive
+ * trigger emission match the underlying engine.
+ */
+export declare const runMigrate: (tables: ReadonlyArray<AnyTable>, sqlLayer: Layer.Layer<SqlClient.SqlClient, ConfigError.ConfigError | SqlError.SqlError, never>, dialect?: DialectId) => Promise<void>;
+
+/**
+ * Top-level entry point — called once per boot. Returns a
+ * `BootMigrationOutcome`; the caller logs + acts on it (refuse-to-boot
+ * on `refused-blocked` / `prod-mismatch`, continue otherwise).
+ *
+ * Wires the dev/prod dispatch + the VOLTRO_AUTO_MIGRATE escape hatch.
+ */
+export declare const runPlannedMigrations: (sql: SqlClient.SqlClient, declared: ReadonlyArray<TableLike>, ctx: RunPlannedMigrationsCtx) => Effect.Effect<BootMigrationOutcome, SqlError_2, SqlClient.SqlClient>;
+
+export declare interface RunPlannedMigrationsCtx {
+    /** What `voltro logs` should attribute this run to. */
+    readonly appliedBy: string;
+    readonly environment: BootEnvironment;
+    /** Pretty-name dialect used for log lines. */
+    readonly dialectId: string;
+}
+
+/**
+ * The full schema as the planner sees it on one side of the diff.
+ * Both the declared side and the introspected side conform to this
+ * shape so the diff algorithm is symmetric.
+ */
+export declare interface SchemaSnapshot {
+    readonly tables: ReadonlyArray<TableSnapshot>;
+}
+
+/**
+ * Short form for log output / UI. Same hash, first 16 chars; cheap to
+ * recognise in scans of `voltro logs` output. Never used for equality
+ * checks — those go through the full hash.
+ */
+export declare const shortFingerprint: (fp: string) => string;
+
+/**
+ * The `sql` template tag — captures a tagged-template literal into a
+ * {@link RawSqlFragment} descriptor without binding it to any client.
+ *
+ * ```ts
+ * import { sql } from '@voltro/database/sql'
+ * const rows = await store.raw<{ n: number }>(
+ *   sql`SELECT count(*) AS n FROM events WHERE occurred_at > ${cutoff}`,
+ *   { dependsOn: ['events'] },
+ * )
+ * ```
+ *
+ * `cutoff` is bound as a parameter by the store, never interpolated —
+ * a value containing `'; DROP TABLE …` round-trips as data.
+ */
+export declare const sql: (strings: TemplateStringsArray, ...values: ReadonlyArray<unknown>) => RawSqlFragment;
+
+/**
+ * Map a logical column type to its dialect-specific DDL keyword.
+ *
+ * Supported across all five dialects: postgres, mysql, mariadb,
+ * mssql, and sqlite.
+ *
+ * Notes on the sqlite mappings:
+ *   - `TIMESTAMPTZ` becomes `TEXT` storing ISO-8601 strings — sqlite
+ *     has no native timezone type. Apps that read these via the
+ *     framework's typed query path stay agnostic; raw users get a
+ *     string they can `new Date()`.
+ *   - `JSONB` becomes `TEXT` (sqlite has `JSON` validation extensions
+ *     but plain `TEXT` storage with `json()` accessors is the more
+ *     portable default).
+ *   - `VECTOR` is unsupported on sqlite — emitted as `BLOB`.
+ */
+export declare const sqlType: (column: ColumnDefinition<unknown>, dialect: DialectId) => string;
+
+/**
+ * Effect that performs the squash + returns a summary. Fails if:
+ *   - no eligible rows match (`before` cut everything off)
+ *   - the latest pre-squash fingerprint differs from `fingerprint`
+ *     (signals uncommitted drift — refuse to lock in)
+ */
+export declare const squashMigrationPlans: (options: SquashOptions) => Effect.Effect<SquashResult, Error, SqlClient.SqlClient>;
+
+export declare interface SquashOptions {
+    /** ISO-8601 timestamp (`'2026-06-01T00:00:00Z'`) — rows applied
+     *  before this point are squashed. */
+    readonly before: string;
+    /** Optional human-readable note attached to the snapshot row. */
+    readonly note?: string;
+    /** Pre-validated current schema fingerprint. Compared with the
+     *  most-recent pre-squash row's fingerprint to ensure the squash
+     *  doesn't lock in drift. */
+    readonly fingerprint: string;
+    /** The principal name written into `appliedBy` on the snapshot
+     *  row. Typically the CLI user. */
+    readonly appliedBy: string;
+    /** Environment tag for the snapshot row. */
+    readonly environment: string;
+}
+
+export declare interface SquashResult {
+    /** Number of migration_plans rows marked squashed. */
+    readonly squashedCount: number;
+    /** The fingerprint carried on the synthetic snapshot row. */
+    readonly snapshotFingerprint: string;
+    /** ID of the inserted snapshot row. */
+    readonly snapshotId: string;
+}
+
+declare interface Table<Name extends string, Fields extends Record<string, ColumnDefinition<unknown>>, Reactive extends boolean = false, IxNames extends string = never> extends TableLike {
+    readonly tableName: Name;
+    readonly fields: Fields;
+    readonly isReactive: Reactive;
+    readonly appliedMixins: ReadonlyArray<AnyMixin>;
+    readonly appliedIndexes: ReadonlyArray<TableIndex>;
+    readonly appliedUniques: ReadonlyArray<TableUnique>;
+    readonly appliedFullText: ReadonlyArray<TableFullTextIndex>;
+    readonly appliedChecks: ReadonlyArray<TableCheck>;
+    /**
+     * Composite PRIMARY KEY column set, declared via `.primaryKey(['a','b'])`.
+     * When set it REPLACES the single-column `id()` PK assumption: no column
+     * emits an inline `PRIMARY KEY`, and the table gets a table-level
+     * `PRIMARY KEY (a, b)` constraint instead. Empty (the default) means the
+     * `id()` column carries the PK inline, as before.
+     */
+    readonly appliedPrimaryKey: ReadonlyArray<string>;
+    /**
+     * Optional `effect/Schema` the framework decodes the row against
+     * BEFORE every INSERT. Populated by `.validate(schema)`. Set
+     * per-table at table-construction time; immutable thereafter.
+     */
+    readonly insertSchema?: Schema.Schema.Any;
+    /**
+     * Optional `effect/Schema` the framework decodes a patch against
+     * BEFORE every UPDATE. Populated by `.validatePatch(schema)`. The
+     * framework wraps the schema in `Schema.partial` so a patch that
+     * omits fields is still valid — only the fields present in the patch
+     * are checked. Set per-table at table-construction time; immutable
+     * thereafter.
+     */
+    readonly validatePatchSchema?: Schema.Schema.Any;
+    with: <const Mixins extends ReadonlyArray<AnyMixin>>(...mixins: Mixins) => Table<Name, Fields & MergeMixinFields<Mixins>, Reactive, IxNames>;
+    /**
+     * Attach an effect/Schema that validates EVERY insert against the
+     * table. The MutationStore decodes the incoming row right before
+     * the INSERT — failure throws a typed `TableValidationError` the
+     * mutation handler surfaces as its typed-error channel.
+     *
+     * Applies on INSERT. Pair with `.validatePatch(...)` for UPDATE
+     * patches.
+     *
+     * Example:
+     * ```ts
+     * import { Schema } from 'effect'
+     *
+     * export const users = table('users', {
+     *   id:    id(),
+     *   email: text(),
+     * }).validate(Schema.Struct({
+     *   email: Schema.String.pipe(Schema.pattern(/^[^@]+@[^@]+$/)),
+     * }))
+     * ```
+     *
+     * The schema only needs to describe the fields you care about —
+     * the framework merges defaults + computed BEFORE validation, so
+     * `id` and `createdAt` are already filled in by the time the
+     * decoder sees the row.
+     */
+    validate: <S extends Schema.Schema.Any>(schema: S) => Table<Name, Fields, Reactive, IxNames>;
+    /**
+     * Attach an effect/Schema that validates UPDATE patches against the
+     * table. The framework wraps the schema in `Schema.partial`, so a
+     * patch that only touches some columns is valid — every field that
+     * IS present must satisfy its rule. The MutationStore decodes the
+     * (stamped) patch right before the UPDATE; failure throws the same
+     * typed `TableValidationFailed` error `.validate(...)` raises on
+     * insert.
+     *
+     * Example:
+     * ```ts
+     * import { Schema } from 'effect'
+     *
+     * export const users = table('users', {
+     *   id:    id(),
+     *   email: text(),
+     *   age:   integer(),
+     * })
+     *   .validate(Schema.Struct({
+     *     email: Schema.String.pipe(Schema.pattern(/^[^@]+@[^@]+$/)),
+     *   }))
+     *   .validatePatch(Schema.Struct({
+     *     age: Schema.Number.pipe(Schema.greaterThanOrEqualTo(0)),
+     *   }))
+     * ```
+     *
+     * Pass the same shape you'd pass to `.validate(...)` — the partial
+     * wrapping is applied for you, so don't pre-wrap fields in
+     * `Schema.optional`.
+     */
+    validatePatch: <S extends Schema.Schema.Any>(schema: S) => Table<Name, Fields, Reactive, IxNames>;
+    /**
+     * Declare a (possibly composite) secondary index on the table.
+     *
+     * The single surface for ALL indexes — column-level `.index()` does
+     * not exist, on purpose. One pattern, no footgun. Two signatures:
+     *
+     * 1. **Auto-named** (most cases): pass just the field list.
+     *
+     *    ```ts
+     *    table('apps', { id, projectId, ... })
+     *      .index(['projectId'])               // → "apps_projectId_idx"
+     *      .index(['projectId', 'kind'])       // → "apps_projectId_kind_idx"
+     *    ```
+     *
+     *    The auto-generated name surfaces in Postgres EXPLAIN output but
+     *    is NOT typed-addressable via `.using(...)` — when you DON'T
+     *    care about hot-path observability, auto-naming keeps the
+     *    schema file short.
+     *
+     * 2. **Explicit name** (for hot paths): pass a literal name.
+     *
+     *    ```ts
+     *    table('org_memberships', { ... })
+     *      .index('byUserOrg', ['userId', 'orgId'])
+     *      .index('byOrgRole', ['orgId', 'role'])
+     *    ```
+     *
+     *    The literal `IxName` is added to the table's `IxNames` union,
+     *    so `database.orgMemberships.using('byUserOrg')` autocompletes
+     *    against `'byUserOrg' | 'byOrgRole'` and rejects typos at
+     *    compile time. The literal also surfaces verbatim in EXPLAIN
+     *    output and DevTools — the right call for any access pattern
+     *    you actually care about debugging at scale.
+     *
+     * Both forms accept 1+ field names, type-checked against the row.
+     * Names must be unique within the table; collisions throw at
+     * declaration time so the error site is the schema file, not the
+     * migration runner.
+     */
+    index: {
+        <const F extends readonly [keyof Fields & string, ...Array<keyof Fields & string>]>(fields: F, options?: {
+            where?: string;
+            kind?: IndexKind;
+            kindOptions?: IndexKindOptions;
+        }): Table<Name, Fields, Reactive, IxNames>;
+        <const IxName extends string, const F extends readonly [keyof Fields & string, ...Array<keyof Fields & string>]>(name: IxName, fields: F, options?: {
+            where?: string;
+            kind?: IndexKind;
+            kindOptions?: IndexKindOptions;
+        }): Table<Name, Fields, Reactive, IxNames | IxName>;
+    };
+    /**
+     * Declare an EXPRESSION-aware index — entries can be column names
+     * (string) OR expression objects (`{ expr: 'lower("email")' }`).
+     * Use this when you need an index on `lower("email")`,
+     * `date_trunc('month', "createdAt")`, or any other server-side
+     * expression. Plain-column indexes should use `.index(...)` so the
+     * compiler keeps catching typos.
+     *
+     * ```ts
+     * .expressionIndex('byEmailCi', [{ expr: 'lower("email")' }])
+     * .expressionIndex('byOrgMonth', ['orgId', { expr: "date_trunc('month', \"createdAt\")" }])
+     * ```
+     *
+     * `options.where` makes it a partial expression index (postgres /
+     * sqlite / mssql); the underlying machinery is shared with
+     * `.index(...)`'s where option.
+     */
+    expressionIndex: <const IxName extends string>(name: IxName, fields: ReadonlyArray<IndexField>, options?: {
+        where?: string;
+        kind?: IndexKind;
+        kindOptions?: IndexKindOptions;
+    }) => Table<Name, Fields, Reactive, IxNames | IxName>;
+    /**
+     * Declare a (possibly composite) UNIQUE constraint at the table
+     * level. Enforces uniqueness across one or more columns — the DB
+     * rejects conflicting writes with a `PrimaryKeyConflictError`
+     * (mapped from each dialect's native conflict code).
+     *
+     * Two signatures parallel `.index(...)`:
+     *
+     * 1. **Auto-named** (`uq` suffix to disambiguate from indexes):
+     *    ```ts
+     *    table('org_slugs', { id, orgId, slug })
+     *      .unique(['orgId', 'slug'])              // → "org_slugs_orgId_slug_uq"
+     *    ```
+     *
+     * 2. **Explicit name**:
+     *    ```ts
+     *    .unique('byOrgSlug', ['orgId', 'slug'])
+     *    ```
+     *
+     * Optional third arg passes a dedup policy for the migration
+     * planner's needs-backfill path:
+     *    ```ts
+     *    .unique('byOrgSlug', ['orgId', 'slug'], { dedup: 'suffix-counter' })
+     *    ```
+     *
+     * Distinct from the column-level `text().unique()` modifier —
+     * that's single-column and lives ON the column. Composite
+     * uniqueness MUST be declared at the table level.
+     */
+    unique: {
+        <const F extends readonly [keyof Fields & string, ...Array<keyof Fields & string>]>(fields: F, options?: {
+            dedup?: TableUnique['dedup'];
+        }): Table<Name, Fields, Reactive, IxNames>;
+        <const UqName extends string, const F extends readonly [keyof Fields & string, ...Array<keyof Fields & string>]>(name: UqName, fields: F, options?: {
+            dedup?: TableUnique['dedup'];
+        }): Table<Name, Fields, Reactive, IxNames>;
+    };
+    /**
+     * Declare a named table-level `CHECK` constraint — a DB-ENFORCED
+     * invariant that holds regardless of which client writes the row
+     * (defense-in-depth beyond app-level `.validate(Schema)`). Use for
+     * cross-column rules (`"startsAt" < "endsAt"`) or single-column bounds
+     * you want the database itself to guarantee.
+     *
+     * `expr` is RAW SQL — you own its cross-dialect portability. Stick to
+     * unquoted column names + standard operators; avoid dialect-specific
+     * functions / regex (those belong in `.validate(Schema)`). `CHECK` is
+     * enforced on Postgres / MySQL 8+ / MariaDB / MSSQL / SQLite.
+     *
+     * ```ts
+     * table('bookings', { startsAt: timestamp(), endsAt: timestamp(), seats: integer() })
+     *   .check('booking_window', 'startsAt < endsAt')
+     *   .check('seats_positive', 'seats > 0')
+     * ```
+     *
+     * For a single-column check, `column.check(expr)` is the terser form.
+     */
+    check: <const CkName extends string>(name: CkName, expr: string) => Table<Name, Fields, Reactive, IxNames>;
+    /**
+     * Declare a full-text-search index (S7). One method, three back-
+     * ends:
+     *
+     * - **Postgres**: emits a STORED tsvector column derived from the
+     *   listed columns + a GIN index. Search via `.matching(name,
+     *   query)` compiles to `<col>_tsv @@ plainto_tsquery(...)`.
+     * - **MySQL / MariaDB**: emits a native `FULLTEXT INDEX`; search
+     *   compiles to `MATCH(col1, col2) AGAINST(? IN NATURAL LANGUAGE MODE)`.
+     * - **MSSQL / SQLite**: no native catalog auto-creation — falls
+     *   back to `LIKE '%query%'` across each column. Warns at boot
+     *   so the operator knows the engine isn't optimal.
+     *
+     * `config` (default 'english') sets the tsvector language config
+     * on postgres; ignored elsewhere. `weights` is per-column tsvector
+     * weight letters ('A' most-significant — 'D' least); ignored
+     * elsewhere.
+     *
+     * ```ts
+     * posts = table('posts', {
+     *   id:    id(),
+     *   title: text(),
+     *   body:  text(),
+     * }).fullTextIndex('postSearch', ['title', 'body'], {
+     *   config:  'english',
+     *   weights: { title: 'A', body: 'B' },
+     * })
+     * ```
+     */
+    fullTextIndex: <const FtName extends string>(name: FtName, columns: ReadonlyArray<keyof Fields & string>, options?: {
+        config?: string;
+        weights?: Record<string, 'A' | 'B' | 'C' | 'D'>;
+    }) => Table<Name, Fields, Reactive, IxNames>;
+    /**
+     * Declare a COMPOSITE PRIMARY KEY across two or more columns. Replaces the
+     * default single-column `id()` primary key: the listed columns become the
+     * table's PK, emitted as a table-level `PRIMARY KEY (a, b)` constraint on
+     * every dialect (no column carries an inline `PRIMARY KEY`).
+     *
+     * Use for natural composite keys — a join table keyed on both its FKs, a
+     * time-series table keyed on `(deviceId, ts)`, a per-tenant sequence keyed
+     * on `(tenantId, seq)`.
+     *
+     * ```ts
+     * table('memberships', {
+     *   userId: reference(() => users),
+     *   orgId:  reference(() => orgs),
+     *   role:   text(),
+     * }).primaryKey(['userId', 'orgId'])
+     * // → PRIMARY KEY ("userId", "orgId")
+     * ```
+     *
+     * The columns are type-checked against the row. A composite PK implies
+     * NOT NULL on each member column (the DB enforces it). Don't also declare an
+     * `id()` column — the composite key is THE key; a stray `id()` would emit a
+     * second inline PK and the DDL would be rejected.
+     */
+    primaryKey: <const F extends readonly [keyof Fields & string, keyof Fields & string, ...Array<keyof Fields & string>]>(fields: F) => Table<Name, Fields, Reactive, IxNames>;
+    /**
+     * Opt the table into the reactive engine. Applies
+     * `alter table <name> replica identity full` at migration time so the WAL
+     * stream carries full pre-images on UPDATE/DELETE. See the schema-DSL plan.
+     */
+    reactive: () => Table<Name, Fields, true, IxNames>;
+}
+
+/**
+ * A named table-level `CHECK` constraint, set by `.check(name, expr)`.
+ * `expr` is a raw SQL boolean expression — the developer owns its
+ * cross-dialect portability (use unbounded column names + standard
+ * operators; avoid dialect-specific functions / regex). Column-level
+ * checks (`text().check(expr)`) carry their expr on the ColumnDefinition
+ * instead and emit an inline `CHECK`.
+ */
+declare interface TableCheck {
+    readonly name: string;
+    readonly expr: string;
+}
+
+/**
+ * A composite UNIQUE constraint declared at the table level via
+ * `.unique([...])` / `.unique('name', [...])`. Distinct from the
+ * column-level `.unique()` modifier (which only covers a single
+ * column) and distinct from `.index([...])` (which doesn't enforce
+ * uniqueness).
+ *
+ * Emits a real DB-level UNIQUE CONSTRAINT inside CREATE TABLE — the
+ * DB rejects conflicting writes, not the application. That's the
+ * whole point: a multi-tenant `(orgId, slug)` constraint can't be
+ * enforced reliably at the app layer (race conditions), but the DB
+ * gives you a hard guarantee + a hard error.
+ *
+ * `dedup` mirrors the single-column unique-with-dedup story: when
+ * the planner classifies an add-composite-unique on a populated
+ * table that already has duplicates, the annotation tells the
+ * applier how to resolve them. `'fail'` (default) refuses; `'suffix-
+ * counter'` appends `-2`/`-3`/... to the LAST field; a `sql`-fragment
+ * runs custom SQL.
+ */
+/**
+ * Full-text index declaration (S7). Postgres builds a tsvector
+ * generated column + GIN index; MySQL / MariaDB get a native
+ * `FULLTEXT INDEX`; MSSQL / SQLite fall back to a per-column LIKE
+ * scan (no native FTS catalog setup attempted — that's a DBA task).
+ */
+declare interface TableFullTextIndex {
+    readonly name: string;
+    readonly columns: ReadonlyArray<string>;
+    /**
+     * Postgres tsvector language config (default 'english') and per-
+     * column weight letters ('A'..'D'). Both ignored on other dialects.
+     */
+    readonly config?: string;
+    readonly weights?: Readonly<Record<string, 'A' | 'B' | 'C' | 'D'>>;
+}
+
+declare interface TableIndex {
+    readonly name: string;
+    readonly fields: ReadonlyArray<IndexField>;
+    /**
+     * Optional partial-index predicate emitted as a `WHERE` clause.
+     * Use cases: index only non-soft-deleted rows, only active users,
+     * only pending orders.
+     *
+     * Postgres / SQLite / MSSQL ("filtered index") support this
+     * natively. MySQL + MariaDB don't — the DDL emitter falls back to
+     * a full index on those dialects and logs a warning at boot so the
+     * caller knows the predicate was dropped.
+     *
+     * Emitted verbatim (caller-quoted), same conventions as the
+     * expression-field form.
+     */
+    readonly where?: string;
+    /**
+     * Index access method. Default `'btree'` on every dialect. See
+     * {@link IndexKind} for the per-kind semantics + the per-dialect
+     * fallback matrix (postgres `gist`/`gin`/`brin`/`hnsw`; warn+btree or
+     * skip+warn elsewhere).
+     */
+    readonly kind?: IndexKind;
+    /**
+     * Per-kind tuning knobs. Today only `hnsw` (`kindOptions.hnsw.{m,
+     * efConstruction, opclass}`). Ignored for kinds that don't read it.
+     */
+    readonly kindOptions?: IndexKindOptions;
+}
+
+declare interface TableLike {
+    readonly tableName: string;
+    readonly fields: Record<string, ColumnDefinition<unknown>>;
+}
+
+export declare interface TableSnapshot {
+    readonly name: string;
+    readonly columns: ReadonlyArray<ColumnSnapshot>;
+    readonly indexes: ReadonlyArray<IndexSnapshot>;
+    /**
+     * Composite PRIMARY KEY column set (`.primaryKey(['a','b'])`). Set on the
+     * DECLARED side only — it drives the `PRIMARY KEY (a, b)` line in the
+     * applier's create-table emission. Absent (the default) means the single
+     * `id()` column carries the PK inline. Introspection leaves it undefined;
+     * the live PK is compared via the synthesised `<table>_pkey` index.
+     */
+    readonly primaryKey?: ReadonlyArray<string>;
+    /**
+     * Approximate row count from the live DB's planner stats — used by
+     * the migration planner to promote `safe` ops to `online-required`
+     * when the table exceeds the configured threshold (default 50_000).
+     * Pulled from `pg_class.reltuples` on postgres; equivalent stats
+     * on other dialects. Absent on the declared side of the diff (no
+     * data exists yet), present from introspection.
+     */
+    readonly rowCount?: number;
+}
+
+declare interface TableUnique {
+    readonly name: string;
+    readonly fields: ReadonlyArray<string>;
+    readonly dedup?: 'fail' | 'suffix-counter' | {
+        sql: string;
+    };
+}
+
+/**
+ * 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 {
+    readonly dedup?: 'fail' | 'suffix-counter' | Statement.Fragment;
+}
+
+/**
+ * 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 = 'cosine' | 'l2' | 'inner';
+
+/**
+ * A read-only SQL view descriptor. Structurally a `TableLike` (carries
+ * `tableName` + `fields`) so the query builder + row decoder + by-name
+ * registry treat it uniformly, PLUS `isView: true` and the `viewSelect`
+ * SQL body the migrator emits. There is no mutation surface — a view is
+ * queryable, never writable.
+ */
+declare interface View<Name extends string, Fields extends Record<string, ColumnDefinition<unknown>>> extends TableLike {
+    readonly tableName: Name;
+    readonly fields: Fields;
+    /** Marks this descriptor as a VIEW so the migrator + store read path can
+     *  distinguish it from a base table. */
+    readonly isView: true;
+    /** The raw SELECT body emitted verbatim into `CREATE VIEW <name> AS …`.
+     *  The author owns its cross-dialect portability (same contract as a
+     *  `raw()` column or an `expressionIndex` expression). */
+    readonly viewSelect: string;
+}
+
+/**
+ * A stable 64-bit integer derived from `voltro_migration_lock`. Postgres
+ * `pg_advisory_lock(bigint)` wants a number; we hard-code a constant
+ * inside the safe-integer range so every consumer races for the same
+ * lock without doing string hashing at runtime.
+ */
+export declare const VOLTRO_MIGRATION_LOCK_KEY = 6322741009312437n;
+
+/**
+ * Convenience wrapper: acquire → run `work` → release. Releases even
+ * on failure via `Effect.ensuring`, but a process crash mid-work
+ * leaves the postgres lock held until that connection closes (which
+ * the pooled SqlClient does on Effect scope cleanup).
+ */
+export declare const withMigrationLock: <A, E, R = never>(sql: SqlClient.SqlClient, work: Effect.Effect<A, E, R>) => Effect.Effect<A, E | SqlError_2, R>;
+
+export { }