@voltro/database 0.11.4 → 0.13.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;
 
 /**
@@ -1498,6 +1578,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.