@rvoh/dream 2.27.0 → 2.28.0

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

@@ -0,0 +1,35 @@
+import Dream from '../../../../Dream.js';
+import { SortableFieldConfig } from '../Sortable.js';
+export interface SortableCache {
+    changingScope: boolean;
+    position: number | undefined;
+    previousPosition: number | undefined;
+    wasNewRecord: boolean;
+}
+/**
+ * @internal
+ *
+ * The sortable preparation phase of a save. Called from `saveDream` after every
+ * consumer before-hook has run — a phase, not a hook among them — so the
+ * decision is made from the final state of the instance: a position or scope
+ * change introduced by a `beforeSave` hook registered after Sortable's gets the
+ * same handling as one made before `save` was called, and a cache is never
+ * carried over from a state an intervening hook has made stale.
+ *
+ * For each sortable field this caches the values the position work needs and
+ * applies the position sentinel, then returns the fields whose position work
+ * this save will perform — the fields that make the save need a transaction of
+ * its own, so that the write and the position write that follows it commit
+ * together under one scope lock.
+ *
+ * - every create on a model with sortable fields performs position work;
+ * - an update performs it only when the save changes the position or one of the
+ *   sortable scope columns.
+ *
+ * A save that skips hooks performs no position work at all, so it needs no
+ * transaction.
+ */
+export default function prepareSortableFieldsForSave(dream: Dream, { alreadyPersisted, skipHooks }: {
+    alreadyPersisted: boolean;
+    skipHooks: boolean;
+}): SortableFieldConfig[];

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

@@ -1,2 +1,34 @@
 import Dream from '../../../../Dream.js';
+/**
+ * @internal
+ *
+ * Renumbers every sort scope of a model so that each one runs 1..n with no gaps.
+ *
+ * Four things make this safe to run against a live table:
+ *
+ * - **A driver that cannot take the scope lock fails before the table is
+ *   read**, rather than succeeding for whichever scopes happen to be contiguous
+ *   and throwing on the first one that is not.
+ * - **The STI scope is stripped**, exactly as every sortable hook strips it. An
+ *   STI hierarchy shares one position space, so renumbering one child's rows in
+ *   isolation would hand them positions its siblings already hold.
+ * - **Groups are identified structurally**, by the scope columns' `[column,
+ *   value]` tuple rather than by joining the values into one string. Joining
+ *   merges scopes whose values differ only in where a delimiter falls, and
+ *   merges a null member with an empty-string one; a merged group is two
+ *   physical sort scopes renumbered as though they were one, and no single lock
+ *   key covers it.
+ * - **Every discovered scope is renumbered under its own scope lock, from a
+ *   read taken inside that lock.** The unlocked pass below only discovers
+ *   *which* sort scopes exist; it decides nothing about their contents, because
+ *   a concurrent create, destroy or raw update between the two reads is
+ *   precisely the case this exists to repair. Whether a scope needs renumbering
+ *   at all is decided under the lock.
+ *
+ * Each scope's transaction is this function's own: `resort` cannot join a
+ * transaction the caller owns, and must not be called from inside one. It would
+ * wait on a connection of its own for a scope lock the caller's transaction may
+ * already hold — a wait no deadlock detector can see, which ends in
+ * `SortableScopeLockWaitTimedOut` rather than in progress.
+ */
 export default function resortAllRecords(dreamClass: typeof Dream, positionField: string, scope?: string | string[]): Promise<void>;

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

@@ -1,20 +1,36 @@
-import { SelectQueryBuilder, UpdateQueryBuilder } from 'kysely';
 import Dream from '../../../../Dream.js';
 import DreamTransaction from '../../../../dream/DreamTransaction.js';
 import Query from '../../../../dream/Query.js';
-import PostgresQueryDriver from '../../../../dream/QueryDriver/Postgres.js';
-import { SortableCache } from '../hooks/beforeSortableSave.js';
-interface SortableCacheWithOptionalTransaction extends SortableCache {
+import { SortableCache } from './prepareSortableFieldsForSave.js';
+import { SortableSnapshot } from './sortableSnapshot.js';
+/**
+ * @internal
+ *
+ * Everything one sortable field's position write needs. The transaction is
+ * required: every path into `setPosition` runs from
+ * `performSortablePositionWork`, which is called by `saveDream` inside the
+ * transaction that holds the scope lock, and a position write that opened a
+ * transaction of its own would block on a key its own caller holds.
+ */
+export interface SortablePositionWrite extends SortableCache {
     dream: Dream;
     positionField: string;
     query: Query<Dream>;
     scope: string | string[] | undefined;
-    txn?: DreamTransaction<any> | undefined;
-}
-export interface SortableCacheWithRequiredTransaction extends SortableCacheWithOptionalTransaction {
     txn: DreamTransaction<any>;
+    /**
+     * The record's physical position and sort scope values, read from the row
+     * under the scope lock before the driver write. Present on the update path;
+     * absent on create, which has no prior row.
+     */
+    snapshot?: SortableSnapshot | undefined;
+    /**
+     * The position the record holds in the scope its position is being computed
+     * over, where the driver write has replaced it on the row with the position
+     * sentinel. Set only for a save that lands in the scope the row already
+     * occupies; on every other path the scope's own rows carry their real
+     * positions, or the record is joining the scope rather than already in it.
+     */
+    positionUnderSentinel?: number | undefined;
 }
-export default function setPosition(obj: SortableCacheWithOptionalTransaction): Promise<void>;
-export declare function applySortableScopesToQuery<QB extends UpdateQueryBuilder<any, any, any, any> | SelectQueryBuilder<any, any, any>>(dream: Dream, kyselyQuery: QB, whereValueCB: (column: string) => any, scope?: string | string[]): QB;
-export declare function getPostgresQueryDriver(connectionName: string): typeof PostgresQueryDriver;
-export {};
+export default function setPosition(obj: SortablePositionWrite): Promise<void>;

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

@@ -0,0 +1,48 @@
+import DreamTransaction from '../../../../dream/DreamTransaction.js';
+/**
+ * @internal
+ *
+ * Stashes rows a locked batch's preflight read under the batch's scope locks,
+ * so that the per-record position work that follows does not read them a second
+ * time. The preflight reads every candidate's position and sort scope columns
+ * to derive the key set; each record's own snapshot read then asks the same
+ * question of the same row, in the same transaction, under the same locks.
+ *
+ * Called once per preflight, with the rows of the pass that converged: an
+ * earlier pass read before some of the locks were held, and a preflight that
+ * raised holds no lock the rest of the transaction can rely on. The rows are
+ * consumed one at a time and the whole entry is dropped by the first position
+ * write of the batch, since a compaction moves rows this holds stale positions
+ * for — so what it saves is the snapshot reads of the records walked before
+ * that first write.
+ *
+ * @param txn - the batch's transaction
+ * @param table - the table the rows came from
+ * @param primaryKey - the column the rows are keyed by
+ * @param rows - the rows read, carrying at least the position and scope columns
+ */
+export declare function cacheSortableRowsReadUnderLock(txn: DreamTransaction<any>, table: string, primaryKey: string, rows: Record<string, unknown>[]): void;
+/**
+ * @internal
+ *
+ * The cached row for one record, removed from the cache as it is handed over.
+ *
+ * Consuming is destructive because the consumer is a position-mutating
+ * operation: it is about to compact or renumber the scope the row sits in, and
+ * a second read of the same cached row would see the position the row had
+ * before that. {@link invalidateSortableRowCache} covers the same hazard for
+ * the *other* records a compaction moves.
+ */
+export declare function takeCachedSortableRow(txn: DreamTransaction<any>, table: string, primaryKeyValue: unknown): Record<string, unknown> | undefined;
+/**
+ * @internal
+ *
+ * Discards everything cached for this transaction. Called for two reasons: a
+ * position write just moved rows the cache cannot identify — a compaction
+ * shifts every row in one sort scope above a position, and the cache holds no
+ * index by scope — and the batch the rows were read for has finished, after
+ * which they describe nothing the rest of a caller-owned transaction should
+ * trust. The records still to be walked read their own rows again, which is
+ * what they did before the cache existed.
+ */
+export declare function invalidateSortableRowCache(txn: DreamTransaction<any>): void;

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

@@ -0,0 +1,30 @@
+import Dream from '../../../../Dream.js';
+/**
+ * @internal
+ *
+ * The scope members of a sortable field paired with the database columns they
+ * resolve to. A member names either the column itself or the BelongsTo
+ * association whose foreign key backs it, and a caller matching incoming
+ * attributes needs both spellings; a member that resolves to no column is
+ * dropped.
+ *
+ * Every sortable path resolves its scope columns through this one function, so
+ * that a lock key, a snapshot read, a group identity and a scope filter can
+ * never disagree about which columns a sort scope is made of.
+ */
+export declare function sortableScopeColumnPairs(dream: Dream, scope: string | string[] | undefined): [string, string][];
+/**
+ * @internal
+ *
+ * The database columns a sortable field's scope resolves to.
+ */
+export default function sortableScopeColumns(dream: Dream, scope: string | string[] | undefined): string[];
+/**
+ * @internal
+ *
+ * The sort scope as `[column, value]` pairs — the shape a lock key is derived
+ * from and a group is identified by. The value for each column comes from the
+ * caller, which decides whether it is reading the in-memory instance or a
+ * snapshot of the row.
+ */
+export declare function sortableScopeValues(dream: Dream, scope: string | string[] | undefined, valueForColumn: (column: string) => unknown): [string, unknown][];

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

@@ -0,0 +1,44 @@
+import Dream from '../../../../Dream.js';
+/**
+ * @internal
+ *
+ * Derives the advisory lock key that makes one sort scope's position
+ * computation exclusive. Every position-mutating path derives it the same way,
+ * since two paths that disagree about the key do not exclude each other.
+ *
+ * The key covers:
+ *
+ * - the **physical database name**, because Postgres advisory locks are scoped
+ *   to the cluster rather than to a database. Without it, two unrelated
+ *   databases in one cluster — including this repo's own parallel test
+ *   databases — would contend on the same key, and that contention shows up
+ *   only as writers of unrelated scopes queueing behind each other.
+ * - the table and the position field, since a model can declare several
+ *   sortable fields, each with its own position space.
+ * - the scope column values, which are what a "sort scope" actually is.
+ *
+ * Values are encoded structurally rather than joined into a string, so a null
+ * member is distinct from an empty string and no combination of delimiters in
+ * one member can be mistaken for a different tuple. They are also canonicalized
+ * against the column's database type (`canonicalScopeValue`), so a writer
+ * holding a pending JavaScript value and a writer holding the value Postgres
+ * hydrated derive one key rather than two.
+ *
+ * **Scope values are assumed non-adversarial.** The hash is FNV-1a, which is
+ * unkeyed: anyone who can choose a scope column's value — where that column
+ * holds user-supplied text rather than a foreign key — can compute a value
+ * whose key equals another scope's, and share that scope's lock with it. A
+ * collision costs contention and never correctness, since a shared lock
+ * over-serializes rather than under-locking, and the bounded wait
+ * (`sortableScopeLockTimeout`) caps what a deliberate one can achieve at
+ * stalls rather than at hangs. A keyed digest would make deliberate collisions
+ * expensive, and is not used: changing the derivation would give old and new
+ * processes different keys for one scope during a rolling deploy, which is the
+ * race this lock exists to eliminate.
+ *
+ * @param dream - the record whose scope is being locked
+ * @param positionField - the sortable position column
+ * @param scopeValues - `[column, value]` pairs for the scope being locked
+ * @returns a 64-bit signed key
+ */
+export default function sortableScopeLockKey(dream: Dream, positionField: string, scopeValues: [string, unknown][]): bigint;

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

@@ -0,0 +1,51 @@
+import Dream from '../../../../Dream.js';
+import { SortableFieldConfig } from '../Sortable.js';
+import { SortableSnapshots } from './sortableSnapshot.js';
+/**
+ * @internal
+ *
+ * The single key for the scope the record currently occupies — the scope its
+ * position is about to be computed within. Used by the position write itself,
+ * where the record already carries its final scope values.
+ */
+export declare function sortableScopeLockKeyForCurrentScope(dream: Dream, positionField: string, scope: string | string[] | undefined): bigint;
+/**
+ * @internal
+ *
+ * Every key a create's position work needs — one per sortable field, derived
+ * from the scope values the row now carries — sorted and deduplicated, so that
+ * a multi-sortable-field create acquires in the same global order as every
+ * other position-mutating operation. Declaration order cannot serve: the keys
+ * hash the runtime scope values, so which field's key sorts first varies from
+ * record to record.
+ */
+export declare function sortableCurrentScopeLockKeys(dream: Dream, configs: SortableFieldConfig[]): bigint[];
+/**
+ * @internal
+ *
+ * Every key a per-record position-mutating operation needs, sorted and
+ * deduplicated. A save that moves a record between sort scopes compacts the
+ * scope it leaves and makes room in the scope it enters, so it needs both keys;
+ * a save within one scope needs one, and so do a destroy and an undestroy, which
+ * write no scope values at all.
+ *
+ * The *new*-scope key comes from the values being written. The *old*-scope key
+ * comes from the database snapshot of the record's physical scope columns when
+ * one is available, and only falls back to the instance's pending changes when
+ * it is not — which is the case exactly once per save, on the first
+ * acquisition, because the snapshot cannot be read until something is locked.
+ * The caller closes that window by re-reading under the lock and calling this
+ * again with the snapshot; see `acquireStabilizedSortableScopeLocks`.
+ *
+ * A pending change is only an *old* scope when it has a previous persisted
+ * value. A record created earlier in this process reports every column as
+ * changed with `was === undefined` (`Dream#changes` compares against the
+ * pre-save state), which is not a scope the row was ever in: reading it as one
+ * would take a second, bogus lock — and, since every such record produces the
+ * same all-null scope tuple, it would be the *same* bogus key for every record
+ * in the table, serializing writers that touch unrelated scopes.
+ *
+ * Either way this must be called *before* the driver write overwrites the
+ * record's scope columns.
+ */
+export declare function sortableSaveLockKeys(dream: Dream, configs: SortableFieldConfig[], snapshots?: SortableSnapshots): bigint[];

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;
     /**
@@ -1651,10 +1683,12 @@ 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`

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