@voltro/database 0.33.0 → 0.34.0

package/dist/sql.d.ts

@@ -116,11 +116,15 @@ export declare const applyNamespacedSchema: (tables: ReadonlyArray<AnyTable>, na
  *   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. For each op in plan order: emit the DDL, run any backfill,
- *      mark applied.
- *   4. Write a row to `_voltro_migration_plans` with the post-state
- *      fingerprint + operations JSON + duration + environment.
- *   5. Release the advisory lock.
+ *   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.
@@ -247,6 +251,78 @@ export declare type BootMigrationOutcome = {
     readonly plan: MigrationPlan;
 };
 
+/** Which engine-level mechanism stands a branch up. `namespace` = the portable
+ *  schema/database snapshot (every dialect); `neon-cow` = Neon's instant
+ *  copy-on-write branch API (zero-copy, Neon only). */
+declare type BranchMechanism = 'namespace' | 'neon-cow';
+
+/**
+ * The CI exit code.
+ *
+ *   0 — rehearsed clean and converged.
+ *   2 — a REVIEW signal: the plan destroys data, or the planner refuses part of
+ *       it. The migration may well be correct; a human has to say so.
+ *   1 — the rehearsal could not answer: it failed, the branch was not faithful,
+ *       or the migration did not converge.
+ *
+ * `lossy` is deliberately NOT an error. A `drop-column` in a PR is a normal,
+ * intentional thing; making it exit 1 trains people to pass `--force`, and the
+ * next real failure goes with it.
+ */
+export declare const branchRehearsalExitCode: (report: BranchRehearsalReport) => number;
+
+export declare interface BranchRehearsalOps {
+    readonly branchId: string;
+    readonly mechanism: BranchMechanism;
+    readonly branchedTables: number;
+    readonly replayedForeignKeys: number;
+    /** Stand the branch up. Throwing here yields `outcome: 'failed'`. */
+    readonly provision: () => Promise<void>;
+    /**
+     * The FIDELITY check: plan the PARENT's live schema against the BRANCH. Empty
+     * ⇒ the branch is a faithful copy. Supplied as a function rather than a
+     * boolean so the caller does the introspection it already knows how to do.
+     */
+    readonly fidelityPlan: () => Promise<MigrationPlan>;
+    /** Plan the DECLARED schema against the branch — the migration under review. */
+    readonly plan: () => Promise<MigrationPlan>;
+    /** Execute a (lossy-unblocked) plan on the branch. */
+    readonly apply: (plan: MigrationPlan) => Promise<void>;
+    /** Re-plan after the apply. Empty ⇒ converged. */
+    readonly replan: () => Promise<MigrationPlan>;
+    /** Drop the branch. Skipped when `keep`. */
+    readonly teardown: () => Promise<void>;
+    readonly keep?: boolean;
+    readonly log?: (message: string) => void;
+}
+
+export declare interface BranchRehearsalReport {
+    readonly branchId: string;
+    readonly mechanism: BranchMechanism;
+    readonly outcome: RehearsalOutcome;
+    /** Tables the branch was stood up with. */
+    readonly branchedTables: number;
+    /** Foreign keys replayed into the branch (`LIKE` does not copy them). */
+    readonly replayedForeignKeys: number;
+    /** Every operation the plan proposed, classified. */
+    readonly operations: ReadonlyArray<RehearsedOperation>;
+    /** The subset that destroys data — what a PR comment leads with. */
+    readonly lossy: ReadonlyArray<RehearsedOperation>;
+    /** Operations still refused after the branch's lossy unblock. */
+    readonly blocked: ReadonlyArray<RehearsedOperation>;
+    /** Was the plan actually executed on the branch? */
+    readonly applied: boolean;
+    /** Did the re-plan come back empty? `false` whenever `applied` is false. */
+    readonly converged: boolean;
+    /** What the re-plan still proposes — empty iff `converged`. */
+    readonly residual: ReadonlyArray<RehearsedOperation>;
+    /** Non-empty ⇒ the branch diverged from the parent BEFORE the plan ran. */
+    readonly infidelity: ReadonlyArray<RehearsedOperation>;
+    /** Was the branch torn down (false ⇒ `--keep`, or teardown failed). */
+    readonly tornDown: boolean;
+    readonly error?: 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. */
@@ -1002,6 +1078,14 @@ declare interface EagerLoadSpec {
     readonly onJunction?: Predicate;
 }
 
+export declare const emitAddIndexMysql: (op: Extract<MigrationOperation, {
+    kind: "add-index";
+}>, declared: ReadonlyArray<TableLike>) => string;
+
+export declare const emitCreateTableMysql: (op: Extract<MigrationOperation, {
+    kind: "create-table";
+}>) => ReadonlyArray<string>;
+
 export declare const emitDropColumnDdl: (op: Extract<MigrationOperation, {
     kind: "drop-column";
 }>, q: typeof quote) => string;
@@ -1191,6 +1275,10 @@ export declare interface FileMigrationRunResult {
  */
 export declare const fingerprintSchema: (snapshot: SchemaSnapshot) => string;
 
+/** Human/PR-comment rendering. Markdown-free on purpose — the CI job that posts
+ *  it to a PR wraps it, and a terminal reader gets the same text. */
+export declare const formatBranchRehearsal: (report: BranchRehearsalReport) => string;
+
 /** Human report, or `undefined` when the database and the schema agree. */
 export declare const formatReactiveTriggerDrift: (drift: ReactiveTriggerDrift) => string | undefined;
 
@@ -1598,6 +1686,25 @@ declare interface MixinIndex {
     readonly kindOptions?: IndexKindOptions;
 }
 
+/**
+ * How long a prefix a MySQL/MariaDB index key may take on this column.
+ *
+ * `undefined` when the column cannot be found — an introspected-only column
+ * with no live declaration. The caller then emits an unprefixed key, which is
+ * right for every non-text type and only risks "key too long" for an undeclared
+ * text one.
+ *
+ * A second guard, deliberately, and not because the first one is doubted: the
+ * defect above was a renderer losing the column's parameters on the way to a
+ * type decision, and that is a mistake a future path can make again. This one
+ * cannot emit a prefix longer than the column, whatever concluded it needed
+ * one — `min(191, declaredLength)`, which is what the reporter proposed.
+ *
+ * `undefined` = no prefix clause at all (the column is not text-like, or is
+ * unbounded and takes the full 191).
+ */
+export declare const mysqlIndexPrefixFor: (col: ColumnSnapshot | undefined) => number | undefined;
+
 /**
  * Type-narrowing migration marker. Tells the planner that this column
  * previously had type `from` and is now being narrowed/converted to its
@@ -1824,6 +1931,18 @@ declare interface PredicateLeaf {
  * Imperative `applyNamespacedSchema` against a fresh SqlClient — the
  * entry point the CLI / runtime use to provision a tenant's namespace
  * (eager at migrate time, or lazily on first use).
+ *
+ * **This is where `lifecycle: 'onTenantCreate'` seeds fire**, after the DDL
+ * lands and before this resolves — so a caller that awaits provisioning gets
+ * a tenant whose tables AND reference data exist, or an error. It was the
+ * missing half: the lifecycle validated, registered, and never ran, so every
+ * tenant came up empty and nothing said so.
+ *
+ * The seeds run through the hook the CLI installs at boot
+ * (`setTenantCreateSeedHook`); with no seeds declared this costs one null
+ * check. A seed failure REJECTS — see `fireTenantCreateSeeds` for why, and
+ * note that re-calling this function is safe (the DDL is `IF NOT EXISTS` and
+ * seed steps are idempotent by contract).
  */
 export declare const provisionTenantNamespace: (tables: ReadonlyArray<AnyTable>, namespace: string, sqlLayer: Layer.Layer<SqlClient.SqlClient, ConfigError.ConfigError | SqlError.SqlError, never>, dialect?: DialectId) => Promise<void>;
 
@@ -2110,11 +2229,22 @@ export declare interface RawSqlFragment {
     readonly strings: ReadonlyArray<string>;
     readonly values: ReadonlyArray<unknown>;
     /**
-     * Tables this raw read depends on, for reactive invalidation. Raw
-     * reads are otherwise untracked — the query planner can't infer which
-     * tables an arbitrary SQL string touches. Declare them here (or via
-     * `store.raw(fragment, { dependsOn })`) to opt the read into the
-     * reactive layer's change-driven recomputation.
+     * Tables this raw read depends on, for reactive invalidation. Raw reads are
+     * otherwise untracked — the query planner cannot infer which tables an
+     * arbitrary SQL string touches. Declare them here (or via
+     * `store.raw(fragment, { dependsOn })`).
+     *
+     * WHAT IT DRIVES, stated narrowly because the previous wording promised more
+     * than any code delivered. For a live query whose handler returns a COMPUTED
+     * VALUE — the shape whose handler is genuinely re-run on a change — these
+     * tables JOIN the query's declared `source:`, so a write to one recomputes the
+     * subscription. That is the only shape where re-running can refresh a raw
+     * result. A handler that returns a query DESCRIPTOR re-runs the DESCRIPTOR on
+     * a change, not the handler, so declaring tables cannot refresh the raw read
+     * there; the runtime warns about that case at subscribe time instead.
+     *
+     * Best-effort in both directions: the tables are recorded as declared and
+     * never validated against the SQL.
      */
     readonly dependsOn?: ReadonlyArray<string>;
 }
@@ -2128,6 +2258,20 @@ export declare interface ReactiveTriggerDrift {
     /** 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>;
+    /**
+     * The notify FUNCTION exists but its body predates this build
+     * (`NOTIFY_BODY_MARKER` absent from `pg_proc.prosrc`).
+     *
+     * Every trigger can be present, every table correct, and the PAYLOADS still
+     * be wrong — which is a state no per-table check can see. It matters because
+     * of what the body changed: an oversized payload (a row over pg_notify's
+     * 8000-byte cap) that does not carry the primary key cannot be re-read, so
+     * the change reaches every tap as a non-event and is lost with nothing
+     * logged. False when the function is ABSENT — nothing calls a function that
+     * does not exist, and "no reactivity here" is the missing/stale report's
+     * business, not this one's.
+     */
+    readonly functionOutdated: boolean;
 }
 
 /**
@@ -2160,9 +2304,102 @@ export declare const reactiveTriggerRepairSql: (input: {
     readonly missing: ReadonlyArray<string>;
     /** Table names the detector found triggered-but-declared-nonReactive. */
     readonly stale: ReadonlyArray<string>;
+    /**
+     * The installed notify FUNCTION is older than the one this build emits
+     * (`detectReactiveTriggerDrift().functionOutdated`) — every trigger can be
+     * present and the payloads still be wrong. Replaces the body; touches no
+     * table.
+     */
+    readonly functionOutdated?: boolean;
     readonly channel?: string;
 }) => ReadonlyArray<string>;
 
+/**
+ * Record that a schema was applied even though there was nothing to DO.
+ *
+ * ── The deadlock this exists to remove ──────────────────────────────────────
+ *
+ * `applyPlan` is the only writer of `_voltro_migration_plans`, and every caller
+ * short-circuits before it when `operations.length === 0`. So a plan with an
+ * empty diff records nothing — and `checkProdSchema` compares the DECLARED
+ * fingerprint against the last recorded row.
+ *
+ * Those two rules are individually reasonable and together they deadlock. A
+ * consumer walked into it on an upgrade-only deploy and reproduced it in
+ * isolation on a restored database:
+ *
+ *   1. `voltro serve`            → refuses: declared=8aaa5c9b live=72c2305a
+ *   2. `db files` / `db plan` / `db apply --plan`  → "schema is up to date",
+ *                                  0 operations, exit 0, nothing recorded
+ *   3. `voltro serve`            → the identical refusal
+ *   4. introduce ANY real delta  → apply has work, records, and
+ *   5. `voltro serve`            → boots
+ *
+ * There is no path from 1 to 5 through the documented commands. The migrate job
+ * is the gate that is supposed to stop a bad release: it passes, and then every
+ * pod CrashLoopBackOffs, pointing at the command that just succeeded. The
+ * remaining exit is the error message's own suggestion — turn the check off —
+ * and a safety gate disabled to work around bookkeeping stays off.
+ *
+ * `db drift --accept` is not the escape hatch and the consumer checked: drift
+ * compares the LIVE side against the recorded `liveFingerprint`, and the live
+ * side had not moved. What moved is the DECLARED side, which drift never reads.
+ *
+ * ── Why this is a recording rule and not a fingerprint question ─────────────
+ *
+ * A framework upgrade is allowed to change what the declared fingerprint hashes.
+ * Their own note says so, and they are right. What is not allowed is for that
+ * change to be uncatchable: an apply that ran and found nothing to do IS a
+ * successful apply of that schema, and recording it is what makes that sentence
+ * true tomorrow.
+ *
+ * ── Idempotent on purpose ──────────────────────────────────────────────────
+ *
+ * It writes only when the fingerprint is not already the latest recorded one.
+ * `voltro dev` re-boots on every file save; a row per boot would put this table
+ * on the list of things that grow without bound, which is a list this release
+ * has spent enough time on.
+ */
+export declare const recordUpToDate: (sql: SqlClient.SqlClient, plan: MigrationPlan, ctx: {
+    readonly appliedBy: string;
+    readonly environment: "dev" | "staging" | "prod";
+    readonly source: string;
+}) => Effect.Effect<"recorded" | "already-current", never>;
+
+export declare type RehearsalOutcome = 
+/** The plan applied on the branch and the re-plan was empty. Nothing lossy. */
+'clean'
+/** Applied + converged, but the plan destroys data. A review signal, not a failure. */
+| 'lossy'
+/** The plan carries operations the planner refuses to auto-apply even on a
+*  throwaway branch (`needs-rename-annotation`, `multi-step`). */
+| 'blocked'
+/** Applied, and the re-plan STILL proposes work — the migration does not converge. */
+| 'diverged'
+/** The branch is not a faithful copy of the parent, so nothing below it can be trusted. */
+| 'infidelity'
+/** Provisioning or the apply threw. */
+| 'failed';
+
+/** One operation the rehearsal wants a human to look at, flattened for a PR comment. */
+export declare interface RehearsedOperation {
+    readonly kind: string;
+    readonly table: string | undefined;
+    readonly classification: PlannedOperation['classification'];
+    readonly reason: string | undefined;
+    /** The `fix` the planner would have printed had this run against production. */
+    readonly blockedFix: string | undefined;
+}
+
+export declare const rehearsedOperation: (planned: PlannedOperation) => RehearsedOperation;
+
+/**
+ * Run the rehearsal. Never throws for a database-side failure — a rehearsal that
+ * blows up is itself a result the caller has to report, and swallowing the
+ * teardown behind an exception is how branches leak.
+ */
+export declare const rehearseMigrationOnBranch: (ops: BranchRehearsalOps) => Promise<BranchRehearsalReport>;
+
 export declare const releaseMigrationLock: (sql: SqlClient.SqlClient) => Effect.Effect<void, SqlError_2>;
 
 export declare const renderColumnMysql: (col: ColumnSnapshot) => string;