@rvoh/dream 2.26.0 → 2.28.0

package/dist/cjs/src/Dream.js

@@ -1787,23 +1787,6 @@ export default class Dream {
     static async pluck(...columnNames) {
         return (await this.query().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 User.order('id').pluckEach('id', (id) => {
-     *   console.log(id)
-     * })
-     * // 1
-     * // 2
-     * // 3
-     * ```
-     *
-     * @param args - a list of fields to pluck, followed by a callback function to call for each set of found fields
-     * @returns void
-     */
     static async pluckEach(...args) {
         return await this.query().pluckEach(...args);
     }
@@ -1820,6 +1803,25 @@ export default class Dream {
      * with no gaps, accounting for the scopes specified in the
      * corresponding Sortable decorator.
      *
+     * Each sort scope is renumbered in its own transaction, under the same
+     * advisory lock every other position-mutating path takes on that scope, from
+     * a read of the scope taken inside that lock — so a concurrent create or
+     * destroy cannot make the renumbering land on positions it never read.
+     *
+     * **Do not call `resort` from inside a transaction you own.** It opens those
+     * transactions itself, on connections of its own, so it can neither join
+     * yours nor roll back with it: its writes commit on their own. Worse, if your
+     * transaction already holds the scope lock for a scope being renumbered — any
+     * position-mutating write to that scope earlier in the transaction takes it —
+     * `resort` waits on that lock from the outside, where no deadlock detector
+     * can see the cycle, until the wait bound expires and it throws
+     * `SortableScopeLockWaitTimedOut`.
+     *
+     * On an STI hierarchy the position space is shared by every class in the
+     * hierarchy, exactly as it is for creates, updates and destroys. Calling
+     * `resort` on a child class therefore renumbers the hierarchy's rows, not
+     * only the receiver's.
+     *
      * ```ts
      * class Post extends ApplicationModel {
      *   @deco.Sortable({ scope: ['user']})
@@ -3759,6 +3761,19 @@ export default class Dream {
      * This is usually used for a soft-delete
      * pattern
      *
+     * The veto is fail-closed, and the record is left
+     * entirely untouched: on a soft-delete model the soft
+     * delete is skipped as well, no `afterDestroy` or
+     * `afterDestroyCommit` hooks run, since the record is
+     * still present, and the destroy returns before the
+     * `dependent: 'destroy'` cascade, so this record's
+     * dependent associations survive too.
+     *
+     * A veto only stops the subtree rooted at the record
+     * that called it. When a record is reached by another
+     * record's cascade, vetoing spares it and its own
+     * dependents; the destroy that reached it carries on.
+     *
      * ```ts
      * class User extends ApplicationModel {
      *   @deco.BeforeDestroy()

package/dist/cjs/src/db/errors.js

@@ -12,6 +12,7 @@ export const FOREIGN_KEY_VIOLATION = 'FOREIGN_KEY_VIOLATION';
 export const INTEGRITY_CONSTRAINT_VIOLATION = 'INTEGRITY_CONSTRAINT_VIOLATION';
 export const INVALID_INPUT_SYNTAX = 'INVALID_INPUT_SYNTAX';
 export const COLUMN_OVERFLOW = 'COLUMN_OVERFLOW';
+export const LOCK_NOT_AVAILABLE = 'LOCK_NOT_AVAILABLE';
 export const NOT_NULL_VIOLATION = 'NOT_NULL_VIOLATION';
 export const RESTRICT_VIOLATION = 'RESTRICT_VIOLATION';
 export const UNIQUE_VIOLATION = 'UNIQUE_VIOLATION';
@@ -26,6 +27,9 @@ export const PG_ERRORS = {
     '23000': INTEGRITY_CONSTRAINT_VIOLATION,
     '23001': RESTRICT_VIOLATION,
     '23503': FOREIGN_KEY_VIOLATION,
+    // a statement Postgres cancelled because its `lock_timeout` elapsed while it
+    // waited for a lock — the bound Dream puts on the sortable scope-lock wait
+    '55P03': LOCK_NOT_AVAILABLE,
 };
 function pgErrorFromCode(code) {
     return PG_ERRORS[code] || null;

package/dist/cjs/src/decorators/field/sortable/Sortable.js

@@ -1,17 +1,37 @@
-import pascalize from '../../../helpers/pascalize.js';
-import { STI_SCOPE_NAME } from '../../class/STI.js';
-import { afterCreateImplementation } from '../lifecycle/AfterCreate.js';
-import { afterCreateCommitImplementation } from '../lifecycle/AfterCreateCommit.js';
-import { afterDestroyImplementation } from '../lifecycle/AfterDestroy.js';
-import { afterDestroyCommitImplementation } from '../lifecycle/AfterDestroyCommit.js';
-import { afterUpdateImplementation } from '../lifecycle/AfterUpdate.js';
-import { afterUpdateCommitImplementation } from '../lifecycle/AfterUpdateCommit.js';
-import { beforeSaveImplementation } from '../lifecycle/BeforeSave.js';
 import scopeArray from './helpers/scopeArray.js';
-import afterSortableCreate from './hooks/afterSortableCreate.js';
-import afterSortableDestroy from './hooks/afterSortableDestroy.js';
-import afterUpdateSortable from './hooks/afterSortableUpdate.js';
-import beforeSortableSave from './hooks/beforeSortableSave.js';
+/**
+ * Marks an integer column as a sortable position: Dream keeps the positions of
+ * every record in a sort scope contiguous, starting at 1, as records are
+ * created, moved, destroyed and undestroyed.
+ *
+ * ```ts
+ * class Post extends ApplicationModel {
+ *   @deco.Sortable({ scope: 'user' })
+ *   public position: number
+ * }
+ *
+ * await post.update({ position: 2 }) // the records at 2 and above shift up
+ * ```
+ *
+ * A position past the end of the scope is clamped to the end, and a position
+ * below 1 — or none at all — lands the record at the end.
+ *
+ * **A save that changes the sort scope ignores a position given alongside it.**
+ * The record lands at the end of the scope it moves into, whatever position the
+ * same `update` supplied:
+ *
+ * ```ts
+ * await post.update({ user: otherUser, position: 1 })
+ * // post is now the last record in otherUser's scope, not the first
+ * ```
+ *
+ * Move it in two saves to place it: `await post.update({ user: otherUser })`,
+ * then `await post.update({ position: 1 })`.
+ *
+ * Sortable requires a query driver that supports advisory transaction locks —
+ * the `PostgresQueryDriver` does — since every position write serializes the
+ * writers of its sort scope on one.
+ */
 export default function Sortable(opts = {}) {
     return function (_, context) {
         const key = context.name;
@@ -27,116 +47,21 @@ export default function Sortable(opts = {}) {
                 // already declared on the base STI class.
                 dreamClass['sortableFields'] = [...dreamClass['sortableFields']];
             }
+            // the decorator registers nothing but this metadata: none of a sortable
+            // field's runtime work runs as hooks. A save's preparation and position
+            // write run as phases in `saveDream` (`prepareSortableFieldsForSave`,
+            // `performSortablePositionWork`), a destroy's lock acquisition, snapshot
+            // read and compaction as phases in `destroyDream`
+            // (`prepareSortableFieldsForDestroy`, `performSortableDestroyWork`), and
+            // an undestroy's restore inline in `undestroyDream` — each seated
+            // relative to the user's hooks by the caller, so no user hook code can
+            // interleave with the position work and every after-hook observes
+            // computed positions and compacted scopes
             ;
             dreamClass['sortableFields'].push({
                 scope: scopeArray(opts.scope),
                 positionField: key,
             });
-            const positionField = key;
-            const beforeSaveMethodName = `_cacheValueFor${pascalize(key)}`;
-            const afterCreateMethodName = `_setNewValueFor${pascalize(key)}AfterCreate`;
-            const afterCreateCommitMethodName = `_setNewValueFor${pascalize(key)}AfterCreateCommit`;
-            const afterUpdateMethodName = `_updateValueFor${pascalize(key)}AfterUpdate`;
-            const afterUpdateCommitMethodName = `_updateValueFor${pascalize(key)}AfteUpdateCommit`;
-            const afterDestroyMethodName = `_setValuesAfterDestructionFor${pascalize(key)}AfterDestroy`;
-            const afterDestroyCommitMethodName = `_setValuesAfterDestructionFor${pascalize(key)}AfterDestroyCommit`;
-            const dreamPrototype = Object.getPrototypeOf(dream);
-            // before saving, we remember the new value for position, but clear it from our
-            // supervised attributes to prevent position from saving
-            dreamPrototype[beforeSaveMethodName] = function () {
-                beforeSortableSave({
-                    dream: this,
-                    positionField,
-                    scope: opts.scope,
-                });
-            };
-            // once saved, we can now safely update position in isolation
-            dreamPrototype[afterUpdateMethodName] = async function (txn) {
-                // if no transaction is provided, leverage update commit hook instead
-                if (!txn)
-                    return;
-                const query = dreamClass.query().removeDefaultScope(STI_SCOPE_NAME).txn(txn);
-                await afterUpdateSortable({
-                    dream: this,
-                    positionField,
-                    query,
-                    txn,
-                    scope: opts.scope,
-                });
-            };
-            dreamPrototype[afterUpdateCommitMethodName] = async function (txn) {
-                // if transaction is provided, leverage update hook instead
-                if (txn)
-                    return;
-                const query = dreamClass.query().removeDefaultScope(STI_SCOPE_NAME);
-                await afterUpdateSortable({
-                    dream: this,
-                    positionField,
-                    query,
-                    scope: opts.scope,
-                });
-            };
-            // after create, we always want to ensure the position is set, so if they provide one,
-            // we need to split existing records on position and update, but otherwise we simply set the new position
-            // to be the length of all existing records + 1
-            dreamPrototype[afterCreateMethodName] = async function (txn) {
-                // if no transaction is provided, leverage create commit hook instead
-                if (!txn)
-                    return;
-                const query = dreamClass.query().removeDefaultScope(STI_SCOPE_NAME).txn(txn);
-                await afterSortableCreate({
-                    dream: this,
-                    positionField,
-                    query,
-                    scope: opts.scope,
-                    txn,
-                });
-            };
-            dreamPrototype[afterCreateCommitMethodName] = async function (txn) {
-                // if transaction is provided, leverage create hook instead
-                if (txn)
-                    return;
-                const query = dreamClass.query().removeDefaultScope(STI_SCOPE_NAME);
-                await afterSortableCreate({
-                    dream: this,
-                    positionField,
-                    query,
-                    scope: opts.scope,
-                });
-            };
-            // after destroy, auto-adjust positions of all related records with a greater position
-            // than this one to maintain incrementing order,
-            dreamPrototype[afterDestroyMethodName] = async function (txn) {
-                // if no transaction is provided, leverage destroy commit hook instead
-                if (!txn)
-                    return;
-                const query = dreamClass.query().removeDefaultScope(STI_SCOPE_NAME).txn(txn);
-                await afterSortableDestroy({
-                    dream: this,
-                    positionField,
-                    query,
-                    scope: opts.scope,
-                });
-            };
-            dreamPrototype[afterDestroyCommitMethodName] = async function (txn) {
-                // if transaction is provided, leverage destroy hook instead
-                if (txn)
-                    return;
-                const query = dreamClass.query().removeDefaultScope(STI_SCOPE_NAME);
-                await afterSortableDestroy({
-                    dream: this,
-                    positionField,
-                    query,
-                    scope: opts.scope,
-                });
-            };
-            beforeSaveImplementation(dream, beforeSaveMethodName);
-            afterCreateImplementation(dream, afterCreateMethodName);
-            afterCreateCommitImplementation(dream, afterCreateCommitMethodName);
-            afterUpdateImplementation(dream, afterUpdateMethodName);
-            afterUpdateCommitImplementation(dream, afterUpdateCommitMethodName);
-            afterDestroyImplementation(dream, afterDestroyMethodName);
-            afterDestroyCommitImplementation(dream, afterDestroyCommitMethodName);
         });
     };
 }

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

@@ -0,0 +1,38 @@
+import Query from '../../../../dream/Query.js';
+import SortableRequiresAdvisoryTransactionLocks from '../../../../errors/SortableRequiresAdvisoryTransactionLocks.js';
+import heldSortableScopeLockKeys from './heldSortableScopeLockKeys.js';
+/**
+ * @internal
+ *
+ * Serializes every writer of a set of sort scopes by taking those scopes'
+ * transaction-scoped advisory locks. They are released when the enclosing
+ * transaction ends, so there is nothing to release here.
+ *
+ * Keys this transaction already holds are dropped rather than re-acquired: the
+ * lock is held to the end of the transaction either way, so the statement would
+ * do nothing but cost a round trip inside the lock window. Whatever is left is
+ * taken in the order given — callers that need more than one sort them first,
+ * so that two operations touching the same pair of scopes cannot deadlock
+ * against each other — and in one statement, on drivers that can express it.
+ *
+ * Waiting for a key another transaction holds is bounded by the driver, which
+ * raises `SortableScopeLockWaitTimedOut` rather than waiting forever; see
+ * `QueryDriverBase.acquireAdvisoryTransactionLocks`.
+ *
+ * @param dream - the record whose connection provides the driver
+ * @param txn - the transaction the locks are scoped to
+ * @param keys - the scope keys to acquire, in acquisition order
+ */
+export default async function acquireSortableScopeLocks(dream, txn, keys) {
+    if (!keys.length)
+        return;
+    const queryDriverClass = Query.dbDriverClass(dream.connectionName || 'default');
+    if (!queryDriverClass.supportsAdvisoryTransactionLocks)
+        throw new SortableRequiresAdvisoryTransactionLocks(queryDriverClass.name);
+    const heldKeys = heldSortableScopeLockKeys(txn);
+    const keysToAcquire = keys.filter(key => !heldKeys.has(key));
+    if (!keysToAcquire.length)
+        return;
+    await queryDriverClass.acquireAdvisoryTransactionLocks(txn, keysToAcquire);
+    keysToAcquire.forEach(key => heldKeys.add(key));
+}

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

@@ -0,0 +1,183 @@
+import Dream from '../../../../Dream.js';
+import SortableBatchRequiresTooManyScopeLocks from '../../../../errors/SortableBatchRequiresTooManyScopeLocks.js';
+import heldSortableScopeLockKeys from './heldSortableScopeLockKeys.js';
+import sortableScopeLockKey from './sortableScopeLockKey.js';
+import { cacheSortableRowsReadUnderLock } from './sortableRowCache.js';
+import { sortableScopeColumnPairs } from './sortableScopeColumns.js';
+import stabilizeSortableScopeLocks from './stabilizeSortableScopeLocks.js';
+/**
+ * The most advisory sort-scope locks a batch preflight will let one transaction
+ * hold.
+ *
+ * Advisory locks are entries in a cluster-wide shared lock table sized at
+ * startup (`max_locks_per_transaction` × `max_connections`, 6400 entries under
+ * the stock settings), and a transaction holds every key it takes until it
+ * ends. `batchSize` is the caller's to choose and nothing bounds the number of
+ * distinct sort scopes a batch's records span, so without a limit a wide enough
+ * batch over a high-cardinality scope can starve every other connection in the
+ * cluster of a resource they all draw on — a failure that lands on unrelated
+ * transactions rather than on the one that caused it.
+ *
+ * The count is **cumulative over the transaction**: each preflight round counts
+ * the keys the transaction already holds together with the keys that round
+ * would add. So the bound holds across the rounds of one stabilization loop
+ * (each of which can discover a different set of scopes), and across the
+ * batches of a multi-batch run inside a caller-owned transaction, where
+ * advisory locks are released only when the caller commits.
+ *
+ * The headroom this leaves: the locked-batch defaults are ten records per batch
+ * (`Query.BATCH_SIZES.LOCKED_DESTROY` / `LOCKED_UPDATE`), so reaching the bound
+ * takes a caller who raises `batchSize` by two orders of magnitude and whose
+ * records each occupy a sort scope of their own — or a long run of such batches
+ * inside one transaction. Two shapes consume the budget faster than one key per
+ * record: a model declaring more than one sortable field needs one key per
+ * field, and the attribute form of `update` needs up to two per record per
+ * field, since the record's current scope and its destination scope are
+ * different keys.
+ *
+ * Only the batch preflight enforces this. A per-record save, destroy or
+ * undestroy takes its keys without counting them, so what they take is counted
+ * by the next preflight in the same transaction but cannot itself raise.
+ */
+export const MAX_SORTABLE_BATCH_SCOPE_LOCKS = 1000;
+/**
+ * @internal
+ *
+ * The operation-level scope-lock preflight for the batched, row-locking query
+ * APIs — `Query#destroy({ lock: true })` and the attribute form of
+ * `Query#update(attributes, { lock: true })`.
+ *
+ * Why it exists: those operations take *row* locks (`takeAll({ lock: true })`)
+ * and then run per-record sortable work that takes *advisory* scope locks. Two
+ * transactions running in that order can each hold what the other is waiting
+ * for. Acquiring every advisory key the batch needs — across every sortable
+ * field and every candidate record — in one sorted pass, before a single row is
+ * claimed, removes the inversion: the advisory locks are always taken first, and
+ * always in the same order.
+ *
+ * The key set cannot simply be read once: `Query.lockedBatches` plucks only
+ * primary keys, so the candidates' scope columns have to be read separately, and
+ * that first read is not protected by any lock. So the read is stabilized the
+ * same way the per-record paths stabilize theirs, through the same
+ * `stabilizeSortableScopeLocks` protocol — acquire on what the unlocked read
+ * implies, re-read under those locks, take any additional key the re-read
+ * reveals — with the same bound, and the same `SortableScopeDidNotStabilize`
+ * when a batch of rows keeps moving between scopes faster than it can be read.
+ *
+ * A model with no sortable fields never reaches the driver seam, so this is
+ * inert — and free — for every other model.
+ *
+ * How many keys the transaction may hold is bounded — see
+ * {@link MAX_SORTABLE_BATCH_SCOPE_LOCKS} — and a batch that would carry it past
+ * the bound is refused before it claims any row. The first round refuses before
+ * anything at all is locked; a later round refuses after that loop's earlier
+ * rounds took their keys, which stay held until the transaction ends like every
+ * advisory lock this branch takes.
+ *
+ * What the preflight can and cannot see: `incomingScopeValue` recognizes an
+ * attribute that names a scope column directly or the BelongsTo association
+ * backing it. A destination scope produced any other way — by a custom setter,
+ * a virtual attribute, or a `beforeSave` hook that moves the record between
+ * scopes during the per-record save — is invisible here, and those shapes are
+ * preflight fallbacks like the callback form of `update` and a multi-batch run
+ * inside a caller-owned transaction: the missing key is taken as the
+ * per-record save reaches it, after this batch's row locks, and the residual
+ * failure is Postgres's `40P01` deadlock error — a visible, retryable failure
+ * rather than a silent wrong ordering.
+ *
+ * @param dreamInstance - a bare instance of the Query's model, used for the
+ *   table, the connection, and the scope column resolution
+ * @param txn - the batch's transaction; the locks live until it ends
+ * @param primaryKeyValues - the candidate records this batch will try to claim
+ * @param incomingAttributes - the attributes the operation will write, when they
+ *   are knowable before the claim (the attribute form of `update`); a scope
+ *   column among them means the batch also needs the destination scope's key
+ */
+export default async function acquireStabilizedSortableBatchLocks(dreamInstance, txn, primaryKeyValues, incomingAttributes) {
+    const configs = (dreamInstance.constructor['sortableFields'] ??
+        []);
+    if (!configs.length || !primaryKeyValues.length)
+        return;
+    const primaryKey = dreamInstance['_primaryKey'];
+    // `[scope member, column]` pairs, so that an incoming attribute naming the
+    // BelongsTo association rather than its foreign key still lines up
+    const scopeColumnsByPositionField = new Map();
+    const columns = new Set([primaryKey]);
+    for (const { positionField, scope } of configs) {
+        const scopeColumns = sortableScopeColumnPairs(dreamInstance, scope);
+        // the position columns are not part of the key derivation; they are read
+        // because this read is the one the per-record work would otherwise repeat,
+        // and a snapshot is a position as well as a sort scope
+        columns.add(positionField);
+        scopeColumns.forEach(([, column]) => columns.add(column));
+        scopeColumnsByPositionField.set(positionField, scopeColumns);
+    }
+    // the live set of keys this transaction holds, which every acquisition adds
+    // to: what the bound is counted against, so that neither a later round of
+    // this loop nor a later batch of a caller-owned transaction can pass the
+    // check a bound's worth at a time
+    const heldKeys = heldSortableScopeLockKeys(txn);
+    // the read of the pass that converged — taken under every lock this preflight
+    // holds — published to the row cache once the loop is through
+    let rowsReadUnderEveryLock = [];
+    // every pass re-reads the candidates: the first read is unprotected, and each
+    // later one is taken under the locks the previous pass acquired
+    await stabilizeSortableScopeLocks(dreamInstance, txn, async () => {
+        const rows = (await txn.kyselyTransaction
+            .selectFrom(dreamInstance.table)
+            .where(primaryKey, 'in', primaryKeyValues)
+            .select([...columns])
+            .execute());
+        const keys = new Set();
+        for (const row of rows) {
+            for (const config of configs) {
+                const scopeColumns = scopeColumnsByPositionField.get(config.positionField);
+                keys.add(sortableScopeLockKey(dreamInstance, config.positionField, scopeColumns.map(([, column]) => [column, row[column] ?? null])));
+                if (incomingAttributes) {
+                    keys.add(sortableScopeLockKey(dreamInstance, config.positionField, scopeColumns.map(([singleScope, column]) => {
+                        const incoming = incomingScopeValue(incomingAttributes, singleScope, column);
+                        return [column, incoming === NOT_WRITTEN ? (row[column] ?? null) : incoming];
+                    })));
+                }
+            }
+        }
+        // counted before this round acquires anything, and counted over everything
+        // the transaction would hold once it had: the keys it already holds plus
+        // the ones this round adds to them
+        let keyCount = heldKeys.size;
+        for (const key of keys)
+            if (!heldKeys.has(key))
+                keyCount++;
+        if (keyCount > MAX_SORTABLE_BATCH_SCOPE_LOCKS)
+            throw new SortableBatchRequiresTooManyScopeLocks(dreamInstance['sanitizedConstructorName'], keyCount, MAX_SORTABLE_BATCH_SCOPE_LOCKS);
+        rowsReadUnderEveryLock = rows;
+        return keys;
+    });
+    // published only now the loop has converged, so that the rows the per-record
+    // snapshots consume are the ones read under every lock the preflight holds —
+    // and so that a preflight which raises publishes nothing. Neither failure
+    // exit aborts the transaction, so a caller that catches one inside a
+    // transaction of its own would otherwise go on to find rows here that no lock
+    // of theirs protects.
+    cacheSortableRowsReadUnderLock(txn, dreamInstance.table, primaryKey, rowsReadUnderEveryLock);
+}
+/**
+ * Distinguishes "this operation does not write that scope column" from "this
+ * operation writes null into it", which are different destination scopes.
+ */
+const NOT_WRITTEN = Symbol('sortable scope column not written by this operation');
+/**
+ * The value a scope column is about to be written with, or {@link NOT_WRITTEN}
+ * when this operation does not touch it. A scope member can be named either by
+ * its column (`{ userId: 3 }`) or by the BelongsTo association the column backs
+ * (`{ user: someUser }`), and both forms reach `update` as attributes.
+ */
+function incomingScopeValue(incomingAttributes, singleScope, column) {
+    if (Object.prototype.hasOwnProperty.call(incomingAttributes, column))
+        return incomingAttributes[column] ?? null;
+    if (Object.prototype.hasOwnProperty.call(incomingAttributes, singleScope)) {
+        const value = incomingAttributes[singleScope];
+        return value instanceof Dream ? value.primaryKeyValue() : (value ?? null);
+    }
+    return NOT_WRITTEN;
+}

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

@@ -0,0 +1,40 @@
+import { sortableSaveLockKeys } from './sortableScopeLockKeys.js';
+import { readSortableSnapshots } from './sortableSnapshot.js';
+import stabilizeSortableScopeLocks from './stabilizeSortableScopeLocks.js';
+/**
+ * @internal
+ *
+ * Takes the scope locks a per-record position-mutating operation needs, and
+ * returns the database snapshot read under them. Every per-record path goes
+ * through this: a position- or scope-changing save (from `saveDream`'s sortable
+ * phase), a destroy (from the sortable destroy phase), and an undestroy (from
+ * `doUndestroyDream`). A destroy and an undestroy have no incoming scope
+ * values, so their instance-derived key set is a single key per sortable field —
+ * the scope the instance believes the row occupies — and the snapshot is what
+ * corrects it.
+ *
+ * The first pass locks the key set the instance implies, since the snapshot
+ * cannot be read until something is locked; every later pass locks what the
+ * snapshot read under those locks reveals. `stabilizeSortableScopeLocks` owns
+ * that protocol, its bound, and its failure — including the guarantee that a
+ * second pass always runs, so the snapshot is read under the locks even when
+ * the transaction already held every key the instance implies (a record being
+ * walked inside a locked batch, whose preflight took the whole batch's keys).
+ *
+ * @param dream - the record whose scope is being locked
+ * @param txn - the transaction the operation's write runs in
+ * @param configs - the sortable fields this operation performs position work for
+ * @returns the snapshot read under the locks, alongside whether the row was
+ *   physically there to read — an empty snapshot map on its own cannot say
+ */
+export default async function acquireStabilizedSortableScopeLocks(dream, txn, configs) {
+    let read = { rowExists: true, snapshots: new Map() };
+    await stabilizeSortableScopeLocks(dream, txn, async (round) => {
+        // round 0 runs before anything is locked, so there is nothing safe to read
+        // yet: the instance's own values are what the first acquisition goes on
+        if (round > 0)
+            read = await readSortableSnapshots(dream, txn, configs);
+        return sortableSaveLockKeys(dream, configs, read.snapshots);
+    });
+    return read;
+}