@rvoh/dream 2.26.0 → 2.28.0

package/dist/esm/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/esm/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;
+}

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

@@ -0,0 +1,194 @@
+import cachedTypeForAttribute from '../../../../helpers/db/cachedTypeForAttribute.js';
+const UTF8 = new TextEncoder();
+/**
+ * @internal
+ *
+ * The canonical text form of one sort-scope value — the thing an advisory lock
+ * key and a resort group identity are actually built from.
+ *
+ * Two writers of the same physical sort scope have to derive the same key, and
+ * they do not always hold the value in the same JavaScript shape. A save that
+ * has not been written yet holds the *pending* value the caller supplied
+ * (`'1.00'`, an uppercase UUID, an object whose keys are in source order),
+ * while a snapshot read, a create's post-INSERT read and `resort`'s table read
+ * hold the value Postgres *hydrated* (`1`, a lowercase UUID, an object whose
+ * keys are in jsonb's own order). Postgres considers those pairs one value;
+ * `typeof`-only normalization considers them two, and two keys do not exclude
+ * each other.
+ *
+ * So canonicalization is keyed on the column's runtime `dbType`, and the
+ * canonical form of each type is **the form the hydrated value already takes**.
+ * That anchoring is what makes this safe to ship without a migration or a
+ * coordinated deploy: no key derived from a database-hydrated value moves, and
+ * the pending-side keys that do move are exactly the ones that disagree with
+ * every hydrated-path writer of the same scope today.
+ *
+ * The classes handled, and what the hydrated value looks like:
+ *
+ * - `uuid` — Postgres renders UUIDs lowercase, so the canonical form is
+ *   lowercase.
+ * - `numeric` / `real` / `double precision` — hydrated through
+ *   `parsePostgresDecimal`, i.e. `parseFloat`, so `'1.00'` and `1` both
+ *   canonicalize to `'1'`.
+ * - `jsonb` — hydrated by `JSON.parse` of jsonb's own output, whose object keys
+ *   are ordered by key length and then bytewise. Objects are re-emitted in that
+ *   order, recursively, so property insertion order stops mattering.
+ * - `boolean` — hydrated as a JavaScript boolean; Postgres's own input literals
+ *   (`'t'`, `'yes'`, `'0'`, …) canonicalize to `'true'`/`'false'`.
+ * - `date` and the four timestamp/time types — hydrated as `CalendarDate`,
+ *   `DateTime`, `ClockTime` or `ClockTimeTz`, whose JSON form is the quoted ISO
+ *   string. Strings are quoted the same way so a pending `'2026-02-07'` and a
+ *   hydrated `CalendarDate` agree.
+ *
+ * Everything else — `bigint` and `character varying`, which is to say the
+ * foreign keys and text columns nearly every sort scope is made of — is left on
+ * the untyped normalization below, unchanged.
+ *
+ * Two residuals are known and accepted rather than fixed:
+ *
+ * - **`citext`**: Postgres stores the case a row was written with while
+ *   comparing case-insensitively, so two rows of one physical scope hydrate to
+ *   values that differ in case and split the key on their own. Lowercasing
+ *   would fix the split but would *move* hydrated keys, which is the one thing
+ *   this design refuses to do.
+ * - **Temporal values that agree on the instant but not on the text**: a zone
+ *   offset or a fractional-second precision that differs from the hydrated
+ *   rendering still yields a different key. Only the string-vs-object quoting
+ *   mismatch is canonicalized.
+ *
+ * Both are over-serialization or a missed exclusion between two *pending*-side
+ * writers, never a corrupt position under a key two writers do share.
+ *
+ * @param dream - the record whose scope column is being canonicalized
+ * @param column - the physical database column
+ * @param value - the pending or hydrated value held for that column
+ * @returns the canonical text form, or `null` for an absent value
+ */
+export default function canonicalScopeValue(dream, column, value) {
+    if (value === null || value === undefined)
+        return null;
+    switch (cachedTypeForAttribute(dream.constructor, column)) {
+        case 'uuid':
+            return canonicalUuid(value);
+        case 'numeric':
+        case 'real':
+        case 'double precision':
+            return canonicalNumeric(value);
+        case 'jsonb':
+            return canonicalJsonb(value);
+        case 'boolean':
+            return canonicalBoolean(value);
+        case 'date':
+        case 'timestamp without time zone':
+        case 'timestamp with time zone':
+        case 'time without time zone':
+        case 'time with time zone':
+            return canonicalTemporal(value);
+        default:
+            return untypedScopeValue(value);
+    }
+}
+/**
+ * @internal
+ *
+ * The type-blind fallback, and the shape every unrecognized `dbType` keeps:
+ * the same foreign key can arrive as a string or a number depending on the path
+ * that loaded it, so values are rendered as text and null is kept distinct from
+ * every string, including the empty one.
+ */
+export function untypedScopeValue(value) {
+    if (value === null || value === undefined)
+        return null;
+    switch (typeof value) {
+        case 'string':
+            return value;
+        case 'number':
+        case 'bigint':
+        case 'boolean':
+            return value.toString();
+        default:
+            return JSON.stringify(value) ?? null;
+    }
+}
+function canonicalUuid(value) {
+    return typeof value === 'string' ? value.toLowerCase() : untypedScopeValue(value);
+}
+function canonicalNumeric(value) {
+    const parsed = typeof value === 'number' ? value : parseFloat(String(value));
+    return Number.isFinite(parsed) ? String(parsed) : untypedScopeValue(value);
+}
+/**
+ * @internal
+ *
+ * Postgres's own boolean input literals, lower-cased and trimmed, which a
+ * pending value may hold while the hydrated value is a JavaScript boolean.
+ * Exported so the spec drives its cases from the sets themselves rather than
+ * from a hand-copied list that can silently drift out of step with them.
+ */
+export const BOOLEAN_TRUE_LITERALS = new Set(['t', 'true', 'y', 'yes', 'on', '1']);
+export const BOOLEAN_FALSE_LITERALS = new Set(['f', 'false', 'n', 'no', 'off', '0']);
+function canonicalBoolean(value) {
+    if (typeof value === 'boolean')
+        return value ? 'true' : 'false';
+    if (typeof value === 'string') {
+        const literal = value.trim().toLowerCase();
+        if (BOOLEAN_TRUE_LITERALS.has(literal))
+            return 'true';
+        if (BOOLEAN_FALSE_LITERALS.has(literal))
+            return 'false';
+    }
+    return untypedScopeValue(value);
+}
+/**
+ * Temporal columns hydrate as `CalendarDate`/`DateTime`/`ClockTime` instances
+ * whose `toJSON` is the ISO string, so JSON-encoding both shapes puts a pending
+ * ISO string and its hydrated counterpart on the same quoted text.
+ */
+function canonicalTemporal(value) {
+    return JSON.stringify(value) ?? null;
+}
+/**
+ * jsonb neither stores nor renders property insertion order: it orders object
+ * keys by length and then bytewise, and a hydrated value therefore always
+ * arrives in that order. Re-emitting in the same order makes a pending object
+ * literal agree with it, and leaves every hydrated value byte-identical.
+ */
+function canonicalJsonb(value) {
+    const parsed = typeof value === 'string' ? parseJson(value) : value;
+    return JSON.stringify(inJsonbKeyOrder(parsed)) ?? null;
+}
+function parseJson(value) {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return value;
+    }
+}
+function inJsonbKeyOrder(value) {
+    if (Array.isArray(value))
+        return value.map(inJsonbKeyOrder);
+    if (value === null || typeof value !== 'object')
+        return value;
+    return Object.keys(value)
+        .sort(compareJsonbKeys)
+        .reduce((acc, key) => {
+        acc[key] = inJsonbKeyOrder(value[key]);
+        return acc;
+    }, {});
+}
+/**
+ * jsonb's own key collation: shorter keys first, ties broken by comparing the
+ * UTF-8 bytes.
+ */
+function compareJsonbKeys(a, b) {
+    const bytesA = UTF8.encode(a);
+    const bytesB = UTF8.encode(b);
+    if (bytesA.length !== bytesB.length)
+        return bytesA.length - bytesB.length;
+    for (let i = 0; i < bytesA.length; i++) {
+        if (bytesA[i] !== bytesB[i])
+            return bytesA[i] - bytesB[i];
+    }
+    return 0;
+}

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

@@ -1,5 +1,23 @@
 import sortableCacheValuesName from './sortableCacheValuesName.js';
+import { clearSortableSnapshot } from './sortableSnapshot.js';
 export default function clearCachedSortableValues(dream, positionField) {
     const cachedValuesName = sortableCacheValuesName(positionField);
     dream[cachedValuesName] = undefined;
 }
+/**
+ * @internal
+ *
+ * Discards both halves of what a save's sortable phase stashes on the
+ * instance: the cached values the position work reads, and the snapshot of the
+ * row it would have computed its shift against. The position work clears them
+ * itself as it consumes them, so this is for the paths where it does not run —
+ * the row was already gone when the snapshot read found it, or the save's
+ * transaction rolled back — leaving a later save of the same instance to read
+ * the row for itself rather than inherit this save's reading of it.
+ */
+export function clearSortableSaveState(dream, configs) {
+    for (const { positionField } of configs) {
+        clearCachedSortableValues(dream, positionField);
+        clearSortableSnapshot(dream, positionField);
+    }
+}

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

@@ -1,7 +1,7 @@
 import ops from '../../../../ops/index.js';
-import getColumnForSortableScope from './getColumnForSortableScope.js';
-import scopeArray from './scopeArray.js';
-export default async function decrementPositionForScopedRecordsGreaterThanPosition(position, { dream, positionField, query, scope, }) {
+import filterQueryToScopeValues from './filterQueryToScopeValues.js';
+import { snapshotScopeValue } from './sortableSnapshot.js';
+export default async function decrementPositionForScopedRecordsGreaterThanPosition(position, { dream, positionField, query, scope, snapshot, }) {
     let kyselyQuery = query
         .whereNot({ [dream['_primaryKey']]: dream.primaryKeyValue() })
         .where({
@@ -13,11 +13,11 @@ export default async function decrementPositionForScopedRecordsGreaterThanPositi
             [positionField]: eb(positionField, '-', 1),
         };
     });
-    for (const singleScope of scopeArray(scope)) {
-        const column = getColumnForSortableScope(dream, singleScope);
-        if (column) {
-            kyselyQuery = kyselyQuery.where(column, '=', dream[column]);
-        }
-    }
+    // A null scope value has to be matched with `is null`: `column = NULL` is
+    // never true, so the compaction would silently shift nothing at all in a
+    // null-valued sort scope. `filterQueryToScopeValues` is the one place that
+    // branch lives, and it is the same filter every other position-mutating path
+    // builds.
+    kyselyQuery = filterQueryToScopeValues(dream, kyselyQuery, column => snapshotScopeValue(snapshot, column, () => dream[column]), scope);
     await kyselyQuery.execute();
 }

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

@@ -0,0 +1,20 @@
+import sortableScopeColumns from './sortableScopeColumns.js';
+/**
+ * @internal
+ *
+ * Narrows a Dream `Query` to one sort scope, **reading the scope values off the
+ * in-memory instance**. That is only the scope the row physically occupies when
+ * the instance is known to agree with the row — inside a transaction that has
+ * just written those values, or on a record read under the scope lock.
+ *
+ * Where the row may have been moved by another writer, the caller wants
+ * `filterQueryToScopeValues` instead, which takes each column's value from the
+ * caller (the snapshot read under the lock) rather than from the instance.
+ */
+export default function filterQueryToInstanceScope(query, dream, scope) {
+    for (const column of sortableScopeColumns(dream, scope)) {
+        const value = dream[column];
+        query = query.where({ [column]: value ?? null });
+    }
+    return query;
+}

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

@@ -0,0 +1,32 @@
+import sortableScopeColumns from './sortableScopeColumns.js';
+/**
+ * @internal
+ *
+ * Narrows a kysely query to one sort scope, taking each scope column's value
+ * **from the caller** rather than from the in-memory instance — the snapshot
+ * read under the scope lock on the paths that compact a scope a record is
+ * leaving, which is not necessarily the scope the instance was loaded from.
+ *
+ * This is also the one place the null branch lives: a null scope value has to
+ * be matched with `is null`, since `column = NULL` is never true and the filter
+ * would silently match nothing at all in a null-valued sort scope.
+ *
+ * The instance-reading sibling is `filterQueryToInstanceScope`.
+ *
+ * @param dream - the record whose class resolves the scope members to columns
+ * @param kyselyQuery - the query to narrow
+ * @param whereValueCB - the value to match each scope column against
+ * @param scope - the sortable field's scope
+ */
+export default function filterQueryToScopeValues(dream, kyselyQuery, whereValueCB, scope) {
+    for (const column of sortableScopeColumns(dream, scope)) {
+        const columnValue = whereValueCB(column);
+        if (columnValue === null) {
+            kyselyQuery = kyselyQuery.where(column, 'is', null);
+        }
+        else {
+            kyselyQuery = kyselyQuery.where(column, '=', columnValue);
+        }
+    }
+    return kyselyQuery;
+}

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

@@ -0,0 +1,34 @@
+const heldKeysByTransaction = new WeakMap();
+/**
+ * @internal
+ *
+ * The sortable scope-lock keys this transaction already holds.
+ *
+ * Advisory transaction locks are released only when the transaction ends, so a
+ * key taken once is held for the rest of it: every later acquisition of that
+ * key is a statement whose entire effect is to observe that the transaction
+ * already has what it is asking for. Tracking them turns those statements into
+ * nothing at all — the per-field acquisition inside the position write, and
+ * every per-record acquisition inside a locked batch whose preflight already
+ * took the batch's whole key set.
+ *
+ * Being the transaction's whole ledger is also what lets the locked-batch
+ * preflight count its bound cumulatively rather than per batch: how many scope
+ * locks one more batch would leave the transaction holding is this set's size
+ * plus whatever of the batch's keys is not already in it.
+ *
+ * Keyed by the transaction object rather than by the connection, which is what
+ * makes it correct rather than merely fast: a nested transaction gets its own
+ * `DreamTransaction` and therefore its own set, so keys taken inside a
+ * subtransaction that rolls back — releasing its locks with it — are never
+ * remembered as held by the transaction that outlives it. The entry is
+ * discarded with the transaction object.
+ */
+export default function heldSortableScopeLockKeys(txn) {
+    const held = heldKeysByTransaction.get(txn);
+    if (held)
+        return held;
+    const newHeld = new Set();
+    heldKeysByTransaction.set(txn, newHeld);
+    return newHeld;
+}

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

@@ -0,0 +1,21 @@
+import { STI_SCOPE_NAME } from '../../../class/STI.js';
+import afterSortableDestroy from '../hooks/afterSortableDestroy.js';
+/**
+ * @internal
+ *
+ * The compaction of a sortable destroy: closes the vacancy each sortable
+ * field's sort scope is left with, computed from the snapshot the preparation
+ * phase (`prepareSortableFieldsForDestroy`) read before the delete. Called
+ * directly from `destroyDream` after the delete and before any user
+ * `afterDestroy` hook — never registered as a hook among them — so every
+ * after-destroy hook observes the compacted scope regardless of where it was
+ * declared, exactly as every after-save hook observes the computed position.
+ */
+export default async function performSortableDestroyWork(dream, txn) {
+    const dreamClass = dream.constructor;
+    const sortableFields = dreamClass['sortableFields'];
+    for (const { positionField, scope } of sortableFields) {
+        const query = dreamClass.query().removeDefaultScope(STI_SCOPE_NAME).txn(txn);
+        await afterSortableDestroy({ dream, positionField, query, scope, txn });
+    }
+}

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

@@ -0,0 +1,36 @@
+import { STI_SCOPE_NAME } from '../../../class/STI.js';
+import afterSortableCreate from '../hooks/afterSortableCreate.js';
+import afterUpdateSortable from '../hooks/afterSortableUpdate.js';
+import acquireSortableScopeLocks from './acquireSortableScopeLocks.js';
+import { sortableCurrentScopeLockKeys } from './sortableScopeLockKeys.js';
+/**
+ * @internal
+ *
+ * The position work of a sortable save: computes each sortable field's real
+ * position under the scope lock and writes it. Called directly from
+ * `saveDream` after the driver write — never registered as an after-hook — so
+ * no user hook code can interleave with it while the scope lock is held, and
+ * on a self-opened save it is the last work before COMMIT releases the lock.
+ */
+export default async function performSortablePositionWork(dream, txn, sortableFieldConfigs, { alreadyPersisted }) {
+    const dreamClass = dream.constructor;
+    // A create acquires its whole advisory key set here — every sortable field,
+    // one sorted pass — before any field's position is computed, so a
+    // multi-field create takes its keys in the same global order as an update or
+    // a destroy and cannot deadlock against them. The per-field acquisition
+    // inside `setPosition` then re-acquires keys this transaction already holds,
+    // which is a no-op. (An update acquired its keys before the driver write, in
+    // `saveDream`.)
+    if (!alreadyPersisted) {
+        await acquireSortableScopeLocks(dream, txn, sortableCurrentScopeLockKeys(dream, sortableFieldConfigs));
+    }
+    for (const { positionField, scope } of sortableFieldConfigs) {
+        const query = dreamClass.query().removeDefaultScope(STI_SCOPE_NAME).txn(txn);
+        if (alreadyPersisted) {
+            await afterUpdateSortable({ dream, positionField, query, txn, scope });
+        }
+        else {
+            await afterSortableCreate({ dream, positionField, query, txn, scope });
+        }
+    }
+}