@rvoh/dream 2.27.0 → 2.28.1

package/dist/types/src/decorators/field/sortable/helpers/sortableSnapshot.d.ts

@@ -0,0 +1,92 @@
+import Dream from '../../../../Dream.js';
+import DreamTransaction from '../../../../dream/DreamTransaction.js';
+import { SortableFieldConfig } from '../Sortable.js';
+/**
+ * @internal
+ *
+ * What a sortable position-mutating path knows about the row as it physically
+ * exists, rather than as the in-memory instance remembers it.
+ *
+ * `position` is the row's real position; `scopeValues` are the row's real sort
+ * scope column values, keyed by column. An instance loaded before another
+ * writer moved the row carries neither.
+ */
+export interface SortableSnapshot {
+    position: number | null;
+    scopeValues: Map<string, unknown>;
+}
+/**
+ * @internal
+ *
+ * Snapshots keyed by position field — a model may declare several sortable
+ * fields, each with its own scope and its own position space.
+ */
+export type SortableSnapshots = Map<string, SortableSnapshot>;
+/**
+ * @internal
+ *
+ * The outcome of a snapshot read: the snapshots themselves, plus whether the
+ * row was physically there to read.
+ *
+ * The two are deliberately separate. An empty `snapshots` map means only "no
+ * snapshot is available", which the model having no sortable fields produces
+ * just as readily as a row another writer has already deleted — and a caller
+ * that reads absence out of the empty map compacts a scope this operation never
+ * vacated.
+ */
+export interface SortableSnapshotRead {
+    /**
+     * False only when a read positively found no row. A read that never had to
+     * run — a model with no sortable fields — reports true, since it observed
+     * nothing.
+     */
+    rowExists: boolean;
+    snapshots: SortableSnapshots;
+}
+/**
+ * @internal
+ *
+ * Reads the record's real position and sort scope column values straight from
+ * the row, inside the given transaction.
+ *
+ * The read deliberately bypasses Dream's default scopes and goes to the table
+ * by primary key: soft-deleted rows have to be readable here (undestroy reads
+ * one), and an STI child's row is the same physical row whatever scope the
+ * class carries.
+ *
+ * When the row is not there the snapshots are empty and `rowExists` is false;
+ * a caller that goes on to compute a shift falls back to the instance, which is
+ * the pre-existing behavior.
+ *
+ * @param dream - the record to snapshot
+ * @param txn - the transaction the read runs in; the read must be protected by
+ *   whatever scope lock the caller holds in that transaction
+ * @param configs - the sortable fields whose position and scope columns to read
+ */
+export declare function readSortableSnapshots(dream: Dream, txn: DreamTransaction<any>, configs: SortableFieldConfig[]): Promise<SortableSnapshotRead>;
+/**
+ * @internal
+ *
+ * Stashes snapshots on the instance so the phase that computes the shift can
+ * reach the read the earlier phase made. The read and the shift are separate
+ * calls on every path — `prepareSortableFieldsForDestroy` to
+ * `performSortableDestroyWork`, the `saveDream` lock acquisition to
+ * `performSortablePositionWork` — and the instance is what crosses between
+ * them.
+ */
+export declare function cacheSortableSnapshots(dream: Dream, snapshots: SortableSnapshots): void;
+/**
+ * @internal
+ */
+export declare function sortableSnapshotFor(dream: Dream, positionField: string): SortableSnapshot | undefined;
+/**
+ * @internal
+ */
+export declare function clearSortableSnapshot(dream: Dream, positionField: string): void;
+/**
+ * @internal
+ *
+ * The value to filter a sort scope column by: the row's real value when a
+ * snapshot is available, and the caller's own fallback when it is not.
+ */
+export declare function snapshotScopeValue(snapshot: SortableSnapshot | undefined, column: string, fallback: () => unknown): unknown;

package/dist/types/src/decorators/field/sortable/helpers/stabilizeSortableScopeLocks.d.ts

@@ -0,0 +1,59 @@
+import Dream from '../../../../Dream.js';
+import DreamTransaction from '../../../../dream/DreamTransaction.js';
+/**
+ * How many acquisition passes a position-mutating operation will make while
+ * following a record that has been moved to another sort scope, before giving
+ * up. One pass is the ordinary case (lock what the caller says, read, agree); a
+ * second covers a competitor that moved the row between the two; a third exists
+ * so that a single unlucky retry is not fatal. Beyond that the row is being
+ * moved faster than it can be read, and raising is better than compacting a
+ * scope it no longer occupies.
+ *
+ * The bound counts acquisitions, and every one of them counts: the convergence
+ * check runs after the last acquisition and the read taken under it, so an
+ * operation that settles on its final pass settles rather than raising.
+ */
+export declare const MAX_SCOPE_STABILIZATION_ROUNDS = 3;
+/**
+ * @internal
+ *
+ * The stabilization protocol every sortable lock acquisition follows, in one
+ * place: acquire the keys the current knowledge implies, read again under those
+ * locks, and take whatever additional key the read reveals — until a pass
+ * reveals nothing new, or the bound above is exhausted.
+ *
+ * The bootstrapping problem it solves: a sort scope's lock key is derived from
+ * the record's *physical* scope columns, and those cannot be read safely until
+ * that scope is locked. So the first pass locks what the caller can know without
+ * reading — an instance's own values, or an unprotected candidate read — and
+ * every later pass locks what the read taken under those locks reveals.
+ *
+ * Nothing here is ever unwound: the locks are transaction-scoped advisory locks,
+ * which are additive and are released only when the transaction ends. A pass
+ * that discovers a new key simply also takes it, holding at worst one lock too
+ * many for the rest of the transaction — which costs contention and never
+ * correctness. That is what lets this run inside a caller-owned transaction
+ * unchanged; no path here restarts or rolls back a transaction it did not open.
+ *
+ * Keys the transaction already holds — taken by an earlier phase of the same
+ * operation, or by the preflight of the locked batch this record is being
+ * walked in — are not taken again; they are held to the end of the transaction
+ * regardless. Convergence is judged on that same set, so a pass whose read
+ * reveals only keys already held is a pass that agrees.
+ *
+ * Keys are taken in sorted order within a pass, so that two operations touching
+ * the same set of scopes cannot deadlock against each other. Across passes the
+ * order is discovery-driven and therefore unsortable in principle, which is the
+ * named fallback: two operations moving records in opposite directions between
+ * the same two scopes can raise Postgres's `40P01` deadlock error, a visible
+ * retryable failure.
+ *
+ * @param dream - a record of the model being locked; supplies the connection
+ *   and, when this fails, the class name in the error
+ * @param txn - the transaction the locks are scoped to
+ * @param keysForRound - reads whatever this pass can see — the caller's own
+ *   snapshot or candidate read — and returns every lock key it implies. Called
+ *   once per pass with the number of acquisitions made so far, so a caller whose
+ *   first pass needs no read can skip it on round 0
+ */
+export default function stabilizeSortableScopeLocks(dream: Dream, txn: DreamTransaction<any>, keysForRound: (round: number) => Promise<Iterable<bigint>>): Promise<void>;

package/dist/types/src/decorators/field/sortable/helpers/validPosition.d.ts

@@ -1,2 +1,14 @@
-import { SortableCacheWithRequiredTransaction } from './setPosition.js';
-export default function validPosition({ changingScope, dream, position, positionField, query, scope, wasNewRecord, previousPosition, txn, }: SortableCacheWithRequiredTransaction): Promise<number>;
+import { SortablePositionWrite } from './setPosition.js';
+/**
+ * @internal
+ *
+ * The position the record will be written at: the caller's, clamped to the
+ * scope the record now occupies.
+ *
+ * The scope is read off the instance rather than off the snapshot because the
+ * scope in question is the one being *entered*, which is the instance's — the
+ * snapshot holds the scope the row was in before the driver write. On every
+ * path into here the driver write has already landed the instance's scope
+ * values on the row.
+ */
+export default function validPosition({ changingScope, dream, position, positionField, positionUnderSentinel, query, scope, wasNewRecord, previousPosition, txn, }: SortablePositionWrite): Promise<number>;

package/dist/types/src/decorators/field/sortable/hooks/afterSortableCreate.d.ts

@@ -5,6 +5,6 @@ export default function afterSortableCreate({ positionField, dream, query, txn,
     positionField: string;
     dream: Dream;
     query: Query<Dream>;
-    txn?: DreamTransaction<any> | undefined;
+    txn: DreamTransaction<any>;
     scope: string | string[] | undefined;
 }): Promise<void>;

package/dist/types/src/decorators/field/sortable/hooks/afterSortableDestroy.d.ts

@@ -1,8 +1,10 @@
 import Dream from '../../../../Dream.js';
+import DreamTransaction from '../../../../dream/DreamTransaction.js';
 import Query from '../../../../dream/Query.js';
-export default function afterSortableDestroy({ positionField, dream, query, scope, }: {
+export default function afterSortableDestroy({ positionField, dream, query, scope, txn, }: {
     positionField: string;
     dream: Dream;
     query: Query<Dream>;
     scope: string | string[] | undefined;
+    txn: DreamTransaction<any>;
 }): Promise<void>;

package/dist/types/src/decorators/field/sortable/hooks/afterSortableUpdate.d.ts

@@ -5,6 +5,6 @@ export default function afterUpdateSortable({ positionField, dream, query, txn,
     positionField: string;
     dream: Dream;
     query: Query<Dream>;
-    txn?: DreamTransaction<any> | undefined;
+    txn: DreamTransaction<any>;
     scope: string | string[] | undefined;
 }): Promise<void>;

package/dist/types/src/dream/Query.d.ts

@@ -1328,9 +1328,11 @@ export default class Query<DreamInstance extends Dream, QueryTypeOpts extends Re
      *   read is a plain `FOR UPDATE`: if another transaction already holds a lock
      *   on one of the batch's rows, this call blocks until that transaction ends,
      *   holding its own transaction and its pooled connection open the whole
-     *   time. Dream sets no `lock_timeout` or `statement_timeout`, so a
-     *   long-running writer on the other side stalls the run indefinitely and, at
-     *   scale, ties up connections. If that is a risk in your application, set a
+     *   time. Dream sets no `lock_timeout` or `statement_timeout` on a row-lock
+     *   wait — the one it does set, around a sortable model's scope-lock
+     *   acquisition, is restored before the rows are claimed — so a long-running
+     *   writer on the other side stalls the run indefinitely and, at scale, ties
+     *   up connections. If that is a risk in your application, set a
      *   `lock_timeout` on the connection so a stuck batch fails instead of
      *   hanging.
      * - **A `limit` or `offset` on the Query is incompatible with `destroy` on
@@ -1408,6 +1410,36 @@ export default class Query<DreamInstance extends Dream, QueryTypeOpts extends Re
      * When the Query already carries a transaction, that transaction is used for
      * every batch rather than opening one per batch, so the caller's transaction
      * boundary wins and the locks are held until the caller commits.
+     *
+     * On a sortable model, the advisory scope keys this batch needs are acquired
+     * before the claim (see `acquireStabilizedSortableBatchLocks`), which removes
+     * the row-lock/advisory-lock inversion for the rows the batch itself claims.
+     * Two things stay outside that guarantee and are fallbacks rather than
+     * guarantees, with Postgres's `40P01` as the residual failure in both:
+     *
+     * - the ordering is **per batch**. A multi-batch run inside a caller-owned
+     *   transaction keeps batch N-1's row locks while batch N preflights. The
+     *   same shape accumulates *advisory* locks: they are released only when the
+     *   transaction ends, so every batch's scope keys are still held when the
+     *   next one preflights. That accumulation is bounded — the preflight counts
+     *   the keys the transaction already holds along with the ones the batch
+     *   would add, and refuses with `SortableBatchRequiresTooManyScopeLocks`
+     *   rather than letting a long run over a high-cardinality sort scope exhaust
+     *   `max_locks_per_transaction` for the whole cluster — so a run long enough
+     *   raises instead of completing. Letting Dream open a transaction per batch
+     *   releases the keys as it goes and gives each batch the whole budget.
+     * - the preflight covers **the claimed rows' own scopes only**. A
+     *   `dependent: 'destroy'` cascade under `destroy({ lock: true })` destroys
+     *   child records of other tables, and a sortable child takes its own table's
+     *   advisory key inside `perBatch` — after this transaction is already
+     *   holding the root rows' row locks. Walking
+     *   `dependentDestroyAssociationNames()` to fold those keys into the sorted
+     *   pass is deliberately not done: the cascade's shape is only knowable per
+     *   record, and the deadlock it leaves is detected and retryable. The keys
+     *   the preflight *did* take are held across the whole batch, cascade
+     *   included — a per-record destroy holds its scope lock across one delete
+     *   and one compaction, while here the hold spans batch size × cascade depth.
+     *   A smaller `batchSize` shortens it (the default is 10).
      */
     private lockedBatches;
     /**
@@ -1489,7 +1521,7 @@ export default class Query<DreamInstance extends Dream, QueryTypeOpts extends Re
      * use {@link Query.destroy} instead.
      *
      * ```ts
-     * await User.where({ email: ops.ilike('%burpcollaborator%').delete() })
+     * await User.where({ email: ops.ilike('%burpcollaborator%') }).delete()
      * // 12
      * ```
      *
@@ -1651,14 +1683,19 @@ export default class Query<DreamInstance extends Dream, QueryTypeOpts extends Re
      *   read is a plain `FOR UPDATE`: if another transaction already holds a
      *   lock on one of the batch's rows, this call blocks until that transaction
      *   ends, holding its own transaction and its pooled connection open the
-     *   whole time. Dream sets no `lock_timeout` or `statement_timeout`, so a
-     *   long-running writer on the other side stalls the run indefinitely and,
-     *   at scale, ties up connections. If that is a risk in your application,
-     *   set a `lock_timeout` on the connection so a stuck batch fails instead of
+     *   whole time. Dream sets no `lock_timeout` or `statement_timeout` on a
+     *   row-lock wait — the one it does set, around a sortable model's scope-lock
+     *   acquisition, is restored before the rows are claimed — so a long-running
+     *   writer on the other side stalls the run indefinitely and, at scale, ties
+     *   up connections. If that is a risk in your application, set a
+     *   `lock_timeout` on the connection so a stuck batch fails instead of
      *   hanging.
      * - **`skipHooks` composes with `lock`, but stays on the per-instance
      *   path.** With an attributes object and no `lock`, `skipHooks: true`
-     *   issues a single `UPDATE ... WHERE` statement that writes raw columns.
+     *   issues a single `UPDATE ... WHERE` statement that writes raw columns —
+     *   with one refusal: it will not write a non-null value into an
+     *   `@Encrypted` backing column, since nothing on that path encrypts it, and
+     *   throws instead; `null`, which clears the column, is permitted.
      *   With `lock: true`, `skipHooks: true` skips the model hooks on each
      *   claimed record but still writes through the instance, so custom setters
      *   — including the setters encrypted attributes encrypt through — run as
@@ -1681,6 +1718,7 @@ export default class Query<DreamInstance extends Dream, QueryTypeOpts extends Re
      * @throws InvalidBatchSize if `batchSize` is not a positive integer
      * @throws MissingRequiredLockOptionForUpdateCallback if a callback is passed without an options object carrying a boolean `lock`
      * @throws BatchingIncompatibleWithLimitOrOffset if the query carries a `limit` or `offset`
+     * @throws CannotSetEncryptedColumnInQueryUpdate if the single-statement `skipHooks` form's attributes name an `@Encrypted` backing column with anything other than `null`
      */
     update(cb: (record: DreamInstance) => UpdateableProperties<DreamInstance> | undefined | Promise<UpdateableProperties<DreamInstance> | undefined>, options: {
         lock: boolean;

package/dist/types/src/dream/QueryDriver/Base.d.ts

@@ -145,6 +145,62 @@ export default class QueryDriverBase<DreamInstance extends Dream> {
      * worker's lifetime.
      */
     static openTestDatabaseLockSession(connectionName: string): Promise<TestDatabaseLockSession>;
+    /**
+     * @internal
+     *
+     * Whether this driver implements the transaction-scoped advisory lock seam
+     * ({@link acquireAdvisoryTransactionLocks}). Adapters that can hold a
+     * key-addressed lock for the life of a transaction override this to `true`.
+     * It defaults to `false` so that a driver without the primitive fails loud
+     * for features that depend on it (today, the `Sortable` decorator) rather
+     * than silently racing on position values.
+     */
+    static supportsAdvisoryTransactionLocks: boolean;
+    /**
+     * @internal
+     *
+     * Acquire exclusive, transaction-scoped locks on arbitrary keys, waiting
+     * until any other transaction holding one of them finishes. The locks are
+     * released when the enclosing transaction commits or rolls back — never by an
+     * explicit unlock — so callers only ever have to acquire (Postgres:
+     * `pg_advisory_xact_lock(bigint)`).
+     *
+     * Unlike {@link applyRowLock}, this does not depend on rows existing: it is
+     * the only way to serialize writers that are about to insert into the same
+     * logical group. The `Sortable` decorator uses it to make each sort scope's
+     * position computation exclusive, keyed on the physical database, table,
+     * position field and scope values.
+     *
+     * The seam takes the whole key set rather than one key at a time so that a
+     * driver able to express it can take them in a single round trip — the
+     * batched, row-locking query APIs can need one key per candidate record per
+     * sortable field. **Keys must be acquired in the order given**: callers sort
+     * them, and that shared order is what keeps two operations over the same
+     * scopes from deadlocking. A driver that has no bulk form implements this by
+     * looping over the keys in order.
+     *
+     * **The wait must be bounded.** A caller that finds a key held waits for the
+     * holder's transaction, and an implementation that waits forever turns an
+     * ordinary mistake — a sortable operation issued without the enclosing
+     * transaction, so that it waits on a key that transaction itself holds — into
+     * a permanently wedged connection that no deadlock detector can see, because
+     * only one side is waiting. So an implementation applies the
+     * `sortableScopeLockTimeout` DreamApp option (milliseconds) to the
+     * acquisition and raises `SortableScopeLockWaitTimedOut` when it elapses. A
+     * configured `0` means no bound, and is applied just as literally: the
+     * acquisition waits without bound even where the connection carries a
+     * wait bound of its own. The bound belongs to
+     * the acquisition alone: whatever lock-wait behavior the connection was
+     * configured with has to be in force again by the time this returns, so that
+     * the row locks {@link applyRowLock} takes are unaffected.
+     *
+     * Only ever called when {@link supportsAdvisoryTransactionLocks} is `true`;
+     * the base default throws.
+     *
+     * @param txn - the transaction the locks are scoped to
+     * @param keys - the 64-bit signed lock keys, in acquisition order
+     */
+    static acquireAdvisoryTransactionLocks(txn: DreamTransaction<Dream>, keys: bigint[]): Promise<void>;
     static getColumnData(connectionName: string, tableName: string, allTableAssociationData: {
         [key: string]: SchemaBuilderAssociationData;
     }): Promise<{
@@ -391,8 +447,12 @@ export default class QueryDriverBase<DreamInstance extends Dream> {
      * @param dream - the dream instance you wish to destroy
      * @param txn - a transaction to encapsulate, consistently provided by underlying dream mechanisms
      * @param reallyDestroy - whether or not to reallyDestroy. If false, soft delete will be attempted when relevant
+     * @returns the number of rows this call removed (or soft deleted). Zero means
+     *   the row was already gone, or that a `preventDeletion` veto stopped the
+     *   write — callers distinguish the two by the veto flag, and use the count to
+     *   decide whether there is anything for the after-destroy hooks to act on.
      */
-    static destroyDream(dream: Dream, txn: DreamTransaction<Dream>, reallyDestroy: boolean): Promise<void>;
+    static destroyDream(dream: Dream, txn: DreamTransaction<Dream>, reallyDestroy: boolean): Promise<number>;
     static get syncDialect(): string;
     /**
      * Returns the sql that would be executed by this Query

package/dist/types/src/dream/QueryDriver/Kysely.d.ts

@@ -60,13 +60,17 @@ export default class KyselyQueryDriver<DreamInstance extends Dream> extends Quer
     static primaryKeyType(): LegacyCompatiblePrimaryKeyType;
     /**
      * destroys a dream, possibly implementing soft delete if reallyDestroy is false
-     * and the record being deleted implements soft delete.
+     * and the record being deleted implements soft delete. Does nothing at all when a
+     * beforeDestroy hook called `preventDeletion`.
      *
      * @param dream - the dream instance you wish to destroy
      * @param txn - a transaction to encapsulate, consistently provided by underlying dream mechanisms
      * @param reallyDestroy - whether or not to reallyDestroy. If false, soft delete will be attempted when relevant
+     * @returns the number of rows removed — zero when a `preventDeletion` veto
+     *   stopped the write, and zero when the row was already gone, which on the
+     *   soft delete path includes a row that is already soft deleted
      */
-    static destroyDream(dream: Dream, txn: DreamTransaction<Dream>, reallyDestroy: boolean): Promise<void>;
+    static destroyDream(dream: Dream, txn: DreamTransaction<Dream>, reallyDestroy: boolean): Promise<number>;
     /**
      * Converts the given dream class into a Kysely query, enabling
      * you to build custom queries using the Kysely API

package/dist/types/src/dream/QueryDriver/Postgres.d.ts

@@ -1,6 +1,7 @@
 import { type SelectQueryBuilder } from 'kysely';
 import Dream from '../../Dream.js';
 import { SchemaBuilderAssociationData, SchemaBuilderColumnData } from '../../helpers/cli/ASTBuilder.js';
+import DreamTransaction from '../DreamTransaction.js';
 import KyselyQueryDriver from './Kysely.js';
 import type { TestDatabaseLockSession } from './Base.js';
 export default class PostgresQueryDriver<DreamInstance extends Dream> extends KyselyQueryDriver<DreamInstance> {
@@ -54,6 +55,45 @@ export default class PostgresQueryDriver<DreamInstance extends Dream> extends Ky
      * `Query#destroy`.
      */
     applyRowLock(kyselyQuery: SelectQueryBuilder<any, any, any>, tableAlias: string): SelectQueryBuilder<any, any, any>;
+    static supportsAdvisoryTransactionLocks: boolean;
+    /**
+     * @internal
+     *
+     * Postgres implementation of the transaction-scoped advisory lock seam.
+     *
+     * Uses the single-`bigint` form `pg_advisory_xact_lock(bigint)`, whose lock
+     * space is distinct from the two-`int4` form the test-database pool claims
+     * with (see {@link openTestDatabaseLockSession}), so an application lock can
+     * never collide with a pool claim.
+     *
+     * Every key is taken in one statement, over `unnest` of the key array: a
+     * function scan yields its rows in array order, so the caller's sorted
+     * acquisition order — the thing that keeps two operations over the same
+     * scopes from deadlocking — is preserved, while a batch that needs one key
+     * per candidate record costs one round trip rather than N.
+     *
+     * The locks are held until the enclosing transaction ends, and are waiting
+     * (no `NOWAIT`): a second transaction asking for the same key blocks at that
+     * key's row until the holder commits or rolls back. Because they are
+     * transaction-scoped there is nothing to release, and re-acquiring a key
+     * within one transaction is a no-op rather than an error.
+     *
+     * The wait is bounded by `lock_timeout`, taken from
+     * {@link DreamApp.sortableScopeLockTimeout} and applied to the acquisition
+     * statement alone: the prior value is read in the same statement that sets
+     * the bound and restored in the next one, so the transaction's row-lock waits
+     * keep whatever the application configured. Postgres cancels the statement
+     * with `55P03` when the bound elapses, and that is translated here into
+     * {@link SortableScopeLockWaitTimedOut} so no Postgres error code escapes the
+     * driver.
+     *
+     * A timeout of `0` means "no bound", which is what `lock_timeout` itself
+     * means by it, and is sent as the bound rather than skipped: an application
+     * whose connection carries a `lock_timeout` of its own would otherwise have
+     * its acquisition cancelled by that bound, which is neither the unbounded
+     * wait `0` asks for nor a cancellation this driver could translate.
+     */
+    static acquireAdvisoryTransactionLocks(txn: DreamTransaction<Dream>, keys: bigint[]): Promise<void>;
     static supportsParallelTestDatabases: boolean;
     /**
      * @internal

package/dist/types/src/dream/internal/softDeleteDream.d.ts

@@ -1,3 +1,9 @@
 import Dream from '../../Dream.js';
 import DreamTransaction from '../DreamTransaction.js';
-export default function softDeleteDream(dream: Dream, txn: DreamTransaction<any>): Promise<void>;
+/**
+ * @internal
+ *
+ * @returns the number of rows soft deleted — zero when the row is already gone,
+ *   and zero when it is already soft deleted
+ */
+export default function softDeleteDream(dream: Dream, txn: DreamTransaction<any>): Promise<number>;

package/dist/types/src/dream-app/index.d.ts

@@ -120,6 +120,22 @@ export default class DreamApp {
     get paginationPageSize(): number;
     private _paginationMaxPageSize;
     get paginationMaxPageSize(): number;
+    /**
+     * How long, in milliseconds, a position-mutating operation on a
+     * `@deco.Sortable` model will wait for another transaction to release the
+     * sort scope it needs before giving up with
+     * `SortableScopeLockWaitTimedOut`. Applied to the lock acquisition statement
+     * alone — the transaction's other lock waits keep whatever `lock_timeout`
+     * the application has configured.
+     *
+     * `0` waits without bound, which is what Postgres's `lock_timeout` means by
+     * it, and holds even on a connection configured with a `lock_timeout` of its
+     * own: the acquisition disables the bound for the duration of the statement.
+     *
+     * Set it with `dreamApp.set('sortableScopeLockTimeout', milliseconds)`.
+     */
+    private _sortableScopeLockTimeout;
+    get sortableScopeLockTimeout(): number;
     private _primaryKeyType;
     get primaryKeyType(): LegacyCompatiblePrimaryKeyType;
     private _projectRoot;
@@ -221,7 +237,7 @@ export default class DreamApp {
     private requireTestDatabaseClaimSupport;
     load<RT extends 'models' | 'serializers'>(resourceType: RT, resourcePath: string, importCb: (path: string) => Promise<any>): Promise<void>;
     plugin(cb: (app: DreamApp) => void | Promise<void>): void;
-    set<ApplyOpt extends DreamAppSetOption>(applyOption: ApplyOpt, options: ApplyOpt extends 'bypassDeprecationChecks' ? boolean : ApplyOpt extends 'db' ? DreamDbCredentialOptions | string : ApplyOpt extends 'encryption' ? DreamAppEncryptionOptions : ApplyOpt extends 'primaryKeyType' ? LegacyCompatiblePrimaryKeyType : ApplyOpt extends 'importExtension' ? GeneratorImportStyle : ApplyOpt extends 'logger' ? DreamLogger : ApplyOpt extends 'projectRoot' ? string : ApplyOpt extends 'inflections' ? () => void | Promise<void> : ApplyOpt extends 'packageManager' ? DreamAppAllowedPackageManagersEnum : ApplyOpt extends 'paths' ? DreamDirectoryPaths : ApplyOpt extends 'parallelTests' ? number : ApplyOpt extends 'unicodeNormalization' ? UnicodeNormalizationForm : ApplyOpt extends 'paginationPageSize' ? number : ApplyOpt extends 'paginationMaxPageSize' ? number : never, secondaryOptions?: ApplyOpt extends 'db' ? DreamDbCredentialOptions : never): void;
+    set<ApplyOpt extends DreamAppSetOption>(applyOption: ApplyOpt, options: ApplyOpt extends 'bypassDeprecationChecks' ? boolean : ApplyOpt extends 'db' ? DreamDbCredentialOptions | string : ApplyOpt extends 'encryption' ? DreamAppEncryptionOptions : ApplyOpt extends 'primaryKeyType' ? LegacyCompatiblePrimaryKeyType : ApplyOpt extends 'importExtension' ? GeneratorImportStyle : ApplyOpt extends 'logger' ? DreamLogger : ApplyOpt extends 'projectRoot' ? string : ApplyOpt extends 'inflections' ? () => void | Promise<void> : ApplyOpt extends 'packageManager' ? DreamAppAllowedPackageManagersEnum : ApplyOpt extends 'paths' ? DreamDirectoryPaths : ApplyOpt extends 'parallelTests' ? number : ApplyOpt extends 'unicodeNormalization' ? UnicodeNormalizationForm : ApplyOpt extends 'paginationPageSize' ? number : ApplyOpt extends 'paginationMaxPageSize' ? number : ApplyOpt extends 'sortableScopeLockTimeout' ? number : never, secondaryOptions?: ApplyOpt extends 'db' ? DreamDbCredentialOptions : never): void;
     on<T extends DreamHookEventType>(hookEventType: T, cb: T extends 'db:log' ? (event: KyselyLogEvent) => void : T extends 'repl:start' ? (context: Context) => void | Promise<void> : never): void;
 }
 export type DreamHookEventType = 'db:log' | 'repl:start';
@@ -234,7 +250,7 @@ export interface DreamAppOpts {
     serializerCasing?: DreamSerializerCasing;
     parallelTests: number | undefined;
 }
-export type DreamAppSetOption = 'bypassDeprecationChecks' | 'db' | 'encryption' | 'inflections' | 'importExtension' | 'logger' | 'paths' | 'primaryKeyType' | 'projectRoot' | 'serializerCasing' | 'parallelTests' | 'unicodeNormalization' | 'paginationPageSize' | 'paginationMaxPageSize' | 'packageManager';
+export type DreamAppSetOption = 'bypassDeprecationChecks' | 'db' | 'encryption' | 'inflections' | 'importExtension' | 'logger' | 'paths' | 'primaryKeyType' | 'projectRoot' | 'serializerCasing' | 'parallelTests' | 'unicodeNormalization' | 'paginationPageSize' | 'paginationMaxPageSize' | 'sortableScopeLockTimeout' | 'packageManager';
 export interface DreamDirectoryPaths {
     models?: string;
     serializers?: string;

package/dist/types/src/encrypt/assertNoEncryptedColumnWrites.d.ts

@@ -0,0 +1,27 @@
+import Dream from '../Dream.js';
+/**
+ * @internal
+ *
+ * Throws when `attributes` names an @Encrypted backing column with anything other
+ * than null. Guards the write paths that never instantiate a model, and so never
+ * reach the throwing setter the Encrypted decorator installs for that column.
+ *
+ * `encryptedAttributes` is class-scoped, but a query rooted at an STI base reaches
+ * every one of its children's rows on the shared table, so `dreamClass` and every STI
+ * class below it are searched for backing columns.
+ *
+ * The search deliberately stops there rather than covering the whole hierarchy. A query
+ * rooted at an STI child matches only that child's rows, and a backing column only a
+ * sibling declares holds nothing meaningful for them: writing plaintext into it corrupts
+ * no ciphertext, because there is none to corrupt. Converting such a row to the sibling
+ * type is what has to clear that column, and it has to clear it whatever this guard did.
+ * Widening the walk to the siblings therefore buys no protection, and this guard runs on
+ * every single-statement update, so keep it narrow.
+ *
+ * Keys are matched in their snakeified form, since Kysely's CamelCasePlugin
+ * resolves both the camelCase and the snake_case spelling of a key to the same
+ * physical column.
+ *
+ * null is permitted: it clears the column, and there is no plaintext to mangle.
+ */
+export default function assertNoEncryptedColumnWrites(dreamClass: typeof Dream, attributes: Record<string, unknown>): void;

package/dist/types/src/errors/SortableBatchRequiresTooManyScopeLocks.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Raised when a batch of a locked `Query#destroy` or `Query#update` on a
+ * sortable model would carry its transaction past the number of advisory
+ * sort-scope locks Dream is willing to hold at once.
+ *
+ * The batched, row-locking query APIs take every advisory scope key the batch
+ * needs before they claim a single row — one key per sort scope the batch's
+ * candidate records occupy, per sortable field the model declares. Advisory
+ * locks live in Postgres's cluster-wide shared lock table, whose size is fixed
+ * at startup (`max_locks_per_transaction` × `max_connections`), and they are
+ * held until the transaction ends. A batch over a table whose sort scope has
+ * very high cardinality can therefore consume a meaningful fraction of a
+ * resource every other connection in the cluster shares, and exhausting it
+ * fails unrelated transactions rather than only this one.
+ *
+ * So the preflight counts first and refuses, before claiming any row. The count
+ * is the whole transaction's: the keys it already holds plus the keys the
+ * refused batch would add, since advisory locks are released only when the
+ * transaction ends. Inside a transaction Dream opens for the batch that is the
+ * batch's own key set and nothing has been locked when this is raised; inside a
+ * transaction you own, it also counts every key the run's earlier batches took,
+ * and those stay held.
+ *
+ * The fix is almost always a smaller `batchSize`: the keys one batch needs are
+ * bounded by how many distinct sort scopes its records span, so halving the
+ * batch size halves the worst case. If the run itself is what accumulates them
+ * — a long multi-batch run inside a transaction you opened — either let Dream
+ * open a transaction per batch (do not pass a transaction of your own) or
+ * commit between runs, which is what releases the locks as it goes.
+ */
+export default class SortableBatchRequiresTooManyScopeLocks extends Error {
+    dreamClassName: string;
+    keyCount: number;
+    maxKeyCount: number;
+    constructor(dreamClassName: string, keyCount: number, maxKeyCount: number);
+    get message(): string;
+}

package/dist/types/src/errors/SortableRequiresAdvisoryTransactionLocks.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Raised when a model declaring sortable fields is used on a query driver that
+ * cannot take transaction-scoped advisory locks.
+ *
+ * Sortable computes position values under a lock on the sort scope, without
+ * which concurrent writers collide on the same position. A driver that cannot
+ * provide that lock fails loudly here rather than racing silently.
+ */
+export default class SortableRequiresAdvisoryTransactionLocks extends Error {
+    private queryDriverClassName;
+    constructor(queryDriverClassName: string);
+    get message(): string;
+}

package/dist/types/src/errors/SortableScopeDidNotStabilize.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Raised when a position-mutating operation cannot settle on the sort scope its
+ * record actually occupies.
+ *
+ * A save, destroy, undestroy or locked batch operation locks the sort scopes it
+ * believes it is touching, then reads the rows to find out which scopes they
+ * physically occupy. When another writer has moved a row in between, the
+ * operation takes the additional scope's lock and reads again. A row that keeps
+ * moving exhausts that bound, and the operation raises rather than compacting a
+ * scope the row has already left.
+ *
+ * This is a retryable condition: retrying the operation is the intended
+ * response. One caveat for saves the caller did not wrap in a transaction: the
+ * model's before-hooks run before the transaction this error aborts, so any
+ * effects those hooks had outside the record's own row — writes to other
+ * tables, enqueued work — are not rolled back, and run again on retry.
+ */
+export default class SortableScopeDidNotStabilize extends Error {
+    dreamClassName: string;
+    rounds: number;
+    constructor(dreamClassName: string, rounds: number);
+    get message(): string;
+}