@voltro/database 0.34.0 → 0.35.0

package/dist/sql.d.ts

@@ -7,7 +7,7 @@ import { SqlError } from '@effect/sql';
 import { SqlError as SqlError_2 } from '@effect/sql/SqlError';
 import { Statement } from '@effect/sql';
 
-export declare const acquireMigrationLock: (sql: SqlClient.SqlClient) => Effect.Effect<void, SqlError_2>;
+export declare const acquireMigrationLock: (sql: SqlClient.SqlClient, scope?: MigrationLockScope) => Effect.Effect<void, SqlError_2>;
 
 declare interface AggregateColumn<TResult = number | Date | null> {
     readonly op: 'count' | 'sum' | 'avg' | 'min' | 'max' | 'count-distinct' | 'window-row-number' | 'window-rank' | 'window-dense-rank' | 'window-lag' | 'window-lead' | 'window-sum-over' | 'window-avg-over' | 'column';
@@ -58,6 +58,14 @@ declare type AnyTable = Table<string, Record<string, ColumnDefinition<unknown>>,
 
 declare type AnyView = View<string, Record<string, ColumnDefinition<unknown>>>;
 
+/**
+ * The dialect-correct value for an `appliedAt` column, given an ISO instant.
+ *
+ * MySQL-family: UTC wall clock, `YYYY-MM-DD HH:MM:SS.fff`.
+ * Everything else: the ISO string, offset included.
+ */
+export declare const appliedAtValue: (sql: SqlClient.SqlClient, iso: string) => Effect.Effect<string>;
+
 /**
  * One row of `_voltro_migrations` — what the applier writes after a
  * successful plan execution. Same shape exposed via inspect RPC for
@@ -106,7 +114,7 @@ export declare interface AppliedOp {
  * no-op (except sqlite's ATTACH, which the splitter runs standalone and
  * whose "already attached" error the caller can ignore).
  */
-export declare const applyNamespacedSchema: (tables: ReadonlyArray<AnyTable>, namespace: string, dialect?: DialectId) => Effect.Effect<void, never, SqlClient.SqlClient>;
+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.
@@ -145,6 +153,15 @@ export declare interface ApplyPlanCtx {
     readonly source: 'auto-diff' | 'file';
     /** Optional human note via `voltro db apply --note "..."`. */
     readonly notes?: string;
+    /**
+     * Schema scope for the migration advisory lock (see `migrations/lock.ts`).
+     * Absent → resolved from configuration (`DB_SCHEMA`), which is what every
+     * CLI path wants; explicit for programmatic callers whose schema does not
+     * come from the environment. Every taker of this lock must resolve the
+     * scope the same way, or two writers in one schema stop excluding each
+     * other — worse than the cluster-wide key this replaced.
+     */
+    readonly lockSchema?: string;
     /**
      * Re-plan against the LIVE schema — the convergence proof.
      *
@@ -172,23 +189,13 @@ export declare interface ApplyPlanCtx {
     readonly replan: (sql: SqlClient.SqlClient) => Effect.Effect<MigrationPlan, SqlError_2, SqlClient.SqlClient>;
 }
 
-/**
- * Effect that applies the emitted DDL to the provided SqlClient. Splits
- * on `;` only outside dollar-quoted blocks (the postgres NOTIFY trigger
- * function body uses `$$`), so the plpgsql block stays intact as a
- * single statement. SQLite has no `$$` quoting so the splitter is a
- * superset.
- *
- * Caller passes the dialect explicitly. Defaults to `'postgres'` for
- * call-sites that haven't migrated yet.
- */
 export declare const applySchema: (tables: ReadonlyArray<AnyTable>, dialect?: DialectId, 
 /** NOTIFY channel for the reactive triggers. Pass the SAME value the store
  *  was built with. They are two halves of one contract and used to be able to
  *  disagree silently: the store listened on its `cdcChannel` while the DDL
  *  always emitted on the default, so a custom channel received nothing and
  *  raised nothing. */
-cdcChannel?: string) => Effect.Effect<void, never, SqlClient.SqlClient>;
+cdcChannel?: string, options?: SchemaApplyOptions) => Effect.Effect<void, never, SqlClient.SqlClient>;
 
 /**
  * The OPT-IN refuse gate over the advisory. By default (`VOLTRO_ROLLING_DEPLOY`
@@ -1275,6 +1282,8 @@ export declare interface FileMigrationRunResult {
  */
 export declare const fingerprintSchema: (snapshot: SchemaSnapshot) => string;
 
+export declare const fnv1a64: (input: string) => bigint;
+
 /** 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;
@@ -1450,6 +1459,20 @@ export declare const isFileMigration: (value: unknown) => value is FileMigration
 /** Type guard — narrows an unknown value to a {@link RawSqlFragment}. */
 export declare const isRawSqlFragment: (value: unknown) => value is RawSqlFragment;
 
+/**
+ * True when re-RUNNING this exact statement is a no-op if the previous attempt
+ * (or a sibling process) already applied it. This is what makes an IN-PLACE
+ * statement retry sound on the per-operation dialects: the auto-migrate
+ * emitter's DDL is `IF NOT EXISTS`-shaped almost everywhere, and mysql's one
+ * exception (plain `CREATE INDEX` — the dialect cannot spell the conditional)
+ * is tolerated by `isReRunnableDuplicateIndex` above, which is precisely the
+ * re-run contract this predicate leans on. Anything else (sqlite `ATTACH`,
+ * a bare `ADD CONSTRAINT`) is NOT a retry candidate: a half-applied non-
+ * idempotent statement retried blindly turns a transient error into a
+ * confusing permanent one.
+ */
+export declare const isReRunSafeDdl: (statement: string, dialect: DialectId) => boolean;
+
 /**
  * A json-path index entry, produced by {@link jsonIndex}. Unlike a plain
  * `{ expr }` (verbatim, dialect-specific) this carries the column + path
@@ -1497,6 +1520,40 @@ declare type MergeMixinFields<Mixins extends ReadonlyArray<AnyMixin>> = Mixins e
  */
 export declare const migration: (spec: FileMigration) => FileMigration;
 
+/**
+ * The postgres advisory-lock key for a schema. Default schema (undefined /
+ * `'public'`) → the EXACT legacy constant (rolling-deploy pin, see above).
+ * Otherwise FNV-1a 64 of `voltro_migration_lock:<schema>`, with the sign
+ * bit cleared so the value is a positive signed 64-bit int (`pg_advisory_
+ * lock(bigint)`). Collisions across schemas are possible and ACCEPTABLE —
+ * a collision reintroduces serialization between two schemas, not a race.
+ */
+export declare const migrationLockKeyForSchema: (schema: string | undefined) => bigint;
+
+/**
+ * The mysql/mssql lock NAME for a schema. Default → the EXACT pre-1.5 name
+ * (`voltro_migration_<key36>`). Otherwise the schema is suffixed; MySQL
+ * caps `GET_LOCK` names at 64 chars, so a name that would overflow falls
+ * back to a hashed suffix (`_h<fnv-1a-64 hex>`, 46 chars total) instead of
+ * a server error. Note mysql's `GET_LOCK` scope is the SERVER: on
+ * mysql/mariadb `DB_SCHEMA` is not a connection pin (the database comes
+ * from the URL), but setting it to the database name is how two apps on
+ * one server un-share this lock.
+ */
+export declare const migrationLockNameForSchema: (schema: string | undefined) => string;
+
+/**
+ * Which schema's migration lock to take. `schema` undefined → resolve from
+ * configuration (`DB_SCHEMA`, the same variable `connectionConfig.ts` pins
+ * the postgres `search_path` from); the empty string and `'public'`
+ * normalize to the default scope. The scope must come from CONFIGURATION —
+ * never from a per-call `current_schema()` probe, whose answer can drift
+ * per session while the configured value cannot.
+ */
+export declare interface MigrationLockScope {
+    readonly schema?: string | undefined;
+}
+
 /**
  * Discriminated union for the concrete DDL operations the planner
  * emits. Every variant carries the `table` (most ops act on one
@@ -1725,6 +1782,18 @@ declare interface NarrowedFromSpec {
     readonly using?: string;
 }
 
+/**
+ * Postgres identifier for the trigger function backing a given channel.
+ *
+ * Derived from the channel, NOT a single global name, and that is the whole
+ * point: `CREATE OR REPLACE FUNCTION framework_notify_change()` is one row in
+ * `pg_proc` for the entire database, so two schemas applied with different
+ * channels overwrote each other and the last one won. Everything applied
+ * earlier then emitted on somebody else's channel — silently, because a NOTIFY
+ * nobody listens to is not an error.
+ */
+export declare const notifyFunctionName: (channel: string) => string;
+
 /** Negation of an arbitrary sub-predicate → `NOT (...)`. Wraps any
  *  leaf/and/or/subquery subtree (distinct from the per-column `neq` and
  *  the narrow `notInSubquery`/`notExists`). */
@@ -1938,13 +2007,19 @@ declare interface PredicateLeaf {
  * 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).
+ * The seeds run through `setTenantCreateSeedHook` — the hook itself IS
+ * installed at boot (`seedRunner.ts`); 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).
+ *
+ * Wired by BOTH boot paths through `makeTenantProvisioner` (@voltro/cli):
+ * under `tenantIsolation: 'namespace'` on a SQL dialect, every namespace store
+ * view provisions lazily on first use — memoised per namespace per process.
+ * Eager provisioning is the APP's move (call this from a seed/startup over its
+ * own tenant table); the framework has no tenant registry to enumerate.
  */
-export declare const provisionTenantNamespace: (tables: ReadonlyArray<AnyTable>, namespace: string, sqlLayer: Layer.Layer<SqlClient.SqlClient, ConfigError.ConfigError | SqlError.SqlError, never>, dialect?: DialectId) => Promise<void>;
+export declare const provisionTenantNamespace: (tables: ReadonlyArray<AnyTable>, namespace: string, sqlLayer: Layer.Layer<SqlClient.SqlClient, ConfigError.ConfigError | SqlError.SqlError, never>, dialect?: DialectId, options?: SchemaApplyOptions) => Promise<void>;
 
 /**
  * The runtime-facing materialized query — a plain bag of strings the store and
@@ -2274,6 +2349,15 @@ export declare interface ReactiveTriggerDrift {
     readonly functionOutdated: boolean;
 }
 
+/**
+ * Trigger name for one table on one channel.
+ *
+ * The channel is part of the name so a table reachable from two channels keeps
+ * one trigger per channel, instead of the second install's `DROP TRIGGER IF
+ * EXISTS` silently removing the first.
+ */
+export declare const reactiveTriggerName: (tableName: string, channel: string) => string;
+
 /**
  * The statements that bring the DATABASE's change triggers back in line with
  * what the schema declares.
@@ -2400,12 +2484,21 @@ export declare const rehearsedOperation: (planned: PlannedOperation) => Rehearse
  */
 export declare const rehearseMigrationOnBranch: (ops: BranchRehearsalOps) => Promise<BranchRehearsalReport>;
 
-export declare const releaseMigrationLock: (sql: SqlClient.SqlClient) => Effect.Effect<void, SqlError_2>;
+export declare const releaseMigrationLock: (sql: SqlClient.SqlClient, scope?: MigrationLockScope) => Effect.Effect<void, SqlError_2>;
 
 export declare const renderColumnMysql: (col: ColumnSnapshot) => string;
 
 export declare const renderColumnPg: (col: ColumnSnapshot) => string;
 
+/**
+ * The effective lock schema: an explicit scope wins; otherwise `DB_SCHEMA`
+ * (the one env var the CLI's connection resolver reads for the schema pin).
+ * `undefined` = the default schema → the legacy constant key/name.
+ */
+export declare const resolveMigrationLockSchema: (scope?: MigrationLockScope) => string | undefined;
+
+declare type RetryDecision = 'retry' | 'noRetry';
+
 /**
  * Roll back a single file-based migration by id. Looks up the
  * migration's `down` body via file discovery (the file must still be
@@ -2419,6 +2512,7 @@ export declare const renderColumnPg: (col: ColumnSnapshot) => string;
 export declare const rollbackFileBasedMigration: (sql: SqlClient.SqlClient, ctx: {
     projectRoot: string;
     id: string;
+    lockSchema?: string;
 }) => Effect.Effect<{
     id: string;
     durationMs: number;
@@ -2506,6 +2600,9 @@ export declare interface RunFileBasedMigrationsCtx {
     readonly projectRoot: string;
     readonly env: 'dev' | 'staging' | 'prod';
     readonly appliedBy: string;
+    /** Schema scope for the migration advisory lock (see `migrations/lock.ts`).
+     *  Absent → resolved from configuration (`DB_SCHEMA`). */
+    readonly lockSchema?: string;
 }
 
 /**
@@ -2516,7 +2613,7 @@ export declare interface RunFileBasedMigrationsCtx {
  * `voltro_isr_cache` so framework releases that grow new columns
  * don't crash old DBs at boot.
  */
-export declare const runFrameworkBootstrap: (tables: ReadonlyArray<AnyTable>, sqlLayer: Layer.Layer<SqlClient.SqlClient, ConfigError.ConfigError | SqlError.SqlError, never>, dialect?: DialectId) => Promise<void>;
+export declare const runFrameworkBootstrap: (tables: ReadonlyArray<AnyTable>, sqlLayer: Layer.Layer<SqlClient.SqlClient, ConfigError.ConfigError | SqlError.SqlError, never>, dialect?: DialectId, options?: SchemaApplyOptions) => Promise<void>;
 
 /**
  * Run `applySchema` against a fresh SqlClient from the provided sqlLayer.
@@ -2526,7 +2623,7 @@ export declare const runFrameworkBootstrap: (tables: ReadonlyArray<AnyTable>, sq
  * `dialect` is passed through to the DDL emitter so SQL types + reactive
  * trigger emission match the underlying engine.
  */
-export declare const runMigrate: (tables: ReadonlyArray<AnyTable>, sqlLayer: Layer.Layer<SqlClient.SqlClient, ConfigError.ConfigError | SqlError.SqlError, never>, dialect?: DialectId) => Promise<void>;
+export declare const runMigrate: (tables: ReadonlyArray<AnyTable>, sqlLayer: Layer.Layer<SqlClient.SqlClient, ConfigError.ConfigError | SqlError.SqlError, never>, dialect?: DialectId, options?: SchemaApplyOptions) => Promise<void>;
 
 /**
  * Top-level entry point — called once per boot. Returns a
@@ -2545,6 +2642,36 @@ export declare interface RunPlannedMigrationsCtx {
     readonly dialectId: string;
 }
 
+/**
+ * Effect that applies the emitted DDL to the provided SqlClient. Splits
+ * on `;` only outside dollar-quoted blocks (the postgres NOTIFY trigger
+ * function body uses `$$`), so the plpgsql block stays intact as a
+ * single statement. SQLite has no `$$` quoting so the splitter is a
+ * superset.
+ *
+ * Caller passes the dialect explicitly. Defaults to `'postgres'` for
+ * call-sites that haven't migrated yet.
+ */
+/**
+ * Cross-cutting options for the auto-migrate apply entry points.
+ *
+ * `retryFilter` is the DIALECT's own transient-failure predicate
+ * (`SqlDialect.retryFilter`), threaded in by the caller because this package
+ * deliberately has NO dialect registry — the CLI loads the dialect module and
+ * hands its predicate through (optimizations 1.6). Absent → no retry, the
+ * pre-1.6 behavior. Present → a transient DDL failure (SQLITE_BUSY meeting
+ * the schema lock, a deadlock victim) is retried BOUNDED instead of dying on
+ * the first attempt while every equivalent DML statement would be retried.
+ *
+ * `lockSchema` scopes the migration advisory lock (see `migrations/lock.ts`);
+ * absent → `DB_SCHEMA` from the environment, the same configuration the
+ * connection's `search_path` pin reads.
+ */
+export declare interface SchemaApplyOptions {
+    readonly retryFilter?: (error: unknown) => RetryDecision;
+    readonly lockSchema?: string;
+}
+
 /**
  * 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
@@ -3331,6 +3458,11 @@ declare interface View<Name extends string, Fields extends Record<string, Column
  * `pg_advisory_lock(bigint)` wants a number; we hard-code a constant
  * inside the safe-integer range so every consumer races for the same
  * lock without doing string hashing at runtime.
+ *
+ * This is the key for the DEFAULT schema, and it must stay EXACTLY this
+ * value: a rolling deploy of a default-schema app has old and new
+ * replicas migrating side by side, and they can only serialize if both
+ * generations compute the SAME key.
  */
 export declare const VOLTRO_MIGRATION_LOCK_KEY = 6322741009312437n;
 
@@ -3366,7 +3498,7 @@ declare interface WindowSpec {
  * leaves the postgres lock held until that connection closes (which
  * the pooled SqlClient does on Effect scope cleanup).
  */
-export declare const withMigrationLock: <A, E, R = never>(sql: SqlClient.SqlClient, work: Effect.Effect<A, E, R>) => Effect.Effect<A, E | SqlError_2, R>;
+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>;
 
 /** Tree of relations to eager-load. */
 declare type WithSpec = Readonly<Record<string, true | EagerLoadSpec>>;