@rvoh/dream 2.26.0 → 2.28.0

package/dist/esm/src/decorators/field/sortable/helpers/sortableScopeLockKey.js

@@ -0,0 +1,99 @@
+import DreamApp from '../../../../dream-app/index.js';
+import canonicalScopeValue from './canonicalScopeValue.js';
+const FNV_OFFSET_BASIS = 0xcbf29ce484222325n;
+const FNV_PRIME = 0x100000001b3n;
+const UINT64_MASK = 0xffffffffffffffffn;
+const INT64_SIGN_BIT = 0x8000000000000000n;
+const UINT64_MODULUS = 0x10000000000000000n;
+const UTF8 = new TextEncoder();
+/**
+ * The hash of the part of the key that cannot vary for one sortable field —
+ * database, table, position field — so that a path deriving a key per row, per
+ * field, per stabilization round only ever serializes and hashes the scope
+ * values. Keyed by the serialization of those three, so a `DreamApp` whose
+ * database name changes derives a new key rather than reusing a stale one.
+ */
+const invariantPrefixHashes = new Map();
+/**
+ * @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, positionField, scopeValues) {
+    const databaseName = DreamApp.getOrFail().dbName(dream.connectionName || 'default', 'primary');
+    const normalizedScopeValues = [...scopeValues]
+        .sort(([columnA], [columnB]) => (columnA < columnB ? -1 : columnA > columnB ? 1 : 0))
+        .map(([column, value]) => [column, canonicalScopeValue(dream, column, value)]);
+    // the hashed text is exactly
+    // `JSON.stringify([databaseName, table, positionField, normalizedScopeValues])`,
+    // hashed in two halves so the invariant half is hashed once per sortable
+    // field rather than once per row. FNV-1a is a streaming hash, so resuming
+    // from the cached state gives the same key byte for byte
+    return toSignedKey(fnv1a64(JSON.stringify(normalizedScopeValues) + ']', invariantPrefixHash(databaseName, dream.table, positionField)));
+}
+function invariantPrefixHash(databaseName, table, positionField) {
+    // the serialization of the first three members, with the array's closing
+    // bracket replaced by the separator the scope values follow. It is also the
+    // memo key: a JSON array of the three members is unambiguous, where any
+    // joined form would need a delimiter no member could contain
+    const prefix = JSON.stringify([databaseName, table, positionField]).slice(0, -1) + ',';
+    const cached = invariantPrefixHashes.get(prefix);
+    if (cached !== undefined)
+        return cached;
+    const hash = fnv1a64(prefix, FNV_OFFSET_BASIS);
+    invariantPrefixHashes.set(prefix, hash);
+    return hash;
+}
+/**
+ * 64-bit FNV-1a, resumed from a previously hashed prefix.
+ */
+function fnv1a64(value, hash) {
+    for (const byte of UTF8.encode(value)) {
+        hash = ((hash ^ BigInt(byte)) * FNV_PRIME) & UINT64_MASK;
+    }
+    return hash;
+}
+/**
+ * Folds the unsigned hash into the signed range Postgres's
+ * `pg_advisory_xact_lock(bigint)` accepts.
+ */
+function toSignedKey(hash) {
+    return hash >= INT64_SIGN_BIT ? hash - UINT64_MODULUS : hash;
+}

package/dist/esm/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/esm/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/esm/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/esm/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/esm/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/esm/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/esm/src/dream/DreamClassTransactionBuilder.js

@@ -747,24 +747,6 @@ export default class DreamClassTransactionBuilder {
     async pluck(...columnNames) {
         return (await this.queryInstance().pluck(...columnNames));
     }
-    /**
-     * Plucks the specified fields from the given dream class table
-     * in batches, passing each found columns into the provided callback function.
-     *
-     * ```ts
-     * await ApplicationModel.transaction(async txn => {
-     *   await User.txn(txn).order('id').pluckEach('id', (id) => {
-     *     console.log(id)
-     *   })
-     *   // 1
-     *   // 2
-     *   // 3
-     * })
-     * ```
-     *
-     * @param fields - A list of fields to pluck, followed by a callback function to call for each set of found fields
-     * @returns void
-     */
     async pluckEach(...args) {
         await this.queryInstance().pluckEach(...args);
     }

package/dist/esm/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';
@@ -1338,29 +1340,6 @@ export default class Query {
         const vals = await this.dbDriverInstance().pluck(...columnNames);
         return (columnNames.length > 1 ? vals : vals.flat());
     }
-    /**
-     * Plucks the specified column names from the given dream class table
-     * in batches, passing each found columns into the
-     * provided callback function
-     *
-     * ```ts
-     * await User.order('id').pluckEach('id', (id) => {
-     *   console.log(id)
-     * })
-     * // 1
-     * // 2
-     * // 3
-     * ```
-     *
-     * A `limit` or `offset` on the Query cannot compose with the batch windows
-     * — each window replaces the limit with the batch size and the offset with
-     * the running window offset, silently ignoring both — so a limit- or
-     * offset-carrying Query throws at runtime.
-     *
-     * @param args - a list of column names to pluck, followed by a callback function to call for each set of found fields
-     * @returns void
-     * @throws BatchingIncompatibleWithLimitOrOffset if the query carries a `limit` or `offset`
-     */
     async pluckEach(...args) {
         const providedCbIndex = args.findIndex(v => typeof v === 'function');
         const providedCb = args[providedCbIndex];
@@ -1901,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
@@ -2024,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)
@@ -2054,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),
                 };
             };
@@ -2209,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);
@@ -2266,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) {
@@ -2281,7 +2313,7 @@ export default class Query {
                 written++;
             }
             return written;
-        });
+        }, sortableIncomingAttributes);
     }
     async updateWithoutCallingModelHooks(attributes) {
         return await this.dbDriverInstance().update(attributes);