@voltro/database 0.77.1 → 0.78.0

package/dist/sql.d.ts

@@ -2222,6 +2222,42 @@ 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>;
 }
 
 /**
@@ -2286,6 +2322,9 @@ 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;
+
 /**
  * Parse `VOLTRO_DESTRUCTIVE_OK`.
  *
@@ -2757,6 +2796,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 +2942,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 +2995,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 +3027,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`. */
@@ -3305,6 +3388,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 +3410,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 +3490,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
@@ -3555,6 +3645,18 @@ export declare type MigrationOperation = {
     readonly dropConstraints: ReadonlyArray<string>;
 };
 
+/**
+ * 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). */
@@ -3962,7 +4064,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 +4075,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;
@@ -4028,6 +4154,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 +5222,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;
 }
 
 /**
@@ -5185,6 +5328,31 @@ export declare interface SchemaApplyOptions {
 /** 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 +5518,16 @@ export declare interface SquashResult {
     readonly snapshotId: string;
 }
 
+/** 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
@@ -6164,6 +6342,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>>;