@voltro/database 0.12.0 → 0.14.0

package/dist/sql.d.ts

@@ -29,6 +29,14 @@ export declare interface AppliedMigration {
     readonly environment: 'dev' | 'staging' | 'prod';
     readonly rollbackPlan?: ReadonlyArray<MigrationOperation>;
     readonly durationMs: number;
+    /**
+     * How many operations the applier actually EXECUTED, counted from the per-op
+     * results — not `operations.length`, which is what the plan asked for. The
+     * two can only differ if an op reports `skipped`, but the log lines quote
+     * this one on principle: "applied N op(s)" derived from the plan length is a
+     * claim about intent dressed up as a claim about the database.
+     */
+    readonly appliedOps: number;
     readonly onlineStrategy?: 'inline' | 'concurrent' | 'batched' | 'shadow-column';
     readonly source: 'auto-diff' | 'file';
     readonly notes?: string;
@@ -90,6 +98,31 @@ export declare interface ApplyPlanCtx {
     readonly source: 'auto-diff' | 'file';
     /** Optional human note via `voltro db apply --note "..."`. */
     readonly notes?: string;
+    /**
+     * Re-plan against the LIVE schema — the convergence proof.
+     *
+     * `applyPlan` calls this once, after the DDL and BEFORE it records the
+     * fingerprint. A plan that converged re-plans to zero operations; anything
+     * left is DDL that ran without error and did not take effect, and the apply
+     * fails rather than recording a fingerprint that describes a database state
+     * that does not exist.
+     *
+     * This exists because "reports success, applies nothing" is not hypothetical.
+     * A schema shipped 31 operations that logged `applied 31 op(s)` on every boot
+     * for two releases: the statements were real, postgres accepted all of them,
+     * and none of them changed anything (`ALTER COLUMN … TYPE text` on a text
+     * column; `SET DEFAULT NULL` for a default the renderer couldn't express).
+     * The recorded fingerprint then made the next boot short-circuit on
+     * "schema up to date". Both underlying defects are fixed — this is the guard
+     * that makes the NEXT one loud instead of permanent.
+     *
+     * It is REQUIRED, not optional, because the caller is the only place that
+     * knows the exact planner inputs (which tables were filtered, which were
+     * ignored); an applier-side re-plan would compare against a different set and
+     * report drift that isn't there. A caller that cannot re-plan cannot prove it
+     * applied anything.
+     */
+    readonly replan: (sql: SqlClient.SqlClient) => Effect.Effect<MigrationPlan, SqlError_2, SqlClient.SqlClient>;
 }
 
 /**
@@ -598,6 +631,43 @@ export declare interface ColumnSnapshot {
      * blocks a masking export until classified.
      */
     readonly safe?: boolean;
+    /**
+     * Type PARAMETERS for the three `ColumnType`s whose DDL is not determined by
+     * the type tag alone — `vector(n)`, `array(of)`, `enum(name, values)`.
+     * DECLARED-side only (introspection reports a concrete SQL type, not the
+     * declaration that produced it).
+     *
+     * These exist because the applier renders its DDL from a ColumnSnapshot, not
+     * from the `ColumnDefinition` that `migrate.ts`'s canonical `sqlType` reads.
+     * Without them the snapshot renderers had nothing to render and collapsed all
+     * three to `text` — which is not a smaller mistake than it looks. A declared
+     * `vector(1536)` against a live `text` column planned an `alter-column-type`
+     * that emitted `ALTER COLUMN … TYPE text`: valid SQL, applied successfully,
+     * changed nothing. The plan re-emitted it on every boot, the applier reported
+     * success every time, and the schema never converged. (Reported from a live
+     * pod: "applied 31 op(s)" with none of the 31 present in the database.)
+     *
+     * The rule for anything added later: if the applier has to RENDER it, the
+     * snapshot has to CARRY it — a snapshot renderer must never invent a type it
+     * wasn't given.
+     */
+    readonly vectorDim?: number;
+    readonly vectorPrecision?: 'float32' | 'half';
+    readonly arrayElement?: ColumnType;
+    readonly enumName?: string;
+    readonly enumValues?: ReadonlyArray<string>;
+    /**
+     * PostGIS `geography(kind, srid)` / `geometry(kind, srid)` parameters. Same
+     * reason as the three above: a spatial column declares `type: 'text'`, so
+     * WITHOUT this the applier's `add-column` created a plain `text` column and
+     * introspection (`USER-DEFINED` → `text`) agreed with it — no churn, no
+     * error, and no spatial column. DECLARED-side only.
+     */
+    readonly spatial?: {
+        readonly kind: 'geography' | 'geometry';
+        readonly geomKind: string;
+        readonly srid: number;
+    };
 }
 
 declare type ColumnType = 'id' | 'text' | 'integer' | 'real' | 'decimal' | 'bigint' | 'boolean' | 'timestamp' | 'date' | 'json' | 'bytes' | 'reference' | 'vector' | 'enum' | 'array' | 'interval' | 'raw';
@@ -610,6 +680,16 @@ declare type ColumnType = 'id' | 'text' | 'integer' | 'real' | 'decimal' | 'bigi
  */
 export declare const declaredSnapshot: (tables: ReadonlyArray<TableLike>, dialect?: DialectId) => SchemaSnapshot;
 
+/**
+ * `DEFAULT <expr>` for an array-valued default.
+ *
+ * Postgres is the only dialect with native arrays, so a `array()` column there
+ * takes an array literal (`'{a,b}'::text[]`); every other dialect stores the
+ * value as JSON/TEXT and takes the json form. A default on a `json()` column
+ * always takes the json form — the array is the VALUE, not the storage.
+ */
+export declare const defaultArrayClause: (value: ReadonlyArray<unknown>, column: ColumnDefinition<unknown>, dialect: DialectId) => string;
+
 export declare const defaultClause: (column: ColumnDefinition<unknown>, dialect: DialectId) => string | null;
 
 /**
@@ -622,6 +702,18 @@ export declare const defaultJsonClause: (value: object, dialect: DialectId) => s
 
 export declare const describeOutcome: (outcome: BootMigrationOutcome, dialectId: string) => string;
 
+/**
+ * Compare declared reactivity against the triggers actually installed.
+ *
+ * Postgres only — it is the one dialect where reactivity is carried by DDL. The
+ * binlog and Change Tracking readers are configured at runtime from the same
+ * in-memory table list the schema produced, so they cannot drift from it.
+ */
+export declare const detectReactiveTriggerDrift: (sql: SqlClient.SqlClient, tables: ReadonlyArray<{
+    readonly tableName: string;
+    readonly isReactive?: boolean;
+}>) => Effect.Effect<ReactiveTriggerDrift, SqlError_2>;
+
 /** Dialect IDs the framework supports. */
 declare type DialectId = 'postgres' | 'mysql' | 'mariadb' | 'mssql' | 'sqlite' | 'turso';
 
@@ -799,6 +891,9 @@ export declare interface FileMigrationRunResult {
  */
 export declare const fingerprintSchema: (snapshot: SchemaSnapshot) => string;
 
+/** Human report, or `undefined` when the database and the schema agree. */
+export declare const formatReactiveTriggerDrift: (drift: ReactiveTriggerDrift) => string | undefined;
+
 /**
  * Fully-resolved scheme stored on the `id` column definition AFTER
  * `table()` walks the fields. For `typeid`, the prefix is always
@@ -1289,6 +1384,17 @@ export declare const parseEnumCheck: (clause: string) => {
     readonly values: ReadonlyArray<string>;
 } | null;
 
+/**
+ * The ids of migration files present on disk but NOT yet recorded against THIS
+ * database — i.e. exactly what `runFileBasedMigrations` would execute next.
+ *
+ * Exists so a caller can decide WHETHER to apply before applying. `voltro dev`
+ * uses it to refuse unattended file migrations against a remote database: that
+ * decision needs the list (to name it in the refusal) and must not have run
+ * anything to get it.
+ */
+export declare const pendingFileMigrationIds: (sql: SqlClient.SqlClient, projectRoot: string) => Effect.Effect<ReadonlyArray<string>, unknown>;
+
 export declare interface PlanInput {
     readonly declared: ReadonlyArray<TableLike>;
     readonly live: SchemaSnapshot;
@@ -1403,6 +1509,17 @@ export declare interface RawSqlFragment {
     readonly dependsOn?: ReadonlyArray<string>;
 }
 
+/** Prefix `reactiveTableTriggerSql` names its triggers with. */
+export declare const REACTIVE_TRIGGER_PREFIX = "framework_changes_";
+
+export declare interface ReactiveTriggerDrift {
+    /** Tables the schema says are reactive that carry no trigger in the DB. */
+    readonly missing: ReadonlyArray<string>;
+    /** Tables that carry a trigger but are declared `.nonReactive()` — their
+     *  writes still hit the NOTIFY channel and cost WAL for nothing. */
+    readonly stale: ReadonlyArray<string>;
+}
+
 export declare const releaseMigrationLock: (sql: SqlClient.SqlClient) => Effect.Effect<void, SqlError_2>;
 
 export declare const renderColumnMysql: (col: ColumnSnapshot) => string;
@@ -1427,16 +1544,6 @@ export declare const rollbackFileBasedMigration: (sql: SqlClient.SqlClient, ctx:
     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 {
@@ -1498,6 +1605,14 @@ export declare interface SchemaSnapshot {
  */
 export declare const shortFingerprint: (fp: string) => string;
 
+/**
+ * Snapshot a single `TableLike` declaration. Drops the runtime-only
+ * fields (`computed`, `defaultFactory`, `__tsType`) that don't round-
+ * trip to/from `information_schema`. `idScheme.kind` IS carried — the
+ * applier needs it to emit auto-increment DDL for numeric ids.
+ */
+export declare const snapshotColumn: (name: string, def: ColumnDefinition<unknown>) => ColumnSnapshot;
+
 /**
  * The `sql` template tag — captures a tagged-template literal into a
  * {@link RawSqlFragment} descriptor without binding it to any client.
@@ -1567,7 +1682,7 @@ export declare interface SquashResult {
     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 {
+declare interface Table<Name extends string, Fields extends Record<string, ColumnDefinition<unknown>>, Reactive extends boolean = true, IxNames extends string = never> extends TableLike {
     readonly tableName: Name;
     readonly fields: Fields;
     readonly isReactive: Reactive;
@@ -1879,11 +1994,39 @@ declare interface Table<Name extends string, Fields extends Record<string, Colum
      */
     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.
+     * Turn reactivity OFF for this table.
+     *
+     * Not "off across instances" — off. The table emits no change events at all:
+     * no local subscriber fires, no cross-instance transport carries it. That is
+     * what the name says, and a version of this that only silenced the
+     * cross-instance half would leave every in-process subscription live on a
+     * table declared non-reactive.
+     *
+     * Reactivity is the default because that is what this framework is for. The
+     * inverse (`.reactive()`) was the API for a long time and failed in both
+     * directions silently: written on mariadb it did nothing at all, omitted on
+     * postgres+cdc it meant a write on one instance never reached another
+     * instance's subscribers.
+     *
+     * Implemented in EVERY dialect, at the store's emit:
+     *
+     *   memory      the store's single emit point drops the event
+     *   sqlite /    same, and turso reuses that store
+     *   turso
+     *   postgres    also: no `REPLICA IDENTITY FULL`, no `pg_notify` trigger
+     *   mysql /     also: excluded from the binlog reader's table filter
+     *   mariadb
+     *   mssql       also: excluded from the Change Tracking table set
+     *
+     * The WRITE is unaffected — this is about notification, never persistence.
+     *
+     * Worth using for a genuinely hot table nobody subscribes to: an append-only
+     * event log, a metrics sink. On postgres it also drops `REPLICA IDENTITY
+     * FULL`, which widens every UPDATE/DELETE in the WAL. Do NOT use it on a
+     * table a query reads — that subscription simply never fires. `voltro dev`
+     * says so at boot.
      */
-    reactive: () => Table<Name, Fields, true, IxNames>;
+    nonReactive: () => Table<Name, Fields, false, IxNames>;
 }
 
 /**