@rvoh/dream 2.27.0 → 2.28.0

package/dist/cjs/src/decorators/field/sortable/helpers/sortableScopeLockKeys.js

@@ -0,0 +1,72 @@
+import sortableScopeLockKey from './sortableScopeLockKey.js';
+import { sortableScopeValues } from './sortableScopeColumns.js';
+import { snapshotScopeValue } 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 function sortableScopeLockKeyForCurrentScope(dream, positionField, scope) {
+    return sortableScopeLockKey(dream, positionField, sortableScopeValues(dream, scope, column => dream[column]));
+}
+/**
+ * @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 function sortableCurrentScopeLockKeys(dream, configs) {
+    return sortedUniqueKeys(configs.map(({ positionField, scope }) => sortableScopeLockKeyForCurrentScope(dream, positionField, scope)));
+}
+/**
+ * @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 function sortableSaveLockKeys(dream, configs, snapshots = new Map()) {
+    const keys = configs.flatMap(({ positionField, scope }) => {
+        const newScopeKey = sortableScopeLockKey(dream, positionField, sortableScopeValues(dream, scope, column => dream[column]));
+        if (!dream.isPersisted)
+            return [newScopeKey];
+        const changes = dream.changes();
+        const snapshot = snapshots.get(positionField);
+        const oldScopeKey = sortableScopeLockKey(dream, positionField, sortableScopeValues(dream, scope, column => snapshotScopeValue(snapshot, column, () => {
+            const previousValue = changes[column]?.was;
+            return previousValue === undefined ? dream[column] : previousValue;
+        })));
+        return [newScopeKey, oldScopeKey];
+    });
+    return sortedUniqueKeys(keys);
+}
+function sortedUniqueKeys(keys) {
+    return [...new Set(keys)].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+}

package/dist/cjs/src/decorators/field/sortable/helpers/sortableSnapshot.js

@@ -0,0 +1,101 @@
+import pascalize from '../../../../helpers/pascalize.js';
+import sortableScopeColumns from './sortableScopeColumns.js';
+import { takeCachedSortableRow } from './sortableRowCache.js';
+/**
+ * @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 async function readSortableSnapshots(dream, txn, configs) {
+    const snapshots = new Map();
+    if (!configs.length)
+        return { rowExists: true, snapshots };
+    const scopeColumnsByPositionField = new Map();
+    const columns = new Set();
+    for (const { positionField, scope } of configs) {
+        columns.add(positionField);
+        const scopeColumns = sortableScopeColumns(dream, scope);
+        scopeColumns.forEach(column => columns.add(column));
+        scopeColumnsByPositionField.set(positionField, scopeColumns);
+    }
+    // A locked batch's preflight already read this row, in this transaction and
+    // under these locks, to derive the batch's key set — asking again would be
+    // the same question of the same row. The cached row is handed over once and
+    // is dropped by every position write in the transaction, so a record an
+    // earlier record's compaction may have moved reads its row again.
+    const cachedRow = takeCachedSortableRow(txn, dream.table, dream.primaryKeyValue());
+    const row = cachedRow && [...columns].every(column => column in cachedRow)
+        ? cachedRow
+        : (await txn.kyselyTransaction
+            .selectFrom(dream.table)
+            .where(dream['_primaryKey'], '=', dream.primaryKeyValue())
+            .select([...columns])
+            .executeTakeFirst());
+    if (row === undefined)
+        return { rowExists: false, snapshots };
+    for (const [positionField, scopeColumns] of scopeColumnsByPositionField) {
+        snapshots.set(positionField, {
+            position: row[positionField] ?? null,
+            scopeValues: new Map(scopeColumns.map(column => [column, row[column] ?? null])),
+        });
+    }
+    return { rowExists: true, snapshots };
+}
+function sortableSnapshotName(positionField) {
+    return `_sortableSnapshotFor${pascalize(positionField)}`;
+}
+/**
+ * @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 function cacheSortableSnapshots(dream, snapshots) {
+    for (const [positionField, snapshot] of snapshots) {
+        ;
+        dream[sortableSnapshotName(positionField)] = snapshot;
+    }
+}
+/**
+ * @internal
+ */
+export function sortableSnapshotFor(dream, positionField) {
+    return dream[sortableSnapshotName(positionField)];
+}
+/**
+ * @internal
+ */
+export function clearSortableSnapshot(dream, positionField) {
+    ;
+    dream[sortableSnapshotName(positionField)] = undefined;
+}
+/**
+ * @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 function snapshotScopeValue(snapshot, column, fallback) {
+    if (snapshot?.scopeValues.has(column))
+        return snapshot.scopeValues.get(column);
+    return fallback();
+}

package/dist/cjs/src/decorators/field/sortable/helpers/stabilizeSortableScopeLocks.js

@@ -0,0 +1,86 @@
+import SortableScopeDidNotStabilize from '../../../../errors/SortableScopeDidNotStabilize.js';
+import acquireSortableScopeLocks from './acquireSortableScopeLocks.js';
+import heldSortableScopeLockKeys from './heldSortableScopeLockKeys.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 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 async function stabilizeSortableScopeLocks(dream, txn, keysForRound) {
+    const heldKeys = heldSortableScopeLockKeys(txn);
+    for (let acquisitions = 0;; acquisitions++) {
+        const keys = await keysForRound(acquisitions);
+        const keysToAcquire = [...keys]
+            .filter(key => !heldKeys.has(key))
+            .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+        // the key set this pass's read implies is the key set already held: nothing
+        // can move out from under the operation until the transaction ends, and the
+        // read taken beside it was taken under those locks. This check follows every
+        // acquisition, the last one included, so no pass's work is discarded unread.
+        //
+        // Round 0 is never allowed to end the loop, however many of its keys the
+        // transaction already holds: it ran before this operation read anything
+        // under them, and the read is what the caller came for. Where the earlier
+        // shape ended the loop unread — a locked batch's per-record work, whose
+        // preflight already took every key the record implies — the pass after it
+        // now reads under those very locks and agrees, at the cost of no statement
+        // at all
+        if (acquisitions > 0 && !keysToAcquire.length)
+            return;
+        if (acquisitions === MAX_SCOPE_STABILIZATION_ROUNDS)
+            throw new SortableScopeDidNotStabilize(dream['sanitizedConstructorName'], MAX_SCOPE_STABILIZATION_ROUNDS);
+        // records what it takes in `heldKeys`, and takes nothing already there
+        await acquireSortableScopeLocks(dream, txn, keysToAcquire);
+    }
+}

package/dist/cjs/src/decorators/field/sortable/helpers/validPosition.js

@@ -1,7 +1,24 @@
-import applySortableScopeToQuery from './applySortableScopeToQuery.js';
-export default async function validPosition({ changingScope, dream, position, positionField, query, scope, wasNewRecord, previousPosition, txn, }) {
+import filterQueryToInstanceScope from './filterQueryToInstanceScope.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 async function validPosition({ changingScope, dream, position, positionField, positionUnderSentinel, query, scope, wasNewRecord, previousPosition, txn, }) {
     const increasingNumberOfItemsToSort = !previousPosition || wasNewRecord || changingScope;
-    const maxPosition = (await applySortableScopeToQuery(query.txn(txn), dream, scope).max(positionField)) +
-        (increasingNumberOfItemsToSort ? 1 : 0);
+    const scopeMax = await filterQueryToInstanceScope(query.txn(txn), dream, scope).max(positionField);
+    // `scopeMax` includes this record's own row, but mid-save that row holds the
+    // sentinel `0` instead of its real position. When the record already had a
+    // position in this scope, the caller passes it as `positionUnderSentinel`,
+    // and it counts toward the scope's true max — so take the larger of the two
+    // before clamping.
+    const maxPosition = Math.max(scopeMax ?? 0, positionUnderSentinel ?? 0) + (increasingNumberOfItemsToSort ? 1 : 0);
     return Math.max(1, Math.min(maxPosition, position === null || position === undefined || position < 1 ? maxPosition : position));
 }

package/dist/cjs/src/decorators/field/sortable/hooks/afterSortableDestroy.js

@@ -1,11 +1,28 @@
 import clearCachedSortableValues from '../helpers/clearCachedSortableValues.js';
 import decrementPositionForScopedRecordsGreaterThanPosition from '../helpers/decrementScopedRecordsGreaterThanPosition.js';
-export default async function afterSortableDestroy({ positionField, dream, query, scope, }) {
-    await decrementPositionForScopedRecordsGreaterThanPosition(dream[positionField], {
-        dream,
-        positionField,
-        scope,
-        query,
-    });
+import { invalidateSortableRowCache } from '../helpers/sortableRowCache.js';
+import { clearSortableSnapshot, sortableSnapshotFor } from '../helpers/sortableSnapshot.js';
+export default async function afterSortableDestroy({ positionField, dream, query, scope, txn, }) {
+    // The row's real position and scope, read by the destroy's preparation phase
+    // (`prepareSortableFieldsForDestroy`) while the row still existed. The
+    // instance's own position is whatever it held when
+    // it was loaded, which is too low as soon as another create or update moved
+    // the record down — and shifting from a position lower than the vacated one
+    // moves rows onto occupied positions rather than closing the gap.
+    const snapshot = sortableSnapshotFor(dream, positionField);
+    const position = snapshot ? snapshot.position : dream[positionField];
+    if (position !== null && position !== undefined) {
+        await decrementPositionForScopedRecordsGreaterThanPosition(position, {
+            dream,
+            positionField,
+            scope,
+            query,
+            snapshot,
+        });
+        // every surviving row above the vacancy just moved, which includes rows a
+        // locked batch's preflight read for the records it has yet to walk
+        invalidateSortableRowCache(txn);
+    }
     clearCachedSortableValues(dream, positionField);
+    clearSortableSnapshot(dream, positionField);
 }

package/dist/cjs/src/decorators/field/sortable/hooks/afterSortableUpdate.js

@@ -1,19 +1,29 @@
 import clearCachedSortableValues from '../helpers/clearCachedSortableValues.js';
 import setPosition from '../helpers/setPosition.js';
 import sortableCacheValuesName from '../helpers/sortableCacheValuesName.js';
+import { clearSortableSnapshot, sortableSnapshotFor } from '../helpers/sortableSnapshot.js';
 export default async function afterUpdateSortable({ positionField, dream, query, txn, scope, }) {
     const cachedValuesName = sortableCacheValuesName(positionField);
     const sortableCache = dream[cachedValuesName];
     if (!sortableCache)
         return;
+    // The range this update compacts starts at the position the record really
+    // held, which the `saveDream` sortable phase read from the row under the
+    // scope lock. The instance's own memory of it is stale whenever another
+    // writer moved the record after it was loaded, and shifting from a stale
+    // position lands rows on occupied ones.
+    const snapshot = sortableSnapshotFor(dream, positionField);
     await setPosition({
         ...sortableCache,
         dream,
         positionField,
         position: sortableCache.changingScope ? undefined : sortableCache.position,
+        previousPosition: snapshot ? (snapshot.position ?? undefined) : sortableCache.previousPosition,
+        snapshot,
         query,
         scope,
         txn,
     });
     clearCachedSortableValues(dream, positionField);
+    clearSortableSnapshot(dream, positionField);
 }

package/dist/cjs/src/dream/Query.js

@@ -1,4 +1,6 @@
 import { SOFT_DELETE_SCOPE_NAME } from '../decorators/class/SoftDelete.js';
+import acquireStabilizedSortableBatchLocks from '../decorators/field/sortable/helpers/acquireStabilizedSortableBatchLocks.js';
+import { invalidateSortableRowCache } from '../decorators/field/sortable/helpers/sortableRowCache.js';
 import DreamApp from '../dream-app/index.js';
 import AssociationDeclaredWithoutAssociatedDreamClass from '../errors/associations/AssociationDeclaredWithoutAssociatedDreamClass.js';
 import CannotCallUndestroyOnANonSoftDeleteModel from '../errors/CannotCallUndestroyOnANonSoftDeleteModel.js';
@@ -1878,9 +1880,11 @@ export default class Query {
      *   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
@@ -2001,8 +2005,38 @@ export default class Query {
      * 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.
-     */
-    async lockedBatches(batchSize, perBatch) {
+     *
+     * 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).
+     */
+    async lockedBatches(batchSize, perBatch, sortableIncomingAttributes) {
         // the driver seam refuses this combination too, but catching it here means
         // failing before any transaction is opened or any row is touched
         if (this.distinctColumn)
@@ -2031,10 +2065,27 @@ export default class Query {
                 const candidateIds = await batchQuery.txn(txn).pluck(this.namespacedPrimaryKey);
                 if (!candidateIds.length)
                     return { attempted: 0, processed: 0, lastId };
+                // On a sortable model, every advisory scope lock this batch will need is
+                // taken here, sorted, before a single row is claimed. Claiming first and
+                // locking per record inside `perBatch` is the lock-order inversion that
+                // deadlocks against an ordinary concurrent writer of the same scope,
+                // which holds the advisory lock while waiting for the row.
+                //
+                // The ordering this establishes is per batch. A multi-batch run inside a
+                // caller-owned transaction keeps batch N-1's row locks while batch N
+                // preflights, and is a documented fallback rather than a guarantee.
+                await acquireStabilizedSortableBatchLocks(this.dreamInstance, txn, candidateIds, sortableIncomingAttributes);
                 const claimed = await this.dbDriverInstance(batchQuery.txn(txn).where({ [primaryKey]: candidateIds })).takeAll({ lock: true });
+                const processed = await perBatch(claimed, txn);
+                // The preflight stashed the rows it read so this batch's per-record
+                // sortable work could consume them instead of re-reading each one. They
+                // describe this batch's candidates as they were before it ran, so they
+                // are worth nothing to whatever the enclosing transaction does next —
+                // and a caller-owned transaction outlives the batch.
+                invalidateSortableRowCache(txn);
                 return {
                     attempted: candidateIds.length,
-                    processed: await perBatch(claimed, txn),
+                    processed,
                     lastId: candidateIds.at(-1),
                 };
             };
@@ -2186,7 +2237,11 @@ export default class Query {
                     // dirty-state-based, and mutations made directly on the record
                     // Dream holds would otherwise ride along with the save
                     (record) => cb(record['clone']())
-                : () => attributesOrCb, { skipHooks }, resolvedBatchSize);
+                : () => attributesOrCb, { skipHooks }, resolvedBatchSize, 
+            // only the attributes form knows what it is going to write before the
+            // claim; the callback form computes it inside the batch, after the row
+            // locks are taken, and is a documented preflight fallback
+            cb ? undefined : attributesOrCb);
         }
         if (!cb && skipHooks)
             return await this.updateWithoutCallingModelHooks(attributesOrCb);
@@ -2243,7 +2298,7 @@ export default class Query {
      * thrown on every join-load query (leftJoinPreload always carries left-join
      * statements).
      */
-    async lockedUpdate(cb, { skipHooks }, batchSize) {
+    async lockedUpdate(cb, { skipHooks }, batchSize, sortableIncomingAttributes) {
         return await this.lockedBatches(batchSize, async (claimed, txn) => {
             let written = 0;
             for (const record of claimed) {
@@ -2258,7 +2313,7 @@ export default class Query {
                 written++;
             }
             return written;
-        });
+        }, sortableIncomingAttributes);
     }
     async updateWithoutCallingModelHooks(attributes) {
         return await this.dbDriverInstance().update(attributes);

package/dist/cjs/src/dream/QueryDriver/Base.js

@@ -193,6 +193,69 @@ export default class QueryDriverBase {
     connectionName) {
         throw new Error('override openTestDatabaseLockSession in child class');
     }
+    /**
+     * @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 = false;
+    /**
+     * @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
+     */
+    // eslint-disable-next-line @typescript-eslint/require-await
+    static async acquireAdvisoryTransactionLocks(
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    txn, 
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    keys) {
+        throw new Error('override acquireAdvisoryTransactionLocks in child class');
+    }
     // eslint-disable-next-line @typescript-eslint/require-await
     static async getColumnData(
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
@@ -507,9 +570,19 @@ export default class QueryDriverBase {
      * @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.
      */
-    // eslint-disable-next-line @typescript-eslint/require-await, @typescript-eslint/no-unused-vars
-    static async destroyDream(dream, txn, reallyDestroy) {
+    // eslint-disable-next-line @typescript-eslint/require-await
+    static async destroyDream(
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    dream, 
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    txn, 
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    reallyDestroy) {
         throw new Error('implement destroyDream in child class');
     }
     static get syncDialect() {

package/dist/cjs/src/dream/QueryDriver/Kysely.js

@@ -265,21 +265,28 @@ export default class KyselyQueryDriver extends QueryDriverBase {
     }
     /**
      * 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 async destroyDream(dream, txn, reallyDestroy) {
+        if (dream['_preventDeletion'])
+            return 0;
         if (shouldSoftDelete(dream, reallyDestroy)) {
-            await softDeleteDream(dream, txn);
+            return await softDeleteDream(dream, txn);
         }
-        else if (!dream['_preventDeletion']) {
-            await txn.kyselyTransaction
+        else {
+            const results = await txn.kyselyTransaction
                 .deleteFrom(dream.table)
                 .where(dream['_primaryKey'], '=', dream.primaryKeyValue())
                 .execute();
+            return Number(results[0]?.numDeletedRows ?? 0);
         }
     }
     /**