@voltro/database 0.77.1 → 0.79.0

package/dist/sql.d.ts

@@ -603,6 +603,12 @@ declare interface ChangeStreamGap {
     readonly downForMs?: number;
 }
 
+/** A live table's columns that carry a character set, with it. */
+export declare const charsetColumnsOf: (table: TableSnapshot) => ReadonlyArray<{
+    readonly column: string;
+    readonly charset: string;
+}>;
+
 /** Partition into ≤`n`-sized chunks (disjoint, complete). Exported for the
  *  batching regression test — the introspection's correctness reduces to this
  *  producing a complete, non-overlapping partition of the table list. */
@@ -1685,6 +1691,25 @@ export declare interface ColumnSnapshot {
      * blocks a masking export until classified.
      */
     readonly safe?: boolean;
+    /**
+     * The character set a STRING column is stored in — MySQL / MariaDB only, and
+     * only on columns the engine gives one (text, varchar, enum; never json,
+     * which is `utf8mb4` on MariaDB and charset-less on MySQL by construction,
+     * and never a number, a date or bytes).
+     *
+     * Live side: what `information_schema.columns.character_set_name` reports.
+     * Declared side: the store's declared charset (`store: { dialect, charset }`
+     * in `app.config.ts`), stamped on every string column — ABSENT when the app
+     * declares none. The planner compares it only when BOTH sides carry one, so
+     * an undeclared app never plans a conversion; and the fingerprint never
+     * hashes it, because a live reading against an absent declaration would part
+     * every table's two hashes forever. `storeCharset.ts` carries the reason.
+     *
+     * A `string`, not `MysqlCharset`: the reader reports whatever the column is
+     * in (`latin1` is real), and a conversion FROM it is exactly what the
+     * declaration is for. Only the declared side is limited to the two.
+     */
+    readonly charset?: string;
     /**
      * Type PARAMETERS for the three `ColumnType`s whose DDL is not determined by
      * the type tag alone — `vector(n)`, `array(of)`, `enum(name, values)`.
@@ -1724,10 +1749,39 @@ export declare interface ColumnSnapshot {
     };
 }
 
+/**
+ * Does the declared column render a STRING type on the mysql family — the
+ * columns a declared charset is stamped on? Mirrors `sqlType(_, 'mariadb')`:
+ * text (LONGTEXT / VARCHAR / TEXT), enum (`ENUM(...)`), a typeid/ulid `id`
+ * (VARCHAR(64)) and a text-stored `reference` (VARCHAR(64)). A numeric id or
+ * reference is BIGINT; json / array are JSON; bytes is LONGBLOB — none carry a
+ * character set. `raw` is the user's own DDL, which the framework does not
+ * read, so it is left alone on both sides.
+ */
+export declare const columnTakesCharset: (col: Pick<ColumnSnapshot, "type" | "idScheme" | "idStorage" | "referenceStorage">) => boolean;
+
 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';
 
+/** A live foreign key a charset conversion has to carry across the rewrite. */
+export declare interface ConvertCharsetForeignKey {
+    /** Catalog name of the constraint. */
+    readonly name: string;
+    /** The child (referencing) side. */
+    readonly table: string;
+    readonly column: string;
+    readonly targetTable: string;
+    readonly targetColumn: string;
+    readonly onDelete?: 'cascade' | 'restrict' | 'setNull' | 'noAction';
+    readonly onUpdate?: 'cascade' | 'restrict' | 'setNull' | 'noAction';
+    /** Which operation re-creates it after the rewrite: this table's, or the
+     *  other endpoint's (`'peer'` — that table converts in the same plan and
+     *  sorts after this one). Dropping is done by whichever runs first; both
+     *  tolerate an already-absent constraint. */
+    readonly restore: 'here' | 'peer';
+}
+
 /** The tables a plan CREATEs — the set every same-plan operation is checked against. */
 export declare const createdTablesOf: (operations: ReadonlyArray<PlannedOperation>) => ReadonlySet<string>;
 
@@ -2222,15 +2276,62 @@ declare interface DataStore {
      * a way to hand a store somebody else's connection.
      */
     run?<A, E>(effect: Effect.Effect<A, E, SqlClient.SqlClient>): Promise<A>;
+    /**
+     * What this store can say about its OWN shape without a catalog — the
+     * tables it holds and the columns their rows carry.
+     *
+     * The inverse capability of {@link DataStore.run}. A SQL store answers a
+     * schema question by asking the server's catalog, which is authoritative
+     * about far more than this (types, indexes, constraints) and is therefore
+     * the right source whenever there is a connection. A store that IS its data
+     * has no catalog — and is not thereby ignorant: it knows exactly which
+     * tables it holds, because holding them is all a table is there. That much
+     * is answerable honestly, and nothing beyond it is.
+     *
+     * So the contract is deliberately narrow, and the narrowness is the point:
+     *
+     *   - `table` is unqualified by whatever namespace the view is bound to, so
+     *     a tenant view reports the tenant's tables under their bare names.
+     *   - `columns` is the UNION of the keys the held rows carry. An empty
+     *     table therefore reports NO columns, and that is not a claim that it
+     *     has none — a caller must read `rowCount` before treating an absent
+     *     column as absent.
+     *   - `rowCount` is how many rows are held, so "the table is empty and says
+     *     nothing about its columns" is distinguishable from "the table has
+     *     rows and none of them carries that column".
+     *
+     * OPTIONAL on the interface: the in-memory store implements it (it is the
+     * only store whose data IS its schema); SQL stores omit it, because the
+     * catalog answers the same questions better and a second, weaker source of
+     * truth beside it is how the two drift. Callers guard with
+     * `if (store.storedTables)`.
+     *
+     * Read by the file-migration context built WITHOUT a `sql` client
+     * (`makeFileMigrationContext`), so a migration body that opens with
+     * `ctx.skipUnless(ctx.schema.tableExists('…'), …)` — the guard the file
+     * migration docs ask for — runs unchanged in a database-free test.
+     */
+    storedTables?(): ReadonlyArray<StoredTableShape>;
 }
 
+export declare const declaredSnapshot: (tables: ReadonlyArray<TableLike>, dialect?: DialectId, options?: DeclaredSnapshotOptions) => SchemaSnapshot;
+
 /**
  * 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;
+export declare interface DeclaredSnapshotOptions {
+    /**
+     * The store's declared character set (`store: { dialect, charset }`) —
+     * stamped on every string column so the planner can compare it with what the
+     * database reports. MySQL / MariaDB only: on any other dialect a charset is a
+     * configuration error and is refused here rather than ignored, so a
+     * declaration that cannot take effect never reads as one that did.
+     */
+    readonly charset?: MysqlCharset | undefined;
+}
 
 /** The NOTIFY channel a schema emits on when none is configured. */
 export declare const DEFAULT_CDC_CHANNEL = "framework_changes";
@@ -2286,6 +2387,12 @@ export declare interface DeployLedgerRow {
 
 export declare const describeOutcome: (outcome: BootMigrationOutcome, dialectId: string) => string;
 
+/** `bf_links`, `bf_links.ticket_key` — the spelling a message uses. */
+export declare const describeProbe: (probe: SchemaProbe) => string;
+
+/** One line per finding, for the CLI and the doctor. */
+export declare const describeStoreCharsetFinding: (f: StoreCharsetFinding) => string;
+
 /**
  * Parse `VOLTRO_DESTRUCTIVE_OK`.
  *
@@ -2496,6 +2603,31 @@ export declare const emitAddIndexMysql: (op: Extract<MigrationOperation, {
     kind: "add-index";
 }>, declared: ReadonlyArray<TableLike>, engine?: MysqlEngine) => string;
 
+/**
+ * The statements of a `convert-charset` operation, in order:
+ *
+ *   1. drop every foreign key that touches the table (either end) — the
+ *      engines refuse to change the charset of a column a constraint holds;
+ *   2. ONE `ALTER TABLE` that MODIFYs each declared string column to its
+ *      declared definition plus `CHARACTER SET`, and sets the table default —
+ *      a single rewrite, not one per column, and never the json columns;
+ *   3. re-create the constraints this operation owns (`restore: 'here'`); the
+ *      ones between two converting tables come back with the later table.
+ *
+ * Every column is rendered from the DECLARATION (`emitModifyColumnMysql` is
+ * the same renderer the type and nullability operations use), because MODIFY
+ * redefines the column and the declaration is the shape the plan converges
+ * to. A generated column keeps its expression — MODIFY without it would drop
+ * the generation.
+ */
+export declare const emitConvertCharsetMysql: (op: Extract<MigrationOperation, {
+    kind: "convert-charset";
+}>, declared: ReadonlyArray<TableLike>) => {
+    readonly drops: ReadonlyArray<string>;
+    readonly rewrite: string;
+    readonly restores: ReadonlyArray<string>;
+};
+
 export declare const emitCreateTableMssql: (op: Extract<MigrationOperation, {
     kind: "create-table";
 }>) => ReadonlyArray<string>;
@@ -2574,7 +2706,7 @@ cdcChannel?: string) => string;
  * 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;
+export declare const emitNamespacedSchemaSql: (tables: ReadonlyArray<AnyTable>, dialect: DialectId, namespace: string, sqliteFile?: string, options?: SchemaEmitOptions) => string;
 
 /**
  * DDL that creates a tenant's namespace CONTAINER, per dialect:
@@ -2590,12 +2722,17 @@ export declare const emitNamespacedSchemaSql: (tables: ReadonlyArray<AnyTable>,
  * 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 emitNamespaceProvisionDdl: (namespace: string, dialect: DialectId, sqliteFile?: string, 
+/** The declared store charset (mysql family) — the new database's default,
+ *  so its tables inherit the declaration rather than the server default.
+ *  `IF NOT EXISTS` leaves an existing database's default alone (measured on
+ *  both engines); the tables' own column charsets still land. */
+charset?: MysqlCharset) => string;
 
 export declare const emitSchemaSql: (entities: ReadonlyArray<AnyTable | AnyView>, dialect: DialectId, 
 /** NOTIFY channel for the reactive triggers. Must match the store's
  *  `cdcChannel`, or writes emit where nothing is listening. */
-cdcChannel?: string) => string;
+cdcChannel?: string, options?: SchemaEmitOptions) => string;
 
 declare type EmptyMerge = unknown;
 
@@ -2757,6 +2894,31 @@ export declare interface FileMigration {
      * schema change through `ctx.schema` in a migration of its own).
      */
     readonly transactional?: boolean;
+    /**
+     * WHERE in a migrate run this body belongs, relative to the declarative
+     * schema apply. Required, and there is no default, because the answer cannot
+     * be inferred from the body and getting it wrong is silent.
+     *
+     * - **`'before-schema'`** — runs FIRST, before the planner diffs declared
+     *   against live. This is the phase for everything a state diff cannot infer
+     *   and must not be computed against: a table split, a merge, a foreign key
+     *   dropped so the planner does not trip over it, a type change with a USING
+     *   expression. The plan is computed AFTER this body, against the shape it
+     *   left behind.
+     * - **`'after-schema'`** — runs LAST, after the plan has been applied and the
+     *   plugin steps and change triggers have converged. This is the phase for a
+     *   body that NEEDS the new shape: a back-fill into a table the same deploy
+     *   creates, a column filled from its neighbours. It runs in the same job,
+     *   under the same failure gate, and — on a dialect that holds a deploy in
+     *   one transaction — inside the same unit as the schema it depends on.
+     *
+     * A back-fill declared `'before-schema'` is the mistake this field exists to
+     * make unavailable: on the deploy that creates its table the body can only
+     * take its own `skipUnless` guard, and the skip is recorded, so it never gets
+     * a second chance. The runner names that case when it can see it, but a
+     * warning after the fact is the weaker half — the phase is the answer.
+     */
+    readonly phase: MigrationPhase;
     /** The forward body. */
     readonly up: (ctx: FileMigrationContext) => Promise<void> | Effect.Effect<void, unknown, never>;
     /**
@@ -2878,9 +3040,12 @@ export declare interface FileMigrationContext {
 /**
  * A body driven over a store that has no SQL underneath — the in-memory
  * store a unit test uses. No client: `each`, `rewrite`, `expect`,
- * `skipUnless`, `store`, `log` and a Promise body under `transactional` run
- * against the store; `raw()`, every `schema` operation and an Effect body
- * under `transactional` fail with `MigrationNeedsSqlClient`. A store that
+ * `skipUnless`, `store`, `log`, the two read-only probes the store can answer
+ * about itself (`schema.tableExists`, `schema.columnExists`) and a Promise
+ * body under `transactional` run against the store; `raw()`, an Effect body
+ * under `transactional` and every `schema` member that needs a CATALOG —
+ * `snapshot`, `indexExists`, `foreignKeyExists` and all the DDL — fail with
+ * `MigrationNeedsSqlClient`, each naming what to do instead. A store that
  * CAN run SQL (`run` present) is not accepted here: its migration context
  * needs the client, and the type says so before the runtime check does.
  */
@@ -2928,7 +3093,21 @@ export declare interface FileMigrationRunResult {
         id: string;
         durationMs: number;
     }>;
+    /** Ids this pass did NOT run because they are already recorded. */
     readonly skipped: ReadonlyArray<string>;
+    /**
+     * The migrations whose body stopped at its own `skipUnless`, with the schema
+     * objects it found absent. A caller holding the plan that follows can say
+     * whether the skip was permanent; nobody else can.
+     */
+    readonly skips: ReadonlyArray<FileMigrationSkip>;
+}
+
+/** One migration that skipped, and what its body found missing. */
+export declare interface FileMigrationSkip {
+    readonly id: string;
+    readonly reason: string;
+    readonly absent: ReadonlyArray<SchemaProbe>;
 }
 
 /**
@@ -2946,6 +3125,8 @@ export declare const fileMigrationStatus: (sql: SqlClient.SqlClient, projectRoot
 /** One row of `voltro db status` for a `migrations/<timestamp>_<slug>.ts` file. */
 export declare interface FileMigrationStatusRow {
     readonly id: string;
+    /** Where in a run this body executes — `voltro db status` says which. */
+    readonly phase: MigrationPhase;
     readonly applied: boolean;
     /** The file no longer hashes to what was recorded when it ran. Always false
      *  for a row applied before hashes were recorded — see `appliedFileMigrations`. */
@@ -3232,6 +3413,8 @@ export declare const isAlreadySatisfied: (err: unknown, rules: ReadonlyArray<Alr
 /** Type-guard for the discovery walker. */
 export declare const isFileMigration: (value: unknown) => value is FileMigration;
 
+export declare const isMysqlCharset: (value: unknown) => value is MysqlCharset;
+
 /** Type guard — narrows an unknown value to a {@link RawSqlFragment}. */
 export declare const isRawSqlFragment: (value: unknown) => value is RawSqlFragment;
 
@@ -3305,6 +3488,7 @@ 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.',
+ *       phase:       'before-schema',
  *       up: ({ sql, store, log }) => Effect.gen(function* () {
  *         yield* sql.unsafe(`CREATE TABLE addresses ( ... )`)
  *         yield* sql.unsafe(`INSERT INTO addresses (...) SELECT (...) FROM users`)
@@ -3326,6 +3510,9 @@ export declare const MIGRATION_ATOMICITY: Readonly<Record<DialectId, MigrationAt
  */
 export declare const MIGRATION_NEEDS_TWO_CONNECTIONS: string;
 
+/** Both phases, in the order a run executes them. The one definition; readers derive. */
+export declare const MIGRATION_PHASES: readonly [MigrationPhase, MigrationPhase];
+
 /**
  * How much of a plan a dialect can apply atomically.
  *
@@ -3403,10 +3590,13 @@ export declare interface MigrationLockScope {
 /**
  * A migration context was built without a SQL client — over the in-memory
  * store, the shape a unit test uses — and the body reached a surface that
- * needs a live connection: `raw()`, every `ctx.schema` operation, or an
- * Effect body under `ctx.transactional` (which runs ON the connection).
- * `each`, `rewrite`, `expect`, `skipUnless`, `store` and `log` work without
- * one. Also raised at construction when what was handed in as `sql` is not
+ * needs a live connection: `raw()`, an Effect body under `ctx.transactional`
+ * (which runs ON the connection), or a `ctx.schema` member that can only be
+ * answered from a CATALOG — `snapshot`, `indexExists`, `foreignKeyExists` and
+ * every schema CHANGE. `each`, `rewrite`, `expect`, `skipUnless`, `store`,
+ * `log` and the two probes the store can answer about its own shape
+ * (`tableExists`, `columnExists`) work without one; each refusal names what to
+ * do instead. Also raised at construction when what was handed in as `sql` is not
  * an `@effect/sql` client, or when a SQL-backed store arrives without the
  * client it executes on — both are refused before a body can run rather
  * than surfacing as a TypeError from inside the first helper that touches
@@ -3553,8 +3743,44 @@ export declare type MigrationOperation = {
     readonly validation: 'value' | 'container';
     readonly previousValidation: 'value' | 'container' | 'unverified' | 'absent';
     readonly dropConstraints: ReadonlyArray<string>;
+}
+/**
+* Bring every string column of ONE table to the declared character set —
+* MySQL / MariaDB only. A table REWRITE: each named column is `MODIFY`ed to
+* its declared definition plus `CHARACTER SET`, and the table's default is
+* set so a later `ADD COLUMN` inherits it. json columns are never in
+* `columns` (their charset is the engine's, not the declaration's).
+*
+* `foreignKeys` are the constraints that touch this table — either end —
+* because neither engine changes the character set of a column a foreign
+* key holds (MariaDB 1832/1833, MySQL 3780). Each is dropped before the
+* rewrite and re-created after it; `restore` says which endpoint's operation
+* re-creates it, so a constraint between two converting tables comes back
+* only once both sides are at the target (the later of the two, by name).
+*/
+| {
+    readonly kind: 'convert-charset';
+    readonly table: string;
+    readonly charset: MysqlCharset;
+    /** The string columns to rewrite, in declaration order. */
+    readonly columns: ReadonlyArray<string>;
+    /** The character sets those columns are in today (for the plan line). */
+    readonly from: ReadonlyArray<string>;
+    readonly foreignKeys: ReadonlyArray<ConvertCharsetForeignKey>;
 };
 
+/**
+ * The two points in a migrate run at which a file-based body can execute.
+ *
+ * The ORDER of `'before-schema'` is what every file migration has always had
+ * and is not negotiable: a body that drops a constraint the planner would trip
+ * over has to run before the plan is computed, and `voltro db apply --plan`
+ * refuses a pending one for exactly that reason. `'after-schema'` is the point
+ * that did not exist — everything the declarative apply produces is in place,
+ * so a body may depend on it.
+ */
+export declare type MigrationPhase = 'before-schema' | 'after-schema';
+
 export declare interface MigrationPlan {
     readonly operations: ReadonlyArray<PlannedOperation>;
     /** Pre-state fingerprint (live DB at plan time). */
@@ -3779,6 +4005,16 @@ declare interface MixinIndex {
     readonly kindOptions?: IndexKindOptions;
 }
 
+export declare const MYSQL_CHARSETS: ReadonlyArray<MysqlCharset>;
+
+/**
+ * The character sets a store can declare for its string columns on MySQL /
+ * MariaDB. `utf8mb4` holds every Unicode scalar; `utf8mb3` (the engines' old
+ * `utf8`) stops at three bytes and refuses emoji and most supplementary-plane
+ * characters with errno 1366.
+ */
+export declare type MysqlCharset = 'utf8mb3' | 'utf8mb4';
+
 /** Which engine a `mysql`-dialect connection is actually talking to. */
 export declare type MysqlEngine = 'mysql' | 'mariadb';
 
@@ -3801,6 +4037,11 @@ export declare type MysqlEngine = 'mysql' | 'mariadb';
  */
 export declare const mysqlIndexPrefixFor: (col: ColumnSnapshot | undefined) => number | undefined;
 
+export declare interface NamespaceCharsetReport {
+    readonly namespace: string;
+    readonly findings: ReadonlyArray<StoreCharsetFinding>;
+}
+
 /**
  * Type-narrowing migration marker. Tells the planner that this column
  * previously had type `from` and is now being narrowed/converted to its
@@ -3962,7 +4203,9 @@ export declare const parseEnumCheck: (clause: string) => {
  * 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 const pendingFileMigrationIds: (sql: SqlClient.SqlClient, projectRoot: string, 
+/** Absent: BOTH phases — a gate that asks "is anything pending at all". */
+phase?: MigrationPhase) => Effect.Effect<ReadonlyArray<string>, unknown>;
 
 /**
  * What `runFileBasedMigrations` would execute next, with the one fact a deploy
@@ -3971,11 +4214,33 @@ export declare const pendingFileMigrationIds: (sql: SqlClient.SqlClient, project
  * 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<{
+export declare const pendingFileMigrationSummary: (sql: SqlClient.SqlClient, projectRoot: string, 
+/** Absent: BOTH phases. */
+phase?: MigrationPhase) => Effect.Effect<ReadonlyArray<{
     readonly id: string;
+    readonly phase: MigrationPhase;
     readonly irreversible: string | undefined;
 }>, unknown>;
 
+/** A skip the plan that follows makes permanent, with the objects that prove it. */
+export declare interface PermanentSkip {
+    readonly id: string;
+    readonly reason: string;
+    /** The probed objects this plan creates — what makes the skip permanent. */
+    readonly created: ReadonlyArray<SchemaProbe>;
+}
+
+/**
+ * The skips this plan turns into permanent ones.
+ *
+ * A `before-schema` body that probed for an object and found it absent, where
+ * the plan computed immediately afterwards CREATES that object, could not have
+ * taken any other outcome on this deploy — and the skip was recorded, so it
+ * will not be offered again. Both facts are in hand at that moment; neither is
+ * on its own.
+ */
+export declare const permanentSkips: (skips: ReadonlyArray<FileMigrationSkip>, plan: MigrationPlan) => ReadonlyArray<PermanentSkip>;
+
 export declare interface PlanInput {
     readonly declared: ReadonlyArray<TableLike>;
     readonly live: SchemaSnapshot;
@@ -4002,6 +4267,16 @@ export declare interface PlanInput {
      * CLI populates it from `VOLTRO_DB_IGNORE_TABLES` (comma-separated names).
      */
     readonly ignoreTables?: ReadonlyArray<string>;
+    /**
+     * The store's declared character set — `store: { dialect, charset }` in
+     * `app.config.ts`. MySQL / MariaDB only; `declaredSnapshot` refuses it for
+     * any other dialect. Declared, every table the app declares is CREATED with
+     * it and, when a live table's string columns are stored otherwise, CONVERTED
+     * to it (`convert-charset`, a table rewrite that carries the table's foreign
+     * keys across). Absent, nothing is planned about character sets — see
+     * `storeCharset.ts` for why that is the default and what is reported instead.
+     */
+    readonly charset?: MysqlCharset | undefined;
 }
 
 /**
@@ -4028,6 +4303,16 @@ export declare const plannableLiveTables: <T extends {
     readonly name: string;
 }>(tables: ReadonlyArray<T>, declaredNames: ReadonlySet<string>) => ReadonlyArray<T>;
 
+/**
+ * What a planned operation CREATES — the objects that do not exist before the
+ * plan runs and do after it.
+ *
+ * Only creations. An operation that renames or drops is not what a body probing
+ * for absence is waiting for, and reporting one would send an operator looking
+ * for a relationship that is not there.
+ */
+export declare const plannedCreations: (plan: MigrationPlan) => ReadonlyArray<SchemaProbe>;
+
 /**
  * One row in a `MigrationPlan` — a concrete operation paired with the
  * planner's classification + any blocking reason.
@@ -5086,6 +5371,13 @@ export declare interface RunFileBasedMigrationsCtx {
     /** Schema scope for the migration advisory lock (see `migrations/lock.ts`).
      *  Absent → resolved from configuration (`DB_SCHEMA`). */
     readonly lockSchema?: string;
+    /**
+     * WHICH phase this pass runs. Required, not defaulted: a run applies the two
+     * phases as two passes around the declarative apply, and a caller that could
+     * leave this out would run one of them at whichever point it happened to be
+     * called — which is the defect the phase exists to remove, moved up a layer.
+     */
+    readonly phase: MigrationPhase;
 }
 
 /**
@@ -5137,6 +5429,9 @@ export declare interface RunPlannedMigrationsCtx {
     /** How long a soft-drop snapshot may sit before the boot warns about it
      *  (`database.softDropRetentionDays`; default 7). */
     readonly softDropRetentionDays?: number;
+    /** The store's declared character set (`store: { dialect, charset }`),
+     *  MySQL / MariaDB only — threaded into every plan this boot computes. */
+    readonly charset?: MysqlCharset | undefined;
 }
 
 /**
@@ -5152,6 +5447,9 @@ export declare interface RunPlannedMigrationsCtx {
  */
 export declare const runSchemaOp: (sql: SqlClient.SqlClient, op: MigrationSchemaOp, live: SchemaSnapshot) => Effect.Effect<void, SqlError_2>;
 
+/** Runs one Effect over the connection — the shape `ManagedRuntime.runPromise` and a store's `run` share. */
+export declare type RunSql = <A>(effect: Effect.Effect<A, SqlError_2, SqlClient.SqlClient>) => Promise<A>;
+
 /**
  * Effect that applies the emitted DDL to the provided SqlClient. Splits
  * on `;` only outside dollar-quoted blocks (the postgres NOTIFY trigger
@@ -5177,14 +5475,50 @@ export declare const runSchemaOp: (sql: SqlClient.SqlClient, op: MigrationSchema
  * absent → `DB_SCHEMA` from the environment, the same configuration the
  * connection's `search_path` pin reads.
  */
-export declare interface SchemaApplyOptions {
+export declare interface SchemaApplyOptions extends SchemaEmitOptions {
     readonly retryFilter?: (error: unknown) => RetryDecision;
     readonly lockSchema?: string;
 }
 
+export declare interface SchemaEmitOptions {
+    /**
+     * The store's declared character set — MySQL / MariaDB only. Every CREATE
+     * TABLE carries it as the table default, so the bring-up path creates the
+     * same tables the planner's `create-table` does. Refused for any other
+     * dialect (a declaration that cannot take effect must not read as one that
+     * did).
+     */
+    readonly charset?: MysqlCharset | undefined;
+}
+
 /** What a schema operation on the migration context found to do. */
 export declare type SchemaOpOutcome = 'applied' | 'already-absent' | 'already-present';
 
+/** A schema object a body asked about, in the vocabulary a user writes. */
+export declare type SchemaProbe = {
+    readonly kind: 'table';
+    readonly table: string;
+} | {
+    readonly kind: 'column';
+    readonly table: string;
+    readonly name: string;
+} | {
+    readonly kind: 'index';
+    readonly table: string;
+    readonly name: string;
+} | {
+    readonly kind: 'foreign-key';
+    readonly table: string;
+    readonly name: string;
+};
+
+export declare interface SchemaProbeRecorder {
+    /** The context to hand the body — `ctx` with a recording `schema`. */
+    readonly ctx: FileMigrationContext;
+    /** Every existence question that answered ABSENT, in the order it was asked. */
+    readonly absent: () => ReadonlyArray<SchemaProbe>;
+}
+
 /**
  * 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
@@ -5350,6 +5684,67 @@ export declare interface SquashResult {
     readonly snapshotId: string;
 }
 
+/** The declared snapshot's tables with the store charset stamped on every string column. */
+export declare const stampDeclaredCharset: (tables: ReadonlyArray<TableSnapshot>, charset: MysqlCharset) => ReadonlyArray<TableSnapshot>;
+
+/**
+ * What to do about the findings, once. Names the real config field and the
+ * command that applies it; nothing here is an env var.
+ */
+export declare const STORE_CHARSET_REMEDY: string;
+
+/**
+ * One table the store's character set is wrong about.
+ *
+ *  - `disagrees-with-declaration` — the app declares a charset and these
+ *    columns are stored in another one. The plan carries the conversion; the
+ *    doctor names it for the operator who has not run `voltro db plan`.
+ *  - `json-outruns-text` — no declaration, and the table has a json column
+ *    (which holds every Unicode character on both engines) next to string
+ *    columns that do not. The reported symptom, as a line.
+ *  - `mixed` — no declaration, no json, and the table's string columns are not
+ *    all in one charset: a column converted by hand, or a column added under a
+ *    different database default. Two columns of one declaration disagree about
+ *    what a string is.
+ */
+export declare interface StoreCharsetFinding {
+    readonly table: string;
+    readonly kind: 'disagrees-with-declaration' | 'json-outruns-text' | 'mixed';
+    /** The columns that are not where they should be, with the charset they are in. */
+    readonly columns: ReadonlyArray<{
+        readonly column: string;
+        readonly charset: string;
+    }>;
+    /** What the finding measures against: the declaration, or `utf8mb4` for json. */
+    readonly expected: string;
+}
+
+/**
+ * The tables whose string columns cannot hold what they should. Pure — over a
+ * live snapshot the caller has already read — so `voltro db plan`, `voltro
+ * doctor` and a test can ask the same question of the same reading.
+ *
+ * Zero findings on a healthy database is the contract: a `utf8mb4` database
+ * with no declaration reports nothing, and so does any database whose every
+ * string column matches its declaration. Measured against both engines in
+ * `storeCharset.integration.test.ts`.
+ */
+export declare const storeCharsetFindings: (input: {
+    readonly live: SchemaSnapshot;
+    readonly dialect: DialectId;
+    readonly charset?: MysqlCharset | undefined;
+}) => ReadonlyArray<StoreCharsetFinding>;
+
+/** One table as a store that has no catalog can describe it. See {@link DataStore.storedTables}. */
+declare interface StoredTableShape {
+    /** The table's name, unqualified by any namespace the reporting view is bound to. */
+    readonly table: string;
+    /** The union of the column names the held rows carry. Empty for a table with no rows. */
+    readonly columns: ReadonlyArray<string>;
+    /** How many rows the store holds for this table. `0` means `columns` carries no evidence. */
+    readonly rowCount: number;
+}
+
 /**
  * `col IN (SELECT col FROM ...)` / `col NOT IN (SELECT ...)` — the
  * RHS is a sub-query descriptor. The sub-query MUST project a
@@ -5981,6 +6376,20 @@ declare interface TableUnique {
     };
 }
 
+/**
+ * The tenant databases whose string columns are stored otherwise than the
+ * declaration — or, undeclared, otherwise than their json columns. Only the
+ * charset facts are read (type kind, charset), which is all the question
+ * needs; a full introspection per tenant would be a catalog scan per tenant.
+ *
+ * Empty on a server with no tenant database, and empty when every tenant
+ * agrees. Namespaces come out sorted.
+ */
+export declare const tenantNamespaceCharsetFindings: (run: RunSql, options: {
+    readonly charset?: MysqlCharset | undefined;
+    readonly dialect?: "mysql" | "mariadb";
+}) => Promise<ReadonlyArray<NamespaceCharsetReport>>;
+
 /**
  * A `transactional` migration whose body committed the transaction from
  * inside — DDL on the MySQL family, or an explicit COMMIT. The body's work
@@ -6164,6 +6573,18 @@ declare interface WindowSpec_2 {
 
 export declare const withMigrationLock: <A, E, R = never>(sql: SqlClient.SqlClient, work: Effect.Effect<A, E, R>, scope?: MigrationLockScope) => Effect.Effect<A, E | SqlError_2, R>;
 
+/**
+ * Wrap a migration context so its four existence questions are recorded when —
+ * and only when — they answer absent.
+ *
+ * The four are exactly `MigrationSchemaOps`'s `*Exists` members, and the map
+ * below is typed over them, so a fifth existence question added there fails to
+ * compile until it has been decided whether an absent answer is evidence of the
+ * same thing. An existence probe nobody recorded reads exactly like a body that
+ * never asked.
+ */
+export declare const withSchemaProbeRecorder: (ctx: FileMigrationContext) => SchemaProbeRecorder;
+
 /** Tree of relations to eager-load. */
 declare type WithSpec = Readonly<Record<string, true | EagerLoadSpec>>;