@voltro/database 0.62.3 → 0.64.0

package/dist/sql.d.ts

@@ -419,6 +419,14 @@ declare interface ColumnDefinition<TsType, Type extends ColumnType = ColumnType,
      * has nothing to do with FK semantics.
      */
     readonly refOnUpdate?: 'cascade' | 'restrict' | 'setNull' | 'noAction';
+    /**
+     * What the RUNTIME does to this column's rows when the referenced row is
+     * SOFT-deleted (`deletedAt` set) — set by `reference(…, { onSoftDelete })`.
+     * A foreign key never sees a soft delete (it is an UPDATE), so `onDelete`
+     * cannot express it; the store's post-commit change channel enforces this
+     * one instead, the way `pluginRef` orphan rules are enforced.
+     */
+    readonly refOnSoftDelete?: 'cascade' | 'setNull';
     /**
      * Auto-create a B-tree index on this FK column. Default `true` — FK
      * columns are nearly always read-by, and the lookup cost of a missing
@@ -522,12 +530,16 @@ declare interface ColumnDefinition<TsType, Type extends ColumnType = ColumnType,
     /**
      * Field-level encryption flag, set by `.encrypted()`. When `true`
      * the runtime's store middleware encrypts the value on write and
-     * decrypts on read via the registered field cipher (AES-256-GCM,
-     * keyed from the Secrets-Resolver — see `@voltro/plugin-governance`).
-     * The stored column is an opaque `enc:v1:…` string, so the DB type
-     * stays `text`. A row written while encryption is active can't be
+     * decrypts on read via the registered field cipher (AES-256-GCM, keyed
+     * from `VOLTRO_FIELD_ENCRYPTION_KEY` through the Secrets-Resolver — the
+     * framework registers it on both boot paths; `voltro dev` mints the key).
+     * The stored column is an opaque `enc:v2:…` string — bound by GCM's
+     * additional authenticated data to its table, column and row
+     * (`FieldBinding`), so a ciphertext copied into another row or column
+     * does not decrypt there — and the DB type stays `text`. A row written
+     * while encryption is active can't be
      * read back without the key — losing the key loses the data, by
-     * design. Boot fails loud if an `.encrypted()` column is present but
+     * design. Boot refuses if an `.encrypted()` column is declared but
      * no cipher is registered.
      */
     readonly encrypted?: boolean;
@@ -2091,6 +2103,15 @@ declare interface QueryDescriptor<R = Row> {
      *  rows (an admin view, a grace-period check). Same shape and same posture as
      *  `includeDeleted`. */
     readonly includeExpired?: boolean;
+    /**
+     * Lock the matched rows for the rest of the enclosing transaction — set by
+     * `.forUpdate()`. `SELECT … FOR UPDATE` on postgres / mysql / mariadb,
+     * `WITH (UPDLOCK, ROWLOCK)` on mssql; sqlite serialises writers already and
+     * emits nothing. Outside a transaction the lock is released as the statement
+     * ends, which is harmless and useless — the point is a read-modify-write
+     * whose read and write share one transaction.
+     */
+    readonly lock?: 'update';
     /**
      * Opt OUT of the runtime's automatic tenant scope on `tenant()` tables.
      * Set by `.unscoped()`. Honored by the runtime, same as `includeDeleted`.
@@ -2677,6 +2698,9 @@ export declare interface RunPlannedMigrationsCtx {
     readonly environment: BootEnvironment;
     /** Pretty-name dialect used for log lines. */
     readonly dialectId: string;
+    /** How long a soft-drop snapshot may sit before the boot warns about it
+     *  (`database.softDropRetentionDays`; default 7). */
+    readonly softDropRetentionDays?: number;
 }
 
 /**
@@ -3112,10 +3136,11 @@ declare interface Table<Name extends string, Fields extends Record<string, Colum
      * row with the same key is allowed — no hand-written
      * `generatedAs("CASE WHEN …")` column, no resurrection footgun.
      *
-     * **mysql / mariadb:** these engines have no partial-index support, so
-     * `.uniqueActive()` FAILS LOUDLY at migrate time (a full unique index would
-     * silently forbid re-creating a soft-deleted row). Use a generated STORED
-     * column + `.unique()` there until the framework lowers it for you.
+     * **mysql / mariadb:** these engines have no partial-index support, so the
+     * migrator LOWERS `.uniqueActive()` to a generated STORED column holding the
+     * key while the predicate holds (NULL otherwise, and NULLs never collide) plus
+     * a UNIQUE index on it — the same guarantee, on the dialects that cannot
+     * spell it directly. See `lowerUniqueActive` in `migrate.ts`.
      */
     uniqueActive: {
         <const F extends readonly [keyof Fields & string, ...Array<keyof Fields & string>]>(fields: F, options?: {
@@ -3378,8 +3403,9 @@ declare interface TableIndex {
      * declarative planner is predicate-blind, these are emitted by the
      * fresh-schema DDL path (like every partial predicate) and kept OUT of the
      * declarative index snapshot. mysql/mariadb have no partial-index support —
-     * `.uniqueActive()` fails loudly there (use a generated column) rather than
-     * silently dropping the predicate into a full unique index.
+     * `.uniqueActive()` is lowered there to a generated STORED column + UNIQUE
+     * (`migrate.ts`) rather than silently dropping the predicate into a full
+     * unique index.
      */
     readonly unique?: boolean;
 }