@voltro/database 0.54.0 → 0.56.0

package/dist/sql.d.ts

@@ -126,27 +126,6 @@ export declare interface AppliedOp {
  */
 export declare const applyNamespacedSchema: (tables: ReadonlyArray<AnyTable>, namespace: string, dialect?: DialectId, options?: SchemaApplyOptions) => 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. Bootstrap the resume ledger and finish any run a crash left behind
- *      (see `resolveInterruptedRun`).
- *   4. Record every operation that will run OUTSIDE a transaction, then for
- *      each op in plan order: mark it started, emit the DDL, run any backfill,
- *      mark it applied.
- *   5. Write a row to `_voltro_migration_plans` with the post-state
- *      fingerprint + operations JSON + duration + environment, and clear the
- *      ledger.
- *   6. 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 {
@@ -173,10 +152,15 @@ export declare interface ApplyPlanCtx {
      */
     readonly lockSchema?: string;
     /**
-     * Re-plan against the LIVE schema — the convergence proof.
+     * Re-plan against the LIVE schema. Called TWICE, for two different questions.
+     *
+     * **Under the lock, BEFORE any DDL** — because the plan was computed before
+     * the lock was held, and two writers booting at once both plan against the
+     * same live state. The loser would otherwise apply a plan for a database that
+     * no longer exists.
      *
-     * `applyPlan` calls this once, after the DDL and BEFORE it records the
-     * fingerprint. A plan that converged re-plans to zero operations; anything
+     * **After the DDL and BEFORE the fingerprint is recorded** — the convergence
+     * proof. 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.
@@ -196,6 +180,13 @@ export declare interface ApplyPlanCtx {
      * report drift that isn't there. A caller that cannot re-plan cannot prove it
      * applied anything.
      *
+     * **It has to answer about the schema as it is AT THE MOMENT OF THE CALL.** A
+     * fake that returns a constant is fine for the second call and wrong for the
+     * first: answering "nothing to do" before the DDL makes `applyPlan` skip the
+     * very plan under test. What the caller's own unblock decision (`unblockLossy`)
+     * did to the plan is NOT re-derived here — `applyPlan` carries it forward
+     * itself, because the planner has no memory of it.
+     *
      * **USE THE `sql` THIS HANDS YOU.** It is the connection the apply ran on, and
      * that is the point: the convergence proof has to observe the session that
      * made the change. A re-plan that opens its OWN connection is asking a